specdojo 0.4.2 → 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 (63) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/dist/catalog/build.js +7 -7
  3. package/dist/catalog/generate.js +27 -12
  4. package/dist/commands/init.js +10 -7
  5. package/dist/commands/orchestrator.js +9 -2
  6. package/dist/devcontainer/command.js +1 -1
  7. package/dist/devcontainer/scaffold.js +24 -9
  8. package/dist/exec/core.js +4 -0
  9. package/dist/exec/plans-core.js +10 -1
  10. package/dist/exec/plans-generation.js +13 -0
  11. package/dist/exec/plans-storage.js +4 -0
  12. package/dist/exec/register.js +64 -6
  13. package/dist/exec/results.js +5 -1
  14. package/dist/exec/strategy.js +4 -0
  15. package/dist/kata/authoring.js +100 -0
  16. package/dist/kata/command.js +52 -2
  17. package/dist/kata/kata.js +54 -11
  18. package/dist/register/approach.js +29 -1
  19. package/dist/register/create-commands.js +9 -0
  20. package/dist/register/cross-project.js +9 -2
  21. package/dist/register/external-project.js +136 -0
  22. package/dist/schedule/strategy-profiles.js +3 -0
  23. package/dist/shared/agent-types.js +4 -0
  24. package/dist/shared/provider-scaffold.js +3 -3
  25. package/dist/shared/specdojo-config.js +109 -2
  26. package/docs/ja/specdojo/exec-templates/xep-recipe-authoring-template.md +45 -0
  27. package/docs/ja/specdojo/exec-templates/xep-rulebook-authoring-template.md +45 -0
  28. package/docs/ja/specdojo/exec-templates/xep-sample-authoring-template.md +45 -0
  29. package/docs/ja/specdojo/exec-templates/xep-template-authoring-template.md +45 -0
  30. package/docs/ja/specdojo/guides/docs-editing-guide.md +32 -0
  31. package/docs/ja/specdojo/guides/docs-structure-guide.md +1 -1
  32. package/docs/ja/specdojo/guides/exec-config-guide.md +13 -6
  33. package/docs/ja/specdojo/guides/kata-guide.md +4 -0
  34. package/docs/ja/specdojo/guides/quick-start-guide.md +352 -68
  35. package/docs/ja/specdojo/guides/register-operation-guide.md +18 -0
  36. package/docs/ja/specdojo/guides/remote-host-development-guide.md +10 -2
  37. package/docs/ja/specdojo/guides/ryu-guide.md +18 -4
  38. package/docs/ja/specdojo/guides/use-case-guide.md +2 -2
  39. package/docs/ja/specdojo/references/command-reference.md +39 -20
  40. package/docs/ja/specdojo/references/specdojo-config-reference.md +33 -7
  41. package/docs/ja/specdojo/standards/recipe-authoring-standard.md +10 -10
  42. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +13 -13
  43. package/docs/ja/specdojo/standards/sample-authoring-standard.md +4 -4
  44. package/docs/ja/specdojo/standards/template-authoring-standard.md +4 -4
  45. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +6 -0
  46. package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +6 -6
  47. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +21 -4
  48. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +29 -0
  49. package/package.json +2 -2
  50. package/templates/antigravity/README.md +1 -1
  51. package/templates/antigravity/settings.global.json +5 -0
  52. package/templates/claude/README.md +11 -8
  53. package/templates/claude/settings.edit.json +10 -1
  54. package/templates/claude/settings.orchestrator.json +90 -0
  55. package/templates/claude/settings.report.json +14 -1
  56. package/templates/claude/settings.review.json +13 -1
  57. package/templates/codex/README.md +7 -5
  58. package/templates/codex/rules/specdojo.rules +48 -0
  59. package/templates/devcontainer/devcontainer.json +1 -4
  60. package/templates/opencode/README.md +2 -1
  61. package/templates/opencode/agents/opencode-executor.md +2 -0
  62. package/templates/opencode/agents/opencode-review-executor.md +2 -0
  63. package/templates/opencode/agents/specdojo-orchestrator.md +59 -5
@@ -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,7 +68,7 @@ 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
72
  Create Git hooks with lefthook? [y/N]: <- Enter(この体験では作らない)
73
73
  ```
74
74
 
@@ -76,7 +76,7 @@ Create Git hooks with lefthook? [y/N]: <- Enter(この体験で
76
76
  `claud` と入力すると、利用可能な provider の一覧に続いて provider の質問だけが再表示されます。
77
77
  それまでに答えた project や名簿の内容を入力し直す必要はありません。
78
78
 
79
- 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 分の体験は記帳だけで進められるため、コンテナを開かずにそのままホスト環境で続けて構いません。
80
80
 
81
81
  登録簿は `docs/ja/projects/prj-0001/controls/project-register/` に作られます。オーケストレーターで進める場合は、終了時に表示される `npm run orch:<provider>` で起動します。成果物カタログは対話では作られません。成果物の構成が定まったら、[[#41-成果物カタログを作成する|成果物カタログを作成する]] に従って `catalog_path` を設定し、`catalog scaffold` で追加してください。
82
82
 
@@ -228,7 +228,7 @@ npx specdojo init
228
228
  ```
229
229
 
230
230
  `specdojo init` は、project ID と名前、人の nickname と表示名、利用する agent provider、
231
- exec・Dev Container・Git hook の要否を順に質問し、Dev Container を選んだ場合だけ推奨 preset を入れるか(既定は「はい」)を続けて質問します。Git hook は既定では作りません。成果物カタログは対話では質問せず、`--catalog <size>` を
231
+ exec・Dev Container・Git hook の要否を順に質問し、Dev Container を選んだ場合だけ `minimal` / `recommended` / `full` の preset(既定は `recommended`)を続けて質問します。Git hook は既定では作りません。成果物カタログは対話では質問せず、`--catalog <size>` を
232
232
  明示した場合にだけ初期化時に作成します。選択に応じて設定、登録簿、人と
233
233
  agent の名簿、provider の scaffold、`package.json` の `orch:<provider>`、exec の起動設定を
234
234
  作成します。exec の親検証は、対応する npm script が `package.json` にあるものだけを設定し、
@@ -237,7 +237,7 @@ agent の名簿、provider の scaffold、`package.json` の `orch:<provider>`
237
237
  それまでの回答は保持します。非対話環境や `--yes` では再質問せず、不正な指定をエラーとして終了します。
238
238
 
239
239
  CI や標準入力が端末でない環境では質問しません。次のようにオプションだけで同じ初期設定を
240
- 行えます。`--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` と同じ意味で受け付けます。省略値は画面に表示されます。
241
241
 
242
242
  ```bash
243
243
  npx specdojo init --yes \
@@ -336,7 +336,7 @@ npx specdojo config init
336
336
 
337
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
338
 
339
- プロダクト文書は `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) の `別リポジトリ構成` を参照してください。
340
340
 
341
341
  成果物と実装を常に同じ変更・履歴として扱う場合に限り、**同一リポジトリ構成**としてプロダクトリポジトリのルートで同じ初期化手順を実行できます。CLI は構成を強制しません。
342
342
 
@@ -384,7 +384,15 @@ npx specdojo devcontainer scaffold --provider <name> --preset recommended --dry-
384
384
  npx specdojo devcontainer scaffold --provider <name> --preset recommended
385
385
  ```
386
386
 
387
- 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]] を参照してください。
388
396
 
389
397
  設定したプロジェクトを確認します。
390
398
 
@@ -418,117 +426,393 @@ npx specdojo kata status --kind rulebook
418
426
 
419
427
  CLI と同じバージョンで使う `exec-template` と `schema` は npm package 参照固定であり、eject できません。`kata install --all` は docs サイト配信やオフライン運用で全量コピーするときの選択肢で、通常の導入では実行しません。
420
428
 
421
- ## 3. registerで課題と判断を整理する
429
+ ## 3. registerをユースケース別に使う
422
430
 
423
- プロジェクトの開始時点では、解決すべき問題、判断が必要な事項、実施する作業が混在しています。まず register に個票として記録し、issue → decision → todo の順に具体化します。
431
+ register は、後から追跡したい問題・判断・作業を個票として残す入口です。この章では、よくある状況ごとに「こんなとき」「チャットでの頼み方」「コマンド」を並べます。type の詳しい選び方と状態遷移は [登録簿運用ガイド](register-operation-guide.md)、approach と実行 pipeline の詳細は [exec運用ガイド](exec-operation-guide.md) を参照してください。複数の機能を組み合わせたシナリオから読みたい場合は [[specdojo:use-case-guide|ユースケース別ガイド]] へ進んでください。
424
432
 
425
- ```text
426
- issue(何が問題か)
427
- -> decision(何を対象とするか)
428
- -> todo(成果物カタログを作成する)
429
- -> dct-<domain>.yaml
430
- -> schedule
433
+ 初期設定で register を作らなかった場合は、先に `.specdojo/specdojo.config.json` の `project_register_path` を設定して登録簿を用意します。
434
+
435
+ ```bash
436
+ # チャット:「<project-id> の登録簿を用意して」
437
+ npx specdojo register scaffold --project <project-id>
431
438
  ```
432
439
 
433
- ### 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に任せる
443
+
444
+ **こんなとき:** 完了条件を書ける作業を todo として追跡し、難しさに合う agent へ安全に任せたいとき。
434
445
 
435
- `.specdojo/specdojo.config.json` の `project_register_path` を設定し、登録簿を初期生成します。
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 を割り当てる |
436
453
 
437
454
  ```bash
438
- # チャット:「<project-id> の登録簿を用意して」
439
- 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
440
466
  ```
441
467
 
442
- ### 3.2. issue、decision、todoを登録する
468
+ 成功すると個票は `review` になります。成果物と result を人が確認した後、`register close` で完了させます。
443
469
 
444
- 次の例では、初期スコープと必要な成果物が未確定な状態から、成果物カタログを作成する作業までを3つの個票で追跡します。コマンドはまとめて示していますが、実運用では issue の調査結果を受けて decision を起票し、決定後に todo を起票します。
470
+ ### 3.2. 問題を調べて直す
471
+
472
+ **こんなとき:** 症状は分かっているが、原因や直し方を調べる必要があるとき。issue の個票へ問題、影響、原因、対応結果を残します。
445
473
 
446
474
  ```bash
447
- # 1. 解決すべき問題を記録する
448
- # チャット:「issue を起票して。タイトルは『初期スコープと必要成果物が未確定』、個票あり、topic は clarify-initial-scope」
475
+ # チャット:「issue『CSV 出力で文字化けする』を起票して、難しさ hard で調査と修正を任せて」
449
476
  npx specdojo register add \
450
477
  --project <project-id> \
451
478
  --type issue \
452
- --title "初期スコープと必要成果物が未確定" \
453
- --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. 決めることを残す
491
+
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
454
501
 
455
- # 2. 選択肢と決定を記録する
456
- # チャット:「decision を起票して。タイトルは『初期スコープと対象成果物を決定する』、個票あり、topic は decide-initial-scope」
502
+ # チャット:「decision『初期リリースの支払い方法を決める』を起票して」
457
503
  npx specdojo register add \
458
504
  --project <project-id> \
459
505
  --type decision \
460
- --title "初期スコープと対象成果物を決定する" \
461
- --topic decide-initial-scope
506
+ --title "初期リリースの支払い方法を決める" \
507
+ --topic decide-payment-methods
508
+ ```
509
+
510
+ question から decision、仕様書への反映、後日の変更までを一度通す場合は [[#1-10分で体験する--仕様の判断台帳|1. 10分で体験する — 仕様の判断台帳]] の流れを使います。decision は agent に判断させる実行対象ではなく、人が選択肢と理由を確認して `register close` します。
511
+
512
+ ### 3.4. 合意した範囲を変える
513
+
514
+ **こんなとき:** 決定済みの仕様、スコープ、成果物へ変更を加え、理由と影響を追跡したいとき。
462
515
 
463
- # 3. 決定内容を実行可能な作業にする
464
- # チャット:「高優先度の todo を起票して。タイトルは『プロジェクト定義の成果物カタログを作成する』、個票あり、topic は create-project-definition-catalog」
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 に任せて」
465
567
  npx specdojo register add \
466
568
  --project <project-id> \
467
569
  --type todo \
468
- --priority high \
469
- --title "プロジェクト定義の成果物カタログを作成する" \
470
- --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
579
+ ```
580
+
581
+ `recipe-guided` または `retrofit` を使う場合は、上の `--approach fully-guided` を選んだ値へ置き換えます。`--target` には成果物カタログで解決できる成果物の doc id を 1 件だけ指定します。カタログの `done_criteria` と個票の完了条件が、どちらも plan に入ります。
582
+
583
+ ### 3.7. 成果物とkataを一組で作る
584
+
585
+ **こんなとき:** プロジェクトの初期立ち上げで、成果物だけでなく、その成果物を繰り返し作るための rulebook・recipe・sample・template も同じ実行で初期整備したいとき。
586
+
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を直す
606
+
607
+ **こんなとき:** 成果物ではなく、作り方・手順・例・雛形そのものを改善したいとき。
608
+
609
+ | 直す kata | `approach` |
610
+ | --------- | ---------------------- |
611
+ | rulebook | `rulebook-maintenance` |
612
+ | recipe | `recipe-maintenance` |
613
+ | sample | `sample-maintenance` |
614
+ | template | `template-maintenance` |
615
+
616
+ ```bash
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
471
630
  ```
472
631
 
473
- `register add` の出力に表示された `PJR-XXXX` を控えます。すべての登録項目は、背景、選択肢、完了条件、結論などを記録する type 別の個票として生成されます。個票 Frontmatter が構造化フィールドの正本であり、一覧は個票から生成されます。成果物カタログを複数ドメインに分ける場合は、原則として `dct-<domain>.yaml` ごとに todo 個票を起票すると、対象と完了条件を追跡しやすくなります。
632
+ ほかの kata を直す場合は、表に従って `--approach` を置き換えます。`--target` には文書索引で解決でき、approach の種別と一致する kata の doc id を 1 件だけ指定します。
633
+
634
+ ### 3.9. 既存成果物からkataを新しく作る
635
+
636
+ **こんなとき:** 成果物は既にあり、その実績を手本に rulebook など 1 種類の kata だけを新しく作りたいとき。
474
637
 
475
- agent の run と並行して記帳し、その変更だけを commit まで完了させる場合は `register add` や状態遷移コマンドへ `--commit` を付けます。同じ project の `register lifecycle` 枠が空くまで待って記帳・一覧再生成・commit を行うため、別の run の記帳・統合と競合しません。対象の個票や event に既存の未 commit 変更がある場合は、混在を避けるため書き込み前に停止します。
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 \
650
+ --project <project-id> \
651
+ --register <PJR-ID> \
652
+ --worktree
653
+ ```
476
654
 
477
- | type | 記録する内容 | 完了状態 | agent実行 |
478
- | ---------- | -------------------------------------- | --------- | ------------------------------------------ |
479
- | `issue` | 発生している問題、影響、原因、対応結果 | `done` | `exec run --register` で対応できる |
480
- | `decision` | 判断の背景、選択肢、決定内容、決定理由 | `decided` | 対象外。人が判断して `register close` する |
481
- | `todo` | 実施内容、完了条件、作業結果 | `done` | `exec run --register` で対応できる |
655
+ 1 件目の `--target` は新しい kata ID、2 件目以降は任意の手本成果物です。成果物も型もまだない初期立ち上げには `bootstrap` を使います。手本なしで kata だけを作る場合は 2 件目以降を省略します。recipe / sample / template では `approach` と ID の末尾を同じ種類へ置き換えます。
482
656
 
483
- ### 3.3. 判断を確定してカタログ作成へ進む
657
+ ### 3.10. 統合後にreviewのagentへ確かめさせる
484
658
 
485
- issue に人が着手し、個票へ問題、影響、原因、対応方針を記入して完了させます。
659
+ **こんなとき:** worktree の成果を統合した後、完了条件・result・差分・検証結果を別の review agent に照合させたいとき。
486
660
 
487
661
  ```bash
488
- # チャット:「issue <issue-id> に着手して」
489
- npx specdojo register start --project <project-id> --id <issue-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
+ ```
490
669
 
491
- # issue 個票を編集して調査結果を記録する
670
+ `--post-review` は worktree 実行でだけ使えます。todo と issue は判定が `complete` または `complete-with-findings` なら自動 close され、`incomplete` なら `waiting` に戻ります。question、decision、および SpecDojo 自身のコードを変えた項目は自動 close されません。
492
671
 
493
- # チャット:「issue <issue-id> を『問題、影響、対応方針を整理』で完了して」
494
- 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 \
495
679
  --project <project-id> \
496
- --id <issue-id> \
497
- --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
498
690
  ```
499
691
 
500
- issue の結論を基に、decision 個票へ選択肢、決定内容、理由を記入します。decision は agent の実行対象ではないため、人が判断して完了させます。
692
+ 夜間 queue に入るのは `autopilot: approved` の付いた `open` の todo と issue だけです。まず対象を確認する場合は、`orchestrator night` に `--dry-run` を付けます。朝の報告には close、`waiting`、失敗した項目がまとめられます。
693
+
694
+ ### 3.12. 止まった項目を再開する
695
+
696
+ **こんなとき:** register の worktree 実行が agent、検証、reporter、統合の途中で止まり、残っている成果を生かして続けるか、破棄して最初からやり直したいとき。
501
697
 
502
698
  ```bash
503
- # チャット:「decision <decision-id> に着手して」
504
- npx specdojo register start --project <project-id> --id <decision-id>
699
+ # チャット:「<PJR-ID> を止まった段から再開して」
700
+ npx specdojo exec run \
701
+ --project <project-id> \
702
+ --register <PJR-ID> \
703
+ --worktree \
704
+ --resume
505
705
 
506
- # decision 個票を編集して判断内容を記録する
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
507
713
 
508
- # チャット:「decision <decision-id> を『採用するスコープと成果物を決定』で完了して」
509
- npx specdojo register close \
714
+ # チャット:「<PJR-ID> の残っている worktree を破棄し、最初からやり直して」
715
+ npx specdojo exec run \
510
716
  --project <project-id> \
511
- --id <decision-id> \
512
- --conclusion "採用するスコープと成果物を決定"
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
745
+ ```
746
+
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
+ }
513
758
  ```
514
759
 
515
- provider 未設定でも、`issue` や `todo` から生成される exec plan を確認できます。
760
+ 宣言した別名を `--project` に使い、相手側にある起票元は `<別名>:PJR-XXXX` で指定します。
516
761
 
517
762
  ```bash
518
- # チャット:「issue または todo <issue-or-todo-id> の実行計画を作って」
519
- 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
520
771
  ```
521
772
 
522
- 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
+ ```
523
786
 
524
787
  ```bash
525
- # チャット:「issue または todo <issue-or-todo-id> を agent に実行させて」
526
- 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
527
809
  ```
528
810
 
529
- 個票内の `_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 の両方で継続管理しません。
530
814
 
531
- ## 4. 成果物カタログからscheduleへ展開する
815
+ ## 4. 発展: 成果物カタログからscheduleへ展開する
532
816
 
533
817
  この経路では、成果物カタログ(`dct-<domain>.yaml`)とトラック戦略(`sch-strategy-<track>.yaml`)から Schedule を生成し、依存関係に従ってタスクを実行します。
534
818
 
@@ -711,7 +995,7 @@ npx specdojo exec run --project <project-id> --plan <execution_path>/exec/plans/
711
995
 
712
996
  ここまでで、register による立ち上げ整理から、成果物カタログ、Schedule、1タスクの完了までの Quick Start は終了です。以降の worktree 隔離実行と routine は、agent 設定後に試す任意の発展手順です。
713
997
 
714
- ## 5. (発展)worktreeで1タスクを隔離実行する
998
+ ## 5. 発展: worktreeで1タスクを隔離実行する
715
999
 
716
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` まで済ませておきます。
717
1001
 
@@ -732,7 +1016,7 @@ npx specdojo exec run --project <project-id> --auto --parallel 5
732
1016
 
733
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) を参照してください。
734
1018
 
735
- ## 6. routineで定期実行する
1019
+ ## 6. 発展: routineで定期実行する
736
1020
 
737
1021
  この経路では、動作確認済みの Job を `rtn-*.yaml` に定義した間隔で起動します。Job は schedule または register のagent実行を決定論的なコマンドで呼び出します。routine は任意の発展手順です。先に [exec設定ガイド](exec-config-guide.md) に従ってagentを設定し、次のような open かつ高優先度のtodoを用意します。
738
1022
 
@@ -93,6 +93,24 @@ specdojo register add --project prj-0002 --type todo \
93
93
 
94
94
  この経路は対象 project の `integration_branch`(省略時は `project/<project-id>/develop`)を開いている worktree を使い、無ければ一時 worktree を作ります。対象 project の名簿で `--by` を検証し、`register lifecycle` 枠の内側で起票、派生ビュー再生成、1 件の commit を行います。対象登録簿に未 commit 変更がある場合、または統合ブランチが存在しない場合は書き込みません。`--commit` のない別 project への起票と、別 project の項目に対する状態遷移は行えません。状態遷移は対象 project の作業ツリーで実行してください。
95
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
+
96
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 を作る・直す手順」を参照してください)。
97
115
 
98
116
  `--priority` は次の目安で付けます(省略時は `medium`)。
@@ -58,9 +58,17 @@ npx specdojo devcontainer scaffold --provider claude,codex --preset recommended
58
58
  npx specdojo devcontainer scaffold --provider claude,codex --preset recommended
59
59
  ```
60
60
 
61
- `recommended` preset は、端末版 Emacs と Vim(既存設定を上書きしない雛形)、tmux、SpecDojo の文書作業向け VS Code 拡張をまとめて追加します。拡張は Git Graph、markdownlint、YAML、Prettier、remark、Markdown All in One、Code Spell Checker、EditorConfig、Error Lens、Even Better TOML で、選択した provider の拡張もその provider の分だけ追加します。Markdown と YAML は保存時に Prettier で整形し、主要な SpecDojo YAML を `docs/specdojo/schemas/v1/` の schema へ関連付けます。同じ拡張は `.vscode/extensions.json` の recommendation にも追加されます。
61
+ 用途に合わせて、provider とは別に次の preset を選びます。
62
62
 
63
- 既存の `.devcontainer/` は通常実行では上書きしません。置き換える場合だけ `--force` を指定します。生成設定は provider の設定ディレクトリを名前付きボリュームへ保存し、ホストの認証情報・秘密鍵・`.env` は既定でマウントしません。preset を使わない場合、Ollama 接続、コンテナ内の cron、コンテナ内の tmux が必要なときだけ `--ollama`、`--cron`、`--tmux` を追加します。本書の構成図のようにホスト側の tmux でコンテナ自体を包む場合、tmux を含めない個別指定も選べます。
63
+ | preset | 内容 |
64
+ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
65
+ | `minimal` | 選んだ provider の CLI と SpecDojo の動作に必要な最小構成。preset を省略した場合と同じ。 |
66
+ | `recommended` | `minimal` に GitHub CLI(`gh`)、端末版 Emacs と Vim、tmux、SpecDojo の文書作業向け VS Code 拡張・設定を追加する。 |
67
+ | `full` | `recommended` に ripgrep、fd、fzf、yq、shellcheck、shfmt、Ollama 接続、cron を追加する。fd は `fd-find` package から `fd` コマンドとして利用できる。 |
68
+
69
+ `recommended` / `full` のエディタ設定は既存設定を上書きしません。VS Code 拡張は Git Graph、markdownlint、YAML、Prettier、remark、Markdown All in One、Code Spell Checker、EditorConfig、Error Lens、Even Better TOML で、選択した provider の拡張もその provider の分だけ追加します。Markdown と YAML は保存時に Prettier で整形し、主要な SpecDojo YAML を `docs/specdojo/schemas/v1/` の schema へ関連付けます。同じ拡張は `.vscode/extensions.json` の recommendation にも追加されます。
70
+
71
+ 既存の `.devcontainer/` は通常実行では上書きしません。置き換える場合だけ `--force` を指定します。生成設定は provider の設定ディレクトリを名前付きボリュームへ保存し、ホストの認証情報・秘密鍵・`.env` は既定でマウントしません。GitHub へのログインは自動では行わないため、利用者が必要なときだけコンテナ内で `gh auth login` を実行します。認証は同じリポジトリのコンテナを作り直しても名前付き volume に残りますが、同じ利用者で動く agent からも見えます。このため配布する agent 権限では `git push` と `gh` の書き込みを拒否します。pipeline executor・review executor・reporter は読み取りを含む全 `gh` を拒否し、対話型オーケストレーターは役割別設定を持てる Claude Code と OpenCode でだけ `gh pr view`・`gh run view` などの読み取りを許可します。Codex と Antigravity は権限が役割共通のため全 `gh` を拒否します。preset に個別の `--ollama`・`--cron`・`--tmux`・`--editor` を加えることもできます。本書の構成図のようにホスト側の tmux でコンテナ自体を包む場合、tmux を含めない `minimal` も選べます。
64
72
 
65
73
  生成する `devcontainer.json` は、利用リポジトリ単体ではなく、その親ディレクトリをホスト側と同じ名前の `/workspaces/<親名>` へマウントします。例えば `app1-workspace/app1-specdojo` の作業ディレクトリは `/workspaces/app1-workspace/app1-specdojo` です。別リポジトリ構成では `repos` の参照先(例: `../app1`)と `worktree_base`(例: `../app1-specdojo-worktrees`)が利用リポジトリの外にあるためです。これらの Git リポジトリと worktree は `safe.directory` の対象になります。一方、同じ親ディレクトリに置いたその他のファイルもコンテナから見えるため、秘密情報などコンテナへ公開しないファイルは別の場所へ置いてください。
66
74