specagent

# example-repo documentation

> Index for agents: one line per document, or per folder index that lists the documents of its folder one line each (`decisions/README.md`, `runbooks/README.md`, `references/README.md`, `exec-plans/active/README.md`, `exec-plans/done/README.md`, `../.claude/ecc/README.md`). The details live behind the links. `harness docs-check` fails when a document under docs/ is listed neither here nor in a folder index linked from here (`architecture/documentation.md`).

## Start here
- [Architecture](../ARCHITECTURE.md): the layers and one run end to end, each with a Mermaid diagram; the pipelines; where humans enter; checking it yourself
- [Why it is built this way](WHY.md): every rule a reader may question, its reason and the decision or measurement behind it
- [How it works, step by step](how-it-works.md): one run of the pipeline skill from the request to the merge, each step with the file it writes
- [The files of a run](files-of-a-run.md): the record files of one run, who writes each and what a human reads there
- [What each role session may touch](what-a-role-may-touch.md): a role session's sandbox, what its Bash may write and reach, what is denied to it, its two guards and the request lines the manager answers
- [The end of a run](the-end-of-a-run.md): the judge's verdict, the gate, the merge and the push, the score and the measurement page, the decisions into the vault, the collector
- [The diagrams as text](assets/src/README.md): the Mermaid text of four of the README's pictures (the run loop, the roles, the knowledge layer, a session's life), beside the archify specs they are drawn from
- [A subagent vs a SpecAgent role session](comparison.md): the scope, 15 properties with their evidence, what a role session can do and a subagent cannot, the measured numbers
- [Time and money](economy.md): how the system saves time and money, what quality costs, the runs of 2026-10-30 that measured it, the cache in dollars (2026-10-31)
- [Harness architecture](architecture/harness.md): manager, role types, runs, gates, the two caches
- [Memory map](architecture/memory.md): working, episodic, semantic and procedural stores; what Claude writes itself
- [Memory policy](architecture/memory-policy.md): what each store may remember, what never, deletion and export
- [Knowledge layer](architecture/knowledge.md): context, wiki, graph and docs; retrieval order; what is not installed
- [Documentation layers](architecture/documentation.md): the four layers, the layered indexes, plans in parts and the .summary.md summaries
- [Connections between chats](architecture/connections.md): every mechanism by which sessions exchange work, and its file
- [Architecture index](architecture/index.md): diagrams and per-package notes
- [Harness module map](architecture/harness-modules.md): one row per module of packages/harness/src/harness/ and what it owns
- [What settings and hooks enforce](architecture/harness-enforcement.md): the rules settings and hooks hold whatever a session is told

## Roles
- [Manager specification](roles/MANAGER.md): what the manager receives, launches, records, asks and never does; section 14: the assignment every stage gets before it starts
- [Human involvement](roles/HUMAN.md): approval points, unattended rules, answering escalations
- [Run directory layout](roles/RUNS.md): where run state lives (beside the repository) and what each file is
- [Stage table](roles/stages.yaml): stage → role type → mode → gate → approval
- [Stage maps](generated/maps/default.md): one Mermaid flowchart per stage table, generated by `harness map`; GitHub and Obsidian draw it
- [Role types catalog](generated/role-types.md): generated from .claude/agents/*.md
- [reader](roles/types/reader.md): contract
- [planner](roles/types/planner.md): contract
- [writer](roles/types/writer.md): contract
- [verifier](roles/types/verifier.md): contract
- [critic](roles/types/critic.md): contract
- [judge](roles/types/judge.md): contract
- [manager](roles/types/manager.md): contract pointer
- [researcher](roles/types/researcher.md): contract
- [story-writer](roles/types/story-writer.md): contract
- [spec-writer](roles/types/spec-writer.md): contract
- [test-verifier](roles/types/test-verifier.md): contract
- [validator](roles/types/validator.md): contract
- [advisor](roles/types/advisor.md): contract
- [comparator](roles/types/comparator.md): contract
- [synthesizer](roles/types/synthesizer.md): contract
- [quarantine-reader](roles/types/quarantine-reader.md): contract
- [classifier](roles/types/classifier.md): contract
- [analyst](roles/types/analyst.md): contract
- [librarian](roles/types/librarian.md): contract
- [Role map](roles/ROLE-MAP.md): every role named in the sources and what it is here
- [Access table](roles/need-to-know.yaml): what each role type may receive and read
- [Extensions](roles/EXTENSIONS.md): plugins, skills, MCP servers, tools, other agents: what stays fixed, how one is compared, admitted and updated
- [Extension register](roles/extensions.yaml): form, source, version and accepted components of every extension
- [Stage patterns](roles/PATTERNS.md): orchestration patterns as stage tables; pipelines under roles/pipelines/
- [Instruction changelog](roles/CHANGELOG.md): versions of the instruction set (roles/VERSION)
- [plan-fixer](roles/types/plan-fixer.md): contract
- [translator](roles/types/translator.md): contract
- [Role catalogue](roles/catalogue.md): every agent file, contract, brief, skill and pinned ECC text in bytes and tokens, and the bounds
- [Manager in chat](roles/manager-chat.md): the pipeline skill's main session as the manager: no sandbox and four guards, duties by phase, its own measures, recovery, the lessons page

## Loops
- [Loop layer](loops/README.md): goal, rubric, exit rule, hard stops, state file, triggers, catalog of loops

## Design
- [Design docs index](design-docs/index.md): every design document with its status
- [Core beliefs](design-docs/core-beliefs.md): principles that do not change per project
- [Pipeline fold](design-docs/pipeline-fold.md): fewer hand-overs in the SpecAgent pipeline, measured (draft)

## Decisions
- [Decisions](decisions/README.md): every architecture decision record, one line each, and the ADR template

## Plans
- [Tech debt tracker](exec-plans/tech-debt-tracker.md): known debt with owner and priority
- [Active plans](exec-plans/active/README.md): one folder per plan in progress (`00-index.md` and task files, checked by plan-lint) and the plan-mode drafts
- [Finished plans](exec-plans/done/README.md): the plans of merged runs, a folder each, kept as history and not checked by plan-lint
- [Run loop spec](../specs/002-run-loop/spec.md): what the loops inside a run and the attack stage are for, the requirements and how they are measured

## Quality
- [Quality score](quality/QUALITY_SCORE.md): score per component and what lowers it
- [Reliability](quality/RELIABILITY.md): retries, watchdog, resume, what happens on a crash
- [Security](quality/SECURITY.md): threat model, OWASP ASI mapping, allowed domains
- [Observability](quality/OBSERVABILITY.md): OpenTelemetry setup, metrics, spans, budgets
- [Learning loop](quality/LEARNING.md): from run evidence to a reviewed change; versions; skill review
- [Context budget](quality/CONTEXT_BUDGET.md): what loads into a session, the limits and how they are checked
- [Limits](quality/LIMITS.md): usage limits and API errors: who waits, what poll prints, recovery
- [Provenance](quality/PROVENANCE.md): commit trailers and the way from a commit to its run and session
- [Hazards](quality/HAZARDS.md): classes of input and timing a critic and a verifier try on every plan and change.

## Operations
- [Runbooks](runbooks/README.md): how a human is told, first look
- [Stuck run](runbooks/stuck-run.md): poll action, cause, what to do
- [Worktree conflict](runbooks/worktree-conflict.md): merging shard branches
- [Usage limit](runbooks/usage-limit.md): waiting, recovery, when a human acts
- [Template](template/PROJECTS.md): creating a project from this repository and receiving updates
- [Vault form](../templates/vault/README.md): the private vault every user gets from ops/new-vault.py, seeded with the template's global rules (a lesson with its proof, or an order), and the public commons
- [Template migrations](template/MIGRATIONS.md): steps per template version

## Optional
- [References](references/README.md): llms.txt files of external dependencies
- [ECC texts](../.claude/ecc/README.md): every ECC text of the template in one place, a line each; read before a brief for a role with a domain