harness-init

/harness-init: self-adapting project bootstrap

Generate this repository's navigation harness by scanning it and emitting four artifacts that follow a documented pattern. Run autonomously: infer everything you can, write the files, and record any assumption you had to make in the profile so the user can correct it. Ask the user only if a decision is genuinely blocking and cannot be inferred (rare).

For a large or multi-package repo, fan out: use Explore or parallel agents to map areas in parallel, then synthesize. The main loop owns the file writes.

What you produce

1. CLAUDE.md (repo root) plus the root router index.
2. .claude/repo-index/<area>.md one deep index per area (read on demand, not auto-loaded).
3. .claude/meta/navigation.md the on-demand reference layer (includes an orchestration map).
4. .claude/harness/profile.md the project profile (repo slug, tracker, verify commands, stack flags).
5. .claude/memory/ a project memory scaffold (one starter fact plus a MEMORY.md index).

Optional with --emit codex: a root AGENTS.md mirroring the same model for Codex and Cursor.

Wrap generated content between <!-- harness:start --> and <!-- harness:end --> markers so a later --refresh replaces only the managed block and leaves any hand-written prose intact. If a target file already exists without markers, back it up to <name>.bak.<timestamp> before writing.

Phase 1: Detect (do not write yet)

Run a fast, read-only scan. Prefer Bash one-liners and Glob over reading whole files.

• Repo identity: git remote get-url origin (derive owner/repo), git rev-parse --show-toplevel.
• Default branch: git symbolic-ref --quiet refs/remotes/origin/HEAD (strip origin/); fall back to main then master if unresolved.
• Monorepo vs single: look for multiple sub-projects each with their own manifest (package.json, go.mod, pyproject.toml, Cargo.toml, pom.xml, build.gradle, *.csproj, Gemfile). One area per manifest dir; otherwise treat the root as a single area.
• Stack per area: infer from the manifest plus lockfile:
  • Node: package.json (+ yarn.lock -> yarn, pnpm-lock.yaml -> pnpm, package-lock.json -> npm, bun.lockb -> bun). Read the scripts block for lint/test/build.
  • Go: go.mod (+ a Makefile: read targets for lint, test, build, sqlc).
  • Python: pyproject.toml (+ uv.lock -> uv, poetry.lock -> poetry); detect ruff/pytest/mypy.
  • Rust Cargo.toml; Ruby Gemfile; Java/Kotlin pom.xml/build.gradle; .NET *.csproj.
• Verify commands (the most important output): resolve concrete LINT_CMD, UNIT_TEST_CMD, BUILD_CMD, and E2E_TEST_CMD per area from the scripts/targets above. Quote them exactly as a user would type them (e.g. yarn lint, make test, uv run pytest, go build ./...).
• Docs and rules: find AGENTS.md, CLAUDE.md, README*, CONTRIBUTING*, docs/**, and any spec/KB dirs. Note per-area AGENTS.md as authoritative.
• Setup and environment quirks: check for .env.example/.env.sample, .envrc, .tool-versions/.nvmrc, docker-compose*.yml, a .devcontainer, and a README Setup/Prerequisites/Getting-started section. Route real signals to the profile (Phase 2) and the Phase 6 memory fact; do not add a new root CLAUDE.md section for these.
• Deny zones: standard ignores plus anything large/generated you actually see (node_modules, .next, dist, build, out, target, cdk.out, .git, .venv, __pycache__, *.egg-info, vendor, generated sqlc/codegen dirs, test-report/snapshot dirs).
• Tracker prefix: infer from branch and commit history (git log --oneline -50, git branch -a): a recurring [A-Z]{2,}-\d+ token is the prefix (e.g. PROJ-, JIRA-, OPS-). If none is found, leave TICKET_PREFIX empty and note that /pr and /ticket should fall back to GitHub issue refs.
• Routing triggers: for each area, identify the dirs that own the common intents (entrypoints, HTTP handlers/routes, data layer, shared libs, UI components, config, tests). These become Section 2.