Generate a production-ready Claude Code harness for your project. Auto-detects stack (Next.js, Laravel, Spring Boot). Generates CLAUDE.md, settings.json, and safety hooks in one command.

version
2.0.0
GitHub stars
9

Install

/plugin install shipwithai-harness@shipwithai

Run it inside Claude Code after adding the marketplace with /plugin marketplace add ShipWithAI/shipwithai-plugins.

Contents

Discovered from source

Skills 2

Harness Doctor

Diagnostic tool for existing Claude Code harness setups. Detects missing files, misconfigured permissions, broken hook wiring, and stack mismatches. Produces a scored health report with actionable fixes.

When to Use

  • After running harness-setup β€” final validation
  • Harness seems to not be working (Claude ignoring CLAUDE.md or hooks)
  • After moving a project or cloning a repo β€” check hooks are executable
  • Periodic health check

Step 1: Detect Stack (SILENT)

Run same detection as harness-setup Step 0. Same token auto-fill logic.

Show scan summary before proceeding:

πŸ” Harness Doctor β€” Scanning project...

Stack:    Next.js (Next.js 14.2.18)
Detected: CLAUDE.md βœ“  settings.json βœ“  hooks/ βœ“

Step 2: Run Diagnostic Checks

Run all 4 categories unless $ARGUMENTS specifies one. Read references/doctor-checks.md for full check details per category.

CategoryKey checks
MemoryCLAUDE.md exists, < 200 lines, no unfilled {{TOKEN}}, Last verified < 90 days old
Permission.claude/settings.json exists, valid JSON, has deny block, curl/npx not hard-denied
Hooksvalidate-command.py + protect-files.py exist, executable, wired in settings.json
Stackdetected stack matches CLAUDE.md stack line, commands exist in project

Step 3: Health Report

╔══════════════════════════════════════════════════╗
β•‘        πŸ›‘οΈ Harness Doctor β€” Health Report          β•‘
╠══════════════════════════════════════════════════╣
β•‘ Stack:   Next.js                                 β•‘
β•‘ Score:   11/12 checks passed                     β•‘
β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•

Category          Status    Issues
──────────────────────────────────
1. Memory           βœ…       0
2. Permission       ⚠️        1 warning
3. Hooks            ❌       1 critical
4. Stack            βœ…       0

──── CRITICAL ────────────────────

❌ .claude/hooks/validate-command.py not executable
   Fix: chmod +x .claude/hooks/validate-command.py

──── WARNINGS ────────────────────

⚠️  CLAUDE.md Last verified: 2026-01-15 (114 days ago)
   Recommendation: Review and update to reflect current project state

Step 4: Offer to Fix

Found {N} issues ({X} critical, {Y} warnings).

A) Fix all β€” apply all safe fixes automatically
B) Fix critical only
C) Show me the fixes first
D) Skip

Safe auto-fixes (no user confirmation needed):

  • chmod +x on hooks
  • JSON formatting fixes in settings.json

Always ask before:

  • Modifying CLAUDE.md content
  • Changing settings.json deny/allow rules

Harness Setup

Analyze your project and generate a production-ready Claude Code harness. Works for any stack β€” reads your actual code instead of filling templates.

When to Use

  • Project missing a CLAUDE.md, or existing one is generic/outdated
  • Need settings.json with balanced permission rules
  • Want validate-command.py + protect-files.py safety hooks

Step 0: Check for Existing CLAUDE.md

If CLAUDE.md exists and has content:

Ask: "Found existing CLAUDE.md. Overwrite with new harness, or skip?"

  • Skip β†’ stop
  • Overwrite β†’ continue

Step 1: Deep Project Scan (parallel reads)

Read references/analysis-guide.md for extraction instructions. Then run all reads simultaneously.

Read whichever of these exist:

  • Root config files: package.json, pom.xml, pyproject.toml, go.mod, Cargo.toml, composer.json, Gemfile, build.gradle
  • Makefile (if exists)
  • .env.example (if exists)
  • Directory structure: glob ** to depth 2
  • One representative source file (entry point or a typical service/controller)
  • One test file (look in tests/, test/, spec/, src/test/, __tests__/)

After reading, extract answers to:

QuestionSource
StackConfig files + deps (see analysis-guide.md Β§Stack Identification)
Run/build/test/lint commandsscripts in package.json, Makefile targets, pom.xml goals
Directory structureGlob result β€” top 3–5 meaningful dirs
ORM/databaseDeps + schema file location
Env vars needed.env.example or grep process.env./os.getenv( in source
Test framework + locationTest file imports + directory name
Package managerLockfile presence: bun.lockb→bun, pnpm-lock.yaml→pnpm, yarn.lock→yarn, else npm
PortDev script, application.properties:server.port, or stack default

Show summary before asking questions:

πŸ” Scan complete

Stack:     Go (Gin framework)
Commands:  run: go run ./cmd/... | test: go test ./... | lint: golangci-lint run
Structure: cmd/, internal/, pkg/, migrations/
Database:  GORM β€” models in internal/models/
Tests:     Go testing (testify) in *_test.go files
Port:      8080
Env vars:  DATABASE_URL, JWT_SECRET, PORT

Step 2: Ask 2 Questions

Q1 (required): "Describe your project in one sentence."

Q2 (optional): "Any conventions Claude should follow that aren't visible in the code? Leave blank to skip."

Step 3: Generate Harness Files

Write all content from your scan findings. Do not use templates.

3a. CLAUDE.md

Write from scratch using what you found. Include only verified facts:

  • Header: project name (from config or dirname), description (Q1 answer), stack, date
  • Commands: exact commands found β€” never assume defaults
  • Architecture: actual directory names with one-line descriptions
  • Database: ORM name + schema file path (omit if none detected)
  • Environment: env var names from .env.example or source scan (omit if none found)
  • Conventions: Q2 answer (omit entire section if Q2 was left blank)

Hard cap: 200 lines. Zero unfilled placeholders.

3b. .claude/settings.json

  1. Read assets/base-settings.json
  2. Read references/toolchain-rules.md β€” add the rows that match your scan findings
  3. Merge and write to .claude/settings.json

3c. Safety hooks

mkdir -p .claude/hooks

Copy assets/hooks/validate-command.py β†’ .claude/hooks/validate-command.py Copy assets/hooks/protect-files.py β†’ .claude/hooks/protect-files.py

chmod +x .claude/hooks/validate-command.py .claude/hooks/protect-files.py

3d. docs/ARCHITECTURE.md

Write from scan findings (30–50 lines):

  • Stack + key dependency versions detected
  • Directory map with one-line descriptions per dir
  • Entry point(s)
  • Data layer summary

Step 4: Validate and Show Output

grep -c '{{' CLAUDE.md || true   # Must be 0 β€” no unfilled placeholders
wc -l CLAUDE.md                   # Must be ≀ 200
ls -la .claude/hooks/             # Must show -rwxr-xr-x for both .py files

Show:

βœ… Harness generated

Files created:
  CLAUDE.md               ← tailored to your project
  .claude/settings.json   ← customized for your toolchain
  .claude/hooks/validate-command.py
  .claude/hooks/protect-files.py
  docs/ARCHITECTURE.md    ← architecture snapshot

Run /shipwithai-harness:doctor to verify health

Commands 2

Harness Doctor

You are a Claude Code harness diagnostician. Analyze the user's existing harness and produce a health report.

BEFORE ANYTHING ELSE: Read skills/harness-doctor/SKILL.md for the full diagnostic workflow.

Run the full doctor workflow: detect stack β†’ run 4 check categories β†’ produce scored report β†’ offer fixes.

Harness Setup

You are a Claude Code harness engineer. Set up a production-ready harness for the user's project.

BEFORE ANYTHING ELSE: Read skills/harness-setup/SKILL.md for the full detection framework and generation instructions.

Run the full harness-setup workflow: detect stack β†’ ask 2 questions β†’ generate files β†’ validate output.

Sponsors

Details

Marketplace
ShipWithAI/shipwithai-plugins
Source
plugins/harness
Author
ShipWithAI
Category
Productivity

More from ShipWithAI/shipwithai-plugins

All 7