AGENTS.md — Agent Control Panel

Humans steer, agents execute. Read this fully at session start.

Permissions

You own the full repo. You may create, modify, and delete any file — code, scripts, linters, tests, docs, configs, instructions (including this file). Build deterministic tools for everything checkable mechanically. If it can be a linter rule or test — make it one.

Autonomy

Unsure → medium. Tiers defined in policies/risk-policy.json.

Task Loop

1. Boot worktree — python scripts/harness/worktree_boot.py <task-name>
2. Validate — make smoke. Stop if fails.
3. Load context — check progress.txt if resuming. Load docs from Reference Table.
4. Research — for medium/high risk: launch subagent in researcher role (facts only, no opinions). Output → docs/exec-plans/active/*-research.md.
5. Implement — small steps. make check after each change.
6. Doc drift — check policies/risk-policy.json → docsDriftRules. Update matching docs.
7. Pre-PR — make review. Fix all failures.
8. Agent review — for medium/high risk: launch subagent in reviewer role (fresh context, no shared assumptions).
9. Review loop — respond to feedback until approved.
10. Merge + teardown — merge PR, remove worktree.
11. Session end — update progress.txt.

Available Tools

DO NOT USE

• rm -rf on directories → use git clean or targeted removal
• Direct DB queries in prod → use Repo layer
• curl to external APIs → use Providers layer ApiClient
• git push --force to main → regular push or --force-with-lease
• pip install in global env → use venv
• Bare print() in prod code → use logging (Golden Principle #13)

Core Rules

• Layer imports flow downward only. Cross-cutting via Providers only → ARCHITECTURE.md, policies/architecture.yaml
• Validate at boundaries. No YOLO-parsing inside layers.
• Reuse existing utilities. No duplicates.
• No secrets in repo. All knowledge lives in-repo.
• If a doc contradicts code — fix the doc, same commit.
• Detailed structured logging everywhere — see Golden Principle #13.
• Write deterministic checks for everything verifiable. Reduce judgment, increase automation.

Reference Table

Subagent Roles

Launch subagents by role name. If .claude/agents/harness/<role>.md exists, it will be used. Otherwise Claude creates a universal agent with that role — both work fine.

Failure Ledger

When an agent breaks something, fix the harness, not the agent. Add entries: rule:, context:, fix:, enforcement:. Prefer linter/test over documentation. Rewrite "should" as "must".

Self-Improvement

• Update this file, docs, and scripts as needed. Your convenience is priority.
• On failure → add ledger entry + update docs. If automatable → write a linter/test instead.