
shipwithai-harness
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@shipwithaiRun it inside Claude Code after adding the marketplace with /plugin marketplace add ShipWithAI/shipwithai-plugins.
Contents
Discovered from sourceSkills 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.
| Category | Key checks |
|---|---|
| Memory | CLAUDE.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 |
| Hooks | validate-command.py + protect-files.py exist, executable, wired in settings.json |
| Stack | detected 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 +xon 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:
| Question | Source |
|---|---|
| Stack | Config files + deps (see analysis-guide.md Β§Stack Identification) |
| Run/build/test/lint commands | scripts in package.json, Makefile targets, pom.xml goals |
| Directory structure | Glob result β top 3β5 meaningful dirs |
| ORM/database | Deps + schema file location |
| Env vars needed | .env.example or grep process.env./os.getenv( in source |
| Test framework + location | Test file imports + directory name |
| Package manager | Lockfile presence: bun.lockbβbun, pnpm-lock.yamlβpnpm, yarn.lockβyarn, else npm |
| Port | Dev 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
- Read
assets/base-settings.json - Read
references/toolchain-rules.mdβ add the rows that match your scan findings - 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.
Hooks 1
Sponsors
Details
- Marketplace
- ShipWithAI/shipwithai-plugins
- Source
- plugins/harness
- Author
- ShipWithAI
- Category
- Productivity