Cobb

cobb

A single skill for ongoing product development. Route a request to the right phase, then execute that phase under the shared guardrails below.

The full flow is: prd → design (optional, UI/UX-heavy work) → implement → commit (commit mode, followed by automatic review) → selected fixes/suggestions and re-review when needed → commit (finalise mode) → compact (periodic). context is captured inline throughout, not as a separate step.

Default delivery order: implement -> commit -> review -> finalise. Review the stable atomic branch diff, not a moving pre-commit worktree.

Progressive Disclosure Contract

This file is navigation, not the full operating manual. On activation:

1. If AGENTS.md exists in the repo root and has not already been read in this context, read it first — it carries repo-wide instructions and points to SOUL.md (voice) and MEMORY.md (lessons). Read it once per session, not per phase.
2. Load only the selected phase reference from Dispatch.
3. For nested routers, load the router first, then only the selected child reference.
4. Load templates, examples, and secondary references only when the selected reference explicitly requires them for the current task.
5. For multi-phase requests, complete one phase at a time and load the next phase reference only when that phase begins.

Dispatch

Parse the first token of the args and route to the matching phase. Load only that phase's reference file, then execute it.

Routing rules

1. If the first token matches a phase, load that reference and execute it; pass the rest of the args through as the phase's input.
2. If no token matches but intent is clear from the request (e.g. "write a prd for X" → prd, "review my branch" → review), infer the phase, state which phase you picked in one line, then proceed.
3. If intent is ambiguous, fall back to the bare /cobb behaviour below.
4. design is itself a router: /cobb design ui selects the ui mode inside references/design.md.

Bare /cobb (no subcommand)

Do not execute any phase. Instead:

1. Read tasks/ — list active PRDs (f-##, name, Status, Priority) and check git branch/commit state.
2. Print the subcommand menu (the dispatch table above) so the user sees the options.
3. Render the phase recommended from repository state as option 0 Recommended and the remaining phases as 1..N (do not repeat the recommended phase in 1..N). Do not require the user to type a command name.
4. Recommend the single next phase based on state, for example:
   • no tasks/context.md or no PRDs → "start with /cobb prd"
   • a Status: ready PRD with no feature branch → "/cobb implement <prd>"
   • feature branch ahead of base with uncommitted changes → "/cobb commit (review runs after the final clean commit group)"
   • all commits reviewed and clean on a feature branch → "/cobb commit finalise (it trusts the completed review and merges)"
   • all commits done but not yet reviewed → "/cobb review, then /cobb commit finalise"
   • tasks/context.md long/noisy → "/cobb compact"
5. Wait for the user's option number or explicit subcommand before acting.

Shared Guardrails (apply to every phase)

• Number every closed choice. Whenever a response ends by asking the user to choose, confirm, approve, continue, stop, or select a next step, provide numbered reply options. Accept the number alone. Use open-ended input only when honest answers cannot be bounded without losing essential information.
• Option 0 is the recommendation. In every numbered menu, render exactly one recommended choice as 0 Recommended: with a brief evidence-based reason (repository evidence, safety, best practice, critical reasoning), and render each alternative once as 1..N. Never repeat the 0 option inside 1..N. Accept default as an alias for 0. The recommendation may be to stop, investigate, split, or defer; do not mechanically recommend proceeding. Wherever a phase reference says "mark one Recommended", it means render that choice as option 0. Sole exception: commit finalise uses per-field codes such as 1A 2B, where 0/default selects the recommended complete bundle.
• Show questionnaire progress. Before a one-question-at-a-time interview, explore enough context to build the question queue and state the total. Label every prompt Question X of Y. If a new answer creates or removes dependent questions, announce the revised total and why before continuing.
• Context capture is built-in. Update tasks/context.md inline whenever durable decisions, risks, or gotchas emerge, except in read-only review, which reports proposed entries for the next implement/finalise commit. Context updates include a README freshness check for affected areas. See references/context-log.md for what/where to record.
• Base branches. The base-branch list is main, master, dev, develop, trunk, plus names declared under Repo conventions in tasks/context.md. Every phase that resolves a comparison base or merge target uses this list.
• Handoff-friendly. Assume a junior dev (or another AI) picks this up later. Plain language, explicit edge cases, no hidden assumptions.
• Never claim untested success. Do not say tests/checks/builds passed unless you actually ran them; if you didn't run it, say so.
• Status block. End every standalone phase reply with:
  • Files changed: created/updated files
  • Key decisions: assumptions or choices made (if any)
  • Next step: recommended next phase or action
  • If the next step requires a user decision, follow it immediately with numbered options and one Recommended option.

Files cobb manages

• tasks/f-##-<slug>.md — one PRD per feature, with Status (draft | ready), Priority (P0–P3), Type (feat | fix | chore), and a progress checklist.
• tasks/context.md — durable project state, key decisions, milestones, gotchas (handoff record).
• tasks/archive/ — completed PRDs moved here during commit finalise (same filename, no rename).

References

The Dispatch table above is the single routing source for phase files. Two shared references are loaded by phases rather than dispatch:

• references/tdd.md — behavioural testing contract; loaded by prd/implement when applicable.
• references/commit-review.md — post-review action tree; loaded only after a review result.

Design child references (references/design/*.md) are selected inside references/design.md, and templates (references/templates/*.md) load only when the active phase explicitly asks for them — each phase file names its own.