specdojo 0.4.1 → 0.4.3

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 (78) hide show
  1. package/CHANGELOG.md +39 -0
  2. package/dist/catalog/build.js +7 -7
  3. package/dist/catalog/generate.js +27 -12
  4. package/dist/commands/init.js +26 -7
  5. package/dist/commands/orchestrator.js +9 -2
  6. package/dist/dashboard/timeline-build.js +4 -151
  7. package/dist/devcontainer/command.js +1 -1
  8. package/dist/devcontainer/scaffold.js +24 -9
  9. package/dist/exec/core.js +4 -0
  10. package/dist/exec/events.js +17 -6
  11. package/dist/exec/plans-core.js +26 -6
  12. package/dist/exec/plans-generation.js +13 -0
  13. package/dist/exec/plans-storage.js +15 -3
  14. package/dist/exec/register.js +64 -6
  15. package/dist/exec/results.js +5 -1
  16. package/dist/exec/strategy.js +4 -0
  17. package/dist/kata/authoring.js +100 -0
  18. package/dist/kata/command.js +52 -2
  19. package/dist/kata/kata.js +55 -12
  20. package/dist/register/approach.js +29 -1
  21. package/dist/register/core.js +3 -2
  22. package/dist/register/create-commands.js +9 -0
  23. package/dist/register/cross-project.js +141 -0
  24. package/dist/register/derivation.js +28 -7
  25. package/dist/register/external-project.js +136 -0
  26. package/dist/register/item.js +26 -5
  27. package/dist/register/register.js +45 -28
  28. package/dist/schedule/strategy-generate-scope.js +2 -1
  29. package/dist/schedule/strategy-profiles.js +3 -0
  30. package/dist/shared/agent-types.js +4 -0
  31. package/dist/shared/catalog-files.js +31 -0
  32. package/dist/shared/lefthook-scaffold.js +177 -0
  33. package/dist/shared/provider-scaffold.js +3 -3
  34. package/dist/shared/specdojo-config.js +130 -6
  35. package/dist/shared/timeline-index.js +125 -0
  36. package/docs/ja/specdojo/exec-templates/xep-recipe-authoring-template.md +45 -0
  37. package/docs/ja/specdojo/exec-templates/xep-rulebook-authoring-template.md +45 -0
  38. package/docs/ja/specdojo/exec-templates/xep-sample-authoring-template.md +45 -0
  39. package/docs/ja/specdojo/exec-templates/xep-template-authoring-template.md +45 -0
  40. package/docs/ja/specdojo/guides/docs-editing-guide.md +32 -0
  41. package/docs/ja/specdojo/guides/docs-structure-guide.md +1 -1
  42. package/docs/ja/specdojo/guides/exec-config-guide.md +13 -6
  43. package/docs/ja/specdojo/guides/kata-guide.md +4 -0
  44. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +4 -2
  45. package/docs/ja/specdojo/guides/quick-start-guide.md +374 -68
  46. package/docs/ja/specdojo/guides/register-operation-guide.md +30 -0
  47. package/docs/ja/specdojo/guides/remote-host-development-guide.md +10 -2
  48. package/docs/ja/specdojo/guides/ryu-guide.md +18 -4
  49. package/docs/ja/specdojo/guides/use-case-guide.md +2 -2
  50. package/docs/ja/specdojo/references/command-reference.md +77 -29
  51. package/docs/ja/specdojo/references/specdojo-config-reference.md +41 -12
  52. package/docs/ja/specdojo/standards/recipe-authoring-standard.md +10 -10
  53. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +13 -13
  54. package/docs/ja/specdojo/standards/sample-authoring-standard.md +4 -4
  55. package/docs/ja/specdojo/standards/template-authoring-standard.md +4 -4
  56. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +6 -0
  57. package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +6 -6
  58. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +21 -4
  59. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +34 -0
  60. package/package.json +2 -2
  61. package/templates/antigravity/README.md +1 -1
  62. package/templates/antigravity/settings.global.json +5 -0
  63. package/templates/claude/README.md +11 -8
  64. package/templates/claude/settings.edit.json +10 -1
  65. package/templates/claude/settings.orchestrator.json +90 -0
  66. package/templates/claude/settings.report.json +14 -1
  67. package/templates/claude/settings.review.json +13 -1
  68. package/templates/codex/README.md +7 -5
  69. package/templates/codex/rules/specdojo.rules +48 -0
  70. package/templates/devcontainer/devcontainer.json +1 -4
  71. package/templates/init-agent-members.yaml +3 -3
  72. package/templates/lefthook/tools/install-lefthook.mjs +46 -0
  73. package/templates/lefthook/tools/specdojo-pre-commit.mjs +207 -0
  74. package/templates/opencode/README.md +8 -2
  75. package/templates/opencode/agents/opencode-executor.md +2 -0
  76. package/templates/opencode/agents/opencode-review-executor.md +2 -0
  77. package/templates/opencode/agents/specdojo-orchestrator.md +60 -6
  78. /package/dist/{shared → kata}/yaml-schema-modeline.js +0 -0
@@ -18,7 +18,7 @@ SpecDojo CLI の初期設定から始め、register で課題と判断を整理
18
18
  **この文書で分かること**
19
19
 
20
20
  - question の起票から decision、仕様書の更新、change-request による修正までを記帳する流れ
21
- - CLI の初期設定と、register / schedule / routine の使い分け
21
+ - CLI の初期設定と、register のユースケース別の使い方
22
22
  - issue / decision / todo から成果物カタログと Schedule へ展開する手順
23
23
  - npm package の kata を参照し、必要なものだけ eject する方法
24
24
 
@@ -68,14 +68,15 @@ Your display name [Project Owner]: 店主
68
68
  Orchestrator providers (...) [codex]: claude <- 使う AI ツールを 1 つ選ぶ
69
69
  Delegate work to agents (exec)? [y/N]: <- Enter(実戦は後で設定する)
70
70
  Create a Dev Container? [y/N]: y <- y(Dev Container を作る。使わない場合は Enter)
71
- Add the recommended Dev Container settings? [Y/n]: <- Enter(推奨 preset を入れる)
71
+ Dev Container preset (minimal, recommended, full) [recommended]: <- Enter(推奨 preset を選ぶ)
72
+ Create Git hooks with lefthook? [y/N]: <- Enter(この体験では作らない)
72
73
  ```
73
74
 
74
75
  入力が不正な場合は理由が表示され、同じ質問だけがもう一度表示されます。たとえば provider に
75
76
  `claud` と入力すると、利用可能な provider の一覧に続いて provider の質問だけが再表示されます。
76
77
  それまでに答えた project や名簿の内容を入力し直す必要はありません。
77
78
 
78
- Dev Container を作る質問に `y`、推奨 preset に Enter(既定の「はい」)と答えると、tmux・Emacs・Vim・推奨の VS Code 拡張と設定・`.vscode/extensions.json` が入った環境が生成されます。作成したコンテナは、VS Code の「コンテナーで再度開く」または `devcontainer up` で開けます(詳しい説明は [[specdojo:remote-host-development-guide]] を参照)。Dev Container を使わずに手元の環境で進めたい場合は、Dev Container の質問に Enter または `n`(いいえ)と答えて先へ進めます。この 10 分の体験は記帳だけで進められるため、コンテナを開かずにそのままホスト環境で続けて構いません。
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 分の体験は記帳だけで進められるため、コンテナを開かずにそのままホスト環境で続けて構いません。
79
80
 
80
81
  登録簿は `docs/ja/projects/prj-0001/controls/project-register/` に作られます。オーケストレーターで進める場合は、終了時に表示される `npm run orch:<provider>` で起動します。成果物カタログは対話では作られません。成果物の構成が定まったら、[[#41-成果物カタログを作成する|成果物カタログを作成する]] に従って `catalog_path` を設定し、`catalog scaffold` で追加してください。
81
82
 
@@ -227,7 +228,7 @@ npx specdojo init
227
228
  ```
228
229
 
229
230
  `specdojo init` は、project ID と名前、人の nickname と表示名、利用する agent provider、
230
- exec・Dev Container の要否を順に質問し、Dev Container を選んだ場合だけ推奨 preset を入れるか(既定は「はい」)を続けて質問します。成果物カタログは対話では質問せず、`--catalog <size>` を
231
+ exec・Dev Container・Git hook の要否を順に質問し、Dev Container を選んだ場合だけ `minimal` / `recommended` / `full` の preset(既定は `recommended`)を続けて質問します。Git hook は既定では作りません。成果物カタログは対話では質問せず、`--catalog <size>` を
231
232
  明示した場合にだけ初期化時に作成します。選択に応じて設定、登録簿、人と
232
233
  agent の名簿、provider の scaffold、`package.json` の `orch:<provider>`、exec の起動設定を
233
234
  作成します。exec の親検証は、対応する npm script が `package.json` にあるものだけを設定し、
@@ -236,7 +237,7 @@ agent の名簿、provider の scaffold、`package.json` の `orch:<provider>`
236
237
  それまでの回答は保持します。非対話環境や `--yes` では再質問せず、不正な指定をエラーとして終了します。
237
238
 
238
239
  CI や標準入力が端末でない環境では質問しません。次のようにオプションだけで同じ初期設定を
239
- 行えます。`--devcontainer` を指定した場合は既定で推奨 preset(tmux・Emacs・Vim・推奨の VS Code 拡張と設定)が入ります(preset を使わない場合は `--devcontainer-preset none` を指定します)。省略値は画面に表示されます。
240
+ 行えます。`--devcontainer` を指定した場合は既定で `recommended` preset(tmux・Emacs・Vim・推奨の VS Code 拡張と設定)が入ります。CLI と最低限だけにする場合は `--devcontainer-preset minimal` を指定します。従来の `none` も `minimal` と同じ意味で受け付けます。省略値は画面に表示されます。
240
241
 
241
242
  ```bash
242
243
  npx specdojo init --yes \
@@ -247,6 +248,7 @@ npx specdojo init --yes \
247
248
  --provider claude,codex \
248
249
  --exec \
249
250
  --devcontainer \
251
+ --lefthook \
250
252
  --dry-run
251
253
  ```
252
254
 
@@ -334,7 +336,7 @@ npx specdojo config init
334
336
 
335
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設定リファレンス]] で確認できます。
336
338
 
337
- プロダクト文書は `app1/docs/ja/product/`、プロジェクト文書と SpecDojo の型(Kata)は `app1-specdojo/docs/ja/projects/` と `app1-specdojo/docs/ja/specdojo/` に置きます。現行実装では1つの項目で両リポジトリを自動統合できないため、プロダクト文書や実装も変更する項目は分けるか、人が統合を管理します。詳細は [ドキュメント構成ガイド](docs-structure-guide.md) の `別リポジトリ構成` を参照してください。
339
+ プロダクト文書は `app1/docs/ja/product/`、プロジェクト文書は `app1-specdojo/docs/ja/projects/` に置きます。同梱の SpecDojo の型(Kata)は `app1-specdojo/docs/ja/specdojo/`、このリポジトリで新しく作る kata は `app1-specdojo/docs/ja/kata/` から解決します。現行実装では1つの項目で両リポジトリを自動統合できないため、プロダクト文書や実装も変更する項目は分けるか、人が統合を管理します。詳細は [ドキュメント構成ガイド](docs-structure-guide.md) の `別リポジトリ構成` を参照してください。
338
340
 
339
341
  成果物と実装を常に同じ変更・履歴として扱う場合に限り、**同一リポジトリ構成**としてプロダクトリポジトリのルートで同じ初期化手順を実行できます。CLI は構成を強制しません。
340
342
 
@@ -348,6 +350,26 @@ npx specdojo config scaffold --provider <name>
348
350
  `<name>` には `antigravity`、`claude`、`codex`、`copilot`、`opencode` を指定します。従来の
349
351
  `specdojo exec scaffold --provider <name>` も互換入口として利用できます。
350
352
 
353
+ commit 前に文書と SpecDojo の入力を検査する場合は、生成予定と `package.json` への追加内容を
354
+ dry-run で確認してから lefthook を配置します。
355
+
356
+ ```bash
357
+ npx specdojo config scaffold --lefthook --dry-run
358
+ npx specdojo config scaffold --lefthook
359
+ npm install
360
+ ```
361
+
362
+ 生成した hook は、変更した Markdown と YAML だけを Prettier で整形し、変更した Markdown だけを
363
+ markdownlint で検査します。対象 project の `project_register_path` 配下を変更した場合は
364
+ `register build`、`catalog_path` 配下を変更した場合は `catalog validate` も実行します。
365
+ `catalog_path` がない構成には catalog の検査を生成せず、時間のかかるテストも pre-commit には
366
+ 含めません。SpecDojo の文書が通る `.markdownlint.jsonc` と、provider の agent 定義を検査から外す
367
+ `.markdownlintignore` も生成します。既存の markdownlint 設定と ignore は `--force` を付けても保持します。
368
+ `lefthook.yml` と `tools/` の既存ファイルは `--force` なしでは上書きしません。
369
+ 必要な npm script と devDependencies は書き込み前に表示し、同名の既存項目は `--force` を付けても
370
+ 保持します。linked worktree または `node_modules` がない環境では installer が安全に skip するため、
371
+ primary worktree で `npm install` または `node tools/install-lefthook.mjs` を実行してください。
372
+
351
373
  Antigravity CLI を無人実行する場合は、先に dry-run でユーザー設定へ追加する permission rule を確認し、明示的に適用します。このグローバル設定は利用者のすべてのリポジトリに効きます。通常の scaffold はユーザーディレクトリへ触れません。
352
374
 
353
375
  ```bash
@@ -362,7 +384,15 @@ npx specdojo devcontainer scaffold --provider <name> --preset recommended --dry-
362
384
  npx specdojo devcontainer scaffold --provider <name> --preset recommended
363
385
  ```
364
386
 
365
- Dev Container の `<name>` には `antigravity`、`claude`、`codex`、`opencode` を指定します。`--preset recommended` を指定すると、tmux・Emacs・Vim・推奨の VS Code 拡張と設定がまとめて設定されます。既存の `.devcontainer/` は通常実行では上書きされません。生成設定は provider の設定ディレクトリを名前付きボリュームに保存し、ホストの認証情報・秘密鍵・`.env` はマウントしません。preset を使わない場合、Ollama 接続、cron、tmux は必要な場合だけ `--ollama`、`--cron`、`--tmux` で個別に足せます。詳しい説明は [[specdojo:remote-host-development-guide]] を参照してください。
387
+ 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]] を参照してください。
388
+
389
+ | preset | 内容 |
390
+ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
391
+ | `minimal` | 選んだ provider の CLI と SpecDojo の動作に必要な最小構成。preset を省略した場合と同じ。 |
392
+ | `recommended` | `minimal` に `gh`、Emacs、Vim、tmux、文書作業向けの VS Code 拡張・設定を追加する。 |
393
+ | `full` | `recommended` に ripgrep、fd、fzf、yq、shellcheck、shfmt、Ollama 接続、cron を追加する。fd は `fd-find` package から `fd` コマンドとして利用できる。 |
394
+
395
+ `--ollama`・`--cron`・`--tmux`・`--editor` はどの preset にも個別に追加できます。詳しい説明は [[specdojo:remote-host-development-guide]] を参照してください。
366
396
 
367
397
  設定したプロジェクトを確認します。
368
398
 
@@ -396,117 +426,393 @@ npx specdojo kata status --kind rulebook
396
426
 
397
427
  CLI と同じバージョンで使う `exec-template` と `schema` は npm package 参照固定であり、eject できません。`kata install --all` は docs サイト配信やオフライン運用で全量コピーするときの選択肢で、通常の導入では実行しません。
398
428
 
399
- ## 3. registerで課題と判断を整理する
429
+ ## 3. registerをユースケース別に使う
400
430
 
401
- プロジェクトの開始時点では、解決すべき問題、判断が必要な事項、実施する作業が混在しています。まず register に個票として記録し、issue → decision → todo の順に具体化します。
431
+ register は、後から追跡したい問題・判断・作業を個票として残す入口です。この章では、よくある状況ごとに「こんなとき」「チャットでの頼み方」「コマンド」を並べます。type の詳しい選び方と状態遷移は [登録簿運用ガイド](register-operation-guide.md)、approach と実行 pipeline の詳細は [exec運用ガイド](exec-operation-guide.md) を参照してください。複数の機能を組み合わせたシナリオから読みたい場合は [[specdojo:use-case-guide|ユースケース別ガイド]] へ進んでください。
402
432
 
403
- ```text
404
- issue(何が問題か)
405
- -> decision(何を対象とするか)
406
- -> todo(成果物カタログを作成する)
407
- -> dct-<domain>.yaml
408
- -> schedule
433
+ 初期設定で register を作らなかった場合は、先に `.specdojo/specdojo.config.json` の `project_register_path` を設定して登録簿を用意します。
434
+
435
+ ```bash
436
+ # チャット:「<project-id> の登録簿を用意して」
437
+ npx specdojo register scaffold --project <project-id>
409
438
  ```
410
439
 
411
- ### 3.1. 登録簿を用意する
440
+ コマンドの `<project-id>`、`<PJR-ID>`、`<deliverable-doc-id>`、`<kata-doc-id>` は実際の値に置き換えます。`register add` が表示した `PJR-XXXX` を、続く `exec run` で使います。起票と同時に commit まで行う必要がある場合は `register add` に `--commit` を付けます。
441
+
442
+ ### 3.1. 作業を起票してAIに任せる
412
443
 
413
- `.specdojo/specdojo.config.json` の `project_register_path` を設定し、登録簿を初期生成します。
444
+ **こんなとき:** 完了条件を書ける作業を todo として追跡し、難しさに合う agent へ安全に任せたいとき。
445
+
446
+ `difficulty` は agent の能力や作業範囲から選びます。`exec run` は `.specdojo/exec-defaults.yaml` の `routing` に同じ難しさの設定があれば、その executor・reporter・rate limit 対応を使います。`--executor-by` などをコマンドで指定した場合は、その指定が優先されます。
447
+
448
+ | `difficulty` | 目安 | 振り分け |
449
+ | ------------ | ------------------------------------------------ | ----------------------------------------------- |
450
+ | `hard` | 設計判断、広い影響範囲、複数ファイルの難しい変更 | `routing.hard`。推論力の高い agent を割り当てる |
451
+ | `medium` | 手順と完了条件が明確な通常の実装・文書変更 | `routing.medium`。標準の executor を割り当てる |
452
+ | `easy` | 範囲が狭く、機械的で、失敗時の影響が小さい変更 | `routing.easy`。軽量な executor を割り当てる |
414
453
 
415
454
  ```bash
416
- # チャット:「<project-id> の登録簿を用意して」
417
- npx specdojo register scaffold --project <project-id>
455
+ # チャット:「中くらいの難しさの todo『検索結果の空表示を直す』を起票して、worktree で agent に任せて」
456
+ npx specdojo register add \
457
+ --project <project-id> \
458
+ --type todo \
459
+ --title "検索結果の空表示を直す" \
460
+ --topic fix-empty-search-result \
461
+ --difficulty medium
462
+ npx specdojo exec run \
463
+ --project <project-id> \
464
+ --register <PJR-ID> \
465
+ --worktree
418
466
  ```
419
467
 
420
- ### 3.2. issue、decision、todoを登録する
468
+ 成功すると個票は `review` になります。成果物と result を人が確認した後、`register close` で完了させます。
469
+
470
+ ### 3.2. 問題を調べて直す
421
471
 
422
- 次の例では、初期スコープと必要な成果物が未確定な状態から、成果物カタログを作成する作業までを3つの個票で追跡します。コマンドはまとめて示していますが、実運用では issue の調査結果を受けて decision を起票し、決定後に todo を起票します。
472
+ **こんなとき:** 症状は分かっているが、原因や直し方を調べる必要があるとき。issue の個票へ問題、影響、原因、対応結果を残します。
423
473
 
424
474
  ```bash
425
- # 1. 解決すべき問題を記録する
426
- # チャット:「issue を起票して。タイトルは『初期スコープと必要成果物が未確定』、個票あり、topic は clarify-initial-scope」
475
+ # チャット:「issue『CSV 出力で文字化けする』を起票して、難しさ hard で調査と修正を任せて」
427
476
  npx specdojo register add \
428
477
  --project <project-id> \
429
478
  --type issue \
430
- --title "初期スコープと必要成果物が未確定" \
431
- --topic clarify-initial-scope
479
+ --title "CSV 出力で文字化けする" \
480
+ --topic csv-encoding \
481
+ --difficulty hard
482
+ npx specdojo exec run \
483
+ --project <project-id> \
484
+ --register <PJR-ID> \
485
+ --worktree
486
+ ```
487
+
488
+ 原因調査だけで終えず、個票の完了条件に再現条件、修正範囲、検証方法を書いてから実行します。
489
+
490
+ ### 3.3. 決めることを残す
432
491
 
433
- # 2. 選択肢と決定を記録する
434
- # チャット:「decision を起票して。タイトルは『初期スコープと対象成果物を決定する』、個票あり、topic は decide-initial-scope」
492
+ **こんなとき:** まだ答えがない論点を question として残したいとき、または選択肢・採択理由を decision として記録したいとき。
493
+
494
+ ```bash
495
+ # チャット:「question『支払い方法をどこまで扱うか』を起票して」
496
+ npx specdojo register add \
497
+ --project <project-id> \
498
+ --type question \
499
+ --title "支払い方法をどこまで扱うか" \
500
+ --topic payment-scope
501
+
502
+ # チャット:「decision『初期リリースの支払い方法を決める』を起票して」
435
503
  npx specdojo register add \
436
504
  --project <project-id> \
437
505
  --type decision \
438
- --title "初期スコープと対象成果物を決定する" \
439
- --topic decide-initial-scope
506
+ --title "初期リリースの支払い方法を決める" \
507
+ --topic decide-payment-methods
508
+ ```
440
509
 
441
- # 3. 決定内容を実行可能な作業にする
442
- # チャット:「高優先度の todo を起票して。タイトルは『プロジェクト定義の成果物カタログを作成する』、個票あり、topic は create-project-definition-catalog」
510
+ question から decision、仕様書への反映、後日の変更までを一度通す場合は [[#1-10分で体験する--仕様の判断台帳|1. 10分で体験する — 仕様の判断台帳]] の流れを使います。decision は agent に判断させる実行対象ではなく、人が選択肢と理由を確認して `register close` します。
511
+
512
+ ### 3.4. 合意した範囲を変える
513
+
514
+ **こんなとき:** 決定済みの仕様、スコープ、成果物へ変更を加え、理由と影響を追跡したいとき。
515
+
516
+ ```bash
517
+ # チャット:「change-request『交通系電子マネーを支払い方法に加える』を起票して、影響を確認して反映して」
518
+ npx specdojo register add \
519
+ --project <project-id> \
520
+ --type change-request \
521
+ --title "交通系電子マネーを支払い方法に加える" \
522
+ --topic add-ic-card-payment \
523
+ --difficulty medium
524
+ npx specdojo exec run \
525
+ --project <project-id> \
526
+ --register <PJR-ID> \
527
+ --worktree
528
+ ```
529
+
530
+ 個票の `変更要求`、`影響評価`、`審査・決定` を埋め、元の decision や仕様書を参照できるようにします。
531
+
532
+ ### 3.5. リスクと気づきを残す
533
+
534
+ **こんなとき:** 発生前に対応を追跡するなら risk、対応や判断を要求しない観察記録なら note として残したいとき。
535
+
536
+ ```bash
537
+ # チャット:「risk『移行日に旧端末が残る』を起票して」
538
+ npx specdojo register add \
539
+ --project <project-id> \
540
+ --type risk \
541
+ --title "移行日に旧端末が残る" \
542
+ --topic legacy-terminal-on-migration \
543
+ --priority high
544
+
545
+ # チャット:「note『検証環境では朝に負荷が上がる』を記録して」
546
+ npx specdojo register add \
547
+ --project <project-id> \
548
+ --type note \
549
+ --title "検証環境では朝に負荷が上がる" \
550
+ --topic morning-load-observation
551
+ ```
552
+
553
+ risk は必要なら `exec run --register` で軽減策を実行できます。note は `open` のまま追記する記録で、close や agent 実行の対象にはしません。対応が必要になったら、note を元に todo や issue を起票します。
554
+
555
+ ### 3.6. 成果物を作る・直す
556
+
557
+ **こんなとき:** 成果物カタログにある 1 文書を、利用できる kata の整備状況に合う進め方で作成・更新したいとき。
558
+
559
+ | `approach` | 選ぶ状況 |
560
+ | --------------- | ---------------------------------------------------------------- |
561
+ | `fully-guided` | rulebook・recipe・sample・template が揃い、すべてを基準に進める |
562
+ | `recipe-guided` | recipe を主な手順として使い、ほかの kata が未整備でも進める |
563
+ | `retrofit` | 先にある実装や現行動作を調べ、その証拠から成果物を作成・更新する |
564
+
565
+ ```bash
566
+ # チャット:「成果物 <deliverable-doc-id> を fully-guided で直す todo を起票して、agent に任せて」
443
567
  npx specdojo register add \
444
568
  --project <project-id> \
445
569
  --type todo \
446
- --priority high \
447
- --title "プロジェクト定義の成果物カタログを作成する" \
448
- --topic create-project-definition-catalog
570
+ --title "対象成果物を実践の型に沿って改訂する" \
571
+ --topic revise-deliverable \
572
+ --difficulty hard \
573
+ --approach fully-guided \
574
+ --target <deliverable-doc-id>
575
+ npx specdojo exec run \
576
+ --project <project-id> \
577
+ --register <PJR-ID> \
578
+ --worktree
449
579
  ```
450
580
 
451
- `register add` の出力に表示された `PJR-XXXX` を控えます。すべての登録項目は、背景、選択肢、完了条件、結論などを記録する type 別の個票として生成されます。個票 Frontmatter が構造化フィールドの正本であり、一覧は個票から生成されます。成果物カタログを複数ドメインに分ける場合は、原則として `dct-<domain>.yaml` ごとに todo 個票を起票すると、対象と完了条件を追跡しやすくなります。
581
+ `recipe-guided` または `retrofit` を使う場合は、上の `--approach fully-guided` を選んだ値へ置き換えます。`--target` には成果物カタログで解決できる成果物の doc id を 1 件だけ指定します。カタログの `done_criteria` と個票の完了条件が、どちらも plan に入ります。
582
+
583
+ ### 3.7. 成果物とkataを一組で作る
452
584
 
453
- agent の run と並行して記帳し、その変更だけを commit まで完了させる場合は `register add` や状態遷移コマンドへ `--commit` を付けます。同じ project の `register lifecycle` 枠が空くまで待って記帳・一覧再生成・commit を行うため、別の run の記帳・統合と競合しません。対象の個票や event に既存の未 commit 変更がある場合は、混在を避けるため書き込み前に停止します。
585
+ **こんなとき:** プロジェクトの初期立ち上げで、成果物だけでなく、その成果物を繰り返し作るための rulebook・recipe・sample・template も同じ実行で初期整備したいとき。
454
586
 
455
- | type | 記録する内容 | 完了状態 | agent実行 |
456
- | ---------- | -------------------------------------- | --------- | ------------------------------------------ |
457
- | `issue` | 発生している問題、影響、原因、対応結果 | `done` | `exec run --register` で対応できる |
458
- | `decision` | 判断の背景、選択肢、決定内容、決定理由 | `decided` | 対象外。人が判断して `register close` する |
459
- | `todo` | 実施内容、完了条件、作業結果 | `done` | `exec run --register` で対応できる |
587
+ ```bash
588
+ # チャット:「成果物 <deliverable-doc-id> と必要な kata 一式を bootstrap で作る todo を起票して、agent に任せて」
589
+ npx specdojo register add \
590
+ --project <project-id> \
591
+ --type todo \
592
+ --title "成果物と実践の型を初期整備する" \
593
+ --topic bootstrap-deliverable-kata \
594
+ --difficulty hard \
595
+ --approach bootstrap \
596
+ --target <deliverable-doc-id>
597
+ npx specdojo exec run \
598
+ --project <project-id> \
599
+ --register <PJR-ID> \
600
+ --worktree
601
+ ```
602
+
603
+ `bootstrap` は初期整備用です。既に信頼できる kata が揃っている成果物の通常改訂には `fully-guided` を使います。
604
+
605
+ ### 3.8. kataを直す
460
606
 
461
- ### 3.3. 判断を確定してカタログ作成へ進む
607
+ **こんなとき:** 成果物ではなく、作り方・手順・例・雛形そのものを改善したいとき。
462
608
 
463
- issue に人が着手し、個票へ問題、影響、原因、対応方針を記入して完了させます。
609
+ | 直す kata | `approach` |
610
+ | --------- | ---------------------- |
611
+ | rulebook | `rulebook-maintenance` |
612
+ | recipe | `recipe-maintenance` |
613
+ | sample | `sample-maintenance` |
614
+ | template | `template-maintenance` |
464
615
 
465
616
  ```bash
466
- # チャット:「issue <issue-id> に着手して」
467
- npx specdojo register start --project <project-id> --id <issue-id>
617
+ # チャット:「rulebook <kata-doc-id> を見直す todo を起票して、agent に任せて」
618
+ npx specdojo register add \
619
+ --project <project-id> \
620
+ --type todo \
621
+ --title "成果物の作成ルールを見直す" \
622
+ --topic maintain-rulebook \
623
+ --difficulty hard \
624
+ --approach rulebook-maintenance \
625
+ --target <kata-doc-id>
626
+ npx specdojo exec run \
627
+ --project <project-id> \
628
+ --register <PJR-ID> \
629
+ --worktree
630
+ ```
468
631
 
469
- # issue 個票を編集して調査結果を記録する
632
+ ほかの kata を直す場合は、表に従って `--approach` を置き換えます。`--target` には文書索引で解決でき、approach の種別と一致する kata の doc id を 1 件だけ指定します。
470
633
 
471
- # チャット:「issue <issue-id> を『問題、影響、対応方針を整理』で完了して」
472
- npx specdojo register close \
634
+ ### 3.9. 既存成果物からkataを新しく作る
635
+
636
+ **こんなとき:** 成果物は既にあり、その実績を手本に rulebook など 1 種類の kata だけを新しく作りたいとき。
637
+
638
+ ```bash
639
+ # チャット:「成果物 <deliverable-doc-id> を手本に <kata-id> の rulebook を新しく作る todo を起票して、agent に任せて」
640
+ npx specdojo register add \
641
+ --project <project-id> \
642
+ --type todo \
643
+ --title "既存成果物からrulebookを作る" \
644
+ --topic author-rulebook \
645
+ --difficulty hard \
646
+ --approach rulebook-authoring \
647
+ --target <kata-authority>:<name>-rulebook \
648
+ --target <deliverable-doc-id>
649
+ npx specdojo exec run \
473
650
  --project <project-id> \
474
- --id <issue-id> \
475
- --conclusion "問題、影響、対応方針を整理"
651
+ --register <PJR-ID> \
652
+ --worktree
476
653
  ```
477
654
 
478
- issue の結論を基に、decision 個票へ選択肢、決定内容、理由を記入します。decision は agent の実行対象ではないため、人が判断して完了させます。
655
+ 1 件目の `--target` は新しい kata ID、2 件目以降は任意の手本成果物です。成果物も型もまだない初期立ち上げには `bootstrap` を使います。手本なしで kata だけを作る場合は 2 件目以降を省略します。recipe / sample / template では `approach` と ID の末尾を同じ種類へ置き換えます。
656
+
657
+ ### 3.10. 統合後にreviewのagentへ確かめさせる
658
+
659
+ **こんなとき:** worktree の成果を統合した後、完了条件・result・差分・検証結果を別の review agent に照合させたいとき。
479
660
 
480
661
  ```bash
481
- # チャット:「decision <decision-id> に着手して」
482
- npx specdojo register start --project <project-id> --id <decision-id>
662
+ # チャット:「todo または issue <PJR-ID> を worktree で実行し、統合後の review まで任せて」
663
+ npx specdojo exec run \
664
+ --project <project-id> \
665
+ --register <PJR-ID> \
666
+ --worktree \
667
+ --post-review
668
+ ```
483
669
 
484
- # decision 個票を編集して判断内容を記録する
670
+ `--post-review` は worktree 実行でだけ使えます。todo と issue は判定が `complete` または `complete-with-findings` なら自動 close され、`incomplete` なら `waiting` に戻ります。question、decision、および SpecDojo 自身のコードを変えた項目は自動 close されません。
485
671
 
486
- # チャット:「decision <decision-id> を『採用するスコープと成果物を決定』で完了して」
487
- npx specdojo register close \
672
+ ### 3.11. 夜の間に流す
673
+
674
+ **こんなとき:** 人が内容と完了条件を確認した todo・issue だけを、夜間に worktree と post-review 付きでまとめて流したいとき。
675
+
676
+ ```bash
677
+ # チャット:「todo または issue <PJR-ID> を夜間実行してよい印に更新して」
678
+ npx specdojo register update \
488
679
  --project <project-id> \
489
- --id <decision-id> \
490
- --conclusion "採用するスコープと成果物を決定"
680
+ --id <PJR-ID> \
681
+ --autopilot approved \
682
+ --commit
683
+
684
+ # チャット:「<project-id> の承認済み項目を、最大10件、並列2件で夜間実行して」
685
+ npx specdojo orchestrator night \
686
+ --project <project-id> \
687
+ --max-items 10 \
688
+ --parallel 2 \
689
+ --max-consecutive-failures 2
690
+ ```
691
+
692
+ 夜間 queue に入るのは `autopilot: approved` の付いた `open` の todo と issue だけです。まず対象を確認する場合は、`orchestrator night` に `--dry-run` を付けます。朝の報告には close、`waiting`、失敗した項目がまとめられます。
693
+
694
+ ### 3.12. 止まった項目を再開する
695
+
696
+ **こんなとき:** register の worktree 実行が agent、検証、reporter、統合の途中で止まり、残っている成果を生かして続けるか、破棄して最初からやり直したいとき。
697
+
698
+ ```bash
699
+ # チャット:「<PJR-ID> を止まった段から再開して」
700
+ npx specdojo exec run \
701
+ --project <project-id> \
702
+ --register <PJR-ID> \
703
+ --worktree \
704
+ --resume
705
+
706
+ # チャット:「<PJR-ID> は親検証の失敗を直すため、executor から再開して」
707
+ npx specdojo exec run \
708
+ --project <project-id> \
709
+ --register <PJR-ID> \
710
+ --worktree \
711
+ --resume \
712
+ --resume-from executor
713
+
714
+ # チャット:「<PJR-ID> の残っている worktree を破棄し、最初からやり直して」
715
+ npx specdojo exec run \
716
+ --project <project-id> \
717
+ --register <PJR-ID> \
718
+ --worktree \
719
+ --force-restart
720
+ ```
721
+
722
+ | 指定 | 使い分け |
723
+ | ------------------------ | -------------------------------------------------------------------- |
724
+ | `--resume` | checkpoint が示す executor、reporter、統合の段から再開する |
725
+ | `--resume-from executor` | reporter から再開可能だが、成果物を executor に直させる必要がある |
726
+ | `--force-restart` | 再開用 worktree と未統合の成果を破棄して、項目全体を最初から実行する |
727
+
728
+ `--force-restart` は未統合の成果を破棄します。先に evidence と agent のログを確認し、再利用しないと判断した場合だけ指定します。
729
+
730
+ ### 3.13. 別のproject・別のリポジトリへ起票する
731
+
732
+ **こんなとき:** 作業中の気づきが別 project の責務であり、その project の登録簿と統合ブランチへ、起票元との関係を残して渡したいとき。
733
+
734
+ 同じリポジトリ内の別 project には、対象 project と起票元を project 修飾 ID で指定します。
735
+
736
+ ```bash
737
+ # チャット:「prj-0001:PJR-AB12 から派生した todo を prj-0002 へ起票して commit して」
738
+ npx specdojo register add \
739
+ --project prj-0002 \
740
+ --type todo \
741
+ --title "共通 API の変更を追跡する" \
742
+ --topic shared-api-change \
743
+ --from prj-0001:PJR-AB12 \
744
+ --commit
491
745
  ```
492
746
 
493
- provider 未設定でも、`issue` や `todo` から生成される exec plan を確認できます。
747
+ 別リポジトリの場合は、呼び出し元の `.specdojo/specdojo.config.json` のトップレベルへ相手を宣言します。
748
+
749
+ ```json
750
+ {
751
+ "external_projects": {
752
+ "customer": {
753
+ "path": "../customer-specdojo",
754
+ "project_id": "prj-0002"
755
+ }
756
+ }
757
+ }
758
+ ```
759
+
760
+ 宣言した別名を `--project` に使い、相手側にある起票元は `<別名>:PJR-XXXX` で指定します。
494
761
 
495
762
  ```bash
496
- # チャット:「issue または todo <issue-or-todo-id> の実行計画を作って」
497
- npx specdojo exec plan --project <project-id> --register <issue-or-todo-id>
763
+ # チャット:「外部 project customer の PJR-AB12 から派生した todo を、customer へ起票して commit して」
764
+ npx specdojo register add \
765
+ --project customer \
766
+ --type todo \
767
+ --title "相手側で追跡する" \
768
+ --topic remote-follow-up \
769
+ --from customer:PJR-AB12 \
770
+ --commit
498
771
  ```
499
772
 
500
- agent 設定が完了している場合は、同じ登録項目を実行できます。成功後は `review` になるため、人が result と成果物を確認して `register close` します。
773
+ どちらも別 project への起票では `--commit` が必須です。別リポジトリでは、相手に SpecDojo 0.4.2 以上と対象 project の統合ブランチが必要です。push は行わず、close などの状態遷移は対象 project の作業ツリーで行います。
774
+
775
+ ### 3.14. issueからdecision、todo、成果物カタログへ進む
776
+
777
+ プロジェクト立ち上げ時に、問題、判断、実施作業がまだ混在している場合は、次の順で具体化します。この流れは register の履歴を、発展手順の成果物カタログと Schedule へつなぐ橋渡しです。
778
+
779
+ ```text
780
+ issue(何が問題か)
781
+ -> decision(何を対象とするか)
782
+ -> todo(成果物カタログを作成する)
783
+ -> dct-<domain>.yaml
784
+ -> schedule
785
+ ```
501
786
 
502
787
  ```bash
503
- # チャット:「issue または todo <issue-or-todo-id> を agent に実行させて」
504
- npx specdojo exec run --project <project-id> --register <issue-or-todo-id>
788
+ # チャット:「issue『初期スコープと必要成果物が未確定』を起票して」
789
+ npx specdojo register add \
790
+ --project <project-id> \
791
+ --type issue \
792
+ --title "初期スコープと必要成果物が未確定" \
793
+ --topic clarify-initial-scope
794
+
795
+ # チャット:「decision『初期スコープと対象成果物を決定する』を起票して」
796
+ npx specdojo register add \
797
+ --project <project-id> \
798
+ --type decision \
799
+ --title "初期スコープと対象成果物を決定する" \
800
+ --topic decide-initial-scope
801
+
802
+ # チャット:「高優先度の todo『プロジェクト定義の成果物カタログを作成する』を起票して」
803
+ npx specdojo register add \
804
+ --project <project-id> \
805
+ --type todo \
806
+ --priority high \
807
+ --title "プロジェクト定義の成果物カタログを作成する" \
808
+ --topic create-project-definition-catalog
505
809
  ```
506
810
 
507
- 個票内の `_TODO_` を解消してから `register close` すると、個票の文書状態も `ready` になります。基本手順では、成果物カタログ作成の todo を `open` のまま残し、`成果物カタログからscheduleへ展開する` で `dct-<domain>.yaml` を作成・検証した後に完了させます。登録簿は立ち上げ時の課題・判断・作業履歴、成果物カタログは合意後の管理対象成果物の正本です。同じ計画済み作業を register と schedule の両方で継続管理しません。
811
+ issue の調査結果を decision の選択肢へ、decision の結論を todo の完了条件へ引き継ぎます。decision は人が確定します。issue と todo は provider 未設定でも `exec plan --project <project-id> --register <PJR-ID>` で計画を確認でき、agent 設定後は `exec run --project <project-id> --register <PJR-ID> --worktree` で実行できます。
812
+
813
+ すべての登録項目には type 別の個票が作られ、個票 Frontmatter が構造化フィールドの正本になります。個票内の `_TODO_` を解消してから `register close` すると、個票の文書状態も `ready` になります。成果物カタログ作成の todo は、次章で `dct-<domain>.yaml` を作成・検証した後に完了させます。登録簿は立ち上げ時の課題・判断・作業履歴、成果物カタログは合意後の管理対象成果物の正本です。同じ計画済み作業を register と schedule の両方で継続管理しません。
508
814
 
509
- ## 4. 成果物カタログからscheduleへ展開する
815
+ ## 4. 発展: 成果物カタログからscheduleへ展開する
510
816
 
511
817
  この経路では、成果物カタログ(`dct-<domain>.yaml`)とトラック戦略(`sch-strategy-<track>.yaml`)から Schedule を生成し、依存関係に従ってタスクを実行します。
512
818
 
@@ -689,7 +995,7 @@ npx specdojo exec run --project <project-id> --plan <execution_path>/exec/plans/
689
995
 
690
996
  ここまでで、register による立ち上げ整理から、成果物カタログ、Schedule、1タスクの完了までの Quick Start は終了です。以降の worktree 隔離実行と routine は、agent 設定後に試す任意の発展手順です。
691
997
 
692
- ## 5. (発展)worktreeで1タスクを隔離実行する
998
+ ## 5. 発展: worktreeで1タスクを隔離実行する
693
999
 
694
1000
  前節「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` まで済ませておきます。
695
1001
 
@@ -710,7 +1016,7 @@ npx specdojo exec run --project <project-id> --auto --parallel 5
710
1016
 
711
1017
  各段階(prepare → agent → commit → merge → remove)を人が確認しながら進める場合は [exec worktree運用ガイド](exec-worktree-guide.md)、project `develop`・feature・exec のブランチ全体運用は [ブランチワークフローガイド](branch-workflow-guide.md)、自動・並列実行の運用は [Schedule実行運用ガイド](schedule-operation-guide.md) を参照してください。
712
1018
 
713
- ## 6. routineで定期実行する
1019
+ ## 6. 発展: routineで定期実行する
714
1020
 
715
1021
  この経路では、動作確認済みの Job を `rtn-*.yaml` に定義した間隔で起動します。Job は schedule または register のagent実行を決定論的なコマンドで呼び出します。routine は任意の発展手順です。先に [exec設定ガイド](exec-config-guide.md) に従ってagentを設定し、次のような open かつ高優先度のtodoを用意します。
716
1022
 
@@ -83,6 +83,34 @@ specdojo register add --project <project-id> --type todo \
83
83
  --title "在庫初期データの登録" --topic inventory-seed
84
84
  ```
85
85
 
86
+ 別の project の作業ツリーから起票する場合は、対象 project と `--commit` を明示します。
87
+
88
+ ```bash
89
+ specdojo register add --project prj-0002 --type todo \
90
+ --title "共通 API の変更を追跡する" --topic shared-api-change \
91
+ --from prj-0001:PJR-AB12 --commit
92
+ ```
93
+
94
+ この経路は対象 project の `integration_branch`(省略時は `project/<project-id>/develop`)を開いている worktree を使い、無ければ一時 worktree を作ります。対象 project の名簿で `--by` を検証し、`register lifecycle` 枠の内側で起票、派生ビュー再生成、1 件の commit を行います。対象登録簿に未 commit 変更がある場合、または統合ブランチが存在しない場合は書き込みません。`--commit` のない別 project への起票と、別 project の項目に対する状態遷移は行えません。状態遷移は対象 project の作業ツリーで実行してください。
95
+
96
+ 別リポジトリの project へ起票する場合は、`specdojo.config.json` のトップレベルに別名を宣言し、その別名を `--project` に指定します。
97
+
98
+ ```json
99
+ {
100
+ "external_projects": {
101
+ "customer": { "path": "../customer-specdojo", "project_id": "prj-0002" }
102
+ }
103
+ }
104
+ ```
105
+
106
+ ```bash
107
+ specdojo register add --project customer --type todo \
108
+ --title "相手側で追跡する" --topic remote-follow-up \
109
+ --from customer:PJR-AB12 --commit
110
+ ```
111
+
112
+ 呼び出し元は相手の登録簿を直接編集せず、相手にインストールされた SpecDojo 0.4.2 以上へ処理を渡します。`--from customer:PJR-AB12` は相手の実 project ID に置き換えて検証・記録されます。相手のリポジトリや CLI がない場合、版が古い場合、`--commit` がない場合は起票前に停止します。相手への状態遷移は、相手のリポジトリへ移動して実行します。
113
+
86
114
  タイトルが日本語の場合は、内容を表す英語の `--topic` を小文字・ハイフン区切りで指定します。省略して `item` や日本語タイトル中の英単語だけが topic になった場合、`register add` は作成を続けたうえで警告します。警告後も、`register update --topic` で個票名と文書 ID を変更できます。成果物や kata(実践の型)を作成・修正する todo では、`--approach <approach> --target <doc-id>` を指定して進め方と対象を宣言できます(詳細は [exec運用ガイド](exec-operation-guide.md) の「register の todo から approach で成果物・kata を作る・直す手順」を参照してください)。
87
115
 
88
116
  `--priority` は次の目安で付けます(省略時は `medium`)。
@@ -195,6 +223,8 @@ specdojo register close \
195
223
 
196
224
  `--commit` は register の worktree 実行の記帳・統合と同じ `register lifecycle` 枠が空くまで待ち、枠の内側で記帳、`register build` 相当の検証・再生成、commit を順に行います。commit 対象はそのコマンドが新たに変更した個票・event・参照文書だけで、開始前からあるほかの未 commit 変更は残します。対象個票やevent自体に開始前の変更がある場合は、既存差分を混ぜないため書き込み前に停止します。既定の件名は `docs(register PJR-XXXX): <command> <title>` で、`-m <message>` または `--message <message>` で上書きできます。`--dry-run` と同時に指定した場合は表示だけを行い、枠の取得と commit は行いません。
197
225
 
226
+ 別 project への起票では、対象登録簿全体が clean であることを追加で確認します。元の作業ツリーのブランチと HEAD は変更しません。
227
+
198
228
  ### 2.2. 個票の作成
199
229
 
200
230
  すべての登録項目は、type 別のテンプレート(`pjr-todo-template.md` など `pjr-<type>-template.md`)から作る個票です。`register add` は個票の Frontmatter に構造化フィールドを書き込み、H1 と本文にタイトル・説明を置きます。