concepts

Stories

A story is the unit a program decomposes into. Each story becomes a run with its own branch and PR.

What lives on a story row

• story_id — stable id like S-E001-003 (epic + ordinal).
• epic_id — the epic the story rolls up into (E001, E002, ...).
• title — one-line description.
• size — t-shirt size (xs, s, m, l, xl) used by the orchestrator for parallelism heuristics.
• risk — low / med / high; high-risk stories pin to better models per config.yml.
• status — pending, in_progress, complete, failed, blocked, gated, cancelled.
• depends_on — story ids this one waits on.
• branch / parent_branch — branch names once dispatched.
• run_id — the run that implemented this story (null until dispatched).
• failure_class — set on failed; categorises why for downstream verification.

Where stories come from

The program_plan phase writes them. The DAG of dependencies lives in .pipeline/ROADMAP.md; one row per story.

Dispatch order

The iterate phase dispatches a story when every entry in its depends_on has status: complete. With parallelism: 1 (the default) one story runs at a time; setting parallelism: 3 lets up to three ready stories run in parallel — useful when stories touch independent domains.

Reading a story DAG

stories:
  - id: S-E001-001
    title: "Auth: Clerk sign-in routes + session guard"
    epic: E001
    size: m
    risk: low
    depends_on: []
  - id: S-E001-002
    title: "API: /api/me + RBAC scope resolution"
    epic: E001
    size: m
    risk: med
    depends_on: [S-E001-001]
  - id: S-E001-003
    title: "Mobile home tab: scope header + recent runs"
    epic: E001
    size: m
    risk: low
    depends_on: [S-E001-002]