specdojo 0.2.1 → 0.3.1

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 (242) hide show
  1. package/.github/agents/specdojo-orchestrator.md +165 -0
  2. package/CHANGELOG.md +298 -0
  3. package/README.md +92 -42
  4. package/dist/agent-response.js +20 -0
  5. package/dist/agent.js +4 -4
  6. package/dist/build-command.js +28 -8
  7. package/dist/catalog-build-references.js +144 -0
  8. package/dist/catalog-build-render.js +144 -0
  9. package/dist/catalog-build.js +13 -290
  10. package/dist/catalog-generate.js +6 -9
  11. package/dist/catalog-plan-generate.js +2 -2
  12. package/dist/catalog-plan.js +6 -6
  13. package/dist/catalog-scaffold.js +4 -4
  14. package/dist/catalog.js +2 -2
  15. package/dist/dashboard-exec-records.js +105 -0
  16. package/dist/dashboard-routines.js +255 -0
  17. package/dist/dashboard-shared.js +14 -0
  18. package/dist/dashboard-timeline.js +175 -0
  19. package/dist/dashboard.js +31 -444
  20. package/dist/deliverable-trash.js +3 -3
  21. package/dist/devcontainer-command.js +43 -0
  22. package/dist/devcontainer-scaffold.js +165 -0
  23. package/dist/doc-index.js +3 -3
  24. package/dist/exec-agent-config.js +107 -9
  25. package/dist/exec-agent-git-state.js +18 -0
  26. package/dist/exec-agent-protected-config.js +46 -8
  27. package/dist/exec-commands.js +557 -0
  28. package/dist/exec-core.js +457 -0
  29. package/dist/exec-evidence.js +254 -11
  30. package/dist/exec-handoff.js +336 -0
  31. package/dist/exec-parent-validation.js +317 -43
  32. package/dist/exec-pipeline-state.js +74 -9
  33. package/dist/exec-plans-core.js +693 -0
  34. package/dist/exec-plans-generation.js +206 -0
  35. package/dist/exec-plans-storage.js +131 -0
  36. package/dist/exec-plans.js +3 -1016
  37. package/dist/exec-protection-handoff.js +43 -2
  38. package/dist/exec-provider-scaffold.js +247 -15
  39. package/dist/exec-register-resume.js +65 -19
  40. package/dist/exec-register.js +9 -3
  41. package/dist/exec-repo-integration-git.js +23 -0
  42. package/dist/exec-repo-integration-sync.js +264 -0
  43. package/dist/exec-repo-integration.js +534 -0
  44. package/dist/exec-repo-trace.js +182 -0
  45. package/dist/exec-reporter-output.js +206 -0
  46. package/dist/exec-reporter.js +525 -248
  47. package/dist/exec-results.js +103 -71
  48. package/dist/exec-run-agent-pipeline.js +256 -0
  49. package/dist/exec-run-agent.js +531 -0
  50. package/dist/exec-run-in-place.js +541 -0
  51. package/dist/exec-run-job.js +717 -0
  52. package/dist/exec-run-lifecycle-commands.js +522 -0
  53. package/dist/exec-run-lock.js +110 -107
  54. package/dist/exec-run-mode-shared.js +140 -0
  55. package/dist/exec-run-register-command.js +244 -0
  56. package/dist/exec-run-register-core.js +386 -0
  57. package/dist/exec-run-register-mode.js +206 -0
  58. package/dist/exec-run-register-resume.js +393 -0
  59. package/dist/exec-run-register-state.js +322 -0
  60. package/dist/exec-run-register-worktree.js +509 -0
  61. package/dist/exec-run-schedule-mode.js +294 -0
  62. package/dist/exec-run-schedule-prepare.js +353 -0
  63. package/dist/exec-run-schedule-task.js +572 -0
  64. package/dist/exec-run-shared.js +399 -0
  65. package/dist/exec-run.js +11 -4953
  66. package/dist/exec-shared.js +9 -2
  67. package/dist/exec-slot-lock.js +242 -0
  68. package/dist/exec-task-repos.js +415 -0
  69. package/dist/exec-trial-commands.js +558 -0
  70. package/dist/exec-trial-core.js +371 -0
  71. package/dist/exec-trial.js +2 -895
  72. package/dist/exec-worktree-command.js +87 -43
  73. package/dist/exec-worktree-ops-commit.js +707 -0
  74. package/dist/exec-worktree-ops-lifecycle.js +292 -0
  75. package/dist/exec-worktree-ops-merge.js +303 -0
  76. package/dist/exec-worktree-ops.js +3 -847
  77. package/dist/exec-worktree.js +146 -31
  78. package/dist/exec.js +2 -999
  79. package/dist/frontmatter-namespace.js +2 -2
  80. package/dist/grade-apply.js +734 -0
  81. package/dist/grade-command-apply.js +250 -0
  82. package/dist/grade-command-inspect.js +138 -0
  83. package/dist/grade-command-plan.js +101 -0
  84. package/dist/grade-command-shared.js +68 -0
  85. package/dist/grade-core.js +307 -0
  86. package/dist/grade-markdown.js +274 -0
  87. package/dist/grade-pipeline-state.js +184 -0
  88. package/dist/grade-plan.js +507 -0
  89. package/dist/grade-result.js +133 -5
  90. package/dist/grade-target-discovery.js +265 -0
  91. package/dist/grade-targets.js +432 -0
  92. package/dist/grade.js +14 -2451
  93. package/dist/init-command.js +443 -0
  94. package/dist/job-definition.js +670 -0
  95. package/dist/job.js +64 -578
  96. package/dist/kata-command.js +2 -2
  97. package/dist/orchestrator.js +213 -0
  98. package/dist/register-command-types.js +1 -0
  99. package/dist/register-core.js +363 -0
  100. package/dist/register-create-commands.js +245 -0
  101. package/dist/register-event-merge.js +169 -0
  102. package/dist/register-events.js +4 -4
  103. package/dist/register-item.js +13 -7
  104. package/dist/register-maintenance-commands.js +187 -0
  105. package/dist/register-migration.js +268 -0
  106. package/dist/register-renumber.js +314 -0
  107. package/dist/register-transition-commands.js +248 -0
  108. package/dist/register-update.js +230 -0
  109. package/dist/register-views.js +256 -0
  110. package/dist/register.js +175 -1975
  111. package/dist/review-grade.js +252 -0
  112. package/dist/review-plan.js +114 -4
  113. package/dist/review-types.js +40 -1
  114. package/dist/routine-definition.js +401 -0
  115. package/dist/routine.js +73 -402
  116. package/dist/schedule-approach.js +2 -2
  117. package/dist/schedule-build.js +2 -2
  118. package/dist/schedule-strategy-generate-document.js +273 -0
  119. package/dist/schedule-strategy-generate-scope.js +199 -0
  120. package/dist/schedule-strategy-generate.js +9 -473
  121. package/dist/schedule.js +19 -6
  122. package/dist/specdojo-config.js +465 -20
  123. package/dist/specdojo-gitignore.js +135 -0
  124. package/dist/specdojo.js +6 -0
  125. package/dist/viewpoint-document-kinds-check.js +128 -0
  126. package/dist/yaml-pages.js +4 -4
  127. package/dist/yaml.js +28 -0
  128. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +348 -90
  129. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +51 -17
  130. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +7 -5
  131. package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +29 -31
  132. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +34 -55
  133. package/docs/ja/specdojo/exec-templates/xrp-job-template.md +54 -0
  134. package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +28 -37
  135. package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +29 -34
  136. package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +30 -30
  137. package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +29 -34
  138. package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +29 -34
  139. package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +29 -34
  140. package/docs/ja/specdojo/exec-templates/xrp-template.md +29 -28
  141. package/docs/ja/specdojo/exec-templates/xrr-template.md +11 -9
  142. package/docs/ja/specdojo/guides/docs-editing-guide.md +20 -0
  143. package/docs/ja/specdojo/guides/docs-structure-guide.md +103 -70
  144. package/docs/ja/specdojo/guides/exec-config-guide.md +93 -49
  145. package/docs/ja/specdojo/guides/exec-operation-guide.md +124 -27
  146. package/docs/ja/specdojo/guides/exec-worktree-guide.md +40 -11
  147. package/docs/ja/specdojo/guides/kata-guide.md +4 -4
  148. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +45 -22
  149. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +1 -1
  150. package/docs/ja/specdojo/guides/practice-system-composition-guide.md +13 -13
  151. package/docs/ja/specdojo/guides/quick-start-guide.md +260 -30
  152. package/docs/ja/specdojo/guides/register-operation-guide.md +31 -14
  153. package/docs/ja/specdojo/guides/release-v0-3-0-migration-guide.md +264 -0
  154. package/docs/ja/specdojo/guides/remote-host-development-guide.md +22 -1
  155. package/docs/ja/specdojo/guides/review-guide.md +195 -158
  156. package/docs/ja/specdojo/guides/routine-operation-guide.md +75 -10
  157. package/docs/ja/specdojo/guides/ryu-guide.md +32 -30
  158. package/docs/ja/specdojo/guides/schedule-design-guide.md +10 -10
  159. package/docs/ja/specdojo/guides/schedule-operation-guide.md +1 -1
  160. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +58 -33
  161. package/docs/ja/specdojo/guides/use-case-guide.md +3 -3
  162. package/docs/ja/specdojo/guides/waza-guide.md +15 -2
  163. package/docs/ja/specdojo/index.md +2 -2
  164. package/docs/ja/specdojo/philosophy/specdojo-philosophy.md +5 -5
  165. package/docs/ja/specdojo/recipes/bps-recipe.md +213 -0
  166. package/docs/ja/specdojo/recipes/pm-members-recipe.md +52 -117
  167. package/docs/ja/specdojo/references/command-reference.md +335 -92
  168. package/docs/ja/specdojo/references/deliverables-reference.md +1 -1
  169. package/docs/ja/specdojo/references/directory-layout-reference.md +13 -9
  170. package/docs/ja/specdojo/references/specdojo-config-reference.md +107 -24
  171. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +132 -220
  172. package/docs/ja/specdojo/rulebooks/br-rulebook.md +6 -44
  173. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +2 -0
  174. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +0 -87
  175. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +61 -39
  176. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +0 -87
  177. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +1 -33
  178. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +0 -137
  179. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +0 -247
  180. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +0 -83
  181. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +4 -2
  182. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +78 -150
  183. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +5 -4
  184. package/docs/ja/specdojo/rulebooks/sch-rulebook.md +1 -1
  185. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +0 -11
  186. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +0 -61
  187. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +2 -47
  188. package/docs/ja/specdojo/samples/bps-sample.md +74 -21
  189. package/docs/ja/specdojo/samples/gl-sample.yaml +17 -1
  190. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +28 -0
  191. package/docs/ja/specdojo/samples/pm-members-sample.yaml +2 -67
  192. package/docs/ja/specdojo/samples/pm-organization-sample.md +8 -7
  193. package/docs/ja/specdojo/samples/pm-raci-sample.md +1 -1
  194. package/docs/ja/specdojo/samples/tml-sample.yaml +40 -0
  195. package/docs/ja/specdojo/standards/document-metadata-standard.md +21 -16
  196. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +14 -14
  197. package/docs/ja/specdojo/standards/job-definition-standard.md +37 -17
  198. package/docs/ja/specdojo/standards/people-and-organization-definition-standard.md +37 -32
  199. package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -1
  200. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +21 -11
  201. package/docs/ja/specdojo/templates/agent-members-template.yaml +25 -0
  202. package/docs/ja/specdojo/templates/bps-template.md +91 -0
  203. package/docs/ja/specdojo/templates/pm-members-template.yaml +2 -59
  204. package/docs/specdojo/schemas/v1/agent-members.schema.yaml +76 -0
  205. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +4 -2
  206. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +55 -2
  207. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +93 -6
  208. package/docs/specdojo/schemas/v1/exec-reporter-output.schema.yaml +27 -78
  209. package/docs/specdojo/schemas/v1/gl.schema.yaml +87 -0
  210. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +33 -0
  211. package/docs/specdojo/schemas/v1/job-run.schema.yaml +27 -0
  212. package/docs/specdojo/schemas/v1/job.schema.yaml +25 -0
  213. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +49 -1
  214. package/docs/specdojo/schemas/v1/pm-members.schema.yaml +9 -169
  215. package/docs/specdojo/schemas/v1/pm-review-viewpoints.schema.yaml +100 -10
  216. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +13 -0
  217. package/docs/specdojo/schemas/v1/routine-run.schema.yaml +3 -0
  218. package/docs/specdojo/schemas/v1/routine.schema.yaml +7 -0
  219. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +110 -0
  220. package/package.json +17 -12
  221. package/templates/antigravity/README.md +29 -4
  222. package/templates/antigravity/{pm-members-snippet.yaml → agent-members-snippet.yaml} +8 -2
  223. package/templates/antigravity/exec-defaults-snippet.yaml +10 -7
  224. package/templates/antigravity/orchestrator.md +18 -7
  225. package/templates/antigravity/settings.global.json +55 -0
  226. package/templates/claude/agents/claude-executor.md +14 -0
  227. package/templates/claude/agents/claude-reporter.md +16 -0
  228. package/templates/claude/agents/specdojo-orchestrator.md +18 -7
  229. package/templates/claude/settings.edit.json +27 -1
  230. package/templates/codex/README.md +5 -4
  231. package/templates/codex/agents/specdojo-orchestrator.toml +18 -7
  232. package/templates/codex/orchestrator.md +18 -7
  233. package/templates/copilot/README.md +7 -5
  234. package/templates/copilot/{pm-members-snippet.yaml → agent-members-snippet.yaml} +4 -2
  235. package/templates/devcontainer/devcontainer.json +27 -0
  236. package/templates/devcontainer/emacs/init.el +88 -0
  237. package/templates/devcontainer/post-create.sh +62 -0
  238. package/templates/init-agent-members.yaml +200 -0
  239. package/templates/init-exec-defaults.yaml +74 -0
  240. package/templates/opencode/agents/specdojo-orchestrator.md +18 -7
  241. package/docs/ja/specdojo/exec-templates/xrp-viewpoint-detail-template.md +0 -7
  242. package/docs/ja/specdojo/exec-templates/xrr-viewpoint-detail-template.md +0 -7
@@ -8,32 +8,32 @@ specdojo:
8
8
  - specdojo:docs-structure-guide
9
9
  ---
10
10
 
11
- # 実践体系構成ガイド
11
+ # 型の構成ガイド
12
12
 
13
- Practice System Composition Guide
13
+ Kata Composition Guide
14
14
 
15
- SpecDojo の実践体系(成果物の作成を支援する文書群)が、どの種別で構成され、各種別がどんな役割を持ち、成果物とどう結びつくかを示します。実践体系の全体像を記述する正本です。
15
+ SpecDojo の型(Kata、成果物の作成を支援する文書群)が、どの種別で構成され、各種別がどんな役割を持ち、成果物とどう結びつくかを示します。型の全体像を記述する正本です。
16
16
 
17
17
  **対象読者**
18
18
 
19
- - 実践体系の全体像を把握したい利用者、支援文書を設計・保守する作成者、エージェント
19
+ - 型の全体像を把握したい利用者、支援文書を設計・保守する作成者、エージェント
20
20
 
21
21
  **この文書で分かること**
22
22
 
23
- - 実践体系を構成する8種別の役割、種別間の関係、成果物への紐付け(解決の仕組み)
23
+ - 型を構成する8種別の役割、種別間の関係、成果物への紐付け(解決の仕組み)
24
24
 
25
25
  **次に読む文書**
26
26
 
27
27
  - `approach` に応じた rulebook / recipe / sample / template の参照方法は [実践の進め方ガイド](ryu-guide.md) を参照してください。
28
28
  - 文書の分類・ライフサイクル・配置は [ドキュメント構成ガイド](docs-structure-guide.md) を参照してください。
29
29
 
30
- ## 1. 実践体系とは
30
+ ## 1. 型とは
31
31
 
32
- SpecDojo は、成果物(プロダクトとプロジェクトの内容そのもの)と、その作成を支援する文書群を分けて管理します。後者を実践体系と呼びます。
32
+ SpecDojo は、成果物(プロダクトとプロジェクトの内容そのもの)と、その作成を支援する文書群を分けて管理します。後者を型(Kata)と呼びます。
33
33
 
34
- 実践体系は成果物を再掲するものではなく、成果物を「なぜ・何を・どう書くか」を支える別の役割を担います。本書は実践体系の構成の正本であり、[全体概要ガイド](specdojo-overview-guide.md) の `実践体系の役割` は本書の概要にあたります。
34
+ 型は成果物を再掲するものではなく、成果物を「なぜ・何を・どう書くか」を支える別の役割を担います。本書は型の構成の正本であり、[全体概要ガイド](specdojo-overview-guide.md) の `型の役割` は本書の概要にあたります。
35
35
 
36
- npm package が所有する実践体系文書は、package ごとの authority を ID に付けます。SpecDojo core は `specdojo:`、業界固有の variant package は `construction-dojo:` などを使用します。authority は論理IDにだけ含め、ファイル名には含めません。利用プロジェクトへコピーした標準文書を override する場合は同じ完全IDを維持し、独自文書を追加する場合は別IDを付けます。
36
+ npm package が所有する型の文書は、package ごとの authority を ID に付けます。SpecDojo core は `specdojo:`、業界固有の variant package は `construction-dojo:` などを使用します。authority は論理IDにだけ含め、ファイル名には含めません。利用プロジェクトへコピーした標準文書を override する場合は同じ完全IDを維持し、独自文書を追加する場合は別IDを付けます。
37
37
 
38
38
  ### 1.1. npm package からの参照と eject
39
39
 
@@ -45,7 +45,7 @@ package の探索では `node_modules` 全体を再帰走査せず、resolver
45
45
 
46
46
  ## 2. 種別と役割
47
47
 
48
- 実践体系は次の8種類の文書で構成されます。各種別は同じ内容を再掲するのではなく、それぞれ異なる問いに答えます。
48
+ 型は次の8種類の文書で構成されます。各種別は同じ内容を再掲するのではなく、それぞれ異なる問いに答えます。
49
49
 
50
50
  | 種別 | 答える問い | 使い方 |
51
51
  | ---------- | ---------------------------------------- | ---------------------------------------------- |
@@ -85,7 +85,7 @@ flowchart TB
85
85
  RB -->|frontmatterで宣言| TPL
86
86
  ```
87
87
 
88
- | 実践体系 | 成果物との紐付け方 | 例 |
88
+ | 型の種別 | 成果物との紐付け方 | 例 |
89
89
  | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
90
90
  | philosophy | standard / rulebook が前提とする方針・概念。個別成果物への直接の紐付けはない | specdojo:needs-to-implementation-philosophy |
91
91
  | standard | 全成果物・全 rulebook が共通して従う規約。個別成果物への直接の紐付けはない | specdojo:document-metadata-standard |
@@ -99,13 +99,13 @@ flowchart TB
99
99
 
100
100
  ## 4. 実践の型サブセットと活用
101
101
 
102
- exec plan が実行時に参照するのは、実践体系のうち rulebook / recipe / sample / template の4種(実践の型)です。これらをどこまで参照するか(`approach` に応じた参照方針)は [実践の進め方ガイド](ryu-guide.md) を正本とします。
102
+ exec plan が実行時に参照するのは、型のうち rulebook / recipe / sample / template の4種(実践の型)です。これらをどこまで参照するか(`approach` に応じた参照方針)は [実践の進め方ガイド](ryu-guide.md) を正本とします。
103
103
 
104
104
  philosophy / standard は全体に効く前提・共通規約として常に踏まえ、guide / reference は個別成果物に紐づかない横断文書として理解と参照に使います。
105
105
 
106
106
  ## 5. 関連ドキュメント
107
107
 
108
- - [全体概要ガイド](specdojo-overview-guide.md): 実践体系を含む SpecDojo 全体像
108
+ - [全体概要ガイド](specdojo-overview-guide.md): 成果物・型・技を含む SpecDojo 全体像
109
109
  - [実践の進め方ガイド](ryu-guide.md): `approach` に応じた実践の型の参照方法
110
110
  - [ドキュメント構成ガイド](docs-structure-guide.md): 文書の分類、命名、ディレクトリ配置
111
111
  - [ドキュメントメタ情報標準](../standards/document-metadata-standard.md): 各種別の Frontmatter 規約
@@ -9,7 +9,7 @@ specdojo:
9
9
 
10
10
  Quick Start Guide
11
11
 
12
- SpecDojo CLI の初期設定から始め、register で課題と判断を整理し、成果物カタログ、schedule、routine へ展開する基本フローを最短手順で試します。
12
+ SpecDojo CLI の初期設定から始め、register で課題と判断を整理し、成果物カタログ、schedule、routine へ展開する基本フローを最短手順で試します。冒頭の `10分で体験する — 仕様の判断台帳` では、kata や成果物カタログを用意せずに、記帳ひとつから判断を残す流れを先に体験します。
13
13
 
14
14
  **対象読者**
15
15
 
@@ -17,6 +17,7 @@ SpecDojo CLI の初期設定から始め、register で課題と判断を整理
17
17
 
18
18
  **この文書で分かること**
19
19
 
20
+ - question の起票から decision、仕様書の更新、change-request による修正までを記帳する流れ
20
21
  - CLI の初期設定と、register / schedule / routine の使い分け
21
22
  - issue / decision / todo から成果物カタログと Schedule へ展開する手順
22
23
  - npm package の kata を参照し、必要なものだけ eject する方法
@@ -28,29 +29,221 @@ SpecDojo CLI の初期設定から始め、register で課題と判断を整理
28
29
 
29
30
  各コマンドには、設定済みのオーケストレーター(`specdojo-orchestrator`)へチャットで指示する場合の文言を `# チャット:` として併記します。オーケストレーターは指示を対応する `specdojo` サブコマンドへ変換し、状態を変える操作は実行前に内容を提示して承認を求めます。導入先での設定と起動方法は [オーケストレーター運用ガイド](orchestrator-operation-guide.md) を参照してください。`<project-id>` などのプレースホルダは実際の値に読み替えてください。
30
31
 
31
- ## 1. CLIを初期設定する
32
+ ## 1. 10分で体験する — 仕様の判断台帳
32
33
 
33
- 既定では、プロダクトリポジトリ `app1/` の隣に SpecDojo 専用リポジトリ `app1-specdojo/` と worktree 用ディレクトリ `app1-worktrees/` を置く Detached Unit で始めます。
34
+ **記して、形にして、磨き続ける。** SpecDojo は、迷っていることを記帳し、決めたことを仕様書へ書き、後日の変更も同じ台帳に残します。この節では、共通サンプルの「駄菓子屋きぬや 販売管理システム構築」を題材に、次の流れを 10 分ほどで体験します。kata(型)や成果物カタログを事前に用意する必要はありません。
34
35
 
35
36
  ```text
36
- workspace/
37
+ question を起票する(迷っていること)
38
+ -> decision で決める(選択肢・理由・決定)
39
+ -> 仕様書を 1 つ書く(決定を反映する)
40
+ -> 後日 change-request で直す(変更の理由を残す)
41
+ -> 決定ログ・変更要求ログで振り返る
42
+ ```
43
+
44
+ 各手順には、実行するコマンドと、オーケストレーターへの話しかけ方の例(`# チャット:`)を併記します。どちらか一方で進められます。表示された `PJR-XXXX` は、自分の環境で表示された ID に読み替えてください。
45
+
46
+ ### 1.1. 道場を開く(導入と初期設定)
47
+
48
+ プロジェクトリポジトリを作り、SpecDojo を導入して `init` の質問に答えます。
49
+
50
+ ```bash
51
+ mkdir app1-specdojo
52
+ git -C app1-specdojo init
53
+ cd app1-specdojo
54
+ npm init -y
55
+ npm install --save-dev specdojo
56
+ npx specdojo init
57
+ ```
58
+
59
+ この体験では、記帳だけを使う最小構成で答えます。`[]` 内は既定値で、Enter だけで採用されます。
60
+
61
+ ```text
62
+ Project ID [prj-0001]: <- Enter(prj-0001)
63
+ Project name [My Project]: 駄菓子屋きぬや 販売管理システム構築
64
+ Create a project register? [Y/n]: <- Enter(登録簿を作る)
65
+ Your nickname [owner]: owner
66
+ Your display name [Project Owner]: 店主
67
+ Orchestrator providers (...) [codex]: claude <- 使う AI ツールを 1 つ選ぶ
68
+ Delegate work to agents (exec)? [y/N]: <- Enter(実戦は後で設定する)
69
+ Deliverables catalog (none|small|medium|large) [none]: <- Enter(カタログは使わない)
70
+ Create a Dev Container? [y/N]: <- Enter
71
+ ```
72
+
73
+ 登録簿は `docs/ja/projects/prj-0001/controls/project-register/` に作られます。オーケストレーターで進める場合は、終了時に表示される `npm run orch:<provider>` で起動します。
74
+
75
+ ### 1.2. 迷っていることを起票する(question)
76
+
77
+ レジで扱う支払い方法が決まっていない、という迷いを question として起票します。
78
+
79
+ ```bash
80
+ # チャット:「question を起票して。タイトルは『支払い方法をどこまで扱うか』」
81
+ npx specdojo register add \
82
+ --project prj-0001 \
83
+ --type question \
84
+ --title "支払い方法をどこまで扱うか" \
85
+ --topic payment-scope
86
+ ```
87
+
88
+ 出力に表示された `PJR-XXXX` を控えます。`controls/project-register/` に `pjr-xxxx-payment-scope.md` という個票ができるので開き、`確認事項` と `背景` に「現金のほか、常連客のつけやキャッシュレスまで扱うか」「つけの記録漏れが問題になっている」などを書きます。個票の章立ては question の型(テンプレート)から与えられます。
89
+
90
+ ### 1.3. decisionで決める
91
+
92
+ 選択肢と理由を比べて決めるために、decision を起票します。
93
+
94
+ ```bash
95
+ # チャット:「decision を起票して。タイトルは『初期リリースで扱う支払い方法を決める』」
96
+ npx specdojo register add \
97
+ --project prj-0001 \
98
+ --type decision \
99
+ --title "初期リリースで扱う支払い方法を決める" \
100
+ --topic payment-methods
101
+ ```
102
+
103
+ decision の個票に、次のように書きます。オーケストレーターを使う場合は、相談した内容がそのまま個票の本文になります。
104
+
105
+ - `検討した選択肢`: A 現金のみ、B 現金とつけ、C 現金とつけとキャッシュレス
106
+ - `決定内容`: B 現金とつけを扱う
107
+ - `採択理由`: つけの記録漏れが現在の主な問題であり、キャッシュレスは利用者が少ない
108
+
109
+ 書き終えたら、decision と、元の question を close します。decision と question は close すると `decided` になります。
110
+
111
+ ```bash
112
+ # チャット:「decision PJR-XXXX を『現金とつけを扱う』で完了して」
113
+ npx specdojo register close \
114
+ --project prj-0001 \
115
+ --id PJR-XXXX \
116
+ --conclusion "初期リリースは現金とつけを扱う"
117
+
118
+ # チャット:「question PJR-XXXX を『decision で決定』で完了して」
119
+ npx specdojo register close \
120
+ --project prj-0001 \
121
+ --id PJR-XXXX \
122
+ --conclusion "decision で現金とつけを扱うと決定"
123
+ ```
124
+
125
+ ### 1.4. 決めたことを仕様書に書く
126
+
127
+ 決定を仕様書へ反映します。この体験では成果物カタログを使わず、Markdown を 1 つ作ります。仕様書はプロダクトの文書なので、プロダクトリポジトリ(例: `app1/docs/ja/product/payment-policy.md`)に置きます。
128
+
129
+ ```markdown
130
+ # 支払い方法の基本方針
131
+
132
+ ## 1. 扱う支払い方法
133
+
134
+ - 現金
135
+ - つけ(常連客のみ。会計時に残高を記録する)
136
+
137
+ ## 2. 根拠
138
+
139
+ - decision PJR-XXXX(初期リリースで扱う支払い方法を決める)
140
+ ```
141
+
142
+ 仕様書から decision の ID を参照しておくと、「なぜこう書いたか」を後から台帳でたどれます。
143
+
144
+ ### 1.5. 後日の変更をchange-requestで直す
145
+
146
+ 運用を始めた後、「子ども向けに交通系電子マネーも使いたい」という要望が出たとします。仕様書をいきなり書き換えず、change-request として記帳します。
147
+
148
+ ```bash
149
+ # チャット:「change-request を起票して。タイトルは『交通系電子マネーを支払い方法に加える』」
150
+ npx specdojo register add \
151
+ --project prj-0001 \
152
+ --type change-request \
153
+ --title "交通系電子マネーを支払い方法に加える" \
154
+ --topic add-ic-card-payment
155
+ ```
156
+
157
+ change-request の個票に `変更要求`、`影響評価`、`審査・決定` を書き、仕様書 `payment-policy.md` の扱う支払い方法へ「交通系電子マネー」を追加して、根拠に change-request の ID を加えます。直し終えたら close します。change-request は close すると `done` になります。
158
+
159
+ ```bash
160
+ # チャット:「change-request PJR-XXXX を『仕様書へ反映』で完了して」
161
+ npx specdojo register close \
162
+ --project prj-0001 \
163
+ --id PJR-XXXX \
164
+ --conclusion "交通系電子マネーを支払い方法の基本方針へ追加"
165
+ ```
166
+
167
+ ### 1.6. 台帳を確かめる
168
+
169
+ 記帳のたびに、個票から一覧とログが生成されます。手動で作り直す場合は `register build` を実行します。
170
+
171
+ ```bash
172
+ # チャット:「登録簿の一覧とログを作り直して」
173
+ npx specdojo register build --project prj-0001
174
+ ```
175
+
176
+ | 生成物 | 内容 |
177
+ | -------------------------------------------------- | --------------------------------------------- |
178
+ | `controls/project-register/generated/pjr-index.md` | question・decision・change-request を含む全件 |
179
+ | `controls/generated/pm-decision-log.md` | 決定ログ(decision の一覧) |
180
+ | `controls/generated/pm-change-request-log.md` | 変更要求ログ(change-request の一覧) |
181
+ | `controls/generated/pm-issue-log.md` | 課題ログ(issue の一覧) |
182
+
183
+ パスは `docs/ja/projects/prj-0001/` からの相対です。正本は個票の Markdown なので、`git log` でも SpecDojo なしでも読めます。作成された設定・個票・仕様書を確認して commit すれば、体験は完了です。
184
+
185
+ ### 1.7. 次に進む
186
+
187
+ - 型と実戦: 仕様書を増やしたくなったら、成果物カタログ(`dct-<domain>.yaml`)で作る成果物を宣言し、型に沿って作ります。手順は以降の `CLIを初期設定する` と `成果物カタログからscheduleへ展開する` を参照してください。
188
+ - 実戦(exec): 起票した todo や issue を AI に実行させるには、[exec設定ガイド](exec-config-guide.md) で agent を設定し、`npx specdojo exec run --project prj-0001 --register PJR-XXXX` を実行します。
189
+ - 評定(grade)と講評(review): 成果物の品質評価と完了判断は [レビューガイド](review-guide.md) を参照してください。v0.3.0 の grade は試験的で、npm package では `grade list` / `plan` / `apply` / `validate` / `result` などの部品を利用できます。通しの実行に使う本体リポジトリの開発用 `tools/grade/run-per-document.sh` は package に含まれず、成果物の grade には project の `catalog_path` が必要です。
190
+ - 記帳の種別と状態遷移は [登録簿運用ガイド](register-operation-guide.md) を参照してください。
191
+
192
+ ## 2. CLIを初期設定する
193
+
194
+ 既定では、SpecDojo の成果物更新、登録簿の状態遷移、実行記録をプロダクトの Git 履歴に混ぜないため、次の **別リポジトリ構成**で始めます。
195
+
196
+ - **プロダクトリポジトリ** `app1/`: ソースコードと、仕様・設計などのプロダクトドキュメントを置きます。
197
+ - **プロジェクトリポジトリ** `app1-specdojo/`: 登録簿・計画・実行記録などのプロジェクトドキュメントと型(Kata)を置きます。1つのプロジェクトリポジトリに、複数のプロジェクトを格納できます。
198
+ - **worktree 用ディレクトリ** `app1-specdojo-worktrees/`: タスクごとの変更を隔離して進めるために、Git worktree を作る場所です。名前はプロジェクトリポジトリのディレクトリ名から決まります。
199
+
200
+ ```text
201
+ app1-workspace/
37
202
  ├── app1/ # 既存または新規のプロダクトリポジトリ
38
- ├── app1-specdojo/ # SpecDojo のプロジェクト文書と運用記録
39
- └── app1-worktrees/ # task 単位の worktree 置き場
203
+ ├── app1-specdojo/ # プロジェクトリポジトリ
204
+ └── app1-specdojo-worktrees/ # task 単位の worktree 置き場
40
205
  ```
41
206
 
42
- workspace 直下で専用リポジトリと worktree 用ディレクトリを作成し、`app1-specdojo/` に依存パッケージと SpecDojo の設定ファイルを用意します。
207
+ `app1-workspace/` 直下でプロジェクトリポジトリと worktree 用ディレクトリを作成し、`app1-specdojo/` に依存パッケージと SpecDojo の設定ファイルを用意します。
43
208
 
44
209
  ```bash
45
- mkdir app1-specdojo app1-worktrees
210
+ mkdir app1-specdojo
46
211
  git -C app1-specdojo init
47
212
  cd app1-specdojo
48
213
  npm init -y
49
214
  npm install --save-dev specdojo @specdojo/docs-lint
50
- # チャット:「<project-id> の SpecDojo 設定を初期化して」
51
- npx specdojo config init
215
+ # 質問に答えて project、register、agent 実行までを初期設定する
216
+ npx specdojo init
52
217
  ```
53
218
 
219
+ `specdojo init` は、project ID と名前、人の nickname と表示名、利用する agent provider、
220
+ exec・成果物カタログ・Dev Container の要否を順に質問します。選択に応じて設定、登録簿、人と
221
+ agent の名簿、provider の scaffold、`package.json` の `orch:<provider>`、exec の起動設定を
222
+ 作成します。exec の親検証は、対応する npm script が `package.json` にあるものだけを設定し、
223
+ 該当する script がなければ省略します。既存ファイルは上書きせず、作成内容は `--dry-run` で
224
+ 先に確認できます。
225
+
226
+ CI や標準入力が端末でない環境では質問しません。次のようにオプションだけで同じ初期設定を
227
+ 行えます。省略値は画面に表示されます。
228
+
229
+ ```bash
230
+ npx specdojo init --yes \
231
+ --project prj-0001 \
232
+ --name "Example Project" \
233
+ --nickname owner \
234
+ --display-name "Project Owner" \
235
+ --provider claude,codex \
236
+ --exec \
237
+ --catalog small \
238
+ --devcontainer \
239
+ --dry-run
240
+ ```
241
+
242
+ 初期化後は、表示された `npm run orch:<provider>` でオーケストレーターを起動し、最初の 1 件を
243
+ 起票します。オーケストレーターを使わない場合は、同じ案内に表示される
244
+ `exec run --register <id> --executor-by <executor> --reporter-by <reporter>` で実行できます。
245
+ 作成された設定と文書は内容を確認して commit してください。
246
+
54
247
  `@specdojo/docs-lint` は SpecDojo 文書向けの remark プラグインと検証コマンドを提供します。
55
248
  最小構成では、リポジトリルートの `.remarkrc.yaml` から次のように公開 export を参照できます。
56
249
 
@@ -62,11 +255,20 @@ plugins:
62
255
 
63
256
  文書 lint の全設定例と検証コマンドは [[specdojo:docs-editing-guide|ドキュメント編集ガイド]] を参照してください。
64
257
 
65
- `specdojo config init` は `.specdojo/specdojo.config.json` が存在しない場合に雛形を作成し、既存ファイルは上書きしません。雛形は register だけを使える最小構成であり、project パスは `app1-specdojo/` のリポジトリルートを基準とし、`run.worktree_base` は兄弟ディレクトリの `../app1-worktrees` を指します。作成された設定を開き、対象プロジェクトの ID と各パスを実際の名前に合わせてください。catalog、schedule、exec へ進むときに追加するキーと既定値は [[specdojo:specdojo-config-reference|SpecDojo設定リファレンス]] で確認できます。
258
+ ### 2.1. 個別に設定する場合
66
259
 
67
- プロダクト文書は `app1/docs/ja/product/`、プロジェクト文書と SpecDojo の実践体系は `app1-specdojo/docs/ja/projects/` と `app1-specdojo/docs/ja/specdojo/` に置きます。現行実装では1つの項目で両リポジトリを自動統合できないため、プロダクト文書や実装も変更する項目は分けるか、人が統合を管理します。詳細は [ドキュメント構成ガイド](docs-structure-guide.md) の `別リポジトリ構成(Detached Unit)` を参照してください。
260
+ 各設定を個別に管理したい場合は、従来どおり `config init` と各 scaffold を順に実行できます。
68
261
 
69
- 成果物と実装を常に同じ変更・履歴として扱う場合に限り、Attached Unit としてプロダクトリポジトリのルートで同じ初期化手順を実行できます。CLI は構成を強制しません。
262
+ ```bash
263
+ # チャット:「<project-id> の SpecDojo 設定を初期化して」
264
+ npx specdojo config init
265
+ ```
266
+
267
+ `specdojo config init` は `.specdojo/specdojo.config.json` が存在しない場合に雛形を作成し、既存ファイルは上書きしません。雛形は register だけを使える最小構成であり、project パスはリポジトリルートを基準とし、`run.worktree_base` はディレクトリ名から作る `../<リポジトリ名>-worktrees` を指します。例えば `app1-specdojo/` では `../app1-specdojo-worktrees` です。作成された設定を開き、対象プロジェクトの ID と各パスを実際の名前に合わせてください。catalog、schedule、exec へ進むときに追加するキーと既定値は [[specdojo:specdojo-config-reference|SpecDojo設定リファレンス]] で確認できます。
268
+
269
+ プロダクト文書は `app1/docs/ja/product/`、プロジェクト文書と SpecDojo の型(Kata)は `app1-specdojo/docs/ja/projects/` と `app1-specdojo/docs/ja/specdojo/` に置きます。現行実装では1つの項目で両リポジトリを自動統合できないため、プロダクト文書や実装も変更する項目は分けるか、人が統合を管理します。詳細は [ドキュメント構成ガイド](docs-structure-guide.md) の `別リポジトリ構成` を参照してください。
270
+
271
+ 成果物と実装を常に同じ変更・履歴として扱う場合に限り、**同一リポジトリ構成**としてプロダクトリポジトリのルートで同じ初期化手順を実行できます。CLI は構成を強制しません。
70
272
 
71
273
  agent を使う場合は、設定ファイルを確認した後で利用する provider の設定を配置します。register
72
274
  だけを使う最小構成では、この手順を省略できます。
@@ -75,9 +277,25 @@ agent を使う場合は、設定ファイルを確認した後で利用する p
75
277
  npx specdojo config scaffold --provider <name>
76
278
  ```
77
279
 
78
- `<name>` には `claude`、`codex`、`copilot`、`opencode` を指定します。従来の
280
+ `<name>` には `antigravity`、`claude`、`codex`、`copilot`、`opencode` を指定します。従来の
79
281
  `specdojo exec scaffold --provider <name>` も互換入口として利用できます。
80
282
 
283
+ Antigravity CLI を無人実行する場合は、先に dry-run でユーザー設定へ追加する permission rule を確認し、明示的に適用します。このグローバル設定は利用者のすべてのリポジトリに効きます。通常の scaffold はユーザーディレクトリへ触れません。
284
+
285
+ ```bash
286
+ npx specdojo config scaffold --provider antigravity --global --dry-run
287
+ npx specdojo config scaffold --provider antigravity --global
288
+ ```
289
+
290
+ Dev Container は任意です。分離された環境が必要な場合だけ、既存の `.devcontainer/` がないことと生成内容を dry-run で確認してから作成します。
291
+
292
+ ```bash
293
+ npx specdojo devcontainer scaffold --provider <name> --dry-run
294
+ npx specdojo devcontainer scaffold --provider <name>
295
+ ```
296
+
297
+ Dev Container の `<name>` には `antigravity`、`claude`、`codex`、`opencode` を指定します。既存の `.devcontainer/` は通常実行では上書きされません。生成設定は provider の設定ディレクトリを名前付きボリュームに保存し、ホストの認証情報・秘密鍵・`.env` はマウントしません。Ollama 接続、cron、tmux は必要な場合だけ `--ollama`、`--cron`、`--tmux` で追加します。
298
+
81
299
  設定したプロジェクトを確認します。
82
300
 
83
301
  ```bash
@@ -87,9 +305,9 @@ npx specdojo project list
87
305
 
88
306
  以降の例では、対象プロジェクトを `<project-id>` と表記します。`current_project` を設定している場合も、最初は対象を確認しやすいように `--project` を明示します。
89
307
 
90
- このガイドの基本手順は、provider 未設定でも完了できるように人が作業する経路を使います。agent に実行させる箇所は、`pm-members.yaml` と provider を [exec設定ガイド](exec-config-guide.md) に従って設定した後に試してください。
308
+ このガイドの基本手順は、exec 未設定でも完了できるように人が作業する経路を使います。agent に実行させる箇所は、`specdojo init --exec` で設定するか、`.specdojo/agent-members.yaml` と provider を [exec設定ガイド](exec-config-guide.md) に従って個別に設定した後に試してください。
91
309
 
92
- ### 1.1. kataの参照元を確認する
310
+ ### 2.2. kataの参照元を確認する
93
311
 
94
312
  rulebook、standard、recipe、sample、template は、利用リポジトリに同じ ID のファイルがあればそれを優先し、無ければ npm package 内を参照します。初期導入時に kata 一式をコピーする必要はありません。
95
313
 
@@ -110,7 +328,7 @@ npx specdojo kata status --kind rulebook
110
328
 
111
329
  CLI と同じバージョンで使う `exec-template` と `schema` は npm package 参照固定であり、eject できません。`kata install --all` は docs サイト配信やオフライン運用で全量コピーするときの選択肢で、通常の導入では実行しません。
112
330
 
113
- ## 2. registerで課題と判断を整理する
331
+ ## 3. registerで課題と判断を整理する
114
332
 
115
333
  プロジェクトの開始時点では、解決すべき問題、判断が必要な事項、実施する作業が混在しています。まず register に個票として記録し、issue → decision → todo の順に具体化します。
116
334
 
@@ -122,7 +340,7 @@ issue(何が問題か)
122
340
  -> schedule
123
341
  ```
124
342
 
125
- ### 2.1. 登録簿を用意する
343
+ ### 3.1. 登録簿を用意する
126
344
 
127
345
  `.specdojo/specdojo.config.json` の `project_register_path` を設定し、登録簿を初期生成します。
128
346
 
@@ -131,7 +349,7 @@ issue(何が問題か)
131
349
  npx specdojo register scaffold --project <project-id>
132
350
  ```
133
351
 
134
- ### 2.2. issue、decision、todoを登録する
352
+ ### 3.2. issue、decision、todoを登録する
135
353
 
136
354
  次の例では、初期スコープと必要な成果物が未確定な状態から、成果物カタログを作成する作業までを3つの個票で追跡します。コマンドはまとめて示していますが、実運用では issue の調査結果を受けて decision を起票し、決定後に todo を起票します。
137
355
 
@@ -164,13 +382,15 @@ npx specdojo register add \
164
382
 
165
383
  `register add` の出力に表示された `PJR-XXXX` を控えます。すべての登録項目は、背景、選択肢、完了条件、結論などを記録する type 別の個票として生成されます。個票 Frontmatter が構造化フィールドの正本であり、一覧は個票から生成されます。成果物カタログを複数ドメインに分ける場合は、原則として `dct-<domain>.yaml` ごとに todo 個票を起票すると、対象と完了条件を追跡しやすくなります。
166
384
 
385
+ agent の run と並行して記帳し、その変更だけを commit まで完了させる場合は `register add` や状態遷移コマンドへ `--commit` を付けます。同じ project の `register lifecycle` 枠が空くまで待って記帳・一覧再生成・commit を行うため、別の run の記帳・統合と競合しません。対象の個票や event に既存の未 commit 変更がある場合は、混在を避けるため書き込み前に停止します。
386
+
167
387
  | type | 記録する内容 | 完了状態 | agent実行 |
168
388
  | ---------- | -------------------------------------- | --------- | ------------------------------------------ |
169
389
  | `issue` | 発生している問題、影響、原因、対応結果 | `done` | `exec run --register` で対応できる |
170
390
  | `decision` | 判断の背景、選択肢、決定内容、決定理由 | `decided` | 対象外。人が判断して `register close` する |
171
391
  | `todo` | 実施内容、完了条件、作業結果 | `done` | `exec run --register` で対応できる |
172
392
 
173
- ### 2.3. 判断を確定してカタログ作成へ進む
393
+ ### 3.3. 判断を確定してカタログ作成へ進む
174
394
 
175
395
  issue に人が着手し、個票へ問題、影響、原因、対応方針を記入して完了させます。
176
396
 
@@ -216,13 +436,13 @@ agent 設定が完了している場合は、同じ登録項目を実行でき
216
436
  npx specdojo exec run --project <project-id> --register <issue-or-todo-id>
217
437
  ```
218
438
 
219
- 個票内の `_TODO_` を解消してから `register close` すると、個票の文書状態も `ready` になります。基本手順では、成果物カタログ作成の todo を `open` のまま残し、次章で `dct-<domain>.yaml` を作成・検証した後に完了させます。登録簿は立ち上げ時の課題・判断・作業履歴、成果物カタログは合意後の管理対象成果物の正本です。同じ計画済み作業を register と schedule の両方で継続管理しません。
439
+ 個票内の `_TODO_` を解消してから `register close` すると、個票の文書状態も `ready` になります。基本手順では、成果物カタログ作成の todo を `open` のまま残し、`成果物カタログからscheduleへ展開する` で `dct-<domain>.yaml` を作成・検証した後に完了させます。登録簿は立ち上げ時の課題・判断・作業履歴、成果物カタログは合意後の管理対象成果物の正本です。同じ計画済み作業を register と schedule の両方で継続管理しません。
220
440
 
221
- ## 3. 成果物カタログからscheduleへ展開する
441
+ ## 4. 成果物カタログからscheduleへ展開する
222
442
 
223
443
  この経路では、成果物カタログ(`dct-<domain>.yaml`)とトラック戦略(`sch-strategy-<track>.yaml`)から Schedule を生成し、依存関係に従ってタスクを実行します。
224
444
 
225
- ### 3.1. 成果物カタログを作成する
445
+ ### 4.1. 成果物カタログを作成する
226
446
 
227
447
  成果物カタログは「何を、どこに作り、何を満たせば完了か」を定義する `dct-<domain>.yaml` です。`.specdojo/specdojo.config.json` の対象 project へ、たとえば `"catalog_path": "010-deliverables-catalog"` を追加してから次の順に実行します。パスの基準と後続の設定キーは [[specdojo:specdojo-config-reference|SpecDojo設定リファレンス]] を参照してください。
228
448
 
@@ -262,7 +482,7 @@ npx specdojo register close \
262
482
 
263
483
  `--size` には `small` / `medium` / `large` を指定します。`catalog scaffold` 後は、生成された全成果物をそのまま採用するのではなく、プロジェクトのスコープに合わせて `dct-*.yaml` の成果物、依存関係、完了条件を確認してください。
264
484
 
265
- ### 3.2. トラック戦略を作成する
485
+ ### 4.2. トラック戦略を作成する
266
486
 
267
487
  `sch-strategy-<track>.yaml` は、成果物カタログを実行タスクへ展開するための生成入力です。成果物カタログが WHAT / DONE を持つのに対し、strategy は対象カタログ、作業フェーズ、担当ロールを定義します。新規 strategy は DCT・Timeline・整備状況判定から `schedule strategy generate` で作成し、既存 strategy の owner や開始日などの人間が決めた項目は再生成時も保持します。
268
488
 
@@ -284,7 +504,7 @@ members:
284
504
 
285
505
  </details>
286
506
 
287
- 先に `sch-strategy-launch.yaml` の `approach_rules` へ成果物ごとの intent を宣言し、必要な Kata を `specdojo grade` で評価します。次のコマンドで strategy の差分を確認して生成します。`<role>` は `pm-roles.yaml` に定義された主担当ロールへ置き換えてください。
507
+ 先に `sch-strategy-launch.yaml` の `approach_rules` へ成果物ごとの intent を宣言し、必要な Kata を `specdojo grade` で評価します。v0.3.0 の npm package では grade の通しの実行は提供せず、試験的な `grade plan` / `agent run` / `grade apply` などの部品を組み合わせます。1 文書の手順は [CLI コマンドリファレンス](../references/command-reference.md#81-npm-package-で-1-文書を評価する)を参照してください。次のコマンドで strategy の差分を確認して生成します。`<role>` は `pm-roles.yaml` に定義された主担当ロールへ置き換えてください。
288
508
 
289
509
  ```bash
290
510
  npx specdojo schedule strategy generate --project <project-id> --track launch \
@@ -350,7 +570,7 @@ owner_rules:
350
570
 
351
571
  `owner_rules.owner` は `pm-members.yaml` の `roles` と対応させます。複数フェーズ、反復、レビュー、成果物間のゲートを含む実運用向けの設計は [Schedule設計ガイド](schedule-design-guide.md)、トラックの選び方は [トラック設計ガイド](track-design-guide.md) を参照してください。
352
572
 
353
- ### 3.3. Scheduleを生成する
573
+ ### 4.3. Scheduleを生成する
354
574
 
355
575
  ```bash
356
576
  # チャット:「<track> トラックの schedule を生成して」
@@ -363,7 +583,7 @@ npx specdojo exec refresh --project <project-id>
363
583
 
364
584
  `schedule build` は strategy と対象カタログから、実行対象となる `sch-track-<track>.yaml` を生成します。`exec refresh` はそこから Ready タスク、CPM、タイムラインなどを生成します。
365
585
 
366
- ### 3.4. 1タスクを実行する
586
+ ### 4.4. 1タスクを実行する
367
587
 
368
588
  次のタスクを確認して claim します。`execution: human` のタスクは agent を起動せず、claim 時に確認用resultを生成します。人が成果物とresultを編集してから完了を記録します。
369
589
 
@@ -389,11 +609,21 @@ npx specdojo exec refresh --project <project-id>
389
609
 
390
610
  成果物の変更は作業ツリーに、実行結果は `<execution_path>/exec/results/` に記録されます。agent による自動実行や並列実行へ進む場合は、[exec設定ガイド](exec-config-guide.md) で設定してから [Schedule実行運用ガイド](schedule-operation-guide.md) を参照してください。
391
611
 
612
+ `mode: review` のタスクを実行すると、runner は review plan の生成前に対象成果物を grade します。ただし、この自動 grade は npm package に含まれない本体リポジトリ開発用の `tools/grade/run-per-document.sh` を使うため、v0.3.0 の公開物では実行されません。公開物では、`catalog_path` を設定したうえで grade の部品を使って成果物を事前評価します。grade は成果物の品質を観点ごとに評価し、review はその評価結果を付け直さず、変更内容・実行記録・`done_criteria` を照合してタスクの完了可否を判断します。review result の verdict と finding の読み方、成果物を `ready` にする human finalize との境界は [レビューガイド](review-guide.md) を参照してください。
613
+
614
+ agent に review を実行させる場合は、`exec run --plan` で executor と reporter を指定して 2 段で実行します。
615
+
616
+ ```bash
617
+ # review を 2 段で実行する
618
+ npx specdojo exec run --project <project-id> --plan <execution_path>/exec/plans/<task-id>-plan.md \
619
+ --executor-by <executor-nickname> --reporter-by <reporter-nickname>
620
+ ```
621
+
392
622
  ここまでで、register による立ち上げ整理から、成果物カタログ、Schedule、1タスクの完了までの Quick Start は終了です。以降の worktree 隔離実行と routine は、agent 設定後に試す任意の発展手順です。
393
623
 
394
- ## 4. (発展)worktreeで1タスクを隔離実行する
624
+ ## 5. (発展)worktreeで1タスクを隔離実行する
395
625
 
396
- 前節「1タスクを実行する」は human・in-place の経路でした。agent に成果物を作らせる場合は、変更を git worktree に隔離して実行し、成功時に現在ブランチへ merge back できます。この経路は agent・provider の設定が前提です。先に [exec設定ガイド](exec-config-guide.md) に従って `pm-members.yaml` の agent と `.specdojo/exec-defaults.yaml` を用意し、`execution: agent` のフェーズを持つ strategy で `schedule build` / `exec refresh` まで済ませておきます。
626
+ 前節「1タスクを実行する」は human・in-place の経路でした。agent に成果物を作らせる場合は、変更を git worktree に隔離して実行し、成功時に現在ブランチへ merge back できます。この経路は agent・provider の設定が前提です。先に [exec設定ガイド](exec-config-guide.md) に従って `.specdojo/agent-members.yaml` の agent と `.specdojo/exec-defaults.yaml` を用意し、`execution: agent` のフェーズを持つ strategy で `schedule build` / `exec refresh` まで済ませておきます。
397
627
 
398
628
  対象タスクを worktree に隔離して一括実行します。SpecDojo が worktree 準備・agent 実行・commit・merge・状態更新をまとめて行います。
399
629
 
@@ -412,7 +642,7 @@ npx specdojo exec run --project <project-id> --auto --parallel 5
412
642
 
413
643
  各段階(prepare → agent → commit → merge → remove)を人が確認しながら進める場合は [exec worktree運用ガイド](exec-worktree-guide.md)、project `develop`・feature・exec のブランチ全体運用は [ブランチワークフローガイド](branch-workflow-guide.md)、自動・並列実行の運用は [Schedule実行運用ガイド](schedule-operation-guide.md) を参照してください。
414
644
 
415
- ## 5. routineで定期実行する
645
+ ## 6. routineで定期実行する
416
646
 
417
647
  この経路では、動作確認済みの Job を `rtn-*.yaml` に定義した間隔で起動します。Job は schedule または register のagent実行を決定論的なコマンドで呼び出します。routine は任意の発展手順です。先に [exec設定ガイド](exec-config-guide.md) に従ってagentを設定し、次のような open かつ高優先度のtodoを用意します。
418
648