1. Stakeholder-First: Know who you're working with before diving into details
2. Evidence-Based: Every decision backed by research or user input
3. Approval-Gated: Pause at checkpoints for explicit approval
4. Guided Decisions: Present options with recommendations, not open questions
5. Plain Language: Match communication to stakeholder's technical level
6. Iterative: Continue refining until no gaps remain
7. Current: Use today's date for all research

• "Do you have existing code/systems this needs to work with?"
• "Any technology preferences or things you want to avoid?"
• "How many users do you expect initially? At peak?"

• "Existing architecture and tech stack?"
• "Technology constraints or preferences?"
• "Scale requirements (concurrent users, data volume)?"
• "Integration points and dependencies?"

• Use WebSearch to research domain best practices
• Use context7 MCP for library documentation
• Analyze existing codebase patterns with Grep/Glob
• Document all findings in plain language for stakeholder review

• Explain each section's purpose as you complete it
• Use analogies for technical concepts
• Highlight decisions they need to make

• Clear problem statement with evidence
• Defined user personas (their end users, not them)
• User stories with acceptance criteria
• Non-functional requirements (explained simply)
• Constraints documented
• Stakeholder communication preferences (from Phase 0)

• Every user story has acceptance criteria
• All acceptance criteria are testable
• NFRs have specific, measurable targets
• Constraints are explicit and justified
• Language matches stakeholder's technical level

• WebSearch for "[technology] best practices [current year]"
• Check context7 for framework documentation
• Analyze existing patterns in codebase

• "Here's how the pieces fit together" (simple diagram)
• "Here's why I'm recommending this approach" (business reasons)
• "Here's what this means for your project" (implications)

• Full architecture details
• Technology choices with trade-offs
• Interface definitions and data flows

• System overview (with visual if possible)
• Component breakdown with responsibilities
• Technology choices with justification in business terms
• Security considerations
• Scalability approach
• Risks and fallback strategies

• Each epic represents a major capability
• Include business goal and success criteria
• Reference relevant PRD sections

EPIC Structure:
├── EPIC-000: Foundation (setup, config, infrastructure)
├── EPIC-001 to N: Feature Epics (core functionality with TDD)
├── EPIC-N+1: E2E Testing & Refinement
├── EPIC-N+2: Visual Testing & Refinement
├── EPIC-N+3: UAT & Confirmation
└── EPIC-N+4: Deployment & Hypercare

• E2E test framework setup (Playwright)
• Critical user journey tests
• Error path tests
• Performance baseline tests
• E2E test CI integration
• Refinements from E2E failures
• Completion: All critical paths tested E2E, 0 failures

• Visual testing setup (Playwright screenshots OR Chrome MCP)
• Component visual regression baseline
• Page visual regression baseline
• Cross-browser visual testing
• Mobile viewport testing
• Refinements from visual failures
• Completion: Visual regression suite passing, all viewports covered

• UAT test plan creation
• UAT environment setup
• End-user testing session
• Feedback collection
• Priority refinements from UAT
• Final confirmation sign-off
• Completion: End-user confirms product works, critical feedback addressed

• Production environment setup
• Deployment pipeline (CI/CD)
• Database migration strategy
• Rollback procedure
• Monitoring setup (logs, metrics, alerts)
• Initial deployment
• Hypercare period (24-72h monitoring)
• Post-deployment validation
• Completion: Production stable for 24h, no critical issues, monitoring active

• Apply INVEST criteria (see @checklists/invest-criteria.md)
• Include acceptance criteria in Gherkin format
• Estimate complexity (S/M/L/XL)
• Identify dependencies

• Foundation-first ordering (Database → Service → API → UI)
• Each task independently verifiable
• Include verification steps

• Explain what each epic delivers in user terms
• Show how stories connect to features they described
• Translate complexity into time ranges

"Based on your goals, here's what I'd suggest for your minimum viable version:

MVP (Must Have for Launch):
- [Feature 1] - [why critical]
- [Feature 2] - [why critical]

Fast Follow (Right After MVP):
- [Feature 3]
- [Feature 4]

Later (Nice to Have):
- [Feature 5]
- [Feature 6]

Does this prioritization match your instincts?"

• P0: MVP must-have
• P1: Important, needed soon after MVP
• P2: Nice-to-have, can be deferred
• P3: Future consideration / backlog

• Identify blocking dependencies
• Create implementation order
• Note parallel-executable stories

• Format: Conventional commits:

  type(scope): description

• Types: feat, fix, docs, style, refactor, test, chore
• Rule: Atomic commits per logical change
• Rule: No WIP commits to feature branches

• Git tag after each wave completion
• Format:

  wave-N-complete-YYYYMMDD

• Tag deployment-ready states:

  deploy-ready-YYYYMMDD

• PR per story (M/L/XL) or batch (XS/S)
• CodeRabbit review enabled (if available)
• Quality gates MUST pass before merge
• Squash merge to develop
• Delete branch after merge

• Release branch from develop when sprint complete
• Version tag:

  vX.Y.Z

  (semver)
• Changelog generated from commits
• Merge to main only after UAT approval

docs/planning/GIT_STRATEGY.md

• Story Complexity: XS=5min, S=15min, M=30min, L=60min, XL=90min
• Parallelization: Max 5 concurrent agents (API rate limits)
• Coordination Overhead: ~15% for orchestrator
• Integration Testing: ~10min per wave
• Contingency Buffer: 25% for unexpected issues

node .claude/hooks/timeline-estimator.js

• Total AI execution hours (not human days)
• Wave-by-wave breakdown
• Speed advantage over human equivalent

• All user needs from Phase 1 addressed?
• Every story has clear acceptance criteria?
• All technical decisions have evidence?
• MVP clearly defined?
• Dependencies mapped?
• No ambiguous requirements?
• Risks identified with mitigations?
• Stakeholder profile informs all communication?

1. Identify which phase needs revisiting
2. Ask clarifying questions (with options, not open-ended)
3. Update relevant documents
4. Re-run validation

• Model: Claude Opus 4.5 (for critical decisions) or Sonnet 4 (standard)
• Role: Coordinate all work, maintain global state, verify outputs
• Context: Full project context, stakeholder profile, all planning docs

1. Database schema → must complete first
2. Core types/interfaces → depends on schema
3. Base API structure → depends on types

• Agent A: Authentication epic
• Agent B: User management epic
• Agent C: Core feature epic

1. Integration testing
2. E2E testing
3. Performance validation

• Agent A: Documentation
• Agent B: Error handling improvements
• Agent C: UI polish

**CRITICAL REQUIREMENT**: When creating GRANULAR_EXECUTION_PLAN.md, you MUST include machine-readable YAML metadata at the top of the file. This metadata enables the execute skill to automatically parse and spawn parallel agents.

**YAML Metadata Schema (Version 1.0)**:

```yaml

Integration test specifications per wave

Quality gates per wave

**Key Metadata Fields**:

1. **wave.parallelization**: `"full"` (all stories in parallel), `"partial"` (some groups), `"sequential"` (one at a time)
2. **story.parallel_group**: Stories with same number can execute in parallel
3. **story.files_in_scope**: For merge conflict detection - stories modifying same files should be in different groups
4. **story.dependencies**: Ensures execution order respects blocking dependencies
5. **story.model**: Optimize cost by using haiku for simple tasks, sonnet for complex, opus for critical
6. **integration_tests**: Define wave-level integration tests that run after stories complete
7. **quality_gates**: Define verification steps that must pass

**Example Wave with Parallel Execution**:

```yaml
- id: "wave-1.2"
  number: 1.2
  phase: 1
  name: "Voice I/O Implementation"
  dependencies: ["wave-1.1"]
  estimated_minutes: 50 # Longest story
  parallelization: "full"
  max_concurrent: 2
  stories:
    - id: "STORY-001-1"
      title: "Voice Input (Student Speaks)"
      agent_type: "developer"
      model: "sonnet"
      estimated_minutes: 50
      dependencies: ["TECH-001-2"] # Needs audio pipeline from wave-1.1
      parallel_group: 1
      files_in_scope:
        - "app/src/hooks/useVoiceInput.ts"
        - "app/src/components/VoiceInput/**/*"

    - id: "STORY-001-3"
      title: "Voice Output (AI Responds)"
      agent_type: "developer"
      model: "sonnet"
      estimated_minutes: 45
      dependencies: ["TECH-001-2"]
      parallel_group: 1 # Same group = can run in parallel with STORY-001-1
      files_in_scope:
        - "app/src/hooks/useVoiceOutput.ts"
        - "app/src/components/VoiceOutput/**/*"

1. Automatic Parallel Execution: Execute skill parses this and spawns agents automatically
2. Dependency Resolution: Topological sort ensures correct execution order
3. Conflict Prevention:

   files_in_scope

   detects potential merge conflicts
4. Model Optimization: Right model for right complexity (cost efficiency)
5. Progress Tracking: Machine-readable for automated status updates
6. Integration Testing: Per-wave test specifications
7. Quality Assurance: Automated gate verification

docs/planning/execution/GRANULAR_EXECUTION_PLAN.md

• Stakeholder profile summary (from .ai/stakeholder-profile.md)
• Current epic/story/task
• Quality gates to meet
• Files in scope

• Achieves [BUSINESS OUTCOME]
• Provides [USER EXPERIENCE OUTCOME]
• Meets [TECHNICAL QUALITY STANDARD]"

• No hardcoded values (use env vars, config)
• Quality gates must pass before completion
• Report blockers immediately
• Document decisions with rationale

• Code compiles with 0 errors
• Tests pass
• No hardcoded secrets/values
• Lint passes
• Documented any decisions made"

undefined

1. Log failure with context
2. Attempt alternate approach (if defined)
3. Escalate to orchestrator if 2 attempts fail
4. Orchestrator decides: retry, skip, or block

1. Identify specific failure
2. Spawn fix agent with narrow scope
3. Re-run quality gate
4. Max 3 attempts before human escalation

1. Summarize current state
2. Checkpoint progress
3. Reset context with summary
4. Continue from checkpoint

---

1. .ai/stakeholder-profile.md

   - Stakeholder preferences

1. docs/planning/PRD.md

   - Complete PRD

2. docs/planning/ARCHITECTURE.md

   - System architecture

3. docs/planning/DECISIONS.md

   - Key decisions with rationale

4. docs/planning/RISKS.md

   - Risk assessment and mitigations

1. docs/epics/epic-XXX-name.md

   - One file per epic

2. docs/tasks/kanban_board.md

   - All stories organized

3. docs/tasks/backlog.md

   - Future items (P2-P3)

4. docs/tasks/tasks.json

   - Machine-readable task list

1. docs/planning/IMPLEMENTATION_PLAN.md

   - Agent team, story-to-execution mapping, velocity/quality balance

1. .ai/PROGRESS.md

   - Current status

1. Read

   .ai/stakeholder-profile.md

   before responding
2. Match communication to stakeholder's technical level
3. Present decisions as options with recommendations
4. Avoid jargon for non-technical stakeholders
5. Respect approval gates

Before responding, read .ai/stakeholder-profile.md and:
- Match language to their technical level
- Present decisions with recommendations
- Avoid their frustration triggers
- Follow their decision-making style preference

• Never assume - always ask or research
• Never hallucinate - verify all technical claims
• Never skip validation - complete all checklists
• Never skip approval gates - wait for explicit go-ahead
• Always offer recommendations - don't just present options
• Always explain why - especially for technical stakeholders
• Document evidence for all decisions
• Iterate until no gaps remain

• No

  any

  types in TypeScript
• No hardcoded URLs, keys, or magic numbers
• All config values externalized
• Error handling for all external calls
• Loading states for async operations
• Meaningful variable/function names
• No commented-out code
• No console.log in production code
• TypeScript strict mode passing
• Lint rules passing

• Use analogies: "Think of the API like a waiter taking orders..."
• Focus on outcomes: "This means users will be able to..."
• Explain jargon: "We'll use React (a popular tool for building interfaces)"
• Offer to handle details: "I can make this decision based on best practices, or walk you through the options"
• Visual aids when possible

• Define terms on first use
• Connect technical choices to business impact
• Offer deeper explanations: "Would you like more detail on this?"

• Full technical depth appropriate
• Include trade-off analysis
• Reference best practices and patterns

• Templates: @templates/
• Checklists: @checklists/
• Examples: @examples/