| name | repo-harness-plan |
| description | Interactive planning entrypoint for repo-local agentic development work. Produces an approved plan before implementation and routes to init, scaffold, migrate, upgrade, repair, or check only after the decision is clear. |
| when_to_use | repo-harness-plan, plan repo-local agentic workflow work, design repo-harness change, decide init vs scaffold vs migrate, plan harness change |
repo-harness-plan
Use this command when the user wants a decision-complete plan for repo-harness workflow work.
Protocol
- Confirm the working repo with
pwd or git rev-parse --show-toplevel.
- Run
bun scripts/inspect-project-state.ts --repo <repo> --format text when the target repo has this engine available.
- Read repo-local
AGENTS.md, CLAUDE.md, tasks/todos.md, and .ai/harness/policy.json when present.
- Before recommending implementation, write a workflow inventory: active plan path, expected contract/review/notes files,
tasks/todos.md, .ai/harness/checks/latest.json, .ai/harness/runs/, allowed-path owner, and the plan switching or worktree isolation rule.
- Produce one recommended plan and name the next action command:
repo-harness-init, repo-harness-scaffold, repo-harness-migrate, repo-harness-upgrade, repo-harness-repair, or repo-harness-check.
- When the plan is decision-complete, capture it with
.ai/harness/scripts/capture-plan.sh --slug <slug> --title <title> so the repo has a file-backed plans/plan-*.md artifact.
Failure Modes
- If the inspector cannot classify the repo, keep the plan in Draft and list the missing files.
- If implementation approval is absent, do not run
plan-to-todo.sh.
- If the requested command surface is ambiguous, pick one public command and name why the alternatives are out of scope.
Boundaries
- Does not edit implementation files or run
plan-to-todo.sh by default.
- May save a plan artifact with
.ai/harness/scripts/capture-plan.sh; do not generate contracts, reviews, todos, or worktrees until the user approves implementation.
- Do not optimize for a planning harness by removing approval, review, or contract scope gates. If an automated run stalls on approval, fix the test harness or capture route, not the approval boundary.
- Do not expose
hooks-init, docs-init, or create-project-dirs as public commands; they are internal implementation steps.
