Forge Harness

Critical Rules

• ALWAYS use AskUserQuestion for decisions — never plain text questions
• ALWAYS use the bundled scripts (scripts/create-harness.mjs, scripts/validate-harness.mjs) when working on a local repo — they are deterministic and faster than hand-writing files
• ALWAYS confirm overwrites with the user before passing --force to create-harness.mjs — the script skips existing files by default for a reason
• ALWAYS read ${CLAUDE_PLUGIN_ROOT}/shared/agentic-subsystems.md before scaffolding — the 5 subsystems (Instructions / State / Verification / Scope / Lifecycle) are the design framework
• The script bundles are pure Node built-ins — no npm install needed in the target repo
• Keep the harness MINIMAL on first scaffold — memory persistence, tool safety, multi-agent coordination are opt-ins, not defaults
• Generated files live in the TARGET REPO, not the plugin — ${CLAUDE_PLUGIN_ROOT} is the source; --target <path> is the destination

Step 1 — Confirm Target & Intent

Accept the brain dump from $ARGUMENTS or from the conversation context. Determine:

• Target directory — absolute path to the repo being harnessed. If unclear, use AskUserQuestion to ask.
• Intent — one of:
  • create — scaffold a new harness from scratch
  • audit — score an existing harness across the 5 subsystems and recommend improvements
  • report — produce a shareable HTML assessment

If intent is ambiguous, use AskUserQuestion to ask the user to pick one.

If the target directory already has AGENTS.md or CLAUDE.md, default to audit mode unless the user explicitly asked to create. Surprise overwrites are a --force event and require explicit consent.

Step 2 — Detect Stack & Verify Capabilities

Spawn or invoke deterministic detection via Bash:

node ${CLAUDE_PLUGIN_ROOT}/scripts/create-harness.mjs --target <ABSOLUTE_PATH> --help

(This is a dry-run probe — the --help flag prints capabilities without writing.)

Then run actual detection (no flags = preview mode does not exist; the script writes by default, so we use AskUserQuestion before calling it):

For create intent, before running the script, show the user what will be generated:

The harness scaffolder will write the following to <TARGET>:

• AGENTS.md (or CLAUDE.md if --agent-file is set)
• feature_list.json (5 placeholder features)
• progress.md
• session-handoff.md
• init.sh (with detected verification commands)

Existing files will be skipped unless --force is set.

1. Proceed
2. Use CLAUDE.md instead of AGENTS.md
3. Override package manager (npm, pnpm, yarn, bun)
4. Override verification commands manually
5. Cancel

Step 3 — Create Harness (intent=create)

node ${CLAUDE_PLUGIN_ROOT}/scripts/create-harness.mjs --target <ABSOLUTE_PATH> [--agent-file CLAUDE.md] [--package-manager npm|pnpm|yarn|bun] [--commands "cmd one,cmd two"]

After running, report:

• The detected stack (e.g., typescript-react)
• The verification commands that ended up in init.sh
• Which files were written vs skipped (existing)
• Next steps for the user: replace placeholder features in feature_list.json with real ones; run ./init.sh from the target repo to verify baseline; commit the harness.

If overwriting is required, surface a discrete second prompt:

File <path> already exists. Force overwrite?

1. Yes, overwrite this file
2. No, skip this file
3. Yes, overwrite ALL existing harness files (--force)

Never silently pass --force without explicit user approval.

Step 4 — Audit Harness (intent=audit)

node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-harness.mjs --target <ABSOLUTE_PATH> --json

The script returns a JSON report with:

• overall score (0–100)
• bottleneck (which of the 5 subsystems scored lowest)
• Per-subsystem score (0–5) with individual check results

Present the result to the user. If overall < 70, recommend the first 2–3 changes that would lift the lowest-scoring subsystem. Do NOT claim the bottleneck is the cause of any agent failure without evidence — say "candidate bottleneck" until confirmed by an actual agent session.

Step 5 — Render HTML Report (intent=report)

node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-harness.mjs --target <ABSOLUTE_PATH> --html <TARGET>/harness-assessment.html

After writing the HTML, tell the user the absolute path so they can open it in a browser.

Be clear with the user: this is a structural benchmark, not a behavioral one. It confirms the harness is present and coherent. Real effectiveness still requires before/after agent-session testing on representative tasks.

Step 6 — Recommend Next Steps

For every successful run, end with concrete next-step recommendations the user can copy-paste into their backlog:

• Replace placeholder features in feature_list.json with real project features
• Run ./init.sh to verify the baseline before adding new scope
• Commit the harness with a descriptive message
• If the project will have multi-session work: confirm session-handoff.md is filled in at end of session
• If working with memory persistence: see ${CLAUDE_PLUGIN_ROOT}/shared/references/memory-persistence-pattern.md
• If working with multi-agent coordination: see ${CLAUDE_PLUGIN_ROOT}/shared/references/multi-agent-pattern.md

Step 7 — Retrospective (Optional)

If the run revealed a recurring pattern (e.g., a stack the detector didn't classify correctly, a verification command that's wrong for the user's setup), append a note to ${CLAUDE_PLUGIN_ROOT}/shared/learnings.md with the date and observation. Pattern accumulation drives future generator improvements.

When to Read References

Load only the reference needed for the user's problem:

• Memory across sessions: Memory Persistence
• Reusable workflows as skills: Skill Runtime — see also the sibling forge-skill
• Permissions, tools, concurrency: Tool Registry & Safety
• Context budget and progressive disclosure: Context Engineering
• Delegation and parallel agents: Multi-Agent Coordination
• Hooks, startup, long-running work: Lifecycle & Bootstrap
• Non-obvious failure modes: Gotchas
• 5-subsystem framework: Agentic Subsystems

Deliverable Checklist

For a usable minimal harness, the target project ends with:

• AGENTS.md or CLAUDE.md (Instructions subsystem)
• feature_list.json (State subsystem — feature tracker)
• progress.md (State subsystem — session continuity)
• init.sh (Verification subsystem)
• session-handoff.md for multi-session work (Lifecycle subsystem)
• Documented verification evidence pattern (recorded in progress.md or feature_list.json)

If you cannot create files (e.g., sandbox restrictions), provide exact file contents and the node scripts/create-harness.mjs ... command instead.