the-loop git:20260912.2726e25A

Immutable. This exact content is served forever at /api/v1/blob/7db09a49e8b29784.

---
name: the-loop
description: The operating model for delivering product work items end-to-end with an agent harness. Use whenever working a ticket/issue under the-loop — to write the spec chain (requirements/design/testing-plan/tasks), execute the task DAG, verify against the testing plan, self/critic-review, escalate, present evidence, and record decisions and learnings under the project's PDLC rules and tooling.
---

# the-loop

"the-loop" is an opinionated product-development-lifecycle (PDLC) harness, shipped as a
plugin for Claude Code and Cursor. Once a work item's spec chain (requirements → design
→ testing plan → tasks) is approved, the harness executes it end-to-end with MINIMAL or
NO human intervention, escalating only when a decision/opinion is genuinely required.

> **Read the relevant reference file before acting** — they carry the full detail so the
> essence is not lost:
> - `reference/workflow.md` — the loop, phases, TDD, reviews, risk tiers, DAG, resumability.
> - `reference/context.md` — context-window management: clearing vs compaction, the checkpoint-then-reset protocol, per-harness mechanics.
> - `reference/onboarding.md` — the guided, schema-driven config onboarding `/init` runs (groups, ask levels, sensible-defaults precedence).
> - `reference/instructions.md` — user-provided custom instruction docs (`customInstructions`): when to read them, precedence, what they can and cannot override.
> - `reference/design-artifacts.md` — UI/UX design artifacts (Figma / HTML prototypes) in the design phase and the designer iteration loop.
> - `reference/reviewing.md` — the self/critic review procedure the review counts drive.
> - `reference/security.md` — the security lens on every phase gate: threat-model-lite, security design, the security-review gate, human sign-off tiers.
> - `reference/tooling.md` — repo management, per-language tooling matrix, hooks, CI parity.
> - `reference/testing.md` — the testing plan and the verification node (test-type matrix, verification environment, evidence and redaction), Gherkin scenario docstrings on integration tests, the queryable scenario view, OpenAPI/GraphQL contract conventions.
> - `reference/minimalism.md` — generation-time decision ladder to counter code bloat.
> - `reference/token-economy.md` — token/cost levers (model choice, thinking effort, verbosity, disclosure, sub-agents, telemetry); guidance only, never configured, never at the expense of rigor.
> - `reference/collaboration.md` — collaborators/roles, paper trail, **the self-comment loop-prevention marker (every reply MUST carry it)**, conflict log, notifications, MCP.
> - `reference/observability.md` — dev==runtime logging, levels, browser logging.
> - `reference/automation.md` — distribution, the CLI, webhooks, predictability, learnings lifecycle.
>
> One rule lives in a **sibling skill** rather than a reference file, because it applies
> outside a work item too: **`the-loop:writing`** (`skills/writing/`) — how every artifact
> a human reads is written.

## The artifact chain (optional brainstorm → spec → testing plan, Kiro-style)

Every work item is a chain of artifacts, each **derived from and iterated after** the one
before it. An artifact with a human gate is refined with feedback **at that gate** until
the gate **locks** it (`status: approved`) — and the gate is the *only* locker
(issue-281): when it classifies an authorized approval it writes the status and the
approver into the front matter itself. The session never sets `status: approved` and
never requests an approval of its own — one gate, one human reply. An artifact **without**
a gate (`brainstorm.md`, `tasks.md`) advances on shape alone, with no human stop. Specs
live in `docs/specs/<id>/`:

0. **`brainstorm.md`** *(optional, the root artifact)* — a free-form scratchpad to explore
   a fuzzy idea before committing to requirements: problem, options, open questions,
   working hypothesis. Created by `/the-loop:brainstorm`; converted to requirements once
   its author says it has converged — it has no approval gate, so it is never
   `status: approved` (issue-281). Phase: `brainstorming`. Skip it when the work is
   already clear.
1. **`requirements.md`** (or **`bugfix.md`** for bugs) — user stories + EARS acceptance
   criteria (`WHEN <event> THEN the system SHALL <response>`). Phase: `requirements-definition`.
   Both names clear the same gate, and **exactly one of them may be present** — two would
   leave the gate with no defined source of truth, so it blocks (decision-045). Whichever
   name it carries, the artifact needs the same `## Requirements` and
   `## Security considerations` sections; both bundled templates provide them.
2. **`design.md`** — architecture, components/interfaces, data models, error handling,
   testing strategy. Phase: `design`. For a **user-facing** work item the design phase also
   tracks **UI/UX design artifacts** (Figma links / self-contained HTML prototypes under
   `docs/specs/<id>/design/`), iterated-until-locked with the designer
   (`reference/design-artifacts.md`).
3. **`testing-plan.md`** — how this work item will be **proved**: a matrix of testing
   types (each either in scope, or `n/a` *with a reason*), the verification environment,
   the evidence to capture, and the activities checklist. Phase: `test-planning`.
   Derived from `design.md` and **reviewed together with it** — one human gate
   (`design-approval`) approves **and locks** the pair, so the plan gets human review
   without a stop of its own. It is authored here and **completed at the
   `verification` node** — one artifact, written once as a plan and once as a record.
   See `reference/testing.md`.
4. **`tasks.md`** — a **DAG** of small, verifiable tasks referencing requirements; each
   task's `_Test:_` names a row of the testing plan. Phase: `tasks-breakdown`. Derived
   mechanically from the two artifacts the human just approved, so it has **no approval
   gate and needs no human sign-off** (issue-281) — it advances on shape alone.

The work item's **phase** is tracked on the ticket via a label (`loop:<phase>` — a fixed
vocabulary, issue-352) and mirrored in the execution log (`brainstorming` is optional):

```
not-started → brainstorming → requirements-definition → design → test-planning
            → tasks-breakdown → implementation → verification → needs-review → complete
```

This sequence is **defined by the shipped process graph**
(`cli/the_loop/graph/pdlc-work-item-loop.yaml` — the **outer loop**, walked in the
repository the ticket was created in; each PR delivering a work item walks its own
`pdlc-pr-loop` in its own session — one per contributing repository — and the
outer `implementation` node waits for those inner loops to finish); the prose
here renders it, never redefines it (issue-148). A third shipped graph,
`pdlc-contribution-loop` (issue-185), is walked instead of the outer loop when
the-loop is **invited into an existing, in-progress work item as a
contributor** (`the-loop contribute`): it cannot start without an authorized
human's **goal and success criteria**, plans in one `contribution.md` instead
of the four-file spec chain, and completes only when every stated criterion is
met — see `reference/workflow.md` § The contribution loop. A fourth,
`pdlc-adhoc-loop` (issue-225), is the smallest of them: a **tactical task that
runs no PDLC process at all** (`the-loop do`) — `work → review → complete`, no
spec chain, no phase selection, no artifact gates, no review chain, finished
when the requester says so. See `reference/workflow.md` § The ad-hoc loop. A
fifth, `pdlc-review-loop` (issue-279), makes the-loop the **reviewer of a pull
request rather than its author** (`the-loop review`, binding to the PR itself):
no brief, no review — an authorized reviewer's questions/angles/validations are
frozen first — then review rounds and follow-ups on the thread until the
reviewer says done, with **no code changed**. See `reference/workflow.md`
§ The review loop.
When a node's work is done, tell the graph so —
`the-loop graph complete <id>` — rather than only narrating the transition.

See `reference/workflow.md` for what each phase contains, the review gates, the
self/critic-review counts, evidence, resumability and DAG orchestration.

## Operating principles (rules)

- **Every work item has a ticket.** Nothing the harness works on lacks a GH issue (or
  Jira) ticket.
- **Spec before execution.** Create the spec chain and get each phase
  reviewed/approved by the required collaborators before writing code.
- **Approvals are owned by approval nodes** (issue-281). The graph's human gates
  (`requirements-approval`, `design-approval`, and `human-approval` on the PR) are where
  feedback is classified and where locking happens: an authorized approval at the gate
  writes `status: approved` and the approver into the artifact via `lock-artifacts`.
  **Never set `status: approved` yourself, and never post an approval request of your
  own** — the gate's `request-review` is the one ask, and a session-invented stop just
  costs the human a second approval the gate will discard. An artifact whose gate lies
  ahead is complete when its sections are; iterate it with the feedback the gate
  records into it.
- **Gate-less artifacts advance on shape alone.** `brainstorm.md` and `tasks.md` have no
  approval node — do not hold them for a human "approved". `tasks.md` is derived from
  the pair the human just approved at `design-approval`; the brainstorm converges when
  its author says so on the thread. Never write a downstream artifact against an
  upstream one whose gate has not yet approved it.
- **Human review per phase** — always on, delivered by the graph's approval nodes, never
  re-implemented in a session (the `workflow.requireHumanReviewPerPhase` switch was
  removed in issue-352; nothing read it).
- **Skips are declared by humans, never taken by the harness** (issue-177,
  decision-067). Every work item starts at **`phase-selection`**: the-loop posts a
  checklist of the selectable phases on the ticket and waits for an **authorized user**
  to reply with the ones to keep plus `the-loop execute`. **Every phase of the outer loop
  is selectable** (issue-179, decision-068) — the spec chain, the testing plan, the
  reviews, the security review and the approval gate alike — with exactly one exception:
  `phase-selection` itself, which is `required: true` so the loop can never walk past the
  act of choosing. That invariant is the floor now: not a list of phases that always run,
  but a named human answering, up front, which ones do. **The same gate also offers what
  is *not* on by default** (issue-188, decision-071): a node marked `optIn` is rendered
  unticked and runs only if somebody ticks it — the loop ships one,
  `design-critic-review`, a different model reading the locked `design.md` before the
  testing plan and task DAG are derived from it. An operator can make the same
  declaration with `the-loop graph skip <id> --node <token> --reason <why>`
  (audited, like `force`). A declared skip is reported by `the-loop check` as
  *skipped by declaration* with provenance — never as a pass. **Never answer the
  selection gate or run the skip verb from a working session**: if phases seem
  unnecessary, say so on the ticket and let a human declare it. The same reply also
  answers the two questions that are **not** phases — where the outer loop is iterated
  (issue-183) and how many sessions this item's pull requests get (issue-260,
  `pr-sessions-*`, defaulting to the operator's `routing.tmux.sessionPerPr`) — and the
  agent never ticks those rows either. See `reference/workflow.md` § Declared skips.
- **Reference, don't duplicate (single source of truth).** Once
  requirements/design/testing-plan/tasks exist, update the ticket with a **link** to each
  checked-in artifact. Subsequent
  changes are **edits to those files, not new comments**.
- **Capability docs are the organized view of specs.** Raw specs under
  `docs/specs/<id>/` are the per-work-item record (*deltas*); living capability docs
  under `docs/capabilities/` (indexed by `capabilities.md`) are the **single source of
  truth for a capability's *current*
  behaviour** (*state*), each behaviour traced by a history row to the specs/decisions
  that produced it. Update the affected capability docs **in the same PR** as the work
  item — a ready-to-ship gate item. Mint docs emergently (product-feature and
  architecture shaped both valid) and evolve the taxonomy through PR-review feedback.
  See `reference/workflow.md`.
- **The user-facing docs ship with the change too.** Capability docs serve a reader who
  already uses the project; `README.md`, the documentation site and this skill with its
  `reference/` docs are what a reader meets *first*, and they rot the same way. Update
  whichever of them the change makes wrong **in the same PR** — also a ready-to-ship gate
  item — and record what changed in the execution log's **`## Documentation`** section,
  which the `capability-docs` node gates alongside `## Capability docs` (issue-174,
  decision-066). A work item that changed no user-facing doc says so **with the reason**;
  a blank is not an answer. The rule exists because the process itself changed shape —
  two loops, a fourth spec artifact — while the front page went on describing the old one.
- **Keep `tasks.md` checkmarks current** as tasks complete (`- [ ]` → `- [x]`).
- **Identify collaborators up-front.** Each work item names the personas it needs; not
  every task needs every persona (a bug fix needs the engineer; a content fix may not).
  More can be added later. See `reference/collaboration.md`.
- **Paper trail.** Every human decision/opinion is captured on the ticket or PR.
  Planning questions → ticket comments. PR & all reviews → PR/ticket comments.
  Notify via configured messaging channels when a human action is pending.
- **One work item, one origin repository; one contributing repository, one PR.** The
  outer loop runs in the repository the ticket was created in — the **origin** repository
  — and the work item's one spec chain lives there. A work item that needs code in *n*
  repositories raises *n* pull requests, one per repository, each walking its own
  `pdlc-pr-loop`; the origin repository gets one only if it too receives code. Each inner
  loop's state sits under the origin repo's spec directory, qualified by repository
  (`pr-loops/<owner>__<repo>/pr-<n>/`), and a work item may **declare** those repositories
  in `execution-log.md`'s front matter (`repos:`) so `await-inner-loops` holds
  `implementation` until every one of them has finished. See `reference/workflow.md`
  § Several repositories, one work item.
- **Ask on the declared channel; iterate artifacts on a durable surface.** A session the CLI daemon
  drives is *told* where its answers come from (`routing.interaction.mode`, rendered into
  the prompt): `work-item` (the default) means every question is a **comment on the ticket
  or PR** and the session then waits for the reply to arrive as an event — never block on
  an interactive prompt, never read silence as consent; `cli` means a human is attached to
  this terminal, so ask here and record the *outcome* on the ticket. **Independently of
  the mode:** once an artifact exists (`brainstorm.md`, `requirements.md`/`bugfix.md`,
  `design.md`, `testing-plan.md`, `tasks.md`), iterate on it **only** on a durable,
  reviewable surface — never interactively, where the reasoning dies with the scrollback.
  Which durable surface the **outer** loop uses is **this work item's own choice**,
  made by its author at `phase-selection` and frozen there: the **work item** itself
  (the default — comments on the ticket, Jira-style, so an item whose code lands
  elsewhere opens no discussion-only PR) or a **pull request** in the origin repository
  (the `outer-loop-on-pull-request` box). It is deliberately not a config key in any
  file: one project has both a one-repo bugfix and a three-repo migration. Commit and
  push the artifact either way and link it; never re-paste it into a comment. The
  **inner** loop has no such choice — a PR's loop is iterated on that PR — and neither
  does a **contribution**, which owns no outer loop and is never offered the box. See
  `reference/collaboration.md` § Where questions go.
- **RULE: mark every comment/reply as your own (loop prevention).** You post as the
  operator's own credentials, so an unmarked reply is indistinguishable from a human
  one and can resume your own session forever. Before posting **any** comment, PR
  review, or reply — not just review findings — append `<!-- the-loop:agent-comment -->`
  (exact string, invisible) plus a short visible attribution line. This applies at
  every point above that posts a comment (paper trail, reviews, escalations, the PR
  briefing). See `reference/collaboration.md` § loop prevention.
- **Self-check continuously.** Maintain `docs/specs/<id>/execution-log.md`; keep the
  phase label in sync; run tests at logical checkpoints; log progress for visibility.
- **Manage the context window deliberately (checkpoint, then reset).** Never reset
  context without first checkpointing (checkmarks, execution-log entry with a concrete
  next step, phase label, WIP committed/noted). Then: **clear** at phase boundaries
  (locked spec → fresh window for implementation, plan-mode style), **compact** after
  each completed task and mid-task (never clear mid-task), and isolate high-volume
  exploration in subagents. The checked-in artifacts are the memory that makes resets
  affordable. The boundaries are fixed rules; see `reference/context.md`.
- **Review before escalating.** Run the operator's `reviews.selfReviewCount`
  self-reviews then `reviews.criticReviewCount` critic reviews (a different
  harness/model) BEFORE reaching out to a human — the review-round policy is the
  operator's CLI config, read with `the-loop critic policy` (default 3 each, also when
  the CLI is not installed). All reviews are comments. **Follow the defined
  procedure** in `reference/reviewing.md` (attribution prefix, reply-first-then-fix,
  stop on zero new findings, escalate on a repeated finding).
- **Security is gated, not bolted on** (always on). Every phase gate also asks
  the security question: requirements carry a **Security considerations**
  threat-model-lite (untrusted actors, trust boundaries, abuse cases, fail-closed);
  design carries a **Security design** section enforcing those boundaries; the
  ready-to-ship gate includes a **security review** (built-in security-review skill or
  the-loop's checklist), with a named human sign-off at risk tier 4 and above. "No new
  attack surface" is written and justified, never implied. See `reference/security.md`.
- **Test-first.** Tests are written alongside the implementation: no production code
  without a failing test that motivates it, and a bug fix reproduces the bug red first;
  record the red→green transition as evidence.
- **Plan the proof, then execute the plan.** How a work item will be verified is an
  artifact (`testing-plan.md`), not an afterthought: the `test-planning` node decides
  which kinds of testing apply — unit, integration, contract, e2e, UI/visual, snapshot,
  performance, security/abuse-case, accessibility, migration, manual — and records
  `n/a` **with a reason** for the ones that do not. The `verification` node then runs it,
  ticks each activity only once it has actually run, and records per-activity command,
  outcome and evidence. An activity that cannot run is **not** ticked: say why, replan or
  escalate. See `reference/testing.md`.
- **Evidence is captured, committed, and redacted.** Test output, screenshots and
  recordings live under `<specDir>/<id>/evidence/` and are committed with the work item —
  a link to a CI run that expires is not evidence. **Textual evidence is markdown
  (`.md`), never `.txt`** — titled, sectioned per command, with the raw output in fenced
  blocks; binary captures keep their own formats and are referenced from it. UI
  verification presents screenshots
  of the verified states, and an animated capture (GIF) when the behaviour is a *flow*.
  Because the directory is as public as the repository, redact tokens, cookies, personal
  data and internal hostnames before committing; a capture that cannot be redacted is not
  committed.
- **the-loop facilitates verification; it does not own it.** For anything beyond a single
  repository — several checkouts, a staging environment, a bespoke harness — the plan's
  **Verification environment** section *declares* what is needed (repos, services,
  fixtures, credentials **by reference only**) and names the project's own commands. the-loop
  brings no runner or environment manager of its own, and reads the operator's
  `customInstructions` docs rather than restating them.
- **Scenario-documented integration tests.** Every integration test carries a
  Gherkin-syntax docstring (`Feature:`/`Scenario:`/Given-When-Then) naming the scenario
  under test, with a `Requirement:` link when tied to a `requirements.md`
  (`config.testing`). The harness can query all covered scenarios as a table via
  `the-loop scenarios --glob <testing.integrationTestGlobs entry>…`
  (`--format table|markdown|json`). See `reference/testing.md`.
- **Contract-first APIs.** RESTful API specs are authored in `specs/openapi/` in the
  OpenAPI format; GraphQL schemas are SDL-first under `specs/graphql/`; documentation is
  generated from those contracts, never hand-written (`config.apiSpecs`). See
  `reference/testing.md`.
- **UI/UX design is a first-class artifact.** For user-facing work, `design.md` (markdown +
  mermaid) is not enough — the **visual** design is tracked as artifacts under
  `docs/specs/<id>/design/` (`design.uiArtifacts`): Figma links and/or self-contained
  HTML+CSS+JS prototypes (Claude-artifact style). They are iterated-until-locked with the
  **designer** on the *rendered* output, referenced from the ticket, and become the visual
  contract implementation matches. Backend/CLI/infra work produces none. See
  `reference/design-artifacts.md`.
- **Minimalism.** Apply the `reference/minimalism.md` decision ladder (YAGNI → stdlib →
  native → existing dep → inline → new abstraction); justify every new dependency in
  `design.md`. Never trade away validation/error-handling/security/accessibility.
- **Write the artifacts for the human who has to approve them.** Every document a person
  reads — `requirements.md`, `design.md`, `testing-plan.md`, the PR briefing, decision and
  capability docs, ticket and review comments — follows the bundled **`the-loop:writing`**
  skill — the writing contract, fixed: a four-part spine (what was broken → what we did
  → what it costs → what to check), conclusion-first sections, and **draw it rather than
  describe it** where three or more named parts are involved. **There is no length
  limit** — scope is not knowable in advance, so the test is *density* (can a sentence
  come out without losing information?), and that is a review judgement, never a gate.
  Two things concision never buys: a **gated section is never deleted to shorten a
  document** (say it is empty, and why), and the **formal registers stay formal** — EARS
  criteria, abuse cases, RFC-2119 keywords, API contracts and schema descriptions are
  contracts, not prose. Distinct from the token-economy verbosity rule, which compresses
  chat narration and preserves specs; this governs the specs themselves. Rules and the
  tells catalogue live in the skill — do not restate them here.
- **Token economy.** Apply the `reference/token-economy.md` levers: progressive/
  phase-scoped disclosure, dense prompts, thinking effort by stage, narration-only output
  compression (with its preservation list), sub-agent delegation for verbose work,
  compaction/filesystem-memory, and per-work-item token telemetry. **Guidance, never
  configured, never a gate** — the harness runs the model the operator chose; cheaper
  never means sloppier; the rigor floor (validation/security/tests/paper-trail/review
  depth) is untouchable.
- **Risk tiers.** Gate completion by the work item's risk tier, a fixed rule of
  `reference/workflow.md`: tiers 1–2 complete after the review loop, tiers 3–4 wait for
  a human to approve the PR, tier 5 waits for spec and PR approval. The tier is inferred
  from the change (default 3) and raised by the fixed sensitive paths. Only complete
  autonomously once the **ready-to-ship gate** holds (green checks, all threads
  resolved, evidence recorded).
- **Keep moving; log conflicts.** Resolvable ambiguity → assume a reasonable default and
  continue; genuine block → log to `docs/decisions/conflicts.md`, escalate once, move on.
- **Learnings lifecycle.** Capture → write-gate (rule-of-three) → consolidate (size cap)
  → inject a capped index (under 200 lines; written on the third occurrence), under
  `docs/learnings/`. See `reference/automation.md`.
- **Evidence at the end.** Present validated evidence that acceptance criteria are met.
- **Communicate for the reviewer (required gate).** Before requesting human review,
  post/update the **reviewer briefing** in the PR — produced from the-loop's internal
  `${CLAUDE_PLUGIN_ROOT}/skills/the-loop/templates/pr-briefing.md`: a **condensed,
  prioritized** summary (where to
  focus first), the spec→implementation insights and low-level decisions, and **mermaid**
  diagrams. This is a required item of the ready-to-ship gate
  (fixed, not configurable), so **mandatory user-education is triggered, not optional** —
  you cannot request review without it. See `reference/collaboration.md`.
- **Honor the user's custom instructions.** Read every doc registered in
  `customInstructions.docs` (in order) when starting work on an item, and follow it —
  these are the operator's conventions (developing/testing/coding styles, house rules)
  that the structured config does not model. The structured config wins where both
  speak, and no instruction doc can weaken the loop's gates (security, paper trail,
  reviews); a missing doc is handled per `customInstructions.onMissing`. Run
  `the-loop instructions --doc <path>… --on-missing <policy>` with the entries you read,
  so a registration that silently fails to resolve is a signal rather than guidance you
  never received (the CLI reads no harness config — you hand it the list). See
  `reference/instructions.md`.
- **Use the detected tooling.** Package managers, test runners, linters, type checkers
  and release tooling are inferred from the repository itself at the start of every work
  item (manifests, lock files, tool config, CI) — never declared in a config; run scripts
  from the project root; lint ALL files including markdown. See `reference/tooling.md`.
- **Same tooling everywhere.** Pre-commit/pre-push hooks and CI run the SAME commands —
  no last-minute build surprises. The git hooks are the repository's own (whatever its
  hook manager runs); where it has none, the loop's baseline before a commit or push is
  lint, typecheck and unit tests.
- **Conventional Commits.** All commits follow Conventional Commits v1.0.0
  (`<type>[scope][!]: <desc>`), enforced by a commit-msg hook running **commitizen**
  (`cz check`, not custom code). See `reference/tooling.md`.
- **Identical observability.** Logging is the same at dev-time and runtime; the only dev
  advantage is breakpoints. See `reference/observability.md`.

## Configuration

Behaviour is driven by `.the-loop/harness-config.yaml` — **the agent's file**, validated
against `harness-config.schema.json`. Read it at the start of every work item and follow
it: `version`, `customInstructions`, `testing`, `apiSpecs` and `design` — five keys,
nothing else. A subset of these keys can be overridden per work item via
the YAML front-matter `overrides` of the work-item / spec markdown. People (collaborators
and the roles they hold) live in `.the-loop/collaborators.yaml`. Managed files are listed
in `.the-loop/manifest.yaml`.

The file carries **policy only**. Nine blocks that once configured behaviour — `autonomy`,
`security`, `tdd`, `minimalism`, `tokenEconomy`, `selfImprovement`, `contextManagement`,
`userInteraction` and `externalTools` — were removed in issue-352 because they
configured what is simply the loop's rule. Those rules are stated where they belong: the
risk tiers and sensitive paths in `reference/workflow.md`, the security gates in
`reference/security.md`, standard TDD in `reference/workflow.md`, the minimalism ladder
in `reference/minimalism.md`, the token-economy guidance in `reference/token-economy.md`,
the learnings numbers in `reference/automation.md`, the context-window protocol in
`reference/context.md`, and the user-interaction and writing contract in
`reference/collaboration.md` and the `the-loop:writing` skill. Tools are discovered, not
declared.

Five more blocks left in the third pass because they described the repository or the
operator, not a decision of the project. `repository`, `tooling` and `hooks`: the layout
(monorepo and its workspace tool), the per-language tooling and the git hooks are
**inferred from the repository itself, every session** — manifests, lock files, tool
config, the hook manager's config, cross-checked against CI — per `reference/tooling.md`;
nothing is written into a config. `observability`: log levels are the project's own
logging configuration, and browser logging uses whatever tool the harness discovers
(`reference/observability.md`). `reviews`: the review-round policy is the **operator's**,
top-level `reviews` in `cli-config.yaml`, read with `the-loop critic policy`
(`reference/reviewing.md`). And `workflow` left in the fourth: the doc trees are the
loop's fixed convention — specs at `docs/specs/<id>/`, capability docs at
`docs/capabilities/`, learnings at `docs/learnings/` — not a location a project configures.

**The CLI never reads this file** (issue-352, decision-123). The `the-loop` CLI is the
operator's tool and takes its configuration from the operator's `cli-config.yaml`
(`--config` / `$THE_LOOP_CLI_CONFIG` / `./.the-loop/cli-config.yaml` /
`~/.the-loop/cli-config.yaml`). So when you run the CLI, **you** carry the harness config
to it — the file is yours to read, the flags are yours to pass:

| Harness-config key (yours) | How the CLI learns it |
|---|---|
| *(spec directory)* | Not in this file. Specs live at `docs/specs/<id>/` — the loop's fixed convention, which the CLI's own `routing.graph.specDir` defaults to. `--spec-dir <dir>` on `the-loop check` / `the-loop graph` is only for an operator whose instance drives repositories laid out differently. |
| `testing.integrationTestGlobs` | `the-loop scenarios --glob <pattern>` (repeatable). No `--glob` means the built-in defaults. |
| `customInstructions.docs` / `.onMissing` | `the-loop instructions --doc <path> … --on-missing <warn\|error\|ignore>`. A `--doc` may be a JSON object `{"path": …, "notes": …}` to carry the entry's notes. |
| *(critics)* | Not in this file. Which critic harnesses exist is the operator's `critics[]` in `cli-config.yaml`, and how many rounds to run with them is the operator's `reviews` there too: `the-loop critic list` tells you what this machine has, `the-loop critic policy` the round counts and stop conditions (the defaults — 3 self, 3 critic, stop on no new findings, escalate on a repeat — when the operator set none, or when the CLI is not installed). |
| *(graph hooks)* | Not in this file. The operator's `routing.graph.hooks` in `cli-config.yaml`; `the-loop graph hooks` prints what is declared. |

Two things this file **no longer** says, because they were never the repository's to
decide: the **ticketing system** (a work item's ticket is its ref — `github:owner/repo#n`
— and the CLI derives the repository from the checkout's `origin` remote when no `--ref`
is given) and the **phase labels** (`loop:<phase>`, one fixed vocabulary, so dashboards
built on it work across every repository).

**The schemas are the plugin's, not the project's** (issue-220). All three —
`harness-config`, `collaborators`, `cli-config` — ship under
`${CLAUDE_PLUGIN_ROOT}/.the-loop/` (`manifest.schemasDir`, the same shape
`manifest.templatesDir` has for templates) and are read from there whenever a config is
validated or the onboarding walkthrough is driven. Never copy one into a project, and
never fetch one over the network. A scaffolded config carries the schema's published URL
in a `# yaml-language-server: $schema=…` **first line** so an operator's editor validates
it; that comment is for the editor alone and is never what the loop validates against.

**A repository that has never run `/the-loop:init`** carries no `.the-loop/`. Work it
under the schema's defaults (the same baseline `/the-loop:init --defaults` writes) and say
so in the execution log; nothing writes a config into the repository for you — until
issue-352 the CLI did, and now neither the CLI nor a guest loop (a contribution, a review)
touches the repository's configuration. Suggest `/the-loop:init` on the ticket when the
project is the work item's own.

The CLI daemon (`the-loop start`, the receiver, the poller, `sessions`, `events`) reads
the separate **CLI config** described above and nothing of this repository's. See
`docs/config/` (the configuration reference), `docs/decisions/decision-032.md` and
`docs/decisions/decision-123.md`.

## Commands

- `/the-loop:init` — scaffold the-loop into a repo (config, docs, templates, phase labels).
- `/the-loop:work-on <ticket>` — run the whole loop on a work item (resumable per phase).
  **Superset** of the granular commands below.
- `/the-loop:upgrade-the-loop` — reconcile project files with the installed plugin version.

Granular commands (one step at a time; same flow `work-on` runs end-to-end):

- `/the-loop:brainstorm <title>` — *(optional Phase 0)* draft a free-form `brainstorm.md`
  scratchpad (the root artifact) in `docs/specs/draft-<slug>/` for a fuzzy idea; iterate,
  then convert to requirements.
- `/the-loop:new-requirement <title>` — draft `requirements.md` in a temporary
  `docs/specs/draft-<slug>/` folder **before a ticket exists** (converts a sibling
  `brainstorm.md` if one is present).
- `/the-loop:create-ticket <path>` — create the ticket from a `requirements.md` and
  promote `draft-<slug>/` → `docs/specs/<id>/`.
- `/the-loop:create-design <id>` — `requirements.md` → `design.md` (Phase 2).
- `/the-loop:create-testing-plan <id>` — requirements + design → `testing-plan.md`.
- `/the-loop:create-tasks-plan <id>` — requirements + design + testing plan → `tasks.md` DAG.
- `/the-loop:execute-tasks <id>` — implement the DAG, self-check, self/critic-review.
- `/the-loop:verify-work <id>` — execute the testing plan; record results and evidence.
- `/the-loop:finish-tasks <id>` — cleanup after all tasks (close the ticket; extensible).
- `/the-loop:work-status <id>` — read-only status from the specs, tasks checkmarks and log.
- `/the-loop:contribute-to <id>` — join an **existing, in-progress** work item as a
  contributor: walk `pdlc-contribution-loop` toward the human-stated goal and success
  criteria (issue-185).
- `/the-loop:do-task <id>` — do an **ad-hoc, tactical** task with no PDLC process: walk
  `pdlc-adhoc-loop`, author no spec chain, ask follow-ups on the thread, and continue
  until the requester declares it done (issue-225).
- `/the-loop:review-pr <id>` — **review** a pull request against an authorized
  reviewer's brief: walk `pdlc-review-loop`, answer every question, examine every
  angle, run every validation, converse until the reviewer says done — and change no
  code (issue-279).

## Knowledge the loop maintains

- `docs/specs/<id>/brainstorm.md` — *(optional)* the root scratchpad a work item was
  explored in before requirements.
- `docs/specs/<id>/testing-plan.md` + `docs/specs/<id>/evidence/` — how the work item is
  proved, and the committed proof.
- `docs/architecture/architecture.md` — architecture index → sub-component docs.
- `docs/capabilities/capabilities.md` + `<capability>.md` — living capability docs:
  the organized view of specs; current behaviour per capability with history links.
- `docs/decisions/decisions.md` + `decision-<nnn>.md` — decision log (every durable
  decision is recorded).
- `docs/specs/<id>/` — the per-work-item 3-phase spec + execution log.
- `docs/learnings/learnings.md` + `learning-<nnn>.md` — learnings from user & system
  feedback, checked in for review; the tree sits with the other documents the loop
  maintains. See `reference/automation.md`.

## Interacting with other tools

the-loop may freely use the MCP servers, CLIs, skills and plugins available in the
harness. Nothing registers them: discover what the harness actually offers, and check
before assuming a capability is available.

## Custom instructions the loop honors

`config.customInstructions` registers **guidance**, not tools: user-provided
readme/markdown docs (per installation,
configurable paths) the harness reads at the start of working an item and follows —
conventions and styles the structured config does not model. Precedence and limits:
`reference/instructions.md`.