spec-runner 1.1.7 → 1.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/README.md +51 -80
  2. package/bin/spec-runner-installer.js +401 -0
  3. package/install.sh +1 -1
  4. package/package.json +7 -6
  5. package/spec-runner/templates/.claude/agents/code-reviewer.md +69 -0
  6. package/spec-runner/templates/.claude/agents/design-reviewer.md +65 -0
  7. package/spec-runner/templates/.claude/agents/test-runner.md +34 -0
  8. package/spec-runner/templates/.claude/rules/coding.md +106 -0
  9. package/spec-runner/templates/.claude/rules/design-docs.md +63 -0
  10. package/spec-runner/templates/.claude/skills/architecture-definition/SKILL.md +60 -0
  11. package/spec-runner/templates/.claude/skills/architecture-skill-development/SKILL.md +126 -0
  12. package/spec-runner/templates/.claude/skills/commit/SKILL.md +83 -0
  13. package/spec-runner/templates/.claude/skills/design-change/SKILL.md +94 -0
  14. package/spec-runner/templates/.claude/skills/design-change/references//345/275/261/351/237/277/347/257/204/345/233/262/343/203/201/343/202/247/343/203/203/343/202/257/343/203/252/343/202/271/343/203/210.md +66 -0
  15. package/spec-runner/templates/.claude/skills/design-change/templates/90_ADR/ADR/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +81 -0
  16. package/spec-runner/templates/.claude/skills/existing-project-to-docs/SKILL.md +57 -0
  17. package/spec-runner/templates/.claude/skills/harness-engineering/SKILL.md +100 -0
  18. package/spec-runner/templates/.claude/skills/plugin-development/SKILL.md +173 -0
  19. package/spec-runner/templates/.claude/skills/plugin-development/templates/01_/350/246/201/344/273/266/345/256/232/347/276/251//346/246/202/350/246/201/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +88 -0
  20. package/spec-runner/templates/.claude/skills/plugin-development/templates/02_/346/246/202/350/246/201/350/250/255/350/250/210/90_ADR/ADR/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +81 -0
  21. package/spec-runner/templates/.claude/skills/plugin-development/templates/02_/346/246/202/350/246/201/350/250/255/350/250/210//343/202/267/343/202/271/343/203/206/343/203/240/345/205/250/344/275/223/344/277/257/347/236/260/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +80 -0
  22. package/spec-runner/templates/.claude/skills/plugin-development/templates/02_/346/246/202/350/246/201/350/250/255/350/250/210//343/203/246/343/203/274/343/202/271/343/202/261/343/203/274/343/202/271/344/270/200/350/246/247/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +57 -0
  23. package/spec-runner/templates/.claude/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/infrastructure/aws.md +53 -0
  24. package/spec-runner/templates/.claude/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/infrastructure/database.md +54 -0
  25. package/spec-runner/templates/.claude/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/infrastructure/schema.dbml +25 -0
  26. package/spec-runner/templates/.claude/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/infrastructure/sequence//343/202/267/343/203/274/343/202/261/343/203/263/343/202/271/345/233/263/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +28 -0
  27. package/spec-runner/templates/.claude/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/agents/{agent_name}/agent.md +56 -0
  28. package/spec-runner/templates/.claude/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/agents/{agent_name}/config.md +47 -0
  29. package/spec-runner/templates/.claude/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/agents/{agent_name}/domain.md +67 -0
  30. package/spec-runner/templates/.claude/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/agents/{agent_name}/prompts.md +72 -0
  31. package/spec-runner/templates/.claude/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/plugins/skills/{skill_name}/skill.md +53 -0
  32. package/spec-runner/templates/.claude/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/plugins/tools/{tool_name}/tool.md +51 -0
  33. package/spec-runner/templates/.claude/skills/test-driven-development/SKILL.md +211 -0
  34. package/spec-runner/templates/.github/agents/code-reviewer.agent.md +69 -0
  35. package/spec-runner/templates/.github/agents/design-reviewer.agent.md +65 -0
  36. package/spec-runner/templates/.github/agents/test-runner.agent.md +34 -0
  37. package/spec-runner/templates/.github/instructions/coding.instructions.md +105 -0
  38. package/spec-runner/templates/.github/instructions/design-docs.instructions.md +62 -0
  39. package/spec-runner/templates/.github/skills/architecture-definition/SKILL.md +60 -0
  40. package/spec-runner/templates/.github/skills/architecture-skill-development/SKILL.md +126 -0
  41. package/spec-runner/templates/.github/skills/commit/SKILL.md +83 -0
  42. package/spec-runner/templates/.github/skills/design-change/SKILL.md +94 -0
  43. package/spec-runner/templates/.github/skills/design-change/references//345/275/261/351/237/277/347/257/204/345/233/262/343/203/201/343/202/247/343/203/203/343/202/257/343/203/252/343/202/271/343/203/210.md +66 -0
  44. package/spec-runner/templates/.github/skills/design-change/templates/90_ADR/ADR/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +81 -0
  45. package/spec-runner/templates/.github/skills/existing-project-to-docs/SKILL.md +57 -0
  46. package/spec-runner/templates/.github/skills/harness-engineering/SKILL.md +100 -0
  47. package/spec-runner/templates/.github/skills/plugin-development/SKILL.md +173 -0
  48. package/spec-runner/templates/.github/skills/plugin-development/templates/01_/350/246/201/344/273/266/345/256/232/347/276/251//346/246/202/350/246/201/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +88 -0
  49. package/spec-runner/templates/.github/skills/plugin-development/templates/02_/346/246/202/350/246/201/350/250/255/350/250/210/90_ADR/ADR/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +81 -0
  50. package/spec-runner/templates/.github/skills/plugin-development/templates/02_/346/246/202/350/246/201/350/250/255/350/250/210//343/202/267/343/202/271/343/203/206/343/203/240/345/205/250/344/275/223/344/277/257/347/236/260/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +80 -0
  51. package/spec-runner/templates/.github/skills/plugin-development/templates/02_/346/246/202/350/246/201/350/250/255/350/250/210//343/203/246/343/203/274/343/202/271/343/202/261/343/203/274/343/202/271/344/270/200/350/246/247/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +57 -0
  52. package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/infrastructure/aws.md +53 -0
  53. package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/infrastructure/database.md +54 -0
  54. package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/infrastructure/schema.dbml +25 -0
  55. package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/infrastructure/sequence//343/202/267/343/203/274/343/202/261/343/203/263/343/202/271/345/233/263/343/203/206/343/203/263/343/203/227/343/203/254/343/203/274/343/203/210.md +28 -0
  56. package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/agents/{agent_name}/agent.md +56 -0
  57. package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/agents/{agent_name}/config.md +47 -0
  58. package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/agents/{agent_name}/domain.md +67 -0
  59. package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/agents/{agent_name}/prompts.md +72 -0
  60. package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/plugins/skills/{skill_name}/skill.md +53 -0
  61. package/spec-runner/templates/.github/skills/plugin-development/templates/03_/350/251/263/347/264/260/350/250/255/350/250/210/src/plugins/tools/{tool_name}/tool.md +51 -0
  62. package/spec-runner/templates/.github/skills/test-driven-development/SKILL.md +211 -0
  63. package/bin/spec-runner.js +0 -270
  64. package/docs/flow.md +0 -72
  65. package/templates/.spec-runner/project.json.example +0 -27
  66. package/templates/.spec-runner/scripts/check.sh +0 -390
  67. package/templates/.spec-runner/scripts/spec-runner-core.sh +0 -289
  68. package/templates/.spec-runner/scripts/uc-next-start.sh +0 -161
  69. package/templates/.spec-runner/spec-runner.sh +0 -29
  70. package/templates/.spec-runner/steps/steps.json +0 -96
  71. package/templates/.spec-runner/steps//343/203/206/343/202/271/343/203/210/350/250/255/350/250/210.md +0 -58
  72. package/templates/.spec-runner/steps//343/203/211/343/203/241/343/202/244/343/203/263/350/250/255/350/250/210.md +0 -52
  73. package/templates/.spec-runner/steps//344/273/225/346/247/230/347/255/226/345/256/232.md +0 -210
  74. package/templates/.spec-runner/steps//345/210/206/346/236/220.md +0 -106
  75. package/templates/.spec-runner/steps//345/256/237/350/243/205.md +0 -80
  76. package/templates/.spec-runner/steps//345/256/237/350/243/205/350/250/210/347/224/273.md +0 -96
  77. package/templates/.spec-runner/steps//346/206/262/347/253/240.md +0 -95
  78. package/templates/.spec-runner/steps//346/233/226/346/230/247/343/201/225/350/247/243/346/266/210.md +0 -110
  79. package/templates/.spec-runner/templates/UC-N-MMDD-/345/210/244/346/226/255/350/250/230/351/214/262/343/203/206/343/203/263/343/203/227/343/203/254.md +0 -33
  80. package/templates/.spec-runner/templates/UC-N-/343/203/246/343/203/274/343/202/271/343/202/261/343/203/274/343/202/271/345/220/215.md +0 -26
  81. package/templates/.spec-runner/templates/phase-locks.json +0 -49
  82. package/templates/.spec-runner/templates//343/203/211/343/203/241/343/202/244/343/203/263/343/203/242/343/203/207/343/203/253.md +0 -21
  83. package/templates/.spec-runner/templates//343/203/246/343/203/223/343/202/255/343/202/277/343/202/271/350/250/200/350/252/236/350/276/236/346/233/270.md +0 -16
  84. package/templates/.spec-runner/templates//346/206/262/347/253/240.md +0 -51
  85. package/templates/.spec-runner/templates//351/233/206/347/264/204.md +0 -46
  86. package/templates/mkdocs-scaffold/docs/index.md +0 -32
  87. package/templates/mkdocs-scaffold/mkdocs.yml +0 -16
  88. package/templates/mkdocs-scaffold/requirements-docs.txt +0 -2
  89. package/templates/skills/uc-k1-work-card-init/SKILL.md +0 -76
  90. package/templates/skills/uc-k2-pre-commit-check/SKILL.md +0 -57
  91. package/templates/skills/uc-k3-spec-impl-diff-review/SKILL.md +0 -57
  92. package/templates/spec-runner-command.md +0 -51
@@ -1,106 +0,0 @@
1
- ---
2
- step_id: analyze
3
- phase: null
4
- readonly: true
5
- note: 任意フェーズで実行可能(読み取り専用)
6
- ---
7
-
8
- # 分析(品質フロー)
9
-
10
- **やること**: 任意フェーズで、**読み取り専用**で UC 仕様・憲章の一貫性・矛盾・カバレッジを分析し、構造化レポートを出力する(ファイルは変更しない)。必要に応じて `docs/work.md` の未解決更新を提案する。
11
-
12
- | 項目 | 内容 |
13
- |------|------|
14
- | **対象** | UC 仕様(## 実装方針・## タスク含む)、`docs/01_憲章/憲章.md` |
15
- | **憲章** | **非交渉**。憲章矛盾は **CRITICAL**。原則の無視・勝手な解釈変更は禁止。原則変更は憲章更新手続きで |
16
-
17
- ## ユーザー入力
18
-
19
- `$ARGUMENTS`(空でなければ必ず考慮)。文末「文脈」にも。
20
-
21
- ```text
22
- $ARGUMENTS
23
- ```
24
-
25
- ## 実行フロー
26
-
27
- ### 1. コンテキスト初期化
28
-
29
- `.spec-runner/spec-runner.sh 次のステップ --json` を 1 回。`feature_spec`・`feature_dir` を使用。
30
- **SPEC** = FEATURE_SPEC(**必須**)。実装方針・タスクは UC の「## 実装方針」「## タスク」。
31
- 無ければエラー中止。引数のシングルクォートはエスケープ。
32
-
33
- ### 2. 段階的読み込み
34
-
35
- | ソース | 読む範囲 |
36
- |--------|----------|
37
- | UC 仕様 | 概要、機能/非機能要件、ユーザーストーリー、エッジケース |
38
- | ## 実装方針 | アーキテクチャ、データ参照、フェーズ、技術制約 |
39
- | ## タスク | タスク ID、説明、フェーズ、[P]、参照パス |
40
- | 憲章 | 原則検証用に全文 |
41
-
42
- ### 3. 内部モデル(出力に生データを含めない)
43
-
44
- - 要件一覧(安定キー付与)
45
- - ユーザーストーリー/アクション一覧
46
- - タスク→要件/ストーリーのマッピング
47
- - 憲章ルールセット(MUST/SHOULD)
48
-
49
- ### 4. 検出パス(所見は合計 **50 件まで**、残りはオーバーフロー要約)
50
-
51
- | ID | 内容 |
52
- |----|------|
53
- | A | 重複(ほぼ同一要件、統合候補) |
54
- | B | 曖昧さ(測定なし形容詞、TODO/TKTK/???/placeholder) |
55
- | C | 仕様不足(動詞のみ、受入なしストーリー、未定義ファイル参照タスク) |
56
- | D | 憲章整合(MUST 違反、ゲート欠落) |
57
- | E | カバレッジ(要件にタスク 0、孤児タスク、非機能のタスク漏れ) |
58
- | F | 不整合(用語ずれ、エンティティの有無矛盾、タスク順序矛盾、要件矛盾) |
59
-
60
- ### 5. 重要度
61
-
62
- | レベル | 目安 |
63
- |--------|------|
64
- | CRITICAL | 憲章 MUST 違反、コア成果物欠落、基本機能を阻害するカバレッジゼロ |
65
- | HIGH | 重複・矛盾要件、曖昧なセキュリティ/性能、テスト不可能な受入 |
66
- | MEDIUM | 用語ずれ、非機能のタスク不足、エッジ仕様不足 |
67
- | LOW | 文体、軽微な重複 |
68
-
69
- ### 6. レポート出力(ファイルに書かない)
70
-
71
- ```markdown
72
- ## 仕様分析レポート
73
-
74
- | ID | カテゴリ | 重要度 | 場所 | 概要 | 推奨対応 |
75
- |----|----------|--------|------|------|----------|
76
- ```
77
-
78
- 所見 1 行 1 件。ID はカテゴリ頭文字+連番。
79
-
80
- **カバレッジ概要表** | 要件キー | タスクあり | タスクID | 注記 |
81
-
82
- **憲章整合性の問題** / **未マッピングのタスク**(あれば)
83
-
84
- **メトリクス**: 要件数、タスク数、カバレッジ%、曖昧さ件数、重複件数、CRITICAL 件数
85
-
86
- ### 7. 次のアクション
87
-
88
- - CRITICAL あり → 「実装」の前に解消推奨
89
- - LOW/MEDIUM のみ → 改善案のうえ進行可
90
- - 次コマンドを明示(仕様修正・実装方針追記・実装計画調整等)
91
- - 完了時に `.spec-runner/phase-locks.json` の `quality.analyzed.<scope>` に対象ドキュメントのベース名を追加する(scope: `charter` / `domain` / `architecture` / `uc`)
92
-
93
- ### 8. 修正案オファー
94
-
95
- 「上位 N 件について具体的な修正案を出しましょうか?」と尋ねる(自動適用しない)。
96
-
97
- ## 運用原則
98
-
99
- - 高シグナル・最小トークン、段階的開示、所見表 50 行、再実行で同じ ID・件数
100
-
101
- ## 文脈
102
-
103
- `$ARGUMENTS`
104
-
105
- ---
106
- **次**: 完了後、次のステップへ進む。
@@ -1,80 +0,0 @@
1
- ---
2
- step_id: implement
3
- phase: 6
4
- ---
5
-
6
- # 実装(Phase 6: IMPLEMENTATION)
7
-
8
- **やること**: Phase 5 の **PENDING テストをグリーン**にする。**完了**はコードだけでなく **起動確認**(dev で `/` と主要画面)と **可能なら E2E 1 本グリーン**。あわせて `docs/work.md` のチェックボックスと検証結果を確定する。
9
-
10
- | 項目 | 内容 |
11
- |------|------|
12
- | **UC 配置** | カテゴリ内 **UC-N-xxx.md 1 本**。**## 実装方針**・**## タスク**(または **## タスク一覧**)は **一番下** |
13
- | **検証** | 完了は check.sh。テストは **`project.json` の `test_command.run`** が **exit 0** まで「完了」報告しない |
14
-
15
- ## フォルダ構造
16
-
17
- | 種別 | ルール |
18
- |------|--------|
19
- | docs | リポジトリルート直下のみ |
20
- | アプリコード | **src/** 下(domain / infrastructure / application / app)。docs 隣に domain を置かない |
21
- | paths 例 | `"@/*": ["./src/*"]` |
22
-
23
- ## ユーザー入力
24
-
25
- `$ARGUMENTS`(空でなければ必ず考慮)
26
-
27
- ```text
28
- $ARGUMENTS
29
- ```
30
-
31
- ## 実行前チェック: hooks.before_implement
32
-
33
- - `extensions.yml` の `hooks.before_implement`(無ければスキップ、YAML 不正もスキップ)
34
- - `enabled: true` のみ。condition は評価しない
35
- - 任意: 表示のみ。必須: 実行して待つ
36
-
37
- ## 実行フロー
38
-
39
- 1. **JSON**
40
- `次のステップ --json`。`feature_dir`・`feature_spec`。
41
-
42
- 2. **チェックリスト(FEATURE_DIR/checklists/ がある場合)**
43
- `- [ ]` / `- [x]` を数え表化。未完了 0 → PASS。未完了あり → 「このまま進めますか? yes/no」で待つ。no で停止。yes で続行。
44
-
45
- 3. **読込**
46
- FEATURE_SPEC **必須**。実装方針・タスクは UC 一番下。
47
-
48
- 4. **プロジェクトセットアップ確認**
49
- - **test_command.run** が無い/不適なら `project.json` を更新(1 本のコマンド)
50
- - git なら .gitignore。Docker/ESLint/Prettier/Terraform/Helm 等に応じ ignore を確認・不足のみ追加
51
- - 技術スタックは実装方針または package.json 等から
52
-
53
- 5. **実装範囲**
54
- ## タスク と受入・フローから項目列挙。
55
-
56
- 6. **実行**
57
- タスク順。UC のみなら受入・フローに沿い **テスト→コア→統合** 推奨。同一ファイルは順次。
58
-
59
- 7. **ルールの目安**
60
- セットアップ →(必要なら)テスト先行 → モデル・サービス・EP → 統合 → 仕上げ
61
-
62
- 8. **進捗・エラー**
63
- タスクごと報告。非並列失敗で停止。[P] は成功分続行。UC タスクの完了は `[x]`。
64
-
65
- 9. **完了検証**
66
- - 必須タスク完了・仕様一致
67
- - **`test_command.run` の実行結果** が 0 になるまで完了報告禁止
68
- - **起動確認(必須)**: dev で `/` と当該 UC の主要画面が 200 等。不可なら修正まで
69
- - **E2E(推奨)**: `tests/e2e/` に該当 UC があればハッピーパス 1 本グリーンを目標。無ければユニット+起動で可
70
-
71
- 10. **hooks.after_implement**
72
- あれば同様に表示/実行。
73
-
74
- ## 次の UC・履歴整理
75
-
76
- 次 UC やマージのタイミングはプロジェクト次第。**コミット・ブランチが欲しくなったら** AI に相談する。
77
- **任意**: `.spec-runner/scripts/uc-next-start.sh`(`--yes` で確認省略)— **次 UC 用の仕様ひな形 `.md` のみ**作成(ブランチは作らない)。
78
-
79
- ---
80
- **次**: 完了後、次のステップへ。
@@ -1,96 +0,0 @@
1
- ---
2
- step_id: implementation_plan
3
- phase: 3
4
- note: アーキテクチャ設計
5
- ---
6
-
7
- # 実装計画(アーキテクチャ)
8
-
9
- **やること**: `docs/04_アーキテクチャ/` に設計を置き、最新の UC 仕様に **実装方針を UC の .md の一番下(## 実装方針)** として反映する。あわせて `docs/work.md` の実装タスクを更新する。
10
-
11
- | 項目 | 内容 |
12
- |------|------|
13
- | **docs/02** | カテゴリフォルダ内に **UC-N-xxx.md を 1 本ずつ**。実装方針・タスクは **各 UC .md の一番下** |
14
- | **動的設定** | 必須ドキュメント・命名規則は **`.spec-runner/project.json` を AI が直接編集** |
15
- | **補足(任意)** | 必要に応じて `docs/05_インフラ設計`(schema.dbml 等)を作成 |
16
-
17
- ## ユーザー入力
18
-
19
- `$ARGUMENTS`(空でなければ必ず考慮)
20
-
21
- ```text
22
- $ARGUMENTS
23
- ```
24
-
25
- ## フォルダの作成
26
-
27
- | フェーズ | パス | 内容の例 |
28
- |----------|------|----------|
29
- | Phase 2 | `docs/04_アーキテクチャ/` | パターン選定・インフラ方針・命名・設計判断(`MMDD-題名.md`。年はフォルダ分け可) |
30
- | 任意 | `docs/05_インフラ設計/` | クラウド・ネットワーク・**schema.dbml**(必要時のみ) |
31
- | API 公開時 | `docs/06_API仕様/` | openapi.yaml(Gate 3 で参照) |
32
-
33
- ## API 仕様(openapi.yaml)
34
-
35
- - **単一ソース**: `docs/06_API仕様/openapi.yaml`。型・クライアントはここから生成すると設計と一致。`tags` で分類、`$ref` 分割可。
36
- - **生成手段**: プロジェクト標準(openapi-generator / openapi-typescript / orval 等)。spec-runner は固定しない。
37
-
38
- ## Phase 2(main/develop など)
39
-
40
- `docs/01_憲章/憲章.md` と `docs/03_ドメイン設計/` を読み、**`docs/04_アーキテクチャ/`** にパターン選定・インフラ方針・命名・設計判断記録を作成。フォルダが無ければこのフェーズで作成。
41
-
42
- ## UC 上での計画(実装方針セクション)
43
-
44
- 以下 1–4 を実行。
45
-
46
- 1. **セットアップ**
47
- `.spec-runner/spec-runner.sh 次のステップ --json`。`feature_spec`・`feature_dir`。
48
-
49
- 2. **文脈**
50
- FEATURE_SPEC(**必須**)、`docs/01_憲章/憲章.md`、UC の「## 実装方針」。UC 1 本で計画。
51
-
52
- 3. **計画ワークフロー**
53
- - 技術コンテキスト(不明は「要確認」)
54
- - 憲章チェックを憲章から埋める
55
- - ゲート評価(正当化されない違反は ERROR)
56
- - **ファイル構成**: docs はルート直下。アプリコードは **src/**(憲章・アーキで決まっていれば従う)
57
- - Phase 0: research.md は任意(要確認がある場合のみ)
58
- - Phase 1: **data-model.md / contracts/ は任意**。正は 集約.md・schema.dbml・コード。API は openapi.yaml。必要なら FEATURE_DIR や docs/04 に追加可
59
- - 設計後に憲章チェックを再評価
60
-
61
- 4. **停止と報告**
62
- コマンドは Phase 2 計画の後で終了。FEATURE_SPEC・生成物を報告。
63
-
64
- ## サブフェーズ詳細
65
-
66
- ### Phase 0: 概要とリサーチ
67
-
68
- 1. 技術コンテキストの「要確認」→ リサーチタスク、依存→ベストプラクティス、連携→パターンタスク
69
- 2. リサーチタスク例:
70
-
71
- ```text
72
- 技術コンテキストの各不明点について:
73
- タスク: 「{機能文脈} 向けに {不明点} をリサーチする」
74
- 各技術選択について:
75
- タスク: 「{ドメイン} における {技術} のベストプラクティスを調べる」
76
- ```
77
-
78
- 3. **research.md** に集約: 決定 / 理由 / 検討した代替案
79
- **成果物**: 要確認が解消された research.md
80
-
81
- ### Phase 1: 設計と契約
82
-
83
- **前提**: research.md 完了(使う場合)
84
-
85
- 1. 機能仕様からエンティティ抽出 → `data-model.md`(フィールド・リレ・バリデ・状態遷移)
86
- 2. 外部 IF がある場合 → `/contracts/`(公開 API・CLI・Web 等)。純内部はスキップ可
87
-
88
- **成果物**: data-model / contracts / quickstart は**任意**。コードと 集約.md・openapi で足りなければ作る。
89
-
90
- ## 重要ルール
91
-
92
- - 絶対パスを使用する
93
- - ゲート違反・未解消の確認事項は ERROR
94
-
95
- ---
96
- **次**: 完了後、次のステップへ進む。
@@ -1,95 +0,0 @@
1
- ---
2
- step_id: charter
3
- phase: 0
4
- primary_output: docs/01_憲章/憲章.md
5
- ---
6
-
7
- # 憲章策定(Phase 0: CHARTER)
8
-
9
- **やること**: `docs/01_憲章/憲章.md` のプロジェクト憲章を作成・更新する。spec.md セクション 2(Phase 0)に準拠する。あわせて `docs/work.md` の目的・受入条件・実装タスクを更新する。
10
-
11
- | 項目 | 内容 |
12
- |------|------|
13
- | **成果物** | `docs/01_憲章/憲章.md` のみ |
14
- | **動的設定** | 命名規則・必須ドキュメント・テストコマンドは **`.spec-runner/project.json` を AI が直接編集**して上書き |
15
- | **テンプレ** | 無い場合は `.spec-runner/templates/憲章.md` から生成してから埋める |
16
-
17
- ## ユーザー入力
18
-
19
- `$ARGUMENTS`(空でなければ必ず考慮)
20
-
21
- ```text
22
- $ARGUMENTS
23
- ```
24
-
25
- ## 前提条件
26
-
27
- | 状況 | 行動 |
28
- |------|------|
29
- | `docs/` や `docs/01_憲章/` が無い | このフェーズで **`docs/01_憲章/` を新規作成**し、その中に `憲章.md` を置く |
30
- | `docs/01_憲章/憲章.md` が無い | テンプレから生成してから埋める(上記テンプレパス) |
31
-
32
- ## 禁止
33
-
34
- - **他フェーズのフォルダ**(`docs/03_ドメイン設計/` 等)が既にあっても、**その既存ドキュメントからプロジェクト内容を推測しない**。憲章は**ユーザー入力と対話のみ**で策定し、既存ドキュメントに合わせて書き換えない。
35
-
36
- ## 概要
37
-
38
- - 角括弧プレースホルダ(例: `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`)を (a) 収集・導出 (b) テンプレを正確に埋める (c) 依存成果物へ反映、の三つで進める。
39
- - まだ無い場合は spec.md Phase 0 テンプレ(目的・ビジョン、非交渉要件、技術スタック、投資判断、スコープ外、ガバナンス)に沿って新規作成する。
40
-
41
- ## 実行フロー
42
-
43
- 1. **既存憲章の読み込み**
44
- `docs/01_憲章/憲章.md` が**ある場合のみ**読み、`[ALL_CAPS_IDENTIFIER]` 形式のプレースホルダをすべて特定。**無い場合**は Phase 0 テンプレに沿って新規作成(フォルダ作成ルールに従う)。
45
- **重要**: ユーザーがテンプレより少ない/多い原則を求める場合がある。数が指定されていればそれに従い、一般的なテンプレに沿って更新する。
46
-
47
- 2. **プレースホルダへの値の収集・導出**
48
- - ユーザー入力(会話)で与えられていればそれを使う
49
- - 不明は **推測で確定しない**。本文に **`[要確認: ...]`**(例: `[要確認: PROJECT_NAME(正式名称)]`)
50
- - ガバナンス日付: `RATIFICATION_DATE` は採択日(不明なら質問か TODO)、`LAST_AMENDED_DATE` は変更があれば今日、なければ前回のまま
51
- - `CONSTITUTION_VERSION` はセマンティック:
52
- - **MAJOR**: 後方互換のないガバナンス/原則の削除・再定義
53
- - **MINOR**: 新規原則/セクション追加または重要な拡張
54
- - **PATCH**: 明確化・表現・誤字・意味を変えない調整
55
- - 種類が曖昧なら確定前に理由を提示
56
-
57
- 3. **更新後の憲章文案**
58
- - プレースホルダは具体テキストで置換(意図的スロット以外は角括弧を残さない。残す場合は理由を明記)
59
- - 見出し階層はテンプレと同一。コメントは置換後削除可(説明になっていれば残す)
60
- - 各原則: 簡潔な名前・非交渉ルールの段落/箇条書き・理由が自明でなければ明示
61
- - ガバナンス: 改正手続き・バージョン方針・準拠レビューの期待
62
-
63
- 4. **整合性の伝播**(該当フォルダが**既に存在する場合のみ**)
64
- - `docs/03_ドメイン設計/` や `docs/04_アーキテクチャ/` があれば、憲章原則と矛盾がないか確認。存在しないフェーズは無視
65
- - README / spec-runner ガイダンスで原則参照の更新が必要なら案内
66
-
67
- 5. **最終検証**(成果物・検証も参照)
68
-
69
- 6. **書き込み**
70
- 完成した憲章を **`docs/01_憲章/憲章.md`** に上書き。**憲章先頭に HTML コメントの「同期影響レポート」や `status: reviewed` は付けない**(`.spec-runner/phase-locks.json` のみで管理)。
71
-
72
- 7. **ユーザーへの最終サマリ**
73
- - 新バージョンと上げた理由
74
- - 手動フォローアップが必要なファイル
75
- - 推奨コミットメッセージ例: `docs: 憲章を vX.Y.Z に改正(原則追加とガバナンス更新)`
76
-
77
- ## 成果物・検証
78
-
79
- - [ ] 説明のない角括弧トークンが残っていない
80
- - [ ] バージョン行が変更内容と一致
81
- - [ ] 日付は ISO `YYYY-MM-DD`
82
- - [ ] 原則は宣言的・テスト可能。曖昧な「should」は必要に応じ MUST/SHOULD と理由へ
83
-
84
- ユーザーが一部だけ更新を依頼した場合も、検証とバージョン決定は行う。
85
- 欠けている重要情報(例: 批准日が本当に不明)は `TODO(<フィールド名>): 説明` を本文に挿入し、サマリでフォローアップを案内。
86
- **新規テンプレは作らない**。常に **`docs/01_憲章/憲章.md`** を操作する。
87
-
88
- ## 付録: 書式・スタイル
89
-
90
- - 見出しはテンプレと同一(レベルを上げ下げしない)
91
- - 理由は 100 文字目安で折り返すが、不自然な改行は避ける
92
- - セクション間は空行 1 行、行末空白を避ける
93
-
94
- ---
95
- **次**: 完了後、次のステップへ進む。
@@ -1,110 +0,0 @@
1
- ---
2
- step_id: clarify
3
- phase: null
4
- note: 任意フェーズで曖昧さを解消
5
- ---
6
-
7
- # 曖昧さ解消(品質フロー)
8
-
9
- **やること**: 任意フェーズで対象仕様(憲章 / UC 仕様 / ドメイン設計 / アーキテクチャ)の曖昧さ・不足決定を検出し、**対話で 1 問ずつ**解消して仕様ファイルに反映する。必要なら `docs/work.md` の受入条件・未解決も更新する。
10
-
11
- | 項目 | 内容 |
12
- |------|------|
13
- | **タイミング** | 任意フェーズで実行可能。必要に応じて複数回実行してよい |
14
- | **仕様パス** | `FEATURE_SPEC`(憲章: `docs/01_憲章/憲章.md`、UC: `docs/02_ユースケース仕様/.../UC-N-xxx.md`、ドメイン: `docs/03_ドメイン設計/*.md`、アーキ: `docs/04_アーキテクチャ/*.md`) |
15
- | **判断ログ(任意)** | `FEATURE_DIR/判断記録/UC-N-MMDD-題名.md`。テンプレ: `.spec-runner/templates/UC-N-MMDD-判断記録テンプレ.md`。横断は `docs/04_アーキテクチャ/設計判断記録/` |
16
-
17
- ## ユーザー入力
18
-
19
- `$ARGUMENTS`(空でなければ必ず考慮)。優先付けの文脈にも使う。
20
-
21
- ```text
22
- $ARGUMENTS
23
- ```
24
-
25
- ## 実行フロー
26
-
27
- 1. **JSON**
28
- `.spec-runner/spec-runner.sh 次のステップ --json` を **1 回**。`FEATURE_SPEC`・`FEATURE_DIR` を使用。
29
- - UC 仕様を対象とする場合: 実装方針・タスクは **UC .md の一番下**。
30
- - 憲章を対象とする場合: 憲章本文の原則・定義・用語を対象にする。
31
- - ドメイン/アーキを対象とする場合: 現在の `FEATURE_SPEC`(対象 `.md`)の曖昧さを解消する。
32
- JSON パース失敗 → 中止。`FEATURE_SPEC` が空なら対象仕様が未作成なので先に作成を案内。
33
- シングルクォートはエスケープ(例: `'I'\''m Groot'`)。
34
-
35
- 2. **スキャン**
36
- 付録のカテゴリで曖昧さ・カバレッジをスキャンし各カテゴリに Clear / Partial / Missing。内部マップ作成(質問がない場合以外は生マップは出さない)。
37
- Partial/Missing は **付録「質問候補の除外」** に該当しなければ質問候補へ。
38
-
39
- 3. **質問キュー(最大 5 問)**
40
- 一度に全部は出さない。制約:
41
- - セッション合計 **最大 5 問**
42
- - 各問は **2〜5 択** または **短答(5 語以内)**
43
- - アーキテクチャ・データモデル・タスク・テスト・UX・運用・コンプライアンスに**大きく影響**するものだけ
44
- - カテゴリのバランス、影響の大きい領域優先
45
- - 既答・trivial・計画レベルの実行詳細は除外
46
- - 5 カテゴリ以上未解決なら (影響×不確実性) で上位 5 つ
47
-
48
- 4. **逐次質問ループ**
49
- - **1 問ずつ**提示
50
- - **択一**: 最適肢を分析 → `**推奨:** 選択肢 [X] - <理由>` → 表で全選択肢 → 「A で返答 / yes・recommended で推奨採用 / 短い独自回答可」
51
- - **短答**: `**提案:** <回答> - <理由>` → yes・suggested で採用可
52
- - 回答処理: yes/recommended/suggested → 採用。それ以外は択一対応・5 語以内を確認。曖昧は同一問内で聞き直し(問数増やさない)。OK ならメモリに記録(まだディスクに全面反映しない)
53
- - 打ち切り: 重要曖昧が早く解消 / ユーザー「完了」「十分」等 / 5 問到達。今後の問は事前に明かさない。有効な問が無ければ「重要な曖昧は検出されなかった」と報告
54
-
55
- 5. **回答ごとの反映(増分)**
56
- - メモリとファイル内容を保持
57
- - **本文更新を必須**: 採用回答を必ず該当セクションへ反映(機能→機能要件、操作→ストーリー/アクター、データ→データモデル、非機能→測定可能な基準、エッジ→エッジケース、用語→統一・旧表記は一度だけ (旧: "X"))
58
- - `## 解消事項` は任意。必要な場合のみ最小限を残す(本文の代替にしない)
59
- - 記録する場合は次の改行形式:
60
- ```markdown
61
- - Q: <質問>
62
- A: <回答>
63
- ```
64
- - 古い曖昧記述は置換し矛盾を残さない。**各反映の直後にファイル保存**。見出し階層維持。新規見出しは **`## 解消事項`** のみ可
65
-
66
- 6. **検証(各書き込み後・最終)**
67
- - 本文に解消済み内容が反映され、本文だけ読めば仕様が確定している
68
- - 質問数(採用分)≤ 5
69
- - 更新セクションに解消済みの曖昧プレースホルダが残っていない
70
- - 矛盾なし、Markdown 有効、用語一貫
71
-
72
- 7. **書き戻し**
73
- `FEATURE_SPEC` に保存
74
-
75
- 8. **完了報告**
76
- 質問数・回答数・仕様パス・変更セクション一覧・カテゴリカバレッジ表(Resolved / Deferred / Clear / Outstanding)。Outstanding/Deferred 残りは「実装計画」か再「曖昧さ解消」を推奨。次コマンドを明示
77
-
78
- ## 動作ルール
79
-
80
- - 意味のある曖昧がない: 「正式な解消に値する重要な曖昧さは検出されませんでした」と次へ
81
- - 仕様ファイルがない: 対象仕様(憲章 / UC / ドメイン / アーキ)の作成を案内(ここでは新規作成しない)
82
- - `[要確認: ...]` が残っている項目を優先して質問対象にする
83
- - `[要確認: ...]` が無くても、文脈から曖昧・未決定な表現を検出して質問対象に含める
84
- - 実行状態は `.spec-runner/phase-locks.json` の `quality.clarified.<scope>` で管理し、本文に余計な状態メタ情報は残さない
85
- - `## 解消事項` を残す場合も最小限にし、判断の正本は常に本文とする
86
- - 質問は合計 5 を超えない(聞き直しは新規に数えない)
87
- - 機能の明確さを妨げない限り技術スタックの推測質問は避ける
88
- - 「ストップ」「完了」「進めて」等を尊重
89
- - 質問不要なら簡潔なカバレッジ概要(全 Clear)で次へ
90
- - 5 問で未解決が残る場合は Deferred を理由付きで明示
91
-
92
- ## 付録: スキャンカテゴリ
93
-
94
- | カテゴリ | 見ること |
95
- |----------|----------|
96
- | 機能スコープと振る舞い | コア目標・成功基準、スコープ外、ロール・ペルソナ |
97
- | ドメインとデータモデル | エンティティ・属性・リレ、ID・一意性、ライフサイクル、データ量仮定 |
98
- | インタラクションと UX | ジャーニー、エラー/空/ローディング、a11y・i18n |
99
- | 非機能 | 性能、スケール、信頼性・可用性、観測性、セキュリティ・プライバシー、コンプライアンス |
100
- | 連携と外部依存 | 外部 API・障害モード、I/O 形式、プロトコル仮定 |
101
- | エッジと障害 | ネガティブ、レート制限、競合解決 |
102
- | 制約とトレードオフ | 技術制約、却下した代替案 |
103
- | 用語と一貫性 | 正規用語、避ける同義語 |
104
- | 完了のシグナル | 受入のテスト可能性、測定可能な Done |
105
- | その他 | TODO、未解決決定、曖昧形容詞(堅牢・直感的等) |
106
-
107
- **質問候補から外す場合**: 解消しても実装・検証戦略が大きく変わらない / 情報は計画フェーズに回す方がよい(内部メモ)
108
-
109
- ---
110
- **次**: 完了後、次のステップへ進む。
@@ -1,33 +0,0 @@
1
- # 判断記録(UCごと)
2
-
3
- > ファイル名: `UC-N-MMDD-題名.md`(例: `UC-1-0317-要件解釈.md`)
4
- > 置き場所: `docs/02_ユースケース仕様/<カテゴリ>/判断記録/`
5
-
6
- ## 結論(Decision)
7
-
8
- - [要確認: 決定内容を一文で]
9
-
10
- ## 背景(Context)
11
-
12
- - [要確認: なぜこの判断が必要になったか]
13
-
14
- ## 選択肢(Options)
15
-
16
- - **案A**: [要確認: 説明]
17
- - **案B**: [要確認: 説明]
18
- - (任意)**案C**: [要確認: 説明]
19
-
20
- ## 判断理由(Rationale)
21
-
22
- - [要確認: 採用理由(制約・トレードオフ)]
23
-
24
- ## 影響範囲(Impact)
25
-
26
- - **仕様書**: `docs/02_ユースケース仕様/<カテゴリ>/UC-N-題名.md` のどの節に反映したか
27
- - **ドメイン**: 影響がある場合は `docs/03_ドメイン設計/` の更新点
28
- - **アーキ**: 横断判断なら `docs/04_アーキテクチャ/設計判断記録/` へ
29
-
30
- ## 未解決(Open Questions)
31
-
32
- - [要確認: 未解決事項があれば]
33
-
@@ -1,26 +0,0 @@
1
- # UC-N: {ユースケース名}
2
-
3
- > 原則: 1 UC = 1 操作。CRUD は作成 / 編集 / 削除を別 UC に分ける。
4
-
5
- ## 概要
6
-
7
- ## アクター
8
-
9
- ## 事前条件
10
-
11
- ## 基本フロー
12
-
13
- ## 代替フロー
14
-
15
- ## 例外
16
-
17
- ## 事後条件
18
-
19
- ## 受入条件
20
-
21
- | 前提 | 操作 | 期待 |
22
- |------|------|------|
23
- | <条件・前提状態> | <ユーザー操作・イベント> | <測定可能な結果> |
24
-
25
- ## 備考
26
-
@@ -1,49 +0,0 @@
1
- {
2
- "_comment": "フェーズ完了状態の単一ソース。初期状態ではすべて未完了。レビュー状態もここで管理する。インストール時に .spec-runner/phase-locks.json へコピーされる(既にある場合はスキップ)。",
3
- "charter": {
4
- "completed": false,
5
- "locked_at": null,
6
- "reviewed_by": null
7
- },
8
- "domain": {
9
- "completed": false,
10
- "locked_at": null,
11
- "reviewed_by": null
12
- },
13
- "architecture": {
14
- "completed": false,
15
- "locked_at": null,
16
- "reviewed_by": null
17
- },
18
- "infra": {
19
- "completed": false,
20
- "locked_at": null,
21
- "reviewed_by": null
22
- },
23
- "test_design": {
24
- "completed": false,
25
- "locked_at": null,
26
- "reviewed_by": null
27
- },
28
- "uc_discovery": {
29
- "completed": false,
30
- "locked_at": null,
31
- "reviewed_by": null
32
- },
33
- "uc_reviewed": [],
34
- "quality": {
35
- "_comment": "clarify/analyze の実行済み管理(対象ドキュメントのベース名)",
36
- "clarified": {
37
- "charter": [],
38
- "domain": [],
39
- "architecture": [],
40
- "uc": []
41
- },
42
- "analyzed": {
43
- "charter": [],
44
- "domain": [],
45
- "architecture": [],
46
- "uc": []
47
- }
48
- }
49
- }
@@ -1,21 +0,0 @@
1
- # ドメインモデル
2
-
3
- ## 境界づけられたコンテキスト(Bounded Context)
4
-
5
- - [CONTEXT_1]: [CONTEXT_1_DESC]
6
-
7
- ## 主要概念(高レベル)
8
-
9
- - [CONCEPT_1]
10
- - [CONCEPT_2]
11
-
12
- ## 関係(ざっくりでよい)
13
-
14
- - [RELATION_1]
15
- - [RELATION_2]
16
-
17
- ## 不変条件(Invariants)
18
-
19
- - [INVARIANT_1]
20
- - [INVARIANT_2]
21
-
@@ -1,16 +0,0 @@
1
- # ユビキタス言語辞書
2
-
3
- ## 用語(Terms)
4
-
5
- | 用語 | 定義 | 同義語/別名 | 例 | 備考 |
6
- |------|------|-------------|----|------|
7
- | [TERM_1] | [DEFINITION_1] | [SYNONYM_1] | [EXAMPLE_1] | |
8
- | [TERM_2] | [DEFINITION_2] | [SYNONYM_2] | [EXAMPLE_2] | |
9
-
10
- ## 禁止語(Forbidden)
11
-
12
- 同義語の乱立や解釈ズレを防ぐため、以下の語は使わない(または、使う場合はこの辞書に登録してからにする)。
13
-
14
- - [FORBIDDEN_1](代替: [PREFERRED_1])
15
- - [FORBIDDEN_2](代替: [PREFERRED_2])
16
-