Skip to content
/
Tier B A4 Markdown scaffold

spec-based-claude-code

spec-based-claude-code · papaoloba/spec-based-claude-code · ★ 129 · last commit 2025-07-22

Ten slash commands enforce requirements→design→tasks→implement with file-marker approval gates in plain Claude Code, zero dependencies.

Best whenApproval gates should be enforced by empty filesystem marker files read at command invocation, not by hooks or programmatic validators.
Skip ifSkipping the requirements phase, Starting implementation before all three phases are approved
vs seeds
spec-kit(Archetype 2, 9 cmd + 9 skill + 18 hooks), this is the minimal version: same sequential approval gate concept but none o…
Primitive shape 10 total
Commands 10
00

Summary

spec-based-claude-code — Summary

A lightweight Claude Code implementation of spec-driven development using 10 custom slash commands. Each command maps to one phase of a four-step workflow: requirements → design → tasks → implementation. Phase advancement is gated by explicit approval commands that create .requirements-approved, .design-approved, and .tasks-approved marker files in the spec directory.

The methodology is pure markdown-and-Claude-Code — no CLI binary, no npm package, no hooks, and no MCP server. Users install it by copying the .claude/commands/spec/ directory into their own project. A spec/.current-spec file tracks the active feature spec, enabling multi-spec projects to switch context.

Closest seed match is openspec (Archetype 2 — mirror commands pattern) without the mirrored skills layer: spec-based-claude-code ships commands only, with no autonomous-activation skill counterparts and no lifecycle hooks. It is the most minimal "slash-command-only" SDD implementation in this batch.

01

Overview

spec-based-claude-code — Overview

Origin

Created by papaoloba. GitHub description: "Implementation of a Spec-Driven Development workflow in Claude Code using custom slash commands." Published 2025, written in TypeScript (for the todo-app example). 129 stars, 14 forks.

Philosophy

The project's core belief is that AI coding agents produce better results when planning is separated from coding. Each phase (requirements, design, tasks, implementation) must be reviewed and explicitly approved before proceeding. This prevents the agent from conflating planning with execution, which the README identifies as a root cause of off-spec implementations.

From the README:

"This guide implements a spec-driven development workflow in Claude Code using custom slash commands. The workflow enforces a structured approach where specifications are created, reviewed, and approved before implementation begins."

On the core concept:

"Each feature is developed through four sequential phases:

  1. Requirements — Define WHAT needs to be built
  2. Design — Determine HOW it will be built
  3. Tasks — Plan WHEN and in what order
  4. Implementation — Execute the plan with progress tracking"

On benefits:

"Catch problems early — Identify and resolve requirement ambiguities before coding. Maintain control — Review and approve each phase before proceeding. Iterate safely — Modify specifications without losing conversation context. Keep AI focused — Separate planning from coding for better results."

Target audience

Individual Claude Code users who want structure around AI-assisted feature development without installing any additional tooling. The README is written as a "guide" rather than a framework documentation — it shows users how to manually create the directory structure and command files.

02

Architecture

spec-based-claude-code — Architecture

Distribution

  • Type: methodology-doc / command-pack
  • Install: Clone the repository and copy .claude/commands/spec/ into your project
  • Install complexity: clone-and-configure

Directory tree

spec-based-claude-code/
├── .claude/
│   └── commands/
│       └── spec/           ← 10 slash commands (markdown files)
│           ├── new.md
│           ├── requirements.md
│           ├── design.md
│           ├── tasks.md
│           ├── approve.md
│           ├── implement.md
│           ├── review.md
│           ├── status.md
│           ├── switch.md
│           └── update-task.md
├── spec/                   ← Runtime (created by user; holds specs)
│   ├── 001-feature/
│   │   ├── README.md       ← Current phase document
│   │   ├── .requirements-approved
│   │   ├── .design-approved
│   │   └── .tasks-approved
│   └── .current-spec       ← Active spec tracker
├── templates/              ← Phase document templates
├── CLAUDE.md               ← Project guidance
└── todo-app/               ← Example project (TypeScript)

Required runtime

  • Claude Code
  • Git (recommended)
  • No Node.js, Python, or Go required

Target AI tools

  • Primary: Claude Code (slash commands are Claude Code-specific)
  • Not portable to Cursor/Windsurf/Copilot without adaptation

Config files

File Purpose
CLAUDE.md Project guidance and command reference for Claude Code
spec/.current-spec Tracks active specification name
.claude/settings.local.json Custom tool permissions per command
03

Components

spec-based-claude-code — Components

Commands (10 slash commands)

Command Purpose
/spec:new Initialize new spec directory (numbered, e.g., 001-feature-name) and create README.md
/spec:requirements Generate requirements.md for active spec with user stories, acceptance criteria, and priority tiers
/spec:design Generate design.md (after requirements approved): architecture, data model, API design, tech stack
/spec:tasks Generate tasks.md (after design approved): atomic ordered implementation steps
/spec:approve Approve current phase — creates .requirements-approved, .design-approved, or .tasks-approved marker
/spec:implement Start implementation (after tasks approved) — follows task list in order
/spec:review Review current phase document — suggest improvements, flag gaps
/spec:status Show active spec and current phase (reads .current-spec and approval markers)
/spec:switch Switch active spec by updating .current-spec file
/spec:update-task Mark a task complete in tasks.md (by task number)

Skills

None.

Subagents

None.

Hooks

None.

MCP Servers

None.

Scripts

None.

Templates

The templates/ directory contains blank phase document templates:

  • Requirements template
  • Design template
  • Tasks template

Tool permissions (from command frontmatter)

Each command declares its allowed tools via YAML frontmatter. Examples:

  • /spec:new: Bash(mkdir:*), Bash(echo:*), Bash(date:*), Bash(ls:*)
  • /spec:requirements: Bash(cat:*), Bash(test:*), Bash(touch:*), Write
  • /spec:design: Bash(cat:*), Bash(test:*), Bash(ls:*), Write
  • /spec:tasks: Bash(cat:*), Bash(test:*), Write
05

Prompts

spec-based-claude-code — Prompts

Excerpt 1 — /spec:requirements command (from README verbatim)

---
allowed-tools: Bash(cat:*), Bash(test:*), Bash(touch:*), Write
description: Create or review requirements specification
---

## Context

Current spec: !`cat spec/.current-spec 2>/dev/null || echo "No active spec"`
Spec directory contents: !`ls -la spec/$(cat spec/.current-spec 2>/dev/null)/ 2>/dev/null || echo "Spec not found"`

## Your Task

For the current active specification:

1. Check if requirements.md exists
2. If not, create a comprehensive requirements.md with:
   - Feature overview
   - User stories with acceptance criteria
   - Functional requirements (P0, P1, P2)
   - Non-functional requirements
   - Constraints and assumptions
   - Out of scope items
   - Success metrics
3. If it exists, display current content and suggest improvements
4. Remind user to use `/spec:approve requirements` when ready

Use the Write tool to create/update the requirements.md file.

Prompting technique: Dynamic context injection via ! bash-eval syntax. The command reads the current spec name and directory listing at invocation time, injecting live filesystem context before the prompt instructions. This avoids stale context without hooks.

Excerpt 2 — /spec:design command (from README verbatim)

---
allowed-tools: Bash(cat:*), Bash(test:*), Bash(ls:*), Write
description: Create technical design specification
---

## Context

Current spec: !`cat spec/.current-spec 2>/dev/null`
Requirements approved: !`test -f spec/$(cat spec/.current-spec)/.requirements-approved && echo "Yes" || echo "No"`
Current directory: !`ls -la spec/$(cat spec/.current-spec)/ 2>/dev/null`

## Your Task

1. Verify requirements are approved (look for .requirements-approved file)
2. If not approved, inform user to complete requirements first
3. If approved, create/update design.md with:
   - Architecture overview (with diagrams)
   - Technology stack decisions
   - Data model and schema
   - API design
   - Security considerations
   - Performance considerations
   - Deployment architecture
   - Technical risks and mitigations
4. Use ASCII art or mermaid diagrams where helpful

Use the Write tool to create the design document.

Prompting technique: Gate enforcement via bash-eval context. The approval check (test -f ...approved) is run at prompt evaluation time and injected as "Yes" or "No" text — the agent reads this and self-enforces the gate rather than relying on a separate validation step.

09

Uniqueness

spec-based-claude-code — Uniqueness

differs_from_seeds

Closest to openspec (Archetype 2 — mirror commands+skills pattern) but without the skills layer. Where openspec ships both a slash command and an autonomous-activation skill for each workflow phase (11 commands + 11 skills), spec-based-claude-code ships only slash commands (10) with no skill counterparts and no lifecycle hooks. The gate enforcement mechanism is distinctive: rather than using hooks or programmatic validation, approval is tracked via empty marker files (.requirements-approved) that commands read via bash-eval syntax at invocation time — a pure-filesystem gate. Compared to spec-kit (Archetype 2, 9 commands + 9 skills + 18 hooks), this is the stripped-down version: same sequential approval gate concept but none of the hook infrastructure. Against kiro (Archetype 5) and 094459-sdd-workshop, this is the Claude-Code-native equivalent — same three-document spec pattern but as slash commands rather than an IDE UI.

Positioning

The minimalist reference implementation of SDD for Claude Code. A practitioner with basic Claude Code knowledge can install it in under 5 minutes by copying one directory. Because it ships no hooks, no skills, and no CLI, there is nothing to conflict with existing project configuration.

The 129 stars suggest it is widely used as a starting point or template for custom SDD implementations.

Observable failure modes

  1. No autonomous triggering: Without skills or hooks, the workflow only runs when the user manually invokes commands. If a developer forgets to run /spec:requirements first, nothing enforces the methodology.
  2. Claude Code-only: The ! bash-eval syntax is Claude Code-specific — users cannot port commands to Cursor, Windsurf, or Copilot without rewriting them.
  3. No automated quality checks: Phase review is purely manual. There is no linting, no acceptance criteria validation, no test requirement.
  4. Linear spec model: The workflow assumes one active spec at a time. While /spec:switch exists, the paradigm is single-spec focus rather than parallel feature development.
  5. No task dependency tracking: tasks.md is a flat checklist, not a dependency graph. Complex multi-dependency features may need manual reordering.
04

Workflow

spec-based-claude-code — Workflow

Phases

Phase Command(s) Artifact Gate
0. Create spec /spec:new <name> spec/001-name/README.md —
1. Requirements /spec:requirements → /spec:approve requirements requirements.md .requirements-approved marker
2. Design /spec:design → /spec:approve design design.md .design-approved marker
3. Tasks /spec:tasks → /spec:approve tasks tasks.md .tasks-approved marker
4. Implementation /spec:implement code changes Task checkboxes

Approval gate mechanism

The /spec:approve command creates a hidden marker file (e.g., .requirements-approved) in the spec directory. Subsequent phase commands check for these markers before proceeding:

/spec:design verifies: .requirements-approved exists
/spec:tasks verifies: .design-approved exists
/spec:implement verifies: .tasks-approved exists

If a marker is missing, the command informs the user and refuses to proceed.

Typical flow

/spec:new user-authentication
/spec:requirements      # Claude generates requirements
/spec:review            # Optional: review phase
/spec:approve requirements  # Creates .requirements-approved
/spec:design            # Claude generates design (checks approval)
/spec:approve design
/spec:tasks             # Claude generates tasks
/spec:approve tasks
/spec:implement         # Claude executes tasks in order
/spec:update-task 3     # Mark task 3 complete as work progresses
/spec:status            # Check current state

Multi-spec management

/spec:switch 002-payment-integration  # Change active spec
/spec:status                          # Shows current spec: 002-payment-integration

Phase document structure (from README)

Requirements:

  • Feature overview, user stories with acceptance criteria
  • Functional requirements (P0, P1, P2 priority tiers)
  • Non-functional requirements
  • Constraints and assumptions
  • Out of scope, success metrics

Design:

  • Architecture overview (with ASCII/mermaid diagrams)
  • Technology stack decisions
  • Data model and schema
  • API design
  • Security, performance, deployment considerations
  • Technical risks and mitigations

Tasks:

  • Atomic ordered steps
  • Checkbox format for progress tracking
  • Each task is small enough to implement in a single focused effort
06

Memory Context

spec-based-claude-code — Memory & Context

State storage

File-based. All state lives in the spec/ directory:

spec/
├── .current-spec                    ← Active spec name (single line)
├── 001-user-authentication/
│   ├── README.md                    ← Current phase document
│   ├── requirements.md
│   ├── design.md
│   ├── tasks.md
│   ├── .requirements-approved       ← Empty marker file
│   ├── .design-approved             ← Empty marker file
│   └── .tasks-approved              ← Empty marker file
└── 002-payment-integration/
    └── ...

Persistence

Project-level. All files are committed to the repository, making spec state auditable and portable across machines.

Context injection mechanism

Commands use !-prefixed bash expressions to inject live filesystem state at invocation:

Current spec: !`cat spec/.current-spec 2>/dev/null || echo "No active spec"`

This means each command invocation reads fresh state — there is no session-level memory or caching. The agent always sees the current filesystem state.

Cross-session handoff

Excellent — all state is in files that persist across sessions. The active spec, current phase, approval status, and task completion are all readable from the filesystem at any time.

Compaction handling

Not addressed. Because state is entirely file-based, context compaction does not affect spec state — a new session simply reads the files again.

Memory type

File-based. Plain Markdown + empty marker files.

State files

File Content
spec/.current-spec Active spec directory name
spec/NNN-name/requirements.md Requirements document
spec/NNN-name/design.md Design document
spec/NNN-name/tasks.md Task list with checkboxes
spec/NNN-name/.requirements-approved Approval marker (empty file)
spec/NNN-name/.design-approved Approval marker
spec/NNN-name/.tasks-approved Approval marker
07

Orchestration

spec-based-claude-code — Orchestration

Multi-agent support

None. Single-agent sequential workflow.

Orchestration pattern

Sequential. The four phases must be executed in order with explicit approval gates between each.

Isolation mechanism

None. All edits happen in-place in the project directory.

Execution mode

Interactive-loop. User invokes commands manually; Claude executes each command in the current session.

Multi-model routing

None.

Prompt chaining

Yes, implicit. Each phase's output becomes the context for the next:

  • Requirements → injected into design prompt via bash-eval
  • Design → read when generating tasks
  • Tasks → followed during implementation

The chaining is managed by the ! bash-eval syntax in each command, which reads the prior artifacts at invocation time.

Consensus mechanism

None.

Auto-validators

None. Validation is entirely manual (user reads and approves each phase document).

Git automation

None automated. The CLAUDE.md suggests conventional commits per phase:

spec(001): complete requirements phase

But this is a recommendation, not an enforced automation.

Crash recovery

Implicit. Because all state is in files, any interrupted session can be resumed by re-running the appropriate command.

08

Ui Cli Surface

spec-based-claude-code — UI / CLI Surface

Dedicated CLI binary

None.

Local web dashboard

None.

IDE integration

Claude Code only. The 10 slash commands are invoked from the Claude Code chat interface as /spec:new, /spec:requirements, etc. No IDE plugin, no extension, no TUI.

Observability

  • /spec:status — Shows active spec and current phase by reading filesystem state
  • Spec directories in spec/ provide a manual audit trail (all phase documents are committed)

Installation

Manual copy:

  1. Clone repository
  2. Copy .claude/commands/spec/ to your project's .claude/commands/spec/
  3. Create spec/ directory and spec/.current-spec file

No shell scripts to run.

Cross-tool portability

Low. The slash commands use Claude Code's ! bash-eval syntax and are not compatible with Cursor's .mdc format or Copilot's instruction files without adaptation.

Related frameworks

same archetype · same primary tool · same memory type

BMAD-METHOD ★ 48k
A4 Markdown scaffold

Provides a full agile delivery lifecycle with named expert-persona AI collaborators that elicit the human's best thinking rather…

Agent OS ★ 4.6k
A4 Markdown scaffold

Extracts implicit codebase conventions into token-efficient markdown standards files and injects them selectively into AI agent…

Claude Conductor ★ 367
A4 Markdown scaffold

Gives Claude Code a persistent, cross-linked, auto-analyzed documentation system so it retains codebase context across sessions.

Spec-Driver (Greenfield Spec-Driven Development) ★ 25
A4 Markdown scaffold

Prevents spec rot in AI-assisted development by making implementation changes flow back into evergreen, authoritative specs via…

Anthropic Knowledge Work Plugins ★ 16k
A4 Markdown scaffold

Role-specialized plugin bundles with live MCP connectors that turn Claude into a domain expert for enterprise knowledge workers.

Codex Integration for Claude Code (skill-codex) ★ 1.3k
A4 Markdown scaffold

Single Claude Code skill that handles Codex CLI invocation correctly (stdin blocking, thinking token suppression, session resume)…