Spets

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

Installation

``bash
npm install -g spets

또는 npx로 바로 사용


npx spets init
`

Quick Start

`bash


프로젝트에서 초기화

npx spets init

워크플로우 시작

npx spets start "TODO 앱 만들어줘"

다른 AI 에이전트 사용

npx spets start "task" --agent gemini # Google Gemini CLI
npx spets start "task" --agent codex # OpenAI Codex CLI

상태 확인

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/ # 생성된 문서들
│ └── /
│ ├── 01-plan.md
│ └── 02-implement.md
└── hooks/ # 훅 스크립트
`

GitHub Integration

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

$3

`bash


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에서 파싱)

$3

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

$3

`bash


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
`

$3

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

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

$3

Repository Secrets에 추가:
- CLAUDE_CODE_OAUTH_TOKEN - Claude 인증 토큰 (claude setup-token으로 생성)

AI CLI Plugins

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

$3

`bash


Claude Code 스킬 설치

npx spets plugin install claude

Claude Code에서 사용

/spets start "task description"
`

$3

`bash


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.

$3

`bash


Codex 스킬 설치

npx spets plugin install codex

Codex에서 사용

/spets start "task description"
`

Configuration

.spets/config.yml:

`yaml
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"
`

$3

Automatically delete workflow branches when issues close or workflows complete:

`yaml
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

Supported AI Agents

Spets supports multiple AI agents via the --agent flag:

| Agent | Command | Auto-approve Flag |
|-------|---------|-------------------|
| Claude (default) | claude | --permission-mode bypassPermissions |
| Gemini | gemini | --yolo |
| Codex | codex | exec --full-auto |

`bash


Set default agent in config

.spets/config.yml

agent: gemini # or claude, codex
`

Requirements

- Node.js >= 18
- One of the following AI CLIs:
- Claude CLI (claude command) - default
- Gemini CLI (gemini command) - --agent gemini
- Codex CLI (codex command) - --agent codex
- GitHub CLI (gh`) - GitHub 연동 사용 시

License

MIT