Spets

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

Installation

npm install -g spets

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

Quick Start

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

# 워크플로우 시작
npx spets start "TODO 앱 만들어줘"

# 상태 확인
npx spets status

# 중단된 워크플로우 재개
npx spets resume

How it Works

1. spets init - .spets/ 폴더에 설정과 스텝 템플릿 생성
2. spets start - 유저 쿼리로 워크플로우 시작, Claude가 각 스텝 문서 생성
3. approve/revise/reject - 각 스텝마다 유저가 검토하고 승인
4. 반복 - 모든 스텝 완료까지 진행

Directory Structure

.spets/
├── config.yml          # 워크플로우 설정
├── steps/
│   ├── 01-plan/
│   │   ├── instruction.md   # Claude에게 주는 지시
│   │   └── template.md      # 출력 템플릿
│   └── 02-implement/
│       ├── instruction.md
│       └── template.md
├── outputs/            # 생성된 문서들
│   └── <taskId>/
│       ├── 01-plan.md
│       └── 02-implement.md
└── hooks/              # 훅 스크립트

GitHub Integration

GitHub Issue/PR과 연동하여 워크플로우를 실행합니다.

설정

# GitHub Actions + Issue 템플릿 포함해서 초기화
npx spets init --github

이 명령어는 다음을 생성합니다:

• .github/workflows/spets.yml - GitHub Actions 워크플로우
• .github/ISSUE_TEMPLATE/spets-task.yml - Issue 템플릿
• .spets/config.yml에 github.owner, github.repo 자동 설정 (git remote에서 파싱)

Issue로 워크플로우 시작

1. GitHub에서 New Issue → Spets Task 템플릿 선택
2. Task Description 입력 (예: "사용자 인증 기능 추가")
3. Branch Name 입력 (선택, 비워두면 spets/<issue-number> 자동 생성)
4. Issue 생성 → GitHub Actions 자동 트리거

CLI로 워크플로우 시작

# GitHub 모드 (기존 Issue/PR 자동 감지)
npx spets start "task" --github

# 새 Issue 생성하면서 시작
npx spets start "task" --issue

# 기존 Issue에 연결
npx spets start "task" --issue 42

# 새 PR 생성하면서 시작 (브랜치도 자동 생성)
npx spets start "task" --pr

# 기존 PR에 연결
npx spets start "task" --pr 42

코멘트 명령어

Issue/PR 코멘트로 워크플로우를 제어합니다:

• /approve - 현재 스텝 승인하고 다음 스텝 진행
• /approve --pr - 승인하고 Pull Request 생성
• /approve --issue - 승인하고 Issue 생성/업데이트
• /revise <feedback> - 피드백과 함께 현재 스텝 재생성
• /reject - 워크플로우 중단

필요 설정

Repository Secrets에 추가:

• CLAUDE_CODE_OAUTH_TOKEN - Claude 인증 토큰 (claude setup-token으로 생성)

Claude Code Plugin

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

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

Configuration

.spets/config.yml:

steps:
  - 01-plan
  - 02-implement

# GitHub 연동 (spets init --github 시 자동 설정)
github:
  owner: your-org
  repo: your-repo

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

Branch Cleanup

Automatically delete workflow branches when issues close or workflows complete:

hooks:
  onComplete: "./hooks/cleanup-branch.sh"
  onReject: "./hooks/cleanup-branch.sh"

The cleanup-branch.sh hook is automatically created by spets init.

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

Requirements

• Node.js >= 18
• Claude CLI (claude command) or CLAUDE_CODE_OAUTH_TOKEN
• GitHub CLI (gh) - GitHub 연동 사용 시

License

MIT