RapidSpec

Spec-driven development workflow with AI agents for Claude Code and Cursor IDE.

What is RapidSpec?

RapidSpec is a spec-driven workflow with:

Smart AI Integration - Prevents "imaginary code" with verification agents
Slash Commands - /rapid:proposal, /rapid:apply, etc.
Automated Reviews - Security, architecture, and code quality checks
Step-by-Step Implementation - Supports rapid iteration with "wait, change this" workflow

Installation

Install globally:

npm install -g rapidspec

Or use in your project:

npm install --save-dev rapidspec
npx rapid init

This will:

Create rapidspec/ directory structure
Copy 18 agents to .claude/agents/
Copy 7 commands to .claude/commands/
Copy 7 templates to .rapidspec/templates/
Generate CLAUDE.md and rapidspec/AGENTS.md
Configure .cursor/mcp.json for Cursor IDE integration

This enables /rapid:* slash commands in Claude Code and Cursor IDE.

Quick Start

Initialize RapidSpec in your project:

rapid init

This automatically:

Creates rapidspec/ directory structure
Generates CLAUDE.md and rapidspec/AGENTS.md
Copies all agents to .claude/agents/
Copies all commands to .claude/commands/
Copies all templates to .rapidspec/templates/

What is AGENTS.md?

Single source of truth for AI assistants
Documents RapidSpec workflow, slash commands, and agents
Follows agents.md convention for tool-agnostic discovery
Compatible with Claude Code, Amp, Jules, Gemini CLI, and other AI tools

IDE Support

Claude Code

Native support via .claude/agents/ and .claude/commands/:

Agents: @agent-code-verifier, @agent-security-auditor, etc.
Slash Commands: /rapid:proposal, /rapid:apply, /rapid:review, etc.

Cursor IDE

Agents available via sub-agents-mcp:

Setup: rapid init automatically configures .cursor/mcp.json
Usage: Reload Cursor, then ask naturally (e.g., "Use the code-verifier agent to check this file")
Slash Commands: /rapid:* commands work in Cursor 2.0+
Note: Unlike Claude Code, Cursor doesn't support @agent-* mentions—use natural language requests instead

Manual Configuration (if needed):

{
  "mcpServers": {
    "sub-agents": {
      "command": "npx",
      "args": ["-y", "sub-agents-mcp"],
      "env": {
        "AGENTS_DIR": "/absolute/path/to/.claude/agents",
        "AGENT_TYPE": "cursor"
      }
    }
  }
}

1. Create your first spec

Using slash commands in Claude Code:

/rapid:proposal add-authentication

AI will:

Investigate codebase (prevent "imaginary code")
- Read actual files and find existing patterns
- Analyze git history
Research best practices
- Web search for latest patterns
- Check framework documentation
Present 2-3 implementation options with trade-offs

2. Implement the spec

/rapid:apply add-authentication

AI implements step-by-step with checkpoints:

You can say "wait!" at any time
Each step is testable
No automatic commit (use /rapid:commit when ready)

3. Review and commit

/rapid:review add-authentication  # Optional: Run agent reviews
/rapid:commit add-authentication  # Update tasks.md and commit

4. Archive when done

/rapid:archive add-authentication

Moves to archive/YYYYMMDDhhmmss-[name]/ and updates specs.

Slash Commands

All commands follow /rapid:* pattern:

Core Workflow

/rapid:proposal [name] - Create new spec proposal with research and design review
/rapid:apply [name] - Implement spec step-by-step with architecture validation and checkpoints
/rapid:review [name] - Run comprehensive code quality reviews
/rapid:triage [name] - Review findings one by one and add selected items to tasks
/rapid:resolve-parallel [name] - Resolve multiple tasks in parallel with dependency analysis
/rapid:commit [name] - Review changes, update tasks, and commit
/rapid:archive [name] - Archive completed spec and update canonical specs

Linear Integration

/rapid:from-linear <issue-number> - Create proposal from existing Linear issue

CLI Commands

# Initialize (creates rapidspec/ directory structure)
rapid init [path]

# Validate proposal structure
rapid validate [name]          # Validate specific proposal
rapid validate                 # Validate all active proposals
rapid validate --strict        # Fail on warnings

# Other commands coming soon
rapid proposal <name>          # Create new proposal
rapid list                     # List active proposals
rapid show <name>              # Show proposal details

CLI Validate

The rapid validate CLI command performs structure validation:

✓ Checks required files exist (proposal.md, tasks.md)
✓ Validates proposal format (sections: Summary, Motivation, Solution, etc.)
✓ Checks tasks format (checkbox syntax)
✓ Fast and lightweight

For comprehensive AI-powered reviews, use the slash commands in Claude Code:

Design review (before coding): /rapid:proposal includes design review with architecture agents
Code quality review (after coding): /rapid:review runs code verification and security audits

Agents

RapidSpec includes specialized agents for different workflow stages:

Investigation Agents (Proposal - Research Phase)

Run in parallel at the start of /rapid:proposal:

@agent-git-history-analyzer - Code evolution and decision analysis
@agent-pattern-recognition-specialist - Find existing patterns in codebase
@agent-best-practices-researcher - External standards research via web search
@agent-framework-docs-researcher - Library documentation and source code

Design Review Agents (Proposal - After Option Selection)

Run after user selects an option in /rapid:proposal:

@agent-database-architect - Schema design, migration safety, RLS policies, index strategy
@agent-nextjs-architecture-expert - Server/Client Component architecture, routing, data fetching

Also run at the start of /rapid:apply for implementation guidance.

Code Review Agents (Review - After Implementation)

Run during /rapid:review to verify implementation quality:

Core Agents (always run):

@agent-code-verifier - Verifies implementation against actual files (prevents "imaginary code")
@agent-security-auditor - Checks RLS, auth, OWASP compliance

Conditional Agents (based on changes):

@agent-code-reviewer - Type safety, patterns, performance, error handling
@agent-data-integrity-guardian - Data consistency, constraint validation
@agent-test-automator - E2E test coverage and generation
@agent-performance-oracle - Performance analysis and optimization

Workflow Agents

@agent-task-updater - Reviews implementation, updates tasks.md, prepares commits (used in /rapid:commit)
@agent-pr-comment-resolver - PR comment resolution

Linear Integration

Setup

Get your Linear API key from linear.app/settings/api
Add to your project:

# .env.local
LINEAR_API_KEY=lin_api_xxxxx
LINEAR_TEAM_ID=your-team-id

Create Proposal from Linear Issue

When you already have a Linear issue and want to implement it using RapidSpec:

/rapid:from-linear 123

AI will:

Fetch Linear issue #123 (title, description, comments)
Parse requirements and acceptance criteria
Delegate to /rapid:proposal for complete workflow
Generate all proposal files with full research and verification

This is useful for PM-driven workflows where issues are created first, then implemented.

Complete Workflow

1. Create Proposal (`/rapid:proposal`)

You: "/rapid:proposal add-smart-link-duplicate-prevention"

AI automatically:
1. 📖 Investigation Phase (runs in parallel)
   - Reads actual codebase (no "imaginary code")
   - @agent-git-history-analyzer: Analyzes git history
   - @agent-pattern-recognition-specialist: Finds existing patterns
   - Understands why current behavior exists

2. 🔬 Research Phase (runs in parallel)
   - @agent-best-practices-researcher: Searches best practices (web search)
   - @agent-framework-docs-researcher: Checks framework documentation
   - Analyzes reference repositories

3. 💡 Options Phase
   - Presents 2-3 implementation approaches
   - Shows trade-offs for each option
   - Recommends best approach (⭐)

You: "1" (select option)

AI runs Design Review:
✓ @agent-database-architect: Validates schema, migration safety
✓ @agent-nextjs-architecture-expert: Reviews component structure
✓ Incorporates design feedback into proposal

AI creates:
✓ rapidspec/changes/add-smart-link-duplicate-prevention/
  - proposal.md (full spec with chosen approach + design review)
  - tasks.md (step-by-step implementation plan)
  - investigation.md (findings from code analysis)
  - research.md (best practices and references)

2. Apply Implementation (`/rapid:apply`)

You: "/rapid:apply add-smart-link-duplicate-prevention"

AI runs Architecture Validation:
✓ @agent-database-architect: Provides implementation guidance
✓ @agent-nextjs-architecture-expert: Confirms component approach
✓ Ready to implement with validated architecture

AI implements step-by-step:

┌─────────────────────────────────────┐
│ Task 1.1: Database Migration (5min) │
└─────────────────────────────────────┘
[Shows implementation]

You: "ㄱㄱ" (go) or "wait!" (pause)

┌─────────────────────────────────────┐
│ Task 1.2: API Validation (8min)     │
└─────────────────────────────────────┘
[Shows implementation]

You: "wait! Use 400 status, not 409"

AI: [Adjusts implementation]
"Fixed - using 400 Bad Request. Continue?"

You: "ㄱㄱ"

[... continues through all tasks ...]

After completion:
✅ All tasks completed!

Summary:
- 8 files changed
- 3 migrations created
- 2 tests added

Next steps:
- Run `/rapid:review` for comprehensive review (optional)
- Or `/rapid:commit` to commit directly

3. Review Implementation (`/rapid:review`) - Optional

You: "/rapid:review add-smart-link-duplicate-prevention"

AI runs core + conditional agent reviews:

Core Agents (always run):
✅ Code Verification (@agent-code-verifier)
  ✓ All file references verified
  ✓ No imaginary code
  ✓ Diffs shown for all changes

✅ Security Audit (@agent-security-auditor)
  ✓ RLS enabled on smart_links table
  ✓ Policies use has_role() function
  ✓ Input validation present

Conditional Agents (based on changes):
⚠️  Code Quality Review (@agent-code-reviewer)
  ✓ Type safety maintained
  ⚠️  Function complexity: Consider extracting helper

✅ Data Integrity (@agent-data-integrity-guardian)
  ✓ Migration non-blocking
  ✓ Indexes on foreign keys
  ✓ Constraint validation present

⚠️  Test Coverage (@agent-test-automator)
  ✓ E2E test present
  ✓ Unit tests present
  ⚠️  Missing edge case: concurrent creation

Overall: PASSED (3 warnings - recommended fixes)

Next: /rapid:triage to review findings individually

4. Triage Findings (`/rapid:triage`) - Optional

You: "/rapid:triage add-smart-link-duplicate-prevention"

AI presents findings one by one:

┌─────────────────────────────────────────────────────────┐
│ Triage Progress: 1/3 findings | Est. 3 min remaining    │
└─────────────────────────────────────────────────────────┘

---
Finding #1: Extract Complex Validation Logic

Severity: 🟡 P2 (IMPORTANT)
Category: Code Quality

Description:
The validateSmartLink function has cognitive complexity of 15 (max 10).
Multiple nested conditions make it hard to understand.

Location: src/lib/validation.ts:42

Proposed Solution:
Extract validation rules into separate functions:
- validateUrl(url)
- validateRelease(releaseId)
- checkDuplicate(link)

Estimated Effort: Medium (2 hours)

---
Add to tasks?
1. yes - add to tasks.md
2. next - skip this finding
3. custom - modify before adding

You: "yes"

AI:
✅ Added to tasks.md: Section 3.1 - Extract validation logic

┌─────────────────────────────────────────────────────────┐
│ Triage Progress: 2/3 findings | Est. 2 min remaining    │
│ (1 added, 0 skipped)                                     │
└─────────────────────────────────────────────────────────┘

---
Finding #2: Add missing edge case test...

You: "yes"

[... continues for all findings ...]

╔═══════════════════════════════════════════════════════╗
║         Triage Complete - 3 Findings Reviewed         ║
╚═══════════════════════════════════════════════════════╝

Added to tasks.md (2 tasks):
  🟡 Task 3.1: Extract validation logic
  🔵 Task 3.2: Add concurrent creation test

Skipped (1 finding):
  Finding #3: Variable naming (cosmetic)

Next: /rapid:resolve-parallel or /rapid:apply to fix tasks

5. Resolve Tasks in Parallel (`/rapid:resolve-parallel`) - Optional

You: "/rapid:resolve-parallel add-smart-link-duplicate-prevention"

AI analyzes task dependencies:

Found 2 uncompleted tasks

Analyzing dependencies...
✓ Task 3.1: Extract validation (independent)
✓ Task 3.2: Add test (independent)

Execution Plan:

Wave 1 (2 tasks in parallel):
  - Task 3.1: Extract validation logic (2 hours)
  - Task 3.2: Add concurrent test (30 min)

Total: 2 hours (vs 2.5 hours sequential)
Efficiency Gain: 20% faster

Continue? (yes)

You: "yes"

AI:
Launching Wave 1 (2 tasks in parallel)...

1. Task pr-comment-resolver(task_3_1)
2. Task pr-comment-resolver(task_3_2)

[Both agents work simultaneously]

✅ Wave 1 Complete (2/2 tasks done)

╔═══════════════════════════════════════════════════════╗
║         All Tasks Complete - 2/2                      ║
╚═══════════════════════════════════════════════════════╝

Files changed: 3 files
Tests: All passing

Updated: rapidspec/changes/add-smart-link-duplicate-prevention/tasks.md

Next: /rapid:commit to commit changes

6. Commit Changes (`/rapid:commit`)

You: "/rapid:commit add-smart-link-duplicate-prevention"

AI (@agent-task-updater):
Reviewing changes...
✓ Git status checked
✓ Git diff analyzed
✓ Matched changes to tasks

Files changed (8):
  Modified: 3 files
  Added: 5 files
  Total: +245 -18 lines

Tasks completed (5/6):
✓ 1.1 Database Migration
✓ 1.2 API Validation
✓ 1.3 UI Toast
✓ 2.1 E2E Test
✓ 2.2 Unit Test
⏳ 3.1 Documentation (not done)

Discovered work:
📝 Added index on release_id (performance)
📝 Extracted validation logic (code quality)

Updating tasks.md...
✓ Marked 5 tasks [x]
✓ Added discovered tasks

Commit message:
────────────────────────────────────────
feat(smart-links): prevent duplicate links per release

Completed Tasks (5/6):
- Database Migration: unique constraint
- API Validation: 400 error handling
- UI Toast: duplicate warning
- E2E Test: duplicate.spec.ts
- Unit Test: validation.test.ts

Additional Improvements:
- Added index on release_id for performance
- Extracted validation logic to helper

🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
────────────────────────────────────────

Ready to commit? (ㄱㄱ)

You: "ㄱㄱ"

AI:
✓ Committed: abc1234

7. Archive Completion (`/rapid:archive`)

You: "/rapid:archive add-smart-link-duplicate-prevention"

AI:
1. Verifies completion
   ✓ All tasks marked [x]
   ✓ Tests passing
   ✓ Committed to git

2. Archives the spec
   ✓ Moved to: archive/20251111123045-add-smart-link-duplicate-prevention/

3. Updates canonical specs
   ✓ Updated: specs/smart-links/spec.md
   ✓ Added prevention logic documentation

Done! 🎉

Workflow Diagram

┌─────────────────────────────────────────────────────────────┐
│                     /rapid:proposal                          │
├─────────────────────────────────────────────────────────────┤
│ 1. Investigation (auto - runs in parallel)                  │
│    - Read actual codebase (prevent "imaginary code")        │
│    - @agent-git-history-analyzer: Understand history        │
│    - @agent-pattern-recognition-specialist: Find patterns   │
│                                                              │
│ 2. Research (auto - runs in parallel)                       │
│    - @agent-best-practices-researcher: Web + docs           │
│    - @agent-framework-docs-researcher: Library docs         │
│                                                              │
│ 3. Options (interactive)                                     │
│    - Present 2-3 approaches with trade-offs                 │
│    - User selects (1, 2, 3)                                 │
│                                                              │
│ 4. Design Review (auto - after selection)                   │
│    - @agent-database-architect: Schema, migration safety    │
│    - @agent-nextjs-architecture-expert: Component structure │
│    - Incorporate design feedback into proposal              │
│                                                              │
│ → Files created:                                            │
│   - proposal.md, tasks.md, investigation.md, research.md    │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                     /rapid:apply                            │
├─────────────────────────────────────────────────────────────┤
│ 1. Read spec files                                           │
│    - proposal.md, tasks.md, investigation.md                │
│                                                              │
│ 2. Architecture Validation (auto - before implementation)   │
│    - @agent-database-architect: Implementation guidance     │
│    - @agent-nextjs-architecture-expert: Concrete approach   │
│                                                              │
│ 3. Implementation (step-by-step with checkpoints)           │
│    For each task:                                            │
│      1. Show what will be done                              │
│      2. Wait for "ㄱㄱ" (go) or "wait!" (pause)              │
│      3. Implement and show diff                             │
│      4. Support "잠깐" (wait) to change direction            │
│                                                              │
│ After all tasks complete:                                    │
│   → Shows summary (files changed, tests added)              │
│   → Suggests /rapid:review (optional) or /rapid:commit      │
│                                                              │
│ → Implementation complete (not committed)                   │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                    /rapid:review (optional)                 │
├─────────────────────────────────────────────────────────────┤
│ Core reviews (always run in parallel):                      │
│   - @agent-code-verifier: Verify implementation             │
│   - @agent-security-auditor: RLS, auth, OWASP              │
│                                                              │
│ Conditional reviews (based on changes):                     │
│   - @agent-code-reviewer: Quality, types, patterns         │
│   - @agent-data-integrity-guardian: Data consistency       │
│   - @agent-test-automator: Coverage analysis               │
│   - @agent-performance-oracle: Performance optimization    │
│                                                              │
│ Note: Architecture agents run in /rapid:proposal            │
│       and /rapid:apply (not here)                           │
│                                                              │
│ → Review report (Critical/Warning/Info)                     │
│ → Suggests /rapid:triage to review findings                 │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                  /rapid:triage (optional)                   │
├─────────────────────────────────────────────────────────────┤
│ Review findings one by one:                                  │
│   1. Present each finding with severity and impact          │
│   2. User decides: yes/next/custom                          │
│   3. Accepted findings → Add to tasks.md                    │
│   4. Skipped findings → Document for later                  │
│                                                              │
│ → Findings converted to actionable tasks                    │
│ → Suggests /rapid:resolve-parallel or /rapid:apply          │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│              /rapid:resolve-parallel (optional)             │
├─────────────────────────────────────────────────────────────┤
│ Resolve multiple tasks in parallel:                         │
│   1. Analyze task dependencies                              │
│   2. Generate execution plan (Mermaid diagram)              │
│   3. Execute in waves (parallel within wave)                │
│   4. Update tasks.md after each wave                        │
│                                                              │
│ → Tasks completed 30-50% faster than sequential             │
│ → Suggests /rapid:commit after completion                   │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                     /rapid:commit                           │
├─────────────────────────────────────────────────────────────┤
│ Commit preparation (@agent-task-updater):                   │
│   1. Review git status and git diff                         │
│   2. Match changes to tasks.md                              │
│   3. Mark completed tasks [x]                               │
│   4. Capture discovered work                                │
│   5. Generate commit message from tasks                     │
│   6. Create commit with conventional format                 │
│                                                              │
│ → Committed to git                                          │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                     /rapid:archive                          │
├─────────────────────────────────────────────────────────────┤
│ 1. Verify completion (all tasks done, tests pass)           │
│ 2. Move to archive/YYYYMMDDhhmmss-[name]/                   │
│    (Timestamp format: 20251111123045)                       │
│ 3. Update canonical specs with changes                      │
│                                                              │
│ → Spec archived, specs updated                              │
└─────────────────────────────────────────────────────────────┘

Best Practices

1. Always Verify Before Coding

RapidSpec prevents "imaginary code" by:

Reading actual files before suggesting changes
Checking git history for context
Generating diffs before implementation

2. Use Step-by-Step Implementation

Break large features into small, testable steps:

Each step is a checkpoint
Say "wait!" to change direction
No need for throwaway prototypes

3. Let AI Do Research

AI automatically:

Searches best practices (web search)
Analyzes reference repos
Checks library documentation

4. Support "ㄱㄱ / 잠깐" Workflow

"ㄱㄱ" (go): Continue to next step
"잠깐" (wait): Pause and adjust
Enables rapid iteration without restarts

Philosophy

RapidSpec is based on three principles:

Spec is Truth - Code follows spec, not the other way around
Verify, Don't Imagine - Always check actual code before suggesting changes
Fast Iteration - Support rapid "wait, change this" workflow

Inspired by OpenSpec and Every's Compounding Engineering.

Contributing

Contributions welcome! See CONTRIBUTING.md.

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
agents		agents
cli		cli
commands		commands
templates		templates
test-results		test-results
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

9j/RapidSpec

Folders and files

Latest commit

History

Repository files navigation

RapidSpec

What is RapidSpec?

Installation

Quick Start

IDE Support

Claude Code

Cursor IDE

1. Create your first spec

2. Implement the spec

3. Review and commit

4. Archive when done

Slash Commands

Core Workflow

Linear Integration

CLI Commands

CLI Validate

Agents

Investigation Agents (Proposal - Research Phase)

Design Review Agents (Proposal - After Option Selection)

Code Review Agents (Review - After Implementation)

Workflow Agents

Linear Integration

Setup

Create Proposal from Linear Issue

Complete Workflow

1. Create Proposal (/rapid:proposal)

2. Apply Implementation (/rapid:apply)

3. Review Implementation (/rapid:review) - Optional

4. Triage Findings (/rapid:triage) - Optional

5. Resolve Tasks in Parallel (/rapid:resolve-parallel) - Optional

6. Commit Changes (/rapid:commit)

7. Archive Completion (/rapid:archive)

Workflow Diagram

Best Practices

1. Always Verify Before Coding

2. Use Step-by-Step Implementation

3. Let AI Do Research

4. Support "ㄱㄱ / 잠깐" Workflow

Philosophy

Contributing

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

1. Create Proposal (`/rapid:proposal`)

2. Apply Implementation (`/rapid:apply`)

3. Review Implementation (`/rapid:review`) - Optional

4. Triage Findings (`/rapid:triage`) - Optional

5. Resolve Tasks in Parallel (`/rapid:resolve-parallel`) - Optional

6. Commit Changes (`/rapid:commit`)

7. Archive Completion (`/rapid:archive`)

Packages