Skip to content
/

SpecPulse

specpulse · specpulse/specpulse · ★ 385 · last commit 2025-11-30

Deploys an identical spec-driven workflow across 8 AI platforms using a CLI-first scaffold that the AI then populates.

Best whenThe CLI creates file structure deterministically first; AI only fills content into pre-existing paths — preventing directory hallucination failures.
vs seeds
spec-kithas 18). Unlike superpowers or BMAD-METHOD, it is entirely command-driven w…
Primitive shape 12 total
Commands 12
00

Summary

SpecPulse — Summary

SpecPulse (v2.7.5) is a Python-based CLI framework that installs a "CLI-First, AI-Enhanced" specification-driven workflow across 8 AI platforms simultaneously — Claude Code, Gemini CLI, Windsurf, Cursor, GitHub Copilot, OpenCode, Crush, and Qwen Code. The user installs with pip install specpulse, runs specpulse init my-project --ai claude, and then gets an identical 11-command /sp-* surface injected into whichever AI tools are in use. Its core insight is a two-step pattern: the CLI creates reliable cross-platform file structure first, then the AI fills in content — providing a deterministic scaffold that never fails even if the AI misbehaves. State is stored entirely under .specpulse/ (specs, plans, tasks, memory/context.md) and commands like /sp-llm-enforce act as a compliance watchdog. SpecPulse is most similar to openspec (command + file-layout approach) but surpasses it in breadth by deploying to 8 runtimes rather than one; it lacks openspec's hook mirroring, git worktree isolation, and has no dedicated CLI subcommands separate from the AI slash commands. Compared to spec-kit (the closest seed), SpecPulse trades per-command hooks for universality: where spec-kit mirrors every command with 2 lifecycle hooks, SpecPulse has none.

01

Overview

SpecPulse — Overview

Origin

SpecPulse is a Python package published to PyPI (pip install specpulse) at version 2.7.5 (December 2025). The project is maintained by a small team under the specpulse GitHub organization. The primary repo language is Python; commands are distributed as Markdown templates copied to each AI tool's commands directory at init time.

Philosophy

SpecPulse positions itself as "The Complete AI-Enhanced Development Framework" and explicitly opposes "jumping directly to coding without proper planning." Its manifesto:

"Traditional development is chaotic: ideas jump directly to coding without proper planning, requirements get lost in scattered documentation, AI assistants lack context about your project structure."

The framework introduces AI-Enhanced Specification-Driven Development: specs before code, AI populates those specs, tasks break down from specs, and execution is continuous.

Its most distinctive architectural opinion is the CLI-First + AI-Enhancement duality:

"CLI Creates Foundation (Always Works) → AI Enhances Content (Safe Operations)"

This means the CLI generates empty spec skeletons, directory structures, and index files deterministically — then the AI model fills content into already-created files. The AI is explicitly forbidden from creating directories directly; it only writes into paths the CLI has already established.

Manifesto-style Quotes

  • "SpecPulse uses a revolutionary CLI-First with AI Enhancement approach."
  • "CLI First: Creates reliable, cross-platform structure that never fails."
  • "AI Enhanced: Leverages AI for what it does best — detailed content creation."
  • "Platform Independence: Works identically on Windows, macOS, Linux."
  • "Always start with /sp-pulse — this is your entry point to everything!"

Supported Platforms

8 platforms with identical command surface: Claude Code, Gemini CLI, Windsurf, Cursor, GitHub Copilot, OpenCode, Crush, Qwen Code.

02

Architecture

SpecPulse — Architecture

Distribution

  • Type: Python CLI package (PyPI: specpulse)
  • Install: pip install specpulse or pip install specpulse==2.7.5
  • Language: Python 3.11+
  • Version analyzed: 2.7.5

Installation Flow

  1. pip install specpulse — installs the CLI binary specpulse
  2. specpulse init my-project --ai claude — creates project scaffold and deploys AI platform commands
  3. Navigate to project directory and open AI tool
  4. Run /sp-pulse <feature-name> inside the AI to start working

Directory Tree (post-init)

my-project/
├── .specpulse/              # All project data
│   ├── specs/               # Spec files per feature (001-name/, 002-name/, ...)
│   │   └── 001-feature/
│   │       ├── spec-001.md
│   │       ├── plan-001.md
│   │       └── tasks-001.md
│   ├── memory/
│   │   └── context.md       # Active feature context + history
│   └── features.json        # Feature index
├── .claude/                 # Claude Code commands (auto-deployed on init)
│   └── commands/
│       ├── sp-pulse.md
│       ├── sp-spec.md
│       ├── sp-plan.md
│       ├── sp-task.md
│       ├── sp-execute.md
│       ├── sp-status.md
│       ├── sp-validate.md
│       ├── sp-continue.md
│       ├── sp-decompose.md
│       ├── sp-clarify.md
│       ├── sp-llm-enforce.md
│       └── sp-test.md
├── README.md
└── package.json

Equivalent command directories are created for all 8 target platforms (.gemini/, .cursor/, .windsurf/, etc.).

Required Runtime

  • Python 3.11+
  • No Docker required
  • No Node.js required for the framework itself (Node not needed for spec operations)

Target AI Tools

Claude Code, Gemini CLI, Windsurf, Cursor, GitHub Copilot, OpenCode, Crush, Qwen Code

Repo Structure (Python Package)

specpulse/
├── cli/             # Click-based CLI handlers
│   ├── commands/    # init, status, validate, etc.
│   └── main.py
├── core/            # Feature management, spec operations
├── models/          # Spec, plan, task data models
├── monitor/         # Task monitoring and progress analytics
├── resources/       # Markdown command templates per platform
│   ├── commands/
│   │   ├── claude/
│   │   │   ├── sp-pulse.md
│   │   │   ├── sp-spec.md
│   │   │   └── ... (12 templates)
│   │   ├── gemini/
│   │   ├── cursor/
│   │   └── ... (8 platform dirs)
│   └── templates/
└── utils/
03

Components

SpecPulse — Components

Commands (12 slash commands, identical across 8 platforms)

Command Purpose
/sp-pulse [feature] Initialize new feature; entry point to everything
/sp-spec "description" Create detailed specification for a feature
/sp-plan Generate implementation plan from spec
/sp-task Break plan into concrete development tasks
/sp-execute Execute tasks continuously in sequence
/sp-status Check current feature progress
/sp-validate Validate completed work against spec
/sp-continue feature-id Switch to an existing feature context
/sp-decompose spec-id Decompose a specification into sub-specs
/sp-clarify spec-id Clarify ambiguous requirements in a spec
/sp-llm-enforce [action] Enforce LLM compliance with spec workflow
/sp-test Run tests and validate implementation

CLI Binary Commands (specpulse binary)

Subcommand Purpose
specpulse init <project> --ai <platform> Initialize project + deploy platform commands
specpulse spec create <name> Create spec file programmatically
specpulse plan create Create plan from spec
specpulse task list List current tasks
specpulse status Show project status
specpulse validate Validate spec/plan consistency

Skills

None (SpecPulse does not use the claude-plugin skills/ format — it uses slash commands exclusively).

Subagents

None explicitly. The /sp-create command uses subagent spawning for codebase exploration (mentioned in create.md pattern), but no named persona files.

Hooks

None. SpecPulse does not ship .claude/settings.json or hooks.json. No lifecycle hooks are registered.

MCP Servers

None.

Scripts

The specpulse CLI binary itself acts as the scripting layer. The Python CLI handles:

  • specpulse init — creates directories, copies command templates
  • specpulse spec create — creates spec file scaffolds

Templates

12 Markdown command templates per platform × 8 platforms = 96 template files total. Key template content is in specpulse/resources/commands/<platform>/.

State Files

  • .specpulse/memory/context.md — active feature, navigation state
  • .specpulse/specs/<ID>/spec-*.md — spec documents
  • .specpulse/specs/<ID>/plan-*.md — implementation plans
  • .specpulse/specs/<ID>/tasks-*.md — task breakdowns
  • .specpulse/features.json — feature index with IDs, statuses
05

Prompts

SpecPulse — Prompts

Prompt 1: /sp-pulse Command (Feature Initialization)

Source: specpulse/resources/commands/claude/sp-pulse.md

Technique: Structured procedural prompt with explicit failure-handling and rollback logic.

---
name: sp-pulse
description: Initialize new features and manage project context without SpecPulse CLI
allowed_tools:
  - Read
  - Write
  - Edit
  - Bash
  - TodoWrite
  - Glob
---

# /sp-pulse Command

Initialize new features and manage project context without SpecPulse CLI. Works completely independently through LLM-safe file operations.

## Usage
/sp-pulse [feature-name]           # Initialize new feature
/sp-pulse status                   # Show current feature status
/sp-pulse list                     # List all features

## Implementation

When called with `/sp-pulse {{args}}`, I will:

### 2. For Feature Initialization

#### A. Generate Universal Feature ID
- Scan existing feature directories in `.specpulse/specs/`
- Find highest used number (001, 002, 003, etc.)
- Generate next sequential ID with zero-padding
- Create feature name from input (kebab-case)

#### B. Create Directory Structure (Atomic Operations)
**I will use atomic file operations to prevent corruption:**

**Atomic Directory Creation:**
- Use **Bash** with `mkdir -p` for atomic directory creation
- Validate each directory creation before proceeding
- Rollback entire operation if any step fails

**Safe File Operations:**
- Use **Write** tool with full file content (not partial updates)
- Validate file paths are within `.specpulse/` directory only
- Create backup copies before overwriting existing files

**Rollback Mechanism:**
- Track all created files and directories
- If any step fails, use **Bash** to remove partial creations
- Restore original state from backups
- Report specific failure points with recovery instructions

Notable technique: Explicit atomicity contract — the LLM is instructed to treat directory creation as a transaction with rollback.


Prompt 2: /sp-task Command (Task Generation)

Source: specpulse/resources/commands/claude/sp-task.md (inferred from README description)

Technique: Structured output generation with YAML-in-Markdown schema enforcement.

From README:

---
id: task-001
status: todo
title: "Set up authentication middleware"
description: |
  - What problem does this solve?: Foundation for secure route protection
  - Why is this necessary?: All protected endpoints require authentication
  - How will this be done?: Express middleware with JWT validation
  - When is this complete?: Middleware successfully validates tokens

files_touched:
  - path: src/middleware/auth.js

Notable technique: The task format enforces a 4-question answer schema for every task description (what/why/how/when) — preventing shallow tasks that only name an action without explaining its rationale.


Prompt 3: /sp-llm-enforce (Compliance Watchdog)

Source: specpulse/resources/commands/claude/sp-llm-enforce.md (named in README)

Technique: LLM self-policing / meta-compliance. This command asks the AI to verify its own adherence to the spec-driven workflow, checking whether it followed the correct step sequence before proceeding. No verbatim content available; behavior described in README as "LLM compliance enforcement."

09

Uniqueness

SpecPulse — Uniqueness & Positioning

differs_from_seeds

SpecPulse is closest to openspec in its mirror-command architecture (every workflow step has a matching slash command) and its file-layout discipline, but diverges by targeting 8 AI runtimes simultaneously instead of one. Where openspec ships zero hooks and relies on command mirroring alone, SpecPulse adds a compliance watchdog command (/sp-llm-enforce) and an explicit CLI binary (specpulse) that separates scaffold creation from AI content generation. Compared to spec-kit, SpecPulse drops all lifecycle hooks (spec-kit has 18) in favor of cross-platform universality. Compared to BMAD-METHOD, SpecPulse is command-driven rather than skill/persona-driven, and has no multi-agent orchestration. Against superpowers, SpecPulse lacks Iron Law enforcement, worktree isolation, and automatic TDD gates.

Positioning

SpecPulse occupies the "universal CLI installer" niche: the clearest value proposition is "run pip install specpulse && specpulse init . --ai claude and you have a structured spec workflow on every AI tool you use." It is the most broadly-targeted framework in this batch, prioritizing horizontal coverage over vertical depth.

Distinctive Opinion

The "CLI-First" philosophy — the CLI creates scaffolding deterministically, AI only fills content into pre-existing files — reduces failure modes caused by AI hallucinating directory paths or creating malformed file structures. This is a genuine architectural insight.

Observable Failure Modes

  1. Zero hooks: No lifecycle enforcement means nothing stops the AI from skipping phases or writing code before a spec exists.
  2. No worktree isolation: Concurrent feature work will create file conflicts.
  3. Manual phase transitions: Each step requires a user command; the AI cannot run the full workflow autonomously without user input between phases.
  4. No TDD enforcement: No failing-test-first gate.
  5. 8-platform claim requires ongoing maintenance: Command templates for 8 platforms that each evolve independently are a maintenance burden that could cause drift.

Explicit Antipatterns

None documented. The framework does not explicitly name banned behaviors.

Inspired By

Not explicitly stated; the CLI-AI duality mirrors spec-kit's CLI-command approach.

04

Workflow

SpecPulse — Workflow

Phases

Phase Command Artifact Produced
1. Initialize /sp-pulse <feature-name> .specpulse/specs/<ID>/ directory + context.md
2. Specify /sp-spec "description" spec-<ID>.md with full requirements
3. Plan /sp-plan plan-<ID>.md with architecture decisions
4. Task /sp-task tasks-<ID>.yaml with numbered implementation steps
5. Execute /sp-execute Actual code implementation
6. Validate /sp-validate Validation report
7. Status /sp-status Current feature progress readout

Phase-to-Artifact Map

Phase Artifact
Initialize .specpulse/specs/001-feature/, context.md updated
Specify spec-001.md (problem statement, functional/security/UX/API/data requirements, acceptance criteria)
Plan plan-001.md (architecture decisions, file structure, implementation steps, dependencies, time estimates, testing strategy)
Task tasks-001.yaml (task ID, status, title, description, files_touched)
Execute Source code files
Validate Validation output in session

Approval Gates

SpecPulse does not enforce hard approval gates. The workflow is designed to be continuous (execute all steps in sequence). The /sp-llm-enforce command can be used to block AI if it deviates from the spec workflow, but this is a manual call, not an automated gate.

  • No mandatory human review step
  • No "typed confirm" gate before execution
  • Spec review is informal (user reads spec before /sp-plan)

Spec Format

Markdown (.md files). Specs include structured sections: Problem Statement, Functional Requirements, Security Requirements, User Experience, API Design, Data Models, Acceptance Criteria.

Task Format

YAML-embedded in Markdown:

id: task-001
status: todo
title: "Set up authentication middleware"
description: |
  - What problem does this solve?
  - Why is this necessary?
  - How will this be done?
  - When is this complete?
files_touched:
  - path: src/middleware/auth.js

Execution Mode

Interactive loop — user invokes each phase command; /sp-execute runs tasks continuously until all are done.

06

Memory Context

SpecPulse — Memory & Context

State Storage

All state is file-based under .specpulse/:

File/Dir Purpose
.specpulse/memory/context.md Active feature, navigation state, decision log
.specpulse/specs/<ID>/spec-*.md Feature specifications
.specpulse/specs/<ID>/plan-*.md Implementation plans
.specpulse/specs/<ID>/tasks-*.md Task breakdowns
.specpulse/features.json Feature index (IDs, names, statuses, timestamps)

Memory Type

File-based. No database, no vector store, no Neo4j.

Persistence Scope

Project-level. State lives in the project's .specpulse/ directory. No global state across projects.

Cross-Session Handoff

The .specpulse/memory/context.md file serves as the handoff document. It stores:

  • Active feature ID and name
  • Current workflow step
  • Feature history and navigation
  • Decision log

An AI resuming a session reads context.md to understand where the previous session left off. This is a simple file read — no sophisticated resumption protocol.

Context Compaction

No explicit compaction handling. The context.md file grows linearly as feature history accumulates. No pruning mechanism.

Multi-Session Continuity

The /sp-continue <feature-id> command explicitly reloads a feature's context into the working memory, letting the user switch between features and resume where they left off.

Search Mechanism

None — agents read files directly by path. No full-text search or vector indexing.

07

Orchestration

SpecPulse — Orchestration

Multi-Agent

No explicit multi-agent support. SpecPulse is a single-agent sequential workflow. There are no subagent spawning patterns in the published command templates.

Orchestration Pattern

Sequential. Commands must be run in order: /sp-pulse/sp-spec/sp-plan/sp-task/sp-execute/sp-validate.

Isolation Mechanism

None. SpecPulse does not use git worktrees or branches. All work happens in-place.

Multi-Model

No. Single AI model per session. No model routing.

Execution Mode

Interactive loop. The user drives each phase by issuing slash commands. /sp-execute is semi-autonomous (runs tasks continuously), but start/stop is manual.

Consensus Mechanism

None.

Prompt Chaining

Yes. The /sp-plan command reads the spec file created by /sp-spec; /sp-task reads the plan; /sp-execute reads the tasks. Each stage's output is the input to the next. Classic prompt chain.

Auto-Validators

None built-in. The /sp-validate command exists but is manually invoked. No hooks auto-trigger validation.

Hooks

None registered. SpecPulse has no .claude/settings.json or hooks.json.

Crash Recovery

No. If a session is interrupted, the user must re-invoke the appropriate command. The file-based state means no data is lost, but resumption requires manual re-entry of the workflow step.

Git Automation

None. No automatic commits, PRs, or merges.

08

Ui Cli Surface

SpecPulse — UI & CLI Surface

Dedicated CLI Binary

Exists: Yes
Name: specpulse
Is thin wrapper: No — it's a standalone Python CLI with its own runtime
Install: pip install specpulse

CLI Subcommands

Subcommand Purpose
specpulse init <project> --ai <platform> Initialize project, deploy platform commands
specpulse spec create <name> Programmatically create spec files
specpulse plan create Create plan from spec
specpulse task list List task files
specpulse status Show project status
specpulse validate Validate spec/plan consistency

The CLI is primarily used for project initialization. Day-to-day operations happen through slash commands inside the AI tools, not through the specpulse binary directly.

Local UI

Exists: No
No web dashboard, no TUI, no desktop app is mentioned in the repository.

IDE Integration

SpecPulse deploys commands to 8 AI tool directories. It does not install a dedicated VS Code extension or IDE plugin. Integration is via file-based command templates that each tool auto-discovers.

Observability

No logging, no audit trail, no structured output. Progress tracking is manual via /sp-status.

Platform Deployment Matrix

Platform Directory Created
Claude Code .claude/commands/
Gemini CLI .gemini/commands/
Windsurf .windsurf/workflows/ or similar
Cursor .cursor/commands/
GitHub Copilot .github/prompts/
OpenCode .opencode/command/
Crush Platform-specific dir
Qwen Code TOML configuration

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.