specdojo 0.6.0 → 0.8.0

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 (366) hide show
  1. package/.github/agents/specdojo-orchestrator.md +3 -2
  2. package/CHANGELOG.md +193 -0
  3. package/README.md +2 -2
  4. package/dist/catalog/build.js +24 -1
  5. package/dist/catalog/plan.js +1 -1
  6. package/dist/catalog/scaffold.js +4 -1
  7. package/dist/commands/agent.js +33 -0
  8. package/dist/commands/init.js +6 -1
  9. package/dist/commands/night-orchestrator.js +6 -4
  10. package/dist/commands/orchestrator.js +10 -1
  11. package/dist/dashboard/dashboard-timeline.js +18 -16
  12. package/dist/dashboard/dashboard.js +612 -259
  13. package/dist/dashboard/epic-plan.js +81 -0
  14. package/dist/dashboard/exec-records.js +16 -20
  15. package/dist/dashboard/routines.js +8 -6
  16. package/dist/dashboard/timeline-build.js +5 -9
  17. package/dist/dashboard/timeline.js +9 -4
  18. package/dist/devcontainer/command.js +18 -0
  19. package/dist/devcontainer/host-script.js +21 -0
  20. package/dist/devcontainer/scaffold.js +22 -3
  21. package/dist/docs/frontmatter-namespace.js +1 -48
  22. package/dist/docs/yaml-pages.js +125 -3
  23. package/dist/exec/agent-config.js +22 -0
  24. package/dist/exec/agent-plan.js +3 -2
  25. package/dist/exec/antigravity-session.js +154 -0
  26. package/dist/exec/commands.js +69 -21
  27. package/dist/exec/commit-hook-skips.js +78 -0
  28. package/dist/exec/core.js +19 -7
  29. package/dist/exec/events.js +159 -8
  30. package/dist/exec/evidence.js +64 -16
  31. package/dist/exec/handoff.js +9 -13
  32. package/dist/exec/limit.js +1 -1
  33. package/dist/exec/mechanical-result.js +45 -0
  34. package/dist/exec/migrate-records.js +249 -0
  35. package/dist/exec/parent-validation.js +160 -12
  36. package/dist/exec/pipeline-state.js +27 -5
  37. package/dist/exec/plan-markdownlint.js +89 -0
  38. package/dist/exec/plans-condense-findings.js +89 -0
  39. package/dist/exec/plans-core.js +24 -17
  40. package/dist/exec/plans-generation.js +52 -25
  41. package/dist/exec/plans-grade-findings.js +8 -3
  42. package/dist/exec/plans-kata-findings.js +61 -0
  43. package/dist/exec/plans-planning.js +3 -3
  44. package/dist/exec/plans-storage.js +12 -24
  45. package/dist/exec/register-resume.js +69 -42
  46. package/dist/exec/register.js +26 -22
  47. package/dist/exec/repo-integration-sync.js +8 -4
  48. package/dist/exec/repo-integration.js +21 -1
  49. package/dist/exec/reporter.js +121 -23
  50. package/dist/exec/results.js +85 -24
  51. package/dist/exec/review-completion.js +47 -0
  52. package/dist/exec/review-kata.js +109 -0
  53. package/dist/exec/run/agent-pipeline.js +75 -6
  54. package/dist/exec/run/agent.js +20 -7
  55. package/dist/exec/run/in-place.js +69 -32
  56. package/dist/exec/run/job.js +81 -24
  57. package/dist/exec/run/lifecycle-commands.js +264 -43
  58. package/dist/exec/run/mode-shared.js +11 -3
  59. package/dist/exec/run/register-command.js +12 -10
  60. package/dist/exec/run/register-core.js +20 -13
  61. package/dist/exec/run/register-mode.js +12 -12
  62. package/dist/exec/run/register-post-review.js +21 -9
  63. package/dist/exec/run/register-resume.js +28 -18
  64. package/dist/exec/run/register-state.js +10 -7
  65. package/dist/exec/run/register-worktree.js +60 -30
  66. package/dist/exec/run/schedule-mode.js +26 -6
  67. package/dist/exec/run/schedule-prepare.js +228 -45
  68. package/dist/exec/run/schedule-task.js +132 -25
  69. package/dist/exec/run/shared.js +4 -3
  70. package/dist/exec/run/trailing-records.js +35 -0
  71. package/dist/exec/run-records.js +2 -0
  72. package/dist/exec/strategy.js +1 -0
  73. package/dist/exec/trailing-records.js +242 -0
  74. package/dist/exec/trial-commands.js +3 -2
  75. package/dist/exec/validate-records-commit.js +110 -0
  76. package/dist/exec/validate-records.js +148 -0
  77. package/dist/exec/worktree-command.js +29 -16
  78. package/dist/exec/worktree-ops-commit.js +118 -59
  79. package/dist/exec/worktree-ops-lifecycle.js +77 -44
  80. package/dist/exec/worktree-ops-merge.js +13 -2
  81. package/dist/exec/worktree-ops.js +2 -2
  82. package/dist/exec/worktree.js +19 -2
  83. package/dist/grade/apply.js +32 -6
  84. package/dist/grade/command-inspect.js +2 -2
  85. package/dist/grade/command-run.js +2 -0
  86. package/dist/grade/command-shared.js +1 -1
  87. package/dist/grade/core.js +18 -5
  88. package/dist/grade/markdown.js +3 -3
  89. package/dist/grade/pipeline-state.js +15 -11
  90. package/dist/grade/plan.js +37 -17
  91. package/dist/grade/result.js +3 -3
  92. package/dist/grade/run.js +23 -3
  93. package/dist/grade/target-discovery.js +17 -4
  94. package/dist/grade/targets.js +12 -11
  95. package/dist/job/job.js +31 -17
  96. package/dist/job/noop.js +104 -0
  97. package/dist/register/core.js +2 -0
  98. package/dist/register/create-commands.js +28 -3
  99. package/dist/register/deliverable-target.js +9 -1
  100. package/dist/register/epic.js +104 -26
  101. package/dist/register/event-merge.js +3 -0
  102. package/dist/register/events.js +4 -0
  103. package/dist/register/external-project.js +3 -0
  104. package/dist/register/item.js +6 -0
  105. package/dist/register/maintenance-commands.js +4 -1
  106. package/dist/register/planning.js +7 -14
  107. package/dist/register/register.js +74 -32
  108. package/dist/register/track-domains.js +34 -0
  109. package/dist/register/track-plan.js +78 -0
  110. package/dist/register/transition-commands.js +8 -0
  111. package/dist/register/work-table.js +64 -0
  112. package/dist/review/grade.js +35 -13
  113. package/dist/routine/definition.js +4 -3
  114. package/dist/routine/failure.js +30 -0
  115. package/dist/routine/routine.js +56 -32
  116. package/dist/routine/storage.js +33 -0
  117. package/dist/schedule/schedule.js +1 -0
  118. package/dist/schedule/strategy-generate-document.js +26 -14
  119. package/dist/schedule/strategy-generate-scope.js +17 -45
  120. package/dist/schedule/strategy-generate.js +33 -3
  121. package/dist/schedule/strategy-profiles.js +86 -12
  122. package/dist/shared/agent-types.js +2 -0
  123. package/dist/shared/condense-records.js +25 -0
  124. package/dist/shared/deprecation.js +8 -0
  125. package/dist/shared/document-metadata.js +20 -0
  126. package/dist/shared/finding-cause.js +20 -0
  127. package/dist/shared/frontmatter-namespace.js +48 -0
  128. package/dist/shared/git.js +149 -15
  129. package/dist/shared/grade-result.js +17 -1
  130. package/dist/shared/local-state.js +20 -0
  131. package/dist/shared/markdownlint-config.js +8 -3
  132. package/dist/shared/plan-conventions.js +129 -0
  133. package/dist/shared/plan-templates.js +57 -41
  134. package/dist/shared/provider-scaffold.js +2 -0
  135. package/dist/shared/run-records.js +224 -0
  136. package/dist/shared/specdojo-config.js +39 -21
  137. package/dist/shared/specdojo-gitignore.js +1 -0
  138. package/dist/shared/text.js +65 -5
  139. package/dist/shared/timeline-index.js +2 -0
  140. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +11 -2
  141. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +4 -74
  142. package/docs/ja/specdojo/exec-templates/xep-condense-template.md +50 -0
  143. package/docs/ja/specdojo/exec-templates/xep-draft-template.md +17 -5
  144. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +16 -3
  145. package/docs/ja/specdojo/exec-templates/xep-recipe-guided-template.md +15 -5
  146. package/docs/ja/specdojo/exec-templates/xep-recipe-maintenance-template.md +6 -0
  147. package/docs/ja/specdojo/exec-templates/xep-register-template.md +1 -1
  148. package/docs/ja/specdojo/exec-templates/xep-rulebook-maintenance-template.md +6 -0
  149. package/docs/ja/specdojo/exec-templates/xep-sample-maintenance-template.md +6 -0
  150. package/docs/ja/specdojo/exec-templates/xep-template-maintenance-template.md +6 -0
  151. package/docs/ja/specdojo/exec-templates/xer-condense-template.md +25 -0
  152. package/docs/ja/specdojo/exec-templates/xp-common-conventions-template.md +50 -0
  153. package/docs/ja/specdojo/exec-templates/xrp-common-conventions-template.md +30 -0
  154. package/docs/ja/specdojo/guides/branch-workflow-guide.md +1 -1
  155. package/docs/ja/specdojo/guides/docs-editing-guide.md +48 -0
  156. package/docs/ja/specdojo/guides/docs-structure-guide.md +48 -15
  157. package/docs/ja/specdojo/guides/exec-config-guide.md +61 -28
  158. package/docs/ja/specdojo/guides/exec-operation-guide.md +61 -13
  159. package/docs/ja/specdojo/guides/exec-worktree-guide.md +20 -11
  160. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +4 -2
  161. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +92 -55
  162. package/docs/ja/specdojo/guides/project-move-guide.md +381 -0
  163. package/docs/ja/specdojo/guides/quick-start-guide.md +589 -807
  164. package/docs/ja/specdojo/guides/register-operation-guide.md +26 -4
  165. package/docs/ja/specdojo/guides/remote-host-development-guide.md +33 -4
  166. package/docs/ja/specdojo/guides/review-guide.md +22 -19
  167. package/docs/ja/specdojo/guides/routine-operation-guide.md +14 -8
  168. package/docs/ja/specdojo/guides/ryu-guide.md +23 -13
  169. package/docs/ja/specdojo/guides/schedule-design-guide.md +7 -4
  170. package/docs/ja/specdojo/guides/schedule-operation-guide.md +41 -3
  171. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +5 -4
  172. package/docs/ja/specdojo/guides/timeline-design-guide.md +27 -144
  173. package/docs/ja/specdojo/guides/use-case-guide.md +471 -74
  174. package/docs/ja/specdojo/recipes/bac-recipe.md +94 -0
  175. package/docs/ja/specdojo/recipes/bes-recipe.md +105 -0
  176. package/docs/ja/specdojo/recipes/br-recipe.md +84 -0
  177. package/docs/ja/specdojo/recipes/cdfd-overview-recipe.md +88 -86
  178. package/docs/ja/specdojo/recipes/cdfd-uc-recipe.md +108 -122
  179. package/docs/ja/specdojo/recipes/cnd-recipe.md +125 -0
  180. package/docs/ja/specdojo/recipes/cpd-recipe.md +126 -0
  181. package/docs/ja/specdojo/recipes/cxd-recipe.md +145 -0
  182. package/docs/ja/specdojo/recipes/ifd-recipe.md +134 -0
  183. package/docs/ja/specdojo/recipes/ifx-cmd-recipe.md +135 -86
  184. package/docs/ja/specdojo/recipes/ifx-index-recipe.md +130 -0
  185. package/docs/ja/specdojo/recipes/pm-organization-recipe.md +29 -26
  186. package/docs/ja/specdojo/recipes/pm-plan-recipe.md +35 -26
  187. package/docs/ja/specdojo/recipes/pm-quality-management-plan-recipe.md +38 -28
  188. package/docs/ja/specdojo/recipes/pm-raci-recipe.md +39 -31
  189. package/docs/ja/specdojo/recipes/pm-roles-recipe.md +26 -28
  190. package/docs/ja/specdojo/recipes/prj-assumptions-constraints-dependencies-recipe.md +10 -8
  191. package/docs/ja/specdojo/recipes/prj-comparison-of-alternatives-recipe.md +18 -17
  192. package/docs/ja/specdojo/recipes/stsd-recipe.md +100 -62
  193. package/docs/ja/specdojo/recipes/sysd-critical-flows-recipe.md +106 -0
  194. package/docs/ja/specdojo/recipes/sysd-cross-cutting-policy-recipe.md +137 -0
  195. package/docs/ja/specdojo/recipes/sysd-index-recipe.md +122 -0
  196. package/docs/ja/specdojo/references/command-reference.md +146 -99
  197. package/docs/ja/specdojo/references/deliverables-reference.md +9 -4
  198. package/docs/ja/specdojo/references/directory-layout-reference.md +3 -2
  199. package/docs/ja/specdojo/references/specdojo-config-reference.md +17 -16
  200. package/docs/ja/specdojo/rulebooks/bac-rulebook.md +72 -290
  201. package/docs/ja/specdojo/rulebooks/bdd-rulebook.md +212 -79
  202. package/docs/ja/specdojo/rulebooks/bds-rulebook.md +138 -154
  203. package/docs/ja/specdojo/rulebooks/bes-index-rulebook.md +147 -59
  204. package/docs/ja/specdojo/rulebooks/bes-rulebook.md +100 -96
  205. package/docs/ja/specdojo/rulebooks/br-rulebook.md +88 -108
  206. package/docs/ja/specdojo/rulebooks/ccd-mermaid-rulebook.md +126 -211
  207. package/docs/ja/specdojo/rulebooks/cdfd-d2-rulebook.md +367 -0
  208. package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +6 -5
  209. package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +96 -100
  210. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +38 -47
  211. package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +132 -106
  212. package/docs/ja/specdojo/rulebooks/cdsd-rulebook.md +102 -68
  213. package/docs/ja/specdojo/rulebooks/cdt-rulebook.md +152 -0
  214. package/docs/ja/specdojo/rulebooks/cld-rulebook.md +9 -184
  215. package/docs/ja/specdojo/rulebooks/clis-rulebook.md +187 -0
  216. package/docs/ja/specdojo/rulebooks/cnd-rulebook.md +93 -247
  217. package/docs/ja/specdojo/rulebooks/cpd-rulebook.md +104 -241
  218. package/docs/ja/specdojo/rulebooks/cxd-rulebook.md +124 -257
  219. package/docs/ja/specdojo/rulebooks/dct-index-rulebook.md +87 -98
  220. package/docs/ja/specdojo/rulebooks/dct-rulebook.md +9 -7
  221. package/docs/ja/specdojo/rulebooks/dec-rulebook.md +2 -1
  222. package/docs/ja/specdojo/rulebooks/dss-rulebook.md +193 -0
  223. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +100 -54
  224. package/docs/ja/specdojo/rulebooks/ifd-mermaid-rulebook.md +69 -252
  225. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +91 -76
  226. package/docs/ja/specdojo/rulebooks/ifx-file-rulebook.md +252 -226
  227. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +118 -40
  228. package/docs/ja/specdojo/rulebooks/imp-business-rulebook.md +11 -11
  229. package/docs/ja/specdojo/rulebooks/imp-data-rulebook.md +9 -9
  230. package/docs/ja/specdojo/rulebooks/imp-interface-rulebook.md +4 -4
  231. package/docs/ja/specdojo/rulebooks/imp-operations-rulebook.md +11 -11
  232. package/docs/ja/specdojo/rulebooks/imp-test-rulebook.md +11 -11
  233. package/docs/ja/specdojo/rulebooks/mm-rulebook.md +4 -3
  234. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +34 -29
  235. package/docs/ja/specdojo/rulebooks/pm-change-request-log-rulebook.md +8 -8
  236. package/docs/ja/specdojo/rulebooks/pm-issue-log-rulebook.md +2 -2
  237. package/docs/ja/specdojo/rulebooks/pm-organization-rulebook.md +50 -56
  238. package/docs/ja/specdojo/rulebooks/pm-plan-rulebook.md +46 -55
  239. package/docs/ja/specdojo/rulebooks/pm-quality-management-plan-rulebook.md +57 -54
  240. package/docs/ja/specdojo/rulebooks/pm-raci-rulebook.md +50 -65
  241. package/docs/ja/specdojo/rulebooks/pm-risk-register-rulebook.md +2 -2
  242. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +70 -97
  243. package/docs/ja/specdojo/rulebooks/pr-rulebook.md +2 -1
  244. package/docs/ja/specdojo/rulebooks/prj-assumptions-constraints-dependencies-rulebook.md +47 -56
  245. package/docs/ja/specdojo/rulebooks/prj-comparison-of-alternatives-rulebook.md +61 -135
  246. package/docs/ja/specdojo/rulebooks/sf-index-rulebook.md +116 -32
  247. package/docs/ja/specdojo/rulebooks/sf-rulebook.md +118 -61
  248. package/docs/ja/specdojo/rulebooks/sld-rulebook.md +152 -57
  249. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +51 -39
  250. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +101 -46
  251. package/docs/ja/specdojo/rulebooks/sysd-critical-flows-rulebook.md +72 -329
  252. package/docs/ja/specdojo/rulebooks/sysd-cross-cutting-policy-rulebook.md +74 -263
  253. package/docs/ja/specdojo/rulebooks/sysd-index-rulebook.md +78 -195
  254. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +4 -9
  255. package/docs/ja/specdojo/rulebooks/trc-requirements-to-specs-rulebook.md +3 -4
  256. package/docs/ja/specdojo/rulebooks/trc-requirements-to-tests-rulebook.md +3 -3
  257. package/docs/ja/specdojo/rulebooks/uis-rulebook.md +140 -143
  258. package/docs/ja/specdojo/samples/bac-sample.md +106 -21
  259. package/docs/ja/specdojo/samples/bdd-sample.yaml +143 -35
  260. package/docs/ja/specdojo/samples/bds-sample.md +100 -21
  261. package/docs/ja/specdojo/samples/bes-index-sample.md +59 -20
  262. package/docs/ja/specdojo/samples/bes-sample.md +80 -21
  263. package/docs/ja/specdojo/samples/br-sample.md +68 -14
  264. package/docs/ja/specdojo/samples/ccd-sample.md +81 -19
  265. package/docs/ja/specdojo/samples/cdfd-overview-sample.md +248 -140
  266. package/docs/ja/specdojo/samples/cdfd-sample.md +172 -99
  267. package/docs/ja/specdojo/samples/cdfd-uc-sample.md +130 -97
  268. package/docs/ja/specdojo/samples/cdsd-sample.md +89 -20
  269. package/docs/ja/specdojo/samples/cdt-sample.md +116 -0
  270. package/docs/ja/specdojo/samples/cld-sample.md +3 -30
  271. package/docs/ja/specdojo/samples/clis-sample.md +132 -0
  272. package/docs/ja/specdojo/samples/cnd-sample.md +127 -21
  273. package/docs/ja/specdojo/samples/cpd-sample.md +136 -22
  274. package/docs/ja/specdojo/samples/cxd-sample.md +108 -22
  275. package/docs/ja/specdojo/samples/dct-index-sample.yaml +63 -17
  276. package/docs/ja/specdojo/samples/dss-sample.md +175 -0
  277. package/docs/ja/specdojo/samples/gl-sample.yaml +50 -14
  278. package/docs/ja/specdojo/samples/ifd-sample.md +105 -21
  279. package/docs/ja/specdojo/samples/ifx-cmd-sample.yaml +91 -60
  280. package/docs/ja/specdojo/samples/ifx-file-sample.md +462 -21
  281. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +87 -19
  282. package/docs/ja/specdojo/samples/pm-members-sample.yaml +37 -13
  283. package/docs/ja/specdojo/samples/pm-organization-sample.md +52 -20
  284. package/docs/ja/specdojo/samples/pm-plan-sample.md +84 -26
  285. package/docs/ja/specdojo/samples/pm-quality-management-plan-sample.md +55 -22
  286. package/docs/ja/specdojo/samples/pm-raci-sample.md +69 -28
  287. package/docs/ja/specdojo/samples/pm-roles-sample.yaml +13 -12
  288. package/docs/ja/specdojo/samples/prj-assumptions-constraints-dependencies-sample.md +50 -26
  289. package/docs/ja/specdojo/samples/prj-comparison-of-alternatives-sample.md +89 -62
  290. package/docs/ja/specdojo/samples/sf-index-sample.md +89 -20
  291. package/docs/ja/specdojo/samples/sf-sample.md +121 -21
  292. package/docs/ja/specdojo/samples/sld-sample.md +107 -21
  293. package/docs/ja/specdojo/samples/stsd-sample.md +54 -26
  294. package/docs/ja/specdojo/samples/sysd-critical-flows-sample.md +166 -21
  295. package/docs/ja/specdojo/samples/sysd-cross-cutting-policy-sample.md +178 -21
  296. package/docs/ja/specdojo/samples/sysd-index-sample.md +82 -21
  297. package/docs/ja/specdojo/samples/tml-sample.yaml +4 -1
  298. package/docs/ja/specdojo/samples/uis-sample.md +164 -20
  299. package/docs/ja/specdojo/standards/document-metadata-standard.md +33 -4
  300. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +3 -1
  301. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +1 -0
  302. package/docs/ja/specdojo/templates/bac-template.md +76 -0
  303. package/docs/ja/specdojo/templates/bes-template.md +56 -0
  304. package/docs/ja/specdojo/templates/br-template.md +64 -0
  305. package/docs/ja/specdojo/templates/cdfd-overview-template.md +161 -83
  306. package/docs/ja/specdojo/templates/cdfd-template.md +81 -54
  307. package/docs/ja/specdojo/templates/cdfd-uc-template.md +130 -89
  308. package/docs/ja/specdojo/templates/cnd-template.md +137 -0
  309. package/docs/ja/specdojo/templates/cpd-template.md +129 -0
  310. package/docs/ja/specdojo/templates/cxd-template.md +105 -0
  311. package/docs/ja/specdojo/templates/dct-data-model-cdt-template.yaml +40 -0
  312. package/docs/ja/specdojo/templates/dct-data-model-cld-template.yaml +7 -14
  313. package/docs/ja/specdojo/templates/dct-index-template.md +9 -20
  314. package/docs/ja/specdojo/templates/dct-project-management-template.yaml +5 -1
  315. package/docs/ja/specdojo/templates/ifd-template.md +86 -0
  316. package/docs/ja/specdojo/templates/ifx-cmd-template.yaml +44 -28
  317. package/docs/ja/specdojo/templates/ifx-index-template.yaml +40 -0
  318. package/docs/ja/specdojo/templates/opr-template.md +2 -4
  319. package/docs/ja/specdojo/templates/pm-organization-template.md +9 -3
  320. package/docs/ja/specdojo/templates/pm-plan-template.md +4 -4
  321. package/docs/ja/specdojo/templates/pm-quality-management-plan-template.md +17 -9
  322. package/docs/ja/specdojo/templates/pm-raci-template.md +24 -13
  323. package/docs/ja/specdojo/templates/pm-roles-template.yaml +3 -2
  324. package/docs/ja/specdojo/templates/prj-assumptions-constraints-dependencies-template.md +6 -3
  325. package/docs/ja/specdojo/templates/prj-comparison-of-alternatives-template.md +22 -19
  326. package/docs/ja/specdojo/templates/stsd-template.md +46 -21
  327. package/docs/ja/specdojo/templates/sysd-critical-flows-template.md +94 -0
  328. package/docs/ja/specdojo/templates/sysd-cross-cutting-policy-template.md +122 -0
  329. package/docs/ja/specdojo/templates/sysd-index-template.md +89 -0
  330. package/docs/specdojo/lib/yaml-metadata.cjs +7 -0
  331. package/docs/specdojo/schemas/v1/bdd.schema.yaml +25 -57
  332. package/docs/specdojo/schemas/v1/condense-records.schema.yaml +26 -0
  333. package/docs/specdojo/schemas/v1/dct.schema.yaml +10 -0
  334. package/docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml +3 -0
  335. package/docs/specdojo/schemas/v1/esil.schema.yaml +7 -141
  336. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +3 -0
  337. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +54 -3
  338. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +3 -0
  339. package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +14 -0
  340. package/docs/specdojo/schemas/v1/exec-result-frontmatter.schema.yaml +18 -0
  341. package/docs/specdojo/schemas/v1/finding-cause.schema.yaml +22 -0
  342. package/docs/specdojo/schemas/v1/grade-pipeline-state.schema.yaml +1 -1
  343. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +2 -0
  344. package/docs/specdojo/schemas/v1/ifx-cmd.schema.yaml +65 -5
  345. package/docs/specdojo/schemas/v1/ifx-index.schema.yaml +142 -0
  346. package/docs/specdojo/schemas/v1/register-events.schema.yaml +2 -0
  347. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +17 -1
  348. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +1 -0
  349. package/package.json +6 -3
  350. package/templates/antigravity/README.md +19 -46
  351. package/templates/antigravity/exec-defaults-snippet.yaml +5 -6
  352. package/templates/antigravity/orchestrator.md +3 -2
  353. package/templates/antigravity/settings.edit.json +73 -0
  354. package/templates/antigravity/settings.orchestrator.json +15 -0
  355. package/templates/antigravity/settings.report.json +7 -0
  356. package/templates/antigravity/settings.review.json +7 -0
  357. package/templates/claude/agents/specdojo-orchestrator.md +3 -2
  358. package/templates/codex/agents/specdojo-orchestrator.toml +3 -2
  359. package/templates/codex/orchestrator.md +3 -2
  360. package/templates/devcontainer/remote-host/devcontainer-tmux.sh +217 -0
  361. package/templates/devcontainer/remote-host/specdojo-tmux.sh.sample +8 -96
  362. package/templates/devcontainer/remote-host/ssh-config.sample +3 -1
  363. package/templates/devcontainer/tmux.conf +6 -0
  364. package/templates/init-agent-members.yaml +1 -0
  365. package/templates/init-exec-defaults.yaml +1 -1
  366. package/templates/opencode/agents/specdojo-orchestrator.md +3 -2
@@ -9,1077 +9,865 @@ specdojo:
9
9
 
10
10
  Quick Start Guide
11
11
 
12
- SpecDojo CLI の初期設定から始め、register で課題と判断を整理し、成果物カタログ、schedule、routine へ展開する基本フローを最短手順で試します。冒頭の `10分で体験する — 仕様の判断台帳` では、kata や成果物カタログを用意せずに、記帳ひとつから判断を残す流れを先に体験します。
12
+ SpecDojo の導入から始め、オーケストレーターとの対話を通して、管理対象リポジトリと Git flow の初期設定、register での起票・AI 実行、成果物カタログから schedule による成果物作成、routine の登録までを一貫したストーリーで体験します。
13
+
14
+ 本書では、共通の題材として Web サイトのプロダクトリポジトリ `../landing-page` を用います(※掲載している todo・issue・decision はガイド用の例であり、実プロジェクトの事実ではありません)。
15
+
16
+ 各ステップは次の順序で構成されています:
17
+
18
+ 1. **前提**: その操作に必要な準備や前提条件
19
+ 2. **具体的対話**: 利用者とオーケストレーターの対話(不足事項の確認、提案、承認、実行の流れ)
20
+ 3. **得られる結果と確認先**: 操作によって生成・更新されるファイルや確認手順
21
+ 4. **折りたたんだコマンドと設定差分**: `<details>` で折りたたんだ CLI コマンドや設定ファイルの差分
22
+
23
+ > [!NOTE]
24
+ > オーケストレーターは担当者、期限、採択判断などのプロジェクト事実を勝手に確定しません。必ず利用者に確認・提案し、明示的な承認を得てから実行します。
13
25
 
14
26
  **対象読者**
15
27
 
16
- - SpecDojo CLI を初めて使い、プロジェクトの作業を登録・実行してみたい開発者、運用者
28
+ - SpecDojo を初めて使い、プロジェクトの作業登録から AI 実行、スケジュール、ルーチン運用までを一通り体験したい開発者・運用者
17
29
 
18
30
  **この文書で分かること**
19
31
 
20
- - question の起票から decision、仕様書の更新、change-request による修正までを記帳する流れ
21
- - CLI の初期設定と、register のユースケース別の使い方
22
- - issue / decision / todo から成果物カタログと Schedule へ展開する手順
23
- - npm package の kata を参照し、必要なものだけ eject する方法
32
+ - プロジェクトリポジトリの導入と、管理対象リポジトリ(`../landing-page`)および Git flow ブランチルールの初期設定
33
+ - register を使った機能追加(todo)、不具合調査(issue)、方針比較(decision)の起票と AI による隔離実行
34
+ - 成果物カタログ(`dct-*.yaml`)の準備と、schedule による成果物の体系的作成
35
+ - routine による定期実行の登録と cron / CI への組み込み
24
36
 
25
37
  **次に読む文書**
26
38
 
27
- - register のtypeと状態遷移は [登録簿運用ガイド](register-operation-guide.md) を参照してください。
28
- - Scheduleの自動・手動実行は [Schedule実行運用ガイド](schedule-operation-guide.md)、agent設定は [exec設定ガイド](exec-config-guide.md) を参照してください。
29
-
30
- 各コマンドには、設定済みのオーケストレーター(`specdojo-orchestrator`)へチャットで指示する場合の文言を `# チャット:` として併記します。オーケストレーターは指示を対応する `specdojo` サブコマンドへ変換し、状態を変える操作は実行前に内容を提示して承認を求めます。オーケストレーターはターミナル(`npm run orch:<provider>`)だけでなく、VS Code の各種拡張機能(Copilot Chat、Claude Code、Codex)からも利用できます。導入先での設定と起動方法は [オーケストレーター運用ガイド](orchestrator-operation-guide.md)(VS Code からの利用は [VS Code から使う](orchestrator-operation-guide.md#22-vs-code-から使う) 節)を参照してください。`<project-id>` などのプレースホルダは実際の値に読み替えてください。
39
+ - 登録簿の種別と状態遷移は [[specdojo:register-operation-guide|登録簿運用ガイド]] を参照してください。
40
+ - オーケストレーターの起動や安全設計は [[specdojo:orchestrator-operation-guide|オーケストレーター運用ガイド]] を参照してください。
41
+ - 隔離実行の詳細は [[specdojo:exec-worktree-guide|exec worktree運用ガイド]]、ブランチ運用規則は [[specdojo:branch-workflow-guide|ブランチワークフローガイド]] を参照してください。
31
42
 
32
- ## 1. 10分で体験する — 仕様の判断台帳
43
+ ## 1. 導入とオーケストレーターの起動
33
44
 
34
- **記して、形にして、磨き続ける。** SpecDojo は、迷っていることを記帳し、決めたことを仕様書へ書き、後日の変更も同じ台帳に残します。この節では、共通サンプルの「駄菓子屋きぬや 販売管理システム構築」を題材に、次の流れを 10 分ほどで体験します。kata(型)や成果物カタログを事前に用意する必要はありません。
45
+ Node.js 22.13 以上と Git を用意します。SpecDojo は、成果物の更新、登録簿の状態遷移、実行記録をプロダクトの Git 履歴に混ぜないため、**別リポジトリ構成(Detached Unit)** を基本とします。
35
46
 
36
47
  ```text
37
- question を起票する(迷っていること)
38
- -> decision で決める(選択肢・理由・決定)
39
- -> 仕様書を 1 つ書く(決定を反映する)
40
- -> 後日 change-request で直す(変更の理由を残す)
41
- -> 決定ログ・変更要求ログで振り返る
48
+ landing-page-workspace/
49
+ ├── landing-page/ # 既存のプロダクトリポジトリ(Web サイト本体)
50
+ ├── landing-page-specdojo/ # SpecDojo プロジェクトリポジトリ
51
+ └── landing-page-specdojo-worktrees/ # タスクごとの作業ツリー置き場
42
52
  ```
43
53
 
44
- 各手順には、実行するコマンドと、オーケストレーターへの話しかけ方の例(`# チャット:`)を併記します。どちらか一方で進められます。表示された `PJR-XXXX` は、自分の環境で表示された ID に読み替えてください。
54
+ ### 1.1. ワークスペースの準備と導入
45
55
 
46
- ### 1.1. 道場を開く(導入と初期設定)
56
+ #### 前提
47
57
 
48
- プロジェクトリポジトリを作り、SpecDojo を導入して `init` の質問に答えます。
58
+ - ワークスペースディレクトリに既存のプロダクトリポジトリ `landing-page/` があること。
59
+ - Node.js 22.13 以上、npm、Git が利用可能であること。
60
+ - オーケストレーターに使う AI provider(Claude Code、Codex、Antigravity、OpenCode など)の CLI が導入・ログイン済みであること。
61
+
62
+ #### 導入と起動コマンド(本文)
63
+
64
+ プロダクトリポジトリと並べてプロジェクトリポジトリを作成し、SpecDojo を導入して `init` の質問に答えます。
49
65
 
50
66
  ```bash
51
- mkdir app1-workspace
52
- mkdir app1-workspace/app1-specdojo
53
- git -C app1-workspace/app1-specdojo init
54
- cd app1-workspace/app1-specdojo
67
+ mkdir -p landing-page-workspace
68
+ cd landing-page-workspace
69
+ # 既存プロダクト landing-page と並べてプロジェクトリポジトリを作成
70
+ mkdir landing-page-specdojo
71
+ git -C landing-page-specdojo init -b develop
72
+ cd landing-page-specdojo
55
73
  npm init -y
56
74
  npm install --save-dev specdojo
57
75
  npx specdojo init
76
+ # 初期設定を Git に記録してから、exec 用設定を追加・commitする
77
+ git add . && git commit -m "chore: initialize SpecDojo project"
58
78
  ```
59
79
 
60
- この体験では、記帳だけを使う最小構成で答えます。`[]` 内は既定値で、Enter だけで採用されます。
80
+ 対話式 `init` では、最小構成で以下のように答えます(`[]` 内は既定値で、Enter で採用されます)。
61
81
 
62
82
  ```text
63
83
  Project ID [prj-0001]: <- Enter(prj-0001)
64
- Project name [My Project]: 駄菓子屋きぬや 販売管理システム構築
84
+ Project name [My Project]: LP サイト改善プロジェクト <- プロジェクト名を入力
65
85
  Create a project register? [Y/n]: <- Enter(登録簿を作る)
66
- Your nickname [owner]: owner
67
- Your display name [Project Owner]: 店主
68
- Orchestrator providers (...) [codex]: claude <- 使う AI ツールを 1 つ選ぶ
69
- Delegate work to agents (exec)? [y/N]: <- Enter(実戦は後で設定する)
70
- Create a Dev Container? [y/N]: y <- y(Dev Container を作る。使わない場合は Enter)
71
- Dev Container preset (minimal, recommended, full) [recommended]: <- Enter(推奨 preset を選ぶ)
72
- Create Git hooks with lefthook? [y/N]: <- Enter(この体験では作らない)
86
+ Your nickname [owner]: owner <- あなたのニックネーム
87
+ Your display name [Project Owner]: サイト責任者 <- 表示名
88
+ Orchestrator providers (...) [codex]: claude <- 利用する AI ツールを選ぶ
89
+ Delegate work to agents (exec)? [y/N]: y <- y(AI への作業委譲を有効化)
90
+ Create a Dev Container? [y/N]: n <- Enter(手元環境で進める)
91
+ Create Git hooks with lefthook? [y/N]: n <- Enter(初期設定では作らない)
73
92
  ```
74
93
 
75
- 入力が不正な場合は理由が表示され、同じ質問だけがもう一度表示されます。たとえば provider に
76
- `claud` と入力すると、利用可能な provider の一覧に続いて provider の質問だけが再表示されます。
77
- それまでに答えた project や名簿の内容を入力し直す必要はありません。
78
-
79
- Dev Container を作る質問に `y`、preset に Enter と答えると、既定の `recommended` が選ばれ、tmux・Emacs・Vim・推奨の VS Code 拡張と設定・`.vscode/extensions.json` が入った環境が生成されます。作成したコンテナは、VS Code の「コンテナーで再度開く」または `devcontainer up` で開けます(詳しい説明は [[specdojo:remote-host-development-guide]] を参照)。Dev Container を使わずに手元の環境で進めたい場合は、Dev Container の質問に Enter または `n`(いいえ)と答えて先へ進めます。この 10 分の体験は記帳だけで進められるため、コンテナを開かずにそのままホスト環境で続けて構いません。
80
-
81
- 登録簿は `docs/ja/projects/prj-0001/controls/project-register/` に作られます。オーケストレーターで進める場合は、終了時に表示される `npm run orch:<provider>` で起動します。成果物カタログは対話では作られません。成果物の構成が定まったら、[[#41-成果物カタログを作成する|成果物カタログを作成する]] に従って `catalog_path` を設定し、`catalog scaffold` で追加してください。
82
-
83
- ### 1.2. 迷っていることを起票する(question)
84
-
85
- レジで扱う支払い方法が決まっていない、という迷いを question として起票します。
94
+ 初期化が完了すると、選んだ provider のオーケストレーター起動スクリプトが案内されます。次のコマンドでオーケストレーターを起動します。
86
95
 
87
96
  ```bash
88
- # チャット:「question を起票して。タイトルは『支払い方法をどこまで扱うか』」
89
- npx specdojo register add \
90
- --project prj-0001 \
91
- --type question \
92
- --title "支払い方法をどこまで扱うか" \
93
- --topic payment-scope
97
+ npm run orch:opus
94
98
  ```
95
99
 
96
- 出力に表示された `PJR-XXXX` を控えます。`controls/project-register/` に `pjr-xxxx-payment-scope.md` という個票ができるので開き、`確認事項` と `背景` に「現金のほか、常連客のつけやキャッシュレスまで扱うか」「つけの記録漏れが問題になっている」などを書きます。個票の章立ては question の型(テンプレート)から与えられます。
97
-
98
- ### 1.3. decisionで決める
99
-
100
- 選択肢と理由を比べて決めるために、decision を起票します。
101
-
102
- ```bash
103
- # チャット:「decision を起票して。タイトルは『初期リリースで扱う支払い方法を決める』」
104
- npx specdojo register add \
105
- --project prj-0001 \
106
- --type decision \
107
- --title "初期リリースで扱う支払い方法を決める" \
108
- --topic payment-methods
109
- ```
100
+ provider に応じて `npm run orch:sonnet`、`npm run orch:sol`、`npm run orch:flash`、`npm run orch:opencode` などが利用できます。詳細は [[specdojo:orchestrator-operation-guide|オーケストレーター運用ガイド]] を参照してください。
110
101
 
111
- decision の個票に、次のように書きます。オーケストレーターを使う場合は、相談した内容がそのまま個票の本文になります。
102
+ #### 具体的対話
112
103
 
113
- - `検討した選択肢`: A 現金のみ、B 現金とつけ、C 現金とつけとキャッシュレス
114
- - `決定内容`: B 現金とつけを扱う
115
- - `採択理由`: つけの記録漏れが現在の主な問題であり、キャッシュレスは利用者が少ない
104
+ 起動後、ターミナルでオーケストレーターとのセッションが始まります。
116
105
 
117
- 書き終えたら、decision と、元の question を close します。decision と question は close すると `decided` になります。
106
+ ```chat
107
+ あなた: SpecDojo の導入ができました。このプロジェクトを進めたいです。
118
108
 
119
- ```bash
120
- # チャット:「decision PJR-XXXX を『現金とつけを扱う』で完了して」
121
- npx specdojo register close \
122
- --project prj-0001 \
123
- --id PJR-XXXX \
124
- --conclusion "初期リリースは現金とつけを扱う"
109
+ オーケストレーター: SpecDojo の初期化を確認しました。登録簿(controls/project-register/)と名簿設定(projects.prj-0001.members_path が指す docs/ja/projects/prj-0001/030-project-management/pm-members.yaml)が準備されています。
110
+ まずは隣にあるプロダクトリポジトリ(../landing-page)を管理対象リポジトリとして接続し、安全に開発を進めるための Git flow ブランチ運用ルールを設定することをお勧めします。
111
+ 進めてよろしいですか?
125
112
 
126
- # チャット:「question PJR-XXXX を『decision で決定』で完了して」
127
- npx specdojo register close \
128
- --project prj-0001 \
129
- --id PJR-XXXX \
130
- --conclusion "decision で現金とつけを扱うと決定"
113
+ あなた: はい、進めてください。
131
114
  ```
132
115
 
133
- ### 1.4. 決めたことを仕様書に書く
134
-
135
- 決定を仕様書へ反映します。この体験では成果物カタログを使わず、Markdown を 1 つ作ります。仕様書はプロダクトの文書なので、プロダクトリポジトリ(例: `app1/docs/ja/product/payment-policy.md`)に置きます。
136
-
137
- ```markdown
138
- # 支払い方法の基本方針
139
-
140
- ## 1. 扱う支払い方法
141
-
142
- - 現金
143
- - つけ(常連客のみ。会計時に残高を記録する)
144
-
145
- ## 2. 根拠
146
-
147
- - decision PJR-XXXX(初期リリースで扱う支払い方法を決める)
148
- ```
116
+ #### 得られる結果と確認先
149
117
 
150
- 仕様書から decision の ID を参照しておくと、「なぜこう書いたか」を後から台帳でたどれます。
118
+ - `docs/ja/projects/prj-0001/controls/project-register/` に登録簿の基本構造が作成されます。
119
+ - `package.json` に `orch:<provider>` スクリプトが追加されます。
120
+ - オーケストレーターが対話可能になります。
151
121
 
152
- ### 1.5. 後日の変更をchange-requestで直す
122
+ #### 折りたたんだコマンドと設定差分
153
123
 
154
- 運用を始めた後、「子ども向けに交通系電子マネーも使いたい」という要望が出たとします。仕様書をいきなり書き換えず、change-request として記帳します。
124
+ <details>
125
+ <summary>初期設定の確認コマンドとディレクトリ構造(クリックで展開)</summary>
155
126
 
156
127
  ```bash
157
- # チャット:「change-request を起票して。タイトルは『交通系電子マネーを支払い方法に加える』」
158
- npx specdojo register add \
159
- --project prj-0001 \
160
- --type change-request \
161
- --title "交通系電子マネーを支払い方法に加える" \
162
- --topic add-ic-card-payment
128
+ # プロジェクト一覧の確認
129
+ npx specdojo project list
130
+
131
+ # 作成された登録簿の確認
132
+ ls -l docs/ja/projects/prj-0001/controls/project-register/
163
133
  ```
164
134
 
165
- change-request の個票に `変更要求`、`影響評価`、`審査・決定` を書き、仕様書 `payment-policy.md` の扱う支払い方法へ「交通系電子マネー」を追加して、根拠に change-request の ID を加えます。直し終えたら close します。change-request は close すると `done` になります。
135
+ 生成された初期ディレクトリ構成:
166
136
 
167
- ```bash
168
- # チャット:「change-request PJR-XXXX を『仕様書へ反映』で完了して」
169
- npx specdojo register close \
170
- --project prj-0001 \
171
- --id PJR-XXXX \
172
- --conclusion "交通系電子マネーを支払い方法の基本方針へ追加"
137
+ ```text
138
+ landing-page-specdojo/
139
+ ├── .specdojo/
140
+ │ ├── specdojo.config.json
141
+ │ ├── agent-members.yaml
142
+ │ └── exec-defaults.yaml
143
+ ├── docs/ja/projects/prj-0001/
144
+ │ ├── 030-project-management/
145
+ │ │ └── pm-members.yaml
146
+ │ └── controls/
147
+ │ └── project-register/
148
+ │ ├── generated/
149
+ │ └── events/
150
+ └── package.json
173
151
  ```
174
152
 
175
- ### 1.6. 台帳を確かめる
153
+ </details>
176
154
 
177
- 記帳のたびに、個票から一覧とログが生成されます。手動で作り直す場合は `register build` を実行します。
155
+ ## 2. 管理対象リポジトリと Git flow の設定
178
156
 
179
- ```bash
180
- # チャット:「登録簿の一覧とログを作り直して」
181
- npx specdojo register build --project prj-0001
182
- ```
157
+ ### 前提
183
158
 
184
- | 生成物 | 内容 |
185
- | -------------------------------------------------- | --------------------------------------------- |
186
- | `controls/project-register/generated/pjr-index.md` | question・decision・change-request を含む全件 |
187
- | `controls/generated/pm-decision-log.md` | 決定ログ(decision の一覧) |
188
- | `controls/generated/pm-change-request-log.md` | 変更要求ログ(change-request の一覧) |
189
- | `controls/generated/pm-issue-log.md` | 課題ログ(issue の一覧) |
159
+ - オーケストレーターと対話中であること。
160
+ - プロダクトリポジトリ `../landing-page` が Git で初期化されており、`main` および `develop` ブランチが存在すること。
190
161
 
191
- パスは `docs/ja/projects/prj-0001/` からの相対です。正本は個票の Markdown なので、`git log` でも SpecDojo なしでも読めます。作成された設定・個票・仕様書を確認して commit すれば、体験は完了です。
162
+ ### 具体的対話
192
163
 
193
- ### 1.7. 次に進む
164
+ オーケストレーターにプロダクトリポジトリの接続と Git flow ルールの設定を依頼します。オーケストレーターはブランチ名や統合方式の不足事項を確認し、利用者が選択した後に設定を適用します。
194
165
 
195
- - 型と実戦: 仕様書を増やしたくなったら、成果物カタログ(`dct-<domain>.yaml`)で作る成果物を宣言し、型に沿って作ります。手順は以降の `CLIを初期設定する` と `成果物カタログからscheduleへ展開する` を参照してください。
196
- - 実戦(exec): 起票した todo や issue を AI に実行させるには、[exec設定ガイド](exec-config-guide.md) で agent を設定し、`npx specdojo exec run --project prj-0001 --register PJR-XXXX` を実行します。
197
- - 評定(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` が必要です。
198
- - 記帳の種別と状態遷移は [登録簿運用ガイド](register-operation-guide.md) を参照してください。
166
+ ```chat
167
+ あなた: 隣にある ../landing-page を管理対象リポジトリに追加して、Git flow のブランチルールで運用したいです。
199
168
 
200
- ## 2. CLIを初期設定する
169
+ オーケストレーター: ../landing-page をプロダクトリポジトリ(repos)として接続し、Git flow のブランチ運用ルールを設定します。以下の運用設定について確認させてください:
170
+ 1. 統合先ブランチ(integration_branch): develop でよろしいですか?(本番用の main と日々の開発統合用の develop を分ける Git flow 構成)
171
+ 2. 作業ブランチ命名規則(branch_template): feature/{topic} でよろしいですか?(例: feature/add-faq-section)
172
+ 3. 統合方式(integration_strategy): ff(Fast-Forward 早送り統合)にしますか、それとも merge(マージコミット作成)にしますか?(推奨は履歴が直線的になる ff です)
173
+ 4. コミット件名規則(commit_subject_template): Conventional Commits 形式 {type}({scope}): {title} で統一しますか?
174
+ 5. 依存解決(setup): 隔離作業ツリーで追跡済み package-lock.json ごとに npm ci を実行(install: true)しますか?
201
175
 
202
- Node.js 22.13 以上と Git を用意します。オーケストレーターに Claude Code を使う場合は、Claude Code も導入してログインしておきます。ほかの provider も選べます。
176
+ あなた: 統合先は develop、作業ブランチは feature/{topic}、統合方式は ff、コミット件名は提案どおりの Conventional Commits、依存解決は install: true でお願いします。
203
177
 
204
- 既定では、SpecDojo の成果物更新、登録簿の状態遷移、実行記録をプロダクトの Git 履歴に混ぜないため、次の **別リポジトリ構成**で始めます。
178
+ オーケストレーター: 承知しました。以下の設定を .specdojo/specdojo.config.json の projects.prj-0001.repos に追加します:
179
+ ・リポジトリ名: landing-page
180
+ ・パス: ../landing-page
181
+ ・統合先ブランチ: develop
182
+ ・作業ブランチ規則: feature/{topic}
183
+ ・統合方式: ff
184
+ ・コミット件名: {type}({scope}): {title}
185
+ ・setup: { "install": true, "build": false }
186
+ この変更を適用してよろしいですか?
205
187
 
206
- - **プロダクトリポジトリ** `app1/`: ソースコードと、仕様・設計などのプロダクトドキュメントを置きます。
207
- - **プロジェクトリポジトリ** `app1-specdojo/`: 登録簿・計画・実行記録などのプロジェクトドキュメントと型(Kata)を置きます。1つのプロジェクトリポジトリに、複数のプロジェクトを格納できます。
208
- - **worktree 用ディレクトリ** `app1-specdojo-worktrees/`: タスクごとの変更を隔離して進めるために、Git worktree を作る場所です。名前はプロジェクトリポジトリのディレクトリ名から決まります。
188
+ あなた: はい、適用してください。
209
189
 
210
- ```text
211
- app1-workspace/
212
- ├── app1/ # 既存または新規のプロダクトリポジトリ
213
- ├── app1-specdojo/ # プロジェクトリポジトリ
214
- └── app1-specdojo-worktrees/ # task 単位の worktree 置き場
215
- ```
190
+ オーケストレーター: 設定を更新しました。landing-page が管理対象として認識されました。
191
+ VS Code でプロジェクトリポジトリとプロダクトリポジトリを同時に開くマルチルートワークスペース(prj-0001.code-workspace)を生成できますが、作成しますか?
216
192
 
217
- 既に開発している `app1/` と並べてプロジェクトリポジトリを作り、`app1-specdojo/` に SpecDojo を導入します。worktree 用ディレクトリは、最初の隔離実行時に設定に従って作られます。
193
+ あなた: はい、作成してください。
218
194
 
219
- ```bash
220
- mkdir app1-workspace
221
- mkdir app1-workspace/app1-specdojo
222
- git -C app1-workspace/app1-specdojo init
223
- cd app1-workspace/app1-specdojo
224
- npm init -y
225
- npm install --save-dev specdojo
226
- # 質問に答えて project、register、agent 実行までを初期設定する
227
- npx specdojo init
195
+ オーケストレーター: prj-0001.code-workspace を生成しました。VS Code で「ファイル > ワークスペースを開く」から開くことで、両リポジトリを 1 つのウィンドウで操作できます。
228
196
  ```
229
197
 
230
- `specdojo init` は、project ID と名前、人の nickname と表示名、利用する agent provider、
231
- exec・Dev Container・Git hook の要否を順に質問し、Dev Container を選んだ場合だけ `minimal` / `recommended` / `full` の preset(既定は `recommended`)を続けて質問します。Git hook は既定では作りません。成果物カタログは対話では質問せず、`--catalog <size>` を
232
- 明示した場合にだけ初期化時に作成します。選択に応じて設定、登録簿、人と
233
- agent の名簿、provider の scaffold、`package.json` の `orch:<provider>`、exec の起動設定を
234
- 作成します。exec の親検証は、対応する npm script が `package.json` にあるものだけを設定し、
235
- 該当する script がなければ省略します。既存ファイルは上書きせず、作成内容は `--dry-run` で
236
- 先に確認できます。対話中に不正な値を入力した場合は理由を表示して同じ質問だけをやり直し、
237
- それまでの回答は保持します。非対話環境や `--yes` では再質問せず、不正な指定をエラーとして終了します。
238
-
239
- CI や標準入力が端末でない環境では質問しません。次のようにオプションだけで同じ初期設定を
240
- 行えます。`--devcontainer` を指定した場合は既定で `recommended` preset(tmux・Emacs・Vim・推奨の VS Code 拡張と設定)が入ります。CLI と最低限だけにする場合は `--devcontainer-preset minimal` を指定します。従来の `none` も `minimal` と同じ意味で受け付けます。省略値は画面に表示されます。
198
+ ### 得られる結果と確認先
241
199
 
242
- ```bash
243
- npx specdojo init --yes \
244
- --project prj-0001 \
245
- --name "Example Project" \
246
- --nickname owner \
247
- --display-name "Project Owner" \
248
- --provider claude,codex \
249
- --exec \
250
- --devcontainer \
251
- --lefthook \
252
- --dry-run
253
- ```
200
+ - `.specdojo/specdojo.config.json` に `repos` 定義が保存され、`../landing-page` がプロジェクトの管理下に入ります。
201
+ - `npx specdojo project list` で project ID と解決済み schedule / execution パスを確認します。repos 一覧は表示されません。
202
+ - `prj-0001.code-workspace` が作成され、VS Code で 2 つのリポジトリを同時に開けます。
254
203
 
255
- 初期化後は、表示された `npm run orch:<provider>` でオーケストレーターを起動し、最初の 1 件を
256
- 起票します。成果物カタログが必要になった場合は、`.specdojo/specdojo.config.json` に `catalog_path` を設定して `specdojo catalog scaffold` で追加します(詳細は [[#41-成果物カタログを作成する|成果物カタログを作成する]] を参照)。オーケストレーターを使わない場合は、同じ案内に表示される
257
- `exec run --register <id> --executor-by <executor> --reporter-by <reporter>` で実行できます。
258
- 作成された設定と文書は内容を確認して commit してください。
204
+ ### 折りたたんだコマンドと設定差分
259
205
 
260
- LP の例と同じく Claude Code へ作業を任せる場合は、provider の質問に `claude`、exec の質問に「はい」と答えます。初期化後は `npm run orch:opus`(または `npm run orch:sonnet`)でオーケストレーターを起動できます。
206
+ <details>
207
+ <summary>repos 設定差分と CLI コマンド(クリックで展開)</summary>
261
208
 
262
- プロダクトを変更する前に、`.specdojo/specdojo.config.json` の `projects.prj-0001` へ、同じ workspace にあるプロダクトリポジトリを接続します。
209
+ `.specdojo/specdojo.config.json` の設定差分:
263
210
 
264
211
  ```json
265
- "repos": [
266
- {
267
- "name": "app1",
268
- "path": "../app1",
269
- "integration_branch": "main"
212
+ {
213
+ "projects": {
214
+ "prj-0001": {
215
+ "base_path": "docs/ja/projects/prj-0001",
216
+ "project_register_path": "controls/project-register",
217
+ "catalog_path": "010-deliverables-catalog",
218
+ "schedule_path": "schedule",
219
+ "execution_path": "execution",
220
+ "members_path": "030-project-management/pm-members.yaml",
221
+ "roles_path": "030-project-management/pm-roles.yaml",
222
+ "routines_path": "routines",
223
+ "jobs_path": "jobs",
224
+ "repos": [
225
+ {
226
+ "name": "landing-page",
227
+ "path": "../landing-page",
228
+ "integration_branch": "develop",
229
+ "branch_template": "feature/{topic}",
230
+ "integration_strategy": "ff",
231
+ "commit_subject_template": "{type}({scope}): {title}",
232
+ "merge_message_template": "Merge branch '{branch}' into {target}",
233
+ "setup": {
234
+ "install": true,
235
+ "build": false
236
+ }
237
+ }
238
+ ]
239
+ }
270
240
  }
271
- ]
241
+ }
272
242
  ```
273
243
 
274
- 最初の作業を起票して個票へ完了条件を書いたら、Claude Code の executor と reporter を指定して実行できます。
275
-
276
- ```bash
277
- npx specdojo register add \
278
- --project prj-0001 \
279
- --type todo \
280
- --title "最初のタスク"
281
- npx specdojo exec run \
282
- --project prj-0001 \
283
- --register PJR-XXXX \
284
- --worktree \
285
- --executor-by claude-executor \
286
- --reporter-by claude-reporter
287
- ```
244
+ `install: true` は追跡済み `package-lock.json` ごとに `npm ci` を行います。変更後の `.specdojo/specdojo.config.json` は、exec 実行前にプロジェクトの `develop` に commit してください。
288
245
 
289
- 実行後は両方のリポジトリの commit とプロダクトの動作を確認します。
246
+ 対応する手動確認・ワークスペース生成コマンド:
290
247
 
291
248
  ```bash
292
- git -C ../app1 log --oneline -1
293
- git log --oneline -1
294
- npm --prefix ../app1 run dev
295
- ```
296
-
297
- 人が result と成果物を確認し、気づいた改善を次の `todo` や `issue` として残してから、元の登録項目を close します。
249
+ # プロジェクト設定と repos の確認
250
+ npx specdojo project list
298
251
 
299
- ```bash
300
- npx specdojo register add \
301
- --project prj-0001 \
302
- --type todo \
303
- --title "次の改善" \
304
- --commit
305
- npx specdojo register close \
306
- --project prj-0001 \
307
- --id PJR-XXXX \
308
- --conclusion "完了条件を満たした" \
309
- --commit
252
+ # VS Code マルチルートワークスペースの生成
253
+ npx specdojo config scaffold --workspace --project prj-0001
310
254
  ```
311
255
 
312
- `@specdojo/docs-lint` は初期設定に必須ではありません。SpecDojo 文書向けの remark プラグインと検証コマンドを使う場合だけ追加します。
256
+ </details>
313
257
 
314
- ```bash
315
- npm install --save-dev @specdojo/docs-lint
316
- ```
258
+ ## 3. registerをユースケース別に使う
317
259
 
318
- リポジトリルートの `.remarkrc.yaml` から次のように公開 export を参照できます。
260
+ register(登録簿)は、問題・判断・作業を個票として残し、追跡する入口です。
261
+ ここでは `../landing-page` を題材に、初学者がよく直面する 3 つのユースケース(機能追加の todo、不具合の issue、方針決定の decision)を対話で進めます。
319
262
 
320
- ```yaml
321
- plugins:
322
- - remark-parse
323
- - "@specdojo/docs-lint/remark/no-unescaped-angle-placeholder"
324
- ```
263
+ > [!NOTE]
264
+ > 掲載している FAQ 追加、メニュー不具合、問い合わせフォーム方針の各事例は、ガイド用のサンプルであり実プロジェクトの事実ではありません。
325
265
 
326
- 文書 lint の全設定例と検証コマンドは [[specdojo:docs-editing-guide|ドキュメント編集ガイド]] を参照してください。
266
+ ### 3.1. 機能追加を起票する(todo)
327
267
 
328
- ### 2.1. 個別に設定する場合
268
+ #### 前提
329
269
 
330
- 各設定を個別に管理したい場合は、従来どおり `config init` と各 scaffold を順に実行できます。
270
+ - LP にユーザーから寄せられる疑問に答える「よくある質問(FAQ)」セクションをページ下部に追加したい。
271
+ - 目的と完了条件を定めて作業を追跡したい。
331
272
 
332
- ```bash
333
- # チャット:「<project-id> の SpecDojo 設定を初期化して」
334
- npx specdojo config init
335
- ```
273
+ #### 具体的対話
336
274
 
337
- `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設定リファレンス]] で確認できます。
275
+ ```chat
276
+ あなた: LP によくある質問(FAQ)セクションを追加したいので、todo を起票してほしいです。
338
277
 
339
- 通常の `init` と `config init` は、markdownlint の設定がなければリポジトリ直下に
340
- `.markdownlint.yaml` も作ります。日本語の長い行などを許容するため、MD013・MD024・MD033・MD036・MD041・MD060
341
- を無効にし、ほかの記法検査は維持します。既存の設定は上書きしません。既存の利用リポジトリでも
342
- `npx specdojo config init --dry-run` で確認してから `npx specdojo config init` を再実行すると、
343
- 不足する設定を追加できます。設定がないままでも、exec の result の commit 前検査は同じ基本規則を使います。
344
- 既存設定で MD013 が有効ならその指定を優先するため、長い行を許容する場合は利用側の設定で
345
- `MD013: false` を指定してください。CLI2 と hook の設定の関係は
346
- [[specdojo:command-reference|CLIコマンドリファレンス]] を参照してください。
278
+ オーケストレーター: FAQ セクション追加の todo を起票します。登録項目について確認させてください:
279
+ ・タイトル: 「よくある質問(FAQ)セクションを追加する」
280
+ ・topic(個票ファイル名や作業ブランチ名に使われます): add-faq-section
281
+ ・優先度: medium(通常)でよろしいですか?
282
+ ・完了期日(due_on): 目安の日付はありますか?(未定なら空欄にします)
283
+ ・難しさ(difficulty): 既存のコンポーネント構成に沿った追加のため medium を推奨します。
284
+ ・担当者(owner): 名簿から選べる nickname を割り当てますか?
347
285
 
348
- プロダクト文書は `app1/docs/ja/product/`、プロジェクト文書は `app1-specdojo/docs/ja/projects/` に置きます。同梱の SpecDojo の型(Kata)は `app1-specdojo/docs/ja/specdojo/<種類>s/`、このリポジトリで新しく作る kata はその下の `<kata_authority>/` から解決します。現行実装では1つの項目で両リポジトリを自動統合できないため、プロダクト文書や実装も変更する項目は分けるか、人が統合を管理します。詳細は [ドキュメント構成ガイド](docs-structure-guide.md) の `別リポジトリ構成` を参照してください。
286
+ あなた: 優先度は medium、担当は owner、期日は 2026-11-30、難しさは medium でお願いします。
349
287
 
350
- 成果物と実装を常に同じ変更・履歴として扱う場合に限り、**同一リポジトリ構成**としてプロダクトリポジトリのルートで同じ初期化手順を実行できます。CLI は構成を強制しません。
288
+ オーケストレーター: 承知しました。以下の内容で todo を起票し、登録簿へコミットします:
289
+ ・種別: todo
290
+ ・タイトル: 「よくある質問(FAQ)セクションを追加する」
291
+ ・topic: add-faq-section
292
+ ・優先度: medium、担当: owner、期日: 2026-11-30、難しさ: medium
293
+ ・入力: FAQ の質問項目と掲載方針は未確定。実装前に利用者へ確認する
294
+ 起票を実行してよろしいですか?
351
295
 
352
- agent を使う場合は、設定ファイルを確認した後で利用する provider の設定を配置します。register
353
- だけを使う最小構成では、この手順を省略できます。
296
+ あなた: はい、実行してください。
354
297
 
355
- ```bash
356
- npx specdojo config scaffold --provider <name>
298
+ オーケストレーター: 個票 PJR-FA01(例)を作成し、登録簿へコミットしました。
299
+ 個票ファイル docs/ja/projects/prj-0001/controls/project-register/pjr-fa01-add-faq-section.md を確認してください。
300
+ 個票の「完了条件」に、掲載する質問項目、アコーディオン UI の動作、モバイル表示での検証条件などを記載しておくと、後の AI 実行がスムーズになります。
357
301
  ```
358
302
 
359
- `<name>` には `antigravity`、`claude`、`codex`、`copilot`、`opencode` を指定します。従来の
360
- `specdojo exec scaffold --provider <name>` も互換入口として利用できます。
303
+ #### 得られる結果と確認先
361
304
 
362
- commit 前に文書と SpecDojo の入力を検査する場合は、生成予定と `package.json` への追加内容を
363
- dry-run で確認してから lefthook を配置します。
305
+ - 個票ファイル `docs/ja/projects/prj-0001/controls/project-register/pjr-fa01-add-faq-section.md` が作成されます。
306
+ - `docs/ja/projects/prj-0001/controls/project-register/generated/pjr-index.md`(登録簿一覧)に項目が追加されます。
307
+ - 個票に章立て(概要、完了条件、作業内容、対応結果)が用意されます。
364
308
 
365
- ```bash
366
- npx specdojo config scaffold --lefthook --dry-run
367
- npx specdojo config scaffold --lefthook
368
- npm install
369
- ```
309
+ #### 折りたたんだコマンドと設定差分
310
+
311
+ <details>
312
+ <summary>CLI コマンドと作成された個票の例(クリックで展開)</summary>
370
313
 
371
- 生成した hook は、変更した Markdown と YAML だけを Prettier で整形し、変更した Markdown だけを
372
- markdownlint で検査します。対象 project の `project_register_path` 配下を変更した場合は
373
- `register build`、`catalog_path` 配下を変更した場合は `catalog validate` も実行します。
374
- `catalog_path` がない構成には catalog の検査を生成せず、時間のかかるテストも pre-commit には
375
- 含めません。設定がなければ、同じ基本規則の `.markdownlintrc` と VS Code 向けの
376
- `.markdownlint-cli2.yaml`、provider の agent 定義を検査から外す `.markdownlintignore` も生成します。
377
- `init --lefthook` / `--slidev` もこの配置を使います。既存の `.markdownlint.yaml` などの設定と ignore は
378
- `--force` を付けても保持します。CLI2 の overrides を使う場合は
379
- [[specdojo:command-reference|CLIコマンドリファレンス]] の手順で既存設定を `.markdownlintrc` に移してください。
380
- `lefthook.yml` と `tools/` の既存ファイルは `--force` なしでは上書きしません。
381
- 必要な npm script と devDependencies は書き込み前に表示し、同名の既存項目は `--force` を付けても
382
- 保持します。linked worktree または `node_modules` がない環境では installer が安全に skip するため、
383
- primary worktree で `npm install` または `node tools/install-lefthook.mjs` を実行してください。
384
-
385
- Antigravity CLI を無人実行する場合は、先に dry-run でユーザー設定へ追加する permission rule を確認し、明示的に適用します。このグローバル設定は利用者のすべてのリポジトリに効きます。通常の scaffold はユーザーディレクトリへ触れません。
314
+ 対応する CLI コマンド:
386
315
 
387
316
  ```bash
388
- npx specdojo config scaffold --provider antigravity --global --dry-run
389
- npx specdojo config scaffold --provider antigravity --global
317
+ npx specdojo register add \
318
+ --project prj-0001 \
319
+ --type todo \
320
+ --title "よくある質問(FAQ)セクションを追加する" \
321
+ --topic add-faq-section \
322
+ --description "LP のページ下部に FAQ セクションを追加し、質問と回答、アコーディオン UI、モバイル表示を整える。" \
323
+ --priority medium \
324
+ --owner owner \
325
+ --due 2026-11-30 \
326
+ --difficulty medium \
327
+ --input "FAQ の質問項目と掲載方針は実装前に利用者へ確認する" \
328
+ --commit-type feat \
329
+ --commit-scope add-faq-section \
330
+ --by specdojo-orchestrator \
331
+ --commit
390
332
  ```
391
333
 
392
- Dev Container は任意です。分離された環境が必要な場合だけ、既存の `.devcontainer/` がないことと生成内容を dry-run で確認してから作成します。
334
+ 作成される個票の Frontmatter:
393
335
 
394
- ```bash
395
- npx specdojo devcontainer scaffold --provider <name> --preset recommended --dry-run
396
- npx specdojo devcontainer scaffold --provider <name> --preset recommended
336
+ ```yaml
337
+ ---
338
+ specdojo:
339
+ id: prj-0001:pjr-fa01-add-faq-section
340
+ type: project
341
+ status: draft
342
+ rulebook: specdojo:pjr-rulebook
343
+ part_of:
344
+ - prj-0001:pjr-index
345
+ item_type: todo
346
+ item_status: open
347
+ priority: medium
348
+ owner: owner
349
+ due_on: "2026-11-30"
350
+ ---
397
351
  ```
398
352
 
399
- Dev Container の `<name>` には `antigravity`、`claude`、`codex`、`opencode` を指定します。`--preset recommended` を指定すると、`gh`・tmux・Emacs・Vim・推奨の VS Code 拡張と設定がまとめて設定されます。既存の `.devcontainer/` は通常実行では上書きされません。生成設定は provider の設定ディレクトリと `gh` の認証を名前付きボリュームに保存し、ホストの認証情報・秘密鍵・`.env` はマウントしません。GitHub へのログインは必要なときに利用者がコンテナ内で行います。preset を使わない場合は `gh` の導入と認証 volume を行わず、Ollama 接続、cron、tmux は必要な場合だけ `--ollama`、`--cron`、`--tmux` で個別に足せます。詳しい説明は [[specdojo:remote-host-development-guide]] を参照してください。
353
+ </details>
400
354
 
401
- | preset | 内容 |
402
- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
403
- | `minimal` | 選んだ provider の CLI と SpecDojo の動作に必要な最小構成。preset を省略した場合と同じ。 |
404
- | `recommended` | `minimal` に `gh`、Emacs、Vim、tmux、文書作業向けの VS Code 拡張・設定を追加する。 |
405
- | `full` | `recommended` に ripgrep、fd、fzf、yq、shellcheck、shfmt、Ollama 接続、cron を追加する。fd は `fd-find` package から `fd` コマンドとして利用できる。 |
355
+ ### 3.2. 不具合を調べて直す(issue)
406
356
 
407
- `--ollama`・`--cron`・`--tmux`・`--editor` はどの preset にも個別に追加できます。詳しい説明は [[specdojo:remote-host-development-guide]] を参照してください。
357
+ #### 前提
408
358
 
409
- 設定したプロジェクトを確認します。
359
+ - スマートフォンで LP を閲覧中、ナビゲーションメニューを開いてリンクをタップしてもメニューオーバーレイが閉じない問題が報告された。
360
+ - 症状と再現条件を記録し、原因調査と修正を進めたい。
410
361
 
411
- ```bash
412
- # チャット:「設定済みのプロジェクト一覧を見せて」
413
- npx specdojo project list
414
- ```
362
+ #### 具体的対話
415
363
 
416
- 以降の例では、対象プロジェクトを `<project-id>` と表記します。`current_project` を設定している場合も、最初は対象を確認しやすいように `--project` を明示します。
364
+ ```chat
365
+ あなた: スマホ表示でナビゲーションメニューを開いた後、リンクをタップしてもメニューが閉じない不具合があります。issue を起票して調査したいです。
417
366
 
418
- このガイドの基本手順は、exec 未設定でも完了できるように人が作業する経路を使います。agent に実行させる箇所は、`specdojo init --exec` で設定するか、`.specdojo/agent-members.yaml` と provider を [exec設定ガイド](exec-config-guide.md) に従って個別に設定した後に試してください。
367
+ オーケストレーター: ナビゲーションメニュー不具合の issue を起票します。以下の内容を確認させてください:
368
+ ・タイトル: 「スマホ表示でナビゲーションメニューが閉じない不具合の調査と修正」
369
+ ・topic: fix-mobile-nav-close
370
+ ・優先度: モバイル利用者の閲覧に影響するため high を推奨しますが、いかがでしょうか?
371
+ ・担当者: owner でよろしいですか?
372
+ ・難しさ(difficulty): 原因調査と修正が必要なため medium に設定しますか?
373
+ ・再現条件: 現時点で分かっている再現手順や環境はありますか?
419
374
 
420
- ### 2.2. kataの参照元を確認する
375
+ あなた: 優先度は high、担当は owner、難しさは medium でお願いします。再現条件は画面幅 768px 以下の環境で、メニュー内のアンカーリンクをクリックした際にオーバーレイの閉じる処理が発火していません。
421
376
 
422
- rulebook、standard、recipe、sample、template は、利用リポジトリに同じ ID のファイルがあればそれを優先し、無ければ npm package 内を参照します。初期導入時に kata 一式をコピーする必要はありません。
377
+ オーケストレーター: 承知しました。以下の内容で issue を起票します:
378
+ ・種別: issue
379
+ ・タイトル: 「スマホ表示でナビゲーションメニューが閉じない不具合の調査と修正」
380
+ ・topic: fix-mobile-nav-close
381
+ ・優先度: high、担当: owner、難しさ: medium
382
+ ・再現条件のメモを個票の「問題」セクションに記載します
383
+ 起票を実行してよろしいですか?
423
384
 
424
- ```bash
425
- # npm package から参照中の rulebook を一覧する
426
- npx specdojo kata list --kind rulebook
385
+ あなた: はい、起票してください。
427
386
 
428
- # 登録簿の rulebook を解決順序に従って表示する
429
- npx specdojo kata show specdojo:pjr-rulebook
387
+ オーケストレーター: 個票 PJR-NV02(例)を作成しました。
388
+ 課題ログ(docs/ja/projects/prj-0001/controls/generated/pm-issue-log.md)にも登録されました。
389
+ 調査結果や修正方針が定まったら、個票の「原因」「影響」「対応結果」に記録します。
430
390
  ```
431
391
 
432
- プロジェクト固有の変更が必要なファイルだけを正準パスへ eject します。eject 後は同じ ID の `SOURCE` が `node_modules` から `repository` へ変わります。
392
+ #### 得られる結果と確認先
433
393
 
434
- ```bash
435
- npx specdojo kata eject --id specdojo:pjr-rulebook
436
- npx specdojo kata status --kind rulebook
437
- ```
394
+ - 個票ファイル `docs/ja/projects/prj-0001/controls/project-register/pjr-nv02-fix-mobile-nav-close.md` が作成されます。
395
+ - `docs/ja/projects/prj-0001/controls/generated/pm-issue-log.md`(課題ログ)に登録されます。
438
396
 
439
- CLI と同じバージョンで使う `exec-template` と `schema` は npm package 参照固定であり、eject できません。`kata install --all` は docs サイト配信やオフライン運用で全量コピーするときの選択肢で、通常の導入では実行しません。
440
-
441
- ## 3. registerをユースケース別に使う
397
+ #### 折りたたんだコマンドと設定差分
442
398
 
443
- register は、後から追跡したい問題・判断・作業を個票として残す入口です。この章では、よくある状況ごとに「こんなとき」「チャットでの頼み方」「コマンド」を並べます。type の詳しい選び方と状態遷移は [登録簿運用ガイド](register-operation-guide.md)、approach と実行 pipeline の詳細は [exec運用ガイド](exec-operation-guide.md) を参照してください。複数の機能を組み合わせたシナリオから読みたい場合は [[specdojo:use-case-guide|ユースケース別ガイド]] へ進んでください。
399
+ <details>
400
+ <summary>CLI コマンドと課題ログの反映例(クリックで展開)</summary>
444
401
 
445
- 初期設定で register を作らなかった場合は、先に `.specdojo/specdojo.config.json` の `project_register_path` を設定して登録簿を用意します。
402
+ 対応する CLI コマンド:
446
403
 
447
404
  ```bash
448
- # チャット:「<project-id> の登録簿を用意して」
449
- npx specdojo register scaffold --project <project-id>
405
+ npx specdojo register add \
406
+ --project prj-0001 \
407
+ --type issue \
408
+ --title "スマホ表示でナビゲーションメニューが閉じない不具合の調査と修正" \
409
+ --topic fix-mobile-nav-close \
410
+ --description "画面幅768px以下でメニュー内リンクを選んでもナビゲーションオーバーレイが閉じない。原因調査と修正を行う。" \
411
+ --input "再現条件: 画面幅768px以下でメニューを開き、アンカーリンクを選択する" \
412
+ --priority high \
413
+ --owner owner \
414
+ --difficulty medium \
415
+ --by specdojo-orchestrator \
416
+ --commit
450
417
  ```
451
418
 
452
- コマンドの `<project-id>`、`<PJR-ID>`、`<deliverable-doc-id>`、`<kata-doc-id>` は実際の値に置き換えます。`register add` が表示した `PJR-XXXX` を、続く `exec run` で使います。起票と同時に commit まで行う必要がある場合は `register add` に `--commit` を付けます。
419
+ 生成される課題ログの例:
453
420
 
454
- ### 3.1. 作業を起票してAIに任せる
421
+ ```markdown
422
+ | ID | ステータス | タイトル | 優先度 | 担当 |
423
+ | -------- | ---------- | -------------------------------------------------------------- | ------ | ----- |
424
+ | PJR-NV02 | open | スマホ表示でナビゲーションメニューが閉じない不具合の調査と修正 | high | owner |
425
+ ```
455
426
 
456
- **こんなとき:** 完了条件を書ける作業を todo として追跡し、難しさに合う agent へ安全に任せたいとき。
427
+ </details>
457
428
 
458
- `difficulty` は agent の能力や作業範囲から選びます。`exec run` は `.specdojo/exec-defaults.yaml` の `routing` に同じ難しさの設定があれば、その executor・reporter・rate limit 対応を使います。`--executor-by` などをコマンドで指定した場合は、その指定が優先されます。
429
+ ### 3.3. 実装方針を比較して決める(decision)
459
430
 
460
- | `difficulty` | 目安 | 振り分け |
461
- | ------------ | ------------------------------------------------ | ----------------------------------------------- |
462
- | `hard` | 設計判断、広い影響範囲、複数ファイルの難しい変更 | `routing.hard`。推論力の高い agent を割り当てる |
463
- | `medium` | 手順と完了条件が明確な通常の実装・文書変更 | `routing.medium`。標準の executor を割り当てる |
464
- | `easy` | 範囲が狭く、機械的で、失敗時の影響が小さい変更 | `routing.easy`。軽量な executor を割り当てる |
431
+ #### 前提
465
432
 
466
- ```bash
467
- # チャット:「中くらいの難しさの todo『検索結果の空表示を直す』を起票して、worktree で agent に任せて」
468
- npx specdojo register add \
469
- --project <project-id> \
470
- --type todo \
471
- --title "検索結果の空表示を直す" \
472
- --topic fix-empty-search-result \
473
- --difficulty medium
474
- npx specdojo exec run \
475
- --project <project-id> \
476
- --register <PJR-ID> \
477
- --worktree
478
- ```
433
+ - LP に問い合わせフォームを設置するにあたり、複数の選択肢(外部フォームサービス、自前サーバーレス関数、mailto リンクなど)があり、トレードオフを比較して決定したい。
479
434
 
480
- 成功すると個票は `review` になります。成果物と result を人が確認した後、`register close` で完了させます。
435
+ #### 具体的対話
481
436
 
482
- ### 3.2. 問題を調べて直す
437
+ ```chat
438
+ あなた: 問い合わせフォームの実装方針をいくつか比較して決めたいので、decision を起票して相談したいです。
483
439
 
484
- **こんなとき:** 症状は分かっているが、原因や直し方を調べる必要があるとき。issue の個票へ問題、影響、原因、対応結果を残します。
440
+ オーケストレーター: 問い合わせフォーム実装方針の decision を起票します。確認事項です:
441
+ ・タイトル: 「問い合わせフォームの実装方針を比較・決定する」
442
+ ・topic: contact-form-strategy
443
+ ・担当者: 名簿から選べる nickname を割り当てますか?
444
+ ・比較検討する選択肢の候補として、以下を個票に整理してよろしいでしょうか:
445
+ - 案 A: 外部フォームサービス(Formspree や Google Forms 等)の埋め込み連携
446
+ - 案 B: サーバーレス関数(API エンドポイント)による自前送信処理の実装
447
+ - 案 C: mailto リンクまたは問い合わせメールアドレスの掲示のみ
485
448
 
486
- ```bash
487
- # チャット:「issue『CSV 出力で文字化けする』を起票して、難しさ hard で調査と修正を任せて」
488
- npx specdojo register add \
489
- --project <project-id> \
490
- --type issue \
491
- --title "CSV 出力で文字化けする" \
492
- --topic csv-encoding \
493
- --difficulty hard
494
- npx specdojo exec run \
495
- --project <project-id> \
496
- --register <PJR-ID> \
497
- --worktree
498
- ```
449
+ あなた: 担当は owner、選択肢はその 3 つで比較を作成してください。
499
450
 
500
- 原因調査だけで終えず、個票の完了条件に再現条件、修正範囲、検証方法を書いてから実行します。
451
+ オーケストレーター: 以下の内容で decision を起票します:
452
+ ・種別: decision
453
+ ・タイトル: 「問い合わせフォームの実装方針を比較・決定する」
454
+ ・topic: contact-form-strategy
455
+ ・担当: owner
456
+ 起票を実行してよろしいですか?
501
457
 
502
- ### 3.3. 決めることを残す
458
+ あなた: お願いします。
503
459
 
504
- **こんなとき:** まだ答えがない論点を question として残したいとき、または選択肢・採択理由を decision として記録したいとき。
460
+ オーケストレーター: 個票 PJR-CF03(例)を作成しました。各選択肢の長所・短所を個票に整理しました:
461
+ - 案 A: 導入が迅速でサーバー保守不要。外部サービスの利用規約や制限がトレードオフ。
462
+ - 案 B: デザインと挙動を完全制御できるが、スパム対策やバックエンド保守が必要。
463
+ - 案 C: 実装工数ゼロだが、メールクライアント起動の手間とアドレス収集スパムのリスク。
464
+ 初期リリースとしてはどの方針を採用しますか?採択理由と合わせてご指示ください(オーケストレーターが勝手に採択案を決定することはありません)。
505
465
 
506
- ```bash
507
- # チャット:「question『支払い方法をどこまで扱うか』を起票して」
508
- npx specdojo register add \
509
- --project <project-id> \
510
- --type question \
511
- --title "支払い方法をどこまで扱うか" \
512
- --topic payment-scope
466
+ あなた: 保守負荷を抑えて最短で安全に開始したいため、案 A(外部フォームサービス連携)を採用します。
513
467
 
514
- # チャット:「decision『初期リリースの支払い方法を決める』を起票して」
515
- npx specdojo register add \
516
- --project <project-id> \
517
- --type decision \
518
- --title "初期リリースの支払い方法を決める" \
519
- --topic decide-payment-methods
520
- ```
468
+ オーケストレーター: 承知しました。以下の内容で個票を更新し、decision を完了(decided)にしてよろしいですか?
469
+ ・決定内容: 「案 A: 外部フォームサービスの埋め込み連携を採用」
470
+ ・採択理由: 「保守工数の削減とスパム対策の両立」
521
471
 
522
- question から decision、仕様書への反映、後日の変更までを一度通す場合は [[#1-10分で体験する--仕様の判断台帳|1. 10分で体験する — 仕様の判断台帳]] の流れを使います。decision は agent に判断させる実行対象ではなく、人が選択肢と理由を確認して `register close` します。
472
+ あなた: はい、完了してください。
523
473
 
524
- ### 3.4. 合意した範囲を変える
474
+ オーケストレーター: decision PJR-CF03 を完了(decided)としてクローズしました。
475
+ 決定ログ(docs/ja/projects/prj-0001/controls/generated/pm-decision-log.md)に記録されました。
476
+ ```
525
477
 
526
- **こんなとき:** 決定済みの仕様、スコープ、成果物へ変更を加え、理由と影響を追跡したいとき。
478
+ #### 得られる結果と確認先
527
479
 
528
- ```bash
529
- # チャット:「change-request『交通系電子マネーを支払い方法に加える』を起票して、影響を確認して反映して」
530
- npx specdojo register add \
531
- --project <project-id> \
532
- --type change-request \
533
- --title "交通系電子マネーを支払い方法に加える" \
534
- --topic add-ic-card-payment \
535
- --difficulty medium
536
- npx specdojo exec run \
537
- --project <project-id> \
538
- --register <PJR-ID> \
539
- --worktree
540
- ```
480
+ - 個票ファイル `docs/ja/projects/prj-0001/controls/project-register/pjr-cf03-contact-form-strategy.md` に選択肢・決定内容・採択理由が記録され、ステータスが `decided` になります。
481
+ - `docs/ja/projects/prj-0001/controls/generated/pm-decision-log.md`(決定ログ)に反映されます。
541
482
 
542
- 個票の `変更要求`、`影響評価`、`審査・決定` を埋め、元の decision や仕様書を参照できるようにします。
483
+ #### 折りたたんだコマンドと設定差分
543
484
 
544
- ### 3.5. リスクと気づきを残す
485
+ <details>
486
+ <summary>CLI コマンドと決定ログの反映例(クリックで展開)</summary>
545
487
 
546
- **こんなとき:** 発生前に対応を追跡するなら risk、対応や判断を要求しない観察記録なら note として残したいとき。
488
+ 起票と完了の CLI コマンド:
547
489
 
548
490
  ```bash
549
- # チャット:「risk『移行日に旧端末が残る』を起票して」
491
+ # decision の起票
550
492
  npx specdojo register add \
551
- --project <project-id> \
552
- --type risk \
553
- --title "移行日に旧端末が残る" \
554
- --topic legacy-terminal-on-migration \
555
- --priority high
493
+ --project prj-0001 \
494
+ --type decision \
495
+ --title "問い合わせフォームの実装方針を比較・決定する" \
496
+ --topic contact-form-strategy \
497
+ --description "問い合わせフォームの方式を比較し、選択肢・トレードオフ・採択理由を記録する。" \
498
+ --input "候補: 外部フォームサービス、自前サーバーレス関数、mailtoリンク" \
499
+ --owner owner \
500
+ --by specdojo-orchestrator \
501
+ --commit
556
502
 
557
- # チャット:「note『検証環境では朝に負荷が上がる』を記録して」
558
- npx specdojo register add \
559
- --project <project-id> \
560
- --type note \
561
- --title "検証環境では朝に負荷が上がる" \
562
- --topic morning-load-observation
503
+ # 個票編集後のクローズ(decided への遷移)
504
+ npx specdojo register close \
505
+ --project prj-0001 \
506
+ --id PJR-CF03 \
507
+ --status decided \
508
+ --by owner \
509
+ --conclusion "案 A: 外部フォームサービスの埋め込み連携を採用(保守工数削減とスパム対策両立)" \
510
+ --commit
563
511
  ```
564
512
 
565
- risk は必要なら `exec run --register` で軽減策を実行できます。note は `open` のまま追記する記録で、close や agent 実行の対象にはしません。対応が必要になったら、note を元に todo や issue を起票します。
513
+ </details>
566
514
 
567
- ### 3.6. 成果物を作る・直す
515
+ ### 3.4. その他の種別と運用ガイド
568
516
 
569
- **こんなとき:** 1 文書を、利用できる kata の整備状況に合う進め方で作成・更新したいとき。
517
+ register には上記のほか、以下の種別があります。目的に応じて使い分けてください。詳しい種別の選び方と状態遷移は [[specdojo:register-operation-guide|登録簿運用ガイド]] を参照してください。
570
518
 
571
- | `approach` | 選ぶ状況 |
572
- | --------------- | ---------------------------------------------------------------- |
573
- | `fully-guided` | rulebook・recipe・sample・template が揃い、すべてを基準に進める |
574
- | `recipe-guided` | recipe を主な手順として使い、ほかの kata が未整備でも進める |
575
- | `retrofit` | 先にある実装や現行動作を調べ、その証拠から成果物を作成・更新する |
519
+ | 種別 | 主な用途 | 完了時の状態 |
520
+ | ---------------- | -------------------------------------- | ------------------ |
521
+ | `todo` | 完了条件を定義して実行する作業項目 | `done` |
522
+ | `issue` | 症状・原因・影響を調査して解決する問題 | `done` |
523
+ | `decision` | 選択肢を比較し理由を残して下す意思決定 | `decided` |
524
+ | `question` | まだ答えの出ていない論点や確認事項 | `decided` |
525
+ | `change-request` | 合意済みの仕様やスコープを変更する要求 | `done` |
526
+ | `risk` | 発生前に備える潜在的な危険・不確実性 | `done` |
527
+ | `note` | 後から参照するための観察記録・メモ | `open`(蓄積) |
528
+ | `epic` | 複数の作業を束ねるトラック単位の大括り | `done`(人が判断) |
576
529
 
577
- ```bash
578
- # チャット:「成果物 <deliverable-doc-id> を fully-guided で直す todo を起票して、agent に任せて」
579
- npx specdojo register add \
580
- --project <project-id> \
581
- --type todo \
582
- --title "対象成果物を実践の型に沿って改訂する" \
583
- --topic revise-deliverable \
584
- --difficulty hard \
585
- --approach fully-guided \
586
- --target <deliverable-doc-id>
587
- npx specdojo exec run \
588
- --project <project-id> \
589
- --register <PJR-ID> \
590
- --worktree
591
- ```
530
+ ## 4. 発展: worktreeで1タスクを隔離実行する
592
531
 
593
- `recipe-guided`・`freeform`・`retrofit` を使う場合は、上の `--approach fully-guided` を選んだ値へ置き換えます。`--target` は成果物の doc id を 1 件指定します。カタログにある対象は従来どおりカタログの `done_criteria` と個票の完了条件を使います。
532
+ 登録した作業は、AI エージェント(executor / reporter)に委任して実行できます。
533
+ 手元の作業ツリーを保護するため、SpecDojo は Git worktree による**隔離実行**を行います。
594
534
 
595
- カタログがない場合、既存文書は文書索引からパスと frontmatter の `specdojo.rulebook` を辿れます。これから作る文書は、次のようにリポジトリ相対のパスと rulebook ID を個票に保存します。
535
+ ### 前提
596
536
 
597
- ```bash
598
- npx specdojo register add \
599
- --project <project-id> --type todo \
600
- --title "文書を実践の型に沿って作る" --topic create-document \
601
- --approach fully-guided --target <deliverable-doc-id> \
602
- --target-path docs/ja/product/example.md \
603
- --target-rulebook <kata-authority>:example-rulebook
604
- npx specdojo exec plan --project <project-id> --register <PJR-ID>
605
- ```
537
+ - 3.1 で起票した FAQ 追加の todo(`PJR-FA01`)の個票に完了条件が書かれていること。
538
+ - `.specdojo/exec-defaults.yaml` にagent ルーティングが設定され、必要な agent CLI / provider が利用可能であること。初期化で作られた設定を実行前に確認します。
539
+ - プロダクトリポジトリ `../landing-page` の `develop` ブランチが作業可能な状態であること。
606
540
 
607
- `--target-rulebook` の rulebook と、そこから参照する必要な kata は先に用意します。`fully-guided` は `not-needed` と宣言された型を除く一式、`recipe-guided` は recipe が必要です。不足する型は起票時に名前を示して停止します。個票の「完了条件」を具体化してから実行してください。カタログなしの完了基準は個票の完了条件と rulebook です。`retrofit` では調べる実装のパスも個票に明記します。
541
+ ### 具体的対話
608
542
 
609
- パスと rulebook は `register update --target-path <path> --target-rulebook <doc-id>` で更新でき、それぞれ `-` で削除できます。既存文書のパスや `specdojo.rulebook` と指定が食い違う場合は停止します。カタログ設定済みで対象が未登録の場合は、この 2 つを明示したときだけ同じ解決を使います。
543
+ オーケストレーターに起票済みタスクの隔離実行を依頼します。オーケストレーターは実行方式(worktree)、作業ブランチ名、統合先ブランチを提示して承認を得てから実行します。
610
544
 
611
- ### 3.7. 成果物とkataを一組で作る
545
+ ```chat
546
+ あなた: 起票した FAQ 追加の todo(PJR-FA01)を AI に実行させたいです。安全に進めてください。
612
547
 
613
- **こんなとき:** プロジェクトの初期立ち上げで、成果物だけでなく、その成果物を繰り返し作るための rulebook・recipe・sample・template も同じ実行で初期整備したいとき。
548
+ オーケストレーター: PJR-FA01 の AI 実行(exec run)を準備します。以下の計画を確認させてください:
549
+ ・隔離実行: ../landing-page-specdojo-worktrees/<実際に割り当てられる task ID>/ に専用の作業環境を隔離作成します。
550
+ ・Git flow 規則の適用: 設定済みのブランチ規則に従い、プロダクト側(../landing-page)に作業ブランチ feature/add-faq-section を作成します。
551
+ ・実行 agent: 設定済み routing から選ばれる executor と reporter を割り当てます。
552
+ ・統合方式: 設定された統合方式で処理します。exec 開始前に実際の統合先と統合手順を確認します。
553
+ この計画で AI 実行を開始してよろしいですか?
614
554
 
615
- ```bash
616
- # チャット:「成果物 <deliverable-doc-id> と必要な kata 一式を bootstrap で作る todo を起票して、agent に任せて」
617
- npx specdojo register add \
618
- --project <project-id> \
619
- --type todo \
620
- --title "成果物と実践の型を初期整備する" \
621
- --topic bootstrap-deliverable-kata \
622
- --difficulty hard \
623
- --approach bootstrap \
624
- --target <deliverable-doc-id>
625
- npx specdojo exec run \
626
- --project <project-id> \
627
- --register <PJR-ID> \
628
- --worktree
629
- ```
555
+ あなた: はい、実行を開始してください。
630
556
 
631
- カタログなしの `bootstrap` では、上の起票に `--target-path docs/ja/product/example.md --target-rulebook <kata-authority>:example-rulebook` を追加し、設定ファイルに `kata_authority` を指定します。新しい rulebook ID が必要で、既存 ID は受け付けません。plan は `docs/ja/specdojo/<kind>s/<kata-authority>/example-<kind>.md` に未作成の kata を示し、成果物の `specdojo.rulebook` と rulebook の kata 参照を記入するよう指示します。
557
+ オーケストレーター: 実行を開始しました。
558
+ [1/4] worktree を準備し、プロダクト側に feature/add-faq-section を作成しました。
559
+ [2/4] executor が承認された完了条件に沿って実行し、適用された検証結果を記録しました。
560
+ [3/4] reporter が実行結果(evidence / result)を作成しました。
561
+ [4/4] 設定された方式で統合し、実行記録に統合結果を残しました。
562
+ 個票 PJR-FA01 のステータスが review(人間の講評待ち)になりました。以下の確認をお願いします:
563
+ 1. プロダクト側(../landing-page)のコミットログ(git log -1)と変更差分
564
+ 2. 実行結果ファイル(docs/ja/projects/prj-0001/execution/runs/register/PJR-FA01/.../result.md)
565
+ 3. ローカル開発サーバーでの FAQ 表示とアコーディオン動作
566
+ 確認後、問題がなければ完了(close)をご指示ください。
632
567
 
633
- `finalize`・`bootstrap-finalize` は既存文書だけを対象にできます。カタログなしでは個票の完了条件をチェック表にし、人が成果物を確定します。`bootstrap-finalize` は frontmatter から辿る kata 一式も確定対象です。`cross-deliverable-dedup` は成果物群を扱うためカタログが必要です。
568
+ あなた: プロダクトのコミットとローカル表示を確認しました。FAQ が期待通り動作しています。完了してください。
634
569
 
635
- `bootstrap` は初期整備用です。既に信頼できる kata が揃っている成果物の通常改訂には `fully-guided` を使います。
570
+ オーケストレーター: 完了条件の達成を確認しました。PJR-FA01 を完了(done)としてクローズし、登録簿へコミットします。よろしいですか?
636
571
 
637
- ### 3.8. kataを直す
572
+ あなた: はい、クローズしてください。
638
573
 
639
- **こんなとき:** 成果物ではなく、作り方・手順・例・雛形そのものを改善したいとき。
574
+ オーケストレーター: PJR-FA01 を完了としてクローズしました。お疲れ様でした!
575
+ ```
640
576
 
641
- | 直す kata | `approach` |
642
- | --------- | ---------------------- |
643
- | rulebook | `rulebook-maintenance` |
644
- | recipe | `recipe-maintenance` |
645
- | sample | `sample-maintenance` |
646
- | template | `template-maintenance` |
577
+ ### 得られる結果と確認先
647
578
 
648
- ```bash
649
- # チャット:「rulebook <kata-doc-id> を見直す todo を起票して、agent に任せて」
650
- npx specdojo register add \
651
- --project <project-id> \
652
- --type todo \
653
- --title "成果物の作成ルールを見直す" \
654
- --topic maintain-rulebook \
655
- --difficulty hard \
656
- --approach rulebook-maintenance \
657
- --target <kata-doc-id>
658
- npx specdojo exec run \
659
- --project <project-id> \
660
- --register <PJR-ID> \
661
- --worktree
662
- ```
579
+ - 成功時は設定された統合先に変更が統合されます。コミット件名の scope は未指定なら空です。`feat(add-faq-section): ...` を使う場合は登録時に `--commit-scope add-faq-section` を指定します。
580
+ - `docs/ja/projects/prj-0001/execution/runs/register/PJR-FA01/<run ID>/` に `result.md` が生成され、変更ファイル一覧や検証記録が保存されます。
581
+ - 個票 `PJR-FA01` のステータスが `review` から `done` に遷移します。
663
582
 
664
- ほかの kata を直す場合は、表に従って `--approach` を置き換えます。`--target` には文書索引で解決でき、approach の種別と一致する kata の doc id を 1 件だけ指定します。
583
+ ### 折りたたんだコマンドと設定差分
665
584
 
666
- ### 3.9. 既存成果物からkataを新しく作る
585
+ <details>
586
+ <summary>AI 実行と確認の手動 CLI コマンド(クリックで展開)</summary>
667
587
 
668
- **こんなとき:** 成果物は既にあり、その実績を手本に rulebook など 1 種類の kata だけを新しく作りたいとき。
588
+ 手動で実行する場合のコマンド:
669
589
 
670
590
  ```bash
671
- # チャット:「成果物 <deliverable-doc-id> を手本に <kata-id> の rulebook を新しく作る todo を起票して、agent に任せて」
672
- npx specdojo register add \
673
- --project <project-id> \
674
- --type todo \
675
- --title "既存成果物からrulebookを作る" \
676
- --topic author-rulebook \
677
- --difficulty hard \
678
- --approach rulebook-authoring \
679
- --target <kata-authority>:<name>-rulebook \
680
- --source <deliverable-doc-id>
591
+ # 1 タスクを worktree で隔離実行
681
592
  npx specdojo exec run \
682
- --project <project-id> \
683
- --register <PJR-ID> \
593
+ --project prj-0001 \
594
+ --register PJR-FA01 \
684
595
  --worktree
685
- ```
686
-
687
- `--target` は新しい kata ID、`--source` は任意の読み取り専用の手本です。`--source` は繰り返し指定でき、文書索引の doc id、プロジェクトリポジトリの相対パス、`repos` に宣言した `<repo>:<path>` を受け付けます。パスにはファイル、ディレクトリ、`*.md` などの glob を書けます。たとえば `--source docs/ja/lessons/01-chase/README.md` や `--source 'coderdojo-lessons:lessons/**/*.md'` の形です。カタログがない project でも使えますが、手本が見つからない場合と展開後に 100 ファイルを超える場合は停止します。互換性のため、2 個目以降の `--target` も手本として引き続き受け付けます。
688
-
689
- 成果物も型もまだない初期立ち上げには `bootstrap` を使います。手本なしで kata だけを作る場合は `--source` を省略します。recipe / sample / template では `approach` と ID の末尾を同じ種類へ置き換えます。手本がカタログ成果物で該当参照が `undecided` または未記入の場合だけ参照を新しい kata ID へ更新し、カタログ外とプロダクトリポジトリの手本は変更しません。
690
-
691
- ### 3.10. 統合後にreviewのagentへ確かめさせる
692
596
 
693
- **こんなとき:** worktree の成果を統合した後、完了条件・result・差分・検証結果を別の review agent に照合させたいとき。
597
+ # プロダクトリポジトリの統合コミットを確認
598
+ git -C ../landing-page log -1 --stat
694
599
 
695
- ```bash
696
- # チャット:「todo または issue <PJR-ID> を worktree で実行し、統合後の review まで任せて」
697
- npx specdojo exec run \
698
- --project <project-id> \
699
- --register <PJR-ID> \
700
- --worktree \
701
- --post-review
600
+ # 個票の完了クローズ
601
+ npx specdojo register close \
602
+ --project prj-0001 \
603
+ --id PJR-FA01 \
604
+ --conclusion "FAQ セクションの実装とローカルでの表示・動作確認を完了" \
605
+ --commit
702
606
  ```
703
607
 
704
- `--post-review` は worktree 実行でだけ使えます。todo と issue は判定が `complete` または `complete-with-findings` なら自動 close され、`incomplete` なら `waiting` に戻ります。question、decision、および SpecDojo 自身のコードを変えた項目は自動 close されません。
608
+ </details>
705
609
 
706
- ### 3.11. 夜の間に流す
610
+ ## 5. 発展: 成果物カタログからscheduleへ展開する
707
611
 
708
- **こんなとき:** 人が内容と完了条件を確認した todo・issue だけを、夜間に worktree と post-review 付きでまとめて流したいとき。
612
+ 個別の todo / issue 管理から進み、LP の仕様書・設計書群(要件定義、画面設計、運用手順など)を体系的に計画し、依存関係に沿って段階的に作成する経路です。
709
613
 
710
- ```bash
711
- # チャット:「todo または issue <PJR-ID> を夜間実行してよい印に更新して」
712
- npx specdojo register update \
713
- --project <project-id> \
714
- --id <PJR-ID> \
715
- --autopilot approved \
716
- --commit
614
+ ### 5.1. 成果物カタログを作成する
717
615
 
718
- # チャット:「<project-id> の承認済み項目を、最大10件、並列2件で夜間実行して」
719
- npx specdojo orchestrator night \
720
- --project <project-id> \
721
- --max-items 10 \
722
- --parallel 2 \
723
- --max-consecutive-failures 2
724
- ```
616
+ #### 前提
725
617
 
726
- 夜間 queue に入るのは `autopilot: approved` の付いた `open` の todo と issue だけです。まず対象を確認する場合は、`orchestrator night` に `--dry-run` を付けます。朝の報告には close、`waiting`、失敗した項目がまとめられます。
618
+ - 仕様書・設計書群を体系的に管理したい。
619
+ - `.specdojo/specdojo.config.json` に `catalog_path`(例: `010-deliverables-catalog`)が設定されていること。
727
620
 
728
- ### 3.12. 止まった項目を再開する
621
+ #### 具体的対話
729
622
 
730
- **こんなとき:** register の worktree 実行が agent、検証、reporter、統合の途中で止まり、残っている成果を生かして続けるか、破棄して最初からやり直したいとき。
623
+ ```chat
624
+ あなた: LP の仕様書や設計ドキュメントを体系的に揃えたいです。成果物カタログを作って進めるにはどうすればよいですか?
731
625
 
732
- ```bash
733
- # チャット:「<PJR-ID> を止まった段から再開して」
734
- npx specdojo exec run \
735
- --project <project-id> \
736
- --register <PJR-ID> \
737
- --worktree \
738
- --resume
626
+ オーケストレーター: 現在の設定を調べます。`catalog_path` が未設定のため、成果物カタログ(dct-*.yaml)の保存先 `010-deliverables-catalog` を提案します。Schedule / execution の出力先、名簿と role 対応、routine / Job の置き場所も次の段階に必要です。設定差分を確認してください。
627
+ 以下のカタログ内容も確認させてください:
628
+ ・規模(size): 最小限の基本構成が揃う small サイズで生成しますか?(後から成果物の追加や削除が可能です)
629
+ ・配置場所: .specdojo/specdojo.config.json の catalog_path(010-deliverables-catalog)に配置します。
630
+ まず small サイズのカタログ雛形を生成し、構文を検証してよろしいですか?
739
631
 
740
- # チャット:「<PJR-ID> は親検証の失敗を直すため、executor から再開して」
741
- npx specdojo exec run \
742
- --project <project-id> \
743
- --register <PJR-ID> \
744
- --worktree \
745
- --resume \
746
- --resume-from executor
632
+ あなた: まず `catalog_path` が未設定なら追加し、`roles_path`・`schedule_path`・`execution_path`・`routines_path`・`jobs_path` と名簿・役割ファイルを準備します。差分と初期生成物を確認してから、small サイズのカタログを生成してください。
747
633
 
748
- # チャット:「<PJR-ID> の残っている worktree を破棄し、最初からやり直して」
749
- npx specdojo exec run \
750
- --project <project-id> \
751
- --register <PJR-ID> \
752
- --worktree \
753
- --force-restart
634
+ オーケストレーター: 成果物カタログの生成、検証、および成果物雛形の生成を実行しました。
635
+ ・dct-project-definition.yaml(プロジェクト定義カタログ)を作成しました。
636
+ ・カタログが参照する成果物ファイル(docs/ja/projects/prj-0001/010-deliverables/ 配下)を生成しました。
637
+ プロジェクトのスコープに合わせてカタログ内の成果物定義を調整できます。
754
638
  ```
755
639
 
756
- | 指定 | 使い分け |
757
- | ------------------------ | -------------------------------------------------------------------- |
758
- | `--resume` | checkpoint が示す executor、reporter、統合の段から再開する |
759
- | `--resume-from executor` | reporter から再開可能だが、成果物を executor に直させる必要がある |
760
- | `--force-restart` | 再開用 worktree と未統合の成果を破棄して、項目全体を最初から実行する |
761
-
762
- `--force-restart` は未統合の成果を破棄します。先に evidence と agent のログを確認し、再利用しないと判断した場合だけ指定します。
640
+ #### 得られる結果と確認先
763
641
 
764
- ### 3.13. 別のproject・別のリポジトリへ起票する
642
+ - `docs/ja/projects/prj-0001/010-deliverables-catalog/dct-project-definition.yaml` が作成されます。
643
+ - `docs/ja/projects/prj-0001/010-deliverables/` 配下に成果物 Markdown 雛形が生成されます。
644
+ - `docs/ja/projects/prj-0001/010-deliverables-catalog/generated/` にカタログ派生ビューが出力されます。
765
645
 
766
- **こんなとき:** 作業中の気づきが別 project の責務であり、その project の登録簿と統合ブランチへ、起票元との関係を残して渡したいとき。
646
+ #### 折りたたんだコマンドと設定差分
767
647
 
768
- 同じリポジトリ内の別 project には、対象 project と起票元を project 修飾 ID で指定します。
769
-
770
- ```bash
771
- # チャット:「prj-0001:PJR-AB12 から派生した todo を prj-0002 へ起票して commit して」
772
- npx specdojo register add \
773
- --project prj-0002 \
774
- --type todo \
775
- --title "共通 API の変更を追跡する" \
776
- --topic shared-api-change \
777
- --from prj-0001:PJR-AB12 \
778
- --commit
779
- ```
648
+ <details>
649
+ <summary>カタログ操作と project 設定差分(クリックで展開)</summary>
780
650
 
781
- 別リポジトリの場合は、呼び出し元の `.specdojo/specdojo.config.json` のトップレベルへ相手を宣言します。
651
+ `projects.prj-0001` に追加する設定キーの例です。`base_path` からの相対パスで解決されます。
782
652
 
783
653
  ```json
784
654
  {
785
- "external_projects": {
786
- "customer": {
787
- "path": "../customer-specdojo",
788
- "project_id": "prj-0002"
789
- }
790
- }
655
+ "catalog_path": "010-deliverables-catalog",
656
+ "schedule_path": "schedule",
657
+ "execution_path": "execution",
658
+ "members_path": "030-project-management/pm-members.yaml",
659
+ "roles_path": "030-project-management/pm-roles.yaml",
660
+ "routines_path": "routines",
661
+ "jobs_path": "jobs"
791
662
  }
792
663
  ```
793
664
 
794
- 宣言した別名を `--project` に使い、相手側にある起票元は `<別名>:PJR-XXXX` で指定します。
665
+ 初期化後に `030-project-management/pm-members.yaml` と `pm-roles.yaml` を用意します。`pm-roles.yaml` に ROLE code `BA` があることを確認し、利用者の承認を得て `pm-members.yaml` の担当者(例: nickname が `owner` の人)の `roles` に `BA` を割り当てます。strategy の担当引数には ROLE code `BA`、実行時の `--by` には人の nickname(この例では `owner`)を指定します。実行設定を変更したらプロジェクトリポジトリへ commit してから exec を始めます。
795
666
 
796
667
  ```bash
797
- # チャット:「外部 project customer の PJR-AB12 から派生した todo を、customer へ起票して commit して」
798
- npx specdojo register add \
799
- --project customer \
800
- --type todo \
801
- --title "相手側で追跡する" \
802
- --topic remote-follow-up \
803
- --from customer:PJR-AB12 \
804
- --commit
805
- ```
668
+ # 規模別テンプレートからカタログを生成
669
+ npx specdojo catalog scaffold --project prj-0001 --size small
806
670
 
807
- どちらも別 project への起票では `--commit` が必須です。別リポジトリでは、相手に SpecDojo 0.4.2 以上と対象 project の統合ブランチが必要です。push は行わず、close などの状態遷移は対象 project の作業ツリーで行います。
671
+ # カタログの構造と依存関係を検証
672
+ npx specdojo catalog validate --project prj-0001
808
673
 
809
- ### 3.14. issueからdecision、epic、成果物カタログ・Scheduleへ進む
674
+ # カタログが指す成果物ファイル本体を生成
675
+ npx specdojo deliverable scaffold --project prj-0001
810
676
 
811
- プロジェクト立ち上げ時に、問題、判断、実施作業がまだ混在している場合は、次の順で具体化します。register が起点と完了の判断を持ち、途中の進み具合は schedule が持ちます。
812
-
813
- ```text
814
- issue(何が問題か)
815
- -> decision(何を対象とするか)
816
- -> epic(track の仕事を起票する)
817
- -> 子 todo(成果物カタログや strategy を作成する)
818
- -> schedule(成果物タスクの実行と進捗)
819
- -> epic を完了する(人が判断)
677
+ # カタログの Markdown 派生ビューをビルド
678
+ npx specdojo catalog build --project prj-0001
820
679
  ```
821
680
 
822
- ```bash
823
- # チャット:「issue『初期スコープと必要成果物が未確定』を起票して」
824
- npx specdojo register add \
825
- --project <project-id> \
826
- --type issue \
827
- --title "初期スコープと必要成果物が未確定" \
828
- --topic clarify-initial-scope
829
-
830
- # チャット:「decision『初期スコープと対象成果物を決定する』を起票して」
831
- npx specdojo register add \
832
- --project <project-id> \
833
- --type decision \
834
- --title "初期スコープと対象成果物を決定する" \
835
- --topic decide-initial-scope
681
+ </details>
836
682
 
837
- # チャット:「launch トラックの epic を起票して」
838
- npx specdojo register add \
839
- --project <project-id> \
840
- --type epic \
841
- --track launch \
842
- --title "プロジェクト定義の仕様整備" \
843
- --topic project-definition
683
+ ### 5.2. トラック戦略を作成する
844
684
 
845
- # チャット:「epic から子 todo『成果物カタログを作成する』を起票して」
846
- npx specdojo register add \
847
- --project <project-id> \
848
- --type todo \
849
- --from <epic-id> \
850
- --title "プロジェクト定義の成果物カタログを作成する" \
851
- --topic create-project-definition-catalog \
852
- --approach catalog-planning \
853
- --target domain:project-definition
854
- ```
685
+ #### 前提
855
686
 
856
- issue の調査結果を decision の選択肢へ、decision の結論を track の `epic` とその子 todo へ引き継ぎます。decision は人が確定します。issue や子 todo は provider 未設定でも `exec plan --project <project-id> --register <PJR-ID>` で計画を確認でき、agent 設定後は `exec run --project <project-id> --register <PJR-ID> --worktree` で実行できます(`epic` 自体は実行対象外です)。
687
+ - カタログの成果物をどのようなフェーズ、担当ロール、所要日数で作成するかを定めるトラック戦略 `sch-strategy-<track>.yaml` を作成すること。
688
+ - `members_path` の名簿(`030-project-management/pm-members.yaml`)と `roles_path` の役割(`030-project-management/pm-roles.yaml`)が準備されていること。
857
689
 
858
- すべての登録項目には type 別の個票が作られ、個票 Frontmatter が構造化フィールドの正本になります。個票内の `_TODO_` を解消してから `register close` すると、個票の文書状態も `ready` になります。成果物カタログ作成の todo は、次章で `dct-<domain>.yaml` を作成・検証した後に完了させます。todo の完了により `catalog_status` が `primary` と導出され、strategy 作成と Schedule への展開(`schedule build --track launch`)が可能になります。成果物タスクの途中の進捗は schedule の依存グラフで管理し、登録簿に個々の成果物タスクを二重管理しません。トラック完了時に人が `epic` を close します。
690
+ #### 具体的対話
859
691
 
860
- ## 4. 発展: 成果物カタログからscheduleへ展開する
692
+ ```chat
693
+ あなた: カタログの成果物を作成するためのスケジュール戦略を作りたいです。
861
694
 
862
- この経路では、epic の子 todo から成果物カタログ(`dct-<domain>.yaml`)とトラック戦略(`sch-strategy-<track>.yaml`)を作成して Schedule を生成し、依存関係に従ってタスクを実行します。
695
+ オーケストレーター: トラック戦略(sch-strategy-launch.yaml)を生成します。確認事項です:
696
+ ・トラック名: 立ち上げトラックの launch でよろしいですか?
697
+ ・作成担当(default-owner): pm-roles.yaml の ROLE code BA を指定しますか?
698
+ ・ゲート・マイルストーン担当: 同じく ROLE code BA に設定しますか?
699
+ ・担当者: pm-members.yaml の nickname が owner の人の roles に BA が割り当てられていることを確認します。
863
700
 
864
- ### 4.1. 成果物カタログを作成する
701
+ あなた: トラックは launch、作成・ゲート・マイルストーン担当のロールは BA でお願いします。担当者は owner で、roles に BA を割り当て済みです。
865
702
 
866
- 成果物カタログは「何を、どこに作り、何を満たせば完了か」を定義する `dct-<domain>.yaml` です。`.specdojo/specdojo.config.json` の対象 project へ、たとえば `"catalog_path": "010-deliverables-catalog"` を追加してから次の順に実行します。パスの基準と後続の設定キーは [[specdojo:specdojo-config-reference|SpecDojo設定リファレンス]] を参照してください。
703
+ オーケストレーター: sch-strategy-launch.yaml を生成しました。
704
+ 生成したファイルとタスク定義を確認し、task ID・成果物パス・依存関係・owner・execution mode を実際の出力から読み取ります。
705
+ ```
867
706
 
868
- ```bash
869
- # プロジェクト規模に応じた dct-*.yaml をテンプレートから生成する
870
- # チャット:「<project-id> の成果物カタログを small サイズで作成して」
871
- npx specdojo catalog scaffold --project <project-id> --size small
707
+ #### 得られる結果と確認先
872
708
 
873
- # カタログの構造、ID、依存関係などを検証する
874
- # チャット:「成果物カタログを検証して」
875
- npx specdojo catalog validate --project <project-id>
709
+ - `docs/ja/projects/prj-0001/schedule/sch-strategy-launch.yaml` が生成されます。
876
710
 
877
- # カタログが指す成果物ファイル本体を初回だけ生成する
878
- # チャット:「カタログが指す成果物ファイルを一括生成して」
879
- npx specdojo deliverable scaffold --project <project-id>
711
+ #### 折りたたんだコマンドと設定差分
880
712
 
881
- # カタログの Markdown 派生ビューを生成する
882
- # チャット:「カタログの派生ビューをビルドして」
883
- npx specdojo catalog build --project <project-id>
713
+ <details>
714
+ <summary>トラック戦略生成コマンド(クリックで展開)</summary>
884
715
 
885
- # dct-project-definition.yaml の作成 todo を完了する
886
- # チャット:「todo <catalog-todo-id> を『対象成果物を dct-project-definition.yaml に定義し、検証を完了』で完了して」
887
- npx specdojo register close \
888
- --project <project-id> \
889
- --id <catalog-todo-id> \
890
- --conclusion "対象成果物を dct-project-definition.yaml に定義し、検証を完了"
716
+ ```bash
717
+ npx specdojo schedule strategy generate \
718
+ --project prj-0001 \
719
+ --track launch \
720
+ --default-owner BA \
721
+ --gate-owner BA \
722
+ --milestone-owner BA
891
723
  ```
892
724
 
893
- 各コマンドの役割は次のとおりです。
725
+ </details>
894
726
 
895
- | コマンド | 作成・確認するもの | 再実行時の扱い |
896
- | ---------------------- | ------------------------------------------------ | ----------------------------------------------------------------- |
897
- | `catalog scaffold` | 規模別テンプレートから `dct-*.yaml` を作成する | 既存ファイルは上書きしない。作り直す場合だけ `--force` を指定する |
898
- | `catalog validate` | カタログの構造、ID、依存関係を検証する | カタログを変更するたびに実行する |
899
- | `deliverable scaffold` | カタログの `path` が指す成果物ファイル本体を作る | 既存成果物は上書きしない。通常は初期作成時に1回実行する |
900
- | `catalog build` | `generated/dct-*.md` のカタログ派生ビューを作る | 正本の `dct-*.yaml` を変更した後に再実行する |
727
+ ### 5.3. Scheduleを生成する
901
728
 
902
- `--size` には `small` / `medium` / `large` を指定します。`catalog scaffold` 後は、生成された全成果物をそのまま採用するのではなく、プロジェクトのスコープに合わせて `dct-*.yaml` の成果物、依存関係、完了条件を確認してください。
729
+ #### 前提
903
730
 
904
- ### 4.2. トラック戦略を作成する
731
+ - カタログとトラック戦略が存在すること。
905
732
 
906
- `sch-strategy-<track>.yaml` は、成果物カタログを実行タスクへ展開するための生成入力です。成果物カタログが WHAT / DONE を持つのに対し、strategy は対象カタログ、作業フェーズ、担当ロールを定義します。新規 strategy は DCT・Timeline・整備状況判定から `schedule strategy generate` で作成し、既存 strategy の owner や開始日などの人間が決めた項目は再生成時も保持します。
733
+ #### 具体的対話
907
734
 
908
- この段階へ進む前に、対象 project へ `schedule_path`、`execution_path`、`timeline_path`、`members_path`、`roles_path` を追加します。値は [[specdojo:specdojo-config-reference|SpecDojo設定リファレンス]] の設定例を参照し、前節で生成したファイルの配置と合わせてください。
735
+ ```chat
736
+ あなた: スケジュールを生成して、今すぐ着手できるタスクを確認したいです。
909
737
 
910
- `deliverable scaffold` で作成した `pm-members.yaml` の `members` に、タスクを実行する人を登録します。次の例では `<actor>` が BA ロールを担当します。
738
+ オーケストレーター: track launch の内容と出力先(`schedule_path` の既定は docs/ja/projects/prj-0001/schedule)を確認しました。schedule build と exec refresh を実行してよろしいですか?
911
739
 
912
- <details>
913
- <summary>pm-members.yaml への追記例(クリックで展開)</summary>
740
+ あなた: はい、実行してください。
914
741
 
915
- ```yaml
916
- members:
917
- - nickname: <actor>
918
- display_name: Quick Start Operator
919
- email: null
920
- roles: [BA]
921
- type: human
742
+ オーケストレーター: スケジュール(sch-track-launch.yaml)を生成し、exec refresh を実行しました。
743
+ 生成結果から Ready の task ID、成果物パス、owner、execution mode を読み上げます。例示 ID や固定パスを前提にせず、実際の生成内容を確認してください。
922
744
  ```
923
745
 
924
- </details>
746
+ #### 得られる結果と確認先
925
747
 
926
- 先に `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` に定義された主担当ロールへ置き換えてください。
748
+ - `docs/ja/projects/prj-0001/schedule/sch-track-launch.yaml`
749
+ - `docs/ja/projects/prj-0001/execution/generated/ready.json`(着手可能タスク一覧)
927
750
 
928
- ```bash
929
- npx specdojo schedule strategy generate --project <project-id> --track launch \
930
- --default-owner <role> --gate-owner <role> --milestone-owner <role> --dry-run
931
- npx specdojo schedule strategy generate --project <project-id> --track launch \
932
- --default-owner <role> --gate-owner <role> --milestone-owner <role>
933
- ```
934
-
935
- 以下は生成後の strategy 構造を理解するための例です。small の `dct-project-definition.yaml` に含まれる3成果物を依存順に作成・確認し、最初の Ready タスクが `prj-overview` になる構成を示します。
751
+ #### 折りたたんだコマンドと設定差分
936
752
 
937
753
  <details>
938
- <summary>sch-strategy-launch.yaml の全体例(クリックで展開)</summary>
754
+ <summary>スケジュールビルドの CLI コマンド(クリックで展開)</summary>
939
755
 
940
- ```yaml
941
- kind: strategy
942
- id: <project-id>:sch-strategy-launch
943
- type: project
944
- status: ready
945
- title: スケジュール戦略(launch)
946
- rulebook: specdojo:sch-rulebook
947
- track: launch
948
-
949
- scope:
950
- catalogs:
951
- - id: <project-id>:dct-project-definition
952
- path: /docs/ja/projects/<project-id>/010-deliverables-catalog/dct-project-definition.yaml
953
- include_kinds:
954
- - work
955
-
956
- phase_sets:
957
- first-pass:
958
- - id: draft
959
- name: 初稿作成
960
- execution: human
961
- mode: edit
962
- approach: finalize
963
- task_suffix: "010"
964
- duration_days: 1
965
- description: 成果物カタログの完了条件と rulebook に従って成果物を作成・確認する。
966
-
967
- default_phase_set: first-pass
968
-
969
- owner_rules:
970
- - local_ids:
971
- - prj-overview
972
- - prj-scope
973
- - prj-success-criteria-and-acceptance-criteria
974
- owner: BA
756
+ ```bash
757
+ # スケジュールのビルド
758
+ npx specdojo schedule build --project prj-0001 --track launch --force
759
+
760
+ # Ready タスクと CPM の更新
761
+ npx specdojo exec refresh --project prj-0001
975
762
  ```
976
763
 
977
764
  </details>
978
765
 
979
- 主要フィールドの意味は次のとおりです。
766
+ ### 5.4. 1タスクを実行する
980
767
 
981
- | フィールド | 意味 |
982
- | --------------------- | --------------------------------------------------------------------------- |
983
- | `track` | トラックID。ファイル名の `<track>` および `schedule build --track` と揃える |
984
- | `scope.catalogs` | 対象 `dct-<domain>.yaml` のIDと、`/` から始まるリポジトリルート基準パス |
985
- | `scope.include_kinds` | カタログからタスクへ展開する成果物種別。通常は `work` |
986
- | `phase_sets` | 各成果物に適用する作業フェーズ、実行方法、タスク接尾辞、所要日数 |
987
- | `default_phase_set` | 個別指定がない成果物へ適用する既定のフェーズセット |
988
- | `owner_rules` | 成果物の `local_id` と担当ロールの対応 |
768
+ #### 前提
989
769
 
990
- `owner_rules.owner` は `pm-members.yaml` の `roles` と対応させます。複数フェーズ、反復、レビュー、成果物間のゲートを含む実運用向けの設計は [Schedule設計ガイド](schedule-design-guide.md)、トラックの選び方は [トラック設計ガイド](track-design-guide.md) を参照してください。
770
+ - `exec refresh` 後に実際の Ready タスクがあること。カタログ / schedule に登録した task ID と成果物の配置先を確認します。
991
771
 
992
- ### 4.3. Scheduleを生成する
772
+ #### 具体的対話
993
773
 
994
- ```bash
995
- # チャット:「<track> トラックの schedule を生成して」
996
- npx specdojo schedule build --project <project-id> --track <track> --force
997
- # チャット:「実行状態と Ready、CPM を生成して」
998
- npx specdojo exec refresh --project <project-id>
774
+ ```chat
775
+ あなた: 最初の Ready タスクを進めたいです。
776
+
777
+ オーケストレーター: Ready 一覧の task ID・成果物パス・owner・execution mode・入力要件を提示します。タスクの owner は ROLE code BA です。名簿で roles に BA を持つ人の nickname は owner と確認しました。内容を確認してください。
778
+ ・このタスクを --by owner で claim しますか?
779
+
780
+ あなた: はい、提示された情報を確認したので claim してください。
781
+
782
+ オーケストレーター: claim を完了しました。表示された成果物ファイルと生成された result の場所を確認してください。
783
+ 完了条件を満たしたら「完了にして」とお知らせください。
784
+
785
+ あなた: 成果物の編集が終わりました。完了にしてください。
786
+
787
+ オーケストレーター: 表示された task ID を完了として記録し、次の Ready タスクを更新しました。
999
788
  ```
1000
789
 
1001
- `exec refresh` により、着手可能なタスクが `generated/ready.json` に出力されます。
790
+ #### 得られる結果と確認先
1002
791
 
1003
- `schedule build` は strategy と対象カタログから、実行対象となる `sch-track-<track>.yaml` を生成します。`exec refresh` はそこから Ready タスク、CPM、タイムラインなどを生成します。
792
+ - 成果物ファイルおよび `<execution_path>/runs/schedule/<task-id>/<run-id>/` の `result.md` が記録されます。
793
+ - `exec refresh` により後続のタスクが Ready に繰り上がります。
1004
794
 
1005
- ### 4.4. 1タスクを実行する
795
+ #### 折りたたんだコマンドと設定差分
1006
796
 
1007
- 次のタスクを確認して claim します。`execution: human` のタスクは agent を起動せず、claim 時に確認用resultを生成します。人が成果物とresultを編集してから完了を記録します。
797
+ `<task-id>` は Ready 一覧に表示された実際の task ID、`<nickname>` は `pm-members.yaml` で担当ロール `BA` を持つ人の nickname(この例では `owner`)に、山括弧ごと置き換えて実行します。`BA` は strategy の担当引数に使う ROLE code であり、`--by owner` の `owner` は人の nickname です。
1008
798
 
1009
- ```bash
1010
- # 次のタスクを確認する(claim はしない)
1011
- # チャット:「次に着手すべきタスクを <actor> で確認して。claim はしないで」
1012
- npx specdojo exec scheduler --project <project-id> --by <actor> --dry-run
799
+ <details>
800
+ <summary>タスク実行の CLI コマンド(クリックで展開)</summary>
1013
801
 
1014
- # 確認した task-id を claim する
1015
- # チャット:「タスク <task-id> を <actor> で claim して」
1016
- npx specdojo exec claim --project <project-id> --task <task-id> --by <actor>
802
+ ```bash
803
+ # 次のタスクを確認
804
+ npx specdojo exec scheduler --project prj-0001 --by owner --dry-run
1017
805
 
1018
- # 成果物と、claim 時に生成された result のチェックリスト・確定判断を編集する
806
+ # タスクを claim
807
+ npx specdojo exec claim --project prj-0001 --task <task-id> --by <nickname>
1019
808
 
1020
- # 完了を記録する
1021
- # チャット:「タスク <task-id> を <actor> で完了にして」
1022
- npx specdojo exec complete --project <project-id> --task <task-id> --by <actor>
809
+ # 成果物と result を編集後、完了を記録
810
+ npx specdojo exec complete --project prj-0001 --task <task-id> --by <nickname>
1023
811
 
1024
- # 次の Ready タスクを更新する
1025
- # チャット:「Ready タスクを更新して」
1026
- npx specdojo exec refresh --project <project-id>
812
+ # Ready タスクを更新
813
+ npx specdojo exec refresh --project prj-0001
1027
814
  ```
1028
815
 
1029
- 成果物の変更は作業ツリーに、実行結果は `<execution_path>/exec/results/` に記録されます。agent による自動実行や並列実行へ進む場合は、[exec設定ガイド](exec-config-guide.md) で設定してから [Schedule実行運用ガイド](schedule-operation-guide.md) を参照してください。
816
+ </details>
1030
817
 
1031
- `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) を参照してください。
818
+ ## 6. 発展: routineで定期実行する
1032
819
 
1033
- agent に review を実行させる場合は、`exec run --plan` で executor と reporter を指定して 2 段で実行します。
820
+ 日次の未処理 todo スイープや定期確認作業など、決まった間隔で繰り返し実行したいジョブを `routine` として定義・自動化します。
1034
821
 
1035
- ```bash
1036
- # review を 2 段で実行する
1037
- npx specdojo exec run --project <project-id> --plan <execution_path>/exec/plans/<task-id>-plan.md \
1038
- --executor-by <executor-nickname> --reporter-by <reporter-nickname>
1039
- ```
822
+ ### 前提
1040
823
 
1041
- ここまでで、register による立ち上げ整理から、成果物カタログ、Schedule、1タスクの完了までの Quick Start は終了です。以降の worktree 隔離実行と routine は、agent 設定後に試す任意の発展手順です。
824
+ - `.specdojo/specdojo.config.json` に `routines_path`(例: `routines`)および `jobs_path` が設定されていること。
825
+ - `jobs_path` に定義済み Job があり、routine から渡す入力、実行コマンド、権限、副作用を検証済みであること。無ければ routine の前に Job の設計・承認・作成が必要です。
1042
826
 
1043
- ## 5. 発展: worktreeで1タスクを隔離実行する
827
+ ### 具体的対話
1044
828
 
1045
- 前節「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` まで済ませておきます。
829
+ オーケストレーターに定期実行ルーチンの登録を相談します。オーケストレーターは実行頻度や対象条件を確認し、定義を作成して検証します。
1046
830
 
1047
- 対象タスクを worktree に隔離して一括実行します。SpecDojo が worktree 準備・agent 実行・commit・merge・状態更新をまとめて行います。
831
+ ```chat
832
+ あなた: オープンな高優先度 todo を毎日確認して処理する仕組み(routine)を作りたいです。
1048
833
 
1049
- ```bash
1050
- # 実行前に統合先ブランチ(例: project/<project-id>/develop)にいることを確認する
1051
- git branch --show-current
834
+ オーケストレーター: 定期実行ルーチン(routine)を設定します。以下の設定内容を確認させてください:
835
+ ・ルーチン ID: rtn-daily-register-sweep(既存定義と重複しないことを確認)
836
+ ・実行頻度(interval): 毎日 1 回の 1d でよろしいですか?
837
+ ・対象条件: 状態が open かつ優先度が high の todo を対象にしますか?
838
+ ・処理件数上限(limit): 安全のため 1 回あたり最大 3 件までに制限しますか?
839
+ ・呼び出し Job: `jobs_path` に実在し入力仕様を確認した Job を選びます。Job がなければ、定義・権限・副作用を相談して別途準備し、存在を仮定しません。
840
+ 実行頻度や抽出条件を Job が受け取れるか、入力 schema と副作用を確認します。routine 定義の保存先は `routines_path` の解決先です。この内容で作成してよろしいですか?
1052
841
 
1053
- # 1 タスクを worktree で隔離実行する
1054
- # チャット:「タスク <task-id> を worktree で隔離実行して」
1055
- npx specdojo exec run --project <project-id> --task <task-id> --worktree
842
+ あなた: はい、その設定で作成してください。
1056
843
 
1057
- # Ready 順に自動で隔離実行する場合
1058
- # チャット:「Ready タスクを worktree で並列5件、自動実行して」
1059
- npx specdojo exec run --project <project-id> --auto --parallel 5
1060
- ```
844
+ オーケストレーター: 定義ファイルを作成しました。定義の構文検証と dry-run(試行実行)を行ってよろしいですか?
1061
845
 
1062
- 各段階(prepare → agent → commit → merge → remove)を人が確認しながら進める場合は [exec worktree運用ガイド](exec-worktree-guide.md)、project `develop`・feature・exec のブランチ全体運用は [ブランチワークフローガイド](branch-workflow-guide.md)、自動・並列実行の運用は [Schedule実行運用ガイド](schedule-operation-guide.md) を参照してください。
846
+ あなた: はい、検証と dry-run をお願いします。
1063
847
 
1064
- ## 6. 発展: routineで定期実行する
848
+ オーケストレーター: routine validate に合格し、dry-run で対象の todo が正しく抽出されることを確認しました。
849
+ 継続運用では、cron や CI(GitHub Actions の scheduled workflow 等)から定期的に実行コマンドを呼び出します。設定例を確認しますか?
1065
850
 
1066
- この経路では、動作確認済みの Job を `rtn-*.yaml` に定義した間隔で起動します。Job は schedule または register のagent実行を決定論的なコマンドで呼び出します。routine は任意の発展手順です。先に [exec設定ガイド](exec-config-guide.md) に従ってagentを設定し、次のような open かつ高優先度のtodoを用意します。
851
+ あなた: cron の設定例を教えてください。
1067
852
 
1068
- ```bash
1069
- # チャット:「高優先度の todo『日次確認事項に対応する』を起票して」
1070
- npx specdojo register add \
1071
- --project <project-id> \
1072
- --type todo \
1073
- --priority high \
1074
- --title "日次確認事項に対応する"
853
+ オーケストレーター: cron の設定例を提示します。平日の朝 9 時に due なルーチンを実行する例です:
854
+ 0 9 * * 1-5 cd /path/to/landing-page-specdojo && npx specdojo routine run --project prj-0001 --due
1075
855
  ```
1076
856
 
1077
- 次のroutine例は、このようなtodoを毎日最大3件実行します。先に `jobs_path` 配下へ `job-register-sweep.yaml` を配置してください。このリポジトリの定義例は `docs/ja/projects/prj-0001/jobs/job-register-sweep.yaml`、入力制約の規約は [Job定義標準](../standards/job-definition-standard.md) を参照します。
857
+ ### 得られる結果と確認先
858
+
859
+ - `docs/ja/projects/prj-0001/routines/rtn-daily-register-sweep.yaml`(`routines_path` が既定値の場合) が作成されます。
860
+ - `npx specdojo routine list` でルーチンの一覧、有効/無効状態、前回実行日時が確認できます。
861
+ - cron や CI による無人定期運用が可能になります。
1078
862
 
1079
- `.specdojo/specdojo.config.json` の `routines_path` 配下に `rtn-daily-register-sweep.yaml` を作成します。
863
+ ### 折りたたんだコマンドと設定差分
1080
864
 
1081
865
  <details>
1082
- <summary>rtn-daily-register-sweep.yaml の例(クリックで展開)</summary>
866
+ <summary>ルーチン定義ファイルと CLI コマンド(クリックで展開)</summary>
867
+
868
+ 次は schema に沿った例です。保存前に `job-register-sweep` が `jobs_path` に存在し、入力仕様と副作用が確認済みであることを確かめます。存在しない場合は実在 Job の ID と入力に置き換え、Job を別途設計・承認・作成してから検証してください。
869
+
870
+ `routines/rtn-daily-register-sweep.yaml` の内容:
1083
871
 
1084
872
  ```yaml
1085
873
  id: rtn-daily-register-sweep
@@ -1096,26 +884,20 @@ action:
1096
884
  limit: "3"
1097
885
  ```
1098
886
 
1099
- </details>
1100
-
1101
- 定義を検証し、実行対象を確認してから1回実行します。
887
+ 対応する CLI コマンド:
1102
888
 
1103
889
  ```bash
1104
- # チャット:「ルーチン定義を検証して」
1105
- npx specdojo routine validate --project <project-id>
1106
- # チャット:「ルーチン一覧を見せて」
1107
- npx specdojo routine list --project <project-id>
1108
- # チャット:「rtn-daily-register-sweep を dry-run で確認して」
1109
- npx specdojo routine run --project <project-id> --id rtn-daily-register-sweep --dry-run
1110
- # チャット:「rtn-daily-register-sweep を実行して」
1111
- npx specdojo routine run --project <project-id> --id rtn-daily-register-sweep
1112
- ```
890
+ # ルーチン定義の構文検証
891
+ npx specdojo routine validate --project prj-0001
1113
892
 
1114
- 継続運用では、cron や CI の scheduled workflow から次のコマンドを定期的に呼び出します。CLI 自体は常駐しません。
893
+ # ルーチン一覧の確認
894
+ npx specdojo routine list --project prj-0001
1115
895
 
1116
- ```bash
1117
- # チャット:「due なルーチンをまとめて実行して」
1118
- npx specdojo routine run --project <project-id> --due
896
+ # dry-run で実行対象を確認
897
+ npx specdojo routine run --project prj-0001 --id rtn-daily-register-sweep --dry-run
898
+
899
+ # 期限が到来した(due)ルーチンを一括実行
900
+ npx specdojo routine run --project prj-0001 --due
1119
901
  ```
1120
902
 
1121
- schedule の自動実行や利用制限後の再開を起動する定義、`interval` と `last_run` の扱いは [routine運用ガイド](routine-operation-guide.md) を参照してください。
903
+ </details>