This skill should be used when the user asks about "spec system", "session workflow", "createprd", "nextsession", "sessionspec", "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.
Provides a specification-driven workflow that breaks large projects into 2-4 hour sessions with 12-25 tasks. Triggered by commands like `/nextsession`, `/sessionspec`, `/implement`, `/validate`, or when working in projects with `.spec_system/` directories.
/plugin marketplace add moshehbenavraham/apex-spec-system/plugin install apex-spec@apex-spec-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/workflow.mdA specification-driven workflow system for AI-assisted development that breaks large projects into manageable 2-4 hour sessions with 12-25 tasks each.
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 workflow has 3 distinct stages:
/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)
/nextsession -> Analyze project, recommend next session
|
v
/sessionspec -> Convert to formal specification
|
v
/tasks -> Generate 12-25 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 /nextsession
until ALL phase sessions 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
/documents -> Audit and update documentation
|
v
[User Action] -> Manual testing (highly recommended)
|
v
/carryforward -> Capture lessons learned (optional but recommended)
|
v
/phasebuild -> Create next phase structure
|
v
-> Return to Stage 2 for new phase
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)
│ ├── 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
│ │ └── validation.md
│ ├── scripts/ # Bash automation (if copied locally)
│ └── archive/ # Completed work
└── (project source files)
Format: phaseNN-sessionNN-name
phaseNN: 2-digit phase number (phase00, phase01)sessionNN: 2-digit session number (session01, session02)name: lowercase-hyphenated descriptionExamples:
phase00-session01-project-setupphase01-session03-user-authenticationphase02-session08b-refinements| Limit | Value |
|---|---|
| Maximum tasks | 25 |
| Maximum duration | 4 hours |
| Objectives | Single clear objective |
| Target | Value |
|---|---|
| Task count | 12-25 (sweet spot: 20) |
| Duration | 2-3 hours |
| Focus | Stable/late MVP |
- [ ] 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 markerMark tasks [P] when they:
All files must use ASCII-only characters (0-127):
Validate with:
file filename.txt # Should show: ASCII text
grep -P '[^\x00-\x7F]' filename.txt # Should return nothing
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": []
}
| 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 |
/nextsession | Recommend next session | state.json, PRD | NEXT_SESSION.md |
/sessionspec | Create specification | NEXT_SESSION.md | specs/.../spec.md |
/tasks | Generate task list | spec.md | specs/.../tasks.md |
/implement | Code implementation | spec.md, tasks.md | implementation-notes.md |
/validate | Verify completeness | All session files | 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 | Completed phase artifacts | CONSIDERATIONS.md |
/phasebuild | Create new phase | PRD | PRD/phase_NN/ |
For detailed guidance, consult:
references/workflow.md - Detailed command workflows and decision pointsUtility scripts are available at two locations:
${CLAUDE_PLUGIN_ROOT}/scripts/ (default, always up-to-date).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 functionsTo copy scripts locally during /initspec, choose "copy locally" when prompted. To revert to plugin scripts, delete .spec_system/scripts/.
Commands use a hybrid approach for reliability:
analyze-project.sh --json): Authoritative state factscheck-prereqs.sh --json): Tool and prerequisite validationWhy this matters:
analyze-project.sh JSON Output:
{
"project": "project-name",
"current_phase": 1,
"current_session": "phase01-session02-feature",
"completed_sessions": ["phase00-session01-setup"],
"candidate_sessions": [
{"file": "session_01_auth", "completed": false}
]
}
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"}
},
"issues": [
{"type": "tool", "name": "docker", "message": "required tool not installed"}
]
}
Commands and their script usage:
| Command | analyze-project.sh | check-prereqs.sh |
|---|---|---|
/nextsession | State + candidates | - |
/implement | Current session | Environment + tools |
/validate | Current session | - |
/documents | State + progress | - |
/documents after completing a phase or adding packages| Problem | Solution |
|---|---|
| Scope too large | Split session in PRD before /sessionspec |
| 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 |
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.