Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Repository Agent Harness

This page is a routing layer, not a new policy source. It points agents and reviewers to the smallest authoritative context needed for a task. Detailed rules stay in their owning files so this map can remain short.

State Layers

StateAuthorityUse
Repository entrypointsAGENTS.md and CLAUDE.mdMandatory worktree, lifecycle, and validation policy.
Live milestone and workThe loopyard selected_milestone project setting, task records, dependencies, conflict domains, and dispatch locksSelect work and detect concurrent ownership. Do not copy this changing state into a tracked active-work ledger.
Current designCurrent Design Authority, owning architecture docs, schemas, and implementationDecide what is current. A proposal is rationale or future design unless the authority map says otherwise.
Source layoutRepository MapLocate code, manifests, generated outputs, and subsystem documentation.
Documentation discoverySUMMARY.md, Topics Index, proposal/backlog indexes, and document front matterFind only the records relevant to the selected task.
Documentation policydocs/AGENTS.md and Documentation WorkflowApply reader-facing, metadata, index, and generated-asset rules to documentation changes.
Checks and proofsWorkflow Gates Registry, the Makefile, and task acceptance criteriaSelect path-mandatory gates, then add behavior- and hazard-specific proofs.
Review and handoffREVIEW.md and the session handoff templateGround independent review and preserve a resumable checkpoint when a slice cannot finish.
HistoryGit history and ChangelogExplain what landed without turning startup context into a work log.
Operator-local factsThe current operator environment and its deliberately local recordsReverify host, network, credential, and provider facts at use time; do not publish them as repository truth.

Start a Task

  1. Read the repository policy entrypoints. Query the loopyard selected_milestone, then inspect the selected task in full, including its source link, dependencies, validation, write scope, and conflict domains.

  2. Check live task locks and git worktrees before claiming shared paths. Live ownership belongs in loopyard and git, not in a checked-in table.

  3. Follow the design-authority and repository maps to the owning code and documents. Load proposal, backlog, and research material on demand rather than treating all documentation as startup context.

  4. Make tracked changes in the dedicated task worktree required by AGENTS.md.

  5. Derive the named gates made mandatory by changed paths:

    {
  git diff --no-renames --name-only "$(git merge-base HEAD main)"
  git ls-files --others --exclude-standard
} | sort -u | python3 tools/workflow_gates.py for-paths --stdin

    This result is a lower bound. It does not infer task acceptance criteria, slice class, trust-boundary hazards, generated-output refreshes, or the focused QEMU proof for changed behavior. Add those gates from the task and the registry.

  6. Run the applicable gates, obtain independent review where required, merge through local main, and record the landed commits in loopyard.

If the available loopyard client cannot expose the selected project setting, treat that as a tooling gap. Do not infer the milestone from a roadmap or a stale task description.

Avoid Duplicate Authorities

  • Do not add a hand-maintained run-target inventory. Named checks and their applicability live in docs/workflow/gates.toml; concrete Make targets live in the Makefile.
  • Do not add a checked-in active-work registry. Derive it from loopyard tasks, conflict domains, dispatch locks, and git worktree list.
  • Do not add a second agent wiki that paraphrases architecture. Improve SUMMARY.md, topics/front matter, the repository map, and the design- authority map instead.
  • Do not use chat transcripts as project memory. Durable project decisions belong in the owning design, proposal, backlog, schema, or task record; ephemeral progress belongs in loopyard and git.

Maintaining the Harness

Prefer a machine-readable extension to an existing authority over another prose checklist. When routing changes, update this page and the owning source in the same branch. make workflow-check budgets the aggregate mandatory AGENTS.md + CLAUDE.md entrypoint context and separately caps this map so reference material remains progressively disclosed through the owning documents.

The design rationale and remaining work are recorded in capOS Repository Harness Engineering. The external grounding is summarized in Hosted Agent Harnesses.