/harness init

Initialize this repository with an agent-friendly harness structure.

What this creates: AGENTS.md (map), .harness/ (config + architecture), docs/ (decisions + plans), issues/, agents/reviewer.md (evaluator).

Philosophy: AI analyzes and recommends, human approves and modifies. Zero manual authoring required.

Gotchas

• If .harness/ already exists, stop and ask before overwriting. --force skips this check.
• If AGENTS.md exists and is under the token limit, ask before replacing — the user may have customized it.
• Only generate architecture layers for directories that actually exist in the project.
• reviewer.md must reference only test/lint commands that exist. Don't invent commands.
• Keep AGENTS.md under the token limit in config (default 3000 tokens ≈ 12KB). If the repo is complex, be more aggressive about linking to docs/ instead of inlining.
• Generated files use LF line endings, never CRLF.

Step 1: Check Existing Harness

If .harness/ exists AND $ARGUMENTS does not contain "--force":
  → Show current config, ask: "Harness already initialized. Overwrite? (or use --force)"
  → Wait for approval before continuing

Step 2: Analyze Repository

Read the templates and analysis guide first:

• ${CLAUDE_SKILL_DIR}/references/analysis-guide.md
• ${CLAUDE_SKILL_DIR}/references/scaffolding-templates.md

Scan the repository. Do NOT ask the user — gather this yourself:

What	How
Tech stack	package.json, requirements.txt, go.mod, Cargo.toml, pyproject.toml, Gemfile
Test framework	Look for pytest/vitest/jest/go test/rspec configs or test directories
Linter	.eslintrc*, ruff.toml, .golangci.yml, .rubocop.yml
Existing AGENTS.md	Read if present, count tokens
Existing CLAUDE.md	Read if present
Directory structure	Top-level dirs, src/ structure if present
Git info	Branch strategy (check for main/develop), recent commit patterns

Step 3: Report Findings

Present a concise report:

Repository Analysis:
━━━━━━━━━━━━━━━━━━
Tech stack:      [e.g., React + FastAPI + PostgreSQL]
Test framework:  [e.g., pytest + vitest]
Linter:          [e.g., eslint + ruff]
AGENTS.md:       [exists, ~1200 tokens / does not exist]
.harness/:       [not initialized]

Detected layers: [e.g., types → config → repo → service → ui]

Step 4: Generate Recommendations

Based on analysis, generate all files using the templates from ${CLAUDE_SKILL_DIR}/references/scaffolding-templates.md. Adapt each template to the detected tech stack:

1. AGENTS.md — Map structure. Link to docs/ for details. Stay under token limit.
2. .harness/config.yaml — Default thresholds. Adjust if repo has unusual characteristics.
3. .harness/architecture.yaml — Layer boundaries based on detected directory structure. Only include layers that exist.
4. agents/reviewer.md — Evaluator agent. Reference the actual test/lint commands detected.

Step 5: Present for Approval

Show the user what will be created. For each file, show the full content.

Ask: "Review the above. Modify anything, or approve to create all files."

Wait for explicit approval. Do not create files until the user approves.

Step 6: Create Files

After approval, create all files:

AGENTS.md
.harness/config.yaml
.harness/architecture.yaml
agents/reviewer.md
docs/decisions/.gitkeep
docs/plans/.gitkeep
issues/.gitkeep

Use .gitkeep for empty directories so git tracks them.

Step 7: Verify

After creation, verify:

• AGENTS.md token count is under the limit
• reviewer.md references valid commands
• architecture.yaml layers match actual directories
• All files have LF line endings

Report: "Harness initialized. SessionStart hook will now monitor AGENTS.md size, evaluator presence, and harness staleness."

Step 8: Suggest Next Steps

Next steps:
1. Review AGENTS.md and customize if needed
2. Review agents/reviewer.md — this is your evaluator for Phase 2
3. Create your first issue: add a .md file to issues/
4. The harness will now monitor your repo on each session start