specdojo 0.2.1 → 0.3.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 (168) hide show
  1. package/.github/agents/specdojo-orchestrator.md +165 -0
  2. package/CHANGELOG.md +280 -0
  3. package/README.md +92 -42
  4. package/dist/agent-response.js +20 -0
  5. package/dist/agent.js +4 -4
  6. package/dist/build-command.js +28 -8
  7. package/dist/dashboard.js +122 -1
  8. package/dist/devcontainer-command.js +43 -0
  9. package/dist/devcontainer-scaffold.js +165 -0
  10. package/dist/exec-agent-config.js +107 -9
  11. package/dist/exec-agent-git-state.js +18 -0
  12. package/dist/exec-agent-protected-config.js +46 -8
  13. package/dist/exec-evidence.js +254 -11
  14. package/dist/exec-handoff.js +336 -0
  15. package/dist/exec-parent-validation.js +317 -43
  16. package/dist/exec-pipeline-state.js +74 -9
  17. package/dist/exec-plans.js +115 -113
  18. package/dist/exec-protection-handoff.js +43 -2
  19. package/dist/exec-provider-scaffold.js +247 -15
  20. package/dist/exec-register-resume.js +65 -19
  21. package/dist/exec-register.js +9 -3
  22. package/dist/exec-repo-integration.js +811 -0
  23. package/dist/exec-repo-trace.js +182 -0
  24. package/dist/exec-reporter.js +613 -132
  25. package/dist/exec-results.js +81 -56
  26. package/dist/exec-run-lock.js +110 -107
  27. package/dist/exec-run.js +1585 -356
  28. package/dist/exec-shared.js +7 -0
  29. package/dist/exec-slot-lock.js +242 -0
  30. package/dist/exec-task-repos.js +415 -0
  31. package/dist/exec-trial.js +51 -25
  32. package/dist/exec-worktree-command.js +87 -43
  33. package/dist/exec-worktree-ops.js +502 -57
  34. package/dist/exec-worktree.js +114 -27
  35. package/dist/exec.js +13 -6
  36. package/dist/grade-result.js +128 -0
  37. package/dist/grade.js +809 -72
  38. package/dist/init-command.js +443 -0
  39. package/dist/job.js +160 -10
  40. package/dist/orchestrator.js +213 -0
  41. package/dist/register-event-merge.js +169 -0
  42. package/dist/register-item.js +7 -1
  43. package/dist/register.js +294 -86
  44. package/dist/review-grade.js +252 -0
  45. package/dist/review-plan.js +111 -1
  46. package/dist/review-types.js +40 -1
  47. package/dist/routine.js +72 -5
  48. package/dist/schedule-build.js +2 -2
  49. package/dist/schedule.js +17 -4
  50. package/dist/specdojo-config.js +465 -19
  51. package/dist/specdojo-gitignore.js +135 -0
  52. package/dist/specdojo.js +6 -0
  53. package/dist/viewpoint-document-kinds-check.js +128 -0
  54. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +348 -90
  55. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +51 -17
  56. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +7 -5
  57. package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +29 -31
  58. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +34 -55
  59. package/docs/ja/specdojo/exec-templates/xrp-job-template.md +54 -0
  60. package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +28 -37
  61. package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +29 -34
  62. package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +30 -30
  63. package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +29 -34
  64. package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +29 -34
  65. package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +29 -34
  66. package/docs/ja/specdojo/exec-templates/xrp-template.md +29 -28
  67. package/docs/ja/specdojo/exec-templates/xrr-template.md +11 -9
  68. package/docs/ja/specdojo/guides/docs-editing-guide.md +20 -0
  69. package/docs/ja/specdojo/guides/docs-structure-guide.md +103 -70
  70. package/docs/ja/specdojo/guides/exec-config-guide.md +91 -47
  71. package/docs/ja/specdojo/guides/exec-operation-guide.md +124 -27
  72. package/docs/ja/specdojo/guides/exec-worktree-guide.md +40 -11
  73. package/docs/ja/specdojo/guides/kata-guide.md +4 -4
  74. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +25 -4
  75. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +1 -1
  76. package/docs/ja/specdojo/guides/practice-system-composition-guide.md +13 -13
  77. package/docs/ja/specdojo/guides/quick-start-guide.md +260 -30
  78. package/docs/ja/specdojo/guides/register-operation-guide.md +31 -14
  79. package/docs/ja/specdojo/guides/release-v0-3-0-migration-guide.md +264 -0
  80. package/docs/ja/specdojo/guides/remote-host-development-guide.md +22 -1
  81. package/docs/ja/specdojo/guides/review-guide.md +195 -158
  82. package/docs/ja/specdojo/guides/routine-operation-guide.md +74 -9
  83. package/docs/ja/specdojo/guides/ryu-guide.md +32 -30
  84. package/docs/ja/specdojo/guides/schedule-design-guide.md +10 -10
  85. package/docs/ja/specdojo/guides/schedule-operation-guide.md +1 -1
  86. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +58 -33
  87. package/docs/ja/specdojo/guides/use-case-guide.md +3 -3
  88. package/docs/ja/specdojo/guides/waza-guide.md +15 -2
  89. package/docs/ja/specdojo/index.md +2 -2
  90. package/docs/ja/specdojo/philosophy/specdojo-philosophy.md +5 -5
  91. package/docs/ja/specdojo/recipes/bps-recipe.md +213 -0
  92. package/docs/ja/specdojo/recipes/pm-members-recipe.md +52 -117
  93. package/docs/ja/specdojo/references/command-reference.md +335 -92
  94. package/docs/ja/specdojo/references/deliverables-reference.md +1 -1
  95. package/docs/ja/specdojo/references/directory-layout-reference.md +13 -9
  96. package/docs/ja/specdojo/references/specdojo-config-reference.md +107 -24
  97. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +132 -220
  98. package/docs/ja/specdojo/rulebooks/br-rulebook.md +6 -44
  99. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +2 -0
  100. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +0 -87
  101. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +61 -39
  102. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +0 -87
  103. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +1 -33
  104. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +0 -137
  105. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +0 -247
  106. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +0 -83
  107. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +4 -2
  108. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +78 -150
  109. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +5 -4
  110. package/docs/ja/specdojo/rulebooks/sch-rulebook.md +1 -1
  111. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +0 -11
  112. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +0 -61
  113. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +2 -47
  114. package/docs/ja/specdojo/samples/bps-sample.md +74 -21
  115. package/docs/ja/specdojo/samples/gl-sample.yaml +17 -1
  116. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +28 -0
  117. package/docs/ja/specdojo/samples/pm-members-sample.yaml +2 -67
  118. package/docs/ja/specdojo/samples/pm-organization-sample.md +8 -7
  119. package/docs/ja/specdojo/samples/pm-raci-sample.md +1 -1
  120. package/docs/ja/specdojo/samples/tml-sample.yaml +40 -0
  121. package/docs/ja/specdojo/standards/document-metadata-standard.md +21 -16
  122. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +14 -14
  123. package/docs/ja/specdojo/standards/job-definition-standard.md +37 -17
  124. package/docs/ja/specdojo/standards/people-and-organization-definition-standard.md +37 -32
  125. package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -1
  126. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +21 -11
  127. package/docs/ja/specdojo/templates/agent-members-template.yaml +25 -0
  128. package/docs/ja/specdojo/templates/bps-template.md +91 -0
  129. package/docs/ja/specdojo/templates/pm-members-template.yaml +2 -59
  130. package/docs/specdojo/schemas/v1/agent-members.schema.yaml +76 -0
  131. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +4 -2
  132. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +55 -2
  133. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +93 -6
  134. package/docs/specdojo/schemas/v1/exec-reporter-output.schema.yaml +27 -78
  135. package/docs/specdojo/schemas/v1/gl.schema.yaml +87 -0
  136. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +33 -0
  137. package/docs/specdojo/schemas/v1/job-run.schema.yaml +27 -0
  138. package/docs/specdojo/schemas/v1/job.schema.yaml +25 -0
  139. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +49 -1
  140. package/docs/specdojo/schemas/v1/pm-members.schema.yaml +9 -169
  141. package/docs/specdojo/schemas/v1/pm-review-viewpoints.schema.yaml +100 -10
  142. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +13 -0
  143. package/docs/specdojo/schemas/v1/routine-run.schema.yaml +3 -0
  144. package/docs/specdojo/schemas/v1/routine.schema.yaml +7 -0
  145. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +110 -0
  146. package/package.json +15 -9
  147. package/templates/antigravity/README.md +27 -2
  148. package/templates/antigravity/{pm-members-snippet.yaml → agent-members-snippet.yaml} +8 -2
  149. package/templates/antigravity/exec-defaults-snippet.yaml +7 -6
  150. package/templates/antigravity/orchestrator.md +18 -7
  151. package/templates/antigravity/settings.global.json +55 -0
  152. package/templates/claude/agents/claude-executor.md +14 -0
  153. package/templates/claude/agents/claude-reporter.md +16 -0
  154. package/templates/claude/agents/specdojo-orchestrator.md +18 -7
  155. package/templates/claude/settings.edit.json +27 -1
  156. package/templates/codex/README.md +5 -4
  157. package/templates/codex/agents/specdojo-orchestrator.toml +18 -7
  158. package/templates/codex/orchestrator.md +18 -7
  159. package/templates/copilot/README.md +7 -5
  160. package/templates/copilot/{pm-members-snippet.yaml → agent-members-snippet.yaml} +4 -2
  161. package/templates/devcontainer/devcontainer.json +27 -0
  162. package/templates/devcontainer/emacs/init.el +88 -0
  163. package/templates/devcontainer/post-create.sh +62 -0
  164. package/templates/init-agent-members.yaml +200 -0
  165. package/templates/init-exec-defaults.yaml +72 -0
  166. package/templates/opencode/agents/specdojo-orchestrator.md +18 -7
  167. package/docs/ja/specdojo/exec-templates/xrp-viewpoint-detail-template.md +0 -7
  168. package/docs/ja/specdojo/exec-templates/xrr-viewpoint-detail-template.md +0 -7
package/README.md CHANGED
@@ -1,13 +1,22 @@
1
1
  # SpecDojo
2
2
 
3
- SpecDojo は、仕様駆動開発のためのドキュメントフレームワークです。
4
- プロダクトの構築・改修に必要な情報を体系化し、人と生成 AI が同じ成果物を作成・検証・更新できるようにします。
3
+ SpecDojo は、仕様道(Spec-Dō)の道場です。
4
+ 仕様と設計を作り、運用まで保つための体系を整えます。判断を記帳し、型に沿って実戦で書き、評定で鍛え続け、講評で完了を判断します。人と生成 AI が同じ成果物を作成・検証・更新できるようにし、仕様駆動開発のツールに対しては、その上流で仕様と設計の体系を担います。
5
5
 
6
- **登録簿ひとつから始められます。** 設定 2 行で使い始め、必要になった分だけ広げられます。
6
+ **記して、形にして、磨き続ける。**
7
+
8
+ **記帳ひとつから始められます。** 設定 2 行で使い始め、必要になった分だけ広げられます。
9
+ 迷いを question として起票し、decision で決め、仕様書に書き、後日 change-request で直すまでを 10 分で体験できます。kata(型)を事前に用意する必要はありません。手順は [Quick Start ガイド](https://specdojo.github.io/specdojo/ja/specdojo/guides/quick-start-guide.html) 冒頭の「10分で体験する — 仕様の判断台帳」を参照してください。
10
+
11
+ | 道場の言葉 | SpecDojo の仕組み |
12
+ | ---------- | ------------------------------------------------------------------------------------------------------- |
13
+ | 型(Kata) | 成果物の作り方を定める rulebook・recipe・sample・template |
14
+ | 技(Waza) | `specdojo` CLI。決定を残す記帳、成果物を作る実戦、品質を見る評定、完了を見る講評 |
15
+ | 流(Ryu) | 成果物・型・技をつなぐ `approach`。タスクごとに型をどこまで基準にして技を使うか(守・破・離など)を表す |
7
16
 
8
17
  ## できること
9
18
 
10
- ### 気づいたことを、型に沿って残せる
19
+ ### 記帳 — 気づいたことを、型に沿って残せる
11
20
 
12
21
  作業だけでなく、判断・保留・観測・リスク・変更要求も同じ登録簿へ記録します。種別を選ぶと
13
22
  本文の章構成が与えられるため、「選択肢を比較して理由を書く」といった記録が形を保ちます。
@@ -20,10 +29,16 @@ SpecDojo は、仕様駆動開発のためのドキュメントフレームワ
20
29
  調査や議論の内容がそのまま個票の本文になるため、別途まとめ直す必要がありません。
21
30
  状態を変える操作は実行前に提示して承認を求め、`git push` や破壊的操作は行いません。
22
31
 
23
- ### 必要になったら、成果物の型へ広げられる
32
+ ### 型と実戦 — 必要になったら、成果物の型へ広げられる
24
33
 
25
34
  要件、設計、テスト、運用まで 100 種類以上の記述規則・手順・テンプレート・サンプルを持ちます。
26
- 使うものだけをカタログで宣言し、型に沿って作れます。最初から全部を用意する必要はありません。
35
+ 使うものだけをカタログで宣言し、型に沿った実戦で成果物を作れます。最初から全部を用意する必要はありません。
36
+
37
+ ### 評定と講評 — 品質評価と完了判断を分けて残せる
38
+
39
+ `grade` は成果物の品質を共通の観点で評価し、`review` はその結果と実行記録・完了条件を照合して、タスクを完了してよいかを判断します。品質の finding とタスクの未充足事項を混同せず、最終的な `ready` への確定は人が行います。
40
+
41
+ v0.3.0 の `grade` は試験的な機能です。npm package では `grade list` / `plan` / `apply` / `validate` / `result` などの部品を利用できますが、これらを通しで実行する SpecDojo 本体リポジトリの開発用スクリプト `tools/grade/run-per-document.sh` は package に含まれません。成果物を評価するには、project の `catalog_path` も設定してください。1 文書を部品で評価する手順は [CLI コマンドリファレンス](docs/ja/specdojo/references/command-reference.md#81-npm-package-で-1-文書を評価する)を参照してください。
27
42
 
28
43
  日本語ドキュメントは [SpecDojo ドキュメントサイト](https://specdojo.github.io/specdojo/ja/) で公開しています。
29
44
 
@@ -34,14 +49,29 @@ SpecDojo は、仕様駆動開発のためのドキュメントフレームワ
34
49
 
35
50
  ## 使い始める
36
51
 
52
+ 現在の変更点は [CHANGELOG](CHANGELOG.md) にまとめています。v0.2.1 から更新する場合は、
53
+ レビュー観点、rubric、review テンプレートに互換性のない変更があるため、
54
+ [v0.3.0 移行ガイド](docs/ja/specdojo/guides/release-v0-3-0-migration-guide.md)を先に確認してください。
55
+
37
56
  ### npm で導入する
38
57
 
39
- 既定では、プロダクトリポジトリ `app1/` の隣に SpecDojo 専用リポジトリ
40
- `app1-specdojo/` と worktree 用ディレクトリ `app1-worktrees/` を置く Detached Unit で始めます。
41
- workspace 直下で次を実行します。
58
+ 既定では、SpecDojo の記録をプロダクトの Git 履歴に混ぜないため、次の **別リポジトリ構成**で始めます。
59
+
60
+ - **プロダクトリポジトリ** `app1/`: ソースコードと、仕様・設計などのプロダクトドキュメントを置きます。
61
+ - **プロジェクトリポジトリ** `app1-specdojo/`: 登録簿・計画・実行記録などのプロジェクトドキュメントと、文書の作り方を定める型(Kata)を置きます。1つのプロジェクトリポジトリに、複数のプロジェクトを格納できます。
62
+ - **worktree 用ディレクトリ** `app1-specdojo-worktrees/`: タスクごとの変更を隔離して進めるために、Git worktree を作る場所です。名前はプロジェクトリポジトリのディレクトリ名から決まります。
63
+
64
+ ```text
65
+ app1-workspace/
66
+ ├── app1/ # プロダクトリポジトリ
67
+ ├── app1-specdojo/ # プロジェクトリポジトリ
68
+ └── app1-specdojo-worktrees/ # タスクごとの作業場所
69
+ ```
70
+
71
+ `app1-workspace/` 直下で次を実行します。
42
72
 
43
73
  ```sh
44
- mkdir app1-specdojo app1-worktrees
74
+ mkdir app1-specdojo
45
75
  git -C app1-specdojo init
46
76
  cd app1-specdojo
47
77
  npm init -y
@@ -49,40 +79,50 @@ npm install --save-dev specdojo @specdojo/docs-lint
49
79
  npx specdojo config init
50
80
  ```
51
81
 
52
- SpecDojo は文書と実行管理のためのツールで、成果物へ同梱されるものではないため `--save-dev` で導入します。あわせて、kata は `node_modules/specdojo` から参照されるため、`package-lock.json` が kata の版も固定します。グローバル導入(`npm install -g`)では版がプロジェクトに記録されず再現できません。
82
+ SpecDojo は開発時に使う文書・実行管理ツールなので、`--save-dev` で導入します。kata は、成果物を書くための規則・手順・テンプレート・サンプルの総称です。kata もインストールした package から参照されるため、`package-lock.json` によって SpecDojo と同じ版へ固定されます。
53
83
 
54
- `config init` は `.specdojo/specdojo.config.json` とその親ディレクトリを作成します。既定では
55
- `prj-0001` と `docs/ja/projects/prj-0001/controls/project-register` を使う最小構成です。別の
56
- project ID や配置を使う場合は、生成された設定の `current_project`、`projects` のキー、
57
- `base_path` を次へ進む前に変更してください。catalog や schedule へ進むときに追加するキーは
58
- [SpecDojo設定リファレンス](https://specdojo.github.io/specdojo/ja/specdojo/references/specdojo-config-reference.html)で確認できます。
84
+ `config init` は、登録簿を使い始めるための最小設定を `.specdojo/specdojo.config.json` に作成します。worktree の既定先はリポジトリのディレクトリ名から `../<リポジトリ名>-worktrees` として作られます。設定を変える方法は、後述の「設定を変えたいとき」を参照してください。
85
+
86
+ あわせて、`npm install` で作られる `node_modules/` と SpecDojo の生成物(`docs/**/generated/*`、`.specdojo/doc-index.json` など)を git の管理から外す行を `.gitignore` に用意します。`.gitignore` が無ければ作成し、既にあれば足りない行だけを末尾へ追記します。`node_modules`、`/node_modules` など同じ意味の行が既にあれば `node_modules/` は追記しません。生成物を管理外にしておくと、登録簿の項目を並行実行したときに生成物どうしが衝突しません。追記する行は `npx specdojo config init --dry-run` で事前に確認できます。すでに `node_modules/` や生成物を git で管理している場合は、表示される案内に従って `git rm -r --cached` で管理から外し、コミットします。
59
87
 
60
88
  ### オーケストレーターを配置する
61
89
 
62
- SpecDojo は対話型オーケストレーターを同梱しています。CLI を直接叩く代わりに、会話で意図を伝えると、
63
- 対応するコマンドを提案し、承認を得てから実行します。利用する provider の設定を配置します。
90
+ SpecDojo は、会話を CLI 操作へ変換する対話型オーケストレーターを同梱しています。利用する AI ツール(provider)の設定を配置します。次は Claude Code を使う例です。
64
91
 
65
92
  ```sh
66
93
  npx specdojo config scaffold --provider claude
67
94
  ```
68
95
 
69
- `--provider` には `antigravity`、`claude`、`codex`、`copilot`、`opencode` を指定できます。
70
- オーケストレーターの配置先と起動方法は provider ごとに異なります。
96
+ このコマンドを実行すると、オーケストレーターの定義ファイルが配置され、`package.json` へ起動用のスクリプトが追加されます(`package.json` が存在する場合)。追加されたスクリプトで起動します。
71
97
 
72
- | provider | 配置先 | 起動 |
73
- | ------------- | ------------------------------------------- | -------------------------------------------------------------------------- |
74
- | `claude` | `.claude/agents/specdojo-orchestrator.md` | `claude --agent specdojo-orchestrator` |
75
- | `opencode` | `.opencode/agents/specdojo-orchestrator.md` | `opencode --agent specdojo-orchestrator` |
76
- | `codex` | `.specdojo/codex/orchestrator.md` | `codex "$(cat .specdojo/codex/orchestrator.md)"` |
77
- | `antigravity` | `.specdojo/antigravity/orchestrator.md` | `agy --add-dir "$(pwd)" -i "$(cat .specdojo/antigravity/orchestrator.md)"` |
98
+ | provider | 配置先 | 起動(`package.json` がある場合) |
99
+ | ------------- | ------------------------------------------- | --------------------------------- |
100
+ | `claude` | `.claude/agents/specdojo-orchestrator.md` | `npm run orch:opus` ほか |
101
+ | `opencode` | `.opencode/agents/specdojo-orchestrator.md` | `npm run orch:opencode` |
102
+ | `codex` | `.specdojo/codex/orchestrator.md` | `npm run orch:codex` |
103
+ | `antigravity` | `.specdojo/antigravity/orchestrator.md` | `npm run orch:agy` |
78
104
 
79
- `claude` と `opencode` は agent の定義ファイルを名前で選べるため、`--agent` で起動します。`codex` と
80
- `antigravity` は定義ファイルから agent を選ぶ仕組みを持たないため、規範の本文を起動時の指示として
81
- 渡します。antigravity の `.agents/` は rules と skills のためのディレクトリで、agent の定義は扱いません。
82
- rules へ置くと全セッションへ読み込まれ、executor として起動したときにも役割が混入します。
105
+ 配置されるファイルのモデル名は、手元で使えるモデルに合わせて編集してください。provider ごとの詳しい設定は [オーケストレーター運用ガイド](https://specdojo.github.io/specdojo/ja/specdojo/guides/orchestrator-operation-guide.html) を参照してください。
83
106
 
84
- 配置されるファイルにはモデル名が書かれています。手元で使えるモデルに合わせて編集してください。
85
- executor / reporter の設定も同時に配置されるので、agent にタスクを実行させる段階で使います。
107
+ Antigravity CLI を無人実行する場合は、利用者のグローバル設定へ permission rule を追加します。この設定はすべてのリポジトリに効くため、必ず先に差分を確認してから適用してください。通常の scaffold はグローバル設定へ触れません。
108
+
109
+ ```sh
110
+ npx specdojo config scaffold --provider antigravity --global --dry-run
111
+ npx specdojo config scaffold --provider antigravity --global
112
+ ```
113
+
114
+ 実適用では既存設定を残し、変更前のファイルをバックアップします。追加する allow は `git status` / `diff` / `log` / `show` の読み取り操作だけです。
115
+
116
+ #### Dev Container を使う場合(任意)
117
+
118
+ 利用環境として Dev Container を使う場合は、オーケストレーターの配置に加えて次のコマンドを実行すると、指定した provider の CLI が組み込まれた `.devcontainer/` を生成できます。
119
+
120
+ ```sh
121
+ npx specdojo devcontainer scaffold --provider claude --dry-run
122
+ npx specdojo devcontainer scaffold --provider claude
123
+ ```
124
+
125
+ 既存の `.devcontainer/` は上書きせず、置き換える場合だけ `--force` を指定します。生成設定は provider の設定ディレクトリを名前付きボリュームに保存し、ホストの認証情報・秘密鍵・`.env` はマウントしません。生成後、VS Code などでコンテナを立ち上げると、分離された環境ですぐにオーケストレーターを起動できます。Ollama 接続、cron、tmux はそれぞれ `--ollama`、`--cron`、`--tmux` で追加できます。
86
126
 
87
127
  ### 会話で操作する
88
128
 
@@ -90,7 +130,7 @@ executor / reporter の設定も同時に配置されるので、agent にタス
90
130
 
91
131
  ```text
92
132
  あなた : このプロジェクトを始めたい。まず登録簿を用意して、最初の作業を起票して。
93
- agent : 次を実行します。よろしいですか。
133
+ オーケストレーター : 次を実行します。よろしいですか。
94
134
  npx specdojo register scaffold --project prj-0001
95
135
  npx specdojo register add --project prj-0001 --type todo --title "..."
96
136
  あなた : お願いします。
@@ -109,7 +149,7 @@ kata の rulebook を確認したい
109
149
 
110
150
  ### CLI を直接使う
111
151
 
112
- agent を使わずに操作することもできます。最初の登録簿と todo を作り、一覧を生成します。
152
+ オーケストレーターを使わずに操作することもできます。最初の登録簿と、実施する作業を表す `todo` を作り、一覧を生成します。
113
153
 
114
154
  ```sh
115
155
  npx specdojo register scaffold --project prj-0001
@@ -120,16 +160,17 @@ npx specdojo register add \
120
160
  npx specdojo register build --project prj-0001
121
161
  ```
122
162
 
123
- ここまでの手順は、利用側へ kata をコピーせずに実行できます。生成された todo の個票が編集対象、
124
- `generated/pjr-index.md` が個票から作る一覧です。`register add` が表示した ID を使い、agent を
125
- 起動せずに exec plan の内容まで確認できます。
163
+ `exec run` と並行して記帳し、その変更だけを commit まで完了させる場合は、`register add` / `update` / `renumber` または状態遷移コマンドへ `--commit` を付けます。同じ project の `register lifecycle` 枠が空くまで待ち、ほかの未 commit 変更を含めずに記帳・一覧再生成・commit を行います。対象の個票や event に既存差分がある場合は、混在を避けるため記帳前に停止します。
164
+
165
+ ここまでの手順は、利用側へ kata をコピーせずに実行できます。生成された `todo` の個票が編集対象、
166
+ `generated/pjr-index.md` が個票から作る一覧です。`register add` が表示した ID を使い、AI に作業を
167
+ 依頼する前に実行計画(exec plan)の内容まで確認できます。
126
168
 
127
169
  ```sh
128
170
  npx specdojo exec plan --project prj-0001 --register PJR-XXXX
129
171
  ```
130
172
 
131
- kata は既定で npm package 内のものを参照します。適用中の rulebook を確認し、プロジェクトで
132
- 上書きする場合だけ eject します。
173
+ kata は既定で npm package 内のものを参照します。適用中の rulebook(成果物ごとの記述規則)を確認し、プロジェクトで変更する場合だけ `eject` でリポジトリへコピーします。
133
174
 
134
175
  ```sh
135
176
  npx specdojo kata list --kind rulebook
@@ -137,17 +178,26 @@ npx specdojo kata show specdojo:pjr-rulebook
137
178
  npx specdojo kata eject --id specdojo:pjr-rulebook
138
179
  ```
139
180
 
140
- provider と agent の設定を終えた後は、同じ登録項目を実行できます。成功後は人が result と成果物を
141
- 確認し、登録項目を close します。
181
+ provider の設定を終えた後は、同じ登録項目を AI に実行させられます。成功後は人が実行結果(result)と成果物を確認し、登録項目を完了(close)します。
142
182
 
143
183
  ```sh
144
184
  npx specdojo exec run --project prj-0001 --register PJR-XXXX
145
185
  ```
146
186
 
147
- agent の実行は数分から数十分かかり、`routine` は定期実行されます。作業端末の状態に依存せず
187
+ AI による実行は数分から数十分かかり、定期処理として登録した `routine` は決めた時刻に実行されます。作業端末の状態に依存せず
148
188
  実行を続けたい場合は、常時稼働するホストへリモート接続する構成例を
149
189
  [常時稼働ホスト運用ガイド](https://specdojo.github.io/specdojo/ja/specdojo/guides/remote-host-development-guide.html) に示しています。
150
190
 
191
+ ### 設定を変えたいとき
192
+
193
+ `config init` が作る設定は、`prj-0001` の登録簿から始める例です。別のプロジェクト ID や配置を使う場合は、`.specdojo/specdojo.config.json` を変更します。
194
+
195
+ - `current_project`: `--project` を省略したときに使うプロジェクトです。
196
+ - `projects`: このプロジェクトリポジトリで扱うプロジェクトを定義します。複数登録できます。
197
+ - `base_path`: 各プロジェクトの文書を置く基準パスです。
198
+
199
+ 成果物カタログやスケジュールへ進むときに追加する設定は、[SpecDojo設定リファレンス](https://specdojo.github.io/specdojo/ja/specdojo/references/specdojo-config-reference.html) を参照してください。
200
+
151
201
  ### テンプレートリポジトリとして導入する
152
202
 
153
203
  npm package の参照方式ではなく、SpecDojo のソースと文書体系一式を最初から配置して
@@ -20,6 +20,26 @@ export function extractJsonText(raw) {
20
20
  return unfenced;
21
21
  return unfenced.slice(start, end + 1);
22
22
  }
23
+ /**
24
+ * agent の生応答から JSON 配列の本文を取り出す。
25
+ * 配列内の文字列にオブジェクト記号が含まれていても、配列全体を優先する。
26
+ */
27
+ export function extractJsonArrayText(raw) {
28
+ const unfenced = stripCodeFence(raw.trim());
29
+ for (let start = unfenced.indexOf("["); start >= 0; start = unfenced.indexOf("[", start + 1)) {
30
+ for (let end = unfenced.lastIndexOf("]"); end > start; end = unfenced.lastIndexOf("]", end - 1)) {
31
+ const candidate = unfenced.slice(start, end + 1);
32
+ try {
33
+ if (Array.isArray(JSON.parse(candidate)))
34
+ return candidate;
35
+ }
36
+ catch {
37
+ // 別の角括弧または不完全な配列を飛ばし、次の候補を試す。
38
+ }
39
+ }
40
+ }
41
+ return unfenced;
42
+ }
23
43
  // 最初のコードフェンスの中身を返す。フェンスが無ければ入力をそのまま返す。
24
44
  function stripCodeFence(text) {
25
45
  const fenced = /```[a-z]*\r?\n([\s\S]*?)```/i.exec(text);
package/dist/agent.js CHANGED
@@ -13,14 +13,14 @@ export function resolveAgentMember(roster, nickname) {
13
13
  return candidate.type === "agent" && candidate.nickname === nickname;
14
14
  });
15
15
  if (!members || members.length === 0) {
16
- return { error: `--by agent nickname not found in pm-members.yaml: ${nickname}` };
16
+ return { error: `--by agent nickname not found in agent-members.yaml: ${nickname}` };
17
17
  }
18
18
  if (members.length !== 1) {
19
- return { error: `--by agent nickname is not unique in pm-members.yaml: ${nickname}` };
19
+ return { error: `--by agent nickname is not unique in agent-members.yaml: ${nickname}` };
20
20
  }
21
21
  const [member] = members;
22
22
  if (member.disabled) {
23
- return { error: `--by agent is disabled in pm-members.yaml: ${nickname}` };
23
+ return { error: `--by agent is disabled in agent-members.yaml: ${nickname}` };
24
24
  }
25
25
  return { member };
26
26
  }
@@ -84,7 +84,7 @@ export function registerAgentCommands(program) {
84
84
  .command("run")
85
85
  .description("Feed a plan to one agent and capture its stdout")
86
86
  .requiredOption("--plan <path>", "Plan file passed to the agent on stdin")
87
- .requiredOption("--by <nickname>", "Agent nickname defined in pm-members.yaml")
87
+ .requiredOption("--by <nickname>", "Agent nickname defined in agent-members.yaml")
88
88
  .option("--out <path>", "Write the agent stdout to this file instead of the terminal")
89
89
  .option("--project <projectId>", "Project id in specdojo.config.json")
90
90
  .option("--exec-defaults <path>", "Override the exec-defaults.yaml path")
@@ -30,7 +30,29 @@ function isStepApplicable(scope, project) {
30
30
  return !!project.execution_path?.trim();
31
31
  }
32
32
  }
33
- function resolveSteps(scope, projectArgs, project) {
33
+ /**
34
+ * register build の対象 project を決める。index build はリポジトリ内のすべての登録簿の
35
+ * generated/pjr-index.md を要求する一方、生成物は git 管理外で新しい worktree には無い。
36
+ * そのため `--project` を明示しない build では、登録簿を持つ全 project を対象にする。
37
+ * `--project` を明示した場合は、従来どおりその project だけを対象にする。
38
+ */
39
+ export function resolveRegisterProjectIds(config, projectId, isProjectExplicit) {
40
+ if (!config)
41
+ return [];
42
+ if (isProjectExplicit) {
43
+ const project = projectId ? config.projects[projectId] : undefined;
44
+ return projectId && isStepApplicable("register", project) ? [projectId] : [];
45
+ }
46
+ return Object.keys(config.projects)
47
+ .filter((id) => isStepApplicable("register", config.projects[id]))
48
+ .sort();
49
+ }
50
+ export function resolveSteps(scope, projectArgs, project, registerProjectIds) {
51
+ const registerSteps = registerProjectIds.map((id) => ({
52
+ scope: "register",
53
+ label: registerProjectIds.length > 1 ? `register build (${id})` : "register build",
54
+ subArgs: ["register", "build", "--project", id],
55
+ }));
34
56
  const candidates = [
35
57
  {
36
58
  scope: "exec",
@@ -42,11 +64,7 @@ function resolveSteps(scope, projectArgs, project) {
42
64
  label: "catalog build",
43
65
  subArgs: ["catalog", "build", ...projectArgs],
44
66
  },
45
- {
46
- scope: "register",
47
- label: "register build",
48
- subArgs: ["register", "build", ...projectArgs],
49
- },
67
+ ...registerSteps,
50
68
  {
51
69
  scope: "yaml-pages",
52
70
  label: "yaml-pages build",
@@ -67,7 +85,8 @@ function resolveSteps(scope, projectArgs, project) {
67
85
  },
68
86
  ];
69
87
  const active = scope === "all" ? candidates : candidates.filter((s) => s.scope === scope);
70
- return active.filter((s) => isStepApplicable(s.scope, project));
88
+ // register の対象は registerProjectIds で解決済み。他の段は従来どおり 1 project で判定する。
89
+ return active.filter((s) => s.scope === "register" || isStepApplicable(s.scope, project));
71
90
  }
72
91
  // ================================
73
92
  // Logging
@@ -110,7 +129,8 @@ export function registerBuildCommand(program) {
110
129
  return;
111
130
  }
112
131
  const projectArgs = projectId ? ["--project", projectId] : [];
113
- const steps = resolveSteps(scope, projectArgs, project);
132
+ const registerProjectIds = resolveRegisterProjectIds(config, projectId, !!opts.project?.trim());
133
+ const steps = resolveSteps(scope, projectArgs, project, registerProjectIds);
114
134
  if (steps.length === 0) {
115
135
  logError(`No applicable steps for scope "${scope}". ` +
116
136
  `Check that required paths are configured in specdojo.config.json.`);
package/dist/dashboard.js CHANGED
@@ -893,6 +893,121 @@ function renderAttentionSection(paths) {
893
893
  lines.push("");
894
894
  return lines;
895
895
  }
896
+ // ================================
897
+ // 9. Exec records (plan / result 一覧)
898
+ // ================================
899
+ export const EXEC_RECORDS_FILE = "exec-records.md";
900
+ function readSpecdojoFrontmatter(filePath) {
901
+ try {
902
+ const content = readFileSync(filePath, "utf8");
903
+ const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
904
+ if (!match)
905
+ return {};
906
+ const parsed = yaml.load(match[1]);
907
+ if (typeof parsed !== "object" || parsed === null)
908
+ return {};
909
+ const specdojo = parsed.specdojo;
910
+ return typeof specdojo === "object" && specdojo !== null && !Array.isArray(specdojo)
911
+ ? specdojo
912
+ : {};
913
+ }
914
+ catch {
915
+ // 壊れた frontmatter の記録も一覧から辿れるよう、属性なしの行として残す。
916
+ return {};
917
+ }
918
+ }
919
+ function frontmatterText(value) {
920
+ if (typeof value === "string" && value.trim())
921
+ return value.trim();
922
+ if (value instanceof Date)
923
+ return value.toISOString();
924
+ return undefined;
925
+ }
926
+ function listMarkdownFiles(dir, suffix) {
927
+ if (!existsSync(dir))
928
+ return [];
929
+ return readdirSync(dir)
930
+ .filter((name) => name.endsWith(suffix))
931
+ .sort();
932
+ }
933
+ // execution/exec/{plans,results} の記録を実行単位(ファイル名の stem)でまとめる。
934
+ // 並びは開始日時の新しい順、開始日時が無いものは後ろに stem 順で置く。
935
+ export function collectExecRecords(execPath) {
936
+ const rows = new Map();
937
+ const rowFor = (stem) => {
938
+ const existing = rows.get(stem);
939
+ if (existing)
940
+ return existing;
941
+ const created = { stem };
942
+ rows.set(stem, created);
943
+ return created;
944
+ };
945
+ for (const name of listMarkdownFiles(join(execPath, "plans"), "-plan.md")) {
946
+ const row = rowFor(name.slice(0, -"-plan.md".length));
947
+ const fm = readSpecdojoFrontmatter(join(execPath, "plans", name));
948
+ row.planFile = name;
949
+ row.taskId ??= frontmatterText(fm.task_id);
950
+ row.mode ??= frontmatterText(fm.mode);
951
+ }
952
+ for (const name of listMarkdownFiles(join(execPath, "results"), "-result.md")) {
953
+ const row = rowFor(name.slice(0, -"-result.md".length));
954
+ const fm = readSpecdojoFrontmatter(join(execPath, "results", name));
955
+ row.resultFile = name;
956
+ row.taskId = frontmatterText(fm.task_id) ?? row.taskId;
957
+ row.mode = frontmatterText(fm.mode) ?? row.mode;
958
+ row.status = frontmatterText(fm.status);
959
+ row.startedAt = frontmatterText(fm.started_at);
960
+ }
961
+ return [...rows.values()].sort((a, b) => {
962
+ if (a.startedAt && b.startedAt && a.startedAt !== b.startedAt) {
963
+ return a.startedAt < b.startedAt ? 1 : -1;
964
+ }
965
+ if (a.startedAt && !b.startedAt)
966
+ return -1;
967
+ if (!a.startedAt && b.startedAt)
968
+ return 1;
969
+ return a.stem.localeCompare(b.stem);
970
+ });
971
+ }
972
+ function execRecordLink(dir, file, label) {
973
+ return file ? `[${label}](../exec/${dir}/${file})` : "-";
974
+ }
975
+ export function buildExecRecordsMarkdown(projectId, rows) {
976
+ const lines = [
977
+ "# 実行記録一覧",
978
+ "",
979
+ `- project_id: \`${projectId}\``,
980
+ `- 再生成: \`specdojo dashboard build --project ${projectId}\``,
981
+ "",
982
+ "> このページは `specdojo dashboard build` が生成した派生ビューです。正本は `execution/exec/` 配下の plan / result であり、このページを手編集しても次回のビルドで失われます。実行記録はサイドバーに載せないため、このページから辿ります。",
983
+ "",
984
+ ];
985
+ if (rows.length === 0) {
986
+ lines.push("- 実行記録はまだありません。");
987
+ return lines.join("\n");
988
+ }
989
+ lines.push(`- 件数: ${rows.length}`, "");
990
+ lines.push("| 開始日時 | task | mode | status | plan | result |");
991
+ lines.push("| --- | --- | --- | --- | --- | --- |");
992
+ for (const row of rows) {
993
+ const task = row.taskId ? `\`${sanitizeDashboardCell(row.taskId)}\`` : "-";
994
+ const mode = row.mode ? `\`${sanitizeDashboardCell(row.mode)}\`` : "-";
995
+ const status = row.status ? `\`${sanitizeDashboardCell(row.status)}\`` : "-";
996
+ lines.push(`| ${row.startedAt ? sanitizeDashboardCell(row.startedAt) : "-"} | ${task} | ${mode} | ${status} | ${execRecordLink("plans", row.planFile, "plan")} | ${execRecordLink("results", row.resultFile, "result")} |`);
997
+ }
998
+ return lines.join("\n");
999
+ }
1000
+ function execRecordsPath(paths) {
1001
+ return join(paths.executionGeneratedPath, "..", "exec");
1002
+ }
1003
+ function renderExecRecordsSection(paths) {
1004
+ const lines = ["## 9. 実行記録", ""];
1005
+ const rows = collectExecRecords(execRecordsPath(paths));
1006
+ const plans = rows.filter((row) => row.planFile).length;
1007
+ const results = rows.filter((row) => row.resultFile).length;
1008
+ lines.push(`- [実行記録一覧](./${EXEC_RECORDS_FILE})(plan ${plans} 件、result ${results} 件)`, "");
1009
+ return lines;
1010
+ }
896
1011
  export function buildDashboardMarkdown(paths) {
897
1012
  const lines = [];
898
1013
  const nowLabel = new Date().toISOString().replace(/\.\d{3}Z$/, "");
@@ -912,6 +1027,7 @@ export function buildDashboardMarkdown(paths) {
912
1027
  lines.push(...renderRecommendedRegisterSection(paths.projectId));
913
1028
  lines.push(...renderAttentionSection(paths));
914
1029
  lines.push(...renderGradeSection(paths));
1030
+ lines.push(...renderExecRecordsSection(paths));
915
1031
  // 各セクションは次のセクションとの区切りとして空行で終わる。最後のセクションの空行を
916
1032
  // そのまま残すと、書き出し時に付ける改行と合わさって末尾が空行2行になり markdownlint の
917
1033
  // MD012 に触れるため、ここで末尾の空行を落とす。
@@ -924,6 +1040,11 @@ export function writeDashboard(paths) {
924
1040
  const mdPath = join(paths.executionGeneratedPath, "dashboard.md");
925
1041
  writeFileSync(mdPath, markdown + "\n", "utf8");
926
1042
  generatedFiles.push(toArtifactPath(mdPath));
1043
+ // 実行記録はサイドバーに載せないため、ダッシュボードから辿る一覧ページを並置する。
1044
+ const recordsPath = join(paths.executionGeneratedPath, EXEC_RECORDS_FILE);
1045
+ const recordsMarkdown = buildExecRecordsMarkdown(paths.projectId, collectExecRecords(execRecordsPath(paths)));
1046
+ writeFileSync(recordsPath, recordsMarkdown + "\n", "utf8");
1047
+ generatedFiles.push(toArtifactPath(recordsPath));
927
1048
  // timeline gantt SVG を並置。tml-index が無い/壊れている場合はスキップ。
928
1049
  const indexPath = join(paths.timelinePath, "tml-index.yaml");
929
1050
  if (existsSync(indexPath)) {
@@ -948,7 +1069,7 @@ export function buildDashboard(opts) {
948
1069
  }
949
1070
  // build-command ステップで使う出力先の解決を公開する。
950
1071
  export function dashboardOutputFiles(paths) {
951
- return ["dashboard.md", "dashboard-timeline-gantt.svg"].map((name) => toArtifactPath(join(paths.executionGeneratedPath, name)));
1072
+ return ["dashboard.md", EXEC_RECORDS_FILE, "dashboard-timeline-gantt.svg"].map((name) => toArtifactPath(join(paths.executionGeneratedPath, name)));
952
1073
  }
953
1074
  // ================================
954
1075
  // CLI command
@@ -0,0 +1,43 @@
1
+ import { runDevcontainerScaffold } from "./devcontainer-scaffold.js";
2
+ import { specdojoPackageRootDir } from "./package-paths.js";
3
+ import { specdojoRootDir } from "./specdojo-config.js";
4
+ export function registerDevcontainerCommands(program) {
5
+ const dc = program.command("devcontainer").description("Dev Container helpers");
6
+ dc.command("scaffold")
7
+ .description("Scaffold .devcontainer/ configuration for the repository")
8
+ .option("--provider <names>", "Comma-separated list of agent providers to install (e.g. claude,codex,opencode,antigravity)", "")
9
+ .option("--editor <names>", "Comma-separated list of editors to install and configure (currently: emacs)", "")
10
+ .option("--ollama", "Add Ollama connection settings", false)
11
+ .option("--cron", "Add cron support", false)
12
+ .option("--tmux", "Add tmux", false)
13
+ .option("--force", "Overwrite existing .devcontainer/", false)
14
+ .option("--dry-run", "Show planned files without writing", false)
15
+ .action(async (opts) => {
16
+ try {
17
+ await runDevcontainerScaffold({
18
+ packageRoot: specdojoPackageRootDir(),
19
+ repoRoot: specdojoRootDir(),
20
+ providers: opts.provider
21
+ ? String(opts.provider)
22
+ .split(",")
23
+ .map((s) => s.trim())
24
+ : [],
25
+ editors: opts.editor
26
+ ? String(opts.editor)
27
+ .split(",")
28
+ .map((s) => s.trim())
29
+ : [],
30
+ ollama: !!opts.ollama,
31
+ cron: !!opts.cron,
32
+ tmux: !!opts.tmux,
33
+ force: !!opts.force,
34
+ dryRun: !!opts.dryRun,
35
+ });
36
+ }
37
+ catch (error) {
38
+ const message = error instanceof Error ? error.message : String(error);
39
+ process.stderr.write(`${message}\n`);
40
+ process.exitCode = 1;
41
+ }
42
+ });
43
+ }