specdojo 0.4.6 → 0.4.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/dist/catalog/document-target.js +75 -0
  3. package/dist/commands/agent.js +2 -80
  4. package/dist/exec/agent-config.js +28 -16
  5. package/dist/exec/agent-plan.js +108 -0
  6. package/dist/exec/commands.js +3 -3
  7. package/dist/exec/grade-checkpoint.js +12 -0
  8. package/dist/exec/plans-core.js +4 -65
  9. package/dist/exec/plans-generation.js +22 -5
  10. package/dist/exec/project.js +4 -1
  11. package/dist/exec/register.js +66 -5
  12. package/dist/exec/run/lifecycle-commands.js +2 -0
  13. package/dist/exec/run/register-resume.js +1 -0
  14. package/dist/exec/run/register-state.js +4 -1
  15. package/dist/exec/run/register-worktree.js +5 -1
  16. package/dist/exec/run/schedule-prepare.js +7 -1
  17. package/dist/exec/worktree-command.js +8 -1
  18. package/dist/exec/worktree-ops-merge.js +40 -1
  19. package/dist/grade/apply.js +7 -5
  20. package/dist/grade/command-inspect.js +2 -1
  21. package/dist/grade/command-run.js +39 -0
  22. package/dist/grade/grade.js +3 -1
  23. package/dist/grade/markdown.js +4 -4
  24. package/dist/grade/pipeline-state.js +8 -6
  25. package/dist/grade/plan.js +8 -6
  26. package/dist/grade/run.js +307 -0
  27. package/dist/grade/target-discovery.js +1 -1
  28. package/dist/grade/targets.js +44 -22
  29. package/dist/register/approach.js +16 -0
  30. package/dist/register/core.js +2 -0
  31. package/dist/register/create-commands.js +49 -1
  32. package/dist/register/deliverable-target.js +215 -0
  33. package/dist/register/events.js +4 -0
  34. package/dist/register/item.js +8 -0
  35. package/dist/review/grade.js +19 -17
  36. package/dist/shared/agent-plan.js +1 -0
  37. package/dist/shared/provider-scaffold.js +5 -3
  38. package/dist/specdojo.js +5 -1
  39. package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +2 -2
  40. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +2 -2
  41. package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +2 -2
  42. package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +2 -2
  43. package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +2 -2
  44. package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +2 -2
  45. package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +2 -2
  46. package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +2 -2
  47. package/docs/ja/specdojo/exec-templates/xrp-template.md +2 -2
  48. package/docs/ja/specdojo/guides/exec-config-guide.md +44 -12
  49. package/docs/ja/specdojo/guides/exec-operation-guide.md +4 -0
  50. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +3 -1
  51. package/docs/ja/specdojo/guides/quick-start-guide.md +22 -2
  52. package/docs/ja/specdojo/guides/remote-host-development-guide.md +15 -1
  53. package/docs/ja/specdojo/guides/review-guide.md +2 -2
  54. package/docs/ja/specdojo/guides/ryu-guide.md +12 -0
  55. package/docs/ja/specdojo/references/command-reference.md +52 -27
  56. package/docs/ja/specdojo/references/specdojo-config-reference.md +29 -8
  57. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +28 -22
  58. package/docs/specdojo/schemas/v1/grade-pipeline-state.schema.yaml +1 -1
  59. package/docs/specdojo/schemas/v1/register-events.schema.yaml +2 -0
  60. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +33 -1
  61. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +16 -3
  62. package/package.json +1 -1
  63. package/templates/devcontainer/devcontainer.json +1 -0
  64. package/templates/init-agent-members.yaml +46 -3
  65. package/templates/opencode/README.md +118 -14
  66. package/templates/opencode/agents/specdojo-orchestrator.md +1 -1
  67. package/templates/opencode/opencode.json +25 -0
@@ -167,7 +167,7 @@ members:
167
167
  roles: []
168
168
  type: agent
169
169
  provider: opencode
170
- model: ollama-local/gemma4:31b
170
+ model: ollama-local/gemma4:31b-mlx-work-64k
171
171
  mode: edit
172
172
  stage_role: executor
173
173
  capabilities: [web_search]
@@ -181,7 +181,7 @@ members:
181
181
  roles: []
182
182
  type: agent
183
183
  provider: opencode
184
- model: ollama-local/gemma4:31b
184
+ model: ollama-local/gemma4:31b-mlx-work-64k
185
185
  mode: review
186
186
  stage_role: executor
187
187
  capabilities: [web_search]
@@ -195,7 +195,50 @@ members:
195
195
  roles: []
196
196
  type: agent
197
197
  provider: opencode
198
- model: ollama-local/gemma4:26b
198
+ model: ollama-local/gemma4:26b-mlx-work-64k
199
+ mode: report
200
+ stage_role: reporter
201
+ capabilities: []
202
+ proficiency: normal
203
+ priority: 3
204
+ persona: execution-reporter
205
+ scheduler_strategy: fifo
206
+
207
+ - nickname: qwen-executor
208
+ display_name: OpenCode Qwen Executor
209
+ email: null
210
+ roles: []
211
+ type: agent
212
+ provider: opencode
213
+ model: ollama-local/qwen3.8:27b-mlx-work-64k
214
+ mode: edit
215
+ stage_role: executor
216
+ capabilities: [web_search]
217
+ proficiency: normal
218
+ priority: 3
219
+ persona: task-executor
220
+ scheduler_strategy: critical-first
221
+ - nickname: qwen-review-executor
222
+ display_name: OpenCode Qwen Review Executor
223
+ email: null
224
+ roles: []
225
+ type: agent
226
+ provider: opencode
227
+ model: ollama-local/qwen3.8:27b-mlx-work-64k
228
+ mode: review
229
+ stage_role: executor
230
+ capabilities: [web_search]
231
+ proficiency: normal
232
+ priority: 3
233
+ persona: multi-viewpoint-reviewer
234
+ scheduler_strategy: fifo
235
+ - nickname: qwen-reporter
236
+ display_name: OpenCode Qwen Reporter
237
+ email: null
238
+ roles: []
239
+ type: agent
240
+ provider: opencode
241
+ model: ollama-local/qwen3.8:27b-mlx-work-64k
199
242
  mode: report
200
243
  stage_role: reporter
201
244
  capabilities: []
@@ -13,20 +13,24 @@ specdojo:
13
13
 
14
14
  ## 2. 構成
15
15
 
16
- | パス | 利用プロジェクトでの配置先 | 説明 |
17
- | ------------- | -------------------------- | ---------------------------------------------------------------------- |
18
- | `agents/*.md` | `.opencode/agents/` | agent 定義。パス単位の `edit` とコマンド許可リストの `bash` を含む正本 |
16
+ | パス | 利用プロジェクトでの配置先 | 説明 |
17
+ | --------------- | -------------------------- | --------------------------------------------------------------------------- |
18
+ | `agents/*.md` | `.opencode/agents/` | agent 定義。パス単位の `edit` とコマンド許可リストの `bash` を含む正本 |
19
+ | `opencode.json` | `opencode.json` | Ollama の接続設定(provider: `ollama-local`)と `*-mlx-work-64k` モデル設定 |
19
20
 
20
- 配布する role は、従来の edit / review に加え、成果物編集と検証だけを担う `opencode-executor`、入力された evidence から構造化結果だけを返す `opencode-reporter` を含みます。
21
+ 配布する role は、成果物編集と検証を担う `opencode-executor`、成果物を変更せずレビューする `opencode-review-executor`、入力された evidence から構造化結果だけを返す `opencode-reporter`、対話型で操作を代行する `specdojo-orchestrator` を含みます。
21
22
 
22
23
  ## 3. 導入手順
23
24
 
24
25
  利用プロジェクトのルートで scaffold コマンドを実行します。
25
26
 
26
27
  ```sh
27
- specdojo exec scaffold --provider opencode
28
+ specdojo config scaffold --provider opencode
29
+ # または specdojo exec scaffold --provider opencode
28
30
  ```
29
31
 
32
+ 実行すると、`.opencode/agents/*.md` と `opencode.json` が配置されます(既存ファイルは上書きされません)。
33
+
30
34
  コピー後に次を行います。
31
35
 
32
36
  1. `.specdojo/exec-defaults.yaml` の `providers.opencode.command_template` に `opencode run --agent {agent} --model {model}` を指定し、`command_params.by_mode` で mode から役割の定義を選ぶ。agent の定義は役割ごとの 1 ファイルで model を持たず、model は実体の member の `model` を `--model` で渡す。member 側に `command` は書かない。
@@ -42,19 +46,119 @@ specdojo exec scaffold --provider opencode
42
46
  report: { agent: opencode-reporter }
43
47
  ```
44
48
 
45
- 2. `.specdojo/agent-members.yaml` を実体と別名の 2 段で書く。実体は model の系統で名付け(`gemma-executor`・`qwen-executor` など)、`model` に `opencode.json` の provider 名を含む ID(`ollama-local/gemma4:31b` や `ollama-local/gemma4:26b` など)を持つ。従来の名前(`opencode-executor` など)は `aliases` で実体を指す別名にする。
46
- 3. モデル接続設定(`opencode.json` の provider / model)を利用環境に合わせて作成する。ローカル Ollama の接続先などマシン固有の値を含むため、このテンプレートには含めていない。
47
- 4. コピーしたファイルをコミットする。worktree はコミット済み内容から作られるため、未コミットだと agent 実行時に設定が読めない。
49
+ 2. `.specdojo/agent-members.yaml` を実体と別名の 2 段で書く。実体は model の系統で名付け(`gemma-executor`・`qwen-executor` など)、`model` に `opencode.json` の provider 名を含む ID(`ollama-local/gemma4:31b-mlx-work-64k`、`ollama-local/gemma4:26b-mlx-work-64k`、`ollama-local/qwen3.8:27b-mlx-work-64k` など)を持つ。従来の名前(`opencode-executor` など)は `aliases` で実体を指す別名にする。
50
+ 3. `opencode.json` の接続先(`baseURL`)を利用環境に合わせて確認・調整する(「接続先の設定手順」を参照)。
51
+ 4. Ollama で文脈長 64k の派生モデルタグ(`*-mlx-work-64k`)を作成する(「派生タグ作成手順」を参照)。
52
+ 5. コピーしたファイルをコミットする。worktree はコミット済み内容から作られるため、未コミットだと agent 実行時に設定が読めない。
53
+
54
+ ## 4. 派生タグ作成手順(`*-mlx-work-64k`)
55
+
56
+ SpecDojo のタスク実行では、rulebook・recipe・依存成果物・対象成果物をまとめて読み込むため、公式モデルの既定文脈長(2k〜32k)では作業セットが収まらず agent が終了する場合があります。そのため、Gemma および Qwen では原則として文脈長を 64k(`65536`)に広げた派生タグ(`*-mlx-work-64k`)を使用します。
57
+
58
+ > [!IMPORTANT]
59
+ > `*-mlx-work-64k` は公式配布タグ(`ollama pull` で直接取得できるタグ)ではありません。公式のベースモデルから利用者の手元で作成するローカル派生タグです。公式配布タグとして扱わないでください。
60
+
61
+ ### 作成コマンド例
62
+
63
+ ```bash
64
+ # 1. 公式ベースモデルの取得
65
+ ollama pull gemma4:31b-mlx
66
+ ollama pull gemma4:26b-mlx
67
+ ollama pull qwen3.8:27b-mlx
68
+
69
+ # 2. Modelfile の作成と派生タグの登録
70
+ # Gemma 4 31B:
71
+ echo -e "FROM gemma4:31b-mlx\nPARAMETER num_ctx 65536" > Modelfile.gemma31b
72
+ ollama create gemma4:31b-mlx-work-64k -f Modelfile.gemma31b
73
+
74
+ # Gemma 4 26B:
75
+ echo -e "FROM gemma4:26b-mlx\nPARAMETER num_ctx 65536" > Modelfile.gemma26b
76
+ ollama create gemma4:26b-mlx-work-64k -f Modelfile.gemma26b
77
+
78
+ # Qwen 3.8 27B:
79
+ echo -e "FROM qwen3.8:27b-mlx\nPARAMETER num_ctx 65536" > Modelfile.qwen27b
80
+ ollama create qwen3.8:27b-mlx-work-64k -f Modelfile.qwen27b
81
+ ```
82
+
83
+ Linux や Windows などの非 MLX 環境で標準のベースモデル(`gemma4:31b` 等)を使う場合は、`FROM gemma4:31b` を指定した Modelfile から同様に `*-mlx-work-64k` タグを作成するか、`opencode.json` と名簿のモデル名を環境に合わせて変更してください。
84
+
85
+ 作成後の確認:
86
+
87
+ ```bash
88
+ ollama list
89
+ ```
90
+
91
+ ## 5. 接続先の設定手順
92
+
93
+ scaffold で生成される `opencode.json` は、devcontainer からホスト側の Ollama に接続することを前提として `http://host.docker.internal:11434/v1` を既定値に設定しています。
94
+
95
+ ```json
96
+ {
97
+ "$schema": "https://opencode.ai/config.json",
98
+ "provider": {
99
+ "ollama-local": {
100
+ "npm": "@ai-sdk/openai-compatible",
101
+ "name": "Ollama Local",
102
+ "options": {
103
+ "baseURL": "http://host.docker.internal:11434/v1",
104
+ "apiKey": "not-needed"
105
+ },
106
+ "models": {
107
+ "gemma4:31b-mlx-work-64k": {
108
+ "name": "Gemma 4 31B MLX Work (64k)"
109
+ },
110
+ "gemma4:26b-mlx-work-64k": {
111
+ "name": "Gemma 4 26B MLX Work (64k)"
112
+ },
113
+ "qwen3.8:27b-mlx-work-64k": {
114
+ "name": "Qwen3.8 27B MLX Work (64k)"
115
+ }
116
+ }
117
+ }
118
+ },
119
+ "model": "ollama-local/gemma4:31b-mlx-work-64k"
120
+ }
121
+ ```
122
+
123
+ 環境に応じた調整:
124
+
125
+ - **Docker Desktop 上の devcontainer**: 既定値 `http://host.docker.internal:11434/v1` のまま使用できます。
126
+ - **Linux ホスト / ローカル直接実行**: `http://127.0.0.1:11434/v1` または `http://localhost:11434/v1` に変更します。Ollama サービスが外部からの接続を受け付けるよう、`OLLAMA_HOST=0.0.0.0:11434` が設定されていることを確認してください。
127
+ - **リモートホストの Ollama**: `http://<リモートホストIPまたはFQDN>:11434/v1` を指定します。
128
+
129
+ ### 疎通確認
130
+
131
+ ```bash
132
+ curl http://host.docker.internal:11434/v1/chat/completions \
133
+ -H "Content-Type: application/json" \
134
+ -H "Authorization: Bearer not-needed" \
135
+ -d '{
136
+ "model": "gemma4:26b-mlx-work-64k",
137
+ "messages": [{"role": "user", "content": "疎通確認"}],
138
+ "max_tokens": 16,
139
+ "stream": false
140
+ }'
141
+ ```
142
+
143
+ ## 6. 既存環境の修正手順
144
+
145
+ `specdojo config scaffold` および `specdojo init` は、既存の `opencode.json` や `.specdojo/agent-members.yaml` を既定では上書きしません。
146
+
147
+ 既に OpenCode 設定を導入済みのプロジェクトで、接続設定や `*-mlx-work-64k` モデル指定へ移行する場合は、以下の手順を手動で実施します。
148
+
149
+ 1. **`opencode.json` の作成・更新**:
150
+ リポジトリ直下に `opencode.json` がない場合は作成し、既存の `opencode.json` がある場合は `provider.ollama-local` と `*-mlx-work-64k` モデル定義を追加します。
151
+ 2. **`.specdojo/agent-members.yaml` のモデル更新**:
152
+ 各 member の `model` を `ollama-local/gemma4:31b-mlx-work-64k`、`ollama-local/gemma4:26b-mlx-work-64k`、`ollama-local/qwen3.8:27b-mlx-work-64k` に更新します。
153
+ 3. **`.opencode/agents/specdojo-orchestrator.md` の更新**:
154
+ オーケストレーターの agent 定義がある場合は、frontmatter の `model` を `ollama-local/gemma4:31b-mlx-work-64k` に更新します。
155
+ 4. **派生モデルの作成**:
156
+ 手元の Ollama で「派生タグ作成手順」に従い `*-mlx-work-64k` タグを作成します。
48
157
 
49
- ## 4. カスタマイズ
158
+ ## 7. カスタマイズ
50
159
 
51
160
  - edit agent の `permission.edit` は既定で `docs/**`、`src/**`、`tests/**` を許可する。`permission.edit` / `permission.bash` のパターンは、利用プロジェクトの成果物・execution ディレクトリ配置に合わせて調整する。
52
161
  - 従来の `opencode run --agent {nickname}` と model を持つ定義ファイルで組んだ 1 段の名簿は、そのまま動く。scaffold は既存ファイルを上書きしないため、`--force` で役割ごとの定義(model を持たない)に置き換える場合だけ、上の `command_template` と 2 段の名簿へ移す。
53
- - 文脈の長さ(`num_ctx` など)を広げたい場合は、Modelfile(`FROM gemma4:31b`、`PARAMETER num_ctx 65536` など)を用意して Ollama で別タグを作成し(`ollama create gemma4:31b-work-64k -f Modelfile` など)、`.specdojo/agent-members.yaml` の各 member の `model` をそのタグ名へ書き換えます。
54
- - `specdojo init` や `config scaffold` は既存の `.specdojo/agent-members.yaml` を上書きしません。既に導入したプロジェクトで reporter を 26b に変えたい場合は、`.specdojo/agent-members.yaml` の `gemma-reporter` の `model` を `ollama-local/gemma4:26b`(または独自タグ)へ直接書き換えてください。
55
- - Mac の Apple シリコンでは、Ollama の公式の mlx 版(`gemma4:26b-mlx`・`gemma4:31b-mlx`)を `ollama pull` で取得して使えます。
56
- - 使う場合は `.specdojo/agent-members.yaml` の `model` を `ollama-local/gemma4:26b-mlx` などに書き換えてください。Modelfile で文脈を広げる場合は `FROM` に mlx 版のタグを書きます。
57
- - 既定の雛形は環境を選ばない無印のタグ(`gemma4:26b`・`gemma4:31b`)のままとします。
58
162
  - executor の result パス deny と reporter の全ツール deny は、pipeline の責務境界なので維持する。
59
163
  - executor・review executor の `bash` は deny 基点の許可リストを維持する。`git add` / `git commit` を許可せず、末尾の `git push` と全 `gh` の明示 deny も維持する(許可リストの追加で remote 操作を誤って開かないため)。
60
164
  - orchestrator は利用者の承認後に保護設定も変更できるよう `edit` をリポジトリ全体で allow する。`gh pr view`・`gh pr list`・`gh run list`・`gh run view`・`gh release view` などの読み取りだけを allow し、`git push`、`gh api`、PR・release・repository などの書き込みサブコマンドは明示 deny する。それ以外の `gh` は先頭の `"*": deny` により拒否する。
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  description: SpecDojo 対話型オーケストレーター。会話から意図を読み取り、specdojo register / exec などを提案→承認→実行で代行する。
3
3
  mode: primary
4
- model: ollama-local/gemma4:31b
4
+ model: ollama-local/gemma4:31b-mlx-work-64k
5
5
  temperature: 0.2
6
6
  permission:
7
7
  read:
@@ -0,0 +1,25 @@
1
+ {
2
+ "$schema": "https://opencode.ai/config.json",
3
+ "provider": {
4
+ "ollama-local": {
5
+ "npm": "@ai-sdk/openai-compatible",
6
+ "name": "Ollama Local",
7
+ "options": {
8
+ "baseURL": "http://host.docker.internal:11434/v1",
9
+ "apiKey": "not-needed"
10
+ },
11
+ "models": {
12
+ "gemma4:31b-mlx-work-64k": {
13
+ "name": "Gemma 4 31B MLX Work (64k)"
14
+ },
15
+ "gemma4:26b-mlx-work-64k": {
16
+ "name": "Gemma 4 26B MLX Work (64k)"
17
+ },
18
+ "qwen3.8:27b-mlx-work-64k": {
19
+ "name": "Qwen3.8 27B MLX Work (64k)"
20
+ }
21
+ }
22
+ }
23
+ },
24
+ "model": "ollama-local/gemma4:31b-mlx-work-64k"
25
+ }