The loop
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.From its SKILL.md
npx -y skills add MadaraUchiha-314/the-loop --skill the-loopAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 8 stars8 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
32.6 KB, as published. Nobody here has run it
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, autonomy, 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/initruns (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 routing, verbosity, disclosure, sub-agents, telemetry); advisory, 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>/:
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 neverstatus: approved(issue-281). Phase:brainstorming. Skip it when the work is already clear.requirements.md(orbugfix.mdfor 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## Requirementsand## Security considerationssections; both bundled templates provide them.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 underdocs/specs/<id>/design/), iterated-until-locked with the designer (reference/design-artifacts.md).testing-plan.md— how this work item will be proved: a matrix of testing types (each either in scope, orn/awith a reason), the verification environment, the evidence to capture, and the activities checklist. Phase:test-planning. Derived fromdesign.mdand 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 theverificationnode — one artifact, written once as a plan and once as a record. Seereference/testing.md.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
(<workflow.phaseLabelPrefix><phase>) 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, andhuman-approvalon the PR) are where feedback is classified and where locking happens: an authorized approval at the gate writesstatus: approvedand the approver into the artifact vialock-artifacts. Never setstatus: approvedyourself, and never post an approval request of your own — the gate'srequest-reviewis 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.mdandtasks.mdhave no approval node — do not hold them for a human "approved".tasks.mdis derived from the pair the human just approved atdesign-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 (
workflow.requireHumanReviewPerPhase, default true) — delivered by the graph's approval nodes, never re-implemented in a session. - 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 plusthe-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-selectionitself, which isrequired: trueso 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 markedoptInis rendered unticked and runs only if somebody ticks it — the loop ships one,design-critic-review, a different model reading the lockeddesign.mdbefore the testing plan and task DAG are derived from it. An operator can make the same declaration withthe-loop graph skip <id> --node <token> --reason <why>(audited, likeforce). A declared skip is reported bythe-loop checkas 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'srouting.tmux.sessionPerPr) — and the agent never ticks those rows either. Seereference/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 underworkflow.capabilitiesDir(defaultdocs/capabilities/, indexed bycapabilities.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. Seereference/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 itsreference/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## Documentationsection, which thecapability-docsnode 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.mdcheckmarks 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 inexecution-log.md's front matter (repos:) soawait-inner-loopsholdsimplementationuntil every one of them has finished. Seereference/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;climeans 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 atphase-selectionand 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 (theouter-loop-on-pull-requestbox). 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. Seereference/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). Seereference/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 (
contextManagement). Seereference/context.md. - Review before escalating. Run
reviews.selfReviewCountself-reviews thenreviews.criticReviewCountcritic reviews (a different harness/model), default 3 each, BEFORE reaching out to a human. All reviews are comments. Follow the defined procedure inreference/reviewing.md(attribution prefix, reply-first-then-fix, stop on zero new findings, escalate on a repeated finding). - Security is gated, not bolted on (
config.security). 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 ≥security.review.humanSignOffMinTier. "No new attack surface" is written and justified, never implied. Seereference/security.md. - Test-first.
tdd.mode(defaultstandard): no production code without a failing test that motivates it; 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: thetest-planningnode decides which kinds of testing apply — unit, integration, contract, e2e, UI/visual, snapshot, performance, security/abuse-case, accessibility, migration, manual — and recordsn/awith a reason for the ones that do not. Theverificationnode 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. Seereference/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
customInstructionsdocs 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 aRequirement:link when tied to arequirements.md(config.testing). The harness can query all covered scenarios as a table viathe-loop scenarios(--format table|markdown|json). Seereference/testing.md. - Contract-first APIs. RESTful API specs are authored in
specs/openapi/in the OpenAPI format; GraphQL schemas are SDL-first underspecs/graphql/; documentation is generated from those contracts, never hand-written (config.apiSpecs). Seereference/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 underdocs/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. Seereference/design-artifacts.md. - Minimalism. Apply the
reference/minimalism.mddecision ladder (YAGNI → stdlib → native → existing dep → inline → new abstraction); justify every new dependency indesign.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 bundledthe-loop:writingskill (userInteraction.writingStyle): 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 (writingStyle.diagramFirst). 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 (writingStyle.formalRegisters) are contracts, not prose. Distinct fromtokenEconomy.outputVerbosity, 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.mdlevers (config.tokenEconomy): progressive/phase-scoped disclosure, dense prompts, model routing + thinking-effort by stage/risk tier, narration-only output compression (with its preservation list), sub-agent delegation for verbose work, compaction/filesystem-memory, and per-work-item token telemetry. Advisory, never a gate — cheaper never means sloppier; the rigor floor (validation/security/tests/paper-trail/review depth) is untouchable. - Risk-tiered autonomy. Gate completion by the work item's risk tier
(
config.autonomy): low tiers may complete after the review loop; high tiers wait for a human. 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 (
config.selfImprovement), in the treeworkflow.learningsDirnames (defaultdocs/learnings). Seereference/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 (userInteraction.prSummary.required), so mandatory user-education is triggered, not optional — you cannot request review without it. Seereference/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 percustomInstructions.onMissing. Runthe-loop instructionsat the same time, so a registration that silently fails to resolve is a signal rather than guidance you never received. Seereference/instructions.md. - Use the configured tooling. Package managers, test runners, linters, type checkers
and release tooling come from
.the-loop/harness-config.yaml; run scripts from the project root; lint ALL files including markdown. Seereference/tooling.md. - Same tooling everywhere. Pre-commit/pre-push hooks and CI run the SAME commands — no last-minute build surprises.
- 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) —hooks.commitConvention. Seereference/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 (this repo's harness/plugin
config, formerly config.yaml — issue-82, decision-035), validated against
harness-config.schema.json. Sections: ticketing, repository,
workflow, tooling, customInstructions, testing, apiSpecs, design,
localOrchestration, hooks, observability, reviews, autonomy, security, tdd,
minimalism, tokenEconomy, selfImprovement, contextManagement, userInteraction,
notifications, externalTools. People (collaborators + their notification channels)
live in .the-loop/collaborators.yaml (validated against collaborators.schema.json) —
the single source of truth; notifications
references roles only. A subset of keys can be overridden per work
item via the YAML front-matter overrides of the work-item / spec markdown. Managed
files are listed in .the-loop/manifest.yaml.
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 is worked under the built-in default
— the same baseline --defaults writes, shipped inside the CLI — and the-loop writes it
into .the-loop/harness-config.yaml the first time it works there, so the config is a
file you can read and edit rather than an assumption (issue-193, decision-073). It never
overwrites an existing config, and a contribution adopts nothing: see
reference/automation.md.
The CLI daemon (gh-webhook/poll/sessions/events) reads a separate, independent
CLI config instead (webhooks, polling, eventLog) — it is not tied to this
repo. See docs/config/ (the configuration reference) and
docs/decisions/decision-032.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-formbrainstorm.mdscratchpad (the root artifact) indocs/specs/draft-<slug>/for a fuzzy idea; iterate, then convert to requirements./the-loop:new-requirement <title>— draftrequirements.mdin a temporarydocs/specs/draft-<slug>/folder before a ticket exists (converts a siblingbrainstorm.mdif one is present)./the-loop:create-ticket <path>— create the ticket from arequirements.mdand promotedraft-<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.mdDAG./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: walkpdlc-contribution-looptoward the human-stated goal and success criteria (issue-185)./the-loop:do-task <id>— do an ad-hoc, tactical task with no PDLC process: walkpdlc-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: walkpdlc-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.<learningsDir>/learnings.md+learning-<nnn>.md— learnings from user & system feedback, checked in for review.workflow.learningsDir(defaultdocs/learnings), so the tree sits wherever this project keeps the documents the loop maintains. Seereference/automation.md.
Interacting with other tools
the-loop may freely use the MCP servers, CLIs, skills and plugins registered in
config.externalTools (the externalTools.tools list + notes in
.the-loop/harness-config.yaml). Check that registry before assuming a capability is available.
Custom instructions the loop honors
Supplementary to the external-tools registry, config.customInstructions registers
guidance rather than 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.
What ships with it: 33 files
164.3 KB alongside SKILL.md
reference/
- automation.md14.7 KB
- collaboration.md11.8 KB
- context.md7.7 KB
- design-artifacts.md6.6 KB
- instructions.md5.6 KB
- minimalism.md2.3 KB
- observability.md5.7 KB
- onboarding.md5.4 KB
- reviewing.md7.5 KB
- security.md6.2 KB
- testing.md4.8 KB
- token-economy.md7.6 KB
- tooling.md6.7 KB
- workflow.md17.7 KB
templates/
- brainstorm.md2.4 KB
- bugfix.md1.9 KB
- bug.md739 B
- capability.md1.4 KB
- cli-config.yaml16.2 KB
- collaborators.yaml1.4 KB
- conflicts.md583 B
- decision.md538 B
- design.md3.8 KB
- epic.md1.1 KB
- execution-log.md2.9 KB
- harness-config.yaml12.3 KB
- learning.md353 B
- pr-briefing.md1.2 KB
- requirements.md2.8 KB
- story.md903 B
- tasks.md2.2 KB
- webhook-autoexecute-prompt.md742 B
- webhook-event-prompt.md800 B