Start here. Every document in this repository is reachable from this page, and every path under docs/ has exactly one owner.
| You want to | Read |
|---|---|
| Understand how the harness works | docs/ARCHITECTURE.md |
| Know why something is built the way it is | docs/decisions/README.md |
| Run a workflow stage | docs/WORKFLOW.md, then the one playbook it names |
| Adopt the harness on an existing project | docs/workflow-harness/migration.md |
| Write or edit a skill or a rule | docs/prompt-engineering-principles.md |
| Know what outside evidence says about documenting a repo for agents | docs/research/ |
| Compare a routing instruction change against the eval suite | docs/evals/README.md |
| See what is being built right now | the one plan under docs/plans/active/ — empty means nothing is in flight |
| See what was built before | docs/decisions/ for durable decisions; completed-plan run logs were pruned and live in git history (git show 3bab3c0:docs/plans/completed/ lists the pre-prune tree) |
| Look up a CLI command, flag, or table | cli/docs/CONTRACT.md |
Three classes, and the class determines who is allowed to edit the file.
cli/docs/embedded/), projected into docs/ by the managed-set installer and hash-tracked under .zharness/base/. Edit the embedded source and cut a release. docs/WORKFLOW.md and the stage playbooks are pure mirrors: the updater always overwrites them with upstream bytes, discarding any local edit with no conflict. docs/PROJECT.md is written only when absent and then belongs to the project; the updater never overwrites it (ADR 0011).docs/README.md, docs/decisions/README.md, and docs/decisions/templates/decision.md; in this repository those three paths were authored by hand before the scaffold existed, so they are listed below as authored.| Path | Class | Notes |
|---|---|---|
docs/WORKFLOW.md |
managed | stage router; names the one playbook to read |
docs/playbooks/ |
managed | 6 stage playbooks and their 6 companions; edit cli/docs/embedded/playbooks/ instead. git is absent by design — it owns no harness entity, so its procedure lives in the skill: the commit flow in skills/workflow/git/SKILL.md, pr/merge in skills/workflow/git/references/workflow.md |
docs/README.md |
authored | this page |
docs/ARCHITECTURE.md |
authored | how the system works |
docs/decisions/ |
authored | numbered ADRs, an index, and templates/decision.md to copy for the next one |
docs/plans/ |
authored | initiative records; active/ is the live plan, completed/ is history. Sessions append by hand per the stage playbooks; nothing generates these files |
docs/prompt-engineering-principles.md |
authored | required reading before editing any SKILL.md or rule |
docs/workflow-harness/ |
authored | legacy-adoption guide |
docs/audit/ |
authored | findings that requirements cite as authority |
docs/evals/ |
authored | routing eval suite (case set, run log, retained evidence) invoked only on request, plus the optional failure ledger; maintainer-owned |
docs/research/ |
authored | external-literature evidence that requirements cite as authority; describes the outside world, not this repository |
docs/PROJECT.md |
authored | identity; scaffold-once in consumer repos |
docs/patterns/ |
authored | how to encode an accepted rule as a native guard |
docs/templates/ |
authored | copy-from templates (not the installer templates/) |
docs/memory/ |
authored | optional session memory files |
An existing path under docs/ that is missing from this table is a defect in this table.
docs/| Path | What it is |
|---|---|
cli/docs/ |
the CLI’s contract reference — authored; cli/docs/embedded/ holds the installer’s managed doc set |
skills/ |
the installable agent skills; each has its own SKILL.md |
rules/ |
source for the global rules installed into ~/.claude/rules/ |
| (legacy) a per-machine derived index | removed from the architecture in v0.15 — archive: v0.15 section of CHANGELOG.md |
.zharness/cache/ |
per-machine scratch — skill caches and local reports; gitignored with /.zharness/ |