Prep Pipeline¶

The prep pipeline transforms your ideas into structured, agent-ready tasks. It's a 4-stage guided process that refines requirements, designs architecture, decomposes work into tasks, and writes them to your task backend.

What Prep Does¶

flowchart LR
    A[Vision] --> B[Triage]
    B --> C[Architect]
    C --> D[Plan]
    D --> E[Bootstrap]
    E --> F[Ready Tasks]

    style A fill:#FFC107
    style B fill:#FF9800
    style C fill:#FF5722
    style D fill:#E91E63
    style E fill:#9C27B0
    style F fill:#4CAF50,color:white

The Full Pipeline¶

Run the entire prep pipeline with one command:

cub prep

This launches an interactive session for each stage sequentially. After each stage completes, run cub prep again to continue to the next stage.

Session-Based Workflow¶

Prep uses sessions to track your progress through the pipeline. Each session stores artifacts in .cub/sessions/{session-id}/:

.cub/sessions/myproject-20260117-143022/
+-- session.json     # Session metadata
+-- triage.md        # Refined requirements
+-- architect.md     # Technical design
+-- plan.jsonl       # Beads-compatible task data
+-- plan.md          # Human-readable plan

Running Individual Stages¶

You can also run each stage independently:

cub triage                  # Stage 1: Requirements refinement
cub architect               # Stage 2: Technical design
cub plan                    # Stage 3: Task decomposition
cub bootstrap               # Stage 4: Initialize tasks

Resuming a Session¶

Resume a specific session:

cub prep --session myproject-20260117-143022

# Or continue the most recent session
cub prep --continue

Managing Sessions¶

List and manage your prep sessions:

cub sessions              # List all sessions
cub sessions show         # Show most recent session details
cub sessions delete ID    # Delete a session

When to Use Prep vs Direct Task Creation¶

Use the prep pipeline when:

• Starting a new project or major feature
• You have a vision document but need to clarify requirements
• You want AI-assisted decomposition into right-sized tasks
• You need technical design before implementation

Create tasks directly when:

• Adding a small feature or bug fix
• Tasks are already well-defined
• Quick experiments or prototypes
• Integrating external issue tracking (GitHub Issues, Jira)

# Direct task creation with beads
bd create "Fix login bug" --type bugfix --priority 1

# Or import from external sources
cub import github://owner/repo/issues/123

Non-Interactive Mode¶

For CI/CD or automated workflows, run prep without interactive prompts:

cub prep --non-interactive --vision VISION.md

Artifacts and Outputs¶

Each stage produces artifacts that feed into the next:

flowchart TD
    subgraph Triage
        T1[VISION.md] --> T2[triage.md]
    end

    subgraph Architect
        T2 --> A1[architect.md]
    end

    subgraph Plan
        T2 --> P1[plan.md]
        A1 --> P1
        P1 --> P2[plan.jsonl]
    end

    subgraph Bootstrap
        P2 --> B1[.beads/issues.jsonl]
        P2 --> B2[PROMPT.md]
        P2 --> B3[AGENT.md]
    end

Prep Status¶

After any stage, prep shows your current progress:

PREP STATUS
Session: myproject-20260117-143022

  [x] Triage    - triage.md
  [x] Architect - architect.md
  [ ] Plan      - pending
  [ ] Bootstrap - pending

Next step: cub plan --session myproject-20260117-143022

Quick Reference¶

Next Steps¶