Skip to content
BranchesTags

Repository files navigation

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:

  1. Investigate codebase (prevent "imaginary code")
    • Read actual files and find existing patterns
    • Analyze git history
  2. Research best practices
    • Web search for latest patterns
    • Check framework documentation
  3. 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

  1. Get your Linear API key from linear.app/settings/api

  2. 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:

  1. Fetch Linear issue #123 (title, description, comments)
  2. Parse requirements and acceptance criteria
  3. Delegate to /rapid:proposal for complete workflow
  4. 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:

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

Inspired by OpenSpec and Every's Compounding Engineering.

Contributing

Contributions welcome! See CONTRIBUTING.md.

License

MIT © BAK Chanhee

About

No description, website, or topics provided.

Resources

Readme
MIT license
Activity

Stars

5 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases

Packages

Contributors

Languages