repo-harness: Instructions file for Claude Code

repo-harness AGENTS.md

This repository self-hosts the repo-harness contract; the former repo-harness-skill and project-initializer names have been fully removed and are no longer recognized by any tooling. Claude and Codex should follow the same repo-local workflow surface.

Canonical Workflow Files

• tasks/current.md for the ignored local current-status read model derived from workflow artifacts
• tasks/todos.md for deferred medium/long-term goals, not active execution checklists
• plans/prds/ for upper-layer PRDs; plans/sprints/ for ordered sprint backlogs operated through repo-harness run sprint-backlog; task contracts stay the execution slices
• .archcontext/model/nodes/*.yaml for the capability nodes and longest-prefix context boundaries, selected by .ai/harness/policy.json#context.capability_source
• tasks/workstreams/ for capability long-running workstreams that project durable progress into local contracts
• tasks/lessons.md for correction-derived rules
• docs/researches/ for deep repo knowledge
• tasks/notes/ for task-local implementation decisions, deviations, tradeoffs, and open questions
• plans/ for timestamped plans, with plans/archive/ for history
• .ai/harness/workflow-contract.json for the installed workflow contract manifest
• .ai/harness/policy.json for the machine-readable workflow contract
• .ai/context/context-map.json for progressive context loading
• docs/architecture/index.md for umbrella architecture status, drift requests, snapshots, and diagram links
• docs/reference-configs/agentic-development-flow.md for parent-agent/Waza routing and P1/P2/P3 rules

Operating Rules

• Sync tasks/ whenever substantive repo changes are made.
• Use tasks/notes/<plan-stem>.notes.md only for non-obvious slice decisions, deviations, tradeoffs, and open questions; <plan-stem> is the active plan filename without plan- and .md (for example 20260531-0045-governance-workflow). Do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
• Treat hook execution as typed and user-level: ~/.claude/settings.json and ~/.codex/hooks.json invoke repo-harness-hook, whose route registry selects exactly one in-process handler. .ai/hooks/lib/workflow-state.sh is an operator-helper library, never a host-event dispatcher.
• Keep the umbrella hierarchy explicit: architecture owns stable truth, capability contracts own local agent context, tasks/workstreams/<domain>/<capability>/ owns durable progress, and tasks/todos.md owns only deferred medium/long-term goals with tradeoff and revisit trigger.
• Treat .archcontext/model/nodes/*.yaml as the source of truth for capability prefixes under capability_source: "archcontext"; agent-context-blocks.txt and nested agent files are initialization inputs only, never runtime resolver authority.
• Keep architecture drift handling split: architecture-queue.sh writes architecture requests/events, workstream-sync.sh maintains durable capability workstreams, and context-contract-sync.sh only updates controlled local CLAUDE.md/AGENTS.md architecture blocks.
• Keep assets/workflow-contract.v1.json and .ai/harness/workflow-contract.json in sync.
• Keep CLAUDE.md and AGENTS.md short; put detailed guidance in docs/reference-configs/.
• Treat Codex auto-compact as a fallback only; use .ai/harness/handoff/current.md and .ai/harness/handoff/resume.md for long-task rollover.
• Treat .ai/harness/checks/*.latest.{json,md} and .ai/harness/runs/ as ignored runtime evidence cache; commit durable conclusions in tasks/reviews/, tasks/contracts/, tasks/notes/, or docs/researches/ instead.
• Treat architecture/spec/research docs as the human reading entrypoint. Before closing a workflow, promote durable conclusions into docs/architecture/, docs/researches/, docs/spec.md, or tasks/lessons.md; then archive fulfilled plan/contract/review/notes/todo artifacts so root workflow surfaces represent active work only. When a brain root is configured, a durable conclusion worth reusing across projects may additionally be projected into the vault through an explicit obsidian-memory persist call; the vault layer is optional and never a prerequisite for closing a workflow. .rgignore hides archived workflow artifacts and runtime evidence from default rg searches; use explicit paths or rg -uu for audits.
• Treat _ref/ as an occasional ignored external reference checkout cache, not a commit surface or daily workflow. Agents may read or refresh it for comparison; when it influences a decision, cite the source repo plus commit/tag and path in tasks/notes/ or docs/researches/.
• Treat deploy/ as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files, and env examples; follow .ai/harness/policy.json#operations.deploy_sql for configured SQL roots and naming modes, otherwise keep SQL directly under deploy/sql/ with 4-digit ascending prefixes.
• Treat _ops/ as ignored local operations state for secrets, real env files, provider state, artifacts, logs, and scratch files; do not commit or agent-edit _ops/*.
• Treat contract-level task execution as worktree-first: repo-harness run plan-to-todo --plan <approved-plan> starts repo-harness run contract-worktree start --plan <approved-plan> when policy enables it, and completed blocks finish through Waza /check plus repo-harness run contract-worktree finish.
• Treat the EXECUTION_BOUNDARY anti-extras clause as mandatory exactly once in each delegated runner's final rendered task packet: absent requirements are forbidden design space, not permission to improve, and unrequested extras fail closed. Each runner path names one injection owner and no other surface on that path may carry the clause — the Codex native-child path is owned by SubagentStart.context (contract- and writability-aware; generated personas and the delegation advisor carry none), the standalone contract worker path by its worker prompt, and the MCP path by the codex-goal document. Composed-path tests verify the count.
• After Codex Plan mode, Waza /think, or repo-harness-plan produces a decision-complete work-package plan, capture it with repo-harness run capture-plan --artifact-level work-package --slug <slug> --title <title> so plans/ becomes the file-backed source of truth; if the user has already approved implementation, capture with --status Approved --execute --promotion-reason <merge_boundary|rollback_boundary|verification_boundary|risk_boundary|human_decision_boundary|worktree_boundary> or run repo-harness run plan-to-todo --plan <active-plan>.
• Promote work into a top-level plans/plan-*.md only when Artifact Level: work-package is justified by a merge/PR unit, rollback surface, independent verification boundary, review/acceptance boundary, high-risk surface, or otherwise cannot remain a checklist item in the current active plan or sprint backlog. Inline sprint rows and checklist rows stay in the sprint backlog or active plan ## Task Breakdown; contract rows may expand into plan -> contract -> review -> notes only through the work-package gate.
• If current repo state conflicts with the task, open an isolated codex/<task-slug> worktree, finish there, run Waza /check-style validation, then merge back to main without absorbing unrelated dirty changes.
• Route product discovery and complex/design planning to the parent agent: use geju for pre-contract framing, complete P1/P2/P3 with the parent agent's own capabilities, and freeze the accepted direction into the plan and contract. Route daily small/medium planning, bug hunts, and checks to Waza /think, /hunt, and /check. Route a proactive multi-direction visual/UX choice mid-task to the design-options convention (repo-harness docs show design-options).
• Codex automation profile is runtime-referenced, not vendored: required skills are health, check, and mermaid from ~/.codex/skills.
• Keep durable repo knowledge in docs/researches/, tasks/lessons.md, and the canonical workflow artifacts.
• Treat .ai/harness/brain-manifest.json and repo-harness run sync-brain-docs as explicit operator-invoked export surfaces only; hooks and workflow checks must not read, write, or gate on external brain-vault state.
• Treat Waza as Codex-first: ~/.codex/skills is the Codex runtime source; ~/.agents/skills is skills CLI staging/cache only. The managed skills are think, hunt, check, and health; stage upstream Waza, copy their complete skill directories and shared rules into Codex, and verify with diff/cmp as described in docs/reference-configs/external-tooling.md.
• Use docs/reference-configs/external-tooling.md and bash scripts/check-agent-tooling.sh --host both --check-updates for environment checks; this self-host repo vendors CodeGraph as a dev dependency while generated downstream repos keep the global MCP default unless local policy opts in.
• When changing adoption planner or transaction code, verify repo-harness init --repo . --dry-run and a fixture apply use the same TS operation model.
• Treat repo-local .claude/settings.json and .codex/hooks.json hook adapters as retired legacy config; migration may back them up locally, but they are not product deliverables.