spec-workflow

Spec-Driven Development Workflow Skill

Spec-Driven Development (SDD)downstream process (implementation) This skill is responsible for. Development is carried out based on the 3-tier structure of EPIC → Story → Subtask.

Note: Specification development (upstream process) is done with the /spec Skill. Collaboration flow: /spec(specification development) → spec-workflow(implementation)

Trigger Conditions

Automatically triggered by the following keywords/contexts:

• Implement, create, develop
• New feature implementation
• Subtask start, Story start
• References to EPIC, Story, Subtask

Basic Principles

1. Specification First (Mandatory)

Always confirm the following before implementation:

1. specs/{epic-id}/{story-id}/{subtask-id}.md Load
2. Confirm user stories
3. Understand AC
4. Confirm with the user, "Shall we proceed with this AC?"

2. Strict TDD (Mandatory)

🔴 Red   : ACからテストケースを導出 → 失敗するテストを書く
🟢 Green : テストを通す最小限の実装
🔵 Refactor : テストを保ちながらコード改善

EARS Notation Support

When AC is written in EARS notation, streamline test case derivation:

// EARS記法のAC例:
// WHEN ユーザーがログインを試行する際
// GIVEN 有効なメールとパスワードを入力した場合
// THEN システムはJWTトークンを発行する
// AND ダッシュボードにリダイレクトする

// テストケースへの変換:
describe('ログイン', () => {
  it('有効な認証情報でJWTトークンが発行される', () => {
    // GIVEN: 前提条件をセットアップ
    const credentials = { email: 'valid@example.com', password: 'validPass' };

    // WHEN: トリガーを実行
    const result = login(credentials);

    // THEN: 期待結果を検証
    expect(result.token).toBeDefined();
  });

  it('成功時にダッシュボードへリダイレクトする', () => {
    // AND条件のテスト
  });
});

3. Scope Management (Mandatory)

• Implement only features described in the AC
• Do not implement out-of-scope items; only "propose" them
• Confirm unclear points with the user

Workflow Details

Phase 1: At Subtask Start (Mandatory Flow)

// 1. Subtaskファイルを読み込む
const subtaskFile = await read(`specs/{epic-id}/{story-id}/{subtask-id}.md`)

// 2. ACを確認
const acceptanceCriteria = parseAC(subtaskFile)

// 3. ユーザーストーリーを確認
const userStory = parseUserStory(subtaskFile)

// 4. ユーザーに確認
await ask(`以下のACで実装を進めます。よろしいですか？
${acceptanceCriteria.map(ac => `- ${ac}`).join('\n')}`)

// 5. テストケースを導出
const testCases = deriveTestCases(acceptanceCriteria)

Phase 2: TDD Implementation

// 🔴 Red: テストを先に書く
describe(subtaskTitle, () => {
  acceptanceCriteria.forEach(ac => {
    it(ac, async () => {
      // ACからテストケースを導出
    })
  })
})

// テストが失敗することを確認
await runTests() // Expected: FAIL

// 🟢 Green: 最小限の実装
// ACを満たす最小限のコードを実装
await runTests() // Expected: PASS

// 🔵 Refactor: コード改善
// テストを保ちながら改善
await runTests() // Expected: PASS

Phase 3: At Completion (Mandatory Flow)

// 1. AC全項目をチェック
acceptanceCriteria.forEach(ac => {
  console.log(`✅ ${ac}`)
})

// 2. テストが全て通過していることを確認
await runTests() // All tests pass

// 3. ステータス更新
await updateSubtaskFile({
  status: 'completed',
  completed_at: new Date().toISOString()
})

// 4. 親Storyの確認
if (allSubtasksCompleted(storyId)) {
  await updateStoryFile({ status: 'completed' })
}

// 5. 次のSubtaskを提示
console.log(`次のSubtask: ${getNextSubtask()}`)

Scope Judgement

In Scope (Implementation OK)

• Features explicitly stated in the AC
• Technical implementation required to achieve the AC
• Features that realize the value of the user story

Out of Scope (Proposal Only)

• "While we're at it" improvements not stated in the AC
• Features that "might" be needed in the future
• Features that should be handled in another Subtask/Story

Out-of-Scope Handling Flow

if (isOutOfScope(request)) {
  const response = `
  ご依頼いただいた「${request}」は、現在のSubtaskのACに含まれていません。

  現在のAC:
  ${currentAC.map(ac => `- ${ac}`).join('\n')}

  対応案:
  1. 現在のSubtaskでは実装しない
  2. 別のSubtaskとして提案

  どちらを選択しますか？`

  await ask(response)
}

Test File Placement

specs/{epic-id}/{story-id}/{subtask-id}.md  # Subtask定義
{feature}/
├── service.ts         # 実装ファイル
└── __dev__/
    └── service.test.ts  # テストファイル（Colocation）

Prohibited Actions

• ❌ Starting implementation without AC
• ❌ Implementation without tests (TDD violation)
• ❌ Out-of-scope "while we're at it" implementation
• ❌ Simultaneous implementation of multiple features (1 Subtask = 1 feature)
• ❌ Specification changes without user confirmation
• ❌ Status updates without completion confirmation

Error Handling

When the AC is ambiguous

if (isACAmbiguous(ac)) {
  await ask(`
  以下のACが曖昧なため、実装を開始できません。

  曖昧なAC: ${ac}

  以下のように明確化することを提案します:
  「${suggestedAC}」

  この明確化で進めてよいですか？
  `)
}

When tests do not pass

if (testsFailed) {
  // 実装を修正（Green達成まで）
  // テスト自体の問題なら修正
  // ACの解釈に問題があればユーザーに確認
}

Branch/PR Collaboration

This Skill automatically calls /branch と /pr .

Collaboration Flow

spec-workflow 開始
    │
    ├─ Subtaskファイル読み込み
    │
    ├─ AC確認・ユーザー承認
    │       │
    │       └─ 承認後 → /branch 発火
    │          ブランチ: impl/{subtask-id}-{description}
    │
    ├─ TDD実装
    │   - 🔴 Red: テスト作成
    │   - 🟢 Green: 最小実装
    │   - 🔵 Refactor: 改善
    │
    ├─ AC全項目チェック
    │
    └─ 完了時 → /pr 発火
        PR: 実装レビュー用

/branch Call

Automatically fired after AC confirmation and approval:

Claude: 以下のACで実装を進めます。よろしいですか？
        - AC1: ...
        - AC2: ...

ユーザー: OK

Claude: 実装用ブランチを作成します。

        ブランチ名: impl/001-01-01-user-auth
        ベース: main

        作成してよいですか？

/pr Call

Automatically fired after all AC items have been checked:

Claude: 全てのACを満たしました。

        ✅ AC1: 有効な認証情報でログイン成功
        ✅ AC2: 無効な認証情報でエラー表示
        ✅ AC3: MFAコード検証

        PRを作成しますか？
        タイトル: impl: ユーザー認証機能の実装

        ## Summary
        - 001-01-01 を実装
        - ログイン/ログアウト機能

        ## AC確認
        - [x] AC1
        - [x] AC2
        - [x] AC3

---

Reference Documents

• SPEC_FORMAT.md - Specification Format Definition
• WORKFLOW.md - Workflow Details

---

Related Skills

• /branch: Branch creation (automatically called from this Skill)
• /pr: PR creation (automatically called from this Skill)
• /spec: Specification development (upstream process of this Skill)

Overall Coordination Flow

/spec（仕様策定）
    ├─ /branch 発火（spec/*）
    ├─ ファイル生成
    └─ /pr 発火（仕様レビュー）
        ↓ マージ後
spec-workflow（実装）← 本Skill
    ├─ /branch 発火（impl/*）
    ├─ TDD実装
    └─ /pr 発火（実装レビュー）

Usage Examples

Example 1: New Subtask Implementation

ユーザー: 「001-01-01の設定要件Subtaskを実装して」

[自動] spec-workflow Skill発動
[自動] specs/001-environment-setup/001-01-common-config/001-01-01-config-requirements.md を読み込み

Claude: 「以下のACで実装を進めます。よろしいですか？
- 設定ファイル配置方針が明確に決定されていること
- ESLint、Prettier、TypeScriptの設定内容が仕様として確定していること
- package.jsonスクリプトの統一方針が決定されていること」

ユーザー: 「OK」

Claude: 「🔴 Red: テストケースを導出します...」
（以下、TDDサイクル）

Example 2: Out-of-Scope Request

ユーザー: 「ついでにCI/CDも設定して」

Claude: 「ご依頼いただいた「CI/CD設定」は、現在のSubtaskのACに含まれていません。

現在のAC:
- 設定ファイル配置方針が明確に決定されていること
- ESLint、Prettier、TypeScriptの設定内容が仕様として確定していること

対応案:
1. 現在のSubtaskでは実装しない（推奨）
2. 新規Subtaskとして定義する

どちらを選択しますか？」