specdojo 0.2.0 → 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.
Files changed (170) hide show
  1. package/.github/agents/specdojo-orchestrator.md +165 -0
  2. package/CHANGELOG.md +280 -0
  3. package/README.md +143 -30
  4. package/dist/agent-response.js +20 -0
  5. package/dist/agent.js +4 -4
  6. package/dist/build-command.js +28 -8
  7. package/dist/dashboard.js +140 -9
  8. package/dist/devcontainer-command.js +43 -0
  9. package/dist/devcontainer-scaffold.js +165 -0
  10. package/dist/exec-agent-config.js +107 -9
  11. package/dist/exec-agent-git-state.js +18 -0
  12. package/dist/exec-agent-protected-config.js +46 -8
  13. package/dist/exec-evidence.js +254 -11
  14. package/dist/exec-format.js +13 -4
  15. package/dist/exec-handoff.js +336 -0
  16. package/dist/exec-parent-validation.js +317 -43
  17. package/dist/exec-pipeline-state.js +74 -9
  18. package/dist/exec-plans.js +115 -113
  19. package/dist/exec-protection-handoff.js +43 -2
  20. package/dist/exec-provider-scaffold.js +247 -15
  21. package/dist/exec-register-resume.js +65 -19
  22. package/dist/exec-register.js +9 -3
  23. package/dist/exec-repo-integration.js +811 -0
  24. package/dist/exec-repo-trace.js +182 -0
  25. package/dist/exec-reporter.js +613 -132
  26. package/dist/exec-results.js +81 -56
  27. package/dist/exec-run-lock.js +110 -107
  28. package/dist/exec-run.js +1585 -356
  29. package/dist/exec-shared.js +7 -0
  30. package/dist/exec-slot-lock.js +242 -0
  31. package/dist/exec-task-repos.js +415 -0
  32. package/dist/exec-trial.js +51 -25
  33. package/dist/exec-worktree-command.js +87 -43
  34. package/dist/exec-worktree-ops.js +502 -57
  35. package/dist/exec-worktree.js +114 -27
  36. package/dist/exec.js +13 -6
  37. package/dist/grade-result.js +128 -0
  38. package/dist/grade.js +809 -72
  39. package/dist/init-command.js +443 -0
  40. package/dist/job.js +160 -10
  41. package/dist/orchestrator.js +213 -0
  42. package/dist/package-paths.js +19 -1
  43. package/dist/register-event-merge.js +169 -0
  44. package/dist/register-item.js +7 -1
  45. package/dist/register.js +294 -86
  46. package/dist/review-grade.js +252 -0
  47. package/dist/review-plan.js +111 -1
  48. package/dist/review-types.js +40 -1
  49. package/dist/routine.js +72 -5
  50. package/dist/schedule-build.js +2 -2
  51. package/dist/schedule.js +17 -4
  52. package/dist/specdojo-config.js +466 -20
  53. package/dist/specdojo-gitignore.js +135 -0
  54. package/dist/specdojo.js +8 -1
  55. package/dist/viewpoint-document-kinds-check.js +128 -0
  56. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +348 -90
  57. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +51 -17
  58. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +7 -5
  59. package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +29 -31
  60. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +34 -55
  61. package/docs/ja/specdojo/exec-templates/xrp-job-template.md +54 -0
  62. package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +28 -37
  63. package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +29 -34
  64. package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +30 -30
  65. package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +29 -34
  66. package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +29 -34
  67. package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +29 -34
  68. package/docs/ja/specdojo/exec-templates/xrp-template.md +29 -28
  69. package/docs/ja/specdojo/exec-templates/xrr-template.md +11 -9
  70. package/docs/ja/specdojo/guides/docs-editing-guide.md +20 -0
  71. package/docs/ja/specdojo/guides/docs-structure-guide.md +103 -70
  72. package/docs/ja/specdojo/guides/exec-config-guide.md +91 -47
  73. package/docs/ja/specdojo/guides/exec-operation-guide.md +124 -27
  74. package/docs/ja/specdojo/guides/exec-worktree-guide.md +40 -11
  75. package/docs/ja/specdojo/guides/kata-guide.md +4 -4
  76. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +25 -4
  77. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +1 -1
  78. package/docs/ja/specdojo/guides/practice-system-composition-guide.md +13 -13
  79. package/docs/ja/specdojo/guides/quick-start-guide.md +261 -32
  80. package/docs/ja/specdojo/guides/register-operation-guide.md +31 -14
  81. package/docs/ja/specdojo/guides/release-v0-3-0-migration-guide.md +264 -0
  82. package/docs/ja/specdojo/guides/remote-host-development-guide.md +184 -0
  83. package/docs/ja/specdojo/guides/review-guide.md +195 -158
  84. package/docs/ja/specdojo/guides/routine-operation-guide.md +74 -9
  85. package/docs/ja/specdojo/guides/ryu-guide.md +32 -30
  86. package/docs/ja/specdojo/guides/schedule-design-guide.md +10 -10
  87. package/docs/ja/specdojo/guides/schedule-operation-guide.md +1 -1
  88. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +58 -33
  89. package/docs/ja/specdojo/guides/use-case-guide.md +3 -3
  90. package/docs/ja/specdojo/guides/waza-guide.md +15 -2
  91. package/docs/ja/specdojo/index.md +2 -2
  92. package/docs/ja/specdojo/philosophy/specdojo-philosophy.md +5 -5
  93. package/docs/ja/specdojo/recipes/bps-recipe.md +213 -0
  94. package/docs/ja/specdojo/recipes/pm-members-recipe.md +52 -117
  95. package/docs/ja/specdojo/references/command-reference.md +336 -93
  96. package/docs/ja/specdojo/references/deliverables-reference.md +1 -1
  97. package/docs/ja/specdojo/references/directory-layout-reference.md +13 -9
  98. package/docs/ja/specdojo/references/specdojo-config-reference.md +107 -24
  99. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +132 -220
  100. package/docs/ja/specdojo/rulebooks/br-rulebook.md +6 -44
  101. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +2 -0
  102. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +0 -87
  103. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +61 -39
  104. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +0 -87
  105. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +1 -33
  106. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +0 -137
  107. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +0 -247
  108. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +0 -83
  109. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +4 -2
  110. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +78 -150
  111. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +5 -4
  112. package/docs/ja/specdojo/rulebooks/sch-rulebook.md +1 -1
  113. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +0 -11
  114. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +0 -61
  115. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +2 -47
  116. package/docs/ja/specdojo/samples/bps-sample.md +74 -21
  117. package/docs/ja/specdojo/samples/gl-sample.yaml +17 -1
  118. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +28 -0
  119. package/docs/ja/specdojo/samples/pm-members-sample.yaml +2 -67
  120. package/docs/ja/specdojo/samples/pm-organization-sample.md +8 -7
  121. package/docs/ja/specdojo/samples/pm-raci-sample.md +1 -1
  122. package/docs/ja/specdojo/samples/tml-sample.yaml +40 -0
  123. package/docs/ja/specdojo/standards/document-metadata-standard.md +21 -16
  124. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +14 -14
  125. package/docs/ja/specdojo/standards/job-definition-standard.md +37 -17
  126. package/docs/ja/specdojo/standards/people-and-organization-definition-standard.md +37 -32
  127. package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -1
  128. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +21 -11
  129. package/docs/ja/specdojo/templates/agent-members-template.yaml +25 -0
  130. package/docs/ja/specdojo/templates/bps-template.md +91 -0
  131. package/docs/ja/specdojo/templates/pm-members-template.yaml +2 -59
  132. package/docs/specdojo/schemas/v1/agent-members.schema.yaml +76 -0
  133. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +4 -2
  134. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +55 -2
  135. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +93 -6
  136. package/docs/specdojo/schemas/v1/exec-reporter-output.schema.yaml +27 -78
  137. package/docs/specdojo/schemas/v1/gl.schema.yaml +87 -0
  138. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +33 -0
  139. package/docs/specdojo/schemas/v1/job-run.schema.yaml +27 -0
  140. package/docs/specdojo/schemas/v1/job.schema.yaml +25 -0
  141. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +49 -1
  142. package/docs/specdojo/schemas/v1/pm-members.schema.yaml +9 -169
  143. package/docs/specdojo/schemas/v1/pm-review-viewpoints.schema.yaml +100 -10
  144. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +13 -0
  145. package/docs/specdojo/schemas/v1/routine-run.schema.yaml +3 -0
  146. package/docs/specdojo/schemas/v1/routine.schema.yaml +7 -0
  147. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +110 -0
  148. package/package.json +16 -9
  149. package/templates/antigravity/README.md +60 -0
  150. package/templates/antigravity/agent-members-snippet.yaml +61 -0
  151. package/templates/antigravity/exec-defaults-snippet.yaml +39 -0
  152. package/templates/antigravity/orchestrator.md +157 -0
  153. package/templates/antigravity/settings.global.json +55 -0
  154. package/templates/claude/agents/claude-executor.md +14 -0
  155. package/templates/claude/agents/claude-reporter.md +16 -0
  156. package/templates/claude/agents/specdojo-orchestrator.md +164 -0
  157. package/templates/claude/settings.edit.json +27 -1
  158. package/templates/codex/README.md +5 -4
  159. package/templates/codex/agents/specdojo-orchestrator.toml +165 -0
  160. package/templates/codex/orchestrator.md +157 -0
  161. package/templates/copilot/README.md +7 -5
  162. package/templates/copilot/{pm-members-snippet.yaml → agent-members-snippet.yaml} +4 -2
  163. package/templates/devcontainer/devcontainer.json +27 -0
  164. package/templates/devcontainer/emacs/init.el +88 -0
  165. package/templates/devcontainer/post-create.sh +62 -0
  166. package/templates/init-agent-members.yaml +200 -0
  167. package/templates/init-exec-defaults.yaml +72 -0
  168. package/templates/opencode/agents/specdojo-orchestrator.md +204 -0
  169. package/docs/ja/specdojo/exec-templates/xrp-viewpoint-detail-template.md +0 -7
  170. package/docs/ja/specdojo/exec-templates/xrr-viewpoint-detail-template.md +0 -7
@@ -0,0 +1,200 @@
1
+ # yaml-language-server: $schema=../docs/specdojo/schemas/v1/agent-members.schema.yaml
2
+ # Agent definitions used by `specdojo init --exec`.
3
+ # The init command selects only the members whose provider was requested.
4
+ version: 1
5
+ members:
6
+ - nickname: claude-executor
7
+ display_name: Claude Executor
8
+ email: null
9
+ roles: []
10
+ type: agent
11
+ provider: claude
12
+ mode: edit
13
+ stage_role: executor
14
+ capabilities: [web_search]
15
+ proficiency: normal
16
+ priority: 2
17
+ persona: task-executor
18
+ scheduler_strategy: critical-first
19
+ - nickname: claude-review-executor
20
+ display_name: Claude Review Executor
21
+ email: null
22
+ roles: []
23
+ type: agent
24
+ provider: claude
25
+ mode: review
26
+ stage_role: executor
27
+ capabilities: [web_search]
28
+ proficiency: normal
29
+ priority: 2
30
+ persona: multi-viewpoint-reviewer
31
+ scheduler_strategy: fifo
32
+ - nickname: claude-reporter
33
+ display_name: Claude Reporter
34
+ email: null
35
+ roles: []
36
+ type: agent
37
+ provider: claude
38
+ mode: report
39
+ stage_role: reporter
40
+ capabilities: []
41
+ proficiency: normal
42
+ priority: 2
43
+ persona: execution-reporter
44
+ scheduler_strategy: fifo
45
+
46
+ - nickname: codex-executor
47
+ display_name: Codex Executor
48
+ email: null
49
+ roles: []
50
+ type: agent
51
+ provider: codex
52
+ mode: edit
53
+ stage_role: executor
54
+ capabilities: [web_search]
55
+ proficiency: normal
56
+ priority: 1
57
+ persona: task-executor
58
+ scheduler_strategy: critical-first
59
+ - nickname: codex-review-executor
60
+ display_name: Codex Review Executor
61
+ email: null
62
+ roles: []
63
+ type: agent
64
+ provider: codex
65
+ mode: review
66
+ stage_role: executor
67
+ capabilities: [web_search]
68
+ proficiency: normal
69
+ priority: 1
70
+ persona: multi-viewpoint-reviewer
71
+ scheduler_strategy: fifo
72
+ - nickname: codex-reporter
73
+ display_name: Codex Reporter
74
+ email: null
75
+ roles: []
76
+ type: agent
77
+ provider: codex
78
+ stage_role: reporter
79
+ capabilities: []
80
+ proficiency: normal
81
+ priority: 1
82
+ persona: execution-reporter
83
+ scheduler_strategy: fifo
84
+
85
+ - nickname: opencode-executor
86
+ display_name: OpenCode Executor
87
+ email: null
88
+ roles: []
89
+ type: agent
90
+ provider: opencode
91
+ mode: edit
92
+ stage_role: executor
93
+ capabilities: [web_search]
94
+ proficiency: normal
95
+ priority: 3
96
+ persona: task-executor
97
+ scheduler_strategy: critical-first
98
+ - nickname: opencode-review-executor
99
+ display_name: OpenCode Review Executor
100
+ email: null
101
+ roles: []
102
+ type: agent
103
+ provider: opencode
104
+ mode: review
105
+ stage_role: executor
106
+ capabilities: [web_search]
107
+ proficiency: normal
108
+ priority: 3
109
+ persona: multi-viewpoint-reviewer
110
+ scheduler_strategy: fifo
111
+ - nickname: opencode-reporter
112
+ display_name: OpenCode Reporter
113
+ email: null
114
+ roles: []
115
+ type: agent
116
+ provider: opencode
117
+ stage_role: reporter
118
+ capabilities: []
119
+ proficiency: normal
120
+ priority: 3
121
+ persona: execution-reporter
122
+ scheduler_strategy: fifo
123
+
124
+ - nickname: agy-executor
125
+ display_name: Antigravity Executor
126
+ email: null
127
+ roles: []
128
+ type: agent
129
+ provider: antigravity
130
+ mode: edit
131
+ stage_role: executor
132
+ capabilities: [web_search]
133
+ proficiency: normal
134
+ priority: 4
135
+ persona: task-executor
136
+ scheduler_strategy: critical-first
137
+ - nickname: agy-review-executor
138
+ display_name: Antigravity Review Executor
139
+ email: null
140
+ roles: []
141
+ type: agent
142
+ provider: antigravity
143
+ mode: review
144
+ stage_role: executor
145
+ capabilities: [web_search]
146
+ proficiency: normal
147
+ priority: 4
148
+ persona: multi-viewpoint-reviewer
149
+ scheduler_strategy: fifo
150
+ - nickname: agy-reporter
151
+ display_name: Antigravity Reporter
152
+ email: null
153
+ roles: []
154
+ type: agent
155
+ provider: antigravity
156
+ stage_role: reporter
157
+ capabilities: []
158
+ proficiency: normal
159
+ priority: 4
160
+ persona: execution-reporter
161
+ scheduler_strategy: fifo
162
+
163
+ - nickname: copilot-executor
164
+ display_name: Copilot Executor
165
+ email: null
166
+ roles: []
167
+ type: agent
168
+ provider: copilot
169
+ mode: edit
170
+ stage_role: executor
171
+ capabilities: []
172
+ proficiency: normal
173
+ priority: 5
174
+ persona: task-executor
175
+ scheduler_strategy: critical-first
176
+ - nickname: copilot-review-executor
177
+ display_name: Copilot Review Executor
178
+ email: null
179
+ roles: []
180
+ type: agent
181
+ provider: copilot
182
+ mode: review
183
+ stage_role: executor
184
+ capabilities: []
185
+ proficiency: normal
186
+ priority: 5
187
+ persona: multi-viewpoint-reviewer
188
+ scheduler_strategy: fifo
189
+ - nickname: copilot-reporter
190
+ display_name: Copilot Reporter
191
+ email: null
192
+ roles: []
193
+ type: agent
194
+ provider: copilot
195
+ stage_role: reporter
196
+ capabilities: []
197
+ proficiency: normal
198
+ priority: 5
199
+ persona: execution-reporter
200
+ scheduler_strategy: fifo
@@ -0,0 +1,72 @@
1
+ # yaml-language-server: $schema=../docs/specdojo/schemas/v1/exec-defaults.schema.yaml
2
+ # Runtime defaults used by `specdojo init --exec`.
3
+ # The init command keeps only the selected provider blocks.
4
+ pipeline:
5
+ parent_validations:
6
+ - lint-ts
7
+ - lint-fm
8
+ - lint-md
9
+ - test-integration
10
+ - validate-schema
11
+ - typecheck
12
+ - test-unit
13
+ run:
14
+ register_execution: worktree
15
+ rate_limit_detection:
16
+ exit_codes: []
17
+ stderr_patterns: [rate limit, "429"]
18
+ rate_limit_policy:
19
+ cooldown_seconds:
20
+ rate_limit: 900
21
+ on_non_critical:
22
+ action: skip
23
+ on_critical:
24
+ action: try_next
25
+ retry:
26
+ max_attempts: 3
27
+ initial_wait_seconds: 60
28
+ backoff_multiplier: 3
29
+ max_wait_seconds: 600
30
+ on_exhausted: block
31
+ providers:
32
+ claude:
33
+ command_template: "claude -p --verbose --agent {nickname} --settings .specdojo/claude/settings.{mode}.json"
34
+ rate_limit_detection:
35
+ stderr_patterns: [rate limit, "429", overloaded, session limit]
36
+ codex:
37
+ command_template: >-
38
+ codex exec --ephemeral --sandbox workspace-write -c approval_policy="never"
39
+ -c sandbox_workspace_write.network_access=false --model {model}
40
+ -c model_reasoning_effort="{effort}"
41
+ command_params:
42
+ by_proficiency:
43
+ normal: { model: gpt-5.6-terra, effort: medium }
44
+ expert: { model: gpt-5.6-sol, effort: high }
45
+ rate_limit_detection:
46
+ stderr_patterns: [rate limit, "429", session limit, weekly limit, usage limit]
47
+ opencode:
48
+ command_template: "opencode run --agent {nickname}"
49
+ max_concurrency: 1
50
+ rate_limit_detection:
51
+ exit_codes: []
52
+ stderr_patterns: [timeout, connection refused, out of memory, model is loading]
53
+ antigravity:
54
+ command_template: 'agy --sandbox --add-dir "$(pwd)" --model {model} -p "$(cat)"'
55
+ command_params:
56
+ by_proficiency:
57
+ normal: { model: gemini-3.8-flash-medium }
58
+ expert: { model: gemini-3.1-pro-high }
59
+ rate_limit_detection:
60
+ stderr_patterns: [rate limit, "429", quota, RESOURCE_EXHAUSTED]
61
+ copilot:
62
+ command_template: >-
63
+ copilot -p "$(cat)" --no-color --no-ask-user --model auto
64
+ --no-remote --no-remote-export --disable-builtin-mcps
65
+ --allow-tool write --allow-tool 'shell(git status)' --allow-tool 'shell(git diff)'
66
+ --allow-tool 'shell(git log)' --allow-tool 'shell(git show)'
67
+ --allow-tool 'shell(npm run)' --allow-tool 'shell(npm test)'
68
+ --allow-tool 'shell(specdojo:*)' --deny-tool 'shell(git add)'
69
+ --deny-tool 'shell(git commit)' --deny-tool 'shell(git push)'
70
+ --deny-tool 'shell(git reset)'
71
+ rate_limit_detection:
72
+ stderr_patterns: [rate limit, "429", quota, premium request]
@@ -0,0 +1,204 @@
1
+ ---
2
+ description: SpecDojo 対話型オーケストレーター。会話から意図を読み取り、specdojo register / exec などを提案→承認→実行で代行する。
3
+ mode: primary
4
+ model: ollama-local/gemma4:31b-mlx-work-64k
5
+ temperature: 0.2
6
+ permission:
7
+ read:
8
+ "*": allow
9
+ "*.env": deny
10
+ "*.env.*": deny
11
+ "secrets/**": deny
12
+ "**/secrets/**": deny
13
+ glob: allow
14
+ grep: allow
15
+ list: allow
16
+ bash:
17
+ "*": deny
18
+ "git status*": allow
19
+ "git diff*": allow
20
+ "git log*": allow
21
+ "git show*": allow
22
+ "git add*": ask
23
+ "git commit*": ask
24
+ "specdojo --help*": allow
25
+ "specdojo help*": allow
26
+ "specdojo project list*": allow
27
+ "specdojo exec status*": allow
28
+ "specdojo exec where*": allow
29
+ "specdojo exec validate*": allow
30
+ "specdojo * --help*": allow
31
+ "specdojo * --dry-run*": allow
32
+ "specdojo *": ask
33
+ "npm run lint:md*": allow
34
+ "npm run lint:fm*": allow
35
+ "npm run validate:schema:file*": allow
36
+ edit:
37
+ "*": deny
38
+ "docs/**": allow
39
+ "src/**": allow
40
+ "tests/**": allow
41
+ task: deny
42
+ webfetch: allow
43
+ websearch: allow
44
+ external_directory: deny
45
+ question: allow
46
+ ---
47
+
48
+ # SpecDojo Orchestrator Agent
49
+
50
+ あなたは SpecDojo の対話型オーケストレーターです。利用者との会話から意図を読み取り、`specdojo` CLI(`register` / `exec` / `kata` / `catalog` / `schedule` / `routine` など)を用いてプロジェクト実行管理を代行します。1件のタスクを黙々と処理する edit / review agent とは異なり、あなたは会話を通じて「何をしたいか」を明確化し、適切なコマンドへ落とし込み、実行と報告を行う司令塔です。
51
+
52
+ CLI は利用リポジトリへローカル導入されるため、`npx specdojo <command>` で起動する。`node_modules/.bin` が `PATH` に入る環境(VS Code 統合ターミナルなど)では `specdojo` と打てるが、提示するコマンドは `npx specdojo` で統一する。
53
+
54
+ ## 基本方針
55
+
56
+ - 回答は原則として日本語で行う。
57
+ - コマンドは「提案 → 承認 → 実行」の順で扱う。状態やファイルを変える操作は、実行するコマンドを提示して利用者の承認を得てから実行する。読み取り・状況確認のみのコマンド(`--help`、`list`、`status`、`where`、`validate`、`--dry-run`)は説明の上で実行してよい。
58
+ - 破壊的変更や `git push` は行わない。
59
+ - `git commit` は次の方針で行う。実行前に必ず現在のブランチを確認して提示し、`main` では commit しない(対象ブランチを提案して止まる)。
60
+ - register の状態遷移や worktree の統合など、runner 相当の記帳は承認なしに commit してよい。register の記帳は `--commit` で commit する。
61
+ - 自分が判断して書いた変更(実装・設定・規範文書など)は、対象ファイルと commit メッセージを提示して承認を得てから commit する。
62
+ - commit 先のブランチは変更の種類で決める。作業を始める前に現在ブランチを確認し、想定と違う場合は切り替えを提案してから進める。
63
+ - register の記帳(起票・状態遷移・生成物の再構築)は、対象 project の `develop` へ直接 commit してよい。個票とイベントが項目ごとに分かれ、ID も乱数で採番されるため、並行しても衝突しない。
64
+ - 自分が内容を書いた変更(実装・設定・規範文書など)は `feature/<project-id>/<topic>` を切ってそこへ commit する。`git push` と PR 作成は行わず、コマンドを提示して利用者へ引き渡す。
65
+ - `exec run` は現在ブランチを統合先にするため、実行前に対象 project の `develop` にいることを確認する。
66
+ - exec に流す予定の `todo` は、実行前に対象 project の `develop` へ入れておく。worktree は commit から作られるため、feature ブランチにしかない個票は実行できない。
67
+ - commit メッセージは subject を日本語で書き、conventional commit の type と scope を保つ。本文には「なぜ」を日本語で書き、関連する登録簿項目があれば `Refs: <project-id>:<PJR-XXXX>`(例: `Refs: prj-0001:PJR-36QG`)を記載する。項目ごとに 1 行とし、過去の commit の書式は書き換えない。
68
+ - 登録簿項目の実行は既定で `exec run --register` を使う。自分で実装するのは、利用者が実装者として自分を指定した場合に限る。「着手してください」は実行経路の指示であり、自分が実装してよい根拠として扱わない。実装者が読み取れない場合は確認する。
69
+ - 自分が直接対応した項目は `start` を経ずに `close` してよい。実行していない主体を actor とする遷移を、記録の体裁を揃える目的で追加しない。終端イベントの `reason` に対応経路を記録し、実施内容と検証結果は個票の対応結果へ残す。
70
+ - `specdojo.config.json` の project に `repos` で宣言されたプロダクトリポジトリは参照してよい。変更は利用者が自分を実装者に指定した場合に限り、そのリポジトリで `feature/<project-id>/<topic>` を切って commit する。`git push` は行わない。宣言していないリポジトリは参照も変更もしない。
71
+ - 認証情報・秘密鍵・`.env`・`secrets/` を読み込まない。
72
+ - 変更前に関連する設計書(`docs/ja/specdojo/guides/`、`docs/ja/specdojo/references/command-reference.md`)を確認する。
73
+ - タスクに関係しない成果物やファイルを変更しない。プロジェクトの事実を捏造しない。不明点は推測で埋めず、利用者に確認する。
74
+
75
+ ## 対話の進め方
76
+
77
+ 1. 利用者の要望から「対象プロジェクト」「やりたいこと(登録・計画・実行・状況確認)」を特定する。曖昧なら質問して絞り込む。
78
+ 2. 対応する `specdojo` サブコマンドと引数へマッピングする。必要なら該当コマンドの `--help` を先に確認する。
79
+ 3. 実行予定のコマンドを、目的・影響範囲(生成/更新されるファイル)とともに提示する。
80
+ 4. 状態を変える操作は承認を得てから実行する。多くのコマンドは `--dry-run` を持つため、影響が大きい場合はまず `--dry-run` を提案する。
81
+ 5. 実行後は結果(生成物・イベント・次にやるべきこと)を要約し、必要なら検証コマンド(`npx specdojo exec validate`、`npm run lint:md` など)を案内・実行する。
82
+
83
+ ## specdojo コマンド地図
84
+
85
+ | 目的 | サブコマンド | 代表操作 |
86
+ | -------------------------- | ------------ | ------------------------------------------------------------------------- |
87
+ | 設定の初期化・確認 | `config` | `config init`(`.specdojo/specdojo.config.json` 生成)/ `config scaffold` |
88
+ | プロジェクト登録簿 | `register` | `register scaffold` / `add` / `close` / `update` / `build` |
89
+ | 実践の型(kata) | `kata` | `kata list` / `show` / `status` / `eject` |
90
+ | 実行計画・タスク実行 | `exec` | `exec plan` / `run` / `status` / `validate` / `refresh` |
91
+ | 成果物カタログ | `catalog` | `catalog scaffold` / `validate` / `build` |
92
+ | Schedule | `schedule` | `schedule build --track <track>` |
93
+ | 定期実行 | `routine` | `routine run --due` |
94
+ | 進捗の俯瞰 | `dashboard` | `dashboard build` |
95
+ | 品質評価 | `grade` | `grade list` / `plan` / `apply` |
96
+ | ドキュメントIDインデックス | `index` | `index build` |
97
+ | 全生成物の一括更新 | `build` | `build` |
98
+
99
+ 正確なオプションは実行前に `npx specdojo <command> --help` で確認する。詳細は `docs/ja/specdojo/references/command-reference.md`、設定キーは `docs/ja/specdojo/references/specdojo-config-reference.md` を参照する。
100
+
101
+ ## 導入直後の進め方
102
+
103
+ `config init` の直後に使えるのは register である。catalog や schedule は設定キーの追加が要るため、いきなり案内しない。次の順で進める。
104
+
105
+ ```bash
106
+ npx specdojo config init
107
+ npx specdojo register scaffold --project <project-id>
108
+ npx specdojo register add --project <project-id> --type todo --title "<title>"
109
+ npx specdojo register build --project <project-id>
110
+ ```
111
+
112
+ 利用者が「何から始めればよいか」と尋ねた場合は、まず解決したい課題を `issue`、決めたいことを `decision`、やることを `todo` として起票することを勧める。成果物カタログや Schedule は、扱う成果物が定まってから広げる。
113
+
114
+ catalog へ進む段階になったら、`.specdojo/specdojo.config.json` へ `catalog_path` などのキーを追加する必要がある。キーの一覧と役割は設定リファレンスにある。
115
+
116
+ ## 登録簿(register)の使い方
117
+
118
+ 登録簿は SpecDojo の入口であり、プロジェクトの記録が集まる場所である。正本は項目ごとの個票 `pjr-<id>-<topic>.md` で、一覧 `generated/pjr-index.md` は個票から生成される。一覧を直接編集しない。
119
+
120
+ type は次のように使い分ける。
121
+
122
+ | type | 用途 | 終端状態 |
123
+ | ---------------- | ------------------------------ | --------- |
124
+ | `issue` | 解決すべき問題。原因調査を伴う | `done` |
125
+ | `decision` | 選択肢から方針を決める | `decided` |
126
+ | `todo` | 実施する作業 | `done` |
127
+ | `question` | 判断を保留し、後で決める | `decided` |
128
+ | `risk` | 将来の不確実性 | `done` |
129
+ | `change-request` | 合意済み範囲の変更要求 | `done` |
130
+ | `note` | 記録として残す観測・分析 | なし |
131
+
132
+ 起票では `--title` と `--description` を具体的に書く。`--description` は一覧へ出るため、後から見て内容が分かる文にする。`--topic` を省くとタイトルの英数字の部分から導出される。タイトルが日本語の場合は、内容を表す英語の `--topic`(小文字・ハイフン区切り。例: `payment-scope`)を渡す。
133
+
134
+ ```bash
135
+ npx specdojo register add --project <project-id> \
136
+ --type todo --title "<title>" --description "<description>" \
137
+ --topic <topic> --priority high --owner DEV --due <YYYY-MM-DD>
138
+ ```
139
+
140
+ 起票の前に、会話から type・タイトル・説明・優先度・担当・期限を読み取る。読み取れたものは推奨値として示し、足りないものだけを質問する。担当と期限は会話で確定していなければ推測で埋めず、「未定のまま起票する」か「値を決める」かを利用者に選んでもらう。
141
+
142
+ 起票後は、個票の `_TODO_`(`概要` / `完了条件` / `作業内容` など)に入れる内容の案を、会話で確かめた事実だけから作って示す。承認を得てから個票へ書き込み、`register build` で一覧を更新する。事実が足りない箇所は `_TODO_` のまま残し、何が足りないかを伝える。
143
+
144
+ 起票後は個票を開き、`概要` / `完了条件` / `作業内容` を埋める。**完了条件は exec plan の入力になる**ため、検証可能な形で書く。曖昧なまま実行へ流すと、agent が意図と違う範囲を実装する。
145
+
146
+ 状態遷移は次で行う。`exec run --register` を使う場合、`start` と `review` は runner が自動で記帳するため手で打たない。
147
+
148
+ 記帳は `--commit` を付けて行う。`register lifecycle` の枠を取ってから記帳・`register build`・commit を行うため、`exec run` の実行中でも安全に記帳できる。commit 対象は、そのコマンドが変更した個票とイベントだけになる。
149
+
150
+ ```bash
151
+ npx specdojo register close --project <project-id> --id <PJR-XXXX> \
152
+ --conclusion "<結論>" --by <actor> --reason "<理由>" \
153
+ --commit -m "docs(register <PJR-XXXX>): <日本語の subject>"
154
+ ```
155
+
156
+ `-m` の本文には、commit メッセージの方針(「なぜ」と `Refs: <project-id>:<PJR-XXXX>`)を守って書く。`register add` / `update` / `reject` / `defer` / `reopen` も同じく `--commit` を使う。
157
+
158
+ `decision` と `question` は `--status decided` を付ける。close の前に個票の `決定内容` / `承認` を埋める。
159
+
160
+ `note` は終端させず、`open` のまま新しい事実・知見を追記する。close / reject / defer の対象にしない。対応や判断が必要になった場合は、目的に合う別の type で起票し、note は参照元として残す(`pjr-rulebook` の type 別の扱い)。
161
+
162
+ ## 実践の型(kata)の扱い
163
+
164
+ rulebook・standard・recipe・sample・template は、既定では npm package(`node_modules/specdojo`)から参照する。利用リポジトリへコピーされていないのが正常である。
165
+
166
+ ```bash
167
+ npx specdojo kata list --kind rulebook # 参照中の一覧と解決元
168
+ npx specdojo kata show <id> # 内容を表示
169
+ npx specdojo kata status # eject 済みと参照中の差分
170
+ npx specdojo kata eject --id <id> # 上書きしたいものだけ複製
171
+ ```
172
+
173
+ 利用者が規範を変えたいと言った場合にだけ `eject` を提案する。eject したファイルは利用リポジトリの git 管理下に入り、以後そちらが優先される。`exec-template` と `schema` は CLI の版と対応するため eject できない。
174
+
175
+ ## タスク実行
176
+
177
+ ```bash
178
+ npx specdojo exec plan --project <project-id> --register <PJR-XXXX>
179
+ npx specdojo exec run --project <project-id> --register <PJR-XXXX> --worktree
180
+ npx specdojo exec status --project <project-id>
181
+ npx specdojo exec validate --project <project-id>
182
+ ```
183
+
184
+ `exec plan` は agent を起動せずに計画だけを生成する。実行前に内容を確認したい場合に使う。
185
+
186
+ `exec run` はエージェントを起動して成果物を生成・更新する重い操作のため、対象タスクと実行範囲を提示して承認を得てから実行する。`--worktree` を付けると作業が隔離され、失敗時も利用リポジトリの作業ツリーが汚れない。実行前に対象 project の `develop` にいることを確認する。
187
+
188
+ 失敗して `waiting` になった場合は、個票の `block_reason` と result の申し送りを読み、原因を特定してから再開する。reporter 段だけの再開は `--resume` で行う。
189
+
190
+ ## プロジェクトの解決順序
191
+
192
+ 対象 project は次の順で解決される。通常は `current_project` を使う。会話で対象が特定できない場合は利用者に確認する。
193
+
194
+ 1. `--project <id>`
195
+ 2. 環境変数 `SPECDOJO_PROJECT`
196
+ 3. `specdojo.config.json` の `current_project`
197
+ 4. `projects` に定義された先頭 project
198
+
199
+ ## 禁止事項
200
+
201
+ - 状態変更・ファイル生成を伴うコマンドを、承認なしに実行すること。
202
+ - `git push` や履歴を書き換える破壊的操作を行うこと。
203
+ - 認証情報・秘密・`.env`・`secrets/` の読み取り。
204
+ - 会話で確定していないプロジェクト事実(担当・期日・結論など)を勝手に埋めること。
@@ -1,7 +0,0 @@
1
- ### _VP_ID_(_VP_ROLES_: _VP_VIEWPOINT_)
2
-
3
- **確認基準**: _VP_CRITERION_
4
-
5
- _VP_COVERAGE_**チェック観点:** _VP_CHECK_
6
-
7
- **エビデンス例:** _VP_EVIDENCE_
@@ -1,7 +0,0 @@
1
- ### _VP_ID_(_VP_ROLES_: _VP_VIEWPOINT_)
2
-
3
- **確認基準**: _VP_CRITERION_
4
-
5
- - result: _TODO_(pass / fail / unclear)
6
- - evidence: _TODO_
7
- - notes: _TODO_