zhongwei/gh-levnikolaevich-claude-code-skills-full-development-workflow-skills

Files

Zhongwei Li 37774aa937 Initial commit

2025-11-30 08:37:27 +08:00

24 KiB

Raw Permalink Blame History

name, description

name	description
ln-210-epic-coordinator	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

Phase 5b: Replan Mode (Existing Epics Found)

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

Process:

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
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

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)

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
User Confirmation:
- Wait for user to type "confirm"
- If user provides feedback → Adjust operations and show updated summary
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
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:

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)
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
Phase 3: Check Existing
- Epic Story Counters: 0 rows → CREATE MODE
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)
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

24 KiB Raw Permalink Blame History Unescape Escape

Epic Coordinator

When to Use This Skill

Core Concepts

Decompose-First Pattern

Epic 0 Reserved for Infrastructure

Workflow

Phase 1: Discovery & Research

Phase 2: Scope Analysis & Epic Planning

Phase 3: Check Existing Epics

Phase 4: Epic Preparation (CREATE mode only)

Phase 5a: Epic Creation (CREATE mode)

Phase 5b: Replan Mode (Existing Epics Found)

Definition of Done

Example Usage

Reference Files

Best Practices

24 KiB

Raw Permalink Blame History