Capability: spec-workflow
The core loop: a work item is specified as a chain of artifacts — optional brainstorm, then a Kiro-style 3-phase spec — each iterated with human feedback until locked, then executed end-to-end with minimal intervention.
What it is
The product-development-lifecycle workflow the-loop runs on every work item, exposed as the /the-loop:work-on superset command and granular per-step commands (brainstorm, new-requirement, create-ticket, create-design, create-tasks-plan, execute-tasks, finish-tasks, work-status).
Current behaviour
- Every work item SHALL have a ticket; nothing is worked without one.
- A work item's spec SHALL live in
docs/specs/<id>/as the artifact chainbrainstorm.md (optional) → requirements.md|bugfix.md → design.md → tasks.md, plusexecution-log.md. - Each artifact SHALL be iterated with feedback until locked (
status: approved); no downstream artifact is written against an unlocked upstream one (workflow.requireHumanReviewPerPhase, default true). - WHEN a work item starts as a fuzzy idea THEN the loop SHALL begin with a
brainstorm.mdroot artifact (optional Phase 0) and convert it to requirements once locked. - The work item's phase SHALL be tracked on the ticket via labels (
<workflow.phaseLabelPrefix><phase>) through the state machinenot-started → brainstorming (optional) → requirements-definition → design → tasks-breakdown → implementation → needs-review → complete, mirrored in the execution log. tasks.mdSHALL be a DAG of small verifiable tasks referencing requirements; checkmarks are kept current during implementation.- Security SHALL be a gated concern of each phase (
config.security): requirements/bugfix carry a Security considerations threat-model-lite (untrusted actors, trust boundaries, abuse cases, fail-closed — "no new attack surface" is written and justified, never implied); design carries a Security design section enforcing every boundary; security-relevant tasks name the negative test proving the boundary holds. - Completion SHALL be gated by the ready-to-ship gate (green checks, threads resolved, evidence, a passed security review — built-in security-review skill or the-loop's checklist per
security.review.mechanism— PR briefing, capability docs folded in) and risk-tiered autonomy (config.autonomy); an effective risk tier ≥security.review.humanSignOffMinTier(default 4) SHALL wait for a named human security sign-off, and an unresolved security finding SHALL block completion at any tier. - The loop SHALL read and honor the operator's custom instruction docs (
config.customInstructions): every registered doc is read, in order, immediately after loading the config when work on an item starts (and re-read after a context clear). The structured config wins where both speak; no instruction doc can weaken the loop's gates (security, paper trail, reviews, autonomy) — such instructions are ignored and the conflict logged, fail-closed. A missing doc is handled percustomInstructions.onMissing(defaultwarn). - The loop SHALL manage its context window by checkpoint-then-reset (
config.contextManagement): a reset (clear or compact) is always preceded by a checkpoint —tasks.mdcheckmarks current, an execution-log entry with a concrete next step, the phase label in sync, WIP committed or noted. - WHEN the phase advances across a locked artifact (most importantly tasks-breakdown → implementation) THEN the loop SHALL reset per
contextManagement.phaseBoundary(defaultclear) and derive the next phase's work from the checked-in artifacts, not the conversation. - WHEN a task in the DAG completes THEN the loop SHALL checkpoint and reset per
contextManagement.taskBoundary(defaultcompact); mid-task only compaction is permitted (midTask), never clearing. Headless sessions reset by ending at the boundary and resuming fresh via the execution log. - A work item may be delivered by several PRs. WHEN more than one PR delivers a work item (a spec PR then an implementation PR, a stacked series, a follow-up after review, one PR per repository) THEN the loop SHALL label each of them for routing and list all of them in the execution log's Pull requests table, and
finish-tasksSHALL require every listed PR to be merged or closed before the work item is marked complete — one PR merging is not the work item ending (issue-101).
Design
reference/workflow.md · reference/context.md · reference/instructions.md · reference/security.md · SKILL.md · architecture § the loop
History
| Work item | What changed | Links |
|---|---|---|
| issue-101 | The execution log tracks a list of the PRs delivering a work item; each is labelled for routing and all must be merged/closed before finish-tasks completes the item | spec, decision-039, issue |
| issue-59 | Added per-installation custom instruction docs the loop reads and honors (customInstructions config, onboarding group, precedence rules) | spec, decision-029 |
| issue-48 | Added checkpoint-then-reset context-window management (clear at phase boundaries, compact at task boundaries, contextManagement config) | spec, decision-027 |
| issue-47 | Security became a gated concern of every phase: threat-model-lite in requirements, Security design section, security-review gate item, risk-tiered human sign-off (config.security) | spec, decision-026 |
| issue-25 | Added the capability-docs fold-in as a ready-to-ship gate item | spec, decision-020 |
| issue-18 | Design phase gained first-class UI/UX design artifacts | spec, decision-018 |
| issue-17 | Added the optional brainstorming phase and the iterate-until-locked rule as a first-class principle | spec, decision-017 |
| issue-1 | Established the 3-phase Kiro-style spec workflow, phase labels, granular commands and templates (v0) | spec, decision-004, decision-011 |