Planning Workflow

Transform requirements into executable specifications through multi-agent collaboration

Overview

The Planning Workflow (Spec Pipeline) transforms informal requirements into validated, executable specifications before any code is written. This pre-implementation workflow ensures alignment and reduces rework.

Agent Sequence

Phase 1: Research (Analyst)

Agent: Zara (@analyst)

Command: *research {topic}

Task: create-deep-research-prompt.md

Purpose: Deep dive into domain, gather context, identify constraints

Output: research.json

Skip if: Complexity class is SIMPLE

1. Domain Analysis

   Analyst investigates the problem space, existing solutions, and industry patterns

2. Technical Constraints

   Identifies technical limitations, dependencies, and integration points

3. Research Documentation

   Produces structured research findings in JSON format

Phase 2: Requirements Gathering (PM)

Agent: Kai (@pm)

Command: *gather-requirements

Task: spec-gather-requirements.md

Purpose: Elicit and document functional and non-functional requirements

Output: requirements.json

Requirements Structure

{
  "functional_requirements": [
    {
      "id": "FR-001",
      "description": "User can authenticate via OAuth",
      "priority": "HIGH",
      "source": "stakeholder-interview-2026-03-01"
    }
  ],
  "non_functional_requirements": [
    {
      "id": "NFR-001",
      "category": "performance",
      "description": "API response time < 200ms p95",
      "measurable": true,
      "acceptance_threshold": "200ms"
    }
  ],
  "constraints": [
    {
      "id": "CON-001",
      "description": "Must use existing authentication service",
      "type": "technical"
    }
  ]
}

Phase 3: Impact Analysis (Architect)

Agent: Aria (@architect)

Command: *analyze-impact

Task: architect-analyze-impact.md

Purpose: Assess technical complexity and architectural implications

Output: complexity.json

Skip if: Complexity class is SIMPLE

The architect evaluates:

• Complexity Class: SIMPLE | STANDARD | COMPLEX
• Affected Systems: List of services/modules impacted
• Risk Assessment: Technical risks and mitigation strategies
• Effort Estimate: T-shirt sizing (S/M/L/XL)

Phase 4: Specification Writing (PM)

Agent: Kai (@pm)

Command: *write-spec

Task: spec-write-spec.md

Purpose: Create comprehensive specification document

Output: spec.md

No Invention Rule: Every statement in the spec must trace back to:

• A functional requirement (FR-*)
• A non-functional requirement (NFR-*)
• A constraint (CON-*)
• A verified research finding

See Constitution: No Invention for details.

Spec Template

# Specification: {Feature Name}

## Overview
[High-level description derived from requirements]

## Functional Requirements
- **FR-001:** [Requirement description]
  - Acceptance: [Testable criteria]
  
## Non-Functional Requirements
- **NFR-001:** [Performance/Security/etc requirement]
  - Measurement: [How to verify]
  
## Technical Approach
- **System A:** [Changes required] ← Derived from CON-001
- **System B:** [Integration points] ← From research findings

## Data Model
[Schema changes if applicable]

## API Contract
[Endpoint definitions if applicable]

## Testing Strategy
- Unit tests: [Coverage targets]
- Integration tests: [Scenarios]
- Performance tests: [NFR validation]

## Rollout Plan
[Deployment strategy derived from constraints]

Phase 5: Spec Critique (QA)

Agent: Quinn (@qa)

Command: *critique-spec {story-id}

Task: spec-critique.md

Purpose: Validate completeness, testability, and adherence to standards

Output: APPROVED | NEEDS_REVISION | BLOCKED

APPROVED

Spec is complete, testable, and ready for implementation planning

NEEDS_REVISION

Issues identified that require PM revision before proceeding

BLOCKED

Critical gaps or violations that prevent continuation

QA Validation Checklist:

• All requirements traced to acceptance criteria
• No invented features (Constitution violation check)
• Test strategy covers all functional requirements
• NFRs have measurable acceptance thresholds
• Dependencies and constraints documented
• API contracts follow project standards
• Data model includes migration strategy

Phase 6: Implementation Planning (Architect)

Agent: Aria (@architect)

Command: *plan

Task: architect-analyze-impact.md

Purpose: Create detailed implementation plan and story breakdown

Output: implementation.yaml

Implementation Plan Structure

feature: oauth-authentication
complexity: STANDARD
estimated_effort: M

stories:
  - id: "3.1"
    title: "OAuth Provider Integration"
    effort: 3
    dependencies: []
    files:
      - src/auth/oauth-provider.ts
      - src/auth/oauth-config.ts
      
  - id: "3.2"
    title: "User Session Management"
    effort: 5
    dependencies: ["3.1"]
    files:
      - src/auth/session-manager.ts
      - src/middleware/auth.ts

technical_decisions:
  - decision: "Use Passport.js for OAuth"
    rationale: "Aligns with CON-001 constraint"
    alternatives_considered:
      - "Custom OAuth implementation (rejected: too complex)"
      
risks:
  - risk: "OAuth provider rate limiting"
    mitigation: "Implement token caching (NFR-002)"
    severity: MEDIUM

Workflow Execution

Starting the Planning Workflow

# Start planning for a new feature
*run-workflow spec-pipeline --feature="OAuth Authentication"

Workflow State Transitions

1. Researched

   Trigger: *research completed

   Confidence: 0.85

   Next Steps:

   • *gather-requirements (Priority 1)
   • *advanced-elicitation (Priority 2)
2. Requirements Gathered

   Trigger: *gather-requirements completed

   Confidence: 0.90

   Next Steps:

   • *analyze-impact (Priority 1)
   • *write-spec (Priority 2 - if skipping impact analysis)
3. Impact Analyzed

   Trigger: *analyze-impact completed

   Confidence: 0.85

   Next Steps:

   • *write-spec (Priority 1)
4. Spec Written

   Trigger: *write-spec completed

   Confidence: 0.90

   Next Steps:

   • *critique-spec {story-id} (Priority 1)
5. Spec Approved

   Trigger: *critique-spec returns APPROVED

   Confidence: 0.95

   Next Steps:

   • *plan (Priority 1)
   • *create-story (Priority 2)

Complexity-Based Routing

The planning workflow adapts based on complexity assessment:

Complexity	Research Phase	Impact Analysis	Typical Duration
SIMPLE	Skip	Skip	0.5 days
STANDARD	Required	Required	1-2 days
COMPLEX	Deep dive	Detailed	2-5 days

SIMPLE

# Example: Add new field to existing form
*gather-requirements → *write-spec → *critique-spec → *create-story

STANDARD

# Example: New API endpoint with business logic
*research → *gather-requirements → *analyze-impact → *write-spec → *critique-spec → *plan

COMPLEX

# Example: Multi-service integration with data migration
*research (deep) → *gather-requirements → *analyze-impact → *architect-review → *write-spec → *critique-spec → *plan → *create-epic

Integration with Development Cycle

Once planning is complete, transition to the development workflow:

# Planning workflow produces implementation.yaml
# Architect or PM creates stories from the plan
*create-story --from-plan implementation.yaml

# Stories enter the standard development cycle
*run-workflow story-development --story="3.1"

Best Practices

When to Use Planning Workflow

Use for:

• New features with unclear requirements
• Complex integrations spanning multiple systems
• Changes with significant architectural impact
• Features requiring research or proof-of-concept

Skip for:

• Bug fixes (use development cycle directly)
• Trivial UI changes
• Refactoring with clear scope
• Documentation updates

Requirements Traceability

Maintain clear links from spec to requirements:

## Authentication Flow

The system SHALL support OAuth 2.0 authentication [FR-001].
Response time for token exchange MUST be < 200ms [NFR-001].
Integration SHALL use existing auth service [CON-001].

Every design decision traces back to a requirement ID.

Avoiding Specification Bloat

Keep specs focused:

• Do: Specify what and why
• Don’t: Prescribe exact implementation (that’s the developer’s domain)
• Do: Define acceptance criteria
• Don’t: Write implementation pseudocode
• Do: Document constraints and NFRs
• Don’t: Invent requirements not from stakeholders

Common Issues

Issue: Spec critique returns BLOCKED

Common causes:

• Invented features not in requirements (Constitution violation)
• Missing NFRs for performance/security
• Untestable acceptance criteria
• Undocumented dependencies

Resolution: Revise spec with PM, re-run *critique-spec

Issue: Impact analysis shows COMPLEX but timeline doesn’t allow

Resolution:

• Break into smaller epics with phased delivery
• Descope non-essential requirements
• Negotiate timeline extension with stakeholders
• Consider technical debt approach (with explicit follow-up stories)

Next Steps

Development Cycle

Learn how validated specs transition into implementation

Agent: Analyst

Deep dive into Zara’s research capabilities

Agent: PM

Explore Kai’s requirements and spec authoring commands

Constitution

Review the “No Invention” principle and other rules