Page baselines live in the current checkout's .codoop-flow/ui-snapshots/;
configuration defaults to .codoop-flow/codoop_flow.toml with legacy root fallback.
Init inventories pages; ticket checks/reuses relevant baselines for proposals.
Approval never replaces implemented UI. After verification and review, execute
refreshes baselines in the isolated worktree and finish commits them with code
on the ticket branch, without copying them back to the main checkout. Retain old
HTML and mark unavailable captures stale with reasons. HTML does not replace the
ui_capture screenshot gate. See shared rules.
Loop 2 is the second of three nested loops in codoop-flow's Triple-Loop Model. It is a structured, human-driven process for designing deterministic, machine-readable work tickets that an AI coding agent can execute reliably.
What it solves: AI coding agents fail or produce unusable output when given vague or incomplete requirements. Loop 2 provides a forcing function for the human (or product manager) to produce a precise "ticket package" with such fidelity that an autonomous coding engine (Loop 3) can execute it without ambiguity. The loop prevents scope creep, assumption-driven implementation, and unverifiable output.
Position in pipeline: Reads Loop 1 outputs from docs/backlog/ → produces ticket packages in docs/tickets/drafts/ → promotes to docs/tickets/pending/ for Loop 3 to pick up.
Every ticket carries a ticket_type in metadata.json (default feature). The type selects which documents are required, so the flow fits the work:
| Type | For | Required docs | Recommended docs |
|---|---|---|---|
feature (需求单) |
A new capability driven by a business need | module_prd.md + spec.md |
plan.md, todo.md |
fix (修复单) |
Repairing an existing bug/defect | bug_report.md |
plan.md, todo.md |
feature runs the full three-phase flow below. fix is lighter: it skips the PRD and Spec phases and instead captures the defect in bug_report.md (Symptom / Reproduction / Root Cause / Expected Behavior / Scope), then proceeds to task breakdown, metadata inference, validate, and promote. A fix may voluntarily add a spec.md if it touches a contract/data-model change, but it is not required.
codoop-ticket infers the type from your description and scaffolds it immediately; it does not ask for confirmation. If later context shows the type is wrong, it changes the type and regenerates the affected documents. Via CLI, pass it explicitly with --type feature|fix.
In any AI coding tool, say:
/skill codoop-ticket I want to design an e-commerce product search feature with keyword, category, and price range filtering.
The skill orchestrates a PM and Architect with you as director, guiding you through three phases (PRD → Spec → Tasks) and producing a complete ticket package ready for Loop 3.
codoop_flow.toml controls how ticket documents are reviewed:
It also controls the conversation and final document language through
output_language. Any BCP 47 language tag is accepted; "auto" follows the
user's current language.
| Value | Behavior |
|---|---|
"strict" (default) |
Keep the current phase-by-phase review and confirmation flow. |
"one_pass" |
Keep the complete grilling intake, then generate every applicable PRD, Spec, preview, Plan, ToDo, and Metadata file without phase confirmations. The agent infers Metadata values using the existing standards, shows the completed ticket summary, and asks once whether to promote it to pending/. |
If the field is absent, use "strict" for backward compatibility. Both modes
always require explicit confirmation before promotion; one_pass never skips
grilling or auto-promotes a ticket.
The phase gates below describe "strict" mode.
- research and grill —
codoop-ticketreads project context; for a feature, researches comparable products and recommends a project-specific direction; then it loadsgrillingand asks one decision at a time about scope, user intent, and acceptance criteria - context — reads Loop 1 outputs from
docs/backlog/product/,docs/backlog/interface/,docs/backlog/architecture/,docs/backlog/modules/to anchor the ticket in existing product strategy - draft — PM agent writes
module_prd.mdwith business overview, user stories, state diagrams, acceptance criteria - review — you review and confirm "this PRD is good, move to spec phase"
Hard constraint: module_prd.md is 100% pure business language. No database tables, no API fields, no code details.
- trigger — you confirm Phase 1 is done;
codoop-ticketloads/skill spec-driven-development - design — Architect agent writes
spec.mdbased on the confirmedmodule_prd.md - content — includes API contracts (per platform: backend/web/mobile/desktop), data schema field-level, UI interactions and state management, code examples, testing strategy, Always/Ask First/Never boundaries
- preview — for a feature that adds or materially changes a visible screen, primary task flow, or interaction state, generate a self-contained
preview.htmlbefore review and setmetadata.json.visual_previewtotrue. It recreates the existing page, including navigation, layout and surrounding content, then applies the ticket's change with mock data and key clickable interactions. Reuse checked baselines from.codoop-flow/ui-snapshots/; design independently only when no existing interface is available. It is not production code. - review — you review the spec and, when present, the preview; approved feedback is reflected in both before task breakdown
- trigger — you confirm Phase 2 is done;
codoop-ticketloads/skill planning-and-task-breakdown - decompose — spec is decomposed into two files:
plan.md— phased implementation plan with explicit dependencies, architecture decisions, and checkpointstodo.md— atomic checkbox task list (- [ ]), each task ≤100 lines, each touching ≤5 files, with platform prefixes ([backend],[web], etc.)
- reference — skill prompts you to review
/skill definition-of-doneso task acceptance criteria are aligned with project-wide completion standards - review — you review and confirm
After Phase 3, codoop-ticket calls update_metadata_from_docs to automatically infer metadata.json from your spec.md and task files. visual_preview remains true only when the Phase 2 preview was required (and reviewed in "strict" mode); its presence is a blocking promotion requirement. Separately, the skill determines whether delivery should inspect the actual implementation with saved screenshots and UI/UX review (ui_capture). Backend-only, infrastructure, refactoring, and internal-only work keep both off. In "strict" mode, the human reviews or modifies the result before validation; in "one_pass" mode, the agent applies these standards without a separate Metadata confirmation.
- validate —
codoop ticket validate <ticket_id>ensures all required fields are present and filled meaningfully - promote —
codoop ticket promote <ticket_id>moves the ticket fromdrafts/<ticket_id>/topending/<ticket_id>/, waking Loop 3's scheduler
Every ticket is a directory at one of these pipeline stages:
docs/tickets/
drafts/<ticket_id>/ ← being designed (human-facing)
pending/<ticket_id>/ ← design complete, awaiting Loop 3
in_progress/<ticket_id>/ ← Loop 3 is executing
done/<ticket_id>/ ← shipped and archived
failed/<ticket_id>/ ← self-healing exhausted; needs human intervention
Files inside each ticket directory:
| File | Author | Required | Purpose |
|---|---|---|---|
metadata.json |
Auto-inferred; human confirms | Yes | Machine-readable config for Loop 3: ticket type, modules, self-heal budget, preview and UI-capture flags |
module_prd.md |
PM agent + human | Yes for feature |
100% pure-business description — user stories, state flows, acceptance criteria |
spec.md |
Architect agent + human | Yes for feature |
Technical contract — APIs, data schema, UI interactions |
preview.html |
Ticket agent + human | Required when visual_preview is true |
Static HTML prototype for reviewing a ticket-local visual flow and key interactions |
bug_report.md |
Human (+ agent) | Yes for fix |
Defect record — Symptom / Reproduction / Root Cause / Expected Behavior / Scope |
plan.md |
Auto-decomposed + human review | Recommended (both) | Step-by-step implementation plan with phases and checkpoints |
todo.md |
Auto-decomposed + human review | Recommended (both) | Atomic checkbox task list, each ≤100 lines, with platform prefixes |
| Skill | Role |
|---|---|
| codoop-ticket | Main orchestrator. Guides you through all three phases and calls sub-skills. |
| spec-driven-development | Phase 2 (spec design). Can also be invoked standalone. |
| planning-and-task-breakdown | Phase 3 (task breakdown). Can also be invoked standalone. |
| definition-of-done | Reference tool. Not called as an action-producer, but reviewed during Phase 3 to inform acceptance criteria. |
spec-driven-development can be invoked directly when you have a requirement but no spec:
/skill spec-driven-development Based on this PRD, design the technical spec.
planning-and-task-breakdown can be invoked directly when you have a spec but need to break it into tasks:
/skill planning-and-task-breakdown Based on this spec, break it into implementation tasks.
Both work identically in standalone mode as they do when called by codoop-ticket, except the output paths differ (standalone skills use tasks/, integrated skills use the ticket directory).
definition-of-done is referenced (not called) during Phase 3. You read the reference and apply its five-dimension checklist (Correctness, Quality, Integration, Documentation, Ship-readiness) when writing acceptance criteria in todo.md.
Loop 2 has an independent CLI tool codoop-ticket.py that is completely independent of Loop 3's codoop-execute.
All commands can be invoked via:
python3 runtime/codoop-flow/codoop-ticket.py ticket <command> <args>Or directly call the skill in any AI coding tool:
/skill codoop-ticket Design a work ticket for this feature
codoop-ticket ticket init <ticket_id> --config <toml> [--title "..."] [--language auto|zh|en] [--type feature|fix]
Creates docs/tickets/drafts/<ticket_id>/ with:
metadata.jsonstub (placeholder values, includingticket_type)- Scaffold docs per type:
feature→module_prd.md,spec.md,plan.md,todo.md;fix→bug_report.md,plan.md,todo.md
Args:
--title— ticket title (detected for language if--language auto)--language—auto(default, detects CJK →zh, otherwiseen), or explicitzh/en. This affects only the deterministic empty scaffold; the Skill writes final ticket documents usingoutput_languagefromcodoop_flow.toml.--type—feature(default) orfix; selects the scaffold and the required-docs rule--config— path tocodoop_flow.toml
Exit codes: 0 on success, raises FileExistsError if draft already exists.
Validates a draft is ready to promote.
Checks (blocking):
metadata.jsonparses cleanly and satisfies the full schema (all required fields present, correct types, validticket_type)- The type's required docs exist and contain meaningful (non-scaffold, non-empty) content:
feature→module_prd.md+spec.md;fix→bug_report.md preview.htmlexists whenmetadata.json.visual_previewis true
Checks (advisory warnings):
plan.mdandtodo.mdexist and are meaningfully filled
Exit codes: 0 on success, 1 on any blocking error.
Auto-infers metadata.json from the current spec.md (and optionally plan.md/todo.md), writes the result back to disk, and prints it for human review.
Inference logic:
modules— scanned fromspec.mdheaders (## Backend,## Web, etc.) mapped to: backend, web, mobile, desktop
Typically called after Phase 3 is complete, before validating and promoting.
Promotes a draft to pending (ready for Loop 3 pickup).
Internally:
- Calls
validatefirst; fails if any error - Shows the ticket summary (id / title / modules) and asks for interactive confirmation (
--forceskips the prompt) - Moves
docs/tickets/drafts/<ticket_id>/todocs/tickets/pending/<ticket_id>/usingshutil.move - Refuses to clobber existing pending tickets
Human approval is required. pending/ is Loop 3's pickup queue — an unreviewed promote means an agent may start building from an unapproved design. When codoop-ticket (the skill) drives the flow, it must ask the user to confirm before promoting and must not use --force without prior approval.
Output: Path to destination and message that codoop_tools.py pick will pick it up next.
Exit codes: 0 on success, 1 on validation failure, cancelled confirmation, or move failure.
These fields matter for Loop 2:
| Field | Type | Required | Meaning |
|---|---|---|---|
target_repo |
string (path) | Yes | Path to your target git repo. Loop 2 writes ticket directories under <target_repo>/docs/tickets/. |
ticket_design_mode |
string | No | "strict" (default) confirms each design phase; "one_pass" generates the complete ticket package after grilling, then asks once before promotion. |
output_language |
string | No | Any BCP 47 language tag for Skill replies and generated ticket documents; "auto" (default) follows the user's current language. |
user_role |
string | No | "general" |
Every ticket's metadata.json must satisfy this schema:
Required fields:
| Field | Type | Meaning |
|---|---|---|
ticket_id |
string | Identifier matching the directory name (e.g., ticket_001) |
title |
string | Human-readable ticket title |
modules |
list[string] | Which platform modules this ticket touches: backend, web, mobile, desktop |
Optional fields:
| Field | Type | Default | Meaning |
|---|---|---|---|
ticket_type |
string | "feature" |
"feature" (需求单) or "fix" (修复单). Selects required docs in Loop 2 and the commit prefix (feat/fix) in Loop 3 |
coding_engine |
string or null | null | Which AI tool for this ticket: claude, codex, cursor. If absent, uses global default. |
max_healing_attempts |
int | 3 | Maximum self-healing retries in Loop 3 before moving to failed/ |
visual_preview |
bool | false | Requires preview.html for a user-visible feature before promotion; strict mode also reviews this static prototype, which is separate from runtime verification |
ui_capture |
bool | false | If true, delivery writes screenshots under public/qa-screenshots/; review adds UI/UX personas |
Validation: All required fields must be present with correct types.
During Phase 1 (requirement design), codoop-ticket proactively reads Loop 1's backlog outputs:
docs/backlog/product/— requirements.md, user-journey.md, monetization-plan.mddocs/backlog/interface/— design-system.md (visual-design source of truth)docs/backlog/architecture/— architecture.md, database-schema.sql, openapi.yamldocs/backlog/modules/— per-module detailed designs
This anchors every ticket to the global product strategy rather than inventing in isolation.
The promote command's filesystem move (drafts/ → pending/) is the only handoff mechanism. Loop 3's scheduler polls pending/, picks the oldest ticket, and consumes:
metadata.json— drives scheduler decisions (modules, self-heal budget, ui_capture flag) and records whether a visual preview is part of the ticketmodule_prd.md+spec.md— progressively disclosed to the coding engine at startuppreview.html— read alongside the design docs when present so implementation follows the local visual flowplan.md+todo.md— Loop 3 reads the todo list step-by-step and checks off items as they completepublic/qa-screenshots/— created at runtime during UI-ticket delivery
The ticket directory travels with the ticket through all stages: pending/ → in_progress/ → done/ (or failed/), preserving the full design record alongside implementation artifacts.
Loop 2 introduces the human to the project-wide Definition of Done (DoD) — a fixed five-dimension checklist that every task must satisfy before being considered complete:
- Correctness — acceptance criteria met, runtime-verified, tests prove the change, no regressions, edge cases handled
- Quality — intent-clear naming, no duplicated logic, no dead code, no unrelated refactors, linting passes
- Integration — works with the full system, migrations and config handled, backward compatibility considered
- Documentation — public interfaces documented, architectural decisions recorded, timeless language
- Ship-readiness — security reviewed, observability in place, rollback path exists, human approval completed
Key distinction from acceptance criteria: Acceptance criteria in todo.md answer "did we build this correctly?" and vary per task. DoD answers "can we confidently ship this?" and is fixed across all tasks and tickets.
During Phase 3, you are encouraged to reference /skill definition-of-done so task acceptance criteria are strong enough to satisfy the project-wide standard.
/skill spec-driven-development I have this PRD, design the technical spec.
The skill guides you through four phases (Specify → Plan → Tasks → Implement), producing tasks/spec.md, tasks/plan.md, tasks/todo.md for standalone use. All six core spec areas are covered: Objective, Commands, Project Structure, Code Style, Testing Strategy, Boundaries.
/skill planning-and-task-breakdown I have this spec, break it into implementable tasks.
The skill reads the spec, builds a dependency graph, slices vertically (feature-by-feature), writes tasks with acceptance criteria + verification + dependency + file list + size estimate, and saves to tasks/plan.md and tasks/todo.md. It enforces the rule: no code is written during planning.
- Deterministic Input for Deterministic Output — High fidelity requirements enable Loop 3 to execute reliably without guessing.
- Selectable Collaboration Mode —
"strict"confirms each PRD → Spec → Tasks phase;"one_pass"retains grilling and produces the complete package before one promotion decision. - Type-Fit Flow —
featuretickets run the full PRD → Spec → Tasks flow;fixtickets use a lighterbug_report.mdflow. The skill infers and chooses the type automatically. - Metadata Auto-Inference — Loop 2 automatically infers
metadata.jsonfrom spec content, saving humans from manual, error-prone configuration. - Dual-Mode Sub-Skills — spec-driven-development and planning-and-task-breakdown work both standalone and as integrated phases of codoop-ticket.
- No Code Written — Loop 2 is pure documentation. Code is written only in Loop 3.