> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/SynkraAI/aiox-core/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```mermaid theme={null}
graph TD
    A[@analyst: Research] --> B[@pm: Gather Requirements]
    B --> C[@architect: Analyze Impact]
    C --> D[@pm: Write Spec]
    D --> E[@qa: Critique Spec]
    E --> F{Approved?}
    F -->|Yes| G[@architect: Plan Implementation]
    F -->|No| D
    G --> H[Stories Created]
```

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

<Steps>
  <Step title="Domain Analysis">
    Analyst investigates the problem space, existing solutions, and industry patterns
  </Step>

  <Step title="Technical Constraints">
    Identifies technical limitations, dependencies, and integration points
  </Step>

  <Step title="Research Documentation">
    Produces structured research findings in JSON format
  </Step>
</Steps>

### 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`

<Accordion title="Requirements Structure">
  ```json theme={null}
  {
    "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"
      }
    ]
  }
  ```
</Accordion>

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

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

### Phase 4: Specification Writing (PM)

**Agent:** Kai (@pm)

**Command:** `*write-spec`

**Task:** `spec-write-spec.md`

**Purpose:** Create comprehensive specification document

**Output:** `spec.md`

<Warning>
  **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](/architecture/constitution) for details.
</Warning>

<Accordion title="Spec Template">
  ```markdown theme={null}
  # 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]
  ```
</Accordion>

### 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`

<CardGroup cols={3}>
  <Card title="APPROVED" icon="circle-check" color="#10b981">
    Spec is complete, testable, and ready for implementation planning
  </Card>

  <Card title="NEEDS_REVISION" icon="triangle-exclamation" color="#f59e0b">
    Issues identified that require PM revision before proceeding
  </Card>

  <Card title="BLOCKED" icon="octagon-xmark" color="#ef4444">
    Critical gaps or violations that prevent continuation
  </Card>
</CardGroup>

**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`

<Accordion title="Implementation Plan Structure">
  ```yaml theme={null}
  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
  ```
</Accordion>

## Workflow Execution

### Starting the Planning Workflow

```bash theme={null}
# Start planning for a new feature
*run-workflow spec-pipeline --feature="OAuth Authentication"
```

### Workflow State Transitions

<Steps>
  <Step title="Researched" icon="magnifying-glass">
    **Trigger:** `*research` completed

    **Confidence:** 0.85

    **Next Steps:**

    * `*gather-requirements` (Priority 1)
    * `*advanced-elicitation` (Priority 2)
  </Step>

  <Step title="Requirements Gathered" icon="list">
    **Trigger:** `*gather-requirements` completed

    **Confidence:** 0.90

    **Next Steps:**

    * `*analyze-impact` (Priority 1)
    * `*write-spec` (Priority 2 - if skipping impact analysis)
  </Step>

  <Step title="Impact Analyzed" icon="chart-line">
    **Trigger:** `*analyze-impact` completed

    **Confidence:** 0.85

    **Next Steps:**

    * `*write-spec` (Priority 1)
  </Step>

  <Step title="Spec Written" icon="file-lines">
    **Trigger:** `*write-spec` completed

    **Confidence:** 0.90

    **Next Steps:**

    * `*critique-spec {story-id}` (Priority 1)
  </Step>

  <Step title="Spec Approved" icon="circle-check">
    **Trigger:** `*critique-spec` returns APPROVED

    **Confidence:** 0.95

    **Next Steps:**

    * `*plan` (Priority 1)
    * `*create-story` (Priority 2)
  </Step>
</Steps>

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

<Tabs>
  <Tab title="SIMPLE">
    ```bash theme={null}
    # Example: Add new field to existing form
    *gather-requirements → *write-spec → *critique-spec → *create-story
    ```
  </Tab>

  <Tab title="STANDARD">
    ```bash theme={null}
    # Example: New API endpoint with business logic
    *research → *gather-requirements → *analyze-impact → *write-spec → *critique-spec → *plan
    ```
  </Tab>

  <Tab title="COMPLEX">
    ```bash theme={null}
    # Example: Multi-service integration with data migration
    *research (deep) → *gather-requirements → *analyze-impact → *architect-review → *write-spec → *critique-spec → *plan → *create-epic
    ```
  </Tab>
</Tabs>

## Integration with Development Cycle

Once planning is complete, transition to the development workflow:

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="Requirements Traceability">
    Maintain clear links from spec to requirements:

    ```markdown theme={null}
    ## 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.
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Common Issues

<Warning>
  **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`
</Warning>

<Warning>
  **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)
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Development Cycle" icon="code" href="/workflows/development-cycle">
    Learn how validated specs transition into implementation
  </Card>

  <Card title="Agent: Analyst" icon="magnifying-glass" href="/essentials/agents/analyst">
    Deep dive into Zara's research capabilities
  </Card>

  <Card title="Agent: PM" icon="diagram-project" href="/essentials/agents/pm">
    Explore Kai's requirements and spec authoring commands
  </Card>

  <Card title="Constitution" icon="book" href="/architecture/constitution">
    Review the "No Invention" principle and other rules
  </Card>
</CardGroup>