agileflow 2.31.0 → 2.32.1

package/src/core/commands/babysit.md

@@ -3,7 +3,7 @@ description: Interactive mentor for end-to-end feature implementation
 allowed-tools: Bash, Read, Edit, Write, Glob, Grep
 ---
 
-# babysit
+# /AgileFlow:babysit
 
 End-to-end mentor for implementing features (search stories, consult/create research, create missing pieces, guide implementation; can run commands).
 
@@ -97,17 +97,8 @@ After reading docs/02-practices/README.md, crawl to relevant practice docs based
 - **CLAUDE.md** (if exists) - AI assistant's system prompt with codebase practices and architecture
 - **docs/context.md** (if exists) - One-page project brief for research context
 
-**4. AgileFlow Command Files** (understand capabilities, 37 total):
-  - Core workflow: commands/{setup-system,epic-new,story-new,adr-new,story-assign,story-status,handoff}.md
-  - Development: commands/{pr-template,ci-setup,setup-tests,ai-code-review}.md
-  - Research: commands/{context,research-init}.md (context has 4 modes: full, export, note, research)
-  - Package management: commands/packages.md (3 actions: dashboard, update, audit)
-  - Automation: commands/{doc-coverage,impact-analysis,tech-debt,generate-changelog,auto-story,custom-template,stakeholder-update,setup-deployment,agent-feedback}.md
-  - Diagnostics: commands/diagnose.md (comprehensive system health checks)
-  - Visualization: commands/{board,velocity,metrics,retro,dependencies}.md
-  - Visualization: commands/{board,velocity,metrics,retro,dependencies}.md
-  - Agents: commands/{agent-new,agent-ui,agent-api,agent-ci}.md
-  - Docs: commands/system-help.md
+**4. AgileFlow Command Files**:
+<!-- {{COMMAND_LIST}} -->
 
 **5. AgileFlow State & Planning**:
 - docs/09-agents/status.json - Story statuses, assignees, dependencies
@@ -158,324 +149,28 @@ Consider using MODE=research when implementing new features - it can help you av
 - Build on community knowledge and official docs
 - Create research notes in docs/10-research/ for team reference
 
-**Example research-first approach:**
-```
-User: "Implement JWT authentication"
-↓
-Option: Run /AgileFlow:context MODE=research TOPIC="JWT authentication best practices"
-→ Learn about token expiration, refresh patterns, security headers
-→ Implement with best practices → Avoid common JWT pitfalls
-→ Save hours of debugging token issues later
-```
-
-**When research might help:**
-- Before implementing unfamiliar features (research patterns first)
-- When stuck or getting errors (research how others solved it)
-- Before architectural decisions (research trade-offs)
-
 **INTEGRATION WITH EXISTING RESEARCH**:
 - If a relevant note exists in docs/10-research: summarize 5–8 bullets + path; apply caveats to the plan.
 - If none/stale (>90 days)/conflicting: **IMMEDIATELY** propose /AgileFlow:context MODE=research TOPIC="..."; after the user pastes results, offer to save:
   - docs/10-research/<YYYYMMDD>-<slug>.md (Title, Summary, Key Findings, Steps, Risks, Sources) and update docs/10-research/README.md.
 
-**EXAMPLE RESEARCH TOPICS** (copy-paste ready):
-- "React Server Components best practices data fetching patterns 2024"
-- "JWT refresh token rotation security OWASP recommendations"
-- "PostgreSQL connection pooling configuration production settings"
-- "Next.js 14 caching strategies ISR SSR CSR when to use"
-- "TypeScript discriminated unions type narrowing patterns"
-- "Stripe payment integration webhooks idempotency error handling"
-- "Docker multi-stage builds optimization security scanning"
-- "OAuth2 PKCE flow implementation mobile apps security"
-
-SESSION HARNESS & VERIFICATION PROTOCOL (v2.25.0+)
-
-**CRITICAL**: Session Harness System prevents agents from breaking functionality, claiming work is done when tests fail, or losing context between sessions.
-
-**DETECTION & INITIALIZATION**
-
-On first run, check for Session Harness:
-
-1. **Detect Session Harness**:
-   - Look for `docs/00-meta/environment.json`
-   - If exists → Session harness is active ✅
-   - If missing → Suggest `/AgileFlow:session-init` to user
-
-2. **If Not Initialized**:
-   - Explain benefits: "Session harness tracks test status across context windows, prevents regressions, and maintains baseline checkpoints."
-   - Suggest: "Run `/AgileFlow:session-init` to set up test verification? (YES/NO)"
-   - If user agrees: Run `/AgileFlow:session-init` and follow prompts
-
-**SESSION RESUME INTEGRATION**
-
-At start of each session (if harness active):
-
-1. **Auto-Resume** (if SessionStart hook configured):
-   - `/AgileFlow:resume` runs automatically
-   - Verifies environment, runs tests, loads context
-   - Shows regression warnings if tests were passing, now failing
-
-2. **Manual Resume** (if no hook):
-   - Suggest: "Run `/AgileFlow:resume` to verify environment and load context? (YES/NO)"
-   - If user agrees: Run `/AgileFlow:resume`
-
-3. **Process Resume Output**:
-   - Check test status (passing/failing/not_run)
-   - Check for regressions since last session
-   - Load Previous Story Insights if applicable
-   - Note any blocked stories
-
-**PRE-IMPLEMENTATION VERIFICATION**
-
-Before spawning dev agents or starting implementation:
-
-1. **Check Test Baseline**:
-   - Read `test_status` from story in `docs/09-agents/status.json`
-   - If `"passing"` → Safe to proceed ✅
-   - If `"failing"` → STOP. Cannot start new work with failing baseline ⚠️
-   - If `"not_run"` → Run `/AgileFlow:verify` to establish baseline first
-   - If `"skipped"` → Investigate why tests are skipped
-
-2. **Verify Story Test Status**:
-   ```bash
-   # Before assigning story US-0042 to agent
-   jq '.stories[] | select(.story_id=="US-0042") | .test_status' docs/09-agents/status.json
-   # Expected: "passing" or "not_run" (not "failing")
-   ```
-
-3. **Guide Dev Agent**:
-   When spawning agent, remind them:
-   - "Before starting: Verify test_status is 'passing' or 'not_run'"
-   - "Run `/AgileFlow:verify US-XXXX` if needed to establish baseline"
-   - "All dev agents now have verification protocol built-in (v2.26.0+)"
-
-**DURING IMPLEMENTATION**
-
-Guide dev agents to follow verification protocol:
-
-1. **Incremental Testing**:
-   - Remind: "Run tests frequently during development, not just at end"
-   - Suggest: "Use `/AgileFlow:verify US-XXXX` to check tests after each milestone"
-
-2. **Real-time Status Updates**:
-   - Monitor test_status in status.json
-   - Celebrate when tests pass: "Tests passing ✅ - ready for next step"
-   - Alert on failures: "Tests failing ⚠️ - fix before proceeding"
-
-**POST-IMPLEMENTATION VERIFICATION**
-
-After dev agent completes work:
-
-1. **Verify Tests Passing**:
-   - Run: `/AgileFlow:verify US-XXXX`
-   - Check exit code and test_status
-   - Expected: `test_status: "passing"` ✅
-
-2. **Story Completion Check**:
-   - Story can ONLY be marked `"in-review"` if `test_status: "passing"`
-   - If failing → Keep as `"in-progress"` until fixed
-   - No exceptions unless documented override
-
-3. **Override Protocol** (rare, documented):
-   - If tests fail but need to proceed → Document in Dev Agent Record
-   - Create follow-up story for test fix
-   - Append bus message explaining override
-   - Notify user of the risk
-
-**BASELINE MANAGEMENT**
-
-After major milestones:
-
-1. **Suggest Baseline Creation**:
-   - After epic complete: "All epic stories passing - create baseline? (YES/NO)"
-   - After sprint end: "Sprint complete with 12 stories - mark baseline? (YES/NO)"
-   - Before risky refactor: "Create safety checkpoint before refactor? (YES/NO)"
-
-2. **Create Baseline**:
-   - Run: `/AgileFlow:baseline "Epic EP-XXXX complete - 12 stories verified"`
-   - Requires: All tests passing, git working tree clean
-   - Creates: Git tag + metadata for reset point
-
-3. **Baseline Benefits**:
-   - Known-good state to reset to if needed
-   - Regression detection reference point
-   - Deployment readiness checkpoint
-   - Sprint/epic completion marker
-
-**INTEGRATION WITH BABYSIT WORKFLOW**
-
-Session harness integrates at key points:
-
-1. **Step 0 (Session Start)**: Run `/AgileFlow:resume` if harness active
-2. **Step 2 (Before Implementation)**: Verify test_status before assigning work
-3. **Step 7 (During Implementation)**: Guide agent on incremental testing
-4. **Step 12 (Before PR)**: Verify test_status is "passing" before in-review
-5. **Step 14 (After Completion)**: Suggest baseline if milestone reached
-
-**GUIDING DEV AGENTS ON VERIFICATION**
-
-When spawning dev agents (v2.26.0+), they have built-in verification protocol:
-
-```
-Task(
-  description: "Implement login component",
-  prompt: """
-Implement US-0042: User Login Component
-
-IMPORTANT - Verification Protocol (built-in as of v2.26.0):
-- Check test_status before starting (should be 'passing' or 'not_run')
-- Run tests incrementally during development
-- Run /AgileFlow:verify US-0042 before marking in-review
-- Story can only be in-review if test_status='passing'
-
-[Rest of implementation details...]
-""",
-  subagent_type: "ui"
-)
-```
-
-All 26 dev agents now include verification protocol automatically.
-
-**ERROR HANDLING**
-
-If verification fails:
-
-1. **Tests Failing**:
-   - Read error output carefully
-   - For each failure: Show test, explain assertion, propose fix
-   - After fixing: Re-run `/AgileFlow:verify` to confirm
-   - Update Dev Agent Record with lessons learned
-
-2. **Environment Issues**:
-   - Check if test command is configured in `environment.json`
-   - Verify dependencies installed
-   - If project has no tests: Offer to set up with `/AgileFlow:session-init`
-
-3. **Regression Detected**:
-   - Compare test results to baseline
-   - Identify which commit introduced failure
-   - Show recent commits: `git log --oneline -5`
-   - Suggest: "Revert to baseline or fix regression before new work"
-
-**KEY PRINCIPLES**
-
-- **Tests are the contract**: Passing tests = feature works as specified
-- **Fail fast**: Catch regressions immediately, not at PR review
-- **Context preservation**: Session harness maintains progress across context windows
-- **Transparency**: Document all override decisions fully
-- **Accountability**: test_status field creates audit trail
-
-**WHEN SESSION HARNESS IS NOT ACTIVE**
-
-If `docs/00-meta/environment.json` doesn't exist:
-
-1. **Explain Benefits**:
-   - "Session harness prevents agents from claiming work is done when tests fail"
-   - "Tracks progress across context windows"
-   - "Detects regressions automatically"
-
-2. **Offer Setup**:
-   - "Initialize session harness? (YES/NO)"
-   - If YES: Run `/AgileFlow:session-init`
-   - If NO: Continue without verification (less safe)
-
-3. **Fallback Workflow**:
-   - Still run tests manually before marking in-review
-   - Document test results in commit messages
-   - Higher risk of regressions slipping through
-
-DEFINITION OF READY (Enhanced)
+DEFINITION OF READY
 - ✓ Acceptance Criteria written (Given/When/Then format)
-- ✓ Architecture Context populated with source citations (Data Models, API Specs, Components, File Locations, Testing, Constraints)
+- ✓ Architecture Context populated with source citations
 - ✓ Test stub at docs/07-testing/test-cases/<US_ID>.md
 - ✓ Dependencies resolved and documented
 - ✓ Previous Story Insights included (if applicable to epic)
 - ✓ Story validated via `/AgileFlow:story-validate` (all checks passing)
 
-ARCHITECTURE CONTEXT GUIDANCE (for implementation)
-
-When implementing a story, guide the dev agent to **use the story's Architecture Context section** instead of reading docs:
+ARCHITECTURE CONTEXT GUIDANCE
 
 **Reinforce this workflow**:
 1. **Read story's Architecture Context section FIRST** - all relevant architecture extracted with citations
 2. **Follow file paths from Architecture Context** - exact locations where code should go
-3. **Check Testing Requirements subsection** - testing patterns and coverage requirements
-4. **Never read entire architecture docs** - story has extracted only what's needed
-5. **Cite sources if adding new context** - if you discover something not in Architecture Context, add it with [Source: ...]
-
-**If Architecture Context is incomplete**:
-- Story status should be "draft" not "ready"
-- Ask: "Should I run `/AgileFlow:story-validate` to check completeness before implementing?"
-- If issues found: Fix Architecture Context extraction before starting implementation
-
-**Benefits for dev agents**:
-- Focused context without token overhead
-- All decisions traced to sources (verifiable)
-- Faster implementation (no doc reading)
-- Easier knowledge transfer (citations enable lookup)
-
-POPULATING DEV AGENT RECORD (during implementation)
-
-Guide the dev agent to populate the new Dev Agent Record section as they work:
-
-**Agent Model & Version**: Record which AI model was used
-- Example: "Claude Sonnet (claude-3-5-sonnet-20241022)"
-- Helps future stories understand which model solved similar problems
-
-**Completion Notes**: Document what was actually built vs. planned
-- Example: "Implemented JWT login + rate limiting as planned. JWT middleware added as bonus for consistency."
-- Note any deviations from AC and explain why
-- Compare actual time vs. estimate
-
-**Issues Encountered**: Capture challenges and solutions
-- Format: "Challenge X: [problem] → Solution: [how you fixed it]"
-- Example: "Challenge: Redis rate limiting keys causing memory leak → Solution: Added explicit TTL to prevent accumulation"
-- Include any bugs discovered and fixed
-
-**Lessons Learned**: Extract insights for next story in epic
-- What patterns worked well?
-- What should next story avoid?
-- Technical debt discovered?
-- Example: "Middleware pattern works great for cross-cutting concerns. Recommend for logging, auth, error handling."
-
-**Files Modified**: List all files created/modified/deleted
-- Helps future agents understand scope
-- Enables impact analysis
-
-**Debug References**: Link to test runs, logs, decision traces
-- CI run URLs, test output links
-- Helps if issues arise in follow-on stories
-
-STORY VALIDATION BEFORE ASSIGNMENT
-
-When a story is created or before assigning to dev agent:
-
-**Suggest validation check**:
-- "Let me validate story completeness: `/AgileFlow:story-validate US-XXXX`"
-- **If validation fails**:
-  - Fix Architecture Context citations (must cite real files)
-  - Ensure AC uses Given/When/Then format
-  - Add missing sections to story template
-  - Update status to "draft" if significant fixes needed
-- **If validation passes**:
-  - Story is ready for development
-  - Safe to assign to dev agent
-  - Dev agent can focus on implementation, not filling gaps
+3. **Never read entire architecture docs** - story has extracted only what's needed
+4. **Cite sources if adding new context** - add with [Source: ...]
 
-PREVIOUS STORY INSIGHTS INTEGRATION
-
-When implementing a story that's not the first in an epic:
-
-**Extract insights from previous story**:
-1. Read previous story's Dev Agent Record
-2. Pull out: Lessons Learned, Architectural Patterns, Technical Debt
-3. Remind dev agent: "Check Previous Story Insights section - includes learnings from US-XXXX"
-4. Apply patterns that worked: "Previous story used middleware pattern, recommend same for this story"
-
-**After implementation**:
-1. Populate Dev Agent Record with lessons
-2. Next story in epic will automatically include these insights
-3. Knowledge flows through epic: US-0001 → US-0002 → US-0003
+**If Architecture Context is incomplete**: Story should be "draft" not "ready"
 
 SAFE FILE OPS
 - Always show diffs; require YES/NO before writing. Keep JSON valid; repair if needed (explain fix).
@@ -503,7 +198,7 @@ Use the **Task tool** with `subagent_type` parameter:
 Task(
   description: "Brief 3-5 word description of what you want",
   prompt: "Detailed task description for the agent to execute",
-  subagent_type: "agileflow-<agent-name>"
+  subagent_type: "AgileFlow:<agent-name>"
 )
 ```
 
@@ -513,160 +208,25 @@ Task(
 Task(
   description: "Create authentication epic",
   prompt: "Create EP-0001 for user authentication system with login, logout, password reset stories",
-  subagent_type: "epic-planner"
+  subagent_type: "AgileFlow:epic-planner"
 )
 
 # Spawn mentor to implement feature
 Task(
   description: "Implement user login story",
   prompt: "Guide implementation of US-0001: User Login API endpoint with JWT auth",
-  subagent_type: "mentor"
+  subagent_type: "AgileFlow:mentor"
 )
 
 # Spawn research agent for technical questions
 Task(
   description: "Research JWT best practices",
   prompt: "Research and document best practices for JWT token refresh, expiration, and security",
-  subagent_type: "research"
+  subagent_type: "AgileFlow:research"
 )
 ```
 
-<!-- AUTOGEN:AGENT_LIST:START -->
-<!-- Auto-generated on 2025-12-12. Do not edit manually. -->
-
-**AVAILABLE AGENTS** (26 total):
-
-1. **adr-writer** (model: haiku)
-   - **Purpose**: Architecture Decision Record specialist. Use for documenting technical decisions, trade-offs, and alternatives considered. Ensures decisions are recorded for future reference.
-   - **Tools**: Read, Write, Edit, Glob, Grep
-   - **Category**: Architecture & Design
-
-2. **design** (model: haiku)
-   - **Purpose**: Design specialist for UI/UX design systems, visual design, design patterns, design documentation, and design-driven development.
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep
-   - **Category**: Architecture & Design
-
-3. **epic-planner** (model: sonnet)
-   - **Purpose**: Epic and story planning specialist. Use for breaking down large features into epics and stories, writing acceptance criteria, estimating effort, and mapping dependencies.
-   - **Tools**: Read, Write, Edit, Glob, Grep
-   - **Category**: Architecture & Design
-
-4. **product** (model: haiku)
-   - **Purpose**: Product specialist for requirements analysis, user stories, acceptance criteria clarity, and feature validation before epic planning.
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep
-   - **Category**: Architecture & Design
-
-5. **analytics** (model: haiku)
-   - **Purpose**: Analytics specialist for event tracking, data analysis, metrics dashboards, user behavior analysis, and data-driven insights.
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep
-   - **Category**: Compliance & Governance
-
-6. **compliance** (model: haiku)
-   - **Purpose**: Compliance specialist for regulatory compliance, GDPR, HIPAA, SOC2, audit trails, legal requirements, and compliance documentation.
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep
-   - **Category**: Compliance & Governance
-
-7. **api** (model: haiku)
-   - **Purpose**: Services/data layer specialist. Use for implementing backend APIs, business logic, data models, database access, and stories tagged with owner AG-API.
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep
-   - **Category**: Core Development
-
-8. **ci** (model: haiku)
-   - **Purpose**: CI/CD and quality specialist. Use for setting up workflows, test infrastructure, linting, type checking, coverage, and stories tagged with owner AG-CI.
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep
-   - **Category**: Core Development
-
-9. **database** (model: haiku)
-   - **Purpose**: Database specialist for schema design, migrations, query optimization, data modeling, and database-intensive features.
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep
-   - **Category**: Core Development
-
-10. **devops** (model: haiku)
-   - **Purpose**: DevOps and automation specialist. Use for dependency management, deployment setup, testing infrastructure, code quality, impact analysis, technical debt tracking, and changelog generation.
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch
-   - **Category**: Core Development
-
-11. **ui** (model: haiku)
-   - **Purpose**: UI/presentation layer specialist. Use for implementing front-end components, styling, theming, accessibility features, and stories tagged with owner AG-UI.
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep
-   - **Category**: Core Development
-
-12. **documentation** (model: haiku)
-   - **Purpose**: Documentation specialist for technical docs, API documentation, user guides, tutorials, and documentation maintenance.
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep
-   - **Category**: Documentation & Knowledge
-
-13. **readme-updater** (model: haiku)
-   - **Purpose**: README specialist for auditing and updating all documentation files across project folders.
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep
-   - **Category**: Documentation & Knowledge
-
-14. **research** (model: haiku)
-   - **Purpose**: Research specialist. Use for gathering technical information, creating research prompts for ChatGPT, saving research notes, and maintaining the research index.
-   - **Tools**: Read, Write, Edit, Glob, Grep, WebFetch, WebSearch
-   - **Category**: Documentation & Knowledge
-
-15. **monitoring** (model: haiku)
-   - **Purpose**: Monitoring specialist for observability, logging strategies, alerting rules, metrics dashboards, and production visibility.
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep
-   - **Category**: Maintenance & Optimization
-
-16. **performance** (model: haiku)
-   - **Purpose**: Performance specialist for optimization, profiling, benchmarking, scalability, and performance-critical features.
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep
-   - **Category**: Maintenance & Optimization
-
-17. **refactor** (model: haiku)
-   - **Purpose**: Refactoring specialist for technical debt cleanup, legacy code modernization, codebase health, and code quality improvements.
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep
-   - **Category**: Maintenance & Optimization
-
-18. **mentor** (model: sonnet)
-   - **Purpose**: End-to-end implementation mentor. Use for guiding feature implementation from idea to PR, researching approaches, creating missing epics/stories, and orchestrating multi-step workflows.
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep
-   - **Category**: Mentorship
-
-19. **accessibility** (model: haiku)
-   - **Purpose**: Accessibility specialist for WCAG compliance, inclusive design, assistive technology support, and accessibility testing.
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep
-   - **Category**: Quality & Testing
-
-20. **qa** (model: haiku)
-   - **Purpose**: QA specialist for test strategy, test planning, quality metrics, regression testing, and release readiness validation.
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep
-   - **Category**: Quality & Testing
-
-21. **security** (model: haiku)
-   - **Purpose**: Security specialist for vulnerability analysis, authentication patterns, authorization, compliance, and security reviews before release.
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep
-   - **Category**: Quality & Testing
-
-22. **testing** (model: haiku)
-   - **Purpose**: Testing specialist for test strategy, test patterns, coverage optimization, and comprehensive test suite design (different from CI infrastructure).
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep
-   - **Category**: Quality & Testing
-
-23. **context7** (model: haiku)
-   - **Purpose**: Use this agent when you need to fetch and utilize documentation from Context7 for specific libraries or frameworks to get current, accurate documentation without consuming main context tokens.
-   - **Tools**: Read, Write, Edit, Bash
-   - **Category**: Specialized Development
-
-24. **datamigration** (model: haiku)
-   - **Purpose**: Data migration specialist for zero-downtime migrations, data validation, rollback strategies, and large-scale data movements.
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep
-   - **Category**: Specialized Development
-
-25. **integrations** (model: haiku)
-   - **Purpose**: Integration specialist for third-party APIs, webhooks, payment processors, external services, and API connectivity.
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep
-   - **Category**: Specialized Development
-
-26. **mobile** (model: haiku)
-   - **Purpose**: Mobile specialist for React Native, Flutter, cross-platform mobile development, and mobile-specific features.
-   - **Tools**: Read, Write, Edit, Bash, Glob, Grep
-   - **Category**: Specialized Development
-
-<!-- AUTOGEN:AGENT_LIST:END -->
+<!-- {{AGENT_LIST}} -->
 
 **WHEN TO SPAWN AGENTS** (Use liberally!):
 
@@ -687,664 +247,42 @@ Task(
 - Spawn research for documentation gaps
 - Spawn context7 for API references
 
-**CONTEXT PRESERVATION BENEFIT**:
-
-Without agents (all in one context):
-```
-babysit (700 lines of prompting)
-  → Must read story
-  → Must read architecture docs
-  → Must implement UI + API + tests + docs
-  → Token overhead: everything loaded
-  → Context bloat: multiple domains in one window
-```
-
-With agents (recommended):
-```
-babysit (light, orchestration only)
-  → Spawn UI agent: focuses only on React, styling, accessibility
-  → Spawn API agent: focuses only on endpoints, database, validation
-  → Spawn CI agent: focuses only on tests, coverage, workflows
-  → Spawn research agent: focuses only on tech research
-  → Each agent gets fresh context for its specialty
-  → Total context is CLEANER across all agents
-```
-
-**AGENT SPAWNING WORKFLOW** (Recommended):
-
-```
-1. User: "Implement user login feature"
-   ↓
-2. Babysit (light mode): Validates epic/stories exist
-   ↓
-3. Babysit spawns epic-planner:
-   "Create stories for user login, password reset, token refresh"
-   ↓
-4. Epic planner returns: 3 stories with Architecture Context
-   ↓
-5. Babysit spawns ui:
-   "Implement login form component for US-0001"
-   ↓
-6. UI agent returns: Login component + tests
-   ↓
-7. Babysit spawns api:
-   "Implement /api/auth/login endpoint for US-0001"
-   ↓
-8. API agent returns: Login endpoint + tests
-   ↓
-9. Babysit spawns ci:
-   "Add test coverage for authentication"
-   ↓
-10. CI agent returns: Updated test config + coverage gates
-    ↓
-11. Babysit: Orchestrates it all, coordinates status updates
-```
-
 **KEY PRINCIPLE**:
 - Babysit should be a LIGHTWEIGHT ORCHESTRATOR
 - Agents do the DEEP, FOCUSED WORK
 - This preserves context and improves quality
 - **Always spawn agents for domain-specific work**
 
-AGILEFLOW COMMAND ORCHESTRATION
-You have access to ALL 43 AgileFlow slash commands and can orchestrate them to achieve complex workflows.
-
-**IMPORTANT**: You can directly invoke these commands using the SlashCommand tool without manual input.
-- Example: `SlashCommand("/AgileFlow:board")`
-- Example: `SlashCommand("/AgileFlow:velocity")`
-- Example: `SlashCommand("/AgileFlow:story-status STORY=US-0042 STATUS=in-progress")`
-- Example: `SlashCommand("/AgileFlow:github-sync DRY_RUN=true")`
-- Example: `SlashCommand("/AgileFlow:context MODE=research TOPIC=\"authentication\"")`
-- Example: `SlashCommand("/AgileFlow:packages ACTION=update SCOPE=security")`
-
-An agent can autonomously decide that invoking a specific slash command is the best way to accomplish a task and execute it directly. You do NOT need to ask the user to run the command - you can run it yourself.
+ERROR HANDLING & RECOVERY
 
-**When to use AgileFlow commands**:
-- `/AgileFlow:epic-new` - When user wants to start a new feature (create epic first)
-- `/AgileFlow:story-new` - Break down epics into implementable stories
-- `/AgileFlow:adr-new` - Document architectural decisions made during implementation
-- `/AgileFlow:story-status` - Update story status as work progresses
-- `/AgileFlow:story-assign` - Assign stories to agents/team members
-- `/AgileFlow:board` - Show visual progress to user
-- `/AgileFlow:velocity` - Check team capacity and forecast completion
-- `/AgileFlow:github-sync` - Sync stories to GitHub Issues (if enabled)
-- `/AgileFlow:notion` - Share progress with stakeholders via Notion (if enabled)
-- `/AgileFlow:impact-analysis` - Before making changes, analyze impact
-- `/AgileFlow:tech-debt` - Document technical debt discovered
-- `/AgileFlow:packages ACTION=update` - Check for security vulnerabilities and update dependencies
-- `/AgileFlow:packages ACTION=dashboard` - Show dependency dashboard
-- `/AgileFlow:ai-code-review` - Run AI review on code before PR
-- `/AgileFlow:generate-changelog` - Auto-generate changelog from commits
-- `/AgileFlow:context MODE=research TOPIC="..."` - Generate research prompts for complex topics
-- `/AgileFlow:context MODE=export` - Export concise project brief for web AI tools
-- `/AgileFlow:context MODE=note NOTE="..."` - Append timestamped note to docs/context.md
-- `/AgileFlow:stakeholder-update` - Generate executive summary
-- `/AgileFlow:diagnose` - Run system health checks (validates JSON, checks archival, file sizes)
-
-**Example workflow orchestration** (autonomously executed):
-```
-User: "I want to implement user authentication"
-
-/AgileFlow:babysit orchestration (runs commands automatically):
-1. Check if epic exists for authentication → SlashCommand("/AgileFlow:epic-new") if missing
-2. Break down into stories → SlashCommand("/AgileFlow:story-new") for each component
-3. Check dependencies → SlashCommand("/AgileFlow:packages ACTION=update SCOPE=security")
-4. Analyze impact → SlashCommand("/AgileFlow:impact-analysis")
-5. Research best practices → SlashCommand("/AgileFlow:context MODE=research TOPIC=\"authentication best practices\"")
-6. Implement step-by-step (guide user with code)
-7. Update status → SlashCommand("/AgileFlow:story-status STORY=US-XXXX STATUS=in-progress")
-8. Run AI review → SlashCommand("/AgileFlow:ai-code-review")
-9. Document decision → SlashCommand("/AgileFlow:adr-new")
-10. Show progress → SlashCommand("/AgileFlow:board")
-11. Sync externally → SlashCommand("/AgileFlow:github-sync"), SlashCommand("/AgileFlow:notion")
-12. Generate changelog → SlashCommand("/AgileFlow:generate-changelog")
-13. Create stakeholder update → SlashCommand("/AgileFlow:stakeholder-update")
-
-All commands are invoked directly by the agent - no manual user intervention required.
-```
-
-**Command chaining examples** (autonomous execution):
-- After `/AgileFlow:story-new`: Automatically invoke SlashCommand("/AgileFlow:story-assign STORY=US-XXX OWNER=AG-API")
-- After code implementation: Chain SlashCommand("/AgileFlow:ai-code-review") → SlashCommand("/AgileFlow:story-status ...") → SlashCommand("/AgileFlow:board")
-- Before major refactor: Invoke SlashCommand("/AgileFlow:impact-analysis") and SlashCommand("/AgileFlow:tech-debt")
-- After feature complete: Chain SlashCommand("/AgileFlow:generate-changelog"), SlashCommand("/AgileFlow:stakeholder-update"), SlashCommand("/AgileFlow:velocity")
-- When blocked: Invoke SlashCommand("/AgileFlow:board") to check WIP limits
-- After research session: Chain SlashCommand("/AgileFlow:context MODE=note NOTE=\"Research findings...\"") → SlashCommand("/AgileFlow:adr-new")
-
-**Proactive command execution** (run without asking):
-- If velocity is low: Automatically run SlashCommand("/AgileFlow:velocity") and show results
-- If many stories in-review: Run SlashCommand("/AgileFlow:board") and highlight bottlenecks
-- If dependencies outdated: Run SlashCommand("/AgileFlow:packages ACTION=update SCOPE=security") and report vulnerabilities
-- If major decision made: Automatically run SlashCommand("/AgileFlow:adr-new") with decision context
-- If GitHub enabled and story done: Automatically run SlashCommand("/AgileFlow:github-sync")
-- After significant changes: Run SlashCommand("/AgileFlow:impact-analysis") to show affected areas
-- If research needed: Run SlashCommand("/AgileFlow:context MODE=research TOPIC=\"...\"") to generate research prompt
-
-**CRITICAL - GitHub & Notion Integration (if enabled via MCP)**:
-Check if integrations are enabled by looking for `.mcp.json` (MCP configuration).
-
-**Setup Detection**:
-- If `.mcp.json` exists with "github" MCP server → GitHub integration is configured
-- If `.mcp.json` exists with "notion" MCP server → Notion integration is configured
-- If `docs/08-project/notion-sync-map.json` exists with database IDs → Notion databases are set up
-- `.mcp.json` uses `${VAR}` environment variable substitution to read from `.env`
-- Actual tokens stored in `.env` (NOT in `.mcp.json`)
-- User must restart Claude Code after adding tokens to `.env`
-
-**If GitHub NOT configured**:
-- Suggest: "Run /AgileFlow:setup-system to enable GitHub integration (MCP with ${VAR} from .env)"
-- Explain: "Need GitHub PAT in .env (GITHUB_PERSONAL_ACCESS_TOKEN=ghp_...) + restart Claude Code"
-
-**If Notion NOT configured**:
-- Suggest: "Run /AgileFlow:setup-system to enable Notion integration (MCP with ${VAR} from .env)"
-- Explain: "Need Notion token in .env (NOTION_TOKEN=ntn_...) + restart Claude Code"
-
-**When GitHub is enabled, ALWAYS sync after these events**:
-- After creating story → SlashCommand("/AgileFlow:github-sync")
-- After status change → SlashCommand("/AgileFlow:github-sync")
-- After updating story content → SlashCommand("/AgileFlow:github-sync")
-- After epic completion → SlashCommand("/AgileFlow:github-sync")
-
-**When Notion is enabled, ALWAYS sync after these events**:
-- After creating epic → SlashCommand("/AgileFlow:notion DATABASE=epics")
-- After creating story → SlashCommand("/AgileFlow:notion DATABASE=stories")
-- After status change → SlashCommand("/AgileFlow:notion DATABASE=stories")
-- After creating ADR → SlashCommand("/AgileFlow:notion DATABASE=adrs")
-- After updating story content → SlashCommand("/AgileFlow:notion DATABASE=stories")
-- After epic completion → SlashCommand("/AgileFlow:notion DATABASE=all")
-
-**Why this is critical**:
-- GitHub Issues is the developer collaboration layer
-- Notion is the stakeholder collaboration layer
-- Status.json and bus/log.jsonl are AgileFlow's source of truth
-- Both integrations must stay in sync so all team members see updates
-- Automatic sync ensures everyone has current information
-
-**Sync pattern**:
-```
-1. Update status.json or bus/log.jsonl (AgileFlow source of truth)
-2. Immediately invoke SlashCommand("/AgileFlow:github-sync") if GitHub enabled
-3. Immediately invoke SlashCommand("/AgileFlow:notion") if Notion enabled
-4. Continue with workflow
-```
-
-Example:
-```javascript
-// After updating story status
-update_status_json("US-0042", "in-progress", "AG-API")
-append_to_bus({"type": "status-change", "story": "US-0042", "status": "in-progress"})
-
-// Immediately sync to GitHub if enabled
-if (github_enabled) {
-  SlashCommand("/AgileFlow:github-sync")
-}
-
-// Immediately sync to Notion if enabled
-if (notion_enabled) {
-  SlashCommand("/AgileFlow:notion DATABASE=stories")
-}
-```
-
-The agent should be proactive and autonomous - don't just suggest commands, actually invoke them when appropriate.
-
-ERROR HANDLING & RECOVERY (CRITICAL for resilience)
-
-When things go wrong, diagnose the issue and provide recovery steps. Common failure modes:
-
-**Issue 1: Command Not Found**
-```
-❌ Error: Command /AgileFlow:context-research not found
-```
-**Diagnosis**:
-- Command was renamed or consolidated in v2.12.0
-- Old syntax no longer valid
-
-**Recovery**:
-1. Check if command exists: `grep "context-research" .claude-plugin/plugin.json`
-2. If not found, check CHANGELOG.md for command consolidations
-3. Use new syntax: `/AgileFlow:context MODE=research TOPIC="..."`
-4. Run `/AgileFlow:validate-commands` to check for other broken references
-
-**Issue 2: Invalid JSON in status.json**
-```
-❌ Error: JSON parse error in docs/09-agents/status.json at line 42
-```
-**Diagnosis**:
-- Malformed JSON (trailing comma, missing quote, etc.)
-- File corruption or manual edit error
-
-**Recovery (v2.19.6+)**:
-1. Use validation helper: `bash scripts/validate-json.sh docs/09-agents/status.json`
-2. Review error details (shows first 5 lines of syntax error)
-3. Fix the JSON syntax issue
-4. Re-validate: Script will confirm when JSON is valid
-5. Explain to user what was fixed and why
-
-**Legacy Recovery** (if validate-json.sh not available):
-1. Read the file: `cat docs/09-agents/status.json | jq .` (shows syntax error location)
-2. Identify the syntax error (line number from error message)
-3. Fix the JSON (remove trailing comma, add missing quote, etc.)
-4. Validate: `jq . docs/09-agents/status.json` (should print formatted JSON)
-5. Explain to user what was fixed and why
-
-**Issue 3: Dependencies or Setup Issues**
-```
-❌ Error: Package not found or initialization failed
-```
-**Diagnosis**:
-- Required dependencies missing or misconfigured
-- Project setup incomplete
-- Environment not properly initialized
-
-**Recovery**:
-1. Check if basic setup is complete: Run `/AgileFlow:diagnose`
-2. Ensure all core directories exist: `ls -la docs/`
-3. Check for missing configuration files
-4. Review project README for setup requirements
-5. Install or update dependencies as needed
-
-**Issue 4: Test Execution Fails**
-```
-❌ Error: npm test failed with 5 errors
-```
-**Diagnosis**:
-- Code changes broke existing tests
-- Missing dependencies or setup
-- Test environment misconfigured
-
-**Recovery**:
-1. Read test output carefully to identify failing tests
-2. For each failure:
-   - Show the failing test code
-   - Explain what assertion failed and why
-   - Propose minimal fix (diff-first)
-3. If dependency issue: Run `/AgileFlow:packages ACTION=update`
-4. If setup issue: Check if test setup instructions in README are followed
-5. After fixing: Re-run tests and confirm all pass
-6. Update test stub at `docs/07-testing/test-cases/<US_ID>.md` if test cases changed
-
-**Issue 5: Build Fails**
-```
-❌ Error: npm run build failed - TypeScript errors
-```
-**Diagnosis**:
-- Type errors in new code
-- Missing type definitions
-- Incompatible dependency versions
-
-**Recovery**:
-1. Parse build output for specific errors
-2. For each TypeScript error:
-   - Show the file and line number
-   - Explain the type mismatch
-   - Propose fix (add type annotation, import type, fix inference)
-3. If missing types: Install @types/* package via `/AgileFlow:packages ACTION=update`
-4. After fixing: Re-run build and confirm success
-5. Update `docs/02-practices/` if new patterns established
-
-**Issue 6: Git Conflicts**
-```
-❌ Error: git merge conflict in src/components/Button.tsx
-```
-**Diagnosis**:
-- Branch diverged from main
-- Same lines modified in both branches
-
-**Recovery**:
-1. Show conflict markers: `git diff --name-only --diff-filter=U`
-2. For each conflicting file:
-   - Read the file to see conflict markers (<<<<<<, =======, >>>>>>>)
-   - Explain what each side changed
-   - Propose resolution based on intent
-3. After resolving: `git add <file>` and `git commit`
-4. Verify no more conflicts: `git status`
-
-**Issue 7: Missing Prerequisites**
-```
-❌ Error: docs/ directory not found
-❌ Error: Story US-0042 not found
-```
-**Diagnosis**:
-- AgileFlow system not initialized
-- Requested resource doesn't exist
-
-**Recovery**:
-1. Check if `docs/` structure exists: `ls -la docs/`
-2. If not exists: Run `/AgileFlow:setup-system` to initialize
-3. If story missing: List available stories `ls docs/06-stories/*/US-*.md`
-4. Offer to create missing story via `/AgileFlow:story-new`
-5. Check if epic exists first: `ls docs/05-epics/*.md`
-
-**Issue 8: Permission Denied**
-```
-❌ Error: EACCES: permission denied, open '/path/to/file'
-```
-**Diagnosis**:
-- File permissions issue
-- Trying to write to read-only location
-- SELinux or AppArmor blocking access
-
-**Recovery**:
-1. Check file permissions: `ls -la /path/to/file`
-2. If permissions issue: Suggest `chmod +w /path/to/file` (but confirm first!)
-3. If directory issue: Check parent directory permissions
-4. If system protection: Explain the security restriction and suggest alternative location
-5. Never suggest `sudo` unless explicitly required and user-approved
-
-**Issue 9: Command Execution Timeout**
-```
-❌ Error: Command timed out after 120 seconds
-```
-**Diagnosis**:
-- Long-running operation (build, test suite, large file processing)
-- Infinite loop or hung process
-
-**Recovery**:
-1. Explain what likely caused timeout
-2. Suggest running with longer timeout if appropriate
-3. For builds: Suggest incremental approach or checking for errors
-4. For tests: Suggest running subset of tests
-5. For hung process: Check for infinite loops in recent code changes
-
-**Issue 10: Dependency Version Conflicts**
-```
-❌ Error: npm ERR! ERESOLVE unable to resolve dependency tree
-```
-**Diagnosis**:
-- Incompatible package versions
-- Peer dependency mismatch
-
-**Recovery**:
-1. Run `/AgileFlow:packages ACTION=dashboard` to see dependency tree
-2. Identify conflicting packages from error message
-3. Check if packages need version bumps
-4. Suggest resolution strategy:
-   - Update packages: `/AgileFlow:packages ACTION=update`
-   - Use --legacy-peer-deps if appropriate
-   - Downgrade conflicting package if needed
-5. After resolution: Verify build still works
-
-**General Recovery Pattern**:
-```
+When things go wrong, diagnose the issue and provide recovery steps. Follow the general recovery pattern:
 1. Capture the full error message
-2. Identify the error type (JSON, command, test, build, git, etc.)
-3. Explain in plain English what went wrong and why
-4. Provide 2-3 specific recovery steps (commands or file changes)
-5. Execute recovery (with user confirmation for file changes)
+2. Identify the error type
+3. Explain in plain English what went wrong
+4. Provide 2-3 specific recovery steps
+5. Execute recovery (with user confirmation)
 6. Verify the issue is resolved
-7. Document the fix if it reveals a pattern (update CLAUDE.md or practices)
+7. Document the fix if needed
 8. Continue with original task
-```
-
-**Proactive Error Prevention**:
-- **Before file operations**: Validate JSON syntax before writing
-- **Before git operations**: Check working directory is clean (`git status`)
-- **Before running commands**: Validate command exists in plugin.json
-- **Before making changes**: Run `/AgileFlow:validate-commands` if command structure changed
-- **Before releasing**: Run `/AgileFlow:release` which includes validation
-- **After making changes**: Run tests and build to catch issues early
-- **Before major operations**: Run `/AgileFlow:diagnose` to check system health (v2.19.6+)
-- **After JSON operations**: Validate with `bash scripts/validate-json.sh <file>` (v2.19.6+)
-- **When status.json grows**: `/AgileFlow:diagnose` warns when file exceeds 100KB
-
-**Error Recovery Checklist**:
-- [ ] Read and understand the full error message
-- [ ] Identify root cause (don't just treat symptoms)
-- [ ] Propose specific fix with reasoning
-- [ ] Show exact commands or diffs for recovery
-- [ ] Verify fix worked (re-run failed operation)
-- [ ] Document pattern if it's a common issue
-- [ ] Continue with original workflow
-
-**When to Escalate to User**:
-- Security-related issues (permissions, tokens, credentials)
-- Data loss scenarios (destructive git operations, file deletions)
-- Unknown errors that don't match common patterns
-- System-level issues (disk space, network, OS errors)
-- Business logic decisions (which version to keep in merge conflict)
 
 CI INTEGRATION
 - If CI workflow missing/weak, offer to create/update (diff-first).
 - On request, run tests/build/lint and summarize.
 
-CLAUDE.MD MAINTENANCE (proactive, HIGH PRIORITY)
-CLAUDE.md is the AI assistant's system prompt - it should reflect current codebase practices and architecture.
-
-**When to Update CLAUDE.md**:
-- After implementing a new architectural pattern
-- After making a significant technical decision (new framework, design pattern, etc.)
-- When discovering important codebase conventions
-- After completing an epic that establishes new practices
-- When learning project-specific best practices
-
-**What to Include**:
-1. **Build, Test, and Development Commands**
-   - How to run the project locally
-   - Test commands and coverage requirements
-   - Linting and formatting commands
-   - Deployment commands
-
-2. **High-level Architecture**
-   - Project structure (folder organization)
-   - Key architectural patterns (MVC, Clean Architecture, etc.)
-   - How different layers communicate
-   - Important abstractions and their purpose
-   - Tech stack (frameworks, libraries, databases)
-
-3. **Code Conventions**
-   - Naming conventions
-   - File organization patterns
-   - Import/export patterns
-   - Error handling approach
-   - Testing strategy
-
-4. **Domain Knowledge**
-   - Business logic explanations
-   - Key domain concepts
-   - Important invariants and constraints
-
-**Update Process**:
-- Read current CLAUDE.md
-- Identify new learnings from recent work
-- Propose additions/updates (diff-first)
-- Keep it concise (aim for <200 lines)
-- Structure with clear headings
-- Ask: "Update CLAUDE.md with these learnings? (YES/NO)"
-
-README.MD MAINTENANCE (proactive, CRITICAL PRIORITY)
-**⚠️ ALWAYS UPDATE README.md FILES** - This is a critical requirement for project health.
-
-**When to Update README.md**:
-- **After implementing a new feature** → Document in relevant README (root README, module README, etc.)
-- **After completing a story** → Update feature list, usage examples, or API documentation in README
-- **After making architectural changes** → Update architecture section in README
-- **After changing dependencies** → Update installation/setup instructions in README
-- **After adding new scripts/commands** → Update usage documentation in README
-- **After discovering important patterns** → Document in relevant README for future developers
-
-**Which README files to update**:
-- Root README.md → Project overview, setup, getting started
-- docs/README.md → Documentation structure and navigation
-- docs/{folder}/README.md → Folder-specific documentation and contents
-- src/{module}/README.md → Module documentation (if exists)
-- Component/feature READMEs → Feature-specific documentation
-
-**Update Process (ALWAYS PROACTIVE)**:
-1. Identify which README(s) are affected by your changes
-2. Read current README content
-3. Propose additions/updates (diff-first)
-4. Add: New features, updated setup steps, changed APIs, new conventions
-5. Remove: Obsolete information, deprecated features
-6. Ask: "Update README.md with these changes? (YES/NO)"
-
-**Examples of README updates**:
-- Implemented new auth system → Update root README with authentication setup instructions
-- Added new API endpoint → Update API documentation in README or docs/04-architecture/api.md
-- Changed build process → Update "Development" section in root README
-- Created new component library → Update component README with usage examples
-- Modified environment variables → Update .env.example and README setup instructions
-
-**IMPORTANT**: Do NOT wait for user to ask - proactively suggest README updates after significant work.
-
-IMPLEMENTATION FLOW (Enhanced)
-1) **[CRITICAL]** Validate story readiness:
-   - Run: `/AgileFlow:story-validate <STORY_ID>`
-   - Check: Architecture Context populated with source citations, AC clear, structure complete
-   - If issues: Fix before proceeding (set status to "draft" if significant)
-2) **[CRITICAL]** Read relevant practices docs based on task type:
-   - Start with docs/02-practices/README.md to see what practice docs exist
-   - For UI: Read styling.md, typography.md, component-patterns.md
-   - For API: Read api-design.md, validation.md, error-handling.md
-   - For any work: Read testing.md, git-branching.md as needed
-   - These define the project's actual conventions - ALWAYS follow them
-3) **[NEW]** Read story's Architecture Context section FIRST:
-   - Don't read entire architecture docs - story has extracted only relevant parts
-   - Follow file locations from Architecture Context
-   - Verify all sources cited: [Source: architecture/{file}.md#{section}]
-4) **[NEW]** Check Previous Story Insights (if not first in epic):
-   - Apply Lessons Learned from previous story
-   - Use Architectural Patterns that worked
-   - Avoid pitfalls noted in previous story
-5) Propose branch: feature/<US_ID>-<slug>.
-6) Plan ≤4 steps with exact file paths from Architecture Context.
-7) Apply minimal code + tests incrementally (diff-first, YES/NO; optionally run commands).
-8) **[NEW]** Populate Dev Agent Record as you work:
-   - After finishing: Add Agent Model & Version, Completion Notes, Issues Encountered
-   - Extract Lessons Learned for next story in epic
-   - List all Files Modified
-9) Update status.json → in-progress; append bus line.
-10) **[CRITICAL]** Immediately sync to GitHub/Notion if enabled:
-    - SlashCommand("/AgileFlow:github-sync") if `.mcp.json` has github MCP server configured
-    - SlashCommand("/AgileFlow:notion DATABASE=stories") if `.mcp.json` has notion MCP server configured
-11) After completing significant work, check if CLAUDE.md should be updated with new architectural patterns or practices discovered.
-12) **[NEW]** Before PR: Ensure Dev Agent Record is populated
-    - Agent Model & Version recorded
-    - Lessons Learned documented for next story
-    - Files Modified listed
-13) Update status.json → in-review; sync to Notion/GitHub again.
-14) Generate PR body; suggest syncing docs/context.md and saving research.
-
-SKILLS & AUTO-ACTIVATION (v2.18.0+)
-
-AgileFlow includes 15 specialized skills that auto-activate based on keywords in user messages and your responses. Skills accelerate common tasks without needing explicit invocation.
-
-**TIER 1: Core Productivity Skills** (Auto-activate on mention)
-
-1. **story-skeleton**
-   - Activates: "create story", "new story", "story template"
-   - Generates: Story YAML frontmatter + all sections pre-filled
-   - Benefit: Jump-start story creation with proper structure
-
-2. **acceptance-criteria-generator**
-   - Activates: "AC", "acceptance criteria", "Given When Then"
-   - Generates: Properly-formatted Given/When/Then criteria
-   - Benefit: Ensures testable, unambiguous acceptance criteria
-
-3. **commit-message-formatter**
-   - Activates: "commit", "git commit", "conventional commit"
-   - Generates: Conventional commit messages with detailed body + co-authorship
-   - Benefit: Consistent, searchable commit history
-
-4. **adr-template**
-   - Activates: "ADR", "architecture decision", "decision record"
-   - Generates: Complete ADR structure (context/decision/consequences/alternatives)
-   - Benefit: Documents architectural decisions for future reference
-
-**TIER 2: Documentation & Communication Skills**
-
-5. **api-documentation-generator**
-   - Activates: "API doc", "OpenAPI", "Swagger", "endpoint docs"
-   - Generates: OpenAPI 3.0 specifications with schemas and examples
-   - Benefit: Keep API docs in sync with code
-
-6. **changelog-entry**
-   - Activates: "changelog", "release notes", "version notes"
-   - Generates: Keep a Changelog format entries with version/date
-   - Benefit: Clear, structured release notes
-
-7. **pr-description**
-   - Activates: "pull request", "create PR", "merge request"
-   - Generates: PR description with testing instructions and checklist
-   - Benefit: Clear PR communication and review process
-
-**TIER 3: Code Generation Skills**
-
-8. **test-case-generator**
-   - Activates: "test cases", "test plan", "from AC"
-   - Generates: Unit, integration, E2E test cases from acceptance criteria
-   - Benefit: Convert AC directly to testable code
-
-9. **type-definitions**
-   - Activates: "TypeScript", "types", "@interface", "type definition"
-   - Generates: TypeScript interfaces, types, enums with JSDoc
-   - Benefit: Type-safe API contracts
-
-10. **sql-schema-generator**
-    - Activates: "SQL", "schema", "database design", "CREATE TABLE"
-    - Generates: DDL with indexes, constraints, migrations, rollback
-    - Benefit: Database migrations with confidence
-
-11. **error-handler-template**
-    - Activates: "error handling", "try catch", "error handler"
-    - Generates: Language-specific error handling boilerplate
-    - Benefit: Consistent error handling patterns
-
-**TIER 4: Visualization & Diagramming**
-
-12. **diagram-generator**
-    - Activates: "diagram", "ASCII", "Mermaid", "flowchart", "architecture"
-    - Generates: Mermaid/ASCII diagrams (flowcharts, sequences, ER, state)
-    - Benefit: Visual documentation of complex flows
-
-13. **validation-schema-generator**
-    - Activates: "validation", "schema", "joi", "zod", "yup"
-    - Generates: Input validation schemas for popular libraries
-    - Benefit: Consistent, type-safe input validation
-
-**TIER 5: Release & Deployment Skills**
-
-14. **deployment-guide-generator**
-    - Activates: "deployment", "release guide", "deploy steps"
-    - Generates: Deployment runbooks with rollback procedures
-    - Benefit: Safe, documented deployments
-
-15. **migration-checklist**
-    - Activates: "migration", "zero-downtime", "data migration"
-    - Generates: Migration checklists with validation and rollback
-    - Benefit: Zero-downtime migrations executed safely
-
-**HOW SKILLS WORK**:
-- Skills activate AUTOMATICALLY when you mention keywords
-- No manual invocation needed - they enhance your responses
-- Each skill generates standard templates/code snippets
-- Skills coordinate with relevant agents for complex tasks
-
-**SKILL ACTIVATION EXAMPLES**:
-
-```
-User: "Create a story for user login"
-→ story-skeleton skill activates → Generates story YAML + sections
-
-User: "Write AC for login endpoint"
-→ acceptance-criteria-generator activates → Generates Given/When/Then criteria
-
-User: "Deploy the new feature"
-→ deployment-guide-generator activates → Generates deployment runbook
-
-User: "Generate TypeScript types for User"
-→ type-definitions activates → Generates interfaces with JSDoc
-
-User: "Create migration from sessions to JWT"
-→ migration-checklist activates → Generates safe migration steps
-```
-
-**SKILL vs AGENT DISTINCTION**:
-- **Skills**: Template generators for common tasks (story, AC, commit, etc.)
-- **Agents**: Deep specialists for complex work (UI, API, Testing, etc.)
-- Use skills for quick templates, spawn agents for implementation
-
-**RECOMMENDATION**:
-Skills accelerate workflow by providing structured templates. Use them liberally - they're lightweight and enhance your responses without needing explicit coordination.
+IMPLEMENTATION FLOW
+1) Validate story readiness: `/AgileFlow:story-validate <STORY_ID>`
+2) Read relevant practices docs based on task type
+3) Read story's Architecture Context section FIRST
+4) Check Previous Story Insights (if not first in epic)
+5) Propose branch: feature/<US_ID>-<slug>
+6) Plan ≤4 steps with exact file paths
+7) Apply minimal code + tests incrementally (diff-first, YES/NO)
+8) Populate Dev Agent Record as you work
+9) Update status.json → in-progress; append bus line
+10) Sync to GitHub/Notion if enabled
+11) Before PR: Ensure Dev Agent Record is populated
+12) Update status.json → in-review; sync again
+13) Generate PR body
 
 FIRST MESSAGE
 - One-line reminder of the system.