This skill should be used when the user asks about "spec system", "session workflow", "createprd", "plansession", "implement session", "validate session", "phase build", "session scope", "task checklist", or when working in a project containing .spec_system/ directory. Provides guidance for specification-driven AI development workflows.
Instrucciones de origen · Vista previa de solo lectura
name
Apex Spec Workflow
description
This skill should be used when the user asks about "spec system", "session workflow", "createprd", "plansession", "implement session", "validate session", "phase build", "session scope", "task checklist", or when working in a project containing .spec_system/ directory. Provides guidance for specification-driven AI development workflows.
version
1.0.2-beta
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 12-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
/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 (highly recommended)
|
v
/phasebuild -> Create next phase structure
|
v
-> Return to Stage 2 for new phase
{"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"}},"issues":[{"type":"tool","name":"docker","message":"required tool not installed"}]}
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
-
Best Practices
Start with /plansession - Always analyze state before choosing work
One session at a time - Complete before starting next
MVP first - Defer polish and optimizations
Validate encoding - Check ASCII before committing
Update tasks continuously - Mark checkboxes immediately
Trust the system - Follow workflow, resist scope creep
Read before implementing - Review spec.md and tasks.md first
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
