ln-220-story-coordinator
π―Skillfrom levnikolaevich/claude-code-skills
|Coordinates story creation and replanning for epics by auto-discovering team context, decomposing requirements, and delegating to specialized workers.
Part of
levnikolaevich/claude-code-skills(85 items)
Installation
/plugin add levnikolaevich/claude-code-skillsgit clone https://github.com/levnikolaevich/claude-code-skills.git ~/.claude/skillsSkill Details
CREATE/REPLAN Stories for Epic (5-10 Stories). Delegates ln-001-standards-researcher for standards research. Decompose-First Pattern. Auto-discovers team/Epic.
Overview
# Story Coordinator
Universal Story management coordinator that delegates CREATE/REPLAN operations to specialized workers after building IDEAL Story plan.
When to Use This Skill
Use when:
- Decompose Epic to User Stories (5-10 Stories covering Epic scope)
- Update existing Stories when Epic requirements change
- Rebalance Story scopes within Epic
- Add new Stories to existing Epic structure
Core Pattern: Decompose-First
Key principle: Build IDEAL Story plan FIRST, THEN check existing Stories to determine mode:
- No existing Stories β CREATE MODE (delegate to ln-221-story-creator)
- Has existing Stories β REPLAN MODE (delegate to ln-222-story-replanner)
Rationale: Ensures consistent Story decomposition based on current Epic requirements, independent of existing Story structure (may be outdated).
Story Numbering Convention
Rule: Stories start from Story 1 (US001), NO Story 0 reserved.
Rationale:
- Epic 0 = Infrastructure Epic (group of 5-10 Stories like any other Epic)
- Stories within Epic 0 numbered normally: US001, US002, ... US010
- No reserved Story 0 (unlike Epics, Stories don't need infrastructure placeholder)
Numbering within Epic:
- Epic 0: Infrastructure β US001-US010 (logging, monitoring, CI/CD Stories)
- Epic 1: User Management β US011-US020 (registration, login, profile Stories)
- Epic 2: Product Catalog β US021-US030 (product list, search, details Stories)
Next Story Number: Incremented sequentially across ALL Epics (read from kanban_board.md Epic Story Counters table)
How It Works
Phase 1: Context Assembly
Objective: Gather context for Story planning (Epic details, planning questions, frontend context, fallback docs, user input)
Step 1: Discovery (Automated)
Auto-discovers from docs/tasks/kanban_board.md:
- Team ID: Reads Linear Configuration table
- Epic: Parses Epic number from request β Validates in Linear β Loads Epic description
- User format: "Epic N" (Linear Project number, e.g., "Epic 7: OAuth Authentication")
- Query: get_project(query="Epic N") β Fetch full Epic document
- Extract: Goal, Scope In/Out, Success Criteria, Technical Notes (Standards Research if Epic created by ln-210 v7.0.0+)
- Note: Epic N = Linear Project number (global), NOT initiative-internal index (Epic 0-N)
- Next Story Number: Reads Epic Story Counters table β Gets next sequential number
Step 2: Extract Planning Information (Automated)
Parses Epic structure for Story planning questions:
| Question | Extraction Source |
|----------|-------------------|
| Q1 - User/Persona | Epic Goal ("Enable [persona]...") + Scope In (user roles) |
| Q2 - What they want | Epic Scope In (capabilities) + functional requirements |
| Q3 - Why it matters | Epic Success Criteria (metrics) + Goal (business value) |
| Q4 - Which Epic | Already from Step 1 |
| Q5 - Main AC | Derive from Epic Scope In features β testable scenarios |
| Q6 - Application type | Epic Technical Notes (UI/API mentioned) β Default: API |
Step 3: Frontend Research (Optional)
Trigger: If Q2 (capabilities) OR Q5 (AC) missing after Step 2
Process:
- Scan HTML files:
Glob*/.html,src/*/.html - Extract:
- Forms β AC scenarios (e.g., β "Given valid credentials, When submit, Then login success")
- Buttons/Actions β capabilities (e.g., β "User registration")
- Validation rules β edge case AC (e.g., minlength="8" β "Given password <8 chars, Then error")
- Combine with Epic context, deduplicate, prioritize Epic AC if conflict
Fallback: If no HTML β Skip to Step 4
Step 4: Fallback Search Chain
Objective: Fill missing Q1-Q6 BEFORE asking user.
For each question with no answer from Step 2-3:
| Question | Fallback Search |
|----------|-----------------|
| Q1 (User/Persona) | Search requirements.md for "User personas", "Actors" β Default "User" if not found |
| Q3 (Why it matters) | Search requirements.md for "Business objectives", "Goals" β Infer from Epic Success Criteria |
| Q6 (Application type) | Search tech_stack.md for "Frontend", "Backend", "API" β Default "API" |
Skip: Q2, Q5 (Epic + HTML are sources of truth), Q4 (already known)
Step 5: User Input (Only if Missing)
If still missing after Step 2 + 3 + 4:
- Show extracted: "From Epic: [Epic info]. From HTML: [HTML info]. From fallback: [fallback info]"
- Ask user to confirm or provide remaining missing details
If all questions answered from Epic OR HTML OR fallback: Skip user prompts, proceed to Phase 2
Output: Complete context (Epic details, next Story number, Q1-Q6 answers)
---
Phase 2: Standards Research (Delegated)
Objective: Research industry standards/patterns BEFORE Story generation to ensure implementation follows best practices.
Why: Prevents outdated patterns or RFC violations (e.g., OAuth without PKCE).
Process:
- Parse Epic for domain keywords: Extract domain from Epic goal/Scope In (authentication, rate limiting, payments)
- Delegate to ln-001-standards-researcher:
- Call Skill(skill: "ln-001-standards-researcher", epic_description="[Epic full description]", story_domain="[domain]")
- Wait for Standards Research (Markdown string)
- Store: Cache for Phase 5a/5b (workers insert in Story Technical Notes)
Output: Standards Research stored for ALL Stories in Epic
Skip conditions:
- Epic has NO standards in Technical Notes
- Story domain is trivial CRUD
- Epic says "research not needed"
Time-box: 15-20 minutes (handled by ln-001)
Note: Research done ONCE per Epic, results reused for all Stories (5-10 Stories benefit from single research)
---
Phase 3: Planning
Objective: Build IDEAL Story plan, determine execution mode
Story Grouping Guidelines:
Each Story = ONE vertical slice of user capability (end-to-end: UI β API β Service β DB).
β GOOD Story Grouping (1 Story = 1 user journey):
- β "User registration" (form β validation β API β database β email)
- β "Password reset" (request link β verify token β set password β update DB)
- β "Product search" (input β filter/sort β API β DB query β display)
β BAD Story Grouping (horizontal slices):
- β "Create user table" (database only, no user value β Task, not Story)
- β "User registration API endpoint" (API layer only, not vertical)
- β "Registration UI form" (frontend only, not vertical)
Rule: 1 Story = 1 user capability = 3-5 AC = 6-20 hours = 10-28 tests
Database Creation Principle (Incremental Schema Evolution):
Each Story creates ONLY the tables it needs (not all tables upfront).
β GOOD (Incremental):
- β "User registration" β Creates Users table
- β "Product search" β Creates Products table
- β "Order checkout" β Creates Orders, Payments tables
β BAD (Big-Bang):
- β "Setup database" β Creates all 50 tables (no user value, violates vertical slicing)
- β "Database schema" β Creates Users, Products, Orders, Payments upfront
Rationale: Big-bang database setup violates incremental delivery. Each Story should deliver user value, not technical infrastructure.
Build IDEAL Plan (Automated):
- Analyze Epic Scope: Review features in Epic Scope In, identify user capabilities
- Determine Story Count:
- Simple Epic (1-3 features): 3-5 Stories
- Medium Epic (4-7 features): 6-8 Stories
- Complex Epic (8+ features): 8-10 Stories
- Max 10 Stories per Epic
- Story Size Guidelines:
| Criterion | Min | Max | Under-decomposed | Over-decomposed |
|-----------|-----|-----|------------------|-----------------|
| AC | 3 | 5 | >5 AC (split) | <3 AC (merge) |
| Duration | 6h | 20h | >20h (split) | <6h (merge) |
| Tests | 10 | 28 | >28 tests (split) | <10 tests (merge) |
Over-decomposition indicators:
- β <3 AC, <6 hours, <10 tests
- β Purely technical (no user value)
- β Title starts with "Add", "Create", "Update" (likely Task)
- β Crosses only 1-2 layers (not vertical)
- Build IDEAL Plan "in mind":
- Each Story: persona + capability + business value
- Each Story: 3-5 testable AC (Given-When-Then)
- Stories ordered by dependency
- Each Story: Test Strategy section exists but is empty (tests planned later by ln-510-test-planner)
- Each Story: Technical Notes (architecture, integrations, Standards Research from Phase 2, guide links)
- AC Quality Validation (CRITICAL - delegates to workers):
Workers (ln-221, ln-222) must validate AC quality:
Completeness Check (3 scenario types required):
- β Happy Path (1-2 AC): main success scenarios
- β Error Handling (1-2 AC): invalid inputs, auth failures, system errors
- β Edge Cases (1 AC): boundary conditions, special states, race conditions
Example:
β BAD: "User can login" (only happy path)
β GOOD:
- AC1: Valid credentials β login success (happy path)
- AC2: Invalid password β 401 error (error handling)
- AC3: Account locked β 403 error (edge case)
Specificity Check (measurable outcomes required):
- β HTTP status codes (200, 401, 403, 404)
- β Measurable performance (<200ms, 99% uptime)
- β Exact error messages ("Invalid credentials")
Example:
β BAD: "Login should be fast" (vague)
β GOOD: "Then receive token <200ms" (measurable)
INVEST Checklist:
| Criterion | Check | β GOOD | β BAD |
|-----------|-------|---------|--------|
| Independent | Can develop/deploy without blocking others + NO forward dependencies | "Request OAuth token" (Story N uses only N-1) | "Validate token depends on Story N+2 refresh flow" (forward dependency!) |
| Negotiable | AC focus on WHAT, not HOW | "User gets valid token" (what) | "Use authlib 1.3.0, store in Redis" (how) |
| Valuable | Clear business value | "User refreshes expired token to maintain session" | "Add token_refresh table" (no user value) |
| Estimable | Can estimate 6-20h | Clear scope, known patterns, researched standards | "Implement authentication" (too vague) |
| Small | Fits 1-2 sprints | 3-5 AC, 6-20h | "Full OAuth flow" (>5 AC, >20h) |
| Testable | AC measurable | "Given valid refresh token, Then receive token <200ms" | "Token refresh should be fast" (not measurable) |
Output: IDEAL Story plan (5-10 Stories) with titles, statements, core AC, ordering
---
Phase 4: Check Existing & Detect Mode
Objective: Determine execution mode based on existing Stories AND user intent
Process:
Query Linear for existing Stories in Epic:
```
list_issues(project=Epic.id, label="user-story")
```
Mode Detection:
- Analyze user request for keywords:
- ADD keywords: "add story", "one more story", "additional story", "append"
- REPLAN keywords: "update plan", "revise", "requirements changed", "replan stories"
- Decision matrix:
| Condition | Mode | Delegate To |
|-----------|------|-------------|
| Count = 0 | CREATE | Phase 5a: ln-221-story-creator |
| Count β₯ 1 AND ADD keywords | ADD | Phase 5c: ln-221-story-creator (appendMode) |
| Count β₯ 1 AND REPLAN keywords | REPLAN | Phase 5b: ln-222-story-replanner |
| Count β₯ 1 AND ambiguous | ASK USER | "Add new Story or revise the plan?" |
Important: Orchestrator loads metadata ONLY (ID, title, status). Workers load FULL descriptions (token efficiency).
Output: Execution mode determined + existingCount for workers
---
Phase 5a: Delegate CREATE (No Existing Stories)
Trigger: Epic has no Stories yet (first decomposition)
Delegation:
Call ln-221-story-creator via Skill tool:
```javascript
Skill(
skill: "ln-221-story-creator",
epicData: {id, title, description},
idealPlan: [ / 5-10 Stories from Phase 3 / ],
standardsResearch: "Standards Research from Phase 2",
teamId: "team-id",
autoApprove: false // or true for automation
)
```
Worker handles:
- Generate Story documents (8 sections, insert Standards Research)
- Validate INVEST criteria
- Show preview
- User confirmation (if autoApprove=false)
- Create in Linear (project=Epic, labels=user-story, state=Backlog)
- Update kanban_board.md (Epic Grouping Algorithm)
Output: Created Story URLs + summary from worker
---
Phase 5b: Delegate REPLAN (Existing Stories Found)
Trigger: Epic already has Stories (requirements changed)
Delegation:
Call ln-222-story-replanner via Skill tool:
```javascript
Skill(
skill: "ln-222-story-replanner",
epicData: {id, title, description},
idealPlan: [ / 5-10 Stories from Phase 3 / ],
standardsResearch: "Standards Research from Phase 2",
existingCount: N,
teamId: "team-id",
autoApprove: false // or true for automation
)
```
Worker handles:
- Load existing Stories (Progressive Loading: ONE BY ONE for token efficiency)
- Compare IDEAL vs existing (KEEP/UPDATE/OBSOLETE/CREATE operations)
- Show replan summary with diffs (AC, Standards Research, Technical Notes)
- User confirmation (if autoApprove=false)
- Execute operations (respecting status constraints: Backlog/Todo only, warnings for In Progress/Review/Done)
- Update kanban_board.md (add NEW Stories only via Epic Grouping Algorithm)
Output: Operation results + warnings + affected Story URLs from worker
---
Phase 5c: Delegate ADD (Append to Existing Stories)
Trigger: Epic has Stories, user wants to ADD more (not replan existing)
Delegation:
Call ln-221-story-creator via Skill tool with appendMode:
```javascript
Skill(
skill: "ln-221-story-creator",
appendMode: true, // ADD to existing, don't replace
epicData: {id, title, description},
newStoryDescription: userRequestedStory, // Single Story from user request
standardsResearch: "Standards Research from Phase 2",
teamId: "team-id",
autoApprove: false
)
```
Key differences from CREATE MODE:
appendMode: trueβ Skip full IDEAL plan, create only requested StorynewStoryDescriptionβ User's specific request (e.g., "add authorization Story")- Does NOT require Phase 3 IDEAL plan for all Stories
- Preserves existing Stories without comparison
Worker handles:
- Research standards for NEW Story only
- Generate Story document (8 sections)
- Validate INVEST criteria
- Create in Linear (append to existing)
- Update kanban_board.md
Output: Created Story URL + summary from worker
TodoWrite format (mandatory):
Add phases to todos before starting:
```
- Phase 1: Context Assembly (in_progress)
- Phase 2: Standards Research via ln-221 (pending)
- Phase 3: Build IDEAL Story Plan (pending)
- Phase 4: Check Existing Stories (pending)
- Phase 5: Delegate to ln-222/ln-223 (pending)
- Wait for worker result (pending)
```
Mark each as in_progress when starting, completed when done.
---
---
Integration with Ecosystem
Calls:
- ln-001-standards-researcher (Phase 2) - research standards/patterns for Epic
- ln-221-story-creator (Phase 5a, 5c) - CREATE and ADD worker
- ln-222-story-replanner (Phase 5b) - REPLAN worker
Called by:
- ln-200-scope-decomposer (Phase 3) - automated full decomposition (scope β Epics β Stories)
- Manual - user invokes for Epic Story creation/replanning
Upstream:
- ln-210-epic-coordinator - creates Epics (prerequisite for Story creation)
Downstream:
- ln-300-task-coordinator - creates implementation tasks for each Story
- ln-310-story-validator - validates Story structure/content
- ln-400-story-executor - orchestrates task execution for Story
---
Definition of Done
β Phase 1: Context Assembly Complete:
- [ ] Team ID, Epic number, Next Story Number loaded from kanban_board.md
- [ ] Q1-Q6 extracted from Epic (Step 2)
- [ ] Frontend Research attempted if Q2/Q5 missing (Step 3)
- [ ] Fallback Search attempted for missing info (Step 4)
- [ ] User input requested if still missing (Step 5)
- [ ] Complete Story planning context assembled
β Phase 2: Standards Research Complete:
- [ ] Epic parsed for domain keywords
- [ ] ln-001-standards-researcher invoked with Epic description + Story domain
- [ ] Standards Research cached for workers
- [ ] OR Phase 2 skipped (trivial CRUD, no standards, explicit skip)
β Phase 3: Planning Complete:
- [ ] Epic Scope analyzed
- [ ] Optimal Story count determined (5-10 Stories)
- [ ] IDEAL Story plan created (titles, statements, core AC, ordering)
- [ ] Story Grouping Guidelines validated (vertical slicing)
- [ ] INVEST checklist validated for all Stories
β Phase 4: Check Existing Complete:
- [ ] Queried Linear for existing Stories (count only)
- [ ] Execution mode determined (CREATE or REPLAN)
β Phase 5: Delegation Complete:
- [ ] Called ln-221-story-creator (Phase 5a) OR ln-222-story-replanner (Phase 5b) via Skill tool
- [ ] Passed epicData, idealPlan, standardsResearch, teamId, autoApprove
- [ ] Received output from worker (Story URLs + summary + next steps)
---
Example Usage
CREATE MODE (First Time):
```
"Create stories for Epic 7: OAuth Authentication"
```
Process:
- Phase 1: Context Assembly β Discovery (Team "API", Epic 7, US004), Extract (Persona: API client, Value: secure API access), Frontend Research (HTML login/register forms β AC), Fallback Search (requirements.md for personas)
- Phase 2: Standards Research β Epic mentions "OAuth 2.0", delegate ln-001 β Standards Research with RFC 6749, patterns
- Phase 3: Planning β Build IDEAL (5 Stories: "Register client", "Request token", "Validate token", "Refresh token", "Revoke token")
- Phase 4: Check Existing β Count = 0 β CREATE MODE
- Phase 5a: Delegate CREATE β Call ln-221-story-creator β US004-US008 created with Standards Research
REPLAN MODE (Requirements Changed):
```
"Replan stories for Epic 7 - removed custom token formats, added scope management"
```
Process:
- Phase 1: Context Assembly β Discovery (Team "API", Epic 7, has US004-US008), Extract (Removed custom formats, added scopes)
- Phase 2: Standards Research β Epic mentions "OAuth 2.0 scopes", delegate ln-001 β Updated Standards Research with RFC 6749 Section 3.3
- Phase 3: Planning β Build IDEAL (5 Stories: "Register client", "Request token", "Validate token", "Refresh token", "Manage scopes")
- Phase 4: Check Existing β Count = 5 β REPLAN MODE
- Phase 5b: Delegate REPLAN β Call ln-222-story-replanner β KEEP 4, UPDATE Technical Notes (scope research), OBSOLETE US008, CREATE US009
---
Best Practices
Story Content:
- Research-First: Always perform Phase 2 research (standards/patterns) before Story generation
- Story level: STANDARDS/PATTERNS (OAuth RFC 6749, middleware pattern)
- Task level: LIBRARIES (authlib vs oauthlib) - delegated by ln-300
- Business-oriented Stories: Each Story = USER JOURNEY (what user does, what they get), NOT technical tasks
- β GOOD: "As API client, I want to refresh expired token, so that I maintain session without re-authentication"
- β BAD: "Create token refresh endpoint in API" (Task, not Story)
- Vertical Slicing: Each Story delivers end-to-end functionality (UI β API β Service β DB)
- One capability per Story: Clear, focused persona + capability + value
- Testable AC: Given-When-Then, 3-5 AC, specific criteria ("<200ms" not "fast")
- Test Strategy: Section exists but is empty at Story creation (tests planned later by ln-510-test-planner)
- Standards Research: Include Phase 2 research in ALL Story Technical Notes
Story Decomposition:
- Decompose-First: Build IDEAL plan before checking existing - prevents anchoring to suboptimal structure
- INVEST validation: Validate every Story against INVEST criteria
- Size enforcement: 3-5 AC, 6-20 hours
- Avoid over-decomposition: <3 AC, <6 hours β Merge Stories
User Interaction:
- Epic extraction: Try to extract all planning info from Epic in Phase 1 Step 2 before asking user
- Frontend Research: HTML forms/validation β AC scenarios (Phase 1 Step 3)
- Fallback search: requirements.md, tech_stack.md if Epic incomplete (Phase 1 Step 4)
- Only ask user for missing info after Epic extraction AND frontend AND fallback search fail
Delegation:
- Orchestrator loads metadata only: ID, title, status (~50 tokens per Story)
- Workers load full descriptions: 8 sections (~5,000 tokens per Story)
- Token efficiency: 10 Stories Γ 50 tokens = 500 tokens (orchestrator) vs 10 Stories Γ 5,000 tokens = 50,000 tokens (workers load when needed)
---
Version: 5.0.0 (BREAKING: Added AC Quality Validation in Phase 3 (completeness: happy path + errors + edge cases; specificity: HTTP codes + timing). Updated INVEST Independent criterion with forward dependency check. Added Database Creation Principle to Story Grouping Guidelines per BMAD Method best practices.)
Last Updated: 2026-02-03
More from this repository10
Official marketplace for Agile Linear Workflow plugin - complete end-to-end automation for software development teams using Linear. Includes 7XX Project Bootstrap series for technology-agnostic project migration.
Generates comprehensive test documentation with testing strategy and test organization structure for software projects.
Coordinates project documentation by gathering context once, detecting project type, and delegating document creation to 5 specialized workers.
Generates design guidelines documentation for frontend projects with WCAG 2.1 compliance when a frontend framework is detected.
Generates backend documentation files (API spec and database schema) automatically when backend or database technologies are detected in a project.
Audits code comments and docstrings across 6 quality categories, generating a comprehensive compliance score and actionable recommendations for improvement.
Generates a comprehensive runbook.md for DevOps setup, dynamically tailored to project's Docker configuration and deployment specifics.
Configures global exception handling middleware for .NET and Python backend applications with standardized error responses.
Generates reference documentation structure and smart documents for project tech stack, creating only justified architectural decision records and guides.
Audits dependencies for outdated packages, unused imports, unnecessary libraries, and custom implementations, providing actionable recommendations.