specdojo 0.2.1 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.github/agents/specdojo-orchestrator.md +165 -0
- package/CHANGELOG.md +280 -0
- package/README.md +92 -42
- package/dist/agent-response.js +20 -0
- package/dist/agent.js +4 -4
- package/dist/build-command.js +28 -8
- package/dist/dashboard.js +122 -1
- package/dist/devcontainer-command.js +43 -0
- package/dist/devcontainer-scaffold.js +165 -0
- package/dist/exec-agent-config.js +107 -9
- package/dist/exec-agent-git-state.js +18 -0
- package/dist/exec-agent-protected-config.js +46 -8
- package/dist/exec-evidence.js +254 -11
- package/dist/exec-handoff.js +336 -0
- package/dist/exec-parent-validation.js +317 -43
- package/dist/exec-pipeline-state.js +74 -9
- package/dist/exec-plans.js +115 -113
- package/dist/exec-protection-handoff.js +43 -2
- package/dist/exec-provider-scaffold.js +247 -15
- package/dist/exec-register-resume.js +65 -19
- package/dist/exec-register.js +9 -3
- package/dist/exec-repo-integration.js +811 -0
- package/dist/exec-repo-trace.js +182 -0
- package/dist/exec-reporter.js +613 -132
- package/dist/exec-results.js +81 -56
- package/dist/exec-run-lock.js +110 -107
- package/dist/exec-run.js +1585 -356
- package/dist/exec-shared.js +7 -0
- package/dist/exec-slot-lock.js +242 -0
- package/dist/exec-task-repos.js +415 -0
- package/dist/exec-trial.js +51 -25
- package/dist/exec-worktree-command.js +87 -43
- package/dist/exec-worktree-ops.js +502 -57
- package/dist/exec-worktree.js +114 -27
- package/dist/exec.js +13 -6
- package/dist/grade-result.js +128 -0
- package/dist/grade.js +809 -72
- package/dist/init-command.js +443 -0
- package/dist/job.js +160 -10
- package/dist/orchestrator.js +213 -0
- package/dist/register-event-merge.js +169 -0
- package/dist/register-item.js +7 -1
- package/dist/register.js +294 -86
- package/dist/review-grade.js +252 -0
- package/dist/review-plan.js +111 -1
- package/dist/review-types.js +40 -1
- package/dist/routine.js +72 -5
- package/dist/schedule-build.js +2 -2
- package/dist/schedule.js +17 -4
- package/dist/specdojo-config.js +465 -19
- package/dist/specdojo-gitignore.js +135 -0
- package/dist/specdojo.js +6 -0
- package/dist/viewpoint-document-kinds-check.js +128 -0
- package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +348 -90
- package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +51 -17
- package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +7 -5
- package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +29 -31
- package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +34 -55
- package/docs/ja/specdojo/exec-templates/xrp-job-template.md +54 -0
- package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +28 -37
- package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +29 -34
- package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +30 -30
- package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +29 -34
- package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +29 -34
- package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +29 -34
- package/docs/ja/specdojo/exec-templates/xrp-template.md +29 -28
- package/docs/ja/specdojo/exec-templates/xrr-template.md +11 -9
- package/docs/ja/specdojo/guides/docs-editing-guide.md +20 -0
- package/docs/ja/specdojo/guides/docs-structure-guide.md +103 -70
- package/docs/ja/specdojo/guides/exec-config-guide.md +91 -47
- package/docs/ja/specdojo/guides/exec-operation-guide.md +124 -27
- package/docs/ja/specdojo/guides/exec-worktree-guide.md +40 -11
- package/docs/ja/specdojo/guides/kata-guide.md +4 -4
- package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +25 -4
- package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +1 -1
- package/docs/ja/specdojo/guides/practice-system-composition-guide.md +13 -13
- package/docs/ja/specdojo/guides/quick-start-guide.md +260 -30
- package/docs/ja/specdojo/guides/register-operation-guide.md +31 -14
- package/docs/ja/specdojo/guides/release-v0-3-0-migration-guide.md +264 -0
- package/docs/ja/specdojo/guides/remote-host-development-guide.md +22 -1
- package/docs/ja/specdojo/guides/review-guide.md +195 -158
- package/docs/ja/specdojo/guides/routine-operation-guide.md +74 -9
- package/docs/ja/specdojo/guides/ryu-guide.md +32 -30
- package/docs/ja/specdojo/guides/schedule-design-guide.md +10 -10
- package/docs/ja/specdojo/guides/schedule-operation-guide.md +1 -1
- package/docs/ja/specdojo/guides/specdojo-overview-guide.md +58 -33
- package/docs/ja/specdojo/guides/use-case-guide.md +3 -3
- package/docs/ja/specdojo/guides/waza-guide.md +15 -2
- package/docs/ja/specdojo/index.md +2 -2
- package/docs/ja/specdojo/philosophy/specdojo-philosophy.md +5 -5
- package/docs/ja/specdojo/recipes/bps-recipe.md +213 -0
- package/docs/ja/specdojo/recipes/pm-members-recipe.md +52 -117
- package/docs/ja/specdojo/references/command-reference.md +335 -92
- package/docs/ja/specdojo/references/deliverables-reference.md +1 -1
- package/docs/ja/specdojo/references/directory-layout-reference.md +13 -9
- package/docs/ja/specdojo/references/specdojo-config-reference.md +107 -24
- package/docs/ja/specdojo/rulebooks/bps-rulebook.md +132 -220
- package/docs/ja/specdojo/rulebooks/br-rulebook.md +6 -44
- package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +2 -0
- package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +0 -87
- package/docs/ja/specdojo/rulebooks/gl-rulebook.md +61 -39
- package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +0 -87
- package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +1 -33
- package/docs/ja/specdojo/rulebooks/opd-rulebook.md +0 -137
- package/docs/ja/specdojo/rulebooks/opr-rulebook.md +0 -247
- package/docs/ja/specdojo/rulebooks/otp-rulebook.md +0 -83
- package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +4 -2
- package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +78 -150
- package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +5 -4
- package/docs/ja/specdojo/rulebooks/sch-rulebook.md +1 -1
- package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +0 -11
- package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +0 -61
- package/docs/ja/specdojo/rulebooks/tml-rulebook.md +2 -47
- package/docs/ja/specdojo/samples/bps-sample.md +74 -21
- package/docs/ja/specdojo/samples/gl-sample.yaml +17 -1
- package/docs/ja/specdojo/samples/ifx-index-sample.yaml +28 -0
- package/docs/ja/specdojo/samples/pm-members-sample.yaml +2 -67
- package/docs/ja/specdojo/samples/pm-organization-sample.md +8 -7
- package/docs/ja/specdojo/samples/pm-raci-sample.md +1 -1
- package/docs/ja/specdojo/samples/tml-sample.yaml +40 -0
- package/docs/ja/specdojo/standards/document-metadata-standard.md +21 -16
- package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +14 -14
- package/docs/ja/specdojo/standards/job-definition-standard.md +37 -17
- package/docs/ja/specdojo/standards/people-and-organization-definition-standard.md +37 -32
- package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -1
- package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +21 -11
- package/docs/ja/specdojo/templates/agent-members-template.yaml +25 -0
- package/docs/ja/specdojo/templates/bps-template.md +91 -0
- package/docs/ja/specdojo/templates/pm-members-template.yaml +2 -59
- package/docs/specdojo/schemas/v1/agent-members.schema.yaml +76 -0
- package/docs/specdojo/schemas/v1/exec-common.schema.yaml +4 -2
- package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +55 -2
- package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +93 -6
- package/docs/specdojo/schemas/v1/exec-reporter-output.schema.yaml +27 -78
- package/docs/specdojo/schemas/v1/gl.schema.yaml +87 -0
- package/docs/specdojo/schemas/v1/grade-result.schema.yaml +33 -0
- package/docs/specdojo/schemas/v1/job-run.schema.yaml +27 -0
- package/docs/specdojo/schemas/v1/job.schema.yaml +25 -0
- package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +49 -1
- package/docs/specdojo/schemas/v1/pm-members.schema.yaml +9 -169
- package/docs/specdojo/schemas/v1/pm-review-viewpoints.schema.yaml +100 -10
- package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +13 -0
- package/docs/specdojo/schemas/v1/routine-run.schema.yaml +3 -0
- package/docs/specdojo/schemas/v1/routine.schema.yaml +7 -0
- package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +110 -0
- package/package.json +15 -9
- package/templates/antigravity/README.md +27 -2
- package/templates/antigravity/{pm-members-snippet.yaml → agent-members-snippet.yaml} +8 -2
- package/templates/antigravity/exec-defaults-snippet.yaml +7 -6
- package/templates/antigravity/orchestrator.md +18 -7
- package/templates/antigravity/settings.global.json +55 -0
- package/templates/claude/agents/claude-executor.md +14 -0
- package/templates/claude/agents/claude-reporter.md +16 -0
- package/templates/claude/agents/specdojo-orchestrator.md +18 -7
- package/templates/claude/settings.edit.json +27 -1
- package/templates/codex/README.md +5 -4
- package/templates/codex/agents/specdojo-orchestrator.toml +18 -7
- package/templates/codex/orchestrator.md +18 -7
- package/templates/copilot/README.md +7 -5
- package/templates/copilot/{pm-members-snippet.yaml → agent-members-snippet.yaml} +4 -2
- package/templates/devcontainer/devcontainer.json +27 -0
- package/templates/devcontainer/emacs/init.el +88 -0
- package/templates/devcontainer/post-create.sh +62 -0
- package/templates/init-agent-members.yaml +200 -0
- package/templates/init-exec-defaults.yaml +72 -0
- package/templates/opencode/agents/specdojo-orchestrator.md +18 -7
- package/docs/ja/specdojo/exec-templates/xrp-viewpoint-detail-template.md +0 -7
- package/docs/ja/specdojo/exec-templates/xrr-viewpoint-detail-template.md +0 -7
|
@@ -9,7 +9,7 @@ specdojo:
|
|
|
9
9
|
|
|
10
10
|
Quick Start Guide
|
|
11
11
|
|
|
12
|
-
SpecDojo CLI の初期設定から始め、register で課題と判断を整理し、成果物カタログ、schedule、routine
|
|
12
|
+
SpecDojo CLI の初期設定から始め、register で課題と判断を整理し、成果物カタログ、schedule、routine へ展開する基本フローを最短手順で試します。冒頭の `10分で体験する — 仕様の判断台帳` では、kata や成果物カタログを用意せずに、記帳ひとつから判断を残す流れを先に体験します。
|
|
13
13
|
|
|
14
14
|
**対象読者**
|
|
15
15
|
|
|
@@ -17,6 +17,7 @@ SpecDojo CLI の初期設定から始め、register で課題と判断を整理
|
|
|
17
17
|
|
|
18
18
|
**この文書で分かること**
|
|
19
19
|
|
|
20
|
+
- question の起票から decision、仕様書の更新、change-request による修正までを記帳する流れ
|
|
20
21
|
- CLI の初期設定と、register / schedule / routine の使い分け
|
|
21
22
|
- issue / decision / todo から成果物カタログと Schedule へ展開する手順
|
|
22
23
|
- npm package の kata を参照し、必要なものだけ eject する方法
|
|
@@ -28,29 +29,221 @@ SpecDojo CLI の初期設定から始め、register で課題と判断を整理
|
|
|
28
29
|
|
|
29
30
|
各コマンドには、設定済みのオーケストレーター(`specdojo-orchestrator`)へチャットで指示する場合の文言を `# チャット:` として併記します。オーケストレーターは指示を対応する `specdojo` サブコマンドへ変換し、状態を変える操作は実行前に内容を提示して承認を求めます。導入先での設定と起動方法は [オーケストレーター運用ガイド](orchestrator-operation-guide.md) を参照してください。`<project-id>` などのプレースホルダは実際の値に読み替えてください。
|
|
30
31
|
|
|
31
|
-
## 1.
|
|
32
|
+
## 1. 10分で体験する — 仕様の判断台帳
|
|
32
33
|
|
|
33
|
-
|
|
34
|
+
**記して、形にして、磨き続ける。** SpecDojo は、迷っていることを記帳し、決めたことを仕様書へ書き、後日の変更も同じ台帳に残します。この節では、共通サンプルの「駄菓子屋きぬや 販売管理システム構築」を題材に、次の流れを 10 分ほどで体験します。kata(型)や成果物カタログを事前に用意する必要はありません。
|
|
34
35
|
|
|
35
36
|
```text
|
|
36
|
-
|
|
37
|
+
question を起票する(迷っていること)
|
|
38
|
+
-> decision で決める(選択肢・理由・決定)
|
|
39
|
+
-> 仕様書を 1 つ書く(決定を反映する)
|
|
40
|
+
-> 後日 change-request で直す(変更の理由を残す)
|
|
41
|
+
-> 決定ログ・変更要求ログで振り返る
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
各手順には、実行するコマンドと、オーケストレーターへの話しかけ方の例(`# チャット:`)を併記します。どちらか一方で進められます。表示された `PJR-XXXX` は、自分の環境で表示された ID に読み替えてください。
|
|
45
|
+
|
|
46
|
+
### 1.1. 道場を開く(導入と初期設定)
|
|
47
|
+
|
|
48
|
+
プロジェクトリポジトリを作り、SpecDojo を導入して `init` の質問に答えます。
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
mkdir app1-specdojo
|
|
52
|
+
git -C app1-specdojo init
|
|
53
|
+
cd app1-specdojo
|
|
54
|
+
npm init -y
|
|
55
|
+
npm install --save-dev specdojo
|
|
56
|
+
npx specdojo init
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
この体験では、記帳だけを使う最小構成で答えます。`[]` 内は既定値で、Enter だけで採用されます。
|
|
60
|
+
|
|
61
|
+
```text
|
|
62
|
+
Project ID [prj-0001]: <- Enter(prj-0001)
|
|
63
|
+
Project name [My Project]: 駄菓子屋きぬや 販売管理システム構築
|
|
64
|
+
Create a project register? [Y/n]: <- Enter(登録簿を作る)
|
|
65
|
+
Your nickname [owner]: owner
|
|
66
|
+
Your display name [Project Owner]: 店主
|
|
67
|
+
Orchestrator providers (...) [codex]: claude <- 使う AI ツールを 1 つ選ぶ
|
|
68
|
+
Delegate work to agents (exec)? [y/N]: <- Enter(実戦は後で設定する)
|
|
69
|
+
Deliverables catalog (none|small|medium|large) [none]: <- Enter(カタログは使わない)
|
|
70
|
+
Create a Dev Container? [y/N]: <- Enter
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
登録簿は `docs/ja/projects/prj-0001/controls/project-register/` に作られます。オーケストレーターで進める場合は、終了時に表示される `npm run orch:<provider>` で起動します。
|
|
74
|
+
|
|
75
|
+
### 1.2. 迷っていることを起票する(question)
|
|
76
|
+
|
|
77
|
+
レジで扱う支払い方法が決まっていない、という迷いを question として起票します。
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
# チャット:「question を起票して。タイトルは『支払い方法をどこまで扱うか』」
|
|
81
|
+
npx specdojo register add \
|
|
82
|
+
--project prj-0001 \
|
|
83
|
+
--type question \
|
|
84
|
+
--title "支払い方法をどこまで扱うか" \
|
|
85
|
+
--topic payment-scope
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
出力に表示された `PJR-XXXX` を控えます。`controls/project-register/` に `pjr-xxxx-payment-scope.md` という個票ができるので開き、`確認事項` と `背景` に「現金のほか、常連客のつけやキャッシュレスまで扱うか」「つけの記録漏れが問題になっている」などを書きます。個票の章立ては question の型(テンプレート)から与えられます。
|
|
89
|
+
|
|
90
|
+
### 1.3. decisionで決める
|
|
91
|
+
|
|
92
|
+
選択肢と理由を比べて決めるために、decision を起票します。
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
# チャット:「decision を起票して。タイトルは『初期リリースで扱う支払い方法を決める』」
|
|
96
|
+
npx specdojo register add \
|
|
97
|
+
--project prj-0001 \
|
|
98
|
+
--type decision \
|
|
99
|
+
--title "初期リリースで扱う支払い方法を決める" \
|
|
100
|
+
--topic payment-methods
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
decision の個票に、次のように書きます。オーケストレーターを使う場合は、相談した内容がそのまま個票の本文になります。
|
|
104
|
+
|
|
105
|
+
- `検討した選択肢`: A 現金のみ、B 現金とつけ、C 現金とつけとキャッシュレス
|
|
106
|
+
- `決定内容`: B 現金とつけを扱う
|
|
107
|
+
- `採択理由`: つけの記録漏れが現在の主な問題であり、キャッシュレスは利用者が少ない
|
|
108
|
+
|
|
109
|
+
書き終えたら、decision と、元の question を close します。decision と question は close すると `decided` になります。
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
# チャット:「decision PJR-XXXX を『現金とつけを扱う』で完了して」
|
|
113
|
+
npx specdojo register close \
|
|
114
|
+
--project prj-0001 \
|
|
115
|
+
--id PJR-XXXX \
|
|
116
|
+
--conclusion "初期リリースは現金とつけを扱う"
|
|
117
|
+
|
|
118
|
+
# チャット:「question PJR-XXXX を『decision で決定』で完了して」
|
|
119
|
+
npx specdojo register close \
|
|
120
|
+
--project prj-0001 \
|
|
121
|
+
--id PJR-XXXX \
|
|
122
|
+
--conclusion "decision で現金とつけを扱うと決定"
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
### 1.4. 決めたことを仕様書に書く
|
|
126
|
+
|
|
127
|
+
決定を仕様書へ反映します。この体験では成果物カタログを使わず、Markdown を 1 つ作ります。仕様書はプロダクトの文書なので、プロダクトリポジトリ(例: `app1/docs/ja/product/payment-policy.md`)に置きます。
|
|
128
|
+
|
|
129
|
+
```markdown
|
|
130
|
+
# 支払い方法の基本方針
|
|
131
|
+
|
|
132
|
+
## 1. 扱う支払い方法
|
|
133
|
+
|
|
134
|
+
- 現金
|
|
135
|
+
- つけ(常連客のみ。会計時に残高を記録する)
|
|
136
|
+
|
|
137
|
+
## 2. 根拠
|
|
138
|
+
|
|
139
|
+
- decision PJR-XXXX(初期リリースで扱う支払い方法を決める)
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
仕様書から decision の ID を参照しておくと、「なぜこう書いたか」を後から台帳でたどれます。
|
|
143
|
+
|
|
144
|
+
### 1.5. 後日の変更をchange-requestで直す
|
|
145
|
+
|
|
146
|
+
運用を始めた後、「子ども向けに交通系電子マネーも使いたい」という要望が出たとします。仕様書をいきなり書き換えず、change-request として記帳します。
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
# チャット:「change-request を起票して。タイトルは『交通系電子マネーを支払い方法に加える』」
|
|
150
|
+
npx specdojo register add \
|
|
151
|
+
--project prj-0001 \
|
|
152
|
+
--type change-request \
|
|
153
|
+
--title "交通系電子マネーを支払い方法に加える" \
|
|
154
|
+
--topic add-ic-card-payment
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
change-request の個票に `変更要求`、`影響評価`、`審査・決定` を書き、仕様書 `payment-policy.md` の扱う支払い方法へ「交通系電子マネー」を追加して、根拠に change-request の ID を加えます。直し終えたら close します。change-request は close すると `done` になります。
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
# チャット:「change-request PJR-XXXX を『仕様書へ反映』で完了して」
|
|
161
|
+
npx specdojo register close \
|
|
162
|
+
--project prj-0001 \
|
|
163
|
+
--id PJR-XXXX \
|
|
164
|
+
--conclusion "交通系電子マネーを支払い方法の基本方針へ追加"
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### 1.6. 台帳を確かめる
|
|
168
|
+
|
|
169
|
+
記帳のたびに、個票から一覧とログが生成されます。手動で作り直す場合は `register build` を実行します。
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
# チャット:「登録簿の一覧とログを作り直して」
|
|
173
|
+
npx specdojo register build --project prj-0001
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
| 生成物 | 内容 |
|
|
177
|
+
| -------------------------------------------------- | --------------------------------------------- |
|
|
178
|
+
| `controls/project-register/generated/pjr-index.md` | question・decision・change-request を含む全件 |
|
|
179
|
+
| `controls/generated/pm-decision-log.md` | 決定ログ(decision の一覧) |
|
|
180
|
+
| `controls/generated/pm-change-request-log.md` | 変更要求ログ(change-request の一覧) |
|
|
181
|
+
| `controls/generated/pm-issue-log.md` | 課題ログ(issue の一覧) |
|
|
182
|
+
|
|
183
|
+
パスは `docs/ja/projects/prj-0001/` からの相対です。正本は個票の Markdown なので、`git log` でも SpecDojo なしでも読めます。作成された設定・個票・仕様書を確認して commit すれば、体験は完了です。
|
|
184
|
+
|
|
185
|
+
### 1.7. 次に進む
|
|
186
|
+
|
|
187
|
+
- 型と実戦: 仕様書を増やしたくなったら、成果物カタログ(`dct-<domain>.yaml`)で作る成果物を宣言し、型に沿って作ります。手順は以降の `CLIを初期設定する` と `成果物カタログからscheduleへ展開する` を参照してください。
|
|
188
|
+
- 実戦(exec): 起票した todo や issue を AI に実行させるには、[exec設定ガイド](exec-config-guide.md) で agent を設定し、`npx specdojo exec run --project prj-0001 --register PJR-XXXX` を実行します。
|
|
189
|
+
- 評定(grade)と講評(review): 成果物の品質評価と完了判断は [レビューガイド](review-guide.md) を参照してください。v0.3.0 の grade は試験的で、npm package では `grade list` / `plan` / `apply` / `validate` / `result` などの部品を利用できます。通しの実行に使う本体リポジトリの開発用 `tools/grade/run-per-document.sh` は package に含まれず、成果物の grade には project の `catalog_path` が必要です。
|
|
190
|
+
- 記帳の種別と状態遷移は [登録簿運用ガイド](register-operation-guide.md) を参照してください。
|
|
191
|
+
|
|
192
|
+
## 2. CLIを初期設定する
|
|
193
|
+
|
|
194
|
+
既定では、SpecDojo の成果物更新、登録簿の状態遷移、実行記録をプロダクトの Git 履歴に混ぜないため、次の **別リポジトリ構成**で始めます。
|
|
195
|
+
|
|
196
|
+
- **プロダクトリポジトリ** `app1/`: ソースコードと、仕様・設計などのプロダクトドキュメントを置きます。
|
|
197
|
+
- **プロジェクトリポジトリ** `app1-specdojo/`: 登録簿・計画・実行記録などのプロジェクトドキュメントと型(Kata)を置きます。1つのプロジェクトリポジトリに、複数のプロジェクトを格納できます。
|
|
198
|
+
- **worktree 用ディレクトリ** `app1-specdojo-worktrees/`: タスクごとの変更を隔離して進めるために、Git worktree を作る場所です。名前はプロジェクトリポジトリのディレクトリ名から決まります。
|
|
199
|
+
|
|
200
|
+
```text
|
|
201
|
+
app1-workspace/
|
|
37
202
|
├── app1/ # 既存または新規のプロダクトリポジトリ
|
|
38
|
-
├── app1-specdojo/ #
|
|
39
|
-
└── app1-worktrees/
|
|
203
|
+
├── app1-specdojo/ # プロジェクトリポジトリ
|
|
204
|
+
└── app1-specdojo-worktrees/ # task 単位の worktree 置き場
|
|
40
205
|
```
|
|
41
206
|
|
|
42
|
-
workspace
|
|
207
|
+
`app1-workspace/` 直下でプロジェクトリポジトリと worktree 用ディレクトリを作成し、`app1-specdojo/` に依存パッケージと SpecDojo の設定ファイルを用意します。
|
|
43
208
|
|
|
44
209
|
```bash
|
|
45
|
-
mkdir app1-specdojo
|
|
210
|
+
mkdir app1-specdojo
|
|
46
211
|
git -C app1-specdojo init
|
|
47
212
|
cd app1-specdojo
|
|
48
213
|
npm init -y
|
|
49
214
|
npm install --save-dev specdojo @specdojo/docs-lint
|
|
50
|
-
#
|
|
51
|
-
npx specdojo
|
|
215
|
+
# 質問に答えて project、register、agent 実行までを初期設定する
|
|
216
|
+
npx specdojo init
|
|
52
217
|
```
|
|
53
218
|
|
|
219
|
+
`specdojo init` は、project ID と名前、人の nickname と表示名、利用する agent provider、
|
|
220
|
+
exec・成果物カタログ・Dev Container の要否を順に質問します。選択に応じて設定、登録簿、人と
|
|
221
|
+
agent の名簿、provider の scaffold、`package.json` の `orch:<provider>`、exec の起動設定を
|
|
222
|
+
作成します。exec の親検証は、対応する npm script が `package.json` にあるものだけを設定し、
|
|
223
|
+
該当する script がなければ省略します。既存ファイルは上書きせず、作成内容は `--dry-run` で
|
|
224
|
+
先に確認できます。
|
|
225
|
+
|
|
226
|
+
CI や標準入力が端末でない環境では質問しません。次のようにオプションだけで同じ初期設定を
|
|
227
|
+
行えます。省略値は画面に表示されます。
|
|
228
|
+
|
|
229
|
+
```bash
|
|
230
|
+
npx specdojo init --yes \
|
|
231
|
+
--project prj-0001 \
|
|
232
|
+
--name "Example Project" \
|
|
233
|
+
--nickname owner \
|
|
234
|
+
--display-name "Project Owner" \
|
|
235
|
+
--provider claude,codex \
|
|
236
|
+
--exec \
|
|
237
|
+
--catalog small \
|
|
238
|
+
--devcontainer \
|
|
239
|
+
--dry-run
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
初期化後は、表示された `npm run orch:<provider>` でオーケストレーターを起動し、最初の 1 件を
|
|
243
|
+
起票します。オーケストレーターを使わない場合は、同じ案内に表示される
|
|
244
|
+
`exec run --register <id> --executor-by <executor> --reporter-by <reporter>` で実行できます。
|
|
245
|
+
作成された設定と文書は内容を確認して commit してください。
|
|
246
|
+
|
|
54
247
|
`@specdojo/docs-lint` は SpecDojo 文書向けの remark プラグインと検証コマンドを提供します。
|
|
55
248
|
最小構成では、リポジトリルートの `.remarkrc.yaml` から次のように公開 export を参照できます。
|
|
56
249
|
|
|
@@ -62,11 +255,20 @@ plugins:
|
|
|
62
255
|
|
|
63
256
|
文書 lint の全設定例と検証コマンドは [[specdojo:docs-editing-guide|ドキュメント編集ガイド]] を参照してください。
|
|
64
257
|
|
|
65
|
-
|
|
258
|
+
### 2.1. 個別に設定する場合
|
|
66
259
|
|
|
67
|
-
|
|
260
|
+
各設定を個別に管理したい場合は、従来どおり `config init` と各 scaffold を順に実行できます。
|
|
68
261
|
|
|
69
|
-
|
|
262
|
+
```bash
|
|
263
|
+
# チャット:「<project-id> の SpecDojo 設定を初期化して」
|
|
264
|
+
npx specdojo config init
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
`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設定リファレンス]] で確認できます。
|
|
268
|
+
|
|
269
|
+
プロダクト文書は `app1/docs/ja/product/`、プロジェクト文書と SpecDojo の型(Kata)は `app1-specdojo/docs/ja/projects/` と `app1-specdojo/docs/ja/specdojo/` に置きます。現行実装では1つの項目で両リポジトリを自動統合できないため、プロダクト文書や実装も変更する項目は分けるか、人が統合を管理します。詳細は [ドキュメント構成ガイド](docs-structure-guide.md) の `別リポジトリ構成` を参照してください。
|
|
270
|
+
|
|
271
|
+
成果物と実装を常に同じ変更・履歴として扱う場合に限り、**同一リポジトリ構成**としてプロダクトリポジトリのルートで同じ初期化手順を実行できます。CLI は構成を強制しません。
|
|
70
272
|
|
|
71
273
|
agent を使う場合は、設定ファイルを確認した後で利用する provider の設定を配置します。register
|
|
72
274
|
だけを使う最小構成では、この手順を省略できます。
|
|
@@ -75,9 +277,25 @@ agent を使う場合は、設定ファイルを確認した後で利用する p
|
|
|
75
277
|
npx specdojo config scaffold --provider <name>
|
|
76
278
|
```
|
|
77
279
|
|
|
78
|
-
`<name>` には `claude`、`codex`、`copilot`、`opencode` を指定します。従来の
|
|
280
|
+
`<name>` には `antigravity`、`claude`、`codex`、`copilot`、`opencode` を指定します。従来の
|
|
79
281
|
`specdojo exec scaffold --provider <name>` も互換入口として利用できます。
|
|
80
282
|
|
|
283
|
+
Antigravity CLI を無人実行する場合は、先に dry-run でユーザー設定へ追加する permission rule を確認し、明示的に適用します。このグローバル設定は利用者のすべてのリポジトリに効きます。通常の scaffold はユーザーディレクトリへ触れません。
|
|
284
|
+
|
|
285
|
+
```bash
|
|
286
|
+
npx specdojo config scaffold --provider antigravity --global --dry-run
|
|
287
|
+
npx specdojo config scaffold --provider antigravity --global
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
Dev Container は任意です。分離された環境が必要な場合だけ、既存の `.devcontainer/` がないことと生成内容を dry-run で確認してから作成します。
|
|
291
|
+
|
|
292
|
+
```bash
|
|
293
|
+
npx specdojo devcontainer scaffold --provider <name> --dry-run
|
|
294
|
+
npx specdojo devcontainer scaffold --provider <name>
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
Dev Container の `<name>` には `antigravity`、`claude`、`codex`、`opencode` を指定します。既存の `.devcontainer/` は通常実行では上書きされません。生成設定は provider の設定ディレクトリを名前付きボリュームに保存し、ホストの認証情報・秘密鍵・`.env` はマウントしません。Ollama 接続、cron、tmux は必要な場合だけ `--ollama`、`--cron`、`--tmux` で追加します。
|
|
298
|
+
|
|
81
299
|
設定したプロジェクトを確認します。
|
|
82
300
|
|
|
83
301
|
```bash
|
|
@@ -87,9 +305,9 @@ npx specdojo project list
|
|
|
87
305
|
|
|
88
306
|
以降の例では、対象プロジェクトを `<project-id>` と表記します。`current_project` を設定している場合も、最初は対象を確認しやすいように `--project` を明示します。
|
|
89
307
|
|
|
90
|
-
このガイドの基本手順は、
|
|
308
|
+
このガイドの基本手順は、exec 未設定でも完了できるように人が作業する経路を使います。agent に実行させる箇所は、`specdojo init --exec` で設定するか、`.specdojo/agent-members.yaml` と provider を [exec設定ガイド](exec-config-guide.md) に従って個別に設定した後に試してください。
|
|
91
309
|
|
|
92
|
-
###
|
|
310
|
+
### 2.2. kataの参照元を確認する
|
|
93
311
|
|
|
94
312
|
rulebook、standard、recipe、sample、template は、利用リポジトリに同じ ID のファイルがあればそれを優先し、無ければ npm package 内を参照します。初期導入時に kata 一式をコピーする必要はありません。
|
|
95
313
|
|
|
@@ -110,7 +328,7 @@ npx specdojo kata status --kind rulebook
|
|
|
110
328
|
|
|
111
329
|
CLI と同じバージョンで使う `exec-template` と `schema` は npm package 参照固定であり、eject できません。`kata install --all` は docs サイト配信やオフライン運用で全量コピーするときの選択肢で、通常の導入では実行しません。
|
|
112
330
|
|
|
113
|
-
##
|
|
331
|
+
## 3. registerで課題と判断を整理する
|
|
114
332
|
|
|
115
333
|
プロジェクトの開始時点では、解決すべき問題、判断が必要な事項、実施する作業が混在しています。まず register に個票として記録し、issue → decision → todo の順に具体化します。
|
|
116
334
|
|
|
@@ -122,7 +340,7 @@ issue(何が問題か)
|
|
|
122
340
|
-> schedule
|
|
123
341
|
```
|
|
124
342
|
|
|
125
|
-
###
|
|
343
|
+
### 3.1. 登録簿を用意する
|
|
126
344
|
|
|
127
345
|
`.specdojo/specdojo.config.json` の `project_register_path` を設定し、登録簿を初期生成します。
|
|
128
346
|
|
|
@@ -131,7 +349,7 @@ issue(何が問題か)
|
|
|
131
349
|
npx specdojo register scaffold --project <project-id>
|
|
132
350
|
```
|
|
133
351
|
|
|
134
|
-
###
|
|
352
|
+
### 3.2. issue、decision、todoを登録する
|
|
135
353
|
|
|
136
354
|
次の例では、初期スコープと必要な成果物が未確定な状態から、成果物カタログを作成する作業までを3つの個票で追跡します。コマンドはまとめて示していますが、実運用では issue の調査結果を受けて decision を起票し、決定後に todo を起票します。
|
|
137
355
|
|
|
@@ -164,13 +382,15 @@ npx specdojo register add \
|
|
|
164
382
|
|
|
165
383
|
`register add` の出力に表示された `PJR-XXXX` を控えます。すべての登録項目は、背景、選択肢、完了条件、結論などを記録する type 別の個票として生成されます。個票 Frontmatter が構造化フィールドの正本であり、一覧は個票から生成されます。成果物カタログを複数ドメインに分ける場合は、原則として `dct-<domain>.yaml` ごとに todo 個票を起票すると、対象と完了条件を追跡しやすくなります。
|
|
166
384
|
|
|
385
|
+
agent の run と並行して記帳し、その変更だけを commit まで完了させる場合は `register add` や状態遷移コマンドへ `--commit` を付けます。同じ project の `register lifecycle` 枠が空くまで待って記帳・一覧再生成・commit を行うため、別の run の記帳・統合と競合しません。対象の個票や event に既存の未 commit 変更がある場合は、混在を避けるため書き込み前に停止します。
|
|
386
|
+
|
|
167
387
|
| type | 記録する内容 | 完了状態 | agent実行 |
|
|
168
388
|
| ---------- | -------------------------------------- | --------- | ------------------------------------------ |
|
|
169
389
|
| `issue` | 発生している問題、影響、原因、対応結果 | `done` | `exec run --register` で対応できる |
|
|
170
390
|
| `decision` | 判断の背景、選択肢、決定内容、決定理由 | `decided` | 対象外。人が判断して `register close` する |
|
|
171
391
|
| `todo` | 実施内容、完了条件、作業結果 | `done` | `exec run --register` で対応できる |
|
|
172
392
|
|
|
173
|
-
###
|
|
393
|
+
### 3.3. 判断を確定してカタログ作成へ進む
|
|
174
394
|
|
|
175
395
|
issue に人が着手し、個票へ問題、影響、原因、対応方針を記入して完了させます。
|
|
176
396
|
|
|
@@ -216,13 +436,13 @@ agent 設定が完了している場合は、同じ登録項目を実行でき
|
|
|
216
436
|
npx specdojo exec run --project <project-id> --register <issue-or-todo-id>
|
|
217
437
|
```
|
|
218
438
|
|
|
219
|
-
個票内の `_TODO_` を解消してから `register close` すると、個票の文書状態も `ready` になります。基本手順では、成果物カタログ作成の todo を `open`
|
|
439
|
+
個票内の `_TODO_` を解消してから `register close` すると、個票の文書状態も `ready` になります。基本手順では、成果物カタログ作成の todo を `open` のまま残し、`成果物カタログからscheduleへ展開する` で `dct-<domain>.yaml` を作成・検証した後に完了させます。登録簿は立ち上げ時の課題・判断・作業履歴、成果物カタログは合意後の管理対象成果物の正本です。同じ計画済み作業を register と schedule の両方で継続管理しません。
|
|
220
440
|
|
|
221
|
-
##
|
|
441
|
+
## 4. 成果物カタログからscheduleへ展開する
|
|
222
442
|
|
|
223
443
|
この経路では、成果物カタログ(`dct-<domain>.yaml`)とトラック戦略(`sch-strategy-<track>.yaml`)から Schedule を生成し、依存関係に従ってタスクを実行します。
|
|
224
444
|
|
|
225
|
-
###
|
|
445
|
+
### 4.1. 成果物カタログを作成する
|
|
226
446
|
|
|
227
447
|
成果物カタログは「何を、どこに作り、何を満たせば完了か」を定義する `dct-<domain>.yaml` です。`.specdojo/specdojo.config.json` の対象 project へ、たとえば `"catalog_path": "010-deliverables-catalog"` を追加してから次の順に実行します。パスの基準と後続の設定キーは [[specdojo:specdojo-config-reference|SpecDojo設定リファレンス]] を参照してください。
|
|
228
448
|
|
|
@@ -262,7 +482,7 @@ npx specdojo register close \
|
|
|
262
482
|
|
|
263
483
|
`--size` には `small` / `medium` / `large` を指定します。`catalog scaffold` 後は、生成された全成果物をそのまま採用するのではなく、プロジェクトのスコープに合わせて `dct-*.yaml` の成果物、依存関係、完了条件を確認してください。
|
|
264
484
|
|
|
265
|
-
###
|
|
485
|
+
### 4.2. トラック戦略を作成する
|
|
266
486
|
|
|
267
487
|
`sch-strategy-<track>.yaml` は、成果物カタログを実行タスクへ展開するための生成入力です。成果物カタログが WHAT / DONE を持つのに対し、strategy は対象カタログ、作業フェーズ、担当ロールを定義します。新規 strategy は DCT・Timeline・整備状況判定から `schedule strategy generate` で作成し、既存 strategy の owner や開始日などの人間が決めた項目は再生成時も保持します。
|
|
268
488
|
|
|
@@ -284,7 +504,7 @@ members:
|
|
|
284
504
|
|
|
285
505
|
</details>
|
|
286
506
|
|
|
287
|
-
先に `sch-strategy-launch.yaml` の `approach_rules` へ成果物ごとの intent を宣言し、必要な Kata を `specdojo grade`
|
|
507
|
+
先に `sch-strategy-launch.yaml` の `approach_rules` へ成果物ごとの intent を宣言し、必要な Kata を `specdojo grade` で評価します。v0.3.0 の npm package では grade の通しの実行は提供せず、試験的な `grade plan` / `agent run` / `grade apply` などの部品を組み合わせます。1 文書の手順は [CLI コマンドリファレンス](../references/command-reference.md#81-npm-package-で-1-文書を評価する)を参照してください。次のコマンドで strategy の差分を確認して生成します。`<role>` は `pm-roles.yaml` に定義された主担当ロールへ置き換えてください。
|
|
288
508
|
|
|
289
509
|
```bash
|
|
290
510
|
npx specdojo schedule strategy generate --project <project-id> --track launch \
|
|
@@ -350,7 +570,7 @@ owner_rules:
|
|
|
350
570
|
|
|
351
571
|
`owner_rules.owner` は `pm-members.yaml` の `roles` と対応させます。複数フェーズ、反復、レビュー、成果物間のゲートを含む実運用向けの設計は [Schedule設計ガイド](schedule-design-guide.md)、トラックの選び方は [トラック設計ガイド](track-design-guide.md) を参照してください。
|
|
352
572
|
|
|
353
|
-
###
|
|
573
|
+
### 4.3. Scheduleを生成する
|
|
354
574
|
|
|
355
575
|
```bash
|
|
356
576
|
# チャット:「<track> トラックの schedule を生成して」
|
|
@@ -363,7 +583,7 @@ npx specdojo exec refresh --project <project-id>
|
|
|
363
583
|
|
|
364
584
|
`schedule build` は strategy と対象カタログから、実行対象となる `sch-track-<track>.yaml` を生成します。`exec refresh` はそこから Ready タスク、CPM、タイムラインなどを生成します。
|
|
365
585
|
|
|
366
|
-
###
|
|
586
|
+
### 4.4. 1タスクを実行する
|
|
367
587
|
|
|
368
588
|
次のタスクを確認して claim します。`execution: human` のタスクは agent を起動せず、claim 時に確認用resultを生成します。人が成果物とresultを編集してから完了を記録します。
|
|
369
589
|
|
|
@@ -389,11 +609,21 @@ npx specdojo exec refresh --project <project-id>
|
|
|
389
609
|
|
|
390
610
|
成果物の変更は作業ツリーに、実行結果は `<execution_path>/exec/results/` に記録されます。agent による自動実行や並列実行へ進む場合は、[exec設定ガイド](exec-config-guide.md) で設定してから [Schedule実行運用ガイド](schedule-operation-guide.md) を参照してください。
|
|
391
611
|
|
|
612
|
+
`mode: review` のタスクを実行すると、runner は review plan の生成前に対象成果物を grade します。ただし、この自動 grade は npm package に含まれない本体リポジトリ開発用の `tools/grade/run-per-document.sh` を使うため、v0.3.0 の公開物では実行されません。公開物では、`catalog_path` を設定したうえで grade の部品を使って成果物を事前評価します。grade は成果物の品質を観点ごとに評価し、review はその評価結果を付け直さず、変更内容・実行記録・`done_criteria` を照合してタスクの完了可否を判断します。review result の verdict と finding の読み方、成果物を `ready` にする human finalize との境界は [レビューガイド](review-guide.md) を参照してください。
|
|
613
|
+
|
|
614
|
+
agent に review を実行させる場合は、`exec run --plan` で executor と reporter を指定して 2 段で実行します。
|
|
615
|
+
|
|
616
|
+
```bash
|
|
617
|
+
# review を 2 段で実行する
|
|
618
|
+
npx specdojo exec run --project <project-id> --plan <execution_path>/exec/plans/<task-id>-plan.md \
|
|
619
|
+
--executor-by <executor-nickname> --reporter-by <reporter-nickname>
|
|
620
|
+
```
|
|
621
|
+
|
|
392
622
|
ここまでで、register による立ち上げ整理から、成果物カタログ、Schedule、1タスクの完了までの Quick Start は終了です。以降の worktree 隔離実行と routine は、agent 設定後に試す任意の発展手順です。
|
|
393
623
|
|
|
394
|
-
##
|
|
624
|
+
## 5. (発展)worktreeで1タスクを隔離実行する
|
|
395
625
|
|
|
396
|
-
前節「1タスクを実行する」は human・in-place の経路でした。agent に成果物を作らせる場合は、変更を git worktree に隔離して実行し、成功時に現在ブランチへ merge back できます。この経路は agent・provider の設定が前提です。先に [exec設定ガイド](exec-config-guide.md) に従って
|
|
626
|
+
前節「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` まで済ませておきます。
|
|
397
627
|
|
|
398
628
|
対象タスクを worktree に隔離して一括実行します。SpecDojo が worktree 準備・agent 実行・commit・merge・状態更新をまとめて行います。
|
|
399
629
|
|
|
@@ -412,7 +642,7 @@ npx specdojo exec run --project <project-id> --auto --parallel 5
|
|
|
412
642
|
|
|
413
643
|
各段階(prepare → agent → commit → merge → remove)を人が確認しながら進める場合は [exec worktree運用ガイド](exec-worktree-guide.md)、project `develop`・feature・exec のブランチ全体運用は [ブランチワークフローガイド](branch-workflow-guide.md)、自動・並列実行の運用は [Schedule実行運用ガイド](schedule-operation-guide.md) を参照してください。
|
|
414
644
|
|
|
415
|
-
##
|
|
645
|
+
## 6. routineで定期実行する
|
|
416
646
|
|
|
417
647
|
この経路では、動作確認済みの Job を `rtn-*.yaml` に定義した間隔で起動します。Job は schedule または register のagent実行を決定論的なコマンドで呼び出します。routine は任意の発展手順です。先に [exec設定ガイド](exec-config-guide.md) に従ってagentを設定し、次のような open かつ高優先度のtodoを用意します。
|
|
418
648
|
|
|
@@ -79,9 +79,12 @@ specdojo register scaffold --project <project-id>
|
|
|
79
79
|
登録は `register add` で行います。ID は省略すると自動採番されます。
|
|
80
80
|
|
|
81
81
|
```bash
|
|
82
|
-
specdojo register add --project <project-id> --type todo
|
|
82
|
+
specdojo register add --project <project-id> --type todo \
|
|
83
|
+
--title "在庫初期データの登録" --topic inventory-seed
|
|
83
84
|
```
|
|
84
85
|
|
|
86
|
+
タイトルが日本語の場合は、内容を表す英語の `--topic` を小文字・ハイフン区切りで指定します。省略して `item` や日本語タイトル中の英単語だけが topic になった場合、`register add` は作成を続けたうえで警告します。警告後も、`register update --topic` で個票名と文書 ID を変更できます。
|
|
87
|
+
|
|
85
88
|
`--priority` は次の目安で付けます(省略時は `medium`)。
|
|
86
89
|
|
|
87
90
|
| priority | 目安 |
|
|
@@ -123,8 +126,8 @@ type は派生ビューの生成と `exec run --register` の挙動(`agent実
|
|
|
123
126
|
| 他者・外部の対応を待つ | `register wait` | `waiting` |
|
|
124
127
|
| 確認・レビューに回す | `register review` | `review` |
|
|
125
128
|
| 完了する | `register close` | `done`(`decision` / `question` は `decided`。`note` は終端させない) |
|
|
126
|
-
| 対応しないと判断する | `register reject` | `rejected`
|
|
127
|
-
| 延期する | `register defer` | `deferred`
|
|
129
|
+
| 対応しないと判断する | `register reject` | `rejected`(`note` は拒否) |
|
|
130
|
+
| 延期する | `register defer` | `deferred`(`note` は拒否) |
|
|
128
131
|
| 終了済み項目を再開する | `register reopen` | `open` |
|
|
129
132
|
| 担当・期限などを変更する | `register update` | (状態は変えずフィールドを更新) |
|
|
130
133
|
|
|
@@ -147,8 +150,8 @@ type は派生ビューの生成と `exec run --register` の挙動(`agent実
|
|
|
147
150
|
- 状態遷移は `open` から終端まで順に辿る必要はありません。人が対応した項目や、対話型 orchestrator がその場で処理した項目は、`start` を経ずに `close` / `reject` して構いません。着手を記録していない時点の遷移を後から補うと、実際には起きていない事実がイベントログに残ります。詳しい基準は [プロジェクト登録簿 作成ルール](../rulebooks/pjr-rulebook.md) の `中間状態を経ない終端` を参照します。
|
|
148
151
|
- 直接終端させる場合は、誰がどの経路で対応したかを `register close --by <actor> --reason "<経路と根拠>"` で残します。exec 経由でないため plan / result / evidence が生成されず、実施内容と検証結果は個票の対応結果が唯一の記録になります。
|
|
149
152
|
- agent へ実行させる項目は `exec run --register` を使います。この経路では runner が `start` と `wait` / `review` を記録し、plan / result / evidence も残ります。着手の記録が要る項目は、この経路を選びます。
|
|
150
|
-
- 動いていない `open` や期限切れの項目は放置せず、期限の更新、優先度の見直し、`defer` / `reject` のいずれかへ整理します。ただし `note` の `open`
|
|
151
|
-
- `waiting` へ移す理由は `register wait --reason "<理由>"` で個票 Frontmatter の `block_reason`
|
|
153
|
+
- 動いていない `open` や期限切れの項目は放置せず、期限の更新、優先度の見直し、`defer` / `reject` のいずれかへ整理します。ただし `note` の `open` は生きている記録を意味し、終端させません。`register close` / `register reject` / `register defer` は `note` をエラー終了し、対応・回答・判断が必要な場合は、目的に合う別項目の起票を案内します。
|
|
154
|
+
- `waiting` へ移す理由は `register wait --reason "<理由>"` で個票 Frontmatter の `block_reason` に記録します。これは `waiting` 中だけの現在値であり、`start` / `review` / `close` などで別の状態へ遷移すると個票から削除されます。削除前の理由は項目別イベントログに残り、終端時の結論を表す `conclusion` は変更しません。旧 `--conclusion` も互換性のため受け付けますが、記録先は `block_reason` です。誤った現在値を状態遷移なしで削除する場合は `register update --block-reason -` を使います。
|
|
152
155
|
|
|
153
156
|
すべての登録項目は個票(`pjr-XXXX-<topic>.md`)を持ちます。`close` / `reject` は処理状態の遷移とあわせて個票 Frontmatter の `status`(文書成熟度)も更新します。処理状態とは別の状態軸であり、遷移基準は [プロジェクト登録簿 作成ルール](../rulebooks/pjr-rulebook.md) の `個票 status の遷移基準` を正本とします。
|
|
154
157
|
|
|
@@ -159,6 +162,18 @@ type は派生ビューの生成と `exec run --register` の挙動(`agent実
|
|
|
159
162
|
|
|
160
163
|
- 変更前に確認したい場合は `--dry-run` を付けると、個票 Frontmatter の変更予定と再生成されるビューを表示します。
|
|
161
164
|
|
|
165
|
+
記帳と commit を一つの操作として完了させる場合は、`add` / `update` / `renumber` と各状態遷移コマンドに `--commit` を付けます。
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
specdojo register close \
|
|
169
|
+
--project <project-id> \
|
|
170
|
+
--id PJR-0005 \
|
|
171
|
+
--conclusion "取消処理で在庫数を戻すよう修正" \
|
|
172
|
+
--commit
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
`--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 は行いません。
|
|
176
|
+
|
|
162
177
|
### 2.2. 個票の作成
|
|
163
178
|
|
|
164
179
|
すべての登録項目は、type 別のテンプレート(`pjr-todo-template.md` など `pjr-<type>-template.md`)から作る個票です。`register add` は個票の Frontmatter に構造化フィールドを書き込み、H1 と本文にタイトル・説明を置きます。
|
|
@@ -289,13 +304,13 @@ specdojo register history --project <project-id> --since 2026-08-01 --json
|
|
|
289
304
|
2026-08-09T08:20:00Z reg_cd2 PJR-0012 updated status: review -> done; completed: - -> 2026-08-09 # close by PO: accepted
|
|
290
305
|
```
|
|
291
306
|
|
|
292
|
-
- `register add`、状態遷移、`register update`、`register renumber` は、現在値を個票へ、event を項目別イベントファイルへ書き込みます。`--by` と `--reason` を指定すると actor
|
|
307
|
+
- `register add`、状態遷移、`register update`、`register renumber` は、現在値を個票へ、event を項目別イベントファイルへ書き込みます。`--by` と `--reason` を指定すると actor と理由を明示できます。記帳と再生成を `register lifecycle` 枠の内側で commit まで完了させる場合は `--commit` を付けます。
|
|
293
308
|
- 一覧の列に現れない変更(対応結果本文の追記、個票 `status` の昇格など)は event になりません。個票の全差分が必要な場合は `git log -p` を使います。
|
|
294
309
|
- `--status-only` は追加・削除・状態遷移だけを残し、変更内容も遷移に関わる項目(`status` / `type` / `completed` / `conclusion`)へ絞ります。
|
|
295
310
|
- `renumber` による ID 付け替えは、`id` の変更を含む `updated` イベントとして現れます。
|
|
296
311
|
- 複数の遷移を1コミットへまとめたり squash したりしても、項目別イベントファイルに残る各 event の発生日時・actor・変更内容は失われません。`register start` を含む遷移時の commit policy は別の運用判断です。
|
|
297
312
|
- 個票とイベントログはそれぞれ一時ファイルを同一ディレクトリで完成させてから置換します。同じ現在値への再実行は event を増やさず、`register build` がファイルの 1 対 1 対応、イベント ID・直前参照・状態連鎖・最新状態を検証するため、中断による片側だけの更新も検出できます。
|
|
298
|
-
- 異なる項目の並行実行は別の個票とイベントファイルへ書くため共有ログ競合を起こしません。同じ項目を複数 worktree
|
|
313
|
+
- 異なる項目の並行実行は別の個票とイベントファイルへ書くため共有ログ競合を起こしません。同じ項目を複数 worktree で変更してイベントファイルが競合した場合は、統合時に両側のイベントの和集合で解決します。
|
|
299
314
|
- exec event と共通化するのは UTC 秒精度、version、actor、reason、追記・検証の原則です。exec は task state の SSOT で 1 event 1 JSON、Register は現在値を個票に維持し項目別 YAML 配列を監査履歴とするため、保存形式と fold 処理は共通化しません。
|
|
300
315
|
- 生成物(`generated/` 配下)は追跡対象外のため、PR の差分にも Git 履歴にも現れません。レビュー対象は個票と `events/` 配下の項目別ログです。
|
|
301
316
|
- 既存プロジェクトは移行前でも動作し、event のない個票は Git 履歴から再構成します。`register migrate --dry-run` で件数を確認し、`register migrate` で復元可能な Git 履歴を決定的な event ID へ変換します。浅い clone などで履歴が不足する場合は無理に合成せず Git フォールバックを維持します。
|
|
@@ -338,8 +353,8 @@ specdojo exec run --project <project-id> --register PJR-0012
|
|
|
338
353
|
# 複数項目を指定順に直列実行する(成功IDごとにcommit、途中失敗でも継続)
|
|
339
354
|
specdojo exec run --project <project-id> --register PJR-0012 PJR-0013 --register-commit --on-failure continue
|
|
340
355
|
|
|
341
|
-
#
|
|
342
|
-
specdojo exec run --project <project-id> --register PJR-0012 --
|
|
356
|
+
# 設定に関係なく、現在の作業ツリーで明示的に実行する
|
|
357
|
+
specdojo exec run --project <project-id> --register PJR-0012 --in-place
|
|
343
358
|
|
|
344
359
|
# worktree 隔離のまま複数項目を並列実行する
|
|
345
360
|
specdojo exec run --project <project-id> --register PJR-0012 PJR-0013 --worktree --parallel 2
|
|
@@ -347,13 +362,15 @@ specdojo exec run --project <project-id> --register PJR-0012 PJR-0013 --worktree
|
|
|
347
362
|
|
|
348
363
|
- type が `todo` / `issue` / `change-request` の項目は成果物・実装を変更する対応、`question` / `risk` の項目は調査して結論案を result に記録する対応になります。`decision` / `note` は実行対象外です。
|
|
349
364
|
- 状態は register の遷移(`in-progress` / `review` / `waiting`)で追跡され、agent は項目を終端化しません。成功後は人が内容を確認して `register close` します。
|
|
350
|
-
-
|
|
365
|
+
- 個票 Frontmatter の `targets` に宣言した変更対象文書は、plan 生成時に直近の自動評価(grade)結果があれば `_GRADE_FINDINGS_` として plan に展開されます。`targets` がない場合は finding を展開しません。「関連ドキュメント」は根拠や参考への導線であり、そこに wikilink があるだけでは解消対象になりません。表示は最大10文書・各20件までに制限され、超過分はサイドカーを参照するよう促します。サイドカーがない場合は「finding なし」と表示されます。
|
|
351
366
|
- `--register` には複数の PJR-ID を空白区切り・カンマ区切り(またはその混在)で渡せます。指定順に1件ずつ実行し、各IDが plan/result 生成・開始・agent実行・状態遷移まで完結してから次へ進みます。重複したIDは最初の1件だけを実行します。
|
|
352
367
|
- 全ID処理後にID別の成否・状態遷移・commit 結果を一覧表示します。いずれかが失敗した場合は終了コード 1 で終了します。
|
|
353
|
-
- `--register-commit` を付けると成功IDごとに、その実行で生じた変更だけをcommit
|
|
354
|
-
-
|
|
355
|
-
-
|
|
356
|
-
-
|
|
368
|
+
- `--register-commit` を付けると成功IDごとに、その実行で生じた変更だけをcommitします(実行前から作業ツリーにある利用者の変更は含めません)。commit subject は `exec(register <PJR-ID>): <title>` とし、commitlint の100文字上限を超える場合は末尾を `…` に置き換えて100文字へ切り詰めます。`--on-failure`(`stop` 既定 / `continue`)で途中失敗時に停止するか継続するかを選びます。`stop` では失敗以降のIDが skipped として記録されます。
|
|
369
|
+
- 実行場所の既定は `.specdojo/exec-defaults.yaml` の `run.register_execution` で `worktree` / `in-place` を選びます。未設定の既存リポジトリは互換性のため in-place です。CLI の `--worktree` / `--in-place` は設定を上書きし、同時指定はエラーになります。
|
|
370
|
+
- worktree モードでは、成果物の変更を git worktree に隔離して実行し、成功時に統合ブランチへ merge back します。task worktree では root と package-lock 付き独立 package ごとに `npm ci` を実行し、書き込み可能な独立 `node_modules` を準備してから agent を起動します。成功時の `start → review`、plan、result、成果物は `exec(register <PJR-ID>): <title>` の merge commit に同梱され、統合ブランチの first-parent には1項目1commitだけが増えます。失敗時は `start → waiting` と plan / result を `exec(register <PJR-ID>): wait` commit 1件にまとめ、worktree を保持します。`--resume` で再開した場合の `start` 遷移も exec branch 側に記録され、成功時は merge commit 1件、再び失敗した場合は `wait` commit 1件になります。worktree モードは常に commit するため `--register-commit` は無視されます(指定すると注記を表示します)。
|
|
371
|
+
- worktree の準備時間が見合わない小さな作業で、失敗差分を現在の作業ツリーで直ちに整理できる場合だけ `--in-place` を明示します。in-place は直列実行で、変更を作業ツリーへ残します。`--register-commit` を付けると成功IDごとに commit しますが、`--resume` / `--force-restart` / `--join` と `--parallel` は使えません。
|
|
372
|
+
- worktree モードに限り `--parallel <n>` で複数項目を並列実行できます。状態遷移は直列化され、成果物は項目ごとの worktree に隔離されます。親 runner の検証(`pipeline.parent_validations`)も既定では 1 項目ずつ直列に実行され、executor と reporter だけが並列に動きます(同時数は `pipeline.parent_validation_concurrency` で変更できます)。in-place モードで `--parallel` を指定するとエラーになります。失敗時は当該項目の worktree を保持します(調査・再実行のため)。
|
|
373
|
+
- `--worktree` の実行中に別の項目を後から並行させる場合は、後から起動する run に `--join` を付けます(例: `exec run --register <PJR-ID> --worktree --join`)。状態遷移・統合・生成物の再生成、provider の `max_concurrency`、親検証の枠は、合流した run を跨いで統制されます。同時に動かせる run の数は `run.max_concurrent_runs`(既定 4)で、使用中の枠は `exec slots` で確認できます。詳細は [exec運用ガイド](exec-operation-guide.md) の「実行中の register worktree 実行へ後から合流する」を参照してください。
|
|
357
374
|
- 実行せずに plan の内容だけ確認したい場合は `exec plan --register <PJR-ID>` を使います。
|
|
358
375
|
- open な項目の定期スイープなど、時刻条件で繰り返す場合は routine(`rtn-*.yaml`)を使います。
|
|
359
376
|
|