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