Apex Spec Workflow

Apex Spec Workflow

A specification-driven workflow system for AI-assisted development that breaks large projects into manageable 2-4 hour sessions with 12-25 tasks each.

Core Philosophy

1 session = 1 spec = 2-4 hours (12-25 tasks)

Break large projects into manageable, well-scoped implementation sessions that fit within AI context windows and human attention spans.

A collection of sessions is a phase. A collection of phases is a mature/late technical PRD.

The 13-Command Workflow

The workflow has 3 distinct stages:

Stage 1: INITIALIZATION (One-Time Setup)

/initspec          ->  Set up spec system in project
      |
      v
/createprd         ->  Generate PRD from requirements doc (optional)
  OR                   OR
[User Action]      ->  Manually populate PRD with requirements
      |
      v
/createuxprd       ->  Generate UX PRD from design docs (optional)
  OR                   OR
[User Action]      ->  Manually populate UX PRD with requirements
      |
      v
/phasebuild        ->  Create first phase structure (session stubs)

Stage 2: SESSIONS WORKFLOW (Repeat Until Phase Complete)

/plansession   ->  Analyze project, create spec + task checklist
      |
      v
/implement     ->  AI-led task-by-task implementation
      |
      v
/validate      ->  Verify session completeness
      |
      v
/updateprd     ->  Sync PRD, mark session complete
      |
      +-------------> Loop back to /plansession
                      until ALL phase sessions complete

Stage 3: PHASE TRANSITION (After All Previous Phase's Sessions Are Complete)

/audit             ->  Local dev tooling (formatter, linter, types, tests, observability, hooks)
      |
      v
/pipeline          ->  CI/CD workflows (quality, build, security, integration, ops)
      |
      v
/infra             ->  Production infrastructure (health, security, backup, deploy)
      |
      v
/carryforward      ->  Capture lessons learned (optional but recommended)
      |
      v
/documents         ->  Audit and update documentation
      |
      v
[User Action]      ->  Manual testing and LLM audit (HIGHLY recommended)
      |
      v
/phasebuild        ->  Create next phase structure
      |
      v
                   ->  Return to Stage 2 for new phase

Directory Structure

Projects using this system follow this layout:

project/
|-- .spec_system/               # All spec system files
|   |-- state.json              # Project state tracking
|   |-- CONSIDERATIONS.md       # Institutional memory (lessons learned)
|   |-- SECURITY-COMPLIANCE.md  # Security posture & GDPR compliance
|   |-- CONVENTIONS.md          # Project coding standards and conventions
|   |-- PRD/                    # Product requirements
|   |   |-- PRD.md              # Master PRD
|   |   \-- phase_NN/           # Phase definitions
|   |-- specs/                  # Implementation specs
|   |   \-- phaseNN-sessionNN-name/
|   |       |-- spec.md
|   |       |-- tasks.md
|   |       |-- implementation-notes.md
|   |       |-- security-compliance.md
|   |       \-- validation.md
|   |-- scripts/                # Bash automation (if copied locally)
|   \-- archive/                # Completed work
\-- (project source files)

Monorepo Directory Structure

Monorepo projects use the same single .spec_system/ at the repo root. Sessions reference their target package in metadata (spec.md header and state.json), not in directory names.

monorepo-project/
|-- .spec_system/               # Single spec system at repo root
|   |-- state.json              # Includes monorepo flag + packages array
|   |-- CONVENTIONS.md          # Includes Workspace Structure table
|   |-- CONSIDERATIONS.md
|   |-- SECURITY-COMPLIANCE.md
|   |-- PRD/
|   |   |-- PRD.md              # Includes Package Map section
|   |   \-- phase_00/
|   |       |-- session_01_project_setup.md
|   |       |-- session_02_web_scaffold.md      # Package: apps/web
|   |       \-- session_03_api_models.md        # Package: apps/api
|   |-- specs/
|   |   |-- phase00-session01-project-setup/    # Cross-cutting (no package)
|   |   |-- phase00-session02-web-scaffold/     # Scoped to apps/web
|   |   \-- phase00-session03-api-models/       # Scoped to apps/api
|   \-- archive/
|-- apps/
|   |-- web/                    # Frontend package
|   \-- api/                    # Backend package
\-- packages/
    \-- shared/                 # Shared library

Key differences from single-repo:

• Session stubs gain optional Package: annotation
• spec.md headers include Package: and Package Stack: fields
• CONVENTIONS.md includes a Workspace Structure table
• Session numbering is global within a phase (interleaved across packages)

Session Naming Convention

Format: phaseNN-sessionNN-name

• phaseNN: 2-digit phase number (phase00, phase01)
• sessionNN: 2-digit session number (session01, session02)
• name: lowercase-hyphenated description

Examples:

• phase00-session01-project-setup
• phase01-session03-user-authentication
• phase02-session08b-refinements

Session Scope Rules

Hard Limits (Reject if Exceeded)

| Limit | Value | |-------|-------| | Maximum tasks | 25 | | Maximum duration | 4 hours | | Objectives | Single clear objective |

Ideal Targets

| Target | Value | |--------|-------| | Task count | 12-25 (sweet spot: 20) | | Duration | 2-3 hours | | Focus | Stable/late MVP |

Task Design

Task Format

- [ ] TNNN [SNNMM] [P] Action verb + what + where (`path/to/file`)

Components:

• TNNN: Sequential task ID (T001, T002, ...)
• [SNNMM]: Session reference (S0103 = Phase 01, Session 03)
• [P]: Optional parallelization marker
• Description: Action verb + clear description
• Path: File being created/modified

Task Categories

1. Setup (2-4 tasks): Environment, directories, config
2. Foundation (4-8 tasks): Core types, interfaces, base classes
3. Implementation (8-15 tasks): Main feature logic
4. Testing (3-5 tasks): Tests, validation, verification

Parallelization

Mark tasks [P] when they:

• Create independent files
• Don't depend on each other's output
• Can be done in any order

Critical Requirements

ASCII Encoding (Non-Negotiable)

All files must use ASCII-only characters (0-127):

• NO Unicode characters
• NO emoji
• NO smart quotes - use straight quotes (" ')
• NO em-dashes - use hyphens (-)
• Unix LF line endings only (no CRLF)

Validate with:

file filename.txt        # Should show: ASCII text
grep -P '[^\x00-\x7F]' filename.txt  # Should return nothing

Over-Arching Rules

• Complete one session at a time before starting next
• Update task checkboxes immediately as work progresses
• Follow workflow sequence - resist scope creep
• Read spec.md and tasks.md before implementing

State Tracking

The .spec_system/state.json file tracks project progress:

{
  "version": "2.0",
  "project_name": "Project Name",
  "current_phase": 0,
  "current_session": null,
  "phases": {
    "0": {
      "name": "Foundation",
      "status": "in_progress",
      "session_count": 5
    }
  },
  "completed_sessions": [],
  "next_session_history": []
}

Monorepo State Tracking

When monorepo is confirmed true, state.json gains a packages array and uses object-form completed_sessions:

{
  "version": "2.0",
  "project_name": "Acme Platform",
  "monorepo": true,
  "packages": [
    { "name": "web", "path": "apps/web", "type": "frontend", "stack": "TypeScript + React" },
    { "name": "api", "path": "apps/api", "type": "backend", "stack": "Python 3.12 + FastAPI" },
    { "name": "shared", "path": "packages/shared", "type": "library", "stack": "TypeScript" }
  ],
  "current_phase": 0,
  "current_session": "phase00-session04-api-models",
  "phases": {
    "0": { "name": "Foundation", "status": "in_progress", "session_count": 6 }
  },
  "completed_sessions