| name | harness-setup |
| description | Build or extend a repository harness. Understands the repo first, then determines what to build, migrate, or create based on what exists. |
| metadata | {"author":"https://github.com/afranken","version":"1.0.0","visibility":"public"} |
Harness Setup
One execution sequence. Work items apply based on what the repo needs — there is no upfront routing decision.
Mode selection
Check for an argument before doing anything else:
| Argument | Mode |
|---|
interactive | Pause after each section for review before proceeding |
one-shot | Generate all sections without pausing (prepend verification warning to each file) |
| (none) | Ask: "Interactive (I pause after each section) or one-shot (generate all at once, with a verification warning)?" |
Carry the chosen mode through all steps — do not ask again.
Step 1: Before/After Probe
Load references/before-after-probe.md and record current agent behavior before making any changes.
Step 2: Understand the Repository
Run the scan for a quick artifact overview (optional but fast):
bash .agents/skills/harness-setup/scripts/scan.sh
Then load and run both prompts in references/discovery.md, followed by the prompt in references/inventory.md. Capture all output before creating any files.
- Discovery answers: what is this repo — language, frameworks, constraints, testing, build system
- Inventory answers: what harness artifacts exist, what is missing, what is in the wrong place
Multi-pass analysis: Run every analysis prompt twice independently — without referencing your first pass on the second run. Resolve disagreements before proceeding.
Step 3: Plan
From the combined discovery and inventory output, determine which work items apply and which sub-path each takes:
| Work item | Applies when | Reference |
|---|
| M0: README scope and accuracy | Always | references/readme.md |
M1: CLAUDE.md shim + .claude/skills/ symlinks | Claude Code is a target (see gate below) — skip entirely otherwise | references/claude.md |
| M2: AGENTS.md + INVARIANTS.md | Missing, mixes concerns, or no INVARIANTS.md | references/agents.md |
| M3: Module-level AGENTS.md | Root AGENTS.md over line budget, or high-risk dirs undocumented | references/agents.md |
| M4: Skills | Always — ask whether any task type warrants a new skill (developer may decline); consolidate from non-canonical locations whenever they exist | references/skills.md |
| M5: Makefile | Missing targets or no Makefile | references/makefile.md |
| M6: docs/ | Any of ARCHITECTURE.md, DECISIONS.md, SETUP.md, TESTING.md, CONTRIBUTING.md missing | references/docs.md |
M1 gate — is Claude Code a target? The CLAUDE.md shim and .claude/skills/ symlinks are Claude-Code-specific compatibility artifacts, not part of the portable harness — Copilot, Cursor, and Codex read AGENTS.md and .agents/skills/ natively and need neither. Decide before running M1:
- A
CLAUDE.md or a .claude/ directory already exists → Claude Code is a target; run M1.
- Neither exists → ask the developer: "Do you use Claude Code in this repo? I'll add a
CLAUDE.md shim and .claude/skills/ symlinks only if so — other tools read AGENTS.md and .agents/skills/ natively and need neither." If they decline, skip M1 entirely (no shim, no symlinks) and record the decision in the plan. Carry the answer through; do not ask again.
Run order: M0 → M2 → M1 → M3 → M4 → M5 → M6
Plan before changes: Write out which work items apply, which sub-path each takes, and in what order. Present for confirmation before making any changes. If your tool supports a planning mode (e.g., Claude Code /model opusplan), use it for Steps 2–3, then switch to execution mode.
Step 4: Execute
Load references/bootstrap.md — shared conventions (identifier-grounding, interaction pattern, execution mode) that apply to every work item.
Work through the plan in order. For each work item:
- Artifact exists with good content → extend only where needed, leave the rest untouched
- Artifact exists in the wrong location → migrate content to canonical location, then delete the original
- Artifact is missing → create from scratch using the reference file
Never delete a file before confirming its content is preserved or no longer needed.
Step 5: Validate
Load references/validation.md and run both prompts. Run the Before/After Probe again.
Step 6: Review
Load references/review-panel.md and run all four reviewers. Each reads fresh — do not carry forward context from previous steps. Surface findings inline; do not write to a file.
