repo-harness: Instructions file for Claude Code

repo-harness

Workflow

• For non-trivial work, follow the global Progressive Due Diligence rule (P1 map, P2 trace, P3 decision) before design decisions or code edits.
• Keep root CLAUDE.md and AGENTS.md as standalone regular files; repeat shared rules in both and keep host-specific guidance separate.
• Read the current request and repo-local agent context, work on a branch, make bounded commits, verify once, then report the PR outcome.
• Read tasks/lessons.md at session start and apply its active lessons. Current repo state and evidence override a lesson.
• Finish the main task first. Fix a small problem found on the way directly. For a large problem, open a GitHub issue before you work on it.
• Ordinary tasks use the PR description: goal, scope, changes, verification, risk and rollback. No mandatory plan/contract/review/notes chain; notes are only for non-obvious decisions.
• Keep four hard boundaries: main publication, deletion, credentials/permissions, and release/production operations.
• Only when the current task explicitly authorizes main publication may a model squash-merge after automated checks pass and GitHub has no outstanding change requests or unresolved review threads; an explicit no-merge instruction always wins. Push/tag still require task authorization; credentials/permissions, other deletion and release/production retain their separate approval boundaries. Record authorized publication, the provider-confirmed merge SHA and parent SHA, git revert <squash-commit>, and the daily report. Do not create rollback tags.
• Create task worktrees only at /tmp/<repo>-wt-<slug> (Windows: os.tmpdir()): use repo-harness run contract-worktree start --plan <plan-file> for plan tasks, or git worktree add with that path. Never create one beside the main checkout (../); the Claude Bash hook denies a target outside that root. Commit or push before a reboot or a tmp cleanup.
• Closeout and sweep remove only merged, clean and unowned worktrees. To keep one, give it an unmerged commit, keep it dirty, or mark or lock it. Details: agentic-development-flow.
• Automatically delete only merged, clean worktrees/branches; ask the user for every other deletion. Credentials/permissions (including confirmation bypass) and release/production operations require user approval.
• Select independent review by the diff's Review by risk tier: none for low, one fresh-context review for medium, gatekeeper plus cross-model review for high; ordinary steps record diagnostics without approval loops.
• When you delegate, investigate first, then split work by write ownership. Give each parallel writer its own worktree from a clean source. Implementation sub-agents edit only their scope. They may run scoped typecheck and affected tests in their own worktree. They commit early in their own worktree and return their check results. In a shared checkout they do not commit; the parent commits. Evidence roles run the named check that is their task and do not commit. The parent agent owns task management, conflict resolution, build and post-merge integration verification, including typecheck and affected tests. After integration, the parent removes each sub-agent worktree and branch whose commits are in the task branch and whose checkout is clean. It also removes the intermediate build output and temporary files that the work created. Other deletion still needs the user.
• Model division and cross-model dispatch/review follow Herdr Dispatch.
• GitHub operations (PRs, reviews, merges, labels, releases, comments) go only through the gh/git CLI or the GitHub API. Never use simulated browser clicks on github.com: the account can be banned.
• Changing implementation and test assertions together does not raise the review tier. Check for tests bent to fit a bug within the tier's existing review; at Low, include this check in self-review. Do not add a separate test-review gate. Reuse recorded acceptance as defined in Review by risk.
• .archcontext/model/ owns architecture boundaries; read docs/architecture/ on demand and update only real responsibility changes. Architecture diagnostics do not block work or author nested agent instructions.
• When a branch changes a capability's responsibility, entrypoints, relations or flows, follow repo-harness-architecture (assets/skill-commands/repo-harness-architecture/references/worker.md). Handle architecture debt in the model and human prose. The archctx rolling writer publishes generated regions and the projection manifest; do not apply and commit them in a feature PR.
• Preserve agents/fleet/, release checklists and downstream assets/templates. .ai/harness/workflow-contract.json is the opt-in marker. assets/workflow-contract.v1.json is the contract.
• _ops/ is ignored private operations state: never commit or agent-edit it. _ref/ is an ignored reference cache; cite influential revisions. Follow deploy SQL policy, otherwise use ascending 4-digit files under deploy/sql/.