cc-pipeline 0.6.7 → 0.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-pipeline",
-  "version": "0.6.7",
+  "version": "0.7.2",
   "description": "Autonomous Claude Code pipeline engine. Install into any repo, write a BRIEF.md, and let Claude build your project phase by phase.",
   "type": "module",
   "bin": {

package/src/agents/claudecode.ts

@@ -47,7 +47,8 @@ export class ClaudeCodeAgent extends BaseAgent {
 
     const appendOutput = (line: string) => {
       try {
-        appendFileSync(outputPath, line + '\n', 'utf-8');
+        const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
+        appendFileSync(outputPath, `[${ts}] ${line}\n`, 'utf-8');
         lastActivityMs = Date.now();
       } catch (_) {}
     };

package/src/config.ts

@@ -19,6 +19,7 @@ export interface PipelineConfig {
   name: string;
   version: number;
   phasesDir: string;
+  maxPhases: number;
   steps: StepConfig[];
   usageCheck: { when: string };
   usageLimits: { sessionBudgetUSD: number; weeklyBudgetUSD: number };
@@ -45,6 +46,7 @@ export function loadConfig(projectDir: string): PipelineConfig {
     name: raw.name || 'Unnamed Pipeline',
     version: raw.version || 1,
     phasesDir: raw.phases_dir || 'docs/phases',
+    maxPhases: raw.max_phases ?? 100,
     steps: [],
     usageCheck: raw.usage_check || { when: 'phase_boundary' },
     usageLimits: {

package/src/engine.ts

@@ -10,7 +10,7 @@ import { CodexAgent } from './agents/codex.js';
 import { pipelineEvents } from './events.js';
 import { computeUsagePercentages } from './usage.js';
 
-const MAX_PHASES = 20;
+const DEFAULT_MAX_PHASES = 100;
 
 /**
  * Main pipeline engine loop.
@@ -21,7 +21,7 @@ const MAX_PHASES = 20;
  * - Print banner
  * - Loop through phases, executing steps
  * - Check for PROJECT COMPLETE in reflections
- * - Handle phase limits and MAX_PHASES
+ * - Handle phase limits and maxPhases
  * - Signal handling for clean shutdown
  */
 export async function runEngine(projectDir: string, options: any = {}) {
@@ -40,6 +40,7 @@ export async function runEngine(projectDir: string, options: any = {}) {
 
   // Load config
   const config = loadConfig(projectDir);
+  const maxPhases = config.maxPhases ?? DEFAULT_MAX_PHASES;
 
   // Derive current state
   const state = getCurrentState(logFile);
@@ -110,21 +111,7 @@ export async function runEngine(projectDir: string, options: any = {}) {
 
     const phaseLimit = options.phases || 0;
 
-    while (phase <= MAX_PHASES) {
-      // Check for PROJECT COMPLETE
-      if (phase > 1) {
-        const prevPhaseDir = join(projectDir, config.phasesDir, `phase-${phase - 1}`);
-        const reflectFile = join(prevPhaseDir, 'REFLECTIONS.md');
-        if (existsSync(reflectFile)) {
-          const firstLine = readFileSync(reflectFile, 'utf8').split('\n')[0];
-          if (firstLine && /PROJECT COMPLETE/i.test(firstLine)) {
-            appendEvent(logFile, { event: 'project_complete', phase: phase - 1 });
-            log(`PROJECT COMPLETE detected in phase ${phase - 1} reflections.`);
-            return;
-          }
-        }
-      }
-
+    while (phase <= maxPhases) {
       pipelineEvents.emit('phase:start', { phase });
 
       // Execute all steps in phase
@@ -179,6 +166,20 @@ export async function runEngine(projectDir: string, options: any = {}) {
           }
         }
 
+        // After GROOM step: check if it signaled project complete
+        if (stepDef.name === 'groom' && lastResult === 'ok') {
+          const groomFile = join(projectDir, config.phasesDir, `phase-${phase}`, 'GROOM.md');
+          if (existsSync(groomFile)) {
+            const groomContent = readFileSync(groomFile, 'utf8');
+            if (/PROJECT COMPLETE/i.test(groomContent)) {
+              appendEvent(logFile, { event: 'project_complete', phase });
+              log(`PROJECT COMPLETE — all Epics finished (detected by GROOM in phase ${phase}).`);
+              pipelineEvents.emit('phase:done', { phase });
+              return;
+            }
+          }
+        }
+
         // If still failed after all retries, stop the pipeline
         if (lastResult === 'error' && stepDef.agent !== 'bash' && !stepDef.continueOnError) {
           logErr(`\n  Step "${stepDef.name}" failed after 3 attempts. Pipeline stopped.`);
@@ -221,7 +222,7 @@ export async function runEngine(projectDir: string, options: any = {}) {
       }
     }
 
-    log(`Hit MAX_PHASES (${MAX_PHASES}). Stopping.`);
+    log(`Hit max phases (${maxPhases}). Stopping.`);
   } finally {
     cleanup();
   }

package/src/prompts.ts

@@ -1,4 +1,4 @@
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 
 /**
@@ -41,6 +41,42 @@ export function generatePrompt(projectDir: string, config: any, phase: number, p
   }
   prompt = prompt.replace(/\{\{BRIEF\}\}/g, briefContent);
 
+  // Substitute {{NEXT}} — contents of previous phase's NEXT.md (if exists)
+  let nextContent = '';
+  if (phase > 1) {
+    const prevNextPath = join(projectDir, config.phasesDir, `phase-${phase - 1}`, 'NEXT.md');
+    if (existsSync(prevNextPath)) {
+      nextContent = readFileSync(prevNextPath, 'utf-8');
+    }
+  }
+  prompt = prompt.replace(/\{\{NEXT\}\}/g, nextContent);
+
+  // Substitute {{EPIC}} — contents of the Epic file referenced in NEXT.md
+  // Parses "Epic: epic-N-name.md" from NEXT content to find the file
+  let epicContent = '';
+  if (nextContent) {
+    const epicMatch = nextContent.match(/^Epic:\s*(.+\.md)/m);
+    if (epicMatch) {
+      const epicPath = join(projectDir, 'docs', 'epics', epicMatch[1].trim());
+      if (existsSync(epicPath)) {
+        epicContent = readFileSync(epicPath, 'utf-8');
+      }
+    }
+  }
+  prompt = prompt.replace(/\{\{EPIC\}\}/g, epicContent);
+
+  // Substitute {{ALL_EPICS}} — concatenated contents of all docs/epics/*.md files
+  let allEpics = '';
+  const epicsDir = join(projectDir, 'docs', 'epics');
+  if (existsSync(epicsDir)) {
+    const files = readdirSync(epicsDir).filter(f => f.endsWith('.md')).sort();
+    allEpics = files.map(f => {
+      const content = readFileSync(join(epicsDir, f), 'utf-8');
+      return `--- ${f} ---\n${content}`;
+    }).join('\n\n');
+  }
+  prompt = prompt.replace(/\{\{ALL_EPICS\}\}/g, allEpics);
+
   // Substitute {{FILE_TREE}} - placeholder for now
   const fileTree = '(file tree generation not yet implemented)';
   prompt = prompt.replace(/\{\{FILE_TREE\}\}/g, fileTree);

package/src/state.test.ts

@@ -357,6 +357,46 @@ test('deriveResumePoint: advance to next phase after last step', () => {
   rmSync(tempDir, { recursive: true });
 });
 
+test('getCurrentState: project_complete returns done state (same as phase_complete)', () => {
+  const tempDir = mkdtempSync(join(tmpdir(), 'cc-pipeline-test-'));
+  const logFile = join(tempDir, 'pipeline.jsonl');
+
+  const events = [
+    { event: 'step_start', phase: 34, step: 'groom', ts: '2025-01-01T00:00:00Z' },
+    { event: 'step_done', phase: 34, step: 'groom', status: 'ok', ts: '2025-01-01T00:01:00Z' },
+    { event: 'project_complete', phase: 34, ts: '2025-01-01T00:02:00Z' },
+  ];
+  writeFileSync(logFile, events.map(e => JSON.stringify(e)).join('\n') + '\n', 'utf8');
+
+  const state = getCurrentState(logFile);
+
+  assert.strictEqual(state.phase, 34);
+  assert.strictEqual(state.step, 'done');
+  assert.strictEqual(state.status, 'complete');
+
+  rmSync(tempDir, { recursive: true });
+});
+
+test('deriveResumePoint: project_complete advances to next phase first step', () => {
+  const tempDir = mkdtempSync(join(tmpdir(), 'cc-pipeline-test-'));
+  const logFile = join(tempDir, 'pipeline.jsonl');
+
+  const events = [
+    { event: 'step_start', phase: 34, step: 'spec', ts: '2025-01-01T00:00:00Z' },
+    { event: 'step_done', phase: 34, step: 'spec', status: 'ok', ts: '2025-01-01T00:01:00Z' },
+    { event: 'project_complete', phase: 34, ts: '2025-01-01T00:02:00Z' },
+  ];
+  writeFileSync(logFile, events.map(e => JSON.stringify(e)).join('\n') + '\n', 'utf8');
+
+  const resume = deriveResumePoint(logFile, mockSteps);
+
+  // project_complete is treated as phase_complete — next run starts fresh in the next phase
+  assert.strictEqual(resume.phase, 35);
+  assert.strictEqual(resume.stepName, 'spec');
+
+  rmSync(tempDir, { recursive: true });
+});
+
 test('deriveResumePoint: handles unknown step by starting from beginning', () => {
   const tempDir = mkdtempSync(join(tmpdir(), 'cc-pipeline-test-'));
   const logFile = join(tempDir, 'pipeline.jsonl');

package/src/state.ts

@@ -75,7 +75,7 @@ export function getCurrentState(logFile: string): { phase: number; step: string;
   }
 
   // Find last relevant event
-  const relevantEvents = ['step_start', 'step_done', 'step_skip', 'phase_complete'];
+  const relevantEvents = ['step_start', 'step_done', 'step_skip', 'phase_complete', 'project_complete'];
   const lastEvent = events
     .filter(e => relevantEvents.includes(e.event))
     .pop();
@@ -98,6 +98,11 @@ export function getCurrentState(logFile: string): { phase: number; step: string;
     case 'step_skip':
       return { phase, step, status: 'complete' };
     case 'phase_complete':
+    case 'project_complete':
+      // Treat project_complete the same as phase_complete — resume starts at next phase.
+      // This ensures that if the user adds new Epics after completion and reruns, the
+      // engine advances to the next phase and runs groom fresh rather than resuming
+      // mid-phase after the groom step.
       return { phase, step: 'done', status: 'complete' };
     default:
       return { phase: 1, step: 'pending', status: 'ready' };

package/templates/CLAUDE.md

@@ -62,6 +62,37 @@ Phase outputs are saved to `docs/phases/phase-N/`.
 
 The pipeline stops automatically when the project is complete (`PROJECT COMPLETE` in REFLECTIONS.md).
 
+## Adding New Epics
+
+The pipeline works through `docs/epics/` one Epic at a time. When all Epics are
+complete the pipeline stops. To continue development, add a new Epic and run again.
+
+**Epic files** live at `docs/epics/epic-N.md` where N is the next number in sequence.
+Check what exists and increment: if `epic-3.md` is the last one, create `epic-4.md`.
+
+**Minimum viable Epic** — the pipeline's groom step will fill in research and detail,
+so you only need to provide intent:
+
+```markdown
+# Epic N: [Short name]
+
+## Goal
+[One paragraph: what the user can do when this Epic is complete.
+ Must be user-testable — a real capability, not an infrastructure layer.]
+
+## Acceptance Criteria
+- [ ] [Specific, observable thing a user can do or see]
+- [ ] [Another testable outcome]
+```
+
+**Rules for good Epics:**
+- Each Epic is a vertical slice — the user can test and get value from it independently
+- Avoid infrastructure Epics ("set up the database", "add an API layer") — frame around user actions instead
+- Size them to feel like 2–4 phases of work; the groom step will flag if it seems too large
+- One Epic at a time is fine — you don't need to plan the whole future upfront
+
+Once the file exists, just run `npx cc-pipeline run` and the pipeline picks it up automatically.
+
 ## Customizing the Pipeline
 
 See `.pipeline/CLAUDE.md` for full configuration docs — how to edit workflow steps, change agents/models, customize prompts, and add new steps.

package/templates/pipeline/prompts/groom.md

@@ -0,0 +1,113 @@
+# Epic Grooming
+
+You are the Groom Agent. Your job is to ensure a groomed Epic is ready
+for this phase. You operate in one of three modes:
+
+## Context — Read These First
+
+1. **Project Brief**: `BRIEF.md` — the immutable north star
+2. **Previous NEXT.md**: {{NEXT}}
+3. **All existing Epics**: Read every file in `docs/epics/` (if the directory exists)
+4. **STATUS.md** (if it exists) — what has been built so far
+
+Current phase: {{PHASE}}
+
+## Determine Your Mode
+
+> **Always scan `docs/epics/` before deciding.** Read every file there.
+> A "draft" Epic has a Goal + Acceptance Criteria but an empty or missing
+> `## Research & Decisions` section. If ANY draft Epic exists — even if
+> NEXT.md says "Next: none" or is empty — treat this as Mode 2 (Transition).
+> Only write PROJECT COMPLETE when you have confirmed zero draft Epics remain.
+
+### Mode 1: Bootstrap (Phase 1, no Epics exist)
+
+If `docs/epics/` doesn't exist or is empty:
+
+1. Read BRIEF.md thoroughly
+2. Decompose the project into Epics — each one a vertical slice of
+   user-testable value. NOT architectural layers.
+   - WRONG: "Epic 1: Database setup", "Epic 2: API layer"
+   - RIGHT: "Epic 1: User can sign up and log in", "Epic 2: User can create and view dashboards"
+3. Create `docs/epics/` directory
+4. Write ALL Epics as draft stubs (Goal + Acceptance Criteria only):
+   ```markdown
+   # Epic N: [Name]
+
+   ## Goal
+   [What the user can do when this Epic is complete]
+
+   ## Acceptance Criteria
+   - [ ] [Testable outcome 1]
+   - [ ] [Testable outcome 2]
+   ```
+5. For Epic 1 ONLY — do internet research scoped to its specific problem
+   space. Populate its `## Research & Decisions` section with findings:
+   libraries chosen, architectural decisions, patterns to follow.
+6. Refine Epic 1's Acceptance Criteria based on research.
+7. Write `docs/epics/epic-1-[name].md` as the fully groomed version.
+
+Size guidance: An Epic is the **smallest piece of functionality where a user
+can open the app, see something meaningful, and confirm it works** — even if
+it's incomplete by the final product's standards. It doesn't need to be fully
+functional end-to-end; it just needs to be real enough that a human can look
+at it and say "yes, that's the thing." Rendering exists without interaction,
+a form exists without validation, a list exists without editing — these are
+all valid Epics. The key question is: *can a user perceive and evaluate this?*
+If yes, it's a good Epic boundary. If it's invisible infrastructure or only
+makes sense in combination with something else, keep splitting or reframe it
+around what the user will actually see.
+
+Phases then break the Epic into even smaller implementation steps — "draw the
+container", "populate it with data", "wire up the interaction" — each one a
+focused build task within the Epic's visible slice.
+
+### Mode 2: Transition (previous Epic marked complete)
+
+If the previous phase's NEXT.md says `Status: complete`:
+
+1. Read Brief + all existing Epics to understand context
+2. Find the next draft Epic (has Goal + Acceptance Criteria but no
+   Research & Decisions section, or the section is empty)
+3. Do internet research scoped to that Epic's specific problem space
+4. Populate its `## Research & Decisions` section
+5. Refine its Acceptance Criteria based on research
+6. If no draft Epics remain and nothing new can be derived from Brief:
+   - Write "PROJECT COMPLETE" to `docs/phases/phase-{{PHASE}}/GROOM.md`
+   - You're done. The pipeline will detect this and stop.
+
+### Mode 3: Skip (current Epic is in-progress)
+
+If the previous phase's NEXT.md says `Status: in-progress`:
+
+The current Epic is already groomed and work continues on it.
+Write a brief note to `docs/phases/phase-{{PHASE}}/GROOM.md`:
+
+```markdown
+# Groom: Phase {{PHASE}}
+
+Skipped — Epic [name] is in-progress and already groomed.
+```
+
+Then stop. Do not modify any Epic files.
+
+## Output
+
+Write to `docs/phases/phase-{{PHASE}}/GROOM.md` with a summary of
+what you did (which mode, what Epics were created/groomed, or why you skipped).
+
+For Bootstrap and Transition modes, include a line like:
+```
+Expected phases for Epic 1: [your estimate]
+```
+This tells the Spec Writer how much to take on per phase. Epics can span
+many phases — there is no upper limit. Estimate honestly.
+
+## Rules
+
+- Each Epic MUST be a vertical slice — user-testable, standalone value
+- Never create infrastructure-only Epics
+- Only groom ONE Epic per phase (the next one in sequence)
+- Don't modify already-completed Epics
+- The Brief is immutable — read it, don't edit it
+- Epic filenames: `epic-N-short-name.md` (e.g., `epic-1-auth.md`)

package/templates/pipeline/prompts/next.md

@@ -0,0 +1,54 @@
+# Phase Steering — NEXT
+
+You are the Steering Agent. Your ONLY job is to write a short pointer
+telling the next phase which Epic to work on and what its current status is.
+
+You do NOT plan, decompose, or make implementation decisions. You only point.
+
+## Context — Read These First
+
+1. **Current Epic**: Find which Epic this phase worked on by reading
+   `docs/phases/phase-{{PHASE}}/SPEC.md` (it references the Epic)
+2. **That Epic's file** in `docs/epics/` — check its Remaining Work section
+3. **REFLECTIONS.md**: `docs/phases/phase-{{PHASE}}/REFLECTIONS.md`
+4. **STATUS.md** (if it exists)
+5. **All Epics**: List `docs/epics/` to know what exists
+
+Current phase: {{PHASE}}
+
+## Write NEXT.md
+
+Output to `docs/phases/phase-{{PHASE}}/NEXT.md`.
+
+### If the current Epic still has Remaining Work:
+
+```
+Epic: [filename, e.g. epic-1-auth.md]
+Status: in-progress
+Focus: [Brief summary of what remains — pulled from Epic's Remaining Work section]
+```
+
+### If the current Epic's Remaining Work is empty (all criteria met):
+
+```
+Epic: [filename of completed epic]
+Status: complete
+Next: [filename of next draft epic, e.g. epic-2-dashboard.md]
+Note: All acceptance criteria met. No carry-over.
+```
+
+If no next draft Epic exists, write:
+```
+Epic: [filename of completed epic]
+Status: complete
+Next: none
+Note: All Epics complete. GROOM will verify on next phase.
+```
+
+## Rules
+
+- NEXT.md is 3-5 lines. Never longer.
+- Never decompose work or suggest implementation approaches.
+- Never modify Epic files — that's REFLECT's job.
+- One Epic per phase, always. If the current Epic is done, point to the next draft.
+- "Draft" means: has Goal + Acceptance Criteria but Research & Decisions is empty or missing.

package/templates/pipeline/prompts/reflect.md

@@ -1,6 +1,7 @@
 # Phase Reflection
 
-You are a Reflection Agent. Your job is to look backward at what happened in this phase AND look forward to inform the next phase. This document gets fed into the next phase's Spec Writer — make it count.
+You are a Reflection Agent. Your job is to look backward at what happened
+in this phase. You do NOT look forward — that's the NEXT step's job.
 
 ## Context — Read These First
 
@@ -9,62 +10,56 @@ You are a Reflection Agent. Your job is to look backward at what happened in thi
 3. **RESEARCH.md**: `docs/phases/phase-{{PHASE}}/RESEARCH.md` — what the codebase looked like before
 4. **REVIEW.md**: `docs/phases/phase-{{PHASE}}/REVIEW.md` — what the reviewers found
 5. **Project Brief**: `BRIEF.md` — the full project goals
+6. **Current Epic**: Find which Epic this phase worked on from the SPEC, then read
+   that Epic file in `docs/epics/`
 
 Current phase: {{PHASE}}
 
 Also run `git log --oneline -15` to see what actually changed.
 
-## Write the Reflection
+## Task 1: Write the Reflection
 
 Output to `docs/phases/phase-{{PHASE}}/REFLECTIONS.md`:
 
-If ALL goals in BRIEF.md are now complete, write `PROJECT COMPLETE` as the very first line.
-
 ```markdown
 # Reflections: Phase {{PHASE}}
 
-## Looking Back
-
-### What Went Well
+## What Went Well
 - [Thing that worked, with evidence]
 - [Process that was effective]
-- [Decision that paid off]
 
-### What Didn't Work
+## What Didn't Work
 - [Problem encountered]: [what happened and why]
 - [Bad assumption]: [what we got wrong]
 
-### Spec vs Reality
+## Spec vs Reality
 - **Delivered as spec'd**: [list items completed per SPEC]
 - **Deviated from spec**: [what changed and why]
 - **Deferred**: [what was in scope but got pushed out, and why]
 
-### Review Findings Impact
+## Review Findings Impact
 - [Key finding from REVIEW.md]: [how it was addressed]
-- [Test gap identified]: [how it was fixed]
-
-## Looking Forward
-
-### Recommendations for Next Phase
-- [Specific recommendation based on what we learned]
-- [Pattern to continue or change]
-- [Risk to watch out for]
-
-### What Should Next Phase Build?
-[Based on BRIEF.md remaining goals, what's the most logical next phase?
-Be specific about scope and priorities.]
 
-### Technical Debt Noted
+## Technical Debt
 - [Shortcut taken that needs future attention]: `file:line`
 - [Known issue deferred]: [description]
-
-### Process Improvements
-- [What to do differently in the next phase's workflow]
 ```
 
-## Guidelines
-- **Be honest** — don't sugarcoat failures. They're the most valuable part.
-- **Be specific** — "it was slow" is useless. "Research step missed the existing helper in utils/" is useful.
-- **Be actionable** — every observation should suggest what to do differently.
-- **The forward look is critical** — the next phase's Spec Writer reads this. Give them what they need.
+## Task 2: Update the Epic's Remaining Work
+
+After writing REFLECTIONS.md, update the current Epic file in `docs/epics/`:
 
+1. Read the Epic's `## Acceptance Criteria` — check off any that are now met
+2. Update `## Completed Work` — add a line for this phase:
+   `- Phase {{PHASE}}: [brief summary of what was delivered]`
+3. Update `## Remaining Work`:
+   - List specific, actionable items that were deferred, partially done, or out of scope
+   - If everything is done, clear this section (empty = Epic complete)
+4. Do NOT modify the Epic's Goal, Research & Decisions, or Acceptance Criteria text
+   (you may check off criteria, but don't rewrite them)
+
+## Guidelines
+- **Be honest** — don't sugarcoat failures
+- **Be specific** — "Research step missed the existing helper in utils/" not "it was slow"
+- **Be actionable** — every observation should suggest what to do differently
+- **Backward only** — do NOT write recommendations for next phase. That's NEXT's job.

package/templates/pipeline/prompts/spec.md

@@ -1,13 +1,18 @@
 # Write Phase Spec
 
-You are the Spec Writer. Your job is to take the overall project vision and break this specific phase into a clear, bounded specification.
+You are the Spec Writer. Your job is to scope this phase's work within
+a single Epic — the one identified by NEXT.md (or GROOM for phase 1).
 
 ## Context — Read These First
 
-1. **Project Brief**: `BRIEF.md` — the big picture and goals
-2. **Previous Reflections**: `{{PREV_REFLECTIONS}}` — lessons and forward-look from last phase (if exists)
-3. **Any existing phase specs in docs/phases/** — for continuity and avoiding duplication
-4. **Reference Documentation**: If `BRIEF.md` contains a `## Reference Documentation` section, read every file listed there before writing the spec
+1. **NEXT.md from previous phase**: {{NEXT}}
+   - If empty (phase 1): Read `docs/phases/phase-{{PHASE}}/GROOM.md` to find which Epic was groomed
+2. **The Epic file**: Based on NEXT.md's `Epic:` field (or GROOM output),
+   read that specific file from `docs/epics/`. This is your primary input.
+3. **Project Brief**: `BRIEF.md` — the big picture (read for context, but scope from Epic)
+4. **Previous Reflections**: `{{PREV_REFLECTIONS}}` — lessons from last phase (if exists)
+5. **Any existing phase specs in docs/phases/** — for continuity and avoiding duplication
+6. **Reference Documentation**: If `BRIEF.md` contains a `## Reference Documentation` section, read every file listed there before writing the spec
 
 Current phase: {{PHASE}}
 
@@ -115,10 +120,32 @@ Example of RIGHT phase breakdown:
 
 Each phase should be testable end-to-end: "Can a user do X?" If the answer involves infrastructure that doesn't connect to a user action, it's scoped wrong.
 
+## Phase Sizing — Read This Carefully
+
+A phase should be **small enough that a single agent can finish it cleanly in
+one session**. Epics can span many phases — that's fine. Your job is to take
+a small, clean slice from wherever the Epic currently stands.
+
+**How to scope this phase:**
+1. Read the Epic's Acceptance Criteria
+2. Pick **1–2 criteria** — the smallest coherent thing that's user-testable
+3. Everything else goes in "Out of Scope" — it stays in the Epic for future phases
+4. If NEXT.md has a `Focus:` line, that is your scope. Don't expand it.
+
+**Signs you've scoped too much:**
+- Your "In Scope" list has more than 3 items
+- You're delivering the entire Epic Goal in one phase
+- The spec reads like a full feature launch rather than a single user story
+
+When in doubt, cut scope. A phase that delivers one thing completely is better
+than a phase that delivers three things partially.
+
 ## Guidelines
 - **Be bounded**: Every spec must have clear "Out of Scope"
 - **Be verifiable**: Every acceptance criterion must be testable
 - **Vertical slices**: Every phase delivers a user-visible feature, not a horizontal layer
 - **Learn from the past**: If reflections exist, incorporate them explicitly
 - **Don't over-specify HOW**: The spec says WHAT, the plan says HOW
+- **One phase ≠ one Epic**: An Epic spans multiple phases. Scope a slice, not the whole.
+- **Epic is your boundary**: Never invent requirements outside the Epic's Goal and Acceptance Criteria.
 

package/templates/pipeline/workflow.yaml

@@ -15,6 +15,12 @@ version: 1
 phases_dir: "docs/phases"
 
 steps:
+  - name: groom
+    description: "Bootstrap or groom the next Epic"
+    agent: claudecode
+    prompt: prompts/groom.md
+    output: "GROOM.md"
+
   - name: spec
     description: "Break project vision into phase spec"
     agent: claudecode
@@ -60,11 +66,17 @@ steps:
     test_gate: true
 
   - name: reflect
-    description: "Look back + look forward for next phase"
+    description: "Look back at what happened this phase"
     agent: claudecode
     prompt: prompts/reflect.md
     output: "REFLECTIONS.md"
 
+  - name: next
+    description: "Write steering pointer for next phase"
+    agent: claudecode
+    prompt: prompts/next.md
+    output: "NEXT.md"
+
   - name: status
     description: "Update STATUS.md with phase summary"
     agent: claudecode