Story Coordinator

When to Use This Skill

• 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

• No existing Stories → CREATE MODE (delegate to ln-221-story-creator)
• Has existing Stories → REPLAN MODE (delegate to ln-222-story-replanner)

Story Numbering Convention

shared/references/numbering_conventions.md

How It Works

Phase 1: Context Assembly

docs/tasks/kanban_board.md

1. Team ID: Reads Linear Configuration table
2. 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)
3. Next Story Number: Reads Epic Story Counters table → Gets next sequential number

1. Scan HTML files:

   Glob

   **/*.html

   ,

   src/**/*.html

2. Extract:
   • Forms → AC scenarios (e.g.,

     <form id="login">

     → "Given valid credentials, When submit, Then login success")
   • Buttons/Actions → capabilities (e.g.,

     <button id="register">

     → "User registration")
   • Validation rules → edge case AC (e.g.,

     minlength="8"

     → "Given password <8 chars, Then error")
3. Combine with Epic context, deduplicate, prioritize Epic AC if conflict

requirements.md

requirements.md

tech_stack.md

• Show extracted: "From Epic: [Epic info]. From HTML: [HTML info]. From fallback: [fallback info]"
• Ask user to confirm or provide remaining missing details

Phase 2: Standards Research (Delegated)

1. Parse Epic for domain keywords: Extract domain from Epic goal/Scope In (authentication, rate limiting, payments)
2. 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)
3. Store: Cache for Phase 5a/5b (workers insert in Story Technical Notes)

• Epic has NO standards in Technical Notes
• Story domain is trivial CRUD
• Epic says "research not needed"

Phase 3: Planning

• ✅ "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)

• ❌ "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)

• ✅ "User registration" → Creates Users table
• ✅ "Product search" → Creates Products table
• ✅ "Order checkout" → Creates Orders, Payments tables

• ❌ "Setup database" → Creates all 50 tables (no user value, violates vertical slicing)
• ❌ "Database schema" → Creates Users, Products, Orders, Payments upfront

1. Analyze Epic Scope: Review features in Epic Scope In, identify user capabilities
2. 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
3. Story Size Guidelines:

• ❌ <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)

1. 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)
2. AC Quality Validation (CRITICAL - delegates to workers):

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

• AC1: Valid credentials → login success (happy path)
• AC2: Invalid password → 401 error (error handling)
• AC3: Account locked → 403 error (edge case)

• ✅ HTTP status codes (200, 401, 403, 404)
• ✅ Measurable performance (<200ms, 99% uptime)
• ✅ Exact error messages ("Invalid credentials")

Phase 4: Check Existing & Detect Mode

list_issues(project=Epic.id, label="user-story")

1. Analyze user request for keywords:
   • ADD keywords: "add story", "one more story", "additional story", "append"
   • REPLAN keywords: "update plan", "revise", "requirements changed", "replan stories"
2. Decision matrix:

Phase 5a: Delegate CREATE (No Existing Stories)

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
)

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

Phase 5b: Delegate REPLAN (Existing Stories Found)

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
)

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

Phase 5c: Delegate ADD (Append to Existing Stories)

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
)

• appendMode: true

  → Skip full IDEAL plan, create only requested Story

• newStoryDescription

  → User's specific request (e.g., "add authorization Story")
• Does NOT require Phase 3 IDEAL plan for all Stories
• Preserves existing Stories without comparison

• Research standards for NEW Story only
• Generate Story document (8 sections)
• Validate INVEST criteria
• Create in Linear (append to existing)
• Update kanban_board.md

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

Integration with Ecosystem

• 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

• ln-200-scope-decomposer (Phase 3) - automated full decomposition (scope → Epics → Stories)
• Manual - user invokes for Epic Story creation/replanning

• ln-210-epic-coordinator - creates Epics (prerequisite for Story creation)

• 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

• 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

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

• 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

• Queried Linear for existing Stories (count only)
• Execution mode determined (CREATE or REPLAN)

• 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 stories for Epic 7: OAuth Authentication"

1. 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)
2. Phase 2: Standards Research → Epic mentions "OAuth 2.0", delegate ln-001 → Standards Research with RFC 6749, patterns
3. Phase 3: Planning → Build IDEAL (5 Stories: "Register client", "Request token", "Validate token", "Refresh token", "Revoke token")
4. Phase 4: Check Existing → Count = 0 → CREATE MODE
5. Phase 5a: Delegate CREATE → Call ln-221-story-creator → US004-US008 created with Standards Research

"Replan stories for Epic 7 - removed custom token formats, added scope management"

1. Phase 1: Context Assembly → Discovery (Team "API", Epic 7, has US004-US008), Extract (Removed custom formats, added scopes)
2. Phase 2: Standards Research → Epic mentions "OAuth 2.0 scopes", delegate ln-001 → Updated Standards Research with RFC 6749 Section 3.3
3. Phase 3: Planning → Build IDEAL (5 Stories: "Register client", "Request token", "Validate token", "Refresh token", "Manage scopes")
4. Phase 4: Check Existing → Count = 5 → REPLAN MODE
5. Phase 5b: Delegate REPLAN → Call ln-222-story-replanner → KEEP 4, UPDATE Technical Notes (scope research), OBSOLETE US008, CREATE US009

Reference Files

• [MANDATORY] Problem-solving approach:

  shared/references/problem_solving.md

• Orchestrator lifecycle:

  shared/references/orchestrator_pattern.md

• Auto-discovery patterns:

  shared/references/auto_discovery_pattern.md

• Decompose-first pattern:

  shared/references/decompose_first_pattern.md

• Numbering conventions:

  shared/references/numbering_conventions.md

  (Story sequential across Epics)

Best Practices

• 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

• 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

• 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

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