Initial commit

2025-11-30 08:37:27 +08:00
commit 37774aa937
131 changed files with 31137 additions and 0 deletions
--- a/skills/ln-210-epic-coordinator/SKILL.md
+++ b/skills/ln-210-epic-coordinator/SKILL.md
@@ -0,0 +1,594 @@
+---
+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:**
+
+1. **Document Scan:**
+   - Use `Glob` to find: `docs/requirements.md`, `docs/architecture.md`, `docs/tech_stack.md`
+   - Use `Read` to load found documents
+
+2. **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:**
+   ```html
+   <nav>
+     <a href="/products">Products</a>
+     <a href="/cart">Shopping Cart</a>
+     <a href="/checkout">Checkout</a>
+   </nav>
+   <!-- Reveals domains: Product Catalog, Shopping Cart, Payment -->
+   ```
+
+3. **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?
+
+4. **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:
+1. **New project** (no `docs/infrastructure.md` found, no Epic "Infrastructure" in kanban_board.md Epic Story Counters)
+2. **Multi-stack** (requirements.md or tech_stack.md mentions frontend AND backend on different stacks - e.g., React + Python)
+3. **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:
+1. Existing project (found `docs/infrastructure.md`)
+2. Epic Story Counters shows existing Epic with "Infrastructure" in title
+3. 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:
+
+1. **Read Epic Story Counters** table in kanban_board.md
+2. **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:
+
+1. **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)
+
+2. **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)
+
+3. **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)
+
+4. **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)
+
+5. **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):
+
+1. **Get Next Epic Number:**
+   - Read current Next Epic Number from kanban_board.md
+   - Example: 11
+
+2. **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"
+
+3. **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`
+
+4. **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
+
+---
+
+### Phase 5b: Replan Mode (Existing Epics Found)
+
+**Trigger:** Phase 3 determined Count ≥ 1 (REPLAN MODE)
+
+**Process:**
+
+1. **Load Existing Epics:**
+   - Read Epic Story Counters table from kanban_board.md
+   - For each Epic row: load Epic from Linear via `get_project(id)`
+   - Load FULL description (Goal, Scope In/Out, Success Criteria, Risks, Phases)
+   - Note Epic status (active/archived)
+   - **Total:** N existing Epics
+
+2. **Compare IDEAL Plan (from Phase 2) vs Existing:**
+   - **Match by goal:** Fuzzy match Epic goals + domain names
+   - **Identify operations needed:**
+     - **KEEP:** Epic in IDEAL + existing, goals unchanged → No action
+     - **UPDATE:** Epic in IDEAL + existing, scope/criteria changed → Update description
+     - **OBSOLETE:** Epic in existing, NOT in IDEAL → Archive (state="archived")
+     - **CREATE:** Epic in IDEAL, NOT in existing → Create new
+
+3. **Categorize Operations:**
+   ```
+   ✅ KEEP (N Epics): No changes needed
+   - Epic 5: User Management
+   - Epic 6: Payment Processing
+
+   🔧 UPDATE (M Epics): Scope or criteria changed
+   - Epic 7: Reporting (Scope modified: add real-time dashboards)
+   - Epic 8: Notifications (Success Criteria: add email delivery tracking)
+
+   ❌ OBSOLETE (K Epics): No longer in initiative scope
+   - Epic 9: Legacy Data Migration (removed from scope)
+
+   ➕ CREATE (L Epics): New domains added
+   - Epic 17: Analytics Engine (new initiative requirement)
+   ```
+
+4. **Show Replan Summary:**
+   - Display operations for all Epics
+   - Show diffs for UPDATE operations (before/after Scope, Criteria)
+   - Show warnings for edge cases:
+     - ⚠️ "Epic 7 has 5 Stories In Progress - cannot auto-archive, manual review needed"
+   - Total operation count
+
+5. **User Confirmation:**
+   - Wait for user to type "confirm"
+   - If user provides feedback → Adjust operations and show updated summary
+
+6. **Execute Operations:**
+   - **KEEP:** Skip (no Linear API calls)
+   - **UPDATE:** Call `update_project(id, description=new_description)` (if no Stories In Progress)
+   - **OBSOLETE:** Call `update_project(id, state="archived")` (if no Stories In Progress)
+   - **CREATE:** Call `create_project()` (same as Phase 5a Step 3) + update kanban_board.md
+
+7. **Update kanban_board.md:**
+   - Remove OBSOLETE Epics from Epic Story Counters table
+   - Update modified Epics (UPDATE operations) - preserve Story counters
+   - Add new Epics (CREATE operations) to Epic Story Counters
+   - Update Epics Overview section (move archived to Archived section)
+
+**Output:** Summary message with operation results + affected Epic URLs
+
+**Important Constraints:**
+- **Never auto-update/archive Epics with Stories In Progress** (show warnings only)
+- **Never delete Epics:** Use state="archived" to preserve history
+- **Always require user confirmation** before executing operations
+
+---
+
+## 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):**
+- [ ] Existing Epics loaded from Linear
+- [ ] IDEAL plan compared against existing
+- [ ] Operations categorized (KEEP/UPDATE/OBSOLETE/CREATE)
+- [ ] User confirmed operations (CONTROL POINT 2)
+- [ ] Operations executed in Linear
+- [ ] kanban_board.md updated (removed OBSOLETE, added CREATE)
+- [ ] Summary displayed with affected Epic URLs
+
+**Output:** List of Linear Project URLs (Epic {N}: {Title}) + Next Epic Number value
+
+---
+
+## Example Usage
+
+**Request:**
+```
+"Create epics for e-commerce platform"
+```
+
+**Process:**
+
+1. **Phase 1: Discovery & Research**
+   - Team "Product", Next Epic Number = 11
+   - Scan requirements.md, architecture.md, tech_stack.md
+   - Scan HTML files: Found navigation with Products, Cart, Checkout
+   - Infrastructure Epic decision: YES (new project, multi-stack: React + Python)
+
+2. **Phase 2: Scope Analysis**
+   - Auto-identify 6 domains from docs + HTML: "Infrastructure", "User Management", "Product Catalog", "Shopping Cart", "Payment Processing", "Order Management"
+   - Build Epic list: Epic 0 (Infrastructure) + Epic 1-5 (business)
+   - Show proposed Epic structure → User confirms
+
+3. **Phase 3: Check Existing**
+   - Epic Story Counters: 0 rows → CREATE MODE
+
+4. **Phase 4: Epic Preparation**
+   - Auto-extract Q1-Q5 for all 6 domains from requirements.md, architecture.md, HTML
+   - Generate 6 Epic documents (Epic 0-5 indexes)
+
+5. **Phase 5a: Epic Creation**
+   - Show batch preview with Epic 0-5 indexes
+   - User types "confirm"
+   - Create in Linear sequentially:
+     - Epic 0 → Linear: "Epic 11: Infrastructure & Operations"
+     - Epic 1 → Linear: "Epic 12: User Management"
+     - Epic 2 → Linear: "Epic 13: Product Catalog"
+     - Epic 3 → Linear: "Epic 14: Shopping Cart"
+     - Epic 4 → Linear: "Epic 15: Payment Processing"
+     - Epic 5 → Linear: "Epic 16: Order Management"
+   - Next Epic Number updated to 17
+   - Display summary with all 6 URLs
+
+**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
+
+---
+
+## Best Practices
+
+- **Research project docs first:** Always scan requirements.md, architecture.md, tech_stack.md in Phase 1 Step 2 BEFORE asking user
+- **Scan HTML files:** Extract functional domains from navigation, forms, page titles (Phase 1 Step 2) - complements documentation
+- **Propose Infrastructure Epic:** For new projects, multi-stack, or projects with security/monitoring/deployment requirements (Phase 1 Step 3)
+- **Epic 0 for Infrastructure:** Use Epic 0 as reserved index for Infrastructure Epic within initiative, business domains start from Epic 1 (Phase 2 Step 2)
+- **Business Epic grouping:** Group domains by complete business process OR HTML screen
+  - ✅ BY BUSINESS PROCESS: "User Authentication" (login + register + password reset + profile)
+  - ✅ BY HTML SCREEN: "Product Catalog" (products list page + product details page + search)
+  - ❌ AVOID: "Login Screen", "Register Screen" as separate Epics (too granular, merge into "User Authentication")
+  - ❌ AVOID: "User Table", "Login Service" (technical components, not business domains)
+  - **Guideline:** 1 Epic = 5-10 User Stories = 1 complete business capability or major UI screen group
+- **Batch Epic preview:** Generate ALL Epics before showing preview - allows user to see complete Epic plan with Epic 0-N indexes (Phase 5a Step 1)
+- **Auto-extraction:** Extract Q1-Q5 from requirements.md, architecture.md, HTML BEFORE asking user (Phase 4 Step 1) - ask only for missing information
+- **Linear Title format:** "Epic {Next Epic Number}: {Domain}" where Next Epic Number from kanban_board.md (Phase 5a Step 3)
+- **Business-focused Scope:** Epic Scope In lists USER CAPABILITIES, not technical tasks
+  - ✅ GOOD: "Users can register, login, logout, reset password"
+  - ❌ BAD: "Create user table, JWT middleware, password hashing service"
+  - Technical architecture → Epic "Architecture Impact" section, NOT Scope In
+- **Measurable success criteria:** "<200ms" not "fast", ">98% login rate" not "reliable"
+- **Define OUT of scope:** Prevent scope creep with explicit exclusions
+- **No code snippets:** Never include actual code in Epic descriptions - only high-level features and goals
+
+---
+
+**Version:** 7.0.0 (BREAKING: Epic 0 clarified as initiative-internal index. HTML research added to Phase 1 Step 2 for frontend domain extraction. Phase structure simplified - removed old Phase 3 "Build IDEAL Plan" (merged into Phase 2 inline). Phase 4 extracted from Phase 5a for Epic Preparation. Phase numbering updated: Phase 3=Check Existing, Phase 4=Preparation, Phase 5a/5b=Creation/Replan. Linear titles use Next Epic Number consistently. Removed confusing "conceptual numbering" explanations.)
+**Last Updated:** 2025-11-20
--- a/skills/ln-210-epic-coordinator/diagram.html
+++ b/skills/ln-210-epic-coordinator/diagram.html
@@ -0,0 +1,136 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>ln-210-epic-coordinator - State Diagram</title>
+    <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
+    <link rel="stylesheet" href="../shared/css/diagram.css">
+</head>
+<body>
+    <div class="container">
+        <header>
+            <h1>🎯 ln-210-epic-coordinator</h1>
+            <p class="subtitle">Epic Coordinator - State Diagram v7.0.0</p>
+        </header>
+
+        <div class="info-box">
+            <h3>📋 Workflow Overview</h3>
+            <ul>
+                <li><strong>Purpose:</strong> Decompose scope/initiative into 3-7 Epics (Linear Projects)</li>
+                <li><strong>Modes:</strong> CREATE (batch preview → create ALL Epics) / REPLAN (compare IDEAL vs EXISTING → execute operations)</li>
+                <li><strong>Pattern:</strong> Batch Preview (show ALL Epics) → Single Confirm → Create ALL</li>
+                <li><strong>Output:</strong> 3-7 Linear Projects with Epic documents (Epic 0: Infrastructure, Epic 1-N: Business domains)</li>
+            </ul>
+        </div>
+
+        <div class="legend">
+            <div class="legend-item">
+                <div class="legend-color color-discovery"></div>
+                <span>Discovery/Research</span>
+            </div>
+            <div class="legend-item">
+                <div class="legend-color color-loop"></div>
+                <span>Preparation</span>
+            </div>
+            <div class="legend-item">
+                <div class="legend-color color-decision"></div>
+                <span>Decision Point</span>
+            </div>
+            <div class="legend-item">
+                <div class="legend-color color-action"></div>
+                <span>Creation/Completion</span>
+            </div>
+        </div>
+
+        <div class="diagram-container">
+            <div class="mermaid">
+graph TD
+    Start([Start: Create/Replan Epics]) --> Phase1[Phase 1: Discovery & Research<br/>Auto-discover Team ID + Next Epic Number<br/>Scan docs + HTML files<br/>Infrastructure Epic decision]
+
+    Phase1 --> Phase2[Phase 2: Scope Analysis<br/>Auto-identify domains from docs + HTML<br/>Build Epic list Epic 0-N<br/>Show proposed structure]
+
+    Phase2 --> UserConfirm1{User confirms<br/>Epic structure?}
+    UserConfirm1 -->|No| Phase2
+    UserConfirm1 -->|Yes| Phase3[Phase 3: Check Existing Epics<br/>Count rows in Epic Story Counters]
+
+    Phase3 --> Decision{Existing<br/>Epics count?}
+
+    Decision -->|Count = 0<br/>CREATE MODE| Phase4[Phase 4: Epic Preparation<br/>Auto-extract Q1-Q5 for ALL domains<br/>Generate ALL Epic documents]
+
+    Phase4 --> Phase5a[Phase 5a: Epic Creation<br/>Show batch preview Epic 0-N]
+
+    Phase5a --> UserConfirm2{User types<br/>'confirm'?}
+    UserConfirm2 -->|No| Phase4
+    UserConfirm2 -->|Yes| CreateAll[Create ALL Epics in Linear<br/>Epic 0 → Epic 11: Infrastructure<br/>Epic 1 → Epic 12: User Management<br/>etc.]
+
+    CreateAll --> Summary1[Display summary<br/>6 Epics created Epic 11-16]
+    Summary1 --> End([End])
+
+    Decision -->|Count ≥ 1<br/>REPLAN MODE| Phase5b[Phase 5b: Epic Replan<br/>Load existing Epics<br/>Compare IDEAL vs EXISTING<br/>Categorize operations]
+
+    Phase5b --> Operations[Show operations:<br/>KEEP / UPDATE / OBSOLETE / CREATE]
+
+    Operations --> UserConfirm3{User confirms<br/>operations?}
+    UserConfirm3 -->|No| End
+    UserConfirm3 -->|Yes| Execute[Execute operations in Linear<br/>Update kanban_board.md]
+
+    Execute --> Summary2[Display summary<br/>Operation results + affected URLs]
+    Summary2 --> End
+
+    %% Styling
+    classDef discovery fill:#E3F2FD,stroke:#1976D2,stroke-width:2px
+    classDef loop fill:#FFF9C4,stroke:#F57C00,stroke-width:2px
+    classDef decision fill:#FFE0B2,stroke:#E64A19,stroke-width:2px
+    classDef action fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
+
+    class Phase1,Phase2 discovery
+    class Phase4,Phase5a,Phase5b,Operations,Execute loop
+    class Decision,UserConfirm1,UserConfirm2,UserConfirm3 decision
+    class Phase3,CreateAll,Summary1,Summary2 action
+            </div>
+        </div>
+
+        <div class="info-box">
+            <h3>🔑 Key Features v7.0.0</h3>
+            <ul>
+                <li><strong>HTML Research:</strong> Extract domains from navigation, forms, page titles (complements documentation)</li>
+                <li><strong>Epic 0 Reserved:</strong> Infrastructure Epic = Epic 0 index, business domains = Epic 1-N</li>
+                <li><strong>Batch Preview:</strong> Show ALL Epics before creation, single confirmation (not sequential loop)</li>
+                <li><strong>Auto-extraction Q1-Q5:</strong> Goal, Scope In/Out, Success Criteria, Risks from docs + HTML</li>
+                <li><strong>CREATE/REPLAN Modes:</strong> Decompose-First Pattern - builds IDEAL plan, compares with existing, determines operations</li>
+                <li><strong>Business Epic Grouping:</strong> 1 Epic = complete business process OR HTML screen group (5-10 Stories)</li>
+            </ul>
+        </div>
+
+        <div class="info-box">
+            <h3>📐 Phase Structure</h3>
+            <ul>
+                <li><strong>Phase 1:</strong> Discovery & Research (Team ID, docs, HTML, Infrastructure decision)</li>
+                <li><strong>Phase 2:</strong> Scope Analysis (identify domains, build Epic list, user confirms structure)</li>
+                <li><strong>Phase 3:</strong> Check Existing Epics (determine CREATE vs REPLAN mode)</li>
+                <li><strong>Phase 4:</strong> Epic Preparation (CREATE only - auto-extract, generate docs)</li>
+                <li><strong>Phase 5a:</strong> Epic Creation (CREATE only - batch preview, confirm, create ALL)</li>
+                <li><strong>Phase 5b:</strong> Epic Replan (REPLAN only - compare, show operations, execute)</li>
+            </ul>
+        </div>
+
+        <footer>
+            <p>Generated for ln-210-epic-coordinator skill | Version 7.0.0</p>
+            <p>Diagram format: Mermaid.js | Last updated: 2025-11-20</p>
+        </footer>
+    </div>
+
+    <script>
+        mermaid.initialize({
+            startOnLoad: true,
+            theme: 'default',
+            flowchart: {
+                useMaxWidth: true,
+                htmlLabels: true,
+                curve: 'basis'
+            }
+        });
+    </script>
+</body>
+</html>
--- a/skills/ln-210-epic-coordinator/references/epic_template_universal.md
+++ b/skills/ln-210-epic-coordinator/references/epic_template_universal.md
@@ -0,0 +1,95 @@
+# Epic N: Epic Title
+
+**Linear Project:** [Epic Title](https://linear.app/workspace/project/...)
+**Priority:** High | Medium | Low
+
+---
+
+## Goal
+
+Brief business objective this Epic achieves. Focus on "why" and business value.
+
+---
+
+## Scope
+
+### In Scope
+- Feature/capability 1
+- Feature/capability 2
+- Feature/capability 3
+
+### Out of Scope
+- Explicitly NOT doing in this Epic
+- Future enhancements deferred
+- Related but not included features
+
+---
+
+## Success Criteria
+
+Measurable outcomes to verify Epic completion:
+- Measurable outcome 1 (quantifiable)
+- Measurable outcome 2 (testable)
+- Measurable outcome 3 (observable)
+
+---
+
+## Dependencies
+
+### Technical Dependencies
+- **Dependency 1**: Technical requirement description
+- **Dependency 2**: Infrastructure/library requirement
+
+### External Dependencies
+- **Third-party services**: Which external services required?
+- **Infrastructure**: What infrastructure needed?
+
+### Epic Dependencies
+- **Blocks**: This Epic blocks [Epic Name]
+- **Blocked by**: This Epic is blocked by [Epic Name]
+
+---
+
+## Risks and Mitigations
+
+| Risk | Impact | Probability | Mitigation Strategy |
+|------|--------|-------------|---------------------|
+| Risk description 1 | H/M/L | H/M/L | How to address |
+| Risk description 2 | H/M/L | H/M/L | How to address |
+
+---
+
+## Metrics
+
+How to measure success after deployment:
+- **Metric 1**: Target: [value], Measurement: [how]
+- **Metric 2**: Target: [value], Measurement: [how]
+
+---
+
+## Architecture Impact
+
+### Components Affected
+- Component 1 - Description of changes
+- Component 2 - Description of changes
+
+### Architecture Patterns Applied
+- Pattern 1: Description and why chosen
+- Pattern 2: Description and why chosen
+
+### Technical Decisions
+- Decision 1: Rationale
+- Decision 2: Trade-offs considered
+
+---
+
+## User Stories
+
+User Stories created separately via story-creator skill:
+- US001: [Story Name] - Brief description
+- US002: [Story Name] - Brief description
+
+---
+
+**Template Version:** 2.1.0 (Timeline removed)
+**Last Updated:** 2025-11-07
--- a/skills/ln-210-epic-coordinator/references/linear_integration.md
+++ b/skills/ln-210-epic-coordinator/references/linear_integration.md
@@ -0,0 +1,372 @@
+# Linear Integration Guide
+
+Discovery and API reference for creating Linear Projects (Epics) and User Stories.
+
+---
+
+## Part 1: Discovery
+
+Auto-discovering Linear configuration from centralized source.
+
+### Finding Team ID
+
+**Primary source:** `docs/tasks/kanban_board.md`
+
+Read Linear Configuration table:
+```markdown
+## Linear Configuration
+
+| Variable | Value |
+|----------|-------|
+| **Team ID** | PrompsitAPI |
+| **Team Key** | API |
+| **Next Epic Number** | 7 |
+```
+
+Extract **Team ID** value from table.
+
+**Fallback:** Ask user "What is your Linear team ID?" (formats: "PrompsitAPI", "API")
+
+### Finding Next Epic Number
+
+**Primary source:** `docs/tasks/kanban_board.md`
+
+Read Linear Configuration table → **Next Epic Number** field.
+
+**Verification (optional):** Query Linear Projects via MCP to verify:
+```
+mcp__linear-server__list_projects(team="<TEAM_ID>")
+```
+Extract Epic numbers from project names matching `Epic \d+`, take MAX.
+
+**Fallback:** Ask user "What is the next Epic number?" (formats: "7", "1" if first)
+
+### Finding Next Story Number
+
+**Primary source:** `docs/tasks/kanban_board.md`
+
+Read Epic Story Counters table:
+```markdown
+### Epic Story Counters
+
+| Epic | Last Story | Next Available |
+|------|-----------|----------------|
+| Epic 6 | - | US001 |
+| Epic 7+ | - | US001 |
+```
+
+For specified Epic → Read **Next Available** column.
+
+**Format:** US001, US002, US010 (zero-padded, 3 digits)
+
+**Fallback:** Ask user "What is the next Story number for Epic N?" (default: "US001")
+
+---
+
+## Part 2: Create Project API
+
+### MCP Function
+
+```
+mcp__linear-server__create_project(
+    name: str,              # Required - "Epic N: Title"
+    team: str,              # Required - Team ID/key
+    description: str = "",  # Full Epic markdown
+    startDate: str = "",    # ISO format YYYY-MM-DD
+    targetDate: str = "",   # ISO format YYYY-MM-DD
+    summary: str = ""       # Max 255 chars
+)
+```
+
+### Parameters
+
+**name** (required):
+- Format: "Epic N: Title"
+- Example: "Epic 7: OAuth2 Authentication"
+
+**team** (required):
+- Team ID or key
+- Example: "API", "PrompsitAPI"
+
+**description** (optional):
+- Full Epic content in Markdown
+- Includes: Goal, Scope, Success Criteria, Risks
+
+**summary** (optional):
+- One-sentence goal (max 255 chars)
+- Example: "Implement OAuth2 authentication for API security"
+
+### Return Value
+
+```
+{
+    "success": True,
+    "projectId": "abc123-xyz",
+    "url": "https://linear.app/workspace/project/abc123"
+}
+```
+
+### Example Usage
+
+```
+result = mcp__linear-server__create_project(
+    name="Epic 7: OAuth2 Authentication",
+    team="API",
+    description="""
+# Goal
+Enable secure API authentication using OAuth2.
+
+## In Scope
+- Token generation and validation
+- Refresh token flow
+- User profile API
+
+## Out of Scope
+- Password reset
+- Social login
+
+## Success Criteria
+- Auth endpoint responds <200ms p95
+- 99.9% uptime
+- Zero security vulnerabilities
+""",
+    summary="Implement OAuth2 authentication for API security",
+    startDate="2025-10-24",
+    targetDate="2025-12-15"
+)
+
+# Returns URL to created project
+```
+
+### Error Handling
+
+**Team not found:** Verify team exists, check spelling
+**Invalid date:** Use "YYYY-MM-DD" format only
+**Creation failed:** Create minimal project (name + team only), add details in Linear UI
+
+---
+
+## Part 3: Create Issue API (User Stories)
+
+### MCP Function
+
+```
+mcp__linear-server__create_issue(
+    title: str,              # Required - "USXXX: Title"
+    team: str,               # Required - Team ID/key
+    description: str = "",   # Full Story markdown
+    project: str = "",       # Epic name to link to
+    labels: list = [],       # ["user-story"] for parent stories
+    parentId: str = None     # null for User Stories, Story ID for tasks
+)
+```
+
+### Parameters for User Stories
+
+**title** (required):
+- Format: "USXXX: Title"
+- Example: "US001: Token Generation Service"
+
+**team** (required):
+- Team ID or key
+- Example: "API", "PrompsitAPI"
+
+**description** (optional):
+- Full Story content in Markdown
+- Includes: Story (As a..), Context, AC, Technical Notes, DoD
+
+**project** (optional):
+- Epic name to link story to
+- Example: "Epic 7: OAuth2 Authentication"
+
+**labels** (required for User Stories):
+- Must include: ["user-story"]
+- Identifies as parent for tasks
+
+**parentId** (required):
+- Set to null for User Stories (they are parents)
+- Set to Story ID for tasks (children)
+
+### Return Value
+
+```
+{
+    "success": True,
+    "issueId": "API-123",
+    "url": "https://linear.app/workspace/issue/API-123"
+}
+```
+
+### Example Usage
+
+```
+result = mcp__linear-server__create_issue(
+    title="US001: OAuth Token Authentication",
+    team="API",
+    description="""
+## Story
+**As a** mobile app developer
+**I want** to authenticate API requests with OAuth2 tokens
+**So that** users can securely access their data
+
+## Acceptance Criteria
+- **Given** valid token **When** request sent **Then** returns 200
+- **Given** invalid token **When** request sent **Then** returns 401
+""",
+    project="Epic 7: OAuth2 Authentication",
+    labels=["user-story"],
+    parentId=None
+)
+
+# Returns URL to created User Story
+```
+
+### Error Handling
+
+**Team not found:** Verify team exists, check spelling
+**Project not found:** Verify Epic name matches exactly in Linear
+**Creation failed:** Create minimal issue (title + team only), add details in Linear UI
+
+---
+
+## Part 4: Get Issue and List Issues APIs
+
+### Why Needed?
+
+- `create_issue` returns only **short ID** (e.g., "API-123")
+- `list_issues(parentId=...)` requires **UUID** (e.g., "333e6aa2-64d6-47de-b07b-7385756ae014")
+- Must use `get_issue` to retrieve UUID from short ID
+
+### Get Issue API
+
+**MCP Function:**
+
+```
+mcp__linear-server__get_issue(
+    id: str  # Short ID (API-123) OR UUID
+)
+```
+
+**Parameters:**
+
+**id** (required):
+- Accepts: Short ID (e.g., "API-123", "US001") OR UUID
+- Example: "API-97" or "333e6aa2-64d6-47de-b07b-7385756ae014"
+
+**Return Value:**
+
+Full issue object with:
+- **id**: UUID (internal Linear ID) - "333e6aa2-64d6-47de-b07b-7385756ae014"
+- **identifier**: Short ID - "API-123"
+- **title**: Issue title
+- **description**: Full markdown description
+- **state**: Current status
+- **labels**: Array of labels
+- **parentId**: Parent issue UUID (for child tasks)
+- **project**: Epic/Project object
+- Other fields: assignee, createdAt, updatedAt, etc.
+
+**Example Usage:**
+
+```python
+# Get Story by short ID
+story = mcp__linear-server__get_issue(id="API-97")
+story_uuid = story["id"]  # Extract UUID: "333e6aa2-64d6-47de-b07b-7385756ae014"
+story_short_id = story["identifier"]  # "API-97"
+```
+
+### List Issues API
+
+**MCP Function:**
+
+```
+mcp__linear-server__list_issues(
+    team: str = None,          # Team name/ID
+    parentId: str = None,      # ⚠️ MUST BE UUID, NOT short ID
+    state: str = None,         # Filter by state
+    labels: list = None,       # Filter by labels
+    limit: int = 50            # Max results
+)
+```
+
+**Critical Parameter:**
+
+**parentId** (optional):
+- ⚠️ **MUST BE UUID**, NOT short ID
+- ❌ Wrong: `parentId="API-97"` (short ID) - **WILL FAIL**
+- ✅ Correct: `parentId="333e6aa2-64d6-47de-b07b-7385756ae014"` (UUID)
+
+**Example Usage:**
+
+```python
+# WRONG - will fail with error
+tasks = mcp__linear-server__list_issues(
+    parentId="API-97"  # ❌ Short ID doesn't work
+)
+
+# CORRECT - get UUID first
+story = mcp__linear-server__get_issue(id="API-97")
+story_uuid = story["id"]  # Extract UUID
+
+tasks = mcp__linear-server__list_issues(
+    parentId=story_uuid  # ✅ Use UUID
+)
+```
+
+### Workflow Pattern
+
+**When fetching child tasks:**
+
+```python
+# Step 1: Get parent Story by short ID (from user input)
+story_short_id = "API-97"  # From user or kanban_board.md
+story = mcp__linear-server__get_issue(id=story_short_id)
+
+# Step 2: Extract UUID from Story object
+story_uuid = story["id"]  # "333e6aa2-64d6-47de-b07b-7385756ae014"
+
+# Step 3: Fetch child Tasks using UUID as parentId
+child_tasks = mcp__linear-server__list_issues(
+    parentId=story_uuid,  # ✅ Must use UUID
+    limit=50
+)
+
+# Result: List of all child Tasks for this Story
+```
+
+**When creating child task:**
+
+```python
+# Step 1: Get parent Story UUID (same as above)
+story = mcp__linear-server__get_issue(id="API-97")
+story_uuid = story["id"]
+
+# Step 2: Create child task with UUID as parentId
+result = mcp__linear-server__create_issue(
+    title="Task: Implement feature",
+    team="API",
+    description="Task description...",
+    parentId=story_uuid,  # ✅ Must use UUID
+    labels=[]
+)
+```
+
+### Error Handling
+
+**Issue not found:**
+- Verify short ID exists in Linear
+- Check team context (issue might be in different team)
+
+**Empty list returned:**
+- Verify parentId is UUID, not short ID
+- Check if Story has any child tasks (may be legitimately empty)
+- Verify Story status (canceled stories may not show tasks)
+
+---
+
+**Version:** 4.0.0 (Added Part 4: Get Issue and List Issues)
+**Last Updated:** 2025-11-03
+**Changes from v3.0.0:**
+- Added Part 4 with get_issue and list_issues documentation
+- Explained UUID vs short ID distinction
+- Provided workflow patterns for fetching child tasks and creating child issues