specdojo 0.4.4 → 0.4.6
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 +4 -4
- package/CHANGELOG.md +31 -0
- package/dist/commands/init.js +33 -7
- package/dist/devcontainer/scaffold.js +5 -1
- package/dist/exec/evidence.js +35 -3
- package/dist/exec/pipeline-state.js +1 -0
- package/dist/exec/plans-core.js +18 -2
- package/dist/exec/plans-generation.js +1 -1
- package/dist/exec/register-resume.js +8 -4
- package/dist/exec/register.js +47 -14
- package/dist/exec/reporter.js +8 -1
- package/dist/exec/results.js +1 -1
- package/dist/exec/run/agent-pipeline.js +7 -5
- package/dist/exec/run/agent.js +14 -1
- package/dist/exec/run/in-place.js +7 -4
- package/dist/exec/run/register-core.js +10 -2
- package/dist/exec/run/register-resume.js +1 -0
- package/dist/exec/run/register-worktree.js +7 -1
- package/dist/exec/task-repos.js +11 -0
- package/dist/exec/worktree-ops-lifecycle.js +4 -2
- package/dist/kata/command.js +54 -9
- package/dist/register/approach.js +13 -12
- package/dist/register/authoring-sources.js +132 -0
- package/dist/register/core.js +1 -0
- package/dist/register/create-commands.js +84 -15
- package/dist/register/events.js +2 -0
- package/dist/register/external-project.js +29 -8
- package/dist/register/item.js +6 -0
- package/dist/register/renumber.js +3 -3
- package/dist/register/views.js +3 -0
- package/dist/shared/git.js +3 -2
- package/dist/shared/lefthook-scaffold.js +5 -22
- package/dist/shared/markdownlint-scaffold.js +67 -0
- package/dist/shared/provider-scaffold.js +2 -2
- package/dist/shared/slidev-scaffold.js +102 -0
- package/dist/shared/specdojo-config.js +9 -3
- package/docs/ja/specdojo/exec-templates/xep-recipe-authoring-template.md +7 -7
- package/docs/ja/specdojo/exec-templates/xep-register-template.md +5 -4
- package/docs/ja/specdojo/exec-templates/xep-rulebook-authoring-template.md +7 -7
- package/docs/ja/specdojo/exec-templates/xep-sample-authoring-template.md +7 -7
- package/docs/ja/specdojo/exec-templates/xep-template-authoring-template.md +7 -7
- package/docs/ja/specdojo/guides/exec-config-guide.md +46 -16
- package/docs/ja/specdojo/guides/kata-guide.md +111 -2
- package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +6 -6
- package/docs/ja/specdojo/guides/quick-start-guide.md +4 -2
- package/docs/ja/specdojo/guides/register-operation-guide.md +2 -0
- package/docs/ja/specdojo/references/command-reference.md +155 -59
- package/docs/ja/specdojo/references/specdojo-config-reference.md +2 -0
- package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +17 -1
- package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +4 -3
- package/docs/specdojo/schemas/v1/exec-result-frontmatter.schema.yaml +3 -3
- package/docs/specdojo/schemas/v1/register-events.schema.yaml +1 -0
- package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +31 -3
- package/package.json +8 -7
- package/templates/antigravity/orchestrator.md +4 -4
- package/templates/claude/README.md +2 -0
- package/templates/claude/agents/specdojo-orchestrator.md +4 -4
- package/templates/codex/README.md +38 -9
- package/templates/codex/agents/codex-executor.toml +1 -1
- package/templates/codex/agents/codex-expert-executor.toml +1 -1
- package/templates/codex/agents/codex-expert-review-executor.toml +1 -1
- package/templates/codex/agents/codex-review-executor.toml +1 -1
- package/templates/codex/agents/specdojo-orchestrator.toml +5 -5
- package/templates/codex/orchestrator.md +4 -4
- package/templates/init-agent-members.yaml +85 -13
- package/templates/opencode/agents/specdojo-orchestrator.md +4 -4
|
@@ -6,6 +6,7 @@ import Ajv2020Module from "ajv/dist/2020.js";
|
|
|
6
6
|
import { runProviderScaffold, specdojoPackageRootDir } from "./provider-scaffold.js";
|
|
7
7
|
import { runWorkspaceScaffold } from "./workspace-scaffold.js";
|
|
8
8
|
import { runLefthookScaffold } from "./lefthook-scaffold.js";
|
|
9
|
+
import { runSlidevScaffold, SLIDEV_KATA_PATTERNS } from "./slidev-scaffold.js";
|
|
9
10
|
import { ensureGitignore, formatGitignoreReport, gitignorePatternsForLayouts, } from "./specdojo-gitignore.js";
|
|
10
11
|
/** Default IANA time zone for register date derivation when run.register_date_timezone is unset. */
|
|
11
12
|
export const DEFAULT_REGISTER_DATE_TIMEZONE = "UTC";
|
|
@@ -786,18 +787,19 @@ export function registerConfigCommands(program) {
|
|
|
786
787
|
});
|
|
787
788
|
cfg
|
|
788
789
|
.command("scaffold")
|
|
789
|
-
.description("Scaffold provider settings, a VS Code multi-root workspace,
|
|
790
|
+
.description("Scaffold provider settings, a VS Code multi-root workspace, Git hooks, or Slidev")
|
|
790
791
|
.option("--provider <name>", "Provider template to copy (antigravity|claude|codex|copilot|opencode)")
|
|
791
792
|
.option("--workspace", "Generate VS Code multi-root workspace (<project-id>.code-workspace) from repos config", false)
|
|
792
793
|
.option("--lefthook", "Generate pre-commit hooks for SpecDojo repositories", false)
|
|
794
|
+
.option("--slidev", "Set up Slidev and formatting for kata", false)
|
|
793
795
|
.option("--project <id>", "Target project ID for workspace scaffolding (defaults to current_project)")
|
|
794
796
|
.option("--force", "Overwrite existing files", false)
|
|
795
797
|
.option("--dry-run", "Show planned files without writing", false)
|
|
796
798
|
.option("--global", "Merge provider permissions into user-level settings (currently antigravity only)", false)
|
|
797
799
|
.action(async (opts) => {
|
|
798
800
|
try {
|
|
799
|
-
if (!opts.provider && !opts.workspace && !opts.lefthook) {
|
|
800
|
-
throw new Error("Specify --provider <name>, --workspace, or --
|
|
801
|
+
if (!opts.provider && !opts.workspace && !opts.lefthook && !opts.slidev) {
|
|
802
|
+
throw new Error("Specify --provider <name>, --workspace, --lefthook, or --slidev to scaffold.");
|
|
801
803
|
}
|
|
802
804
|
if (opts.global && !opts.provider) {
|
|
803
805
|
throw new Error("--global requires --provider antigravity");
|
|
@@ -828,10 +830,14 @@ export function registerConfigCommands(program) {
|
|
|
828
830
|
packageRoot: specdojoPackageRootDir(),
|
|
829
831
|
repoRoot: specdojoRootDir(),
|
|
830
832
|
config,
|
|
833
|
+
slidevKataPatterns: opts.slidev ? SLIDEV_KATA_PATTERNS : [],
|
|
831
834
|
force: !!opts.force,
|
|
832
835
|
dryRun: !!opts.dryRun,
|
|
833
836
|
});
|
|
834
837
|
}
|
|
838
|
+
if (opts.slidev) {
|
|
839
|
+
await runSlidevScaffold({ repoRoot: specdojoRootDir(), dryRun: !!opts.dryRun });
|
|
840
|
+
}
|
|
835
841
|
}
|
|
836
842
|
catch (error) {
|
|
837
843
|
const message = error instanceof Error ? error.message : String(error);
|
|
@@ -14,21 +14,21 @@ _PHASE_DESCRIPTION_
|
|
|
14
14
|
- 記述標準: [[_AUTHORING_STANDARD_ID_|執筆標準]](`_AUTHORING_STANDARD_PATH_`)
|
|
15
15
|
- result: `_RESULT_REF_`
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
手本にするファイル:
|
|
18
18
|
|
|
19
19
|
_AUTHORING_EXEMPLARS_
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
手本ファイルは読み取り専用であり、プロジェクトリポジトリとプロダクトリポジトリのどちらにあっても変更しない。手本がない場合は、記述標準と対象領域の慣行だけを根拠に実践の型を作る。
|
|
22
22
|
|
|
23
23
|
## 3. 進め方
|
|
24
24
|
|
|
25
|
-
1.
|
|
25
|
+
1. 記述標準と手本ファイルを実際に読み、複数の成果物に再利用できる規則・問い・完成例・雛形を抽出する。
|
|
26
26
|
2. `_AUTHORING_KATA_PATH_` に `_AUTHORING_KATA_ID_` を持つ `_AUTHORING_KATA_KIND_` を新規作成する。frontmatter の `status` は `draft` とし、`ready` へ変更しない。
|
|
27
27
|
3. 手本の内容を丸写しせず、プロジェクト固有の値を一般化する。手本同士が矛盾する場合は、共通部分と差異を分け、判断できない点を result の申し送りへ記録する。
|
|
28
|
-
4.
|
|
29
|
-
5.
|
|
28
|
+
4. 手本のうち成果物カタログに載っているものだけ、作った種類の参照が `undecided` または未記入なら `_AUTHORING_KATA_ID_` へ更新する。カタログ外の文書とプロダクトリポジトリのファイルは読み取り専用の手本にとどめ、参照を付け替えない。rulebook は成果物カタログの `rulebook`、recipe / sample / template は成果物が参照する rulebook frontmatter の同名フィールドを正本とする。
|
|
29
|
+
5. カタログ成果物の参照がすでに別の kata を指す場合は上書きせず、その成果物 ID・既存参照・新しい kata ID を result の申し送りへ記録する。`not-needed` も意図的な判断として上書きしない。
|
|
30
30
|
recipe / sample / template の作成時に、手本の rulebook 自体が `undecided`・未記入・`not-needed` で参照先を記録できない場合は、別種の kata を同時作成せず、付け替え不能として result へ記録する。
|
|
31
|
-
6. 新しい kata
|
|
31
|
+
6. 新しい kata と参照の更新だけを変更対象とし、手本ファイルは変更しない。
|
|
32
32
|
|
|
33
33
|
## 4. 完了手順
|
|
34
34
|
|
|
@@ -39,7 +39,7 @@ _AUTHORING_EXEMPLARS_
|
|
|
39
39
|
## 5. 異常終了の条件
|
|
40
40
|
|
|
41
41
|
- 新しい id が既に存在する、対象種別と id の末尾が一致しない、手本を解決できない、または検査が未解消の場合は異常終了する。
|
|
42
|
-
-
|
|
42
|
+
- 手本ファイル(プロダクトリポジトリを含む)へ変更が生じた場合は元に戻し、commit の対象に含めない。解消できなければ異常終了する。
|
|
43
43
|
- agent 自身は登録簿の状態を変更しない。
|
|
44
44
|
|
|
45
45
|
_COMMON_CONVENTIONS_
|
|
@@ -21,16 +21,17 @@ _PJR_DESCRIPTION_
|
|
|
21
21
|
## 3. 進め方
|
|
22
22
|
|
|
23
23
|
1. 個票(存在する場合)を読み、目的・完了条件・制約を把握する。登録簿の一覧は大きいため読まない。
|
|
24
|
-
2.
|
|
24
|
+
2. 個票に完了条件がある場合はそれを作業の基準にする。無い場合はタイトルと説明から完了条件の仮説を立て、記録する。pipeline では個票の対応結果と executor の報告の `handoff` に書き、result を直接書ける実行形式では result に明記する。
|
|
25
25
|
3. 関連する成果物・設計書・実装を確認し、対象ファイルを特定して変更する。
|
|
26
26
|
4. 個票が存在する場合は、個票の作業内容・対応結果セクションを実施内容で更新する。
|
|
27
|
-
5.
|
|
27
|
+
5. 個票の完了条件が result への記載を求める場合、pipeline の executor は個票の対応結果と報告の `handoff` の両方に書く。reporter と runner が result の申し送りへ反映する。executor は result を直接編集しない。
|
|
28
|
+
6. 判断に迷う箇所は _TODO_ / _ASSUMPTION_ で残し、根拠と次のアクションを記録する。pipeline では個票の対応結果と報告の `handoff` に書き、result を直接書ける実行形式では result に書く。
|
|
28
29
|
|
|
29
30
|
### grade result から展開された finding
|
|
30
31
|
|
|
31
32
|
_GRADE_FINDINGS_
|
|
32
33
|
|
|
33
|
-
plan に展開された finding は、message と同じ viewpoint ID
|
|
34
|
+
plan に展開された finding は、message と同じ viewpoint ID の判定根拠に照らして解消する。未解消、根拠不足、または判断不能の場合は、理由と次のアクションを記録する。pipeline では個票の対応結果と報告の `handoff` に書き、result を直接書ける実行形式では result に書く。grade result サイドカーは再評価時に更新されるため、本タスクでは直接編集しない。
|
|
34
35
|
|
|
35
36
|
_AUTOPILOT_CONSTRAINTS_
|
|
36
37
|
|
|
@@ -38,7 +39,7 @@ _AUTOPILOT_CONSTRAINTS_
|
|
|
38
39
|
|
|
39
40
|
1. 「進め方」に従って対応を完了する。
|
|
40
41
|
2. 共通規約に従って、必要な整形・静的検査を実行する。
|
|
41
|
-
3. result
|
|
42
|
+
3. result に実施内容・変更ファイル・申し送りを記入する。pipeline では executor は実施内容・変更ファイル・検証結果を報告し、申し送りを `handoff` に記載する。reporter と runner が result を記入する。これはタスク完了に必須であり、_TODO_ を残したまま終了しない(詳細は共通規約を参照)。
|
|
42
43
|
4. 登録簿(`pjr-index.md`)の行と個票のステータス項目は変更しない。状態遷移(review / close など)は runner と人間が行う。
|
|
43
44
|
|
|
44
45
|
## 5. 異常終了の条件
|
|
@@ -14,21 +14,21 @@ _PHASE_DESCRIPTION_
|
|
|
14
14
|
- 記述標準: [[_AUTHORING_STANDARD_ID_|執筆標準]](`_AUTHORING_STANDARD_PATH_`)
|
|
15
15
|
- result: `_RESULT_REF_`
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
手本にするファイル:
|
|
18
18
|
|
|
19
19
|
_AUTHORING_EXEMPLARS_
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
手本ファイルは読み取り専用であり、プロジェクトリポジトリとプロダクトリポジトリのどちらにあっても変更しない。手本がない場合は、記述標準と対象領域の慣行だけを根拠に実践の型を作る。
|
|
22
22
|
|
|
23
23
|
## 3. 進め方
|
|
24
24
|
|
|
25
|
-
1.
|
|
25
|
+
1. 記述標準と手本ファイルを実際に読み、複数の成果物に再利用できる規則・問い・完成例・雛形を抽出する。
|
|
26
26
|
2. `_AUTHORING_KATA_PATH_` に `_AUTHORING_KATA_ID_` を持つ `_AUTHORING_KATA_KIND_` を新規作成する。frontmatter の `status` は `draft` とし、`ready` へ変更しない。
|
|
27
27
|
3. 手本の内容を丸写しせず、プロジェクト固有の値を一般化する。手本同士が矛盾する場合は、共通部分と差異を分け、判断できない点を result の申し送りへ記録する。
|
|
28
|
-
4.
|
|
29
|
-
5.
|
|
28
|
+
4. 手本のうち成果物カタログに載っているものだけ、作った種類の参照が `undecided` または未記入なら `_AUTHORING_KATA_ID_` へ更新する。カタログ外の文書とプロダクトリポジトリのファイルは読み取り専用の手本にとどめ、参照を付け替えない。rulebook は成果物カタログの `rulebook`、recipe / sample / template は成果物が参照する rulebook frontmatter の同名フィールドを正本とする。
|
|
29
|
+
5. カタログ成果物の参照がすでに別の kata を指す場合は上書きせず、その成果物 ID・既存参照・新しい kata ID を result の申し送りへ記録する。`not-needed` も意図的な判断として上書きしない。
|
|
30
30
|
recipe / sample / template の作成時に、手本の rulebook 自体が `undecided`・未記入・`not-needed` で参照先を記録できない場合は、別種の kata を同時作成せず、付け替え不能として result へ記録する。
|
|
31
|
-
6. 新しい kata
|
|
31
|
+
6. 新しい kata と参照の更新だけを変更対象とし、手本ファイルは変更しない。
|
|
32
32
|
|
|
33
33
|
## 4. 完了手順
|
|
34
34
|
|
|
@@ -39,7 +39,7 @@ _AUTHORING_EXEMPLARS_
|
|
|
39
39
|
## 5. 異常終了の条件
|
|
40
40
|
|
|
41
41
|
- 新しい id が既に存在する、対象種別と id の末尾が一致しない、手本を解決できない、または検査が未解消の場合は異常終了する。
|
|
42
|
-
-
|
|
42
|
+
- 手本ファイル(プロダクトリポジトリを含む)へ変更が生じた場合は元に戻し、commit の対象に含めない。解消できなければ異常終了する。
|
|
43
43
|
- agent 自身は登録簿の状態を変更しない。
|
|
44
44
|
|
|
45
45
|
_COMMON_CONVENTIONS_
|
|
@@ -14,21 +14,21 @@ _PHASE_DESCRIPTION_
|
|
|
14
14
|
- 記述標準: [[_AUTHORING_STANDARD_ID_|執筆標準]](`_AUTHORING_STANDARD_PATH_`)
|
|
15
15
|
- result: `_RESULT_REF_`
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
手本にするファイル:
|
|
18
18
|
|
|
19
19
|
_AUTHORING_EXEMPLARS_
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
手本ファイルは読み取り専用であり、プロジェクトリポジトリとプロダクトリポジトリのどちらにあっても変更しない。手本がない場合は、記述標準と対象領域の慣行だけを根拠に実践の型を作る。
|
|
22
22
|
|
|
23
23
|
## 3. 進め方
|
|
24
24
|
|
|
25
|
-
1.
|
|
25
|
+
1. 記述標準と手本ファイルを実際に読み、複数の成果物に再利用できる規則・問い・完成例・雛形を抽出する。
|
|
26
26
|
2. `_AUTHORING_KATA_PATH_` に `_AUTHORING_KATA_ID_` を持つ `_AUTHORING_KATA_KIND_` を新規作成する。frontmatter の `status` は `draft` とし、`ready` へ変更しない。
|
|
27
27
|
3. 手本の内容を丸写しせず、プロジェクト固有の値を一般化する。手本同士が矛盾する場合は、共通部分と差異を分け、判断できない点を result の申し送りへ記録する。
|
|
28
|
-
4.
|
|
29
|
-
5.
|
|
28
|
+
4. 手本のうち成果物カタログに載っているものだけ、作った種類の参照が `undecided` または未記入なら `_AUTHORING_KATA_ID_` へ更新する。カタログ外の文書とプロダクトリポジトリのファイルは読み取り専用の手本にとどめ、参照を付け替えない。rulebook は成果物カタログの `rulebook`、recipe / sample / template は成果物が参照する rulebook frontmatter の同名フィールドを正本とする。
|
|
29
|
+
5. カタログ成果物の参照がすでに別の kata を指す場合は上書きせず、その成果物 ID・既存参照・新しい kata ID を result の申し送りへ記録する。`not-needed` も意図的な判断として上書きしない。
|
|
30
30
|
recipe / sample / template の作成時に、手本の rulebook 自体が `undecided`・未記入・`not-needed` で参照先を記録できない場合は、別種の kata を同時作成せず、付け替え不能として result へ記録する。
|
|
31
|
-
6. 新しい kata
|
|
31
|
+
6. 新しい kata と参照の更新だけを変更対象とし、手本ファイルは変更しない。
|
|
32
32
|
|
|
33
33
|
## 4. 完了手順
|
|
34
34
|
|
|
@@ -39,7 +39,7 @@ _AUTHORING_EXEMPLARS_
|
|
|
39
39
|
## 5. 異常終了の条件
|
|
40
40
|
|
|
41
41
|
- 新しい id が既に存在する、対象種別と id の末尾が一致しない、手本を解決できない、または検査が未解消の場合は異常終了する。
|
|
42
|
-
-
|
|
42
|
+
- 手本ファイル(プロダクトリポジトリを含む)へ変更が生じた場合は元に戻し、commit の対象に含めない。解消できなければ異常終了する。
|
|
43
43
|
- agent 自身は登録簿の状態を変更しない。
|
|
44
44
|
|
|
45
45
|
_COMMON_CONVENTIONS_
|
|
@@ -14,21 +14,21 @@ _PHASE_DESCRIPTION_
|
|
|
14
14
|
- 記述標準: [[_AUTHORING_STANDARD_ID_|執筆標準]](`_AUTHORING_STANDARD_PATH_`)
|
|
15
15
|
- result: `_RESULT_REF_`
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
手本にするファイル:
|
|
18
18
|
|
|
19
19
|
_AUTHORING_EXEMPLARS_
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
手本ファイルは読み取り専用であり、プロジェクトリポジトリとプロダクトリポジトリのどちらにあっても変更しない。手本がない場合は、記述標準と対象領域の慣行だけを根拠に実践の型を作る。
|
|
22
22
|
|
|
23
23
|
## 3. 進め方
|
|
24
24
|
|
|
25
|
-
1.
|
|
25
|
+
1. 記述標準と手本ファイルを実際に読み、複数の成果物に再利用できる規則・問い・完成例・雛形を抽出する。
|
|
26
26
|
2. `_AUTHORING_KATA_PATH_` に `_AUTHORING_KATA_ID_` を持つ `_AUTHORING_KATA_KIND_` を新規作成する。frontmatter の `status` は `draft` とし、`ready` へ変更しない。
|
|
27
27
|
3. 手本の内容を丸写しせず、プロジェクト固有の値を一般化する。手本同士が矛盾する場合は、共通部分と差異を分け、判断できない点を result の申し送りへ記録する。
|
|
28
|
-
4.
|
|
29
|
-
5.
|
|
28
|
+
4. 手本のうち成果物カタログに載っているものだけ、作った種類の参照が `undecided` または未記入なら `_AUTHORING_KATA_ID_` へ更新する。カタログ外の文書とプロダクトリポジトリのファイルは読み取り専用の手本にとどめ、参照を付け替えない。rulebook は成果物カタログの `rulebook`、recipe / sample / template は成果物が参照する rulebook frontmatter の同名フィールドを正本とする。
|
|
29
|
+
5. カタログ成果物の参照がすでに別の kata を指す場合は上書きせず、その成果物 ID・既存参照・新しい kata ID を result の申し送りへ記録する。`not-needed` も意図的な判断として上書きしない。
|
|
30
30
|
recipe / sample / template の作成時に、手本の rulebook 自体が `undecided`・未記入・`not-needed` で参照先を記録できない場合は、別種の kata を同時作成せず、付け替え不能として result へ記録する。
|
|
31
|
-
6. 新しい kata
|
|
31
|
+
6. 新しい kata と参照の更新だけを変更対象とし、手本ファイルは変更しない。
|
|
32
32
|
|
|
33
33
|
## 4. 完了手順
|
|
34
34
|
|
|
@@ -39,7 +39,7 @@ _AUTHORING_EXEMPLARS_
|
|
|
39
39
|
## 5. 異常終了の条件
|
|
40
40
|
|
|
41
41
|
- 新しい id が既に存在する、対象種別と id の末尾が一致しない、手本を解決できない、または検査が未解消の場合は異常終了する。
|
|
42
|
-
-
|
|
42
|
+
- 手本ファイル(プロダクトリポジトリを含む)へ変更が生じた場合は元に戻し、commit の対象に含めない。解消できなければ異常終了する。
|
|
43
43
|
- agent 自身は登録簿の状態を変更しない。
|
|
44
44
|
|
|
45
45
|
_COMMON_CONVENTIONS_
|
|
@@ -130,7 +130,7 @@ members:
|
|
|
130
130
|
roles: []
|
|
131
131
|
type: agent
|
|
132
132
|
provider: codex
|
|
133
|
-
model: gpt-
|
|
133
|
+
model: gpt-6.1-sol
|
|
134
134
|
effort: high
|
|
135
135
|
mode: edit
|
|
136
136
|
stage_role: executor
|
|
@@ -507,13 +507,13 @@ specdojo exec run --project <project-id> --task <task-id> \
|
|
|
507
507
|
|
|
508
508
|
executor の出力は、そのまま reporter へ渡さずに run 単位の evidence へ整形して保存します。保存先は `<execution_path>/exec/evidence/<task-id>/<run-id>/` です。
|
|
509
509
|
|
|
510
|
-
| ファイル | 内容
|
|
511
|
-
| --------------------------------------------------------------------- |
|
|
512
|
-
| `evidence.json` | stage の実行結果、変更ファイル一覧、diff
|
|
513
|
-
| `executor.log` | executor の標準出力・標準エラーの抜粋(人が調査するための参照先)
|
|
514
|
-
| `reporter-attempt-<n>.stdout.log` / `reporter-attempt-<n>.stderr.log` | 失敗した reporter の形式試行ごとの stdout / stderr(秘匿処理後の生出力)
|
|
515
|
-
| `parent-validation-attempt-<n>-<id>.log` | 失敗した親検証の stdout / stderr(秘匿処理後の出力)
|
|
516
|
-
| `pipeline-state.json` | executor / reporter の状態・actor・試行回数・成果物参照
|
|
510
|
+
| ファイル | 内容 |
|
|
511
|
+
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
|
|
512
|
+
| `evidence.json` | stage の実行結果、変更ファイル一覧、diff サマリ、検証結果、最終メッセージ、申し送り、失敗理由、ログ参照 |
|
|
513
|
+
| `executor.log` | executor の標準出力・標準エラーの抜粋(人が調査するための参照先) |
|
|
514
|
+
| `reporter-attempt-<n>.stdout.log` / `reporter-attempt-<n>.stderr.log` | 失敗した reporter の形式試行ごとの stdout / stderr(秘匿処理後の生出力) |
|
|
515
|
+
| `parent-validation-attempt-<n>-<id>.log` | 失敗した親検証の stdout / stderr(秘匿処理後の出力) |
|
|
516
|
+
| `pipeline-state.json` | executor / reporter の状態・actor・試行回数・成果物参照 |
|
|
517
517
|
|
|
518
518
|
引き渡しの方針は次のとおりです。
|
|
519
519
|
|
|
@@ -524,10 +524,12 @@ executor の出力は、そのまま reporter へ渡さずに run 単位の evid
|
|
|
524
524
|
- reporter が非ゼロ終了または形式エラーで失敗した場合、同じ reporter stage 内の各形式試行を `reporter-attempt-<n>.stdout.log` と `reporter-attempt-<n>.stderr.log` に保存します。同じ run を resume して再度失敗した場合は、直近の失敗内容でこれらのファイルと `log_refs` を置き換えます。
|
|
525
525
|
- 親検証は失敗時だけ出力を保存し、成功時は要約だけを記録します。失敗ログは `parent-validation-output` として `log_refs` から参照します。同じ run の resume や統合段の再検証では attempt 番号を増やして新しいログを追加し、以前の失敗ログを上書きしません。親検証の要約は 1,000 文字以内で先頭と末尾を残すため、末尾に出る失敗ケース名と件数を evidence から確認できます。
|
|
526
526
|
- evidence ディレクトリは Git の管理対象です。成功して統合された run のログは履歴に残り、失敗中の worktree では未コミットのまま保持されます。`--force-restart` などで worktree を破棄すると未コミットログも失われるため、必要な調査を先に行います。既知パターンは保存前に秘匿しますが、未知形式の秘密が残る可能性を考慮し、ログを外部共有する前に内容を確認します。
|
|
527
|
-
- executor が構造化した最終報告を返す場合は、標準出力に `<specdojo_executor_evidence>` タグで JSON(`final_message`・`validations`)を出します。`validations[].status` は `passed` / `failed` / `not_run` / `not_applicable` / `requires_human` のいずれかです。`not_applicable` はリポジトリが検査の適用条件を満たさない場合に使い、`reason` へ理由を必ず記録します。`requires_human` は、実 agent CLI の起動、利用枠や課金を伴う操作、認証情報やホスト側の操作など、agent の sandbox から実行できない確認だけに使います。実行できるが省略した検証には使わず、`not_run` として記録します。タグが無い場合は標準出力の残りを最終メッセージとして扱います。
|
|
527
|
+
- executor が構造化した最終報告を返す場合は、標準出力に `<specdojo_executor_evidence>` タグで JSON(`final_message`・`validations`・省略可能な `completion_status`・`handoff`)を出します。`validations[].status` は `passed` / `failed` / `not_run` / `not_applicable` / `requires_human` のいずれかです。`not_applicable` はリポジトリが検査の適用条件を満たさない場合に使い、`reason` へ理由を必ず記録します。`requires_human` は、実 agent CLI の起動、利用枠や課金を伴う操作、認証情報やホスト側の操作など、agent の sandbox から実行できない確認だけに使います。実行できるが省略した検証には使わず、`not_run` として記録します。タグが無い場合は標準出力の残りを最終メッセージとして扱います。
|
|
528
528
|
- `pipeline.parent_validations` には `validate-schema`(`npm run validate:schema`)、`typecheck`(`npm run typecheck`)、`test-unit`(`npm run test:unit`)、`test-integration`(`npm run test:integration`)、`lint-ts`(`npm run lint:ts`)、`lint-fm`(`npm run lint:fm`)、`lint-md`(`npm run lint:md`)、`build`(`npm run build`)、`format-check`(`npm run format:check`)を指定できます。親 runner は executor の成功後・reporter の起動前に、指定順で固定 argv の検証を実行します。
|
|
529
529
|
- executor prompt には設定済み ID と対応コマンドを明示します。executor はそのコマンドや対象限定版を sandbox 内で実行せず、executor evidence の validations にも含めなくてよいものとします。親 runner の結果は `source: runner` と許可リスト `id` 付きで同じ `validations` 配列へ保存します。executor が同じ検査を `not_run` または `not_applicable` として含めた場合も、同じリポジトリで実行された親 runner の結果を正とします。これにより sandbox 内で成立しない検証を親へ移した場合も二重実行せず、executor の重複報告で run を止めません。
|
|
530
530
|
- result の `changed_files` のパスは evidence の `changes` から、execution の evidence、project register とその派生ビュー、当該 result という runner 管理記録を除いて runner が機械生成します。除外後の変更一覧だけを reporter へ渡し、edit の変更説明は evidence のパスと対にして受け取ります。runner はパスで突き合わせるため、説明の順序は問いません。説明が不足したパスには Git の変更メタデータ(追加・変更・削除・名前の変更、行数)を記録し、変更ファイルが多い場合(50 件超)はディレクトリごとに集約して記録します。evidence にないパスの説明は捨てます。`outcome` と `block_reason` は stage の状態・終了コード・保護機構が保存した理由・executor / 親 runner の検証から機械生成します。reporter の JSON Schema は文章項目と対応づけ用のパスだけを受け付け、いずれかの検証が failed または `not_run` なら、reporter の文章にかかわらず機械判定は blocked です。ただし、executor が `not_run` または `not_applicable` と記録したコマンドを、親 runner が同じリポジトリで同じコマンドとして実行し成功していれば、親 runner の結果を正として executor の報告を無視します。さらに、`npm run <name>` に対応する script がない、`npx <package>` の package が `dependencies` / `devDependencies` にない、検査の対象となる種類の変更ファイルがない、または SpecDojo サブコマンドの設定上の適用条件を満たさないことを runner が機械的に確定できる場合、その `not_run` は block せず、edit result の申し送りへ「適用外の検証(runner の判定)」として追記します。変更ファイル種別で判定する対応は共通規約の検査表を正本とし、`validate:schema:file` は `*.yaml` / `*.yml`、Prettier は `*.md` / `*.ts` / `*.js` / `*.json` / `*.yaml` / `*.yml`、markdownlint は `*.md` の変更がある場合だけ適用対象とします。rename は変更前後の両方を見て、プロダクトリポジトリのコマンドはそのリポジトリの変更だけで判定します。`typecheck` など、この対応に含まれない検査の判定は変更しません。SpecDojo の起動形は `specdojo <subcommand>`、`npx specdojo <subcommand>`、ソース/配布済み CLI の直接起動を認識し、`catalog validate` は対象 project の `catalog_path` で判定します。対象 project は、コマンドの `--project <id>`、run の対象 project(runner が execution path に一致する project を設定から特定したもの)、`current_project` の順に決めます。別の project が `catalog_path` を持っていても、run の対象 project に `catalog_path` がなければ適用外です。対象 project に `catalog_path` があっても、executor の変更(runner 管理記録を除き、rename は変更前後の両方を見ます)が `docs/ja/projects/` 配下に及ばない run では、plan の共通規約の検証表と同じく適用外とし、executor の `not_applicable` も受理します。変更が及ぶ run では従来どおり適用対象です。また、`<repo>:<path>` を引数に含むコマンド、`--prefix <repo>` 付きのコマンド、または `$SPECDOJO_REPO_<NAME>` / `${SPECDOJO_REPO_<NAME>}` を含むコマンドは、対象 project が `repos` で宣言したそのプロダクトリポジトリの `package.json` で script と依存を判定します(`--prefix` はリポジトリ名か設定の `path` と一致するものを対象にします)。設定が読めない、対象 project を特定できない、または適用条件を未定義のサブコマンドは機械的な救済をせず、通常の `not_run` として扱います。executor の failed は親 runner の成功や適用外判定で打ち消しません。`npm run check` のように npm script を `&&` でつないだだけの合成コマンドを executor が `not_run` とした場合は、対象リポジトリの `package.json` の script を展開し、構成する各コマンドが同じリポジトリの親検証か executor 自身の検証で通っていれば満たされたものとして扱います。`npm test` は、`npm run test:unit` と `npm run test:integration` の両方が通っていれば満たされたものとします。構成するコマンドの script の中身と同じコマンドを executor が直接実行して通した場合も満たします(`tsx` の起動の書き方の違いはそろえて比べます)。任意のシェルを含む script は展開しません。理由付きの `not_applicable` は block の理由にせず、runner が edit result の申し送りへ「適用外の検証: `<コマンド>`(<理由>)」として機械的に追記します。ただし、理由がない場合、変更ファイル種別を含む適用条件を満たした `npm run <name>` の script が存在する場合、または同条件を満たした `npx <package>` の package が `dependencies` / `devDependencies` に存在する場合は誤申告として blocked にします。SpecDojo サブコマンドは package の有無だけでは反証せず、既知の適用条件を設定から判定します。適用条件が未定義なら理由付きの agent の申告に従います。`specdojo index build`(`npx specdojo index build`・`node --import tsx src/specdojo.ts index build` などの起動形を含みます)は runner が担う検証です。出力先の `.specdojo/doc-index.json` は agent が書き込めず、index は worktree の準備と統合の前に runner が再生成するため、executor への指示では実行も記録もしないよう伝えます。executor が `not_run` / `not_applicable` と記録しても block の理由にせず、`not_run` の場合は edit result の申し送りへ「runner が担う検証: `<コマンド>`(<理由>)」として追記します。runner の再生成が失敗した場合は worktree の準備で run が止まるか、runner の検証の失敗として block するため、満たしたものとは扱いません。executor の failed は救済せず、ほかの SpecDojo サブコマンドの `not_run` の扱いも変えません。executor の `requires_human` は block の理由にせず、runner が edit result の申し送りへ「人の確認が必要: `<コマンド>`(<要約>)」として機械的に追記します。項目は review へ進み、人が確認してから close します。
|
|
531
|
+
- `completion_status` は作業の完了状態を示す省略可能な欄で、値は `complete` / `incomplete` です。欄のない既存の報告は `complete` として扱います。値が指定されていてこの 2 値に合わない場合は、安全側に倒して `incomplete` として保存します。executor は計画の作業を終えられなかった場合、`incomplete` とし、理由を `final_message`、残作業を `handoff` に書きます。終了コード 0 や親検証の成功では未完了の申告を上書きしません。`exec run --register` は親検証・reporter を起動する前に停止し、項目を `waiting` にして、秘匿処理・文字数制限を適用した `final_message` の要旨を `block_reason` に記録します。worktree 実行では変更と evidence を残し、統合しません。pipeline の executor は `blocked`、evidence の `stage.status` と `exit_code` は実際のプロセス結果のままとします。`--resume --resume-from executor`(または `--resume`)で再開でき、前回の理由と `handoff`、途中の変更を executor に引き継ぎます。完了を申告し直し、必要な検証を通過してから review・統合へ進みます。
|
|
532
|
+
- `handoff` は executor が申し送る判断の理由、保護された設定の変更案、次のアクションなどの文字列配列です。先頭 100 件、各 4,000 文字までを秘匿処理して evidence に保存し、空文字列や文字列以外の要素は除外します。省略した既存の報告・evidence も有効です。reporter にはこの欄も渡し、edit result の「申し送り」には runner が reporter の補足と合わせて機械的に転記します。同一の文字列は重複させず、reporter が省略しても executor の記録は残します。register の完了条件が result への記録を求める場合、pipeline の executor は個票の対応結果と報告の `handoff` の両方に書きます。close の前には個票の対応結果と result の両方を確認します。
|
|
531
533
|
- reporter の出力は JSON Schema で厳格に検証します。形式不正のときは同じ plan と evidence のまま reporter だけを最大 3 回再実行し、executor は再実行しません。
|
|
532
534
|
- reporter stage の再開では、現在の設定 ID と一致する親検証が保存済み evidence にそろっている場合だけ executor evidence を再利用します。`{ id, repo }` を使う場合は、ID とリポジトリの組が一致することを求めます。再実行時も同じ割り当てで、各リポジトリの worktree を `cwd` にします。保存済みの親検証がすべて成功していれば再実行しません。`failed` / `not_run` があれば、親 runner が現在の worktree で固定許可リストの親検証を再実行し、同じ ID の結果を evidence 上で置換してから reporter へ渡します。過去の親検証ログは置換せず、新しい失敗ログだけを追加します。executor 由来の検証は再実行・置換しません。設定 ID が変わった、または結果が欠けている場合、Schedule 実行は新しい executor run としてやり直し、register 実行は明示的な再実行を促して再開を拒否します。
|
|
533
535
|
- result の frontmatter は runner が scaffold した内容を保ち、本文は検証済みの reporter 文章と evidence 由来の事実を組み合わせて runner が描画します。reporter はファイルを書きません。
|
|
@@ -583,16 +585,44 @@ specdojo config scaffold --provider claude
|
|
|
583
585
|
|
|
584
586
|
`specdojo init --exec` と `config scaffold` が配布する agent の名簿と定義は、実体と別名の 2 段構成です(0.4.0 から)。実体は model の系統と役割で名付け、provider・`model`・役割を持ちます。従来の名前は `aliases` で実体を指す別名として残します。claude と opencode の agent の定義は役割(executor・review executor・reporter)ごとの 1 ファイルで `model` を持たず、`command_params.by_mode` で mode から定義を選び、model は実体の `model` を `--model {model}` で渡します。
|
|
585
587
|
|
|
586
|
-
| provider | init が生成する実体 | 別名(従来の名前) | model の書き場所
|
|
587
|
-
| ----------- | ----------------------------------------------------------------- | -------------------------------------------------------------------- |
|
|
588
|
-
| claude | `sonnet-executor`・`sonnet-review-executor`・`sonnet-reporter` | `claude-executor`・`claude-review-executor`・`claude-reporter` | 実体の `model`(`sonnet`)
|
|
589
|
-
|
|
|
590
|
-
|
|
|
591
|
-
|
|
|
592
|
-
|
|
|
588
|
+
| provider | init が生成する実体 | 別名(従来の名前) | model の書き場所 |
|
|
589
|
+
| ----------- | ----------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------- |
|
|
590
|
+
| claude | `sonnet-executor`・`sonnet-review-executor`・`sonnet-reporter` | `claude-executor`・`claude-review-executor`・`claude-reporter` | 実体の `model`(`sonnet`) |
|
|
591
|
+
| claude | `opus-executor`・`opus-review-executor`(expert) | `claude-expert-executor`・`claude-expert-review-executor` | 実体の `model`(`opus`) |
|
|
592
|
+
| codex | `luna-executor`・`luna-review-executor`・`luna-reporter` | `codex-executor`・`codex-review-executor`・`codex-reporter` | 実体の `model`(`gpt-6-luna`、effort は `by_proficiency`) |
|
|
593
|
+
| codex | `sol-executor`・`sol-review-executor`(expert) | `codex-expert-executor`・`codex-expert-review-executor` | 実体の `model`(`gpt-6.1-sol`、effort は `by_proficiency`) |
|
|
594
|
+
| opencode | `gemma-executor`・`gemma-review-executor`・`gemma-reporter` | `opencode-executor`・`opencode-review-executor`・`opencode-reporter` | 実体の `model`(`opencode.json` の provider 名込み) |
|
|
595
|
+
| antigravity | `flash-executor`・`flash-review-executor`・`flash-reporter` | `agy-executor`・`agy-review-executor`・`agy-reporter` | 実体の `model`(推論強度を含む ID) |
|
|
596
|
+
| copilot | `copilot-executor`・`copilot-review-executor`・`copilot-reporter` | なし(`--model auto` で model を自動選択するため系統で名付けない) | `command_template` の `--model auto` |
|
|
597
|
+
|
|
598
|
+
claude と codex は normal と expert の 2 段を持ちます(0.4.6 から)。expert の実体には `proficiency: expert` を付けます。init が書く振り分けの表(`routing`)は、hard を expert の別名(`claude-expert-executor`・`codex-expert-executor`)、medium と easy を normal の別名にし、reporter はどの難易度でも normal の別名にします。expert の段がない provider(opencode・antigravity など)は、hard も normal の別名を使います。codex の reasoning effort は `by_proficiency` で normal が `medium`、expert が `high` で、`gpt-6-luna` は Max までしか受け付けないため Ultra を割り当てません。
|
|
593
599
|
|
|
594
600
|
init は選んだ provider の実体だけを名簿へ書き、別名は向き先の実体が選ばれたものだけを残します。次の手順の案内(`--executor-by` / `--reporter-by`)には別名を示します。antigravity の `agent-members-snippet.yaml` は実体を `disabled: true` で配布するため、別名は末尾にコメントの例として置きます。別名は無効な member を指せないので、向き先の実体を有効にしたものだけを `aliases` へ写します。
|
|
595
601
|
|
|
602
|
+
`gpt-6-astra` は雛形の既定に入れません。使う場合は、次のように実体を名簿へ足し、`--executor-by astra-executor` や `routing` で指名します。
|
|
603
|
+
|
|
604
|
+
```yaml
|
|
605
|
+
members:
|
|
606
|
+
- nickname: astra-executor
|
|
607
|
+
display_name: Codex Astra Executor
|
|
608
|
+
email: null
|
|
609
|
+
roles: []
|
|
610
|
+
type: agent
|
|
611
|
+
provider: codex
|
|
612
|
+
model: gpt-6-astra
|
|
613
|
+
mode: edit
|
|
614
|
+
stage_role: executor
|
|
615
|
+
capabilities: [web_search]
|
|
616
|
+
proficiency: expert
|
|
617
|
+
priority: 1
|
|
618
|
+
persona: task-executor
|
|
619
|
+
scheduler_strategy: critical-first
|
|
620
|
+
```
|
|
621
|
+
|
|
622
|
+
0.4.5 までの init が作った名簿(`terra-executor` などの `gpt-5.6-terra` の実体と `orch:terra`)は、init も scaffold も書き換えません。新しい名前へそろえる場合は、`.specdojo/agent-members.yaml` の `terra-*` を `luna-*`(`model: gpt-6-luna`)へ名前を変え、`sol-*` を加えるか `model` を `gpt-6.1-sol` にし、`aliases` の `codex-*` の向き先を合わせます。`package.json` は `config scaffold --provider codex` を実行すると `orch:luna` が加わります。不要になった `orch:terra` は手で消し、既存の `orch:sol` は上書きされないため `-m gpt-6.1-sol` へ手で直します。
|
|
623
|
+
|
|
624
|
+
配布する `templates/codex/agents/*.toml` も名簿と同じく GPT-6 の 2 段構成(normal の `codex-executor`・`codex-review-executor` は `gpt-6-luna`、expert の `codex-expert-executor`・`codex-expert-review-executor` と `specdojo-orchestrator` は `gpt-6.1-sol`)にそろえています。既存の利用者の `.codex/agents/*.toml` は scaffold でも上書きされないため、`specdojo config scaffold --provider codex --force` で配布原本を再配置するか、各 `.codex/agents/*.toml` の `model`(`gpt-5.4-mini`・`gpt-5.5`・`gpt-5.6-terra`)を手動で `gpt-6-luna` / `gpt-6.1-sol` へ書き換えます。
|
|
625
|
+
|
|
596
626
|
既存の利用者の 1 段の名簿(`aliases` も `model` も持たない member と、`--agent {nickname}` の `command_template`)は、変更しなくてもそのまま動きます。
|
|
597
627
|
|
|
598
628
|
- `aliases` は省略でき、`model` を持たない member は従来どおり `command_params`(`by_proficiency` など)の `model` で起動します。member の `model` がある場合だけ、そちらが優先されます。
|
|
@@ -65,7 +65,9 @@ template は、記述する部分を _TODO_ などのプレースホルダとし
|
|
|
65
65
|
|
|
66
66
|
要否は初回の `bootstrap` で判断します。`undecided` の型は、必要なら項目を省略したうえで必要な型を成果物と一緒に整備し、不要なら `not-needed` へ更新します。既存の型を廃止する、または `not-needed` を必要へ変更する場合は、成果物の実績・繰り返し発生したレビュー指摘・schema の表現範囲を根拠として rulebook frontmatter の宣言も同時に更新します。
|
|
67
67
|
|
|
68
|
-
成果物と型を一組で初めて作るときは `bootstrap` を使います。成果物がすでにあり、そこから再利用可能な型だけを新しく起こすとき、または手本なしで型だけを作るときは `rulebook-authoring` / `recipe-authoring` / `sample-authoring` / `template-authoring` を使います。authoring
|
|
68
|
+
成果物と型を一組で初めて作るときは `bootstrap` を使います。成果物がすでにあり、そこから再利用可能な型だけを新しく起こすとき、または手本なしで型だけを作るときは `rulebook-authoring` / `recipe-authoring` / `sample-authoring` / `template-authoring` を使います。authoring では `--target` に新しい kata ID、繰り返し可能な `--source` に読み取り専用の手本を指定します。手本は文書索引で解決できる doc id、プロジェクトリポジトリの相対パス、または project の `repos` に宣言した `<repo>:<path>` です。パスにはファイル、ディレクトリ、glob を指定できます。展開後の手本は重複を除いて 100 ファイルまでです。広すぎるパターンによる読み取り範囲と plan の肥大化を抑えるため、超過時は起票・実行を停止します。
|
|
69
|
+
|
|
70
|
+
`<repo>` が `repos[].name` と一致する値はプロダクトリポジトリのパスとして扱います。それ以外で `/` または拡張子を含む値はプロジェクトリポジトリのパス、残りは doc id として文書索引で解決します。いずれの形も手本が見つからなければ停止します。成果物カタログは必須ではありません。手本がカタログ成果物で、その kata 参照が `undecided` または未記入の場合だけ新しい kata ID へ更新します。カタログ外とプロダクトリポジトリの手本は変更せず、参照も付け替えません。互換性のため、新しい kata ID に続く 2 個目以降の `--target` も `--source` と同じ手本として受け付けます。
|
|
69
71
|
|
|
70
72
|
利用者が作る kata はリポジトリ単位の `kata_authority` を使い、`docs/ja/specdojo/{rulebooks,recipes,samples,templates}/<kata_authority>/` に置きます。たとえば `customer:payment-rulebook` の配置は `docs/ja/specdojo/rulebooks/customer/payment-rulebook.md` です。`specdojo:` は SpecDojo 本体専用であり、利用者リポジトリでは新規作成できません。これにより、同じリポジトリの複数 project で型を共有しながら、将来追加される同名の同梱 kata と衝突しません。
|
|
71
73
|
|
|
@@ -87,7 +89,114 @@ template は、記述する部分を _TODO_ などのプレースホルダとし
|
|
|
87
89
|
|
|
88
90
|
型そのものの種別と型全体での位置づけは [型の構成ガイド](practice-system-composition-guide.md) を正本とします。
|
|
89
91
|
|
|
90
|
-
## 4.
|
|
92
|
+
## 4. Slidev の kata を検証する
|
|
93
|
+
|
|
94
|
+
スライドの sample・template を作る場合、SpecDojo を入れたリポジトリにも Slidev の実行環境を
|
|
95
|
+
用意すると、kata をビルドして確かめられます。新規導入は `specdojo init --slidev`、既存リポジトリへの
|
|
96
|
+
追加は次のコマンドを使います。`init` は Dev Container の `full` を選んだ場合だけ導入の既定が「はい」です。
|
|
97
|
+
オプションの詳細は [[specdojo:command-reference|コマンドリファレンス]] を参照してください。
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
specdojo config scaffold --slidev --dry-run
|
|
101
|
+
specdojo config scaffold --slidev
|
|
102
|
+
npm install
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
scaffold が加えるのは `@slidev/cli`・`prettier-plugin-slidev`・`prettier` の開発依存と、スライドだけを
|
|
106
|
+
整形する Prettier overrides、markdownlint の基本設定と Slidev 用の CLI2 overrides、CLI 用の除外です。
|
|
107
|
+
既存の依存の版は変えません。既存の設定・ignore は保持するため、表示された追加例を確認し、
|
|
108
|
+
足りない設定を手で統合してから整形・commit してください。
|
|
109
|
+
|
|
110
|
+
既定の対象は `docs/ja/specdojo/samples/**/*-slidev-sample.md` と
|
|
111
|
+
`docs/ja/specdojo/templates/**/*-slidev-template.md` です。たとえば利用者の `kata_authority` が
|
|
112
|
+
`edu-scratch` なら、sample は `docs/ja/specdojo/samples/edu-scratch/lesson-slidev-sample.md` に置きます。
|
|
113
|
+
別名の `lsd-sample.md` や旧配置の kata は、実際のパスを Prettier overrides の `files`、
|
|
114
|
+
`.markdownlint-cli2.yaml` の `overrides.filter`、`.markdownlintignore` の 3 か所に追加してください。
|
|
115
|
+
通常の Markdown として整形するとページ区切り直後の
|
|
116
|
+
設定が本文に変わる場合があるため、Slidev のファイルだけに `slidev` parser と
|
|
117
|
+
`prettier-plugin-slidev` を当てます。設定方法は [公式 plugin の説明](https://github.com/slidevjs/prettier-plugin) に従っています。
|
|
118
|
+
|
|
119
|
+
markdownlint の基本設定は `.markdownlintrc`(先頭が `{` の JSON)に置きます。commit hook と
|
|
120
|
+
`exec run` の result 検査は markdownlint-cli のままで、この基本設定と `.markdownlintignore` を読みます。
|
|
121
|
+
Slidev の kata は ignore で対象外にします。VS Code の markdownlint 拡張と CLI2 は
|
|
122
|
+
`.markdownlintignore` を読まないため、`.markdownlint-cli2.yaml` の `config.extends` から
|
|
123
|
+
`.markdownlintrc` を読み、Slidev 用の規則で検査します。スライドごとの見出しレベル・H1 とページ区切りに
|
|
124
|
+
隣接するブロックを許すため、基本設定に加えて `MD001`・`MD022`・`MD025`・`MD031`・`MD032` を外します。
|
|
125
|
+
|
|
126
|
+
CLI2 の overrides は最初の一致だけを使うため Slidev 用を先頭に置き、`filter` に対象 glob、
|
|
127
|
+
`combine: merge`、`config` に規則を指定します。Prettier は後の一致を優先するため Slidev 用を末尾に置きます。
|
|
128
|
+
通常の文書に対する規則は基本設定に残してください。
|
|
129
|
+
|
|
130
|
+
旧 scaffold の `.markdownlint.jsonc` などがある場合は、規則を JSON の `.markdownlintrc` に移し、
|
|
131
|
+
旧 `.markdownlint.*` を取り除き、CLI2 の `config.extends` を設定します。先頭にコメントを書くと
|
|
132
|
+
markdownlint-cli が JSON として読めません。親ディレクトリの `.markdownlint.*` も確認してください。
|
|
133
|
+
既存設定は `--force` でも自動移行しないため、表示された例を手で統合します。具体的な設定例と移行手順は
|
|
134
|
+
[[specdojo:command-reference|コマンドリファレンス]] の `config scaffold --lefthook` の説明を参照してください。
|
|
135
|
+
|
|
136
|
+
### 4.1. sample のビルドと表示
|
|
137
|
+
|
|
138
|
+
テーマの選定とインストールは利用者の作業です。scaffold は `slidev-theme-neversink` などのテーマを
|
|
139
|
+
選びません。sample の先頭の Slidev frontmatter の `theme` に合わせて開発依存を追加します。
|
|
140
|
+
たとえば `theme: default` を使う場合は次のようにします。
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
npm install --save-dev @slidev/theme-default
|
|
144
|
+
./node_modules/.bin/slidev build docs/ja/specdojo/samples/edu-scratch/lesson-slidev-sample.md --out "$PWD/tmp/slidev-dist"
|
|
145
|
+
./node_modules/.bin/slidev docs/ja/specdojo/samples/edu-scratch/lesson-slidev-sample.md
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
`build` の終了コードが 0 であることを確認し、表示されたローカル URL をブラウザで開いて、ページ区切り・
|
|
149
|
+
レイアウト・日本語・コンポーネントを確認します。CLI の引数は [Slidev 公式 CLI リファレンス](https://sli.dev/builtin/cli) を参照してください。
|
|
150
|
+
SSH / Dev Container 越しに開く場合は、開発サーバーのコマンドに `--remote` を加え、ポート 3030 を転送します。
|
|
151
|
+
`tmp/` は検証用の出力先なので、利用者の `.gitignore` に `/tmp/` を追加して管理対象から外してください。
|
|
152
|
+
|
|
153
|
+
### 4.2. 活動固有の部品と template
|
|
154
|
+
|
|
155
|
+
`ScratchBlocks.vue` などの活動固有のコンポーネント、`scratchblocks` などの追加依存、画像・
|
|
156
|
+
スタイル・setup は利用者がプロダクトリポジトリから用意します。部品に依存する場合は、sample を
|
|
157
|
+
`tmp/slidev-check/slides.md` にコピーし、同じ活動の `components/`・`public/` などをその横へ配置して、
|
|
158
|
+
相対参照を再現したうえで `./node_modules/.bin/slidev build tmp/slidev-check/slides.md --out "$PWD/tmp/slidev-dist"`
|
|
159
|
+
を実行します。template はプレースホルダを埋めた検証用コピーで同じ手順を使い、kata の原本を保持します。
|
|
160
|
+
|
|
161
|
+
PNG / PDF の書き出しに使う Playwright・Chromium、その OS ライブラリと日本語フォントは scaffold に
|
|
162
|
+
含みません。`slidev export` も行う場合は利用者が追加してください。ビルドとブラウザでの表示確認を先に行います。
|
|
163
|
+
|
|
164
|
+
## 5. kata の付属ファイル
|
|
165
|
+
|
|
166
|
+
`kata list` と `kata status` は、ID を読める形式(`.md`・`.mdx`・`.yaml`・`.yml`・`.json`)だけを
|
|
167
|
+
kata として表示します。この形式で ID の宣言がない場合は、従来どおりファイル名を ID とします。
|
|
168
|
+
CSS・画像など、それ以外の形式は独立した kata として表示しません。
|
|
169
|
+
|
|
170
|
+
付属ファイルは、kata と同じディレクトリに、最後の拡張子を除いた名前をそろえて置きます。
|
|
171
|
+
たとえば `lsd-sample.md` には `lsd-sample.css` を付けられます。複数の画像や部品は、同じ名前の
|
|
172
|
+
ディレクトリ `lsd-sample/` 以下にまとめられます。`generated/` 以下は対象外です。
|
|
173
|
+
ID を読める 5 形式のファイルは、同じ名前やディレクトリ内にあっても別の kata として扱い、
|
|
174
|
+
親 kata の付属ファイルには含めません。frontmatter に付属ファイルを宣言する必要はありません。
|
|
175
|
+
|
|
176
|
+
```text
|
|
177
|
+
samples/
|
|
178
|
+
lsd-sample.md
|
|
179
|
+
lsd-sample.css
|
|
180
|
+
lsd-sample/
|
|
181
|
+
images/
|
|
182
|
+
example.png
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
`specdojo kata eject --id <id>` は、同梱 kata とその付属ファイルを同じ相対パスへコピーします。
|
|
186
|
+
`--dry-run` では付属ファイルも 1 ファイルずつ表示し、書き込みません。既存ファイルはそれぞれ
|
|
187
|
+
`skip` となり、`--force` を付けた場合に上書きします。kata 本体が既存でも、未配置の付属ファイルは
|
|
188
|
+
コピーします。`kata install --all` も同じ規則で付属ファイルをコピーします。
|
|
189
|
+
|
|
190
|
+
コピー後に kata を別の場所で使う場合は、相対参照が保たれるよう付属ファイルも一緒に配置します。
|
|
191
|
+
Slidev の全ページに効かせる CSS は、検証用の `slides.md` の横へコピーするときに
|
|
192
|
+
`lsd-sample.css` を `style.css` にします。`kata eject` 自体は名前を変えません。
|
|
193
|
+
|
|
194
|
+
`kata status` は、eject 済みの kata 本体と付属ファイルをまとめて package と比較します。
|
|
195
|
+
付属ファイルだけの変更・追加・欠落も、親 kata の行を `modified` として表示します。
|
|
196
|
+
kata 本体が package にない場合は `package-missing`、package から参照中の場合は `-` です。
|
|
197
|
+
利用者の `kata_authority` に属する独自 kata の差分は、従来どおり `-` です。
|
|
198
|
+
|
|
199
|
+
## 6. 関連ドキュメント
|
|
91
200
|
|
|
92
201
|
- [実践の進め方ガイド](ryu-guide.md): `approach` の選び方・一覧、参照の共通原則、メンテナンス・review への適用
|
|
93
202
|
- [型の構成ガイド](practice-system-composition-guide.md): 実践の型を含む型(Kata)の種別と役割
|
|
@@ -48,10 +48,10 @@ CLI を直接操作する場合の代表フローは [遂行の技活用ガイ
|
|
|
48
48
|
| `orch:sonnet:work` | Claude Code / `sonnet` | `../worktrees/claude-work`(無ければ自動作成) |
|
|
49
49
|
| `orch:opus` | Claude Code / `opus` | なし |
|
|
50
50
|
| `orch:opus:work` | Claude Code / `opus` | `../worktrees/claude-work`(無ければ自動作成) |
|
|
51
|
-
| `orch:
|
|
52
|
-
| `orch:
|
|
53
|
-
| `orch:sol` | Codex / `gpt-
|
|
54
|
-
| `orch:sol:work` | Codex / `gpt-
|
|
51
|
+
| `orch:luna` | Codex / `gpt-6-luna` | なし |
|
|
52
|
+
| `orch:luna:work` | Codex / `gpt-6-luna` | `../worktrees/codex-work`(無ければ自動作成) |
|
|
53
|
+
| `orch:sol` | Codex / `gpt-6.1-sol` | なし |
|
|
54
|
+
| `orch:sol:work` | Codex / `gpt-6.1-sol` | `../worktrees/codex-work`(無ければ自動作成) |
|
|
55
55
|
| `orch:copilot` | GitHub Copilot | なし |
|
|
56
56
|
| `orch:copilot:work` | GitHub Copilot | `../worktrees/copilot-work`(無ければ自動作成) |
|
|
57
57
|
| `orch:qwen` | OpenCode / Qwen 3.8 | なし |
|
|
@@ -65,7 +65,7 @@ Antigravity CLI(`agy`)はファイル定義の agent を持たないため
|
|
|
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
|
|
68
|
+
`specdojo init` と `config scaffold` が利用者の `package.json` へ追加するスクリプトは、Claude Code が `orch:opus`・`orch:sonnet`、Codex が `orch:sol`(`gpt-6.1-sol`)・`orch:luna`(`gpt-6-luna`)、Antigravity が `orch:flash`、OpenCode が `orch:opencode` です。Codex と Antigravity のスクリプトは、名前に対応するモデルを起動コマンドで明示します。
|
|
69
69
|
|
|
70
70
|
0.4.0 以前に作った `orch:codex`・`orch:agy` は自動では削除・上書きされません。`config scaffold --provider codex` または `config scaffold --provider antigravity` を再実行して新しいスクリプトを追加し、新しい名前で起動できることを確認してから、旧スクリプトを `package.json` から削除してください。
|
|
71
71
|
|
|
@@ -82,7 +82,7 @@ npm run orch:opus
|
|
|
82
82
|
npm run orch:sonnet:work
|
|
83
83
|
```
|
|
84
84
|
|
|
85
|
-
frontier モデルは Claude Code が `opus`、Codex が `gpt-
|
|
85
|
+
frontier モデルは Claude Code が `opus`、Codex が `gpt-6.1-sol` に対応します。通常運用はそれぞれ既定の `sonnet` / `gpt-6-luna` を使います。
|
|
86
86
|
|
|
87
87
|
worktree 付きは、全 CLI で `tools/worktree/open-agent-worktree.sh` を通して固定名の worktree を使い、そこから `specdojo orchestrator launch` を起動します。無ければ起動時に作成します。ブランチは `worktree/<name>`、配置は `../worktrees/<name>` です。既存 worktree のブランチが一致しない場合は agent を起動しません。Claude Code の `--worktree` はブランチ名と配置を他の CLI に揃えられないため使用しません。
|
|
88
88
|
|
|
@@ -645,14 +645,16 @@ npx specdojo register add \
|
|
|
645
645
|
--difficulty hard \
|
|
646
646
|
--approach rulebook-authoring \
|
|
647
647
|
--target <kata-authority>:<name>-rulebook \
|
|
648
|
-
--
|
|
648
|
+
--source <deliverable-doc-id>
|
|
649
649
|
npx specdojo exec run \
|
|
650
650
|
--project <project-id> \
|
|
651
651
|
--register <PJR-ID> \
|
|
652
652
|
--worktree
|
|
653
653
|
```
|
|
654
654
|
|
|
655
|
-
|
|
655
|
+
`--target` は新しい kata ID、`--source` は任意の読み取り専用の手本です。`--source` は繰り返し指定でき、文書索引の doc id、プロジェクトリポジトリの相対パス、`repos` に宣言した `<repo>:<path>` を受け付けます。パスにはファイル、ディレクトリ、`*.md` などの glob を書けます。たとえば `--source docs/ja/lessons/01-chase/README.md` や `--source 'coderdojo-lessons:lessons/**/*.md'` の形です。カタログがない project でも使えますが、手本が見つからない場合と展開後に 100 ファイルを超える場合は停止します。互換性のため、2 個目以降の `--target` も手本として引き続き受け付けます。
|
|
656
|
+
|
|
657
|
+
成果物も型もまだない初期立ち上げには `bootstrap` を使います。手本なしで kata だけを作る場合は `--source` を省略します。recipe / sample / template では `approach` と ID の末尾を同じ種類へ置き換えます。手本がカタログ成果物で該当参照が `undecided` または未記入の場合だけ参照を新しい kata ID へ更新し、カタログ外とプロダクトリポジトリの手本は変更しません。
|
|
656
658
|
|
|
657
659
|
### 3.10. 統合後にreviewのagentへ確かめさせる
|
|
658
660
|
|
|
@@ -111,6 +111,8 @@ specdojo register add --project customer --type todo \
|
|
|
111
111
|
|
|
112
112
|
呼び出し元は相手の登録簿を直接編集せず、相手にインストールされた SpecDojo 0.4.2 以上へ処理を渡します。`--from customer:PJR-AB12` は相手の実 project ID に置き換えて検証・記録されます。相手のリポジトリや CLI がない場合、版が古い場合、`--commit` がない場合は起票前に停止します。相手への状態遷移は、相手のリポジトリへ移動して実行します。
|
|
113
113
|
|
|
114
|
+
SpecDojo 自身のリポジトリへ起票する場合も、同じように別名を宣言できます。相手で `npm install` と `npm run build` を実行しておきます。相手に `node_modules/.bin/specdojo` がなく、`package.json` の `name` が `specdojo` なら、呼び出し元と同じ Node.js で `node <相手>/dist/specdojo.js` を起動します。未ビルドの場合は `npm run build` を案内して停止し、版の条件(0.4.2 以上)も引き続き確認します。
|
|
115
|
+
|
|
114
116
|
タイトルが日本語の場合は、内容を表す英語の `--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 を作る・直す手順」を参照してください)。
|
|
115
117
|
|
|
116
118
|
`--priority` は次の目安で付けます(省略時は `medium`)。
|