specdojo 0.3.1 → 0.4.1
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.
- package/.github/agents/specdojo-orchestrator.md +61 -2
- package/CHANGELOG.md +90 -0
- package/README.md +85 -25
- package/dist/{catalog-build-references.js → catalog/build-references.js} +4 -4
- package/dist/catalog/build-render.js +32 -0
- package/dist/{catalog-build.js → catalog/build.js} +9 -9
- package/dist/{catalog.js → catalog/catalog.js} +10 -10
- package/dist/{catalog-generate.js → catalog/generate.js} +8 -8
- package/dist/catalog/paths.js +1 -0
- package/dist/{catalog-plan-generate.js → catalog/plan-generate.js} +4 -4
- package/dist/{catalog-plan.js → catalog/plan.js} +4 -4
- package/dist/{catalog-scaffold.js → catalog/scaffold.js} +3 -3
- package/dist/{agent.js → commands/agent.js} +11 -11
- package/dist/{build-command.js → commands/build.js} +2 -2
- package/dist/{init-command.js → commands/init.js} +168 -45
- package/dist/commands/night-orchestrator.js +287 -0
- package/dist/{orchestrator.js → commands/orchestrator.js} +12 -5
- package/dist/{watch.js → commands/watch.js} +3 -3
- package/dist/{dashboard-timeline.js → dashboard/dashboard-timeline.js} +2 -2
- package/dist/{dashboard.js → dashboard/dashboard.js} +11 -10
- package/dist/{dashboard-exec-records.js → dashboard/exec-records.js} +2 -2
- package/dist/{dashboard-routines.js → dashboard/routines.js} +6 -5
- package/dist/{dashboard-shared.js → dashboard/shared.js} +1 -1
- package/dist/{timeline-build.js → dashboard/timeline-build.js} +2 -1
- package/dist/{timeline.js → dashboard/timeline.js} +1 -1
- package/dist/{deliverable.js → deliverable/deliverable.js} +5 -5
- package/dist/{deliverable-trash.js → deliverable/trash.js} +5 -5
- package/dist/{devcontainer-command.js → devcontainer/command.js} +8 -4
- package/dist/devcontainer/scaffold.js +418 -0
- package/dist/{doc-index.js → docs/doc-index.js} +1 -1
- package/dist/{frontmatter-namespace.js → docs/frontmatter-namespace.js} +1 -1
- package/dist/{index-command.js → docs/index-command.js} +1 -1
- package/dist/docs/template-resolution.js +1 -0
- package/dist/{viewpoint-document-kinds-check.js → docs/viewpoint-document-kinds-check.js} +1 -1
- package/dist/{yaml-pages-command.js → docs/yaml-pages-command.js} +1 -1
- package/dist/{yaml-pages.js → docs/yaml-pages.js} +2 -2
- package/dist/{exec-agent-config.js → exec/agent-config.js} +92 -5
- package/dist/{exec-agent-git-state.js → exec/agent-git-state.js} +1 -1
- package/dist/{exec-agent-protected-config.js → exec/agent-protected-config.js} +1 -1
- package/dist/{exec-commands.js → exec/commands.js} +22 -18
- package/dist/{exec-core.js → exec/core.js} +11 -11
- package/dist/{exec-events.js → exec/events.js} +2 -2
- package/dist/{exec-evidence.js → exec/evidence.js} +11 -6
- package/dist/exec/exec.js +2 -0
- package/dist/exec/format.js +1 -0
- package/dist/{exec-handoff.js → exec/handoff.js} +13 -12
- package/dist/{exec-limit.js → exec/limit.js} +93 -12
- package/dist/{exec-parent-validation.js → exec/parent-validation.js} +18 -4
- package/dist/{exec-pipeline-state.js → exec/pipeline-state.js} +29 -2
- package/dist/{exec-plans-core.js → exec/plans-core.js} +68 -114
- package/dist/{exec-plans-generation.js → exec/plans-generation.js} +53 -10
- package/dist/{exec-plans-storage.js → exec/plans-storage.js} +5 -5
- package/dist/{exec-plans.js → exec/plans.js} +3 -3
- package/dist/{exec-project.js → exec/project.js} +1 -1
- package/dist/{exec-protection-handoff.js → exec/protection-handoff.js} +3 -3
- package/dist/{exec-register-resume.js → exec/register-resume.js} +2 -2
- package/dist/{exec-register.js → exec/register.js} +114 -9
- package/dist/{exec-repo-integration-git.js → exec/repo-integration-git.js} +2 -2
- package/dist/{exec-repo-integration-sync.js → exec/repo-integration-sync.js} +4 -4
- package/dist/{exec-repo-integration.js → exec/repo-integration.js} +14 -11
- package/dist/{exec-repo-trace.js → exec/repo-trace.js} +3 -3
- package/dist/{exec-reporter-output.js → exec/reporter-output.js} +2 -2
- package/dist/{exec-reporter.js → exec/reporter.js} +142 -25
- package/dist/{exec-results.js → exec/results.js} +287 -31
- package/dist/{exec-run-agent-pipeline.js → exec/run/agent-pipeline.js} +35 -12
- package/dist/{exec-run-agent.js → exec/run/agent.js} +115 -28
- package/dist/{exec-run-in-place.js → exec/run/in-place.js} +56 -27
- package/dist/{exec-run-job.js → exec/run/job.js} +65 -36
- package/dist/{exec-run-lifecycle-commands.js → exec/run/lifecycle-commands.js} +30 -22
- package/dist/{exec-run-lock.js → exec/run/lock.js} +4 -3
- package/dist/{exec-run-mode-shared.js → exec/run/mode-shared.js} +3 -3
- package/dist/{exec-run-register-command.js → exec/run/register-command.js} +38 -11
- package/dist/{exec-run-register-core.js → exec/run/register-core.js} +63 -21
- package/dist/{exec-run-register-mode.js → exec/run/register-mode.js} +58 -31
- package/dist/exec/run/register-post-review.js +420 -0
- package/dist/{exec-run-register-resume.js → exec/run/register-resume.js} +48 -27
- package/dist/{exec-run-register-state.js → exec/run/register-state.js} +13 -10
- package/dist/{exec-run-register-worktree.js → exec/run/register-worktree.js} +119 -24
- package/dist/{exec-run.js → exec/run/run.js} +11 -11
- package/dist/{exec-run-schedule-mode.js → exec/run/schedule-mode.js} +17 -17
- package/dist/{exec-run-schedule-prepare.js → exec/run/schedule-prepare.js} +31 -18
- package/dist/{exec-run-schedule-task.js → exec/run/schedule-task.js} +45 -18
- package/dist/{exec-run-shared.js → exec/run/shared.js} +78 -30
- package/dist/{exec-schedule-calendar.js → exec/schedule/calendar.js} +1 -1
- package/dist/{exec-schedule-cpm.js → exec/schedule/cpm.js} +2 -2
- package/dist/{exec-schedule-gantt-chart-render.js → exec/schedule/gantt-chart-render.js} +2 -2
- package/dist/exec/schedule/gantt-chart.js +2 -0
- package/dist/{exec-schedule-hash.js → exec/schedule/hash.js} +2 -2
- package/dist/exec/schedule/index.js +1 -0
- package/dist/{exec-schedule-initial.js → exec/schedule/initial.js} +2 -2
- package/dist/{exec-schedule-progress.js → exec/schedule/progress.js} +2 -2
- package/dist/{exec-schedule-ready.js → exec/schedule/ready.js} +2 -2
- package/dist/{exec-schedule.js → exec/schedule/schedule.js} +11 -11
- package/dist/exec/shared.js +63 -0
- package/dist/exec/slot-lock.js +1 -0
- package/dist/{exec-strategy.js → exec/strategy.js} +2 -2
- package/dist/{exec-task-repos.js → exec/task-repos.js} +104 -17
- package/dist/{exec-task-view.js → exec/task-view.js} +4 -4
- package/dist/{exec-trial-commands.js → exec/trial-commands.js} +20 -22
- package/dist/{exec-trial-core.js → exec/trial-core.js} +6 -6
- package/dist/{exec-trial.js → exec/trial.js} +2 -2
- package/dist/{exec-worktree-command.js → exec/worktree-command.js} +25 -23
- package/dist/{exec-worktree-ops-commit.js → exec/worktree-ops-commit.js} +25 -60
- package/dist/{exec-worktree-ops-lifecycle.js → exec/worktree-ops-lifecycle.js} +13 -8
- package/dist/{exec-worktree-ops-merge.js → exec/worktree-ops-merge.js} +48 -7
- package/dist/{exec-worktree-ops.js → exec/worktree-ops.js} +3 -3
- package/dist/exec/worktree.js +305 -0
- package/dist/{grade-apply.js → grade/apply.js} +9 -9
- package/dist/{grade-command-apply.js → grade/command-apply.js} +7 -7
- package/dist/{grade-command-inspect.js → grade/command-inspect.js} +6 -6
- package/dist/{grade-command-plan.js → grade/command-plan.js} +5 -5
- package/dist/{grade-core.js → grade/core.js} +3 -3
- package/dist/grade/grade.js +19 -0
- package/dist/{grade-markdown.js → grade/markdown.js} +6 -6
- package/dist/{grade-pipeline-state.js → grade/pipeline-state.js} +4 -4
- package/dist/{grade-plan.js → grade/plan.js} +5 -5
- package/dist/{grade-result.js → grade/result.js} +5 -94
- package/dist/{grade-target-discovery.js → grade/target-discovery.js} +7 -7
- package/dist/{grade-targets.js → grade/targets.js} +11 -8
- package/dist/{job-definition.js → job/definition.js} +25 -6
- package/dist/{job.js → job/job.js} +12 -11
- package/dist/{kata-command.js → kata/command.js} +3 -3
- package/dist/{kata.js → kata/kata.js} +5 -5
- package/dist/register/approach.js +134 -0
- package/dist/{register-core.js → register/core.js} +26 -8
- package/dist/{register-create-commands.js → register/create-commands.js} +171 -8
- package/dist/{register-date.js → register/date.js} +1 -1
- package/dist/register/derivation.js +163 -0
- package/dist/{register-event-merge.js → register/event-merge.js} +44 -3
- package/dist/{register-events.js → register/events.js} +13 -3
- package/dist/{register-history.js → register/history.js} +7 -6
- package/dist/{register-item.js → register/item.js} +32 -5
- package/dist/register/lifecycle-lock.js +5 -0
- package/dist/{register-maintenance-commands.js → register/maintenance-commands.js} +13 -7
- package/dist/{register-migrate-timestamps.js → register/migrate-timestamps.js} +3 -3
- package/dist/{register-migration.js → register/migration.js} +5 -4
- package/dist/{register.js → register/register.js} +32 -27
- package/dist/{register-renumber.js → register/renumber.js} +38 -11
- package/dist/{register-transition-commands.js → register/transition-commands.js} +3 -3
- package/dist/{register-update.js → register/update.js} +5 -5
- package/dist/{register-views.js → register/views.js} +47 -7
- package/dist/{review-grade.js → review/grade.js} +2 -2
- package/dist/{review-plan.js → review/plan.js} +3 -3
- package/dist/{routine-definition.js → routine/definition.js} +2 -2
- package/dist/{routine.js → routine/routine.js} +49 -22
- package/dist/{schedule-approach.js → schedule/approach.js} +8 -8
- package/dist/{schedule-build.js → schedule/build.js} +7 -4
- package/dist/{schedule.js → schedule/schedule.js} +6 -6
- package/dist/{schedule-strategy-generate-document.js → schedule/strategy-generate-document.js} +2 -2
- package/dist/{schedule-strategy-generate-scope.js → schedule/strategy-generate-scope.js} +4 -4
- package/dist/{schedule-strategy-generate.js → schedule/strategy-generate.js} +10 -10
- package/dist/shared/agent-types.js +23 -0
- package/dist/shared/artifact-path.js +9 -0
- package/dist/{build-if-stale.js → shared/build-if-stale.js} +1 -1
- package/dist/{catalog-build-render.js → shared/catalog-render.js} +3 -32
- package/dist/{exec-slot-lock.js → shared/cross-process-lock.js} +3 -1
- package/dist/shared/fs.js +30 -0
- package/dist/shared/git.js +346 -0
- package/dist/shared/grade-result.js +94 -0
- package/dist/{package-paths.js → shared/package-paths.js} +3 -3
- package/dist/shared/plan-templates.js +114 -0
- package/dist/{exec-provider-scaffold.js → shared/provider-scaffold.js} +6 -3
- package/dist/shared/random.js +4 -0
- package/dist/{exec-schedule-index.js → shared/schedule-index.js} +3 -1
- package/dist/shared/schedule-paths.js +9 -0
- package/dist/{specdojo-config.js → shared/specdojo-config.js} +162 -21
- package/dist/{exec-shared.js → shared/text.js} +4 -135
- package/dist/shared/time.js +28 -0
- package/dist/shared/workspace-scaffold.js +69 -0
- package/dist/specdojo.js +22 -22
- package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +31 -18
- package/docs/ja/specdojo/exec-templates/xep-register-investigate-template.md +1 -2
- package/docs/ja/specdojo/exec-templates/xep-register-template.md +3 -2
- package/docs/ja/specdojo/exec-templates/xer-template.md +1 -3
- package/docs/ja/specdojo/exec-templates/xrp-job-template.md +6 -4
- package/docs/ja/specdojo/exec-templates/xrp-register-post-run-template.md +46 -0
- package/docs/ja/specdojo/guides/branch-workflow-guide.md +34 -1
- package/docs/ja/specdojo/guides/docs-structure-guide.md +2 -0
- package/docs/ja/specdojo/guides/exec-config-guide.md +169 -26
- package/docs/ja/specdojo/guides/exec-operation-guide.md +184 -13
- package/docs/ja/specdojo/guides/exec-worktree-guide.md +2 -0
- package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +40 -3
- package/docs/ja/specdojo/guides/quick-start-guide.md +89 -21
- package/docs/ja/specdojo/guides/register-operation-guide.md +44 -1
- package/docs/ja/specdojo/guides/remote-host-development-guide.md +61 -6
- package/docs/ja/specdojo/guides/review-guide.md +1 -1
- package/docs/ja/specdojo/guides/routine-operation-guide.md +5 -5
- package/docs/ja/specdojo/guides/specdojo-overview-guide.md +1 -1
- package/docs/ja/specdojo/guides/use-case-guide.md +1 -1
- package/docs/ja/specdojo/guides/waza-guide.md +1 -1
- package/docs/ja/specdojo/references/command-reference.md +124 -55
- package/docs/ja/specdojo/references/specdojo-config-reference.md +33 -7
- package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +22 -13
- package/docs/ja/specdojo/standards/job-definition-standard.md +20 -18
- package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +2 -2
- package/docs/ja/specdojo/templates/pjr-derived-items-template.md +22 -0
- package/docs/ja/specdojo/templates/pjr-index-template.md +1 -0
- package/docs/specdojo/schemas/v1/agent-members.schema.yaml +29 -2
- package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +111 -17
- package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +28 -0
- package/docs/specdojo/schemas/v1/job-run.schema.yaml +2 -2
- package/docs/specdojo/schemas/v1/job.schema.yaml +7 -0
- package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +38 -0
- package/docs/specdojo/schemas/v1/register-events.schema.yaml +5 -0
- package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +91 -7
- package/docs/specdojo/schemas/v1/routine-run.schema.yaml +1 -1
- package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +36 -1
- package/package.json +17 -17
- package/templates/antigravity/README.md +6 -2
- package/templates/antigravity/agent-members-snippet.yaml +108 -12
- package/templates/antigravity/exec-defaults-snippet.yaml +8 -13
- package/templates/antigravity/orchestrator.md +61 -2
- package/templates/claude/README.md +27 -3
- package/templates/claude/agents/claude-executor.md +0 -1
- package/templates/claude/agents/claude-reporter.md +2 -1
- package/templates/claude/agents/claude-review-executor.md +0 -1
- package/templates/claude/agents/specdojo-orchestrator.md +61 -2
- package/templates/codex/README.md +40 -4
- package/templates/codex/agents/specdojo-orchestrator.toml +61 -2
- package/templates/codex/orchestrator.md +61 -2
- package/templates/devcontainer/devcontainer.json +5 -2
- package/templates/devcontainer/post-create.sh +15 -7
- package/templates/devcontainer/remote-host/specdojo-tmux.sh.sample +102 -0
- package/templates/devcontainer/remote-host/ssh-config.sample +19 -0
- package/templates/devcontainer/vim/vimrc +37 -0
- package/templates/init-agent-members.yaml +75 -25
- package/templates/init-exec-defaults.yaml +44 -9
- package/templates/opencode/README.md +17 -3
- package/templates/opencode/agents/opencode-executor.md +0 -1
- package/templates/opencode/agents/opencode-reporter.md +2 -1
- package/templates/opencode/agents/opencode-review-executor.md +0 -1
- package/templates/opencode/agents/specdojo-orchestrator.md +61 -2
- package/dist/devcontainer-scaffold.js +0 -165
- package/dist/exec-schedule-gantt-chart.js +0 -2
- package/dist/exec-worktree.js +0 -474
- package/dist/exec.js +0 -2
- package/dist/grade.js +0 -19
- package/templates/claude/agents/claude-expert-review-executor.md +0 -14
- /package/dist/{catalog-plan-prompt.js → catalog/plan-prompt.js} +0 -0
- /package/dist/{catalog-types.js → catalog/types.js} +0 -0
- /package/dist/{template-frontmatter.js → docs/template-frontmatter.js} +0 -0
- /package/dist/{role-types.js → exec/role-types.js} +0 -0
- /package/dist/{exec-schedule-gantt-chart-scope.js → exec/schedule/gantt-chart-scope.js} +0 -0
- /package/dist/{exec-types.js → exec/types.js} +0 -0
- /package/dist/{grade-command-shared.js → grade/command-shared.js} +0 -0
- /package/dist/{register-command-types.js → register/command-types.js} +0 -0
- /package/dist/{review-types.js → review/types.js} +0 -0
- /package/dist/{schedule-phase-sets.js → schedule/phase-sets.js} +0 -0
- /package/dist/{schedule-strategy-profiles.js → schedule/strategy-profiles.js} +0 -0
- /package/dist/{agent-response.js → shared/agent-response.js} +0 -0
- /package/dist/{catalog-paths.js → shared/catalog-paths.js} +0 -0
- /package/dist/{dist-freshness.js → shared/dist-freshness.js} +0 -0
- /package/dist/{git-environment.js → shared/git-environment.js} +0 -0
- /package/dist/{exec-format.js → shared/markdown-format.js} +0 -0
- /package/dist/{practice-id.js → shared/practice-id.js} +0 -0
- /package/dist/{spawn-self.js → shared/spawn-self.js} +0 -0
- /package/dist/{specdojo-gitignore.js → shared/specdojo-gitignore.js} +0 -0
- /package/dist/{template-resolution.js → shared/template-resolution.js} +0 -0
- /package/dist/{yaml-schema-modeline.js → shared/yaml-schema-modeline.js} +0 -0
- /package/dist/{yaml.js → shared/yaml.js} +0 -0
|
@@ -17,7 +17,7 @@ Exec Operation Guide
|
|
|
17
17
|
|
|
18
18
|
**この文書で分かること**
|
|
19
19
|
|
|
20
|
-
- 実行経路の選び方、状態遷移、blocked 復帰、再実行、human
|
|
20
|
+
- 実行経路の選び方、状態遷移、blocked 復帰、再実行、human タスクの扱い、register から approach を使って成果物・kata を作る・直す手順
|
|
21
21
|
|
|
22
22
|
**次に読む文書**
|
|
23
23
|
|
|
@@ -73,17 +73,18 @@ register 実行は exec events を記録しないため、schedule の Ready・C
|
|
|
73
73
|
|
|
74
74
|
### 1.3. ユースケース別の選び方
|
|
75
75
|
|
|
76
|
-
| やりたいこと
|
|
77
|
-
|
|
|
78
|
-
| 1 task をカレントで軽く実行する
|
|
79
|
-
| 1 task をカレントで実行し進捗へ反映する
|
|
80
|
-
| 1 task を隔離して実行する
|
|
81
|
-
| Ready 順に自動実行する
|
|
82
|
-
| 登録簿の項目を agent に実行させる
|
|
83
|
-
|
|
|
84
|
-
|
|
|
85
|
-
|
|
|
86
|
-
|
|
|
76
|
+
| やりたいこと | 代表コマンド | 状態追跡 | worktree |
|
|
77
|
+
| ----------------------------------------------------- | ------------------------------------- | --------------- | -------- |
|
|
78
|
+
| 1 task をカレントで軽く実行する | `exec run --task` | なし | なし |
|
|
79
|
+
| 1 task をカレントで実行し進捗へ反映する | `exec run --task --track-state` | あり | なし |
|
|
80
|
+
| 1 task を隔離して実行する | `exec run --task --worktree` | あり | あり |
|
|
81
|
+
| Ready 順に自動実行する | `exec run --auto` | あり | あり |
|
|
82
|
+
| 登録簿の項目を agent に実行させる | `exec run --register` | register の遷移 | 設定依存 |
|
|
83
|
+
| 登録簿の todo から approach で成果物・kata を実行する | `exec run --register <PJR-ID>` | register の遷移 | 設定依存 |
|
|
84
|
+
| 登録簿の複数項目を指定順に実行する | `exec run --register PJR-A PJR-B` | register の遷移 | 設定依存 |
|
|
85
|
+
| plan を確認してから実行する | `exec plan` -> `exec run --plan` | 任意 | 任意 |
|
|
86
|
+
| worktree の各段階を人が確認する | `exec worktree prepare` から `remove` | 手動 | あり |
|
|
87
|
+
| 同じplanで複数agentを比較する | `exec trial run` | なし | agent別 |
|
|
87
88
|
|
|
88
89
|
`exec run --register ... --register-commit` は、各IDのcommit後にhookによる整形差分を同じcommitへ収束させ、対象差分が残っていないことを検証します。登録簿・派生ビュー・当該plan/resultはrunner管理パスとして扱い、その他の実行前からある利用者変更はcommitしません。過去の未commit plan/resultを検出した場合は、現在のIDへ混ぜず警告します。
|
|
89
90
|
|
|
@@ -361,6 +362,8 @@ track の再生成では、`exec validate` の警告と同じ鮮度判定を使
|
|
|
361
362
|
|
|
362
363
|
provider別の `max_concurrency` や agent 選択は [exec設定ガイド](exec-config-guide.md) を参照します。
|
|
363
364
|
|
|
365
|
+
指名した executor / reporter が provider API やローカル LLM へ接続できず、`connection_error_detection` に一致した場合は、対応する fallback 指定があれば1回だけ切り替えます。この判定は `--on-rate-limit` とは独立しているため、rate limit を `stop` または `wait` にしていても接続不能時の fallback は働きます。fallback 未指定時は通常の失敗として停止します。
|
|
366
|
+
|
|
364
367
|
### 2.6. executor / reporter pipelineの実行と復旧
|
|
365
368
|
|
|
366
369
|
`agent_pipeline` を持つ phase のタスクは、executor(成果物の編集と検証)と reporter(evidence から result を構成)の 2 stage で実行されます。実行コマンドは従来と同じで、stage の agent を固定したい場合だけ `--executor-by` / `--reporter-by` を足します。
|
|
@@ -411,7 +414,38 @@ specdojo exec resume \
|
|
|
411
414
|
|
|
412
415
|
executor と reporter が成功した後の commit・merge・worktree 撤去で止まった場合、`exec resume --task <task-id>` は agent を起動せず、`pipeline-state.json` の `integrate` 段から統合だけを再開します。前回の merge が完了している場合は exec branch を再 merge せず、runner が残した lifecycle 差分を確認したうえで worktree 撤去と `exec complete` だけを行います。通常実行の成功時は `integrate.status=succeeded`、失敗時は `failed` と block event の `pipeline_state_ref` が残ります。
|
|
413
416
|
|
|
414
|
-
### 2.7. register
|
|
417
|
+
### 2.7. register統合後のreviewと自動close
|
|
418
|
+
|
|
419
|
+
register の worktree 実行では、`--post-review` を付けると、成果を統合した後に読み取り専用の review pipeline を実行できます。review executor の既定は `claude-expert-review-executor` で、`--review-by` により変更できます。reporter は `stage_role: reporter` の候補から選び、edit pipeline で `--reporter-by` を指定している場合は同じ reporter を使います。
|
|
420
|
+
|
|
421
|
+
```bash
|
|
422
|
+
specdojo exec run \
|
|
423
|
+
--project <project-id> \
|
|
424
|
+
--register <PJR-ID> \
|
|
425
|
+
--worktree \
|
|
426
|
+
--post-review
|
|
427
|
+
```
|
|
428
|
+
|
|
429
|
+
毎回有効にする場合は `.specdojo/exec-defaults.yaml` に設定します。既定は `false` です。post-review は統合後の差分を対象にするため、in-place 実行では利用できません。
|
|
430
|
+
|
|
431
|
+
```yaml
|
|
432
|
+
run:
|
|
433
|
+
register_execution: worktree
|
|
434
|
+
register_post_review: true
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
review executor は、個票の完了条件、edit plan/result、executor evidence の検証結果、統合 commit の差分を照合します。成果物や個票を変更すると runner が `incomplete` として扱います。runner は verdict と個票の種類から次の遷移を行い、review executor を actor、review result の判断根拠を reason として register event に残します。
|
|
438
|
+
|
|
439
|
+
| 個票の種類 | verdict | 遷移 |
|
|
440
|
+
| ------------ | ------------------------------------------- | ------------------------------------ |
|
|
441
|
+
| todo / issue | `complete` / `complete-with-findings` | `done` へ close |
|
|
442
|
+
| todo / issue | `incomplete` | `waiting` |
|
|
443
|
+
| その他 | `complete` / `complete-with-findings` | `review` のまま(自動 close しない) |
|
|
444
|
+
| すべて | `incomplete`、review 失敗、未対応の verdict | `waiting` |
|
|
445
|
+
|
|
446
|
+
SpecDojo package 自身の `src/`・`tools/`・`package.json`・lock file を変更した項目は、統合済みでも実行中の親プロセスが新しい runner コードを読み直せません。この場合、verdict が完了でも自動 close せず `review` に残します。新しいプロセスで実際の `exec run` を smoke test し、人が close してください。
|
|
447
|
+
|
|
448
|
+
### 2.8. register実行の再開
|
|
415
449
|
|
|
416
450
|
複数の register 項目を worktree で並列実行するときは、`--executor-by` に `PJR-ID=nickname` をカンマ区切りで渡すと、項目ごとに executor を固定できます。従来の `--executor-by <nickname>` は引き続き全項目への共通指定です。項目別指定は起動対象をすべて指定する必要があり、起動対象外の ID や指定漏れがあると、状態遷移や worktree 作成の前にエラーになります。`--dry-run` では各項目について解決した executor とコマンドを確認できます。
|
|
417
451
|
|
|
@@ -535,3 +569,140 @@ specdojo exec refresh --project <project-id>
|
|
|
535
569
|
```
|
|
536
570
|
|
|
537
571
|
成果物の `status` を `ready` に昇格できるのは人だけです。エージェント実行では、`ready` へ昇格させるコミットは exec のガードで拒否されます。
|
|
572
|
+
|
|
573
|
+
## 4. register の todo から approach で成果物・kata を作る・直す手順
|
|
574
|
+
|
|
575
|
+
プロジェクト登録簿(register)の `todo` 個票に進め方(`approach`)と対象(`targets`)を指定し、成果物や kata(実践の型: rulebook / recipe / sample / template)を agent に作成・修正させる手順を説明します。
|
|
576
|
+
|
|
577
|
+
### 4.1. register 経路と exec run --deliverable の違い
|
|
578
|
+
|
|
579
|
+
成果物や kata を単発で作成・修正する経路には、`exec run --deliverable` と register 経由(`exec run --register`)の 2 つがあります。
|
|
580
|
+
|
|
581
|
+
| 観点 | `exec run --deliverable <localId>` | register 経由(`exec run --register <PJR-ID>`) |
|
|
582
|
+
| ------------------ | ---------------------------------------------- | -------------------------------------------------------- |
|
|
583
|
+
| 実行場所・隔離 | カレントの作業ツリーでそのまま実行(in-place) | git worktree で作業を安全に隔離(`--worktree` 推奨) |
|
|
584
|
+
| ブランチ統合 | 統合ブランチへの merge commit を行わない | 成功時に統合ブランチへ merge commit(1 項目 1 commit) |
|
|
585
|
+
| 状態管理・レビュー | 状態イベントを記録せず、review 遷移もない | `open -> in-progress -> review` と遷移し、人間が確認可能 |
|
|
586
|
+
| 台帳・監査履歴 | 登録簿に記録されない | 個票および `events/` 配下の変更履歴に残る |
|
|
587
|
+
|
|
588
|
+
`exec run --deliverable` は作業場所でそのまま実行する軽量な経路ですが、worktree 隔離・統合・review・台帳の記帳を行いません。このため過去の版との互換性のために残されており、計画外や単発の作業であっても、成果物や kata を作る・直す際は変更の安全な隔離と台帳管理が揃った **register の経路(個票に approach を指定して `exec run --register` で実行)を推奨します**。
|
|
589
|
+
|
|
590
|
+
### 4.2. 個票の起票と approach・target の指定
|
|
591
|
+
|
|
592
|
+
register 経由で実行するには、個票に `approach` と `targets` を指定します。
|
|
593
|
+
|
|
594
|
+
`register add` で新規起票するときに `--approach` と `--target` を指定します。
|
|
595
|
+
|
|
596
|
+
```bash
|
|
597
|
+
# 成果物を作成・修正する todo を起票する例
|
|
598
|
+
specdojo register add \
|
|
599
|
+
--project <project-id> \
|
|
600
|
+
--type todo \
|
|
601
|
+
--title "SpecDojo 設定ガイドの改訂" \
|
|
602
|
+
--topic exec-config-guide-revision \
|
|
603
|
+
--difficulty medium \
|
|
604
|
+
--approach fully-guided \
|
|
605
|
+
--target specdojo:exec-config-guide \
|
|
606
|
+
--owner DEV
|
|
607
|
+
```
|
|
608
|
+
|
|
609
|
+
既存の個票へ追加または変更する場合は `register update` を使います。
|
|
610
|
+
|
|
611
|
+
```bash
|
|
612
|
+
specdojo register update \
|
|
613
|
+
--project <project-id> \
|
|
614
|
+
--id <PJR-ID> \
|
|
615
|
+
--difficulty hard \
|
|
616
|
+
--approach fully-guided \
|
|
617
|
+
--target specdojo:exec-config-guide
|
|
618
|
+
```
|
|
619
|
+
|
|
620
|
+
個票 Frontmatter には次のように `approach` と `targets` が記録されます。
|
|
621
|
+
|
|
622
|
+
```yaml
|
|
623
|
+
specdojo:
|
|
624
|
+
id: prj-0001:pjr-xxxx-exec-config-guide-revision
|
|
625
|
+
type: project
|
|
626
|
+
status: draft
|
|
627
|
+
rulebook: specdojo:pjr-rulebook
|
|
628
|
+
part_of:
|
|
629
|
+
- prj-0001:pjr-index
|
|
630
|
+
item_type: todo
|
|
631
|
+
item_status: open
|
|
632
|
+
priority: medium
|
|
633
|
+
difficulty: medium
|
|
634
|
+
owner: DEV
|
|
635
|
+
approach: fully-guided
|
|
636
|
+
targets:
|
|
637
|
+
- specdojo:exec-config-guide
|
|
638
|
+
```
|
|
639
|
+
|
|
640
|
+
`approach` を指定した個票では、`targets` は **1 件だけ必須** です(schedule のタスクと同様に 1 件の成果物または 1 件の kata を対象にします)。
|
|
641
|
+
|
|
642
|
+
`difficulty` は `hard` / `medium` / `easy` のいずれかです。`exec run --register` と `orchestrator night` は、agent を CLI で指定していない段について `exec-defaults.yaml` の `routing` から executor・reporter・rate limit 対応を選びます。既存の個票で `difficulty` を省略した場合や表がない場合は、従来どおり agent 名簿の `priority` 順で自動選択します。CLI の指定は表より優先します。
|
|
643
|
+
|
|
644
|
+
### 4.3. 対象の指定方法と kata 保守 approach の選び方
|
|
645
|
+
|
|
646
|
+
`targets` に指定する対象文書の書き方と、kata 保守の進め方(`approach`)の選び方は次のとおりです。
|
|
647
|
+
|
|
648
|
+
#### 4.3.1. 成果物を対象にする場合
|
|
649
|
+
|
|
650
|
+
- **対象(`targets`)**: 成果物カタログ(DCT)に定義されている成果物の文書 ID(doc id)を指定します(例: `prj-0001:cxd-specdojo`、`specdojo:exec-config-guide`)。プロダクト成果物の場合は `local_id` の canonical 形式(`<project-id>:<local_id>`)も受け付けます。まだ文書ファイルが作成されていない成果物であっても、カタログに定義されていればカタログで解決され、起票・実行できます。
|
|
651
|
+
- **進め方(`approach`)**: 成果物を作成・修正する進め方(`fully-guided`、`recipe-guided`、`freeform`、`bootstrap`、`retrofit`、`cross-deliverable-dedup` など)から目的に応じて選びます。
|
|
652
|
+
|
|
653
|
+
#### 4.3.2. kata(実践の型)を対象にする場合
|
|
654
|
+
|
|
655
|
+
- **対象(`targets`)**: kata の文書 ID(doc id)を指定します(例: `specdojo:pjr-rulebook`、`specdojo:exec-human-finalize-recipe` など)。kata は文書索引(doc-index)で解決されます。
|
|
656
|
+
- **進め方(`approach`)の選び方**: 見直したい kata の種別に対応する保守 approach を選びます。kata 保守では、通常の「成果物 → 実践の型」という参照の向きが逆になり、実践の型そのものが改訂・編集の対象になります。
|
|
657
|
+
|
|
658
|
+
| kata の種別 | approach | 対象となる文書 |
|
|
659
|
+
| ----------- | ---------------------- | ----------------------------------------------------------------- |
|
|
660
|
+
| rulebook | `rulebook-maintenance` | 作成ルール、規律、品質基準(例: `specdojo:pjr-rulebook`) |
|
|
661
|
+
| recipe | `recipe-maintenance` | 実行手順、運用レシピ(例: `specdojo:exec-human-finalize-recipe`) |
|
|
662
|
+
| sample | `sample-maintenance` | 実例、サンプル成果物 |
|
|
663
|
+
| template | `template-maintenance` | 雛形、テンプレート(例: 個票や成果物のテンプレート) |
|
|
664
|
+
|
|
665
|
+
### 4.4. 組み合わせの検証とエラー
|
|
666
|
+
|
|
667
|
+
`approach` と対象の組み合わせに誤りがある場合は、**起票・更新の時点(`register add` / `register update`)および実行の時点(`exec run --register` / `exec plan --register`)** で検証され、エラーで停止します。
|
|
668
|
+
|
|
669
|
+
- 成果物を対象に `rulebook-maintenance` などの kata 保守 approach を指定した場合、または kata 文書を対象に `fully-guided` などの成果物作成 approach を指定した場合は、種別の不一致として拒否されます。
|
|
670
|
+
- 指定した doc id が成果物カタログ(成果物の場合)または文書索引(kata の場合)で解決できない場合もエラーになります。
|
|
671
|
+
- `approach` を指定しながら `--target` が省略されている場合や、複数件指定されている場合もエラーになります。
|
|
672
|
+
|
|
673
|
+
### 4.5. plan の生成と owner の扱い
|
|
674
|
+
|
|
675
|
+
`exec run --register`(または `exec plan --register`)で生成される plan は、通常の register plan ではなく、schedule と共通の approach テンプレートを用いた plan になります。
|
|
676
|
+
|
|
677
|
+
- **完了条件の合成**: 成果物カタログ(DCT)の `done_criteria` と、個票の「2. 完了条件」節に記載された条件の **両方が plan に載ります**。DCT の `done_criteria` を基本とし、個票の完了条件を追加の条件として併記します。
|
|
678
|
+
- **kata 保守の plan**: 指定された kata の文書 ID を編集対象とします。カタログ上でその kata を一意に宣言している成果物があれば根拠として併記し、共有または未宣言の場合は kata 単独の保守 plan を生成します。
|
|
679
|
+
- **owner の扱い**: schedule のタスクで使われる `owner_rules`(トラック別の自動解決規則)は参照せず、**個票の `owner`(例: `DEV`)をそのまま plan の担当(owner)として使用します**。
|
|
680
|
+
|
|
681
|
+
### 4.6. 実行手順の流れ
|
|
682
|
+
|
|
683
|
+
起票から完了までの一連のコマンド実行手順は次のとおりです。
|
|
684
|
+
|
|
685
|
+
```bash
|
|
686
|
+
# 1. todo 個票を起票する(approach と target を指定)
|
|
687
|
+
specdojo register add \
|
|
688
|
+
--project <project-id> \
|
|
689
|
+
--type todo \
|
|
690
|
+
--title "SpecDojo 設定ガイドの改訂" \
|
|
691
|
+
--topic exec-config-guide-revision \
|
|
692
|
+
--approach fully-guided \
|
|
693
|
+
--target specdojo:exec-config-guide \
|
|
694
|
+
--owner DEV
|
|
695
|
+
|
|
696
|
+
# 2. (任意)事前に生成される plan の内容を確認する
|
|
697
|
+
specdojo exec plan --project <project-id> --register <PJR-ID>
|
|
698
|
+
|
|
699
|
+
# 3. worktree 隔離で agent を実行する
|
|
700
|
+
specdojo exec run --project <project-id> --register <PJR-ID> --worktree
|
|
701
|
+
|
|
702
|
+
# 4. agent が成功すると成果物が統合ブランチへマージされ、個票が review 状態に遷移する
|
|
703
|
+
# 成果物と対応結果を確認し、問題なければ close する
|
|
704
|
+
specdojo register close \
|
|
705
|
+
--project <project-id> \
|
|
706
|
+
--id <PJR-ID> \
|
|
707
|
+
--conclusion "設定ガイドを改訂し検証を通過"
|
|
708
|
+
```
|
|
@@ -33,6 +33,8 @@ Exec Worktree Guide
|
|
|
33
33
|
|
|
34
34
|
worktree の checkpoint・commit・merge などで実行する Git コマンドが `fatal: detected dubious ownership` で失敗した場合、共通の Git 実行層は 2 秒、5 秒、10 秒と間隔を広げながら最大 3 回まで待って同じコマンドを再試行し、待ち時間・回数・理由を警告ログへ記録します。作業ディレクトリに `.git` があるにもかかわらず `Not a git repository` で失敗した場合も、一時的な ownership 判定の失敗として同じ間隔と上限を共有します。これらの失敗は所有者が一致していても一時的に起き、すぐの再試行では収まらないことがあるためです。作業ディレクトリに `.git` がない場合や、3 回とも失敗した場合は従来どおり失敗として報告し、それ以外の Git エラーをこの条件では再試行しません。
|
|
35
35
|
|
|
36
|
+
`git worktree add` は、worktree と branch を作成した後で一時的な失敗を返す場合があるため、同じコマンドを再実行する前に作成結果を照合します。目的の path・branch・分岐元 commit がそろっていれば作成済みとして続行します。branch だけが同じ分岐元 commit に作られた部分状態は、その branch と未登録 path を片付けてから再試行します。branch が異なる commit を指す場合や別の worktree で使われている場合は削除せず、競合を報告して停止します。
|
|
37
|
+
|
|
36
38
|
| コマンド | 責務 | Git変更 | イベント変更 |
|
|
37
39
|
| ------------------ | -------------------------------------------------------------------------------- | --------- | ------------ |
|
|
38
40
|
| `worktree prepare` | task worktree を準備し、実行管理ファイルを exec branch へ checkpoint commit する | あり | なし |
|
|
@@ -58,13 +58,17 @@ CLI を直接操作する場合の代表フローは [遂行の技活用ガイ
|
|
|
58
58
|
| `orch:qwen:work` | OpenCode / Qwen 3.8 | `../worktrees/qwen-work`(無ければ自動作成) |
|
|
59
59
|
| `orch:gemma` | OpenCode / Gemma 4 | なし |
|
|
60
60
|
| `orch:gemma:work` | OpenCode / Gemma 4 | `../worktrees/gemma-work`(無ければ自動作成) |
|
|
61
|
-
| `orch:
|
|
62
|
-
| `orch:
|
|
61
|
+
| `orch:flash` | Antigravity / `gemini-3.8-flash-high` | なし |
|
|
62
|
+
| `orch:flash:work` | Antigravity / `gemini-3.8-flash-high` | `../worktrees/agy-work`(無ければ自動作成) |
|
|
63
63
|
|
|
64
64
|
Antigravity CLI(`agy`)はファイル定義の agent を持たないため、Codex と同じく SSOT `.agents/specdojo-orchestrator.agent.md` の本文を `-i`(初期プロンプトを与えて対話を続ける)で渡します。ラッパーは不要で、`.agents/rules/*.md` の薄いラッパー経由で `.github/instructions/` の規則も読み込まれます。
|
|
65
65
|
|
|
66
66
|
Antigravity で使えるモデル ID は `agy models` で確認してください。配布時点の既定値は、agy 1.3.5 で提供される `gemini-3.8-flash-high` です。
|
|
67
67
|
|
|
68
|
+
`specdojo init` と `config scaffold` が利用者の `package.json` へ追加するスクリプトは、Claude Code が `orch:opus`・`orch:sonnet`、Codex が `orch:sol`・`orch:terra`、Antigravity が `orch:flash`、OpenCode が `orch:opencode` です。Codex と Antigravity のスクリプトは、名前に対応するモデルを起動コマンドで明示します。
|
|
69
|
+
|
|
70
|
+
0.4.0 以前に作った `orch:codex`・`orch:agy` は自動では削除・上書きされません。`config scaffold --provider codex` または `config scaffold --provider antigravity` を再実行して新しいスクリプトを追加し、新しい名前で起動できることを確認してから、旧スクリプトを `package.json` から削除してください。
|
|
71
|
+
|
|
68
72
|
用途に応じて使い分けます。
|
|
69
73
|
|
|
70
74
|
```bash
|
|
@@ -80,7 +84,9 @@ npm run orch:sonnet:work
|
|
|
80
84
|
|
|
81
85
|
frontier モデルは Claude Code が `opus`、Codex が `gpt-5.6-sol` に対応します。通常運用はそれぞれ既定の `sonnet` / `gpt-5.6-terra` を使います。
|
|
82
86
|
|
|
83
|
-
worktree 付きは、全 CLI で `tools/worktree/open-agent-worktree.sh` を通して固定名の worktree
|
|
87
|
+
worktree 付きは、全 CLI で `tools/worktree/open-agent-worktree.sh` を通して固定名の worktree を使い、そこから `specdojo orchestrator launch` を起動します。無ければ起動時に作成します。ブランチは `worktree/<name>`、配置は `../worktrees/<name>` です。既存 worktree のブランチが一致しない場合は agent を起動しません。Claude Code の `--worktree` はブランチ名と配置を他の CLI に揃えられないため使用しません。
|
|
88
|
+
|
|
89
|
+
固定 worktree から起動しても、project 設定と `repos[].path` は主 worktree を基準に解決します。provider の作業ディレクトリは固定 worktree のままです。この受け渡しに使う内部用の `SPECDOJO_ORCHESTRATOR_CONFIG_ROOT` は provider 起動前に除去されるため、対話中に実行する別の `specdojo` コマンドへは引き継がれません。
|
|
84
90
|
|
|
85
91
|
### 2.1. 利用リポジトリへ設定を配置する
|
|
86
92
|
|
|
@@ -117,6 +123,37 @@ npx specdojo config scaffold --provider antigravity --global
|
|
|
117
123
|
|
|
118
124
|
対象 project は、`--project <id>` → 環境変数 `SPECDOJO_PROJECT` → `specdojo.config.json` の `current_project` → `projects` 先頭、の順で解決します([遂行の技活用ガイド](waza-guide.md) の `プロジェクト解決順序` を参照)。会話で対象を特定できない場合は確認します。
|
|
119
125
|
|
|
126
|
+
### 3.1. plan モードと register の使い分け
|
|
127
|
+
|
|
128
|
+
Claude Code などの AI ツールが備える plan モード(計画モード)と、`specdojo` のプロジェクト登録簿(register)は、目的とライフサイクルが異なります。オーケストレーターとの対話では、両者の役割を理解して適切に使い分けることが重要です。
|
|
129
|
+
|
|
130
|
+
#### plan モードと register の性質の違い
|
|
131
|
+
|
|
132
|
+
Claude Code の plan モードで作成される plan は、会話の中でアイデアを整理し、作業手順の当たりをつけるための「使い捨ての下書き(ドラフト)」です。既定では `~/.claude/plans/` 配下にランダムな名前で保存され、古いファイルは一定期間(約 30 日)で自動削除される一時的な性質を持ちます(Claude Code では `plansDirectory` 設定で保存先を変更できます)。これは Claude Code に限らず、他の AI ツール(Codex、Antigravity、OpenCode など)が提供する一時的な plan 機能や計画モードにも共通する特徴です。
|
|
133
|
+
|
|
134
|
+
一方、`specdojo` のプロジェクト登録簿(register)は、プロジェクト進行中の意思決定、課題、作業を体系的に記録・追跡する「リポジトリの正本台帳」です(詳細は [[specdojo:register-operation-guide|登録簿運用ガイド]] を参照してください)。
|
|
135
|
+
|
|
136
|
+
両者の違いを次の観点で対比します。
|
|
137
|
+
|
|
138
|
+
| 観点 | plan モードの plan(会話の下書き) | プロジェクト登録簿(register) |
|
|
139
|
+
| :------------------------ | :----------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
|
|
140
|
+
| **識別** | ランダムな名前(UUID 等)。会話外や後からの参照は困難 | `PJR-XXXX` の恒久的な ID。コミットログや他文書から `Refs:` で追跡可能 |
|
|
141
|
+
| **種類** | 種別の区別なし(Markdown の自由記述) | 明確な種別区分(`decision`・`todo`・`issue`・`question`・`risk`・`note` など) |
|
|
142
|
+
| **状態の遷移とイベント** | 状態管理なし(会話終了や時間経過とともに消去) | 明示的な状態遷移(`open` → `in-progress` → `resolved` / `closed` 等)と `events/pjr-XXXX.yaml` による変更履歴の追跡 |
|
|
143
|
+
| **exec・commit との接続** | exec の plan / result や Git コミットとの体系的な紐付けなし | `specdojo exec` の plan / result への接続([[specdojo:exec-operation-guide\|exec運用ガイド]] 参照)、統合コミットとの紐付け |
|
|
144
|
+
| **意思決定の記録** | 決定内容や合意の経緯が会話ログに埋もれて散逸する | `decision` による決定者・決定日・承認方式(合意・レビュー・委任等)の確実な記録 |
|
|
145
|
+
| **履歴の永続性** | 既定で一時ディレクトリに保存され、一定期間(約 30 日)で削除される | リポジトリ内の個票(`pjr-XXXX-<topic>.md`)として Git 履歴とともに永続管理 |
|
|
146
|
+
| **一覧での見渡し** | 会話横断での俯瞰や残課題の一覧化は困難 | 生成される一覧(`pjr-index.md`)や派生ビューにより、全体の状況や残課題を一覧で見渡し可能 |
|
|
147
|
+
|
|
148
|
+
#### 運用の流れ
|
|
149
|
+
|
|
150
|
+
オーケストレーターと対話しながら進める場合、次のように plan モードから register へ情報を昇格させる運用を推奨します。
|
|
151
|
+
|
|
152
|
+
1. **会話の中での検討・下書き(plan モード)**: オーケストレーターと対話しながらアプローチを検討する段階では、AI ツールの plan モードを使って自由に方針や作業手順を下書きします。この plan は使い捨てのドラフトとして扱います。手元にログを残したい場合でも、`plansDirectory` を `tmp/plans` などの Git コミット対象外のディレクトリに指定し、リポジトリにコミットしません。
|
|
153
|
+
2. **残す判断の記録(register: decision)**: 会話や plan モードで合意した設計方針・重要な判断は、plan モード内に放置せず、`decision` 種別の個票として登録簿に書き写します。決定者、決定日、承認方式を記録することで、後から経緯を検証可能にします。
|
|
154
|
+
3. **作業範囲と完了条件の確定(register: todo)**: 実行すべき作業範囲は、`todo` 種別の個票として登録簿に登録し、plan モードで検討した具体的な作業項目や検証条件を「完了条件」セクションへ書き写します。
|
|
155
|
+
4. **タスクの実行と追跡(exec)**: 登録された todo に対して `specdojo exec` を実行し、exec plan と result を通じて成果物の変更と検証を進めます。
|
|
156
|
+
|
|
120
157
|
## 4. 安全と権限
|
|
121
158
|
|
|
122
159
|
オーケストレーターは、状態やファイルを変える操作を承認なしに実行しません。CLI 側の権限機構でも同じ方針を多重に担保します。
|
|
@@ -48,9 +48,10 @@ question を起票する(迷っていること)
|
|
|
48
48
|
プロジェクトリポジトリを作り、SpecDojo を導入して `init` の質問に答えます。
|
|
49
49
|
|
|
50
50
|
```bash
|
|
51
|
-
mkdir app1-
|
|
52
|
-
|
|
53
|
-
|
|
51
|
+
mkdir app1-workspace
|
|
52
|
+
mkdir app1-workspace/app1-specdojo
|
|
53
|
+
git -C app1-workspace/app1-specdojo init
|
|
54
|
+
cd app1-workspace/app1-specdojo
|
|
54
55
|
npm init -y
|
|
55
56
|
npm install --save-dev specdojo
|
|
56
57
|
npx specdojo init
|
|
@@ -66,11 +67,17 @@ Your nickname [owner]: owner
|
|
|
66
67
|
Your display name [Project Owner]: 店主
|
|
67
68
|
Orchestrator providers (...) [codex]: claude <- 使う AI ツールを 1 つ選ぶ
|
|
68
69
|
Delegate work to agents (exec)? [y/N]: <- Enter(実戦は後で設定する)
|
|
69
|
-
|
|
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
72
|
```
|
|
72
73
|
|
|
73
|
-
|
|
74
|
+
入力が不正な場合は理由が表示され、同じ質問だけがもう一度表示されます。たとえば provider に
|
|
75
|
+
`claud` と入力すると、利用可能な provider の一覧に続いて provider の質問だけが再表示されます。
|
|
76
|
+
それまでに答えた project や名簿の内容を入力し直す必要はありません。
|
|
77
|
+
|
|
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
|
+
|
|
80
|
+
登録簿は `docs/ja/projects/prj-0001/controls/project-register/` に作られます。オーケストレーターで進める場合は、終了時に表示される `npm run orch:<provider>` で起動します。成果物カタログは対話では作られません。成果物の構成が定まったら、[[#41-成果物カタログを作成する|成果物カタログを作成する]] に従って `catalog_path` を設定し、`catalog scaffold` で追加してください。
|
|
74
81
|
|
|
75
82
|
### 1.2. 迷っていることを起票する(question)
|
|
76
83
|
|
|
@@ -191,6 +198,8 @@ npx specdojo register build --project prj-0001
|
|
|
191
198
|
|
|
192
199
|
## 2. CLIを初期設定する
|
|
193
200
|
|
|
201
|
+
Node.js 22.13 以上と Git を用意します。オーケストレーターに Claude Code を使う場合は、Claude Code も導入してログインしておきます。ほかの provider も選べます。
|
|
202
|
+
|
|
194
203
|
既定では、SpecDojo の成果物更新、登録簿の状態遷移、実行記録をプロダクトの Git 履歴に混ぜないため、次の **別リポジトリ構成**で始めます。
|
|
195
204
|
|
|
196
205
|
- **プロダクトリポジトリ** `app1/`: ソースコードと、仕様・設計などのプロダクトドキュメントを置きます。
|
|
@@ -204,27 +213,30 @@ app1-workspace/
|
|
|
204
213
|
└── app1-specdojo-worktrees/ # task 単位の worktree 置き場
|
|
205
214
|
```
|
|
206
215
|
|
|
207
|
-
`app1
|
|
216
|
+
既に開発している `app1/` と並べてプロジェクトリポジトリを作り、`app1-specdojo/` に SpecDojo を導入します。worktree 用ディレクトリは、最初の隔離実行時に設定に従って作られます。
|
|
208
217
|
|
|
209
218
|
```bash
|
|
210
|
-
mkdir app1-
|
|
211
|
-
|
|
212
|
-
|
|
219
|
+
mkdir app1-workspace
|
|
220
|
+
mkdir app1-workspace/app1-specdojo
|
|
221
|
+
git -C app1-workspace/app1-specdojo init
|
|
222
|
+
cd app1-workspace/app1-specdojo
|
|
213
223
|
npm init -y
|
|
214
|
-
npm install --save-dev specdojo
|
|
224
|
+
npm install --save-dev specdojo
|
|
215
225
|
# 質問に答えて project、register、agent 実行までを初期設定する
|
|
216
226
|
npx specdojo init
|
|
217
227
|
```
|
|
218
228
|
|
|
219
229
|
`specdojo init` は、project ID と名前、人の nickname と表示名、利用する agent provider、
|
|
220
|
-
exec
|
|
230
|
+
exec・Dev Container の要否を順に質問し、Dev Container を選んだ場合だけ推奨 preset を入れるか(既定は「はい」)を続けて質問します。成果物カタログは対話では質問せず、`--catalog <size>` を
|
|
231
|
+
明示した場合にだけ初期化時に作成します。選択に応じて設定、登録簿、人と
|
|
221
232
|
agent の名簿、provider の scaffold、`package.json` の `orch:<provider>`、exec の起動設定を
|
|
222
233
|
作成します。exec の親検証は、対応する npm script が `package.json` にあるものだけを設定し、
|
|
223
234
|
該当する script がなければ省略します。既存ファイルは上書きせず、作成内容は `--dry-run` で
|
|
224
|
-
|
|
235
|
+
先に確認できます。対話中に不正な値を入力した場合は理由を表示して同じ質問だけをやり直し、
|
|
236
|
+
それまでの回答は保持します。非対話環境や `--yes` では再質問せず、不正な指定をエラーとして終了します。
|
|
225
237
|
|
|
226
238
|
CI や標準入力が端末でない環境では質問しません。次のようにオプションだけで同じ初期設定を
|
|
227
|
-
|
|
239
|
+
行えます。`--devcontainer` を指定した場合は既定で推奨 preset(tmux・Emacs・Vim・推奨の VS Code 拡張と設定)が入ります(preset を使わない場合は `--devcontainer-preset none` を指定します)。省略値は画面に表示されます。
|
|
228
240
|
|
|
229
241
|
```bash
|
|
230
242
|
npx specdojo init --yes \
|
|
@@ -234,18 +246,74 @@ npx specdojo init --yes \
|
|
|
234
246
|
--display-name "Project Owner" \
|
|
235
247
|
--provider claude,codex \
|
|
236
248
|
--exec \
|
|
237
|
-
--catalog small \
|
|
238
249
|
--devcontainer \
|
|
239
250
|
--dry-run
|
|
240
251
|
```
|
|
241
252
|
|
|
242
253
|
初期化後は、表示された `npm run orch:<provider>` でオーケストレーターを起動し、最初の 1 件を
|
|
243
|
-
|
|
254
|
+
起票します。成果物カタログが必要になった場合は、`.specdojo/specdojo.config.json` に `catalog_path` を設定して `specdojo catalog scaffold` で追加します(詳細は [[#41-成果物カタログを作成する|成果物カタログを作成する]] を参照)。オーケストレーターを使わない場合は、同じ案内に表示される
|
|
244
255
|
`exec run --register <id> --executor-by <executor> --reporter-by <reporter>` で実行できます。
|
|
245
256
|
作成された設定と文書は内容を確認して commit してください。
|
|
246
257
|
|
|
247
|
-
|
|
248
|
-
|
|
258
|
+
LP の例と同じく Claude Code へ作業を任せる場合は、provider の質問に `claude`、exec の質問に「はい」と答えます。初期化後は `npm run orch:opus`(または `npm run orch:sonnet`)でオーケストレーターを起動できます。
|
|
259
|
+
|
|
260
|
+
プロダクトを変更する前に、`.specdojo/specdojo.config.json` の `projects.prj-0001` へ、同じ workspace にあるプロダクトリポジトリを接続します。
|
|
261
|
+
|
|
262
|
+
```json
|
|
263
|
+
"repos": [
|
|
264
|
+
{
|
|
265
|
+
"name": "app1",
|
|
266
|
+
"path": "../app1",
|
|
267
|
+
"integration_branch": "main"
|
|
268
|
+
}
|
|
269
|
+
]
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
最初の作業を起票して個票へ完了条件を書いたら、Claude Code の executor と reporter を指定して実行できます。
|
|
273
|
+
|
|
274
|
+
```bash
|
|
275
|
+
npx specdojo register add \
|
|
276
|
+
--project prj-0001 \
|
|
277
|
+
--type todo \
|
|
278
|
+
--title "最初のタスク"
|
|
279
|
+
npx specdojo exec run \
|
|
280
|
+
--project prj-0001 \
|
|
281
|
+
--register PJR-XXXX \
|
|
282
|
+
--worktree \
|
|
283
|
+
--executor-by claude-executor \
|
|
284
|
+
--reporter-by claude-reporter
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
実行後は両方のリポジトリの commit とプロダクトの動作を確認します。
|
|
288
|
+
|
|
289
|
+
```bash
|
|
290
|
+
git -C ../app1 log --oneline -1
|
|
291
|
+
git log --oneline -1
|
|
292
|
+
npm --prefix ../app1 run dev
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
人が result と成果物を確認し、気づいた改善を次の `todo` や `issue` として残してから、元の登録項目を close します。
|
|
296
|
+
|
|
297
|
+
```bash
|
|
298
|
+
npx specdojo register add \
|
|
299
|
+
--project prj-0001 \
|
|
300
|
+
--type todo \
|
|
301
|
+
--title "次の改善" \
|
|
302
|
+
--commit
|
|
303
|
+
npx specdojo register close \
|
|
304
|
+
--project prj-0001 \
|
|
305
|
+
--id PJR-XXXX \
|
|
306
|
+
--conclusion "完了条件を満たした" \
|
|
307
|
+
--commit
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
`@specdojo/docs-lint` は初期設定に必須ではありません。SpecDojo 文書向けの remark プラグインと検証コマンドを使う場合だけ追加します。
|
|
311
|
+
|
|
312
|
+
```bash
|
|
313
|
+
npm install --save-dev @specdojo/docs-lint
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
リポジトリルートの `.remarkrc.yaml` から次のように公開 export を参照できます。
|
|
249
317
|
|
|
250
318
|
```yaml
|
|
251
319
|
plugins:
|
|
@@ -290,11 +358,11 @@ npx specdojo config scaffold --provider antigravity --global
|
|
|
290
358
|
Dev Container は任意です。分離された環境が必要な場合だけ、既存の `.devcontainer/` がないことと生成内容を dry-run で確認してから作成します。
|
|
291
359
|
|
|
292
360
|
```bash
|
|
293
|
-
npx specdojo devcontainer scaffold --provider <name> --dry-run
|
|
294
|
-
npx specdojo devcontainer scaffold --provider <name>
|
|
361
|
+
npx specdojo devcontainer scaffold --provider <name> --preset recommended --dry-run
|
|
362
|
+
npx specdojo devcontainer scaffold --provider <name> --preset recommended
|
|
295
363
|
```
|
|
296
364
|
|
|
297
|
-
Dev Container の `<name>` には `antigravity`、`claude`、`codex`、`opencode`
|
|
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]] を参照してください。
|
|
298
366
|
|
|
299
367
|
設定したプロジェクトを確認します。
|
|
300
368
|
|
|
@@ -83,7 +83,7 @@ specdojo register add --project <project-id> --type todo \
|
|
|
83
83
|
--title "在庫初期データの登録" --topic inventory-seed
|
|
84
84
|
```
|
|
85
85
|
|
|
86
|
-
タイトルが日本語の場合は、内容を表す英語の `--topic` を小文字・ハイフン区切りで指定します。省略して `item` や日本語タイトル中の英単語だけが topic になった場合、`register add` は作成を続けたうえで警告します。警告後も、`register update --topic` で個票名と文書 ID
|
|
86
|
+
タイトルが日本語の場合は、内容を表す英語の `--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
87
|
|
|
88
88
|
`--priority` は次の目安で付けます(省略時は `medium`)。
|
|
89
89
|
|
|
@@ -147,6 +147,27 @@ type は派生ビューの生成と `exec run --register` の挙動(`agent実
|
|
|
147
147
|
}
|
|
148
148
|
```
|
|
149
149
|
|
|
150
|
+
#### actor の指定
|
|
151
|
+
|
|
152
|
+
`register add`・`update`・`renumber` と状態遷移コマンドの `--by` は、次の名前だけを受け付けます。未知の名前を警告だけで記録する互換設定はありません。監査記録の追跡不能を残さないため、書き込み前にエラーで停止します。
|
|
153
|
+
|
|
154
|
+
- 人が操作・決定・承認した場合: project の `pm-members.yaml` にある本人の nickname
|
|
155
|
+
- agent が実行した場合: `.specdojo/agent-members.yaml` の nickname または alias。alias は実体の nickname に解決して event へ記録する
|
|
156
|
+
- SpecDojo の機械的な記帳: `SpecDojo`
|
|
157
|
+
- 対話型オーケストレーター自身の操作: `specdojo-orchestrator`
|
|
158
|
+
- 夜間 runner の操作: `night-orchestrator`
|
|
159
|
+
|
|
160
|
+
`PO`・`DEV` などの Role code は責任区分であり、actor ではありません。利用者の決定や承認をオーケストレーターが代行記帳するときも、`specdojo-orchestrator` ではなく、事前に確認した利用者本人の nickname を渡します。`--by` を省略した場合の `SpecDojo` は CLI/runner の既定値であり、人の決定や承認を表すためには使いません。
|
|
161
|
+
|
|
162
|
+
過去の event は監査記録として書き換えません。このリポジトリで既に使われた旧名を読むときは、次の対応を手掛かりにします。`manual` と Role code の `PO` は実体を一意に決められないため、event の reason と Git 履歴を併せて確認します。
|
|
163
|
+
|
|
164
|
+
| 過去の actor | 現在たどる名前 |
|
|
165
|
+
| -------------------------------------- | -------------------------- |
|
|
166
|
+
| `orchestrator` / `claude-orchestrator` | `specdojo-orchestrator` |
|
|
167
|
+
| `codex-expert-executor` | `sol-executor` |
|
|
168
|
+
| `naoji3x` | `indie` |
|
|
169
|
+
| `manual` / `PO` | 一意に対応しない(要調査) |
|
|
170
|
+
|
|
150
171
|
- 状態遷移は `open` から終端まで順に辿る必要はありません。人が対応した項目や、対話型 orchestrator がその場で処理した項目は、`start` を経ずに `close` / `reject` して構いません。着手を記録していない時点の遷移を後から補うと、実際には起きていない事実がイベントログに残ります。詳しい基準は [プロジェクト登録簿 作成ルール](../rulebooks/pjr-rulebook.md) の `中間状態を経ない終端` を参照します。
|
|
151
172
|
- 直接終端させる場合は、誰がどの経路で対応したかを `register close --by <actor> --reason "<経路と根拠>"` で残します。exec 経由でないため plan / result / evidence が生成されず、実施内容と検証結果は個票の対応結果が唯一の記録になります。
|
|
152
173
|
- agent へ実行させる項目は `exec run --register` を使います。この経路では runner が `start` と `wait` / `review` を記録し、plan / result / evidence も残ります。着手の記録が要る項目は、この経路を選びます。
|
|
@@ -345,6 +366,8 @@ specdojo register history --project <project-id> --since 2026-08-01 --json
|
|
|
345
366
|
|
|
346
367
|
## 3. agent実行・定期実行との連携
|
|
347
368
|
|
|
369
|
+
### 3.1. 通常の agent 実行
|
|
370
|
+
|
|
348
371
|
登録項目は `exec run --register` で agent に実行させられます。
|
|
349
372
|
|
|
350
373
|
```bash
|
|
@@ -362,6 +385,7 @@ specdojo exec run --project <project-id> --register PJR-0012 PJR-0013 --worktree
|
|
|
362
385
|
|
|
363
386
|
- type が `todo` / `issue` / `change-request` の項目は成果物・実装を変更する対応、`question` / `risk` の項目は調査して結論案を result に記録する対応になります。`decision` / `note` は実行対象外です。
|
|
364
387
|
- 状態は register の遷移(`in-progress` / `review` / `waiting`)で追跡され、agent は項目を終端化しません。成功後は人が内容を確認して `register close` します。
|
|
388
|
+
- todo 個票に `approach` と `targets` を指定した場合、成果物カタログの `done_criteria` や kata 参照を取り込んだ schedule と共通の plan が生成されます(詳細は [exec運用ガイド](exec-operation-guide.md) の「register の todo から approach で成果物・kata を作る・直す手順」を参照してください)。
|
|
365
389
|
- 個票 Frontmatter の `targets` に宣言した変更対象文書は、plan 生成時に直近の自動評価(grade)結果があれば `_GRADE_FINDINGS_` として plan に展開されます。`targets` がない場合は finding を展開しません。「関連ドキュメント」は根拠や参考への導線であり、そこに wikilink があるだけでは解消対象になりません。表示は最大10文書・各20件までに制限され、超過分はサイドカーを参照するよう促します。サイドカーがない場合は「finding なし」と表示されます。
|
|
366
390
|
- `--register` には複数の PJR-ID を空白区切り・カンマ区切り(またはその混在)で渡せます。指定順に1件ずつ実行し、各IDが plan/result 生成・開始・agent実行・状態遷移まで完結してから次へ進みます。重複したIDは最初の1件だけを実行します。
|
|
367
391
|
- 全ID処理後にID別の成否・状態遷移・commit 結果を一覧表示します。いずれかが失敗した場合は終了コード 1 で終了します。
|
|
@@ -380,6 +404,25 @@ specdojo exec run --project <project-id> --register PJR-0012 PJR-0013 --worktree
|
|
|
380
404
|
|
|
381
405
|
実行フローの詳細は [exec運用ガイド](exec-operation-guide.md) を参照します。
|
|
382
406
|
|
|
407
|
+
### 3.2. 完了条件を承認して夜間 queue に入れる
|
|
408
|
+
|
|
409
|
+
人が個票の完了条件と変更範囲を確認した todo または issue だけ、次のコマンドで夜間実行を承認します。個票を手編集せず、event に承認者と理由を残します。
|
|
410
|
+
|
|
411
|
+
```bash
|
|
412
|
+
specdojo register update --project <project-id> --id PJR-0012 \
|
|
413
|
+
--autopilot approved --by <approver> --reason "完了条件と変更範囲を承認"
|
|
414
|
+
|
|
415
|
+
# 承認を取り消す
|
|
416
|
+
specdojo register update --project <project-id> --id PJR-0012 \
|
|
417
|
+
--autopilot - --by <approver> --reason "夜間 queue から除外"
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
`autopilot: approved` は「現在の個票に書かれた完了条件」の承認です。夜間 orchestrator は印のある `open` の todo・issue だけを ID 順に選びます。decision、印のない項目、`waiting` の項目は実行しません。完了条件を変更した場合は一度承認を取り消し、変更後の条件を再確認して承認します。
|
|
421
|
+
|
|
422
|
+
夜間実行は `specdojo orchestrator night` が担います。worktree 隔離、post-review、自動 close / `waiting` への復帰を必須とし、件数、並列数、連続失敗停止、rate limit 時の fallback をオプションで制限します。承認範囲外の操作が必要になった失敗は、元項目を `derived_from` に持つ issue として起票します。結果は `execution/reports/night-orchestrator/` の朝報告 1 文書へ集約します。
|
|
423
|
+
|
|
424
|
+
定期起動は Job `job-night-approved-register` と routine `rtn-night-approved-register` を使います。サンプル routine は保護された運用設定を勝手に有効化しないため `enabled: false` です。人が 2 時(Asia/Tokyo)、一晩 10 件、並列 2、連続失敗 2 件、fallback executor を確認してから有効化してください。
|
|
425
|
+
|
|
383
426
|
## 4. 例外対応と特殊な運用
|
|
384
427
|
|
|
385
428
|
ID 重複の復旧と PO 留保事項の承認運用など、通常運用から外れる場面を扱います。
|