| 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 3-phase spec (requirements/design/tasks), execute the task DAG, 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 3-phase spec (requirements →
design → 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/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/tooling.md — repo management, per-language tooling matrix, hooks, CI parity.reference/testing.md — 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/collaboration.md — personas/roles, paper trail, conflict log, messaging, MCP.reference/observability.md — dev==runtime logging, levels, browser logging.reference/automation.md — distribution, the CLI, webhooks, predictability, learnings lifecycle.
The artifact chain (optional brainstorm → 3-phase spec, Kiro-style)
Every work item is a chain of artifacts, each derived from and iterated after the one
before it. The rule holds at every link: an artifact is refined with human feedback until
it is locked (status: approved), and only then is the next one derived. 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
locked. Phase: brainstorming. Skip it when the work is already clear.requirements.md (or bugfix.md for bugs) — user stories + EARS acceptance
criteria (WHEN <event> THEN the system SHALL <response>). Phase: requirements-definition.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).tasks.md — a DAG of small, verifiable tasks referencing requirements.
Phase: tasks-breakdown.
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 → tasks-breakdown
→ implementation → needs-review → complete
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 3-phase spec and get each phase
reviewed/approved by the required collaborators before writing code.
- Iterate each artifact until locked, then advance. Starting from the optional
brainstorm.md root, every artifact is refined with human feedback until it is locked
(status: approved); only then is the next artifact derived and the phase advanced.
Never write a downstream artifact against an unlocked upstream one. Brainstorming is
optional — a well-defined work item starts at requirements.
- Human review per phase (
workflow.requireHumanReviewPerPhase, default true).
- Reference, don't duplicate (single source of truth). Once requirements/design/
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 workflow.capabilitiesDir (default 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.
- 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.
- 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.
- Review before escalating. Run
reviews.selfReviewCount self-reviews then
reviews.criticReviewCount critic reviews (a different harness/model), default 3
each, BEFORE reaching out to a human. 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).
- Test-first.
tdd.mode (default standard): no production code without a failing
test that motivates it; record the red→green transition as evidence.
- 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 (--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.
- 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). 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/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. See reference/collaboration.md.
- Use the configured tooling. Package managers, test runners, linters, type checkers
and release tooling come from
.the-loop/config.yaml; 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.
- 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. 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/config.yaml, validated against
.the-loop/config.schema.json. Sections: ticketing, repository, workflow,
tooling, testing, apiSpecs, localOrchestration, hooks, observability,
reviews, autonomy, tdd,
minimalism, selfImprovement, userInteraction, personas, messaging,
externalTools, webhooks. 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.
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-tasks-plan <id> — requirements + design → tasks.md DAG (Phase 3)./the-loop:execute-tasks <id> — implement the DAG, self-check, self/critic-review./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.
Knowledge the loop maintains
docs/specs/<id>/brainstorm.md — (optional) the root scratchpad a work item was
explored in before requirements.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.learnings/learnings.md + learning-<nnn>.md — learnings from user & system
feedback, checked in for review. See reference/automation.md.
Interacting with other tools
the-loop may freely use the MCP servers, CLIs, skills and plugins registered in
.the-loop/external-tools.md (or externalTools.notes). Check that registry before
assuming a capability is available.
