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": [
    { "id": "phase00-session01-project-setup", "package": null },
    { "id": "phase00-session02-web-scaffold", "package": "apps/web" },
    { "id": "phase00-session03-shared-types", "package": "packages/shared" }
  ],
  "next_session_history": []
}

The monorepo field uses three states:

| Value | Meaning | Behavior | |-------|---------|----------| | null (or absent) | Unknown / not yet determined | Commands look for signals, prompt if found | | true | Confirmed monorepo | Commands use package-aware logic | | false | Confirmed single-repo | Commands skip package logic entirely |

Single-repo projects see no packages field and keep string-form completed_sessions. Existing state files without monorepo are treated as null (unknown), which behaves identically to classic single-repo until the user confirms otherwise.

Command Quick Reference

| Command | Purpose | Input | Output | |---------|---------|-------|--------| | /initspec | Initialize spec system | Project info | .spec_system/ structure | | /createprd | Generate master PRD | Requirements doc or user text | PRD/PRD.md | | /createuxprd | Generate UX PRD | Design docs or user text | PRD/PRD_UX.md | | /plansession | Analyze, spec, and task list | state.json, PRD | specs/.../spec.md + tasks.md | | /implement | Code implementation | spec.md, tasks.md | implementation-notes.md | | /validate | Verify completeness | All session files | security-compliance.md, validation.md | | /updateprd | Mark complete | validation.md | Updated state.json | | /audit | Local dev tooling | CONVENTIONS.md | Updated tools, report | | /pipeline | CI/CD workflows | CONVENTIONS.md | Workflow files, report | | /infra | Production infra | CONVENTIONS.md | Configs, report | | /documents | Audit/update docs | state.json, PRD, codebase | Updated docs, docs-audit.md | | /carryforward | Capture lessons & security posture | Completed phase artifacts | CONSIDERATIONS.md, SECURITY-COMPLIANCE.md | | /phasebuild | Create new phase | PRD | PRD/phase_NN/ |

Utility Commands

Standalone helpers that operate outside the session workflow. They do not affect session state and can be run at any time. See docs/UTILITIES.md for the full reference and conventions for adding new utility commands.

Additional Resources

Scripts Directory

Utility scripts are available at two locations:

• Plugin: ${CLAUDE_PLUGIN_ROOT}/scripts/ (default, always up-to-date)
• Local: .spec_system/scripts/ (optional, for per-project customization)

Local scripts take precedence - if .spec_system/scripts/ exists, commands use local scripts instead of plugin scripts.

Available scripts:

• analyze-project.sh - Project state analysis (supports --json for structured output)
• check-prereqs.sh - Environment and tool verification (supports --json for structured output)
• common.sh - Shared functions

To copy scripts locally during /initspec, choose "copy locally" when prompted. To revert to plugin scripts, delete .spec_system/scripts/.

Hybrid Architecture

Commands use a hybrid approach for reliability:

1. Deterministic State (analyze-project.sh --json): Authoritative state facts
2. Environment Verification (check-prereqs.sh --json): Tool and prerequisite validation
3. Semantic Analysis (Claude): Interprets PRD content, makes recommendations

Why this matters:

• Script output is deterministic - same input always gives same output
• Eliminates risk of Claude misreading state.json
• Tool verification catches missing dependencies BEFORE implementation starts
• Users can run scripts independently to debug
• Claude focuses on what it does best: understanding context and reasoning

analyze-project.sh JSON Output:

{
  "project": "project-name",
  "monorepo": true,
  "packages": [
    {"name": "web", "path": "apps/web", "type": "frontend", "stack": "TypeScript + React"}
  ],
  "active_package": {"name": "web", "path": "apps/web"},
  "monorepo_detection": null,
  "current_phase": 1,
  "current_session": "phase01-session02-feature",
  "completed_sessions": [
    {"id": "phase00-session01-setup", "package": null}
  ],
  "candidate_sessions": [
    {"file": "session_01_auth", "completed": false, "package": "apps/web"}
  ]
}

For single-repo projects: monorepo is null or false, packages is [], active_package is null, and completed_sessions uses the string array format.

check-prereqs.sh JSON Output:

{
  "overall": "pass",
  "environment": {
    "spec_system": {"status": "pass"},
    "jq": {"status": "pass", "info": "jq-1.7"}
  },
  "tools": {
    "node": {"status": "pass", "info": "v20.10.0"},
    "docker": {"status": "fail", "info": "not installed"}
  },
  "package": {
    "registered": {"status": "pass", "info": "apps/web"},
    "directory": {"status": "pass", "info": "apps/web"},
    "manifest": {"status": "pass", "info": "package.json"},
    "stack": {"status": "pass", "info": "TypeScript"}
  },
  "workspace": {
    "status": {"status": "pass", "info": "monorepo detected"},
    "manager": {"status": "pass", "info": "pnpm"},
    "runner": {"status": "pass", "info": "turbo"}
  },
  "database": {
    "type": {"status": "pass", "info": "PostgreSQL"},
    "migration_tool": {"status": "pass", "info": "prisma"},
    "tool_available": {"status": "pass", "info": "npx prisma"},
    "seed_script": {"status": "warn", "info": "no seed script found"}
  },
  "issues": [
    {"type": "tool", "name": "docker", "message": "required tool not installed"}
  ]
}

The package and workspace sections appear only when --package is used or monorepo is detected. The database section only appears when DB signals are detected in the project. For single-repo projects without databases, these sections are empty objects ({}).

Commands and their script usage:

| Command | analyze-project.sh | check-prereqs.sh | |---------|-------------------|------------------| | /plansession | State + candidates | - | | /implement | Current session | Environment + tools | | /validate | Current session | - | | /documents | State + progress | - |

Monorepo Support

The system supports monorepo projects through a "gentle assumption" -- it auto-detects multi-package structures and offers package-aware workflows, but never requires them. Single-repo projects see zero behavioral change.

How It Works

1. Detection is layered across commands:

   • /initspec (brownfield): Detects existing workspace configs (pnpm, npm, turbo, nx, cargo, go, lerna)
   • /createprd (greenfield): Parses PRD content for multi-package signals
   • /phasebuild: Checkpoint -- warns if PRD references packages but state lacks them
   • Later commands: Opportunistic detection if workspace configs appear

2. Package context flows through sessions:

   • /plansession determines the target package (user input, stub annotation, or prompt)
   • spec.md headers include Package: and Package Stack: fields
   • Task file paths are scoped to the package directory (e.g., apps/web/src/auth.ts)
   • /implement validates files stay within declared package scope
   • /updateprd records package in completed_sessions

3. Session numbering is global within a phase:

   • Sessions interleave across packages (session 02 might be apps/web, session 03 apps/api)
   • Phase completion requires ALL sessions done, regardless of which packages they target
   • One ordered list of sessions per phase -- simple progress tracking

4. Scripts accept --package flag for scoped operations:

   • analyze-project.sh --json --package apps/web -- filters candidates by package
   • check-prereqs.sh --json --package apps/web -- validates package-specific tools

Supported Workspace Managers

| Manager | Detection File | |---------|---------------| | pnpm | pnpm-workspace.yaml | | npm/yarn | package.json with "workspaces" field | | Turborepo | turbo.json | | Nx | nx.json | | Cargo | Cargo.toml with [workspace] | | Go | go.work | | Lerna | lerna.json |

Per-Package Stack Detection

Each package gets a stack field based on its manifest files:

| Stack | Indicator | |-------|-----------| | TypeScript | tsconfig.json | | JavaScript | package.json (no tsconfig) | | Rust | Cargo.toml | | Go | go.mod | | Python | pyproject.toml, setup.py, or requirements.txt | | Ruby | Gemfile | | Java | pom.xml, build.gradle, or build.gradle.kts |

Best Practices

1. Start with /plansession - Always analyze state before choosing work
2. One session at a time - Complete before starting next
3. MVP first - Defer polish and optimizations
4. Validate encoding - Check ASCII before committing
5. Update tasks continuously - Mark checkboxes immediately
6. Trust the system - Follow workflow, resist scope creep
7. Read before implementing - Review spec.md and tasks.md first
8. Keep docs current - Run /documents after completing a phase or adding packages

Troubleshooting

| Problem | Solution | |---------|----------| | Scope too large | Split session in PRD before /plansession | | ASCII validation fails | Run grep -P '[^\x00-\x7F]' to find issues | | State out of sync | Manually update .spec_system/state.json | | Commands not found | Verify plugin is enabled | | Tasks taking too long | Reduce scope, defer non-MVP items | | Missing tools | Run check-prereqs.sh --tools "tool1,tool2" to verify | | Environment issues | Run check-prereqs.sh --env to diagnose | | Stale documentation | Run /documents to audit and update | | Missing docs | Run /documents to create standard files | | Lint/format issues | Run /audit to add tooling and auto-fix | | CI failures | Run /pipeline to add workflows and fix errors | | Infra not validated | Run /infra to configure health, security, backup, deploy | | Monorepo not detected | Run /initspec on an existing repo or describe packages in PRD for /createprd | | Wrong package context | Specify package when running /plansession (e.g., "plan for apps/web") | | Cross-package session | Set package to null for sessions spanning multiple packages | | Package tools missing | Run check-prereqs.sh --json --package apps/web to diagnose |

Monorepo Error Recovery

Monorepo not detected by /initspec: Workspace config may have been added after init, or uses a non-standard layout. Manually set "monorepo": true in state.json, add a packages array, add the Workspace Structure table to CONVENTIONS.md, then run /createprd or /plansession to pick up the config.

Session planned for wrong package: If caught before /updateprd, delete the session spec directory and re-run /plansession with the correct package. If caught after /updateprd, manually edit the package field in the relevant completed_sessions entry in state.json.

Package added mid-project: Add the package entry to state.json's packages array, update CONVENTIONS.md's Workspace Structure table, add session stubs to PRD/phase_NN/ with Package: annotations, and increment session_count in the phase's state entry.

Cross-package dependency discovered mid-session: Complete the current session with stubs/interfaces, note the dependency in implementation-notes.md, and plan the shared package session next. Use a cross-cutting session (package: null) when work genuinely spans packages.

Different packages need different tool versions: Use workspace-level version management (.nvmrc per package, engines in package.json). /audit handles shared tools at root with per-package overrides. Validate with check-prereqs.sh --package apps/web.

State disagrees with workspace configs: Run analyze-project.sh --json -- it reports both the state.json monorepo flag and live monorepo_detection. Compare them and update state.json manually if needed.

Decision Quick Reference

| Situation | Action | |-----------|--------| | New empty project | /initspec sets monorepo: null, deferred to /createprd | | Existing monorepo project | /initspec auto-detects, confirms with user | | PRD describes multiple services | /createprd prompts to confirm monorepo | | Session targets one package | /plansession scopes spec and tasks to that package | | Session spans packages | Use cross-cutting session (package: null) | | Need to add a package mid-project | Manually update state.json and CONVENTIONS.md | | Phase has mixed-package sessions | Normal -- sessions interleave, phase completes when all done | | Different stacks per package | /audit and /pipeline handle per-package tool config |