Spec-Driven Steroids

Inject Spec-Driven Development into AI coding tools without building a new UI.

What it is

spec-driven-steroids is an opt-in planning layer for AI coding tools. When invoked, it always requires a written plan and human approval before implementation.

brief (default): brief → approval → implementation → compact review
full (high risk): requirements → design → tasks → Red Team Review → implementation → Code Review

Direct implementation remains the host harness's default behavior. Use SDS when the change should be specified and approved first.

It injects:

• Platform-specific agents, commands, or workflows
• Universal writing/implementation skills
• CLI validation commands for spec structure and traceability
• A knowledge graph for architectural decisions and business rules

Supported Platforms

Platform	Scope	Injection Type
Antigravity IDE	global / project	Skills (/spec-driven)
Antigravity CLI (AGY)	global / project	Skills (/spec-driven)
Claude Code	project	Agents, commands, skills
Cline	user / project	Agents, commands, skills
Gemini CLI	global / project	Agents, commands, skills
GitHub Copilot CLI	user / project	Agents, commands, skills
GitHub Copilot for VS Code	global / project	Agents, prompts, skills
GitHub Copilot for JetBrains	project	Agents, prompts, skills
OpenCode	global / project	Agents, commands, skills
OpenAI Codex	project	Agents, command skills, skills
Qoder CLI / IDE	user / project	Agents, commands, skills
Qwen Code	user / project	Agents, commands, skills

Installation

npm install -g spec-driven-steroids

Requirements:

• Node.js >=20
• pnpm for local development

CLI Usage

The CLI provides two command names:

• sds (short alias - recommended)
• spec-driven-steroids (full name)

Inject Command

# Interactive injection (prompts for platform and scope)
sds inject

Validate Commands

# Validate spec folder structure
sds validate structure <slug>

# Validate a lightweight brief
sds validate brief <path>

# Validate EARS requirements
sds validate requirements <path>

# Validate design structure and Mermaid
sds validate design <path>

# Validate task structure and traceability
sds validate tasks <path>

# Auto-detect and validate a brief or full spec
sds validate spec <slug>

Other Commands

# Clean globally injected steroids
sds clean --global

# Show version
sds --version

# Show help
sds --help

Stewardship Commands

Manage a knowledge graph of architectural decisions, business rules, and workflow conventions extracted from spec files:

# Report available stewardship capabilities
sds stewardship capabilities

# Search for rules in the knowledge graph
sds stewardship retrieve <query> --domain architecture [--scope <project-id>] [--global]

# Persist a project-scoped rule by default
sds stewardship store architecture --content "Use hexagonal architecture"

# Persist a truly universal rule
sds stewardship store workflow --content "Run typecheck before completion" --global

# Extract decision candidates from a design.md or requirements.md
sds stewardship extract .specs/changes/my-feature/design.md

# Show rule provenance and version history
sds stewardship trace <ruleId> [--scope <project-id>] [--global]

# Retrieve context for a spec phase
sds stewardship inject design [--scope <project-id>] [--global]

# List, deprecate, archive, or move rules
sds stewardship manage list
sds stewardship manage deprecate --ruleId <ruleId> [--scope <project-id>] [--global]
sds stewardship manage move --ruleId <ruleId> --scope <project-id>

Rules are project-scoped by default and only fall back to global rules during retrieval. Use --global only for memories that are safe across unrelated repositories.

Skills Injected

The CLI injects these universal skills that work across all platforms:

Core Spec-Driven Skills

Skill	Purpose	Phase
spec-driven-brief-planner	Write, approve, implement, and review a compact brief	Brief lane
spec-driven-requirements-writer	Write EARS-format requirements	1
spec-driven-technical-designer	Create technical design with Mermaid	2
spec-driven-task-decomposer	Decompose into atomic tasks	3
spec-driven-task-implementer	Execute tasks from tasks.md	4

Universal Skills

Skill	Purpose
contextual-stewardship	Knowledge graph for architectural decisions
quality-grading	Grade code/specs across 4 dimensions
code-review-hardening	Structured code review with self-repair
universal-live-check	Real-time validation framework
long-running-work-planning	Durable checkpointed execution for long tasks
project-guidelines-writer	Generate repository guidelines
agent-work-auditor	Audit agent-generated artifacts

Agents Injected

Agent	Purpose
spec-driven	Main spec-driven workflow orchestrator

Spec Flow

Workflow lanes

Lane	Use When	Artifact	Approval
brief	Default bounded change	brief.md	One approval before implementation
full	High-risk, cross-boundary, migration, security, or public-contract change	requirements.md, design.md, tasks.md	Approval between every planning phase

SDS has no direct lane. Use the host harness without SDS when no planning artifact or approval is needed.

What gets generated

Spec-Driven planning writes artifacts to:

.specs/changes/<slug>/
brief lane:
└── brief.md

full lane:
├── requirements.md
├── design.md
└── tasks.md

The two layouts are mutually exclusive. sds validate structure and sds validate spec detect the lane automatically.

Full workflow phases

1. Requirements - EARS-syntax requirements with stable IDs
2. Design - Mermaid diagrams, architecture sections
3. Tasks - Execute non-exhaustive Discovery Targets, record evidence, then produce stable atomic tasks
4. Implementation - Task execution with verification

Quick start

1. Inject platform files into a repository:

sds inject

2. Generate project guidance:

/inject-guidelines

This creates: AGENTS.md, CONTRIBUTING.md, STYLEGUIDE.md, TESTING.md, ARCHITECTURE.md, SECURITY.md

3. Start the spec flow:

• GitHub Copilot: @spec-driven Add a rate limiter
• OpenCode: use the Spec-Driven agent
• Cline: use the Spec-Driven agent or /spec-driven
• Antigravity IDE: /spec-driven
• Antigravity CLI (AGY): /spec-driven
• Codex: select the spec-driven skill with /skills or mention $spec-driven

4. Approve the single brief or each full-lane planning phase, then move to implementation.

Long-Running Work

For complex long-running tasks, SDS injects long-running-work-planning. It keeps agents working through durable artifacts, task status updates, checkpoints, and verification.

Package Layout

packages/
├── cli/                    # Main CLI package
│   ├── src/
│   │   ├── cli/           # Injection commands
│   │   ├── core/validate/ # Validation modules
│   │   └── context-stewardship/ # Knowledge graph
│   └── templates/          # Platform templates & skills
├── test-utils/             # Test fixtures and mocks
└── landing-page/         # Documentation site

Development

pnpm install
pnpm build
pnpm test

Useful commands:

• pnpm typecheck - Type check all packages
• pnpm lint - Lint all packages
• pnpm test:coverage - Run tests with coverage
• pnpm changeset - Create a changeset
• pnpm changeset:version - Version bump

Repository Docs

• AGENTS.md - AI agent guidance
• CONTRIBUTING.md - PR process
• STYLEGUIDE.md - Code conventions
• TESTING.md - Testing strategy
• ARCHITECTURE.md - System architecture
• SECURITY.md - Security policy

License

MIT