name	ln-210-epic-coordinator
description	CREATE/REPLAN Epics from scope (3-7 Epics). Batch Preview + Auto-extraction. Decompose-First Pattern. Auto-discovers team ID.

Epic Coordinator

Universal Epic management coordinator that handles both creation and replanning through scope decomposition.

When to Use This Skill

This skill should be used when:

Start new scope/initiative requiring decomposition into multiple logical domains (CREATE mode)
Break down large architectural requirement into Epics
Update existing Epics when scope/requirements change (REPLAN mode)
Rebalance Epic scopes within an initiative
Add new Epics to existing initiative structure
First step in project planning (scope → Epics → Stories → Tasks)
Define clear scope boundaries and success criteria for each domain

Output: 3-7 Linear Projects (logical domains/modules)

Core Concepts

Decompose-First Pattern

Key principle: ALWAYS analyze scope and build IDEAL Epic plan FIRST, THEN check existing Epics to determine mode:

No existing Epics → CREATE MODE (generate and create all Epics)
Has existing Epics → REPLAN MODE (compare, determine operations: KEEP/UPDATE/OBSOLETE/CREATE)

Rationale: Ensures consistent Epic decomposition based on current scope requirements, independent of existing Epic structure (which may be outdated or suboptimal).

Epic 0 Reserved for Infrastructure

Rule: Epic 0 is a reserved index for Infrastructure Epic within an initiative.

When to use Epic 0:

New project requiring infrastructure setup
Multi-stack project (Frontend + Backend on different stacks)
Project with security/monitoring/deployment requirements

Epic indexes within initiative:

Epic 0: Infrastructure & Operations (if needed)
Epic 1, 2, 3, ... N: Business domains

Linear Project Titles:

Use Next Epic Number from kanban_board.md for sequential numbering
Example: Next Epic Number = 11
- Epic 0 → Linear title: "Epic 11: Infrastructure & Operations"
- Epic 1 → Linear title: "Epic 12: User Management"
- Epic 2 → Linear title: "Epic 13: Product Catalog"

Important: Epic 0/1/2 are initiative-internal indexes for organizing domains. Linear uses global Next Epic Number for project titles.

Workflow

Phase 1: Discovery & Research

Objective: Gather all necessary context before Epic decomposition.

Step 1: Load Configuration

Auto-discovers Team ID and Next Epic Number from docs/tasks/kanban_board.md:

Team ID: Reads Linear Configuration table → Fallback: Ask user directly
Next Epic Number: Reads Next Epic Number field → Fallback: Ask user directly

Details: See CLAUDE.md sections "Configuration Auto-Discovery" and "Linear Integration".

Step 2: Project Research

Objective: Research project documentation AND frontend code to understand context BEFORE asking user questions.

Process:

Document Scan:
- Use Glob to find: docs/requirements.md, docs/architecture.md, docs/tech_stack.md
- Use Read to load found documents
Frontend Code Scan (if applicable):
- Use Glob to find: **/*.html, src/**/*.html, public/**/*.html, templates/**/*.html
- Use Read to load HTML files
- Extract functional domains from:
  - Navigation menus: <nav>, <a href> links reveal feature areas
  - Forms: Input fields reveal data models (user registration, login, checkout)
  - Page titles: <h1>, <title> tags reveal feature names
  - Route patterns: URL structures reveal domain boundaries
Example HTML extraction:
```
<nav>
  <a href="/products">Products</a>
  <a href="/cart">Shopping Cart</a>
  <a href="/checkout">Checkout</a>
</nav>

```
Extract key information from docs + HTML:
- Business objectives: What is the project trying to achieve? (from requirements.md)
- User personas: Who will use the system? (from requirements.md)
- Major functional domains: What are the main modules/areas? (from requirements.md, architecture.md, HTML navigation)
- Technical stack: What technologies mentioned? (from tech_stack.md, architecture.md, HTML meta/script tags)
- Infrastructure requirements: Any mention of logging, monitoring, deployment, CI/CD, security, performance optimization?
Combine findings:
- Merge domains from docs + HTML (deduplicate, consolidate similar)
- Example: "User Auth" (from docs) + "Login" (from HTML) → "User Management"

Fallback: If docs AND HTML missing → Skip to Phase 2, will ask user basic questions

Step 3: Infrastructure Epic Decision

Objective: Determine if Infrastructure Epic (Epic 0) should be proposed.

Criteria for Infrastructure Epic:

✅ PROPOSE Infrastructure Epic (Epic 0) if ANY of:

New project (no docs/infrastructure.md found, no Epic "Infrastructure" in kanban_board.md Epic Story Counters)
Multi-stack (requirements.md or tech_stack.md mentions frontend AND backend on different stacks - e.g., React + Python)
Infrastructure requirements mentioned in requirements.md, architecture.md:
- Logging, Error Handling
- Monitoring, Alerting
- Hosting, Deployment, CI/CD
- Security (authentication, authorization, encryption, secrets management)
- Performance optimization (caching, rate limiting, database optimization)

❌ DO NOT propose if:

Existing project (found docs/infrastructure.md)
Epic Story Counters shows existing Epic with "Infrastructure" in title
User explicitly declined in previous interaction

Decision: Store YES/NO decision for use in Phase 2

Output from Phase 1:

Team ID, Next Epic Number
Project context (business goals, domains from docs + HTML, tech stack, infrastructure needs) - if found
Infrastructure Epic decision (YES/NO)

Phase 2: Scope Analysis & Epic Planning

Objective: Identify logical domains and build Epic structure inline.

Process:

Step 1: Auto-identify Domains

Use research context from Phase 1 Step 2:

If project docs found → Extract domains from requirements.md, architecture.md (module names, feature areas)
If HTML found → Extract domains from navigation, forms, page structures
Combine and deduplicate domains
Example: "User Auth" + "Profile Management" → "User Management"

Fallback: If no docs/HTML → Ask user basic questions (scope, objectives, functional areas)

Step 2: Build Epic List (inline)

IF Infrastructure needed (from Phase 1 Step 3):

Epic 0: Infrastructure & Operations
- Goal: Establish foundational infrastructure, deployment pipeline, operational capabilities
- Scope: Logging, error handling, monitoring, CI/CD, security baseline, performance
- Multi-stack projects: Each Story doubles (Frontend Story + Backend Story for same functionality)
Epic 1-N: Business domains (from Step 1)

ELSE:

Epic 1-N: Business domains only

Step 3: Determine Epic Count

Infrastructure Epic (if applicable): +1 Epic
Simple Initiative (1-3 domains): 3-4 Epics total
Medium Initiative (4-6 domains): 5-7 Epics total
Complex Initiative (7+ domains): 7-10 Epics total (rare)
Max 10 Epics per Initiative (enforced)

Step 4: Show Proposed Epic Structure (USER CONTROL POINT 1)

Display identified Epics with initiative-internal indexes:

📋 Proposed Epic Structure:

Epic 0: Infrastructure & Operations
Epic 1: User Management
Epic 2: Product Catalog
Epic 3: Shopping Cart
Epic 4: Payment Processing
Epic 5: Order Management

Total: 6 Epics
Type "confirm" to proceed, or modify the list

Step 5: User Confirmation

User types "confirm" → Proceed to Phase 3
User modifies → Update domain list, show again

Output: Approved Epic list (Epic 0-N or Epic 1-N) ready for next phase

Phase 3: Check Existing Epics

Objective: Determine CREATE vs REPLAN mode.

Query kanban_board.md and Linear for existing Epics:

Read Epic Story Counters table in kanban_board.md
Count existing Epic rows (excludes header row)

Decision Point:

Count = 0 → No existing Epics → Proceed to Phase 4+5a (CREATE MODE)
Count ≥ 1 → Existing Epics found → Proceed to Phase 5b (REPLAN MODE)

Phase 4: Epic Preparation (CREATE mode only)

Trigger: Phase 3 determined Count = 0 (CREATE MODE)

Objective: Prepare all Epic documents before batch preview.

Step 1: Auto-extract Information for ALL Domains

For EACH domain (from Phase 2), extract answers to 5 key questions from project documentation:

Q1: Business goal - Why this Epic/domain matters
- Source: requirements.md (domain objectives section)
- Extraction: "The [domain] module aims to..." or "Goal: [objective]"
- Fallback: architecture.md (module purpose)
Q2: Key features in scope - 3-5 bullet points of capabilities
- Source: requirements.md (functional requirements for this domain)
- Extraction: Bulleted lists under domain heading, feature descriptions
- Fallback: architecture.md (component responsibilities)
Q3: Out of scope - Prevent scope creep
- Source: requirements.md (explicitly excluded features section)
- Extraction: "Not in scope:", "Future versions:", "Out of scope for [domain]:"
- Fallback: Infer from requirements.md (features NOT mentioned in domain)
Q4: Success criteria - Measurable outcomes
- Source: requirements.md (acceptance criteria, metrics, KPIs for domain)
- Extraction: Performance targets, user metrics, quality gates
- Fallback: Generic criteria based on domain type (e.g., "<200ms API response" for backend)
Q5: Known risks (Optional) - Blockers, dependencies
- Source: architecture.md (technical constraints, dependencies section)
- Extraction: "Risks:", "Dependencies:", "Constraints:"
- Fallback: User input if critical, otherwise leave as "To be determined during Story planning"

If extraction incomplete:

Show extracted information to user
Ask ONCE for ALL missing information across ALL domains (batch question, not per-domain)
Example: "For Epic 1 (User Management), I couldn't find success criteria. For Epic 2 (Payment), I couldn't find risks. Please provide..."

Step 2: Generate ALL Epic Documents

For EACH domain, generate complete Epic document using epic_template_universal.md:

Epic indexing:

IF Infrastructure Epic exists (from Phase 1 Step 3) → Epic 0 (Infrastructure), Epic 1-N (business domains)
ELSE → Epic 1-N (business domains only)

Linear Title (will be created in Phase 5a):

Use Next Epic Number from kanban_board.md for sequential numbering
Format: "Epic {Next Epic Number}: {Domain Title}"
Example: Next = 11 → "Epic 11: Infrastructure & Operations"

Sections: Goal, Scope In/Out, Success Criteria, Dependencies, Risks & Mitigations, Architecture Impact, Phases

Use extracted information from Step 1 for all sections

Output: All Epic documents ready (Epic 0-N), indexed within initiative

Phase 5a: Epic Creation (CREATE mode)

Trigger: Phase 4 completed preparation

Objective: Show preview, get confirmation, create all Epics in Linear.

Step 1: Show Batch Preview (USER CONTROL POINT 2)

Display ALL generated Epics with initiative-internal indexes:

📋 Epic Batch Preview (6 Epics to create)

═══════════════════════════════════════════════
Epic 0: Infrastructure & Operations
═══════════════════════════════════════════════
Goal: Establish foundational infrastructure, deployment pipeline, and operational capabilities to support all business Epics

Scope In:
- Logging and error handling framework
- Monitoring and alerting system
- CI/CD pipeline (GitHub Actions)
- Security baseline (secrets management, encryption)
- Performance optimization (caching, rate limiting)

Scope Out:
- Application-specific business logic
- User-facing features
- Domain-specific integrations

Success Criteria:
- All deployments automated via CI/CD (<10 min deployment time)
- System uptime ≥99.9%
- API response time <200ms (p95)
- Security audit passed

═══════════════════════════════════════════════
Epic 1: User Management
═══════════════════════════════════════════════
Goal: Enable users to register, authenticate, and manage their accounts securely

Scope In:
- User registration with email verification
- Login/logout with JWT authentication
- Password reset flow
- Profile management

Scope Out:
- Social login (OAuth) - planned for Epic 5
- Multi-factor authentication - future version
- User roles and permissions - part of Epic 3

Success Criteria:
- User registration <2 seconds
- Login success rate >98%
- Password reset completion rate >90%

[... all other Epics ...]

───────────────────────────────────────────────
Total: 6 Epics (Epic 0: Infrastructure, Epic 1-5: Business domains)
Type "confirm" to create all Epics in Linear

Step 2: User Confirmation

User types "confirm" → Proceed to Step 3
User provides feedback → Adjust documents in Phase 4, regenerate preview, repeat

Step 3: Create All Epics in Linear

For EACH Epic (in sequential order for numbering consistency):

Get Next Epic Number:
- Read current Next Epic Number from kanban_board.md
- Example: 11
Create Linear Project:
- Title: "Epic {Next Epic Number}: {Domain Title}"
  - Example: "Epic 11: Infrastructure & Operations" (for Epic 0)
  - Example: "Epic 12: User Management" (for Epic 1)
- Description: Complete Epic markdown (from Phase 4 Step 2)
- Team: Team ID from Phase 1
- State: "planned"
Update kanban_board.md:
- Increment Next Epic Number by 1 in Linear Configuration table
- Add new row to Epic Story Counters: Epic {N} | - | US001 | - | EPN_01
- Add to "Epics Overview" → Active: - [Epic {N}: Title](link) - Backlog
Collect URL

Step 4: Display Summary

✅ Created 6 Epics for initiative

Epics created:
- Epic 11: Infrastructure & Operations (Epic 0 index) [link]
- Epic 12: User Management (Epic 1 index) [link]
- Epic 13: Product Catalog (Epic 2 index) [link]
- Epic 14: Shopping Cart (Epic 3 index) [link]
- Epic 15: Payment Processing (Epic 4 index) [link]
- Epic 16: Order Management (Epic 5 index) [link]

Next Epic Number updated to: 17

Next Steps:
1. Use ln-220-story-coordinator to create Stories for each Epic (run 6 times)
2. OR use ln-200-scope-decomposer to automate Epic + Story creation

Output: Created Epic URLs + summary

TodoWrite format: Add Phase 1-5a todos + one todo per Epic + kanban update. Mark in_progress/completed.

Phase 5b: Replan Mode (Existing Epics Found)

Trigger: Phase 3 determined Count ≥ 1 (REPLAN MODE)

Full workflow: See references/replan_workflow.md for complete REPLAN process.

Summary:

Load existing Epics from Linear (full descriptions)
Compare IDEAL plan vs existing → Categorize: KEEP/UPDATE/OBSOLETE/CREATE
Show replan summary with diffs and warnings
User confirmation required
Execute operations in Linear + update kanban_board.md

Constraints: Never auto-update/archive Epics with Stories In Progress. Never delete (use archived). Always require confirmation.

Definition of Done

Before completing work, verify ALL checkpoints:

✅ Discovery Complete (Phase 1):

Team ID loaded from kanban_board.md
Next Epic Number loaded from kanban_board.md
Documentation scanned (requirements.md, architecture.md, tech_stack.md)
HTML files scanned (if frontend exists)
Infrastructure Epic decision made (YES/NO based on project conditions)

✅ Scope Analysis Complete (Phase 2):

Domains auto-identified from docs + HTML
Infrastructure Epic (Epic 0) included if applicable
Epic list built (Epic 0-N or Epic 1-N)
User confirmed Epic structure (CONTROL POINT 1)

✅ Existing Epics Checked (Phase 3):

Epic Story Counters read from kanban_board.md
Existing Epic count determined (0 → CREATE, ≥1 → REPLAN)

✅ Epic Preparation Complete (Phase 4 - CREATE only):

Q1-Q5 auto-extracted for ALL domains
User provided missing information if needed (batch question)
ALL Epic documents generated (Epic 0-N indexes)

✅ Epic Creation Complete (Phase 5a - CREATE only):

Batch preview shown with Epic 0-N indexes
User confirmed preview (CONTROL POINT 2)
ALL Epics created in Linear with "Epic {N}: {Title}" format (N = Next Epic Number)
kanban_board.md updated after EACH Epic:
- Next Epic Number incremented by 1
- Epic Story Counters row added
- Epics Overview updated
Summary displayed with all Epic URLs

✅ Epic Replan Complete (Phase 5b - REPLAN only):

See references/replan_workflow.md for full checklist

Output: List of Linear Project URLs (Epic {N}: {Title}) + Next Epic Number value

Example Usage

Request: "Create epics for e-commerce platform"

Flow: Phase 1 (discover Team ID=Product, Next=11, scan docs+HTML) → Phase 2 (identify 6 domains: Infrastructure, User, Products, Cart, Payment, Orders) → Phase 3 (count=0 → CREATE) → Phase 4 (auto-extract Q1-Q5, generate docs) → Phase 5a (preview, confirm, create in Linear: Epic 11-16)

Result: 6 Epics created (Epic 0-5 internal indexes, Epic 11-16 Linear titles)

Reference Files

linear_integration.md: Discovery patterns + Linear API reference
epic_template_universal.md: Epic template structure
replan_workflow.md: Complete REPLAN mode workflow (Phase 5b)

Best Practices

Research first: Scan docs (requirements.md, architecture.md, tech_stack.md) + HTML before asking user
Epic 0 for Infrastructure: Reserved index for Infrastructure Epic; business domains start from Epic 1
Business Epic grouping: 1 Epic = 5-10 Stories = 1 business capability (not technical components)
Auto-extraction: Extract Q1-Q5 from docs before asking user; ask only for missing info
Linear Title: "Epic {Next Epic Number}: {Domain}" format
Business-focused Scope: List USER CAPABILITIES, not technical tasks
Measurable criteria: "<200ms" not "fast"; ">98% login rate" not "reliable"
No code snippets: High-level features and goals only

Version: 7.0.0 Last Updated: 2025-11-20

ln-210-epic-coordinator

Install Skill

SKILL.md