Epic/Stage Setup - Bootstrapping Guide

This skill handles the CREATION of epic/stage/phase workflow structure. For WORKING ON existing epics and stages, see the epic-stage-workflow skill.

When to Use

• Starting a new project that will benefit from phased development with quality gates
• Converting an existing project to use epic/stage tracking
• User explicitly requests "epic workflow", "stage tracking", or "phased development"
• Creating a NEW epic or stage within an existing project
• User asks to "create an epic" or "add a stage"

When NOT to Use

• Single-file scripts or throwaway prototypes
• Projects with fewer than 3 distinct features
• Projects where user explicitly wants ad-hoc development without tracking
• Projects already using a different structured workflow (e.g., GitHub Projects, Jira)
• WORKING ON existing stages - use epic-stage-workflow skill instead

Workflow Structure Overview

Epic (Feature)
  └── Stage (Component/Interaction)
        └── Phase: Design → Build → Refinement → Finalize

Hierarchy

• Epic = Feature (Dashboard, Map, Timeline, etc.)
• Stage = Single component or interaction within that feature
• Phase = Design | Build | Refinement | Finalize

What This Skill Sets Up

When invoked for a new project:

1. Creates epics/ directory for epic/stage tracking documents
2. Creates per-epic regression.md files for responsive testing checklists
3. Adds workflow documentation to project CLAUDE.md (from templates below)
4. Creates changelog/ directory with consolidation script

Directory Structure

epics/
├── EPIC-001-feature-name/
│   ├── EPIC-001.md
│   ├── STAGE-001-001.md
│   ├── STAGE-001-002.md
│   └── regression.md        # Per-epic regression checklist
├── EPIC-002-another-feature/
│   ├── EPIC-002.md
│   └── regression.md
└── ...

changelog/
├── create_changelog.sh     # Script to consolidate entries
└── .gitkeep               # Keeps directory in git

After Setup

Tell user:

• Use /next_task to check current work
• Use /epic-stats to see overall progress
• Create first epic: epics/EPIC-001-name/EPIC-001.md

Creating Epics/Stages

All templates are embedded below in this skill file.

Key Rules

• Use 3-digit padding: EPIC-001, STAGE-001-001
• Status values: "Not Started", "Design", "Build", "Refinement", "Finalize", "Complete", "Skipped"
• All four phase sections required in every stage file
• Epic directory name format: epics/EPIC-XXX-kebab-case-name/

Sequential Dependency Ordering (CRITICAL)

Core Rule: Dependencies flow upward numerically. If work X depends on work Y, then Y must have a lower number than X.

STAGE-001 → STAGE-002 → STAGE-003
   ↑            ↑
   │            └── Can depend on 001
   └── No dependencies (first)

EPIC-001 → EPIC-002 → EPIC-003
   ↑           ↑
   │           └── Can depend on EPIC-001 work
   └── No cross-epic dependencies

Before creating ANY stage, verify:

1. Dependency check: Does this stage depend on work that doesn't exist yet?

- If YES: Create the dependency FIRST (lower number) or assign to earlier epic - If NO: Proceed with current numbering

1. Cross-epic check: Does this stage depend on work in a LATER epic?

- If YES: STOP - This violates sequential ordering - Either move the stage to that later epic, or move the dependency to an earlier epic

1. Insertion check: Are you inserting a stage mid-sequence (e.g., STAGE-005-003A)?

- Never insert a stage that depends on later-numbered work - Insertions must only depend on EARLIER stages in the sequence

Red Flags - STOP Before Creating Stage:

Common Rationalizations (REJECT ALL):

Edge Cases:

Circular Dependencies: If EPIC-A needs EPIC-B work AND EPIC-B needs EPIC-A work:

1. This indicates architectural coupling that should be resolved
2. Extract the shared work into an earlier EPIC-C that both depend on
3. Never create circular epic dependencies - one must come first

STAGE-XXX-XXXA Notation: Inserting stages mid-sequence (e.g., 002A between 002 and 003) is ONLY valid when:

• The inserted stage depends on EARLIER stages only (001, 002)
• The inserted stage does NOT depend on later stages (003, 004) or later epics
• Using 002A is preferable to renumbering all subsequent stages

When User Insists After Explanation:

1. Document in stage file: "Dependency ordering override requested by user - [stage] depends on [future work]"
2. Proceed as directed (user has project authority)
3. Flag in lessons-learned: "Sequential dependency violation - user override"
4. The work may block or fail; user accepts that risk

Epic File Template (EPIC-XXX.md)

# EPIC-XXX: [Name]

## Status: Not Started

## Overview

[Description of the feature/capability this epic delivers]

## Stages

| Stage         | Name                | Status      |
| ------------- | ------------------- | ----------- |
| STAGE-XXX-001 | [First stage name]  | Not Started |
| STAGE-XXX-002 | [Second stage name] | Not Started |

## Current Stage: STAGE-XXX-001

## Notes

- [Any relevant notes]

Stage File Template (STAGE-XXX-YYY.md)

# STAGE-XXX-YYY: [Name]

## Status: Not Started

## Overview

[What this stage implements]

## Stage Flags

- Has Input Forms: [ ] Yes

## Design Phase

- **UI Options Presented**:
- **User Choice**:
- **Seed Data Agreed**:
- **Session Notes**:

**Status**: [ ] Complete

## Build Phase

- **Components Created**:
- **API Endpoints Added**:
- **Placeholders Added**:
- **Session Notes**:

**Status**: [ ] Complete

## Refinement Phase

- [ ] Desktop Approved
- [ ] Mobile Approved
- [ ] Regression Items Added

- **Feedback Round 1**:
- **Feedback Round 2**:

**Status**: [ ] Complete

## Finalize Phase

- [ ] Code Review (pre-tests)
- [ ] Tests Written (unit, integration, e2e)
- [ ] Code Review (post-tests)
- [ ] Documentation Updated
- [ ] Committed

**Commit Hash**:
**CHANGELOG Entry**: [ ] Added

**Status**: [ ] Complete

CLAUDE.md Sections Template

Add these sections to a project's CLAUDE.md when bootstrapping:

Development Workflow Section

## Development Workflow

### Hierarchy

- **Epic** = Feature (Dashboard, Map, Timeline, etc.)
- **Stage** = Single component or interaction within that feature
- **Phase** = Design | Build | Refinement | Finalize

### Phase Cycle Per Stage

Each stage goes through 4 phases, typically each in a separate session:

1. DESIGN PHASE - Present options, user picks, confirm seed data
2. BUILD PHASE - Implement, add seed data, add placeholders
3. REFINEMENT PHASE - Dual sign-off (Desktop AND Mobile approval)
4. FINALIZE PHASE - Tests, review, docs, commit (all via subagents)

Commands Section

## Commands

| Command       | Purpose                                         |
| ------------- | ----------------------------------------------- |
| `/next_task`  | Find next work by scanning epic/stage hierarchy |
| `/epic-stats` | Calculate progress across epics                 |

Stage Tracking Section

## Stage Tracking Documents

### Location

epics/EPIC-XXX-name/STAGE-XXX-YYY.md

### Status Values

- `Not Started` - Work not yet begun
- `Design` - In design phase
- `Build` - In build phase
- `Refinement` - In refinement phase
- `Finalize` - In finalize phase
- `Complete` - All phases done
- `Skipped` - Intentionally skipped

Regression Checklist Template

Create per-epic regression files at epics/EPIC-XXX-name/regression.md:

# Regression Checklist - EPIC-XXX: [Name]

Items to verify after each deployment. Format: `[D]` = desktop, `[M]` = mobile, `[D][M]` = both.

## STAGE-XXX-001: [Stage Name]

- [ ] [D][M] Description of item to check

## STAGE-XXX-002: [Stage Name]

- [ ] [D][M] Description of item to check

Changelog Pattern

Agents write entries to date-based files in changelog/ directory:

CRITICAL: Getting the date - NEVER estimate or hardcode dates:

# Get today's date for the changelog filename
TODAY=$(date +%Y-%m-%d)
# Example output: 2026-01-14

File pattern: changelog/$TODAY.changelog.md

Entry format:

## [STAGE-XXX-YYY] Stage Name

- Description of what was done
- Commit: `<hash>`

Rules:

• Multiple entries on same day - PREPEND to same file (newest at top)
• Always include commit hash after committing
• User runs ./changelog/create_changelog.sh to consolidate into CHANGELOG.md

create_changelog.sh Template

#!/bin/bash
# Consolidates changelog entries into CHANGELOG.md
# Run from project root: ./changelog/create_changelog.sh

set -e

CHANGELOG_DIR="changelog"
OUTPUT_FILE="CHANGELOG.md"

# Create or clear the output file with header
cat > "$OUTPUT_FILE" << 'EOF'
# Changelog

All notable changes to this project are documented here.

EOF

# Process changelog files in reverse chronological order
for file in $(ls -r "$CHANGELOG_DIR"/*.changelog.md 2>/dev/null); do
    if [ -f "$file" ]; then
        date=$(basename "$file" .changelog.md)
        echo "## $date" >> "$OUTPUT_FILE"
        echo "" >> "$OUTPUT_FILE"
        cat "$file" >> "$OUTPUT_FILE"
        echo "" >> "$OUTPUT_FILE"
    fi
done

echo "CHANGELOG.md updated from $CHANGELOG_DIR entries"