Spets

Spec Driven Development Execution Framework - 유저가 정의한 스텝대로 SDD를 실행하는 CLI

Installation

npm install -g spets

# 또는 npx로 바로 사용
npx spets init

Quick Start

# 프로젝트에서 초기화
npx spets init

# 인터랙티브 셋업 (AI 에이전트 선택 포함)
npx spets init -i

# 워크플로우 시작 (Claude Code 안에서)
/spets "TODO 앱 만들어줘"

# 상태 확인
npx spets status

# 대시보드
npx spets dashboard

How it Works

1. spets init - .spets/ 폴더에 설정과 스텝 템플릿 생성
2. spets orchestrate init "task" - 유저 쿼리로 워크플로우 시작
3. 각 스텝은 5단계 실행: Explore → Clarify → Execute → Verify → Review
4. 모든 스텝 완료까지 진행

Directory Structure

.spets/
├── config.yml          # 워크플로우 설정
├── steps/
│   ├── 01-plan/
│   │   └── template.md      # 출력 템플릿
│   └── 02-implement/
│       └── template.md
├── outputs/            # 생성된 문서들
│   └── <taskId>/
│       ├── 01-plan.md
│       └── 02-implement.md
├── hooks/              # 훅 스크립트
└── knowledge/          # 학습된 지식 파일

AI CLI Plugins

Spets provides skill/command definitions for use within AI CLI sessions:

Claude Code

# Claude Code 스킬 설치
npx spets plugin install claude

# Claude Code에서 사용
/spets "task description"

Gemini CLI

# Gemini CLI 스킬 설치
npx spets plugin install gemini

# Gemini CLI에서 사용
@spets "task description"

The Gemini CLI command is installed at .gemini/commands/spets.md (project-level). Use it within a Gemini CLI session.

Codex CLI

# Codex 스킬 설치
npx spets plugin install codex

# Codex에서 사용
/spets "task description"

Configuration

.spets/config.yml:

steps:
  - 01-plan
  - 02-implement

# AI 에이전트 선택
agent: claude  # claude, codex, gemini

# 훅 (선택)
hooks:
  preStep: "./hooks/pre-step.sh"
  postStep: "./hooks/post-step.sh"
  onApprove: "./hooks/on-approve.sh"
  onComplete: "./hooks/on-complete.sh"

Environment Variables Available in Hooks:

• SPETS_TASK_ID - Current task ID
• SPETS_STEP_NAME - Current step name
• SPETS_STEP_INDEX - Current step index
• SPETS_OUTPUT_PATH - Output directory path
• SPETS_BRANCH - Current git branch name
• SPETS_CWD - Working directory

Supported AI Agents

| Agent | Config Value | |-------|-------------| | Claude (default) | claude | | Gemini | gemini | | Codex | codex |

# Set default agent in config
agent: gemini  # or claude, codex

Requirements

• Node.js >= 18
• One of the following AI CLIs:
  • Claude Code (claude command) - default
  • Gemini CLI (gemini command)
  • Codex CLI (codex command)

Troubleshooting: npm EPERM with npx

If npx spets ... fails with permission errors like ~/.npm/_logs, run with a project-local npm cache:

NPM_CONFIG_CACHE=.spets/.npm-cache npm_config_cache=.spets/.npm-cache npx --yes spets init
NPM_CONFIG_CACHE=.spets/.npm-cache npm_config_cache=.spets/.npm-cache npx --yes spets plugin install codex

License

MIT