specdojo 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,11 +3,27 @@
3
3
  SpecDojo は、仕様駆動開発のためのドキュメントフレームワークです。
4
4
  プロダクトの構築・改修に必要な情報を体系化し、人と生成 AI が同じ成果物を作成・検証・更新できるようにします。
5
5
 
6
- SpecDojo は、次のものを npm package とオープンソースのテンプレートリポジトリとして提供します。
6
+ **登録簿ひとつから始められます。** 設定 2 行で使い始め、必要になった分だけ広げられます。
7
7
 
8
- - 成果物の記述規則、作成手順、テンプレート、サンプル
9
- - プロジェクトとプロダクトの文書体系
10
- - register、Schedule、実行、レビューを支援する CLI
8
+ ## できること
9
+
10
+ ### 気づいたことを、型に沿って残せる
11
+
12
+ 作業だけでなく、判断・保留・観測・リスク・変更要求も同じ登録簿へ記録します。種別を選ぶと
13
+ 本文の章構成が与えられるため、「選択肢を比較して理由を書く」といった記録が形を保ちます。
14
+ 正本は Markdown なので、`git log` でそのまま読め、3 年後も SpecDojo なしで読めます。
15
+ 決定ログ・課題ログ・リスク登録簿は、この記録から生成されます。
16
+
17
+ ### 会話で進められる
18
+
19
+ 同梱の対話型オーケストレーターを配置すると、やりたいことを話すだけで進みます。
20
+ 調査や議論の内容がそのまま個票の本文になるため、別途まとめ直す必要がありません。
21
+ 状態を変える操作は実行前に提示して承認を求め、`git push` や破壊的操作は行いません。
22
+
23
+ ### 必要になったら、成果物の型へ広げられる
24
+
25
+ 要件、設計、テスト、運用まで 100 種類以上の記述規則・手順・テンプレート・サンプルを持ちます。
26
+ 使うものだけをカタログで宣言し、型に沿って作れます。最初から全部を用意する必要はありません。
11
27
 
12
28
  日本語ドキュメントは [SpecDojo ドキュメントサイト](https://specdojo.github.io/specdojo/ja/) で公開しています。
13
29
 
@@ -29,28 +45,71 @@ mkdir app1-specdojo app1-worktrees
29
45
  git -C app1-specdojo init
30
46
  cd app1-specdojo
31
47
  npm init -y
32
- npm install specdojo
33
- npm install --save-dev @specdojo/docs-lint
48
+ npm install --save-dev specdojo @specdojo/docs-lint
34
49
  npx specdojo config init
35
50
  ```
36
51
 
52
+ SpecDojo は文書と実行管理のためのツールで、成果物へ同梱されるものではないため `--save-dev` で導入します。あわせて、kata は `node_modules/specdojo` から参照されるため、`package-lock.json` が kata の版も固定します。グローバル導入(`npm install -g`)では版がプロジェクトに記録されず再現できません。
53
+
37
54
  `config init` は `.specdojo/specdojo.config.json` とその親ディレクトリを作成します。既定では
38
55
  `prj-0001` と `docs/ja/projects/prj-0001/controls/project-register` を使う最小構成です。別の
39
56
  project ID や配置を使う場合は、生成された設定の `current_project`、`projects` のキー、
40
57
  `base_path` を次へ進む前に変更してください。catalog や schedule へ進むときに追加するキーは
41
58
  [SpecDojo設定リファレンス](https://specdojo.github.io/specdojo/ja/specdojo/references/specdojo-config-reference.html)で確認できます。
42
59
 
43
- agent にタスクを実行させる場合は、利用する provider の設定を配置します。この手順は register
44
- だけを使う最小構成では省略できます。
60
+ ### オーケストレーターを配置する
61
+
62
+ SpecDojo は対話型オーケストレーターを同梱しています。CLI を直接叩く代わりに、会話で意図を伝えると、
63
+ 対応するコマンドを提案し、承認を得てから実行します。利用する provider の設定を配置します。
45
64
 
46
65
  ```sh
47
- npx specdojo config scaffold --provider codex
66
+ npx specdojo config scaffold --provider claude
48
67
  ```
49
68
 
50
- `--provider` には `claude`、`codex`、`copilot`、`opencode` を指定できます。従来の
51
- `npx specdojo exec scaffold --provider <name>` も互換入口として引き続き利用できます。
69
+ `--provider` には `antigravity`、`claude`、`codex`、`copilot`、`opencode` を指定できます。
70
+ オーケストレーターの配置先と起動方法は provider ごとに異なります。
71
+
72
+ | provider | 配置先 | 起動 |
73
+ | ------------- | ------------------------------------------- | -------------------------------------------------------------------------- |
74
+ | `claude` | `.claude/agents/specdojo-orchestrator.md` | `claude --agent specdojo-orchestrator` |
75
+ | `opencode` | `.opencode/agents/specdojo-orchestrator.md` | `opencode --agent specdojo-orchestrator` |
76
+ | `codex` | `.specdojo/codex/orchestrator.md` | `codex "$(cat .specdojo/codex/orchestrator.md)"` |
77
+ | `antigravity` | `.specdojo/antigravity/orchestrator.md` | `agy --add-dir "$(pwd)" -i "$(cat .specdojo/antigravity/orchestrator.md)"` |
78
+
79
+ `claude` と `opencode` は agent の定義ファイルを名前で選べるため、`--agent` で起動します。`codex` と
80
+ `antigravity` は定義ファイルから agent を選ぶ仕組みを持たないため、規範の本文を起動時の指示として
81
+ 渡します。antigravity の `.agents/` は rules と skills のためのディレクトリで、agent の定義は扱いません。
82
+ rules へ置くと全セッションへ読み込まれ、executor として起動したときにも役割が混入します。
83
+
84
+ 配置されるファイルにはモデル名が書かれています。手元で使えるモデルに合わせて編集してください。
85
+ executor / reporter の設定も同時に配置されるので、agent にタスクを実行させる段階で使います。
52
86
 
53
- 最初の登録簿と todo を作り、一覧を生成します。
87
+ ### 会話で操作する
88
+
89
+ 起動したら、やりたいことをそのまま伝えます。オーケストレーターがコマンドへ翻訳し、実行前に内容を提示します。
90
+
91
+ ```text
92
+ あなた : このプロジェクトを始めたい。まず登録簿を用意して、最初の作業を起票して。
93
+ agent : 次を実行します。よろしいですか。
94
+ npx specdojo register scaffold --project prj-0001
95
+ npx specdojo register add --project prj-0001 --type todo --title "..."
96
+ あなた : お願いします。
97
+ ```
98
+
99
+ 状態を変える操作は承認を得てから実行し、`git push` や破壊的操作は行いません。起票した項目の
100
+ 実行、状況の確認、成果物の生成も同じ流れで進みます。
101
+
102
+ ```text
103
+ PJR-XXXX を実行して
104
+ 今の状況は?
105
+ kata の rulebook を確認したい
106
+ ```
107
+
108
+ 詳しい進め方は [オーケストレーター運用ガイド](https://specdojo.github.io/specdojo/ja/specdojo/guides/orchestrator-operation-guide.html) を参照してください。
109
+
110
+ ### CLI を直接使う
111
+
112
+ agent を使わずに操作することもできます。最初の登録簿と todo を作り、一覧を生成します。
54
113
 
55
114
  ```sh
56
115
  npx specdojo register scaffold --project prj-0001
@@ -85,6 +144,10 @@ provider と agent の設定を終えた後は、同じ登録項目を実行で
85
144
  npx specdojo exec run --project prj-0001 --register PJR-XXXX
86
145
  ```
87
146
 
147
+ agent の実行は数分から数十分かかり、`routine` は定期実行されます。作業端末の状態に依存せず
148
+ 実行を続けたい場合は、常時稼働するホストへリモート接続する構成例を
149
+ [常時稼働ホスト運用ガイド](https://specdojo.github.io/specdojo/ja/specdojo/guides/remote-host-development-guide.html) に示しています。
150
+
88
151
  ### テンプレートリポジトリとして導入する
89
152
 
90
153
  npm package の参照方式ではなく、SpecDojo のソースと文書体系一式を最初から配置して
package/dist/dashboard.js CHANGED
@@ -3,7 +3,7 @@ import { join } from "node:path";
3
3
  import yaml from "js-yaml";
4
4
  import { defaultScheduleCalendar, buildScheduleIndex } from "./exec-schedule-index.js";
5
5
  import { addWorkingDaysToDate } from "./exec-schedule-calendar.js";
6
- import { readJson, toArtifactPath } from "./exec-shared.js";
6
+ import { readJson, stripTerminalControlSequences, toArtifactPath } from "./exec-shared.js";
7
7
  import { readAllEventFiles } from "./exec-events.js";
8
8
  import { getProjectExecutionPath, getProjectRoutinesPath, getProjectSchedulePath, getProjectTimelinePath, loadConfig, loadEnv, specdojoRootDir, } from "./specdojo-config.js";
9
9
  import { resolveRegisterPaths, loadRegisterItems, } from "./register.js";
@@ -603,8 +603,18 @@ function routineScheduleLabel(doc) {
603
603
  // ================================
604
604
  // Markdown rendering
605
605
  // ================================
606
- function escapeCell(text) {
607
- return text.replace(/\|/g, "\\|").replace(/\n/g, " ").trim();
606
+ const MAX_DASHBOARD_CELL_LENGTH = 200;
607
+ // dashboard の表へは event や subprocess 由来の文字列も入る。表へ埋める直前に
608
+ // ターミナル制御シーケンスと改行類を除き、列区切りをエスケープして長さを制限する。
609
+ export function sanitizeDashboardCell(text) {
610
+ const singleLine = stripTerminalControlSequences(text)
611
+ .replace(/[\t\r\n]+/g, " ")
612
+ .replace(/ +/g, " ")
613
+ .trim();
614
+ const truncated = singleLine.length <= MAX_DASHBOARD_CELL_LENGTH
615
+ ? singleLine
616
+ : `${singleLine.slice(0, MAX_DASHBOARD_CELL_LENGTH)}…`;
617
+ return truncated.replace(/\|/g, "\\|");
608
618
  }
609
619
  const STATUS_ORDER = [
610
620
  "open",
@@ -721,7 +731,7 @@ function renderTimelineSection(paths) {
721
731
  const row = schedule.find((s) => s.track === tk.track);
722
732
  if (!row)
723
733
  continue;
724
- lines.push(`| ${wave.wave} | \`${tk.track}\` | \`${tk.catalog_status}\` | ${formatEstimate(tk)} | ${row.startDate ?? "-"} | ${row.endDate ?? "-"} | ${escapeCell(row.parallel_group ?? "-")} | ${escapeCell(row.depends_on.join(", ") || "-")} |`);
734
+ lines.push(`| ${wave.wave} | \`${tk.track}\` | \`${tk.catalog_status}\` | ${formatEstimate(tk)} | ${row.startDate ?? "-"} | ${row.endDate ?? "-"} | ${sanitizeDashboardCell(row.parallel_group ?? "-")} | ${sanitizeDashboardCell(row.depends_on.join(", ") || "-")} |`);
725
735
  }
726
736
  }
727
737
  lines.push("");
@@ -776,7 +786,7 @@ function renderRoutineSection(paths) {
776
786
  lines.push("| id | name | enabled | 間隔 / cron | kind | 最終実行 / 結果 | due |");
777
787
  lines.push("| --- | --- | --- | --- | --- | --- | :---: |");
778
788
  for (const row of agg.rows) {
779
- lines.push(`| \`${row.id}\` | ${escapeCell(row.name ?? "-")} | ${row.enabled ? "enabled" : "disabled"} | \`${escapeCell(row.schedule)}\` | \`${row.kind}\` | ${escapeCell(row.lastRun)} | ${row.due} |`);
789
+ lines.push(`| \`${row.id}\` | ${sanitizeDashboardCell(row.name ?? "-")} | ${row.enabled ? "enabled" : "disabled"} | \`${sanitizeDashboardCell(row.schedule)}\` | \`${row.kind}\` | ${sanitizeDashboardCell(row.lastRun)} | ${row.due} |`);
780
790
  }
781
791
  lines.push("");
782
792
  return lines;
@@ -826,7 +836,7 @@ function renderGradeSection(paths) {
826
836
  }
827
837
  lines.push("| 成果物 | 対象 | verdict | score | findings |", "| --- | --- | --- | ---: | ---: |");
828
838
  for (const result of results) {
829
- lines.push(`| \`${escapeCell(result.document)}\` | \`${result.target}\` | \`${result.verdict}\` | ${result.score} | ${gradeFindingCount(result)} |`);
839
+ lines.push(`| \`${sanitizeDashboardCell(result.document)}\` | \`${result.target}\` | \`${result.verdict}\` | ${result.score} | ${gradeFindingCount(result)} |`);
830
840
  }
831
841
  lines.push("");
832
842
  return lines;
@@ -858,7 +868,7 @@ function renderRecommendedRegisterSection(projectId) {
858
868
  : dueMs < todayMs
859
869
  ? `期日超過 ${Math.ceil((todayMs - dueMs) / 86_400_000)}日`
860
870
  : `期日まで ${Math.ceil((dueMs - todayMs) / 86_400_000)}日`;
861
- lines.push(`| ${index + 1} | \`${row.id}\` | \`${row.type}\` | ${escapeCell(row.title)} | ${row.due} | \`${row.priority}\` | ${row.relatedOpenPjrCount} | ${row.registeredAt} | ${dueReason}、優先度 ${row.priority}、関連 open PJR ${row.relatedOpenPjrCount}件 |`);
871
+ lines.push(`| ${index + 1} | \`${row.id}\` | \`${row.type}\` | ${sanitizeDashboardCell(row.title)} | ${row.due} | \`${row.priority}\` | ${row.relatedOpenPjrCount} | ${row.registeredAt} | ${dueReason}、優先度 ${row.priority}、関連 open PJR ${row.relatedOpenPjrCount}件 |`);
862
872
  });
863
873
  lines.push("");
864
874
  return lines;
@@ -874,7 +884,7 @@ function renderAttentionSection(paths) {
874
884
  lines.push("| 種別 | id | 理由 | 次の行動 |");
875
885
  lines.push("| --- | --- | --- | --- |");
876
886
  for (const row of rows) {
877
- lines.push(`| ${row.source} | \`${row.id}\` | ${escapeCell(row.reason)} | ${escapeCell(row.nextAction)} |`);
887
+ lines.push(`| ${row.source} | \`${row.id}\` | ${sanitizeDashboardCell(row.reason)} | ${sanitizeDashboardCell(row.nextAction)} |`);
878
888
  }
879
889
  }
880
890
  catch (error) {
@@ -26,17 +26,26 @@ export async function isPrettierIgnored(filePath) {
26
26
  const info = await getFileInfo(path.resolve(filePath), { ignorePath });
27
27
  return info.ignored;
28
28
  }
29
+ function normalizeTrailingNewline(source) {
30
+ return `${source.replace(/[\r\n]+$/u, "")}\n`;
31
+ }
29
32
  export async function formatMarkdownFile(filePath) {
30
33
  try {
31
- if (await isPrettierIgnored(filePath))
32
- return;
33
34
  const source = await readFile(filePath, "utf8");
35
+ const normalized = normalizeTrailingNewline(source);
36
+ // exec の plan / result は本文保護のため Prettier 対象外だが、runner が生成する
37
+ // Markdown として末尾改行だけは同じ書き出し経路で必ず正規化する。
38
+ if (await isPrettierIgnored(filePath)) {
39
+ if (normalized !== source)
40
+ await writeFile(filePath, normalized, "utf8");
41
+ return;
42
+ }
34
43
  const config = await resolveConfig(filePath);
35
- const formatted = await format(source, {
44
+ const formatted = await format(normalized, {
36
45
  ...(config ?? {}),
37
46
  filepath: filePath,
38
47
  });
39
- await writeFile(filePath, formatted, "utf8");
48
+ await writeFile(filePath, normalizeTrailingNewline(formatted), "utf8");
40
49
  }
41
50
  catch (error) {
42
51
  const cause = error instanceof Error ? `: ${error.message}` : "";
@@ -1,3 +1,4 @@
1
+ import { readFileSync } from "node:fs";
1
2
  import path from "node:path";
2
3
  import { fileURLToPath } from "node:url";
3
4
  // このモジュールは開発時は src/、npm 配布時は dist/ 直下にある。
@@ -7,9 +8,26 @@ import { fileURLToPath } from "node:url";
7
8
  // 持たない構成では、モジュール位置から求めた package が自動で参照されるため、単体テストの
8
9
  // 一時ディレクトリが開発リポジトリの kata へ解決されてしまう。テストと検証では、この変数へ
9
10
  // 一時ディレクトリを指定して解決範囲を閉じる。
11
+ function moduleRelativePackageRoot() {
12
+ return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
13
+ }
10
14
  export function specdojoPackageRootDir() {
11
15
  const override = process.env.SPECDOJO_PACKAGE_ROOT;
12
16
  if (override && override.trim() !== "")
13
17
  return path.resolve(override);
14
- return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
18
+ return moduleRelativePackageRoot();
19
+ }
20
+ function isRecord(value) {
21
+ return typeof value === "object" && value !== null && !Array.isArray(value);
22
+ }
23
+ // CLI が報告する版。`package.json` を唯一の出所とし、`npm version` の更新へ自動で追従する。
24
+ // SPECDOJO_PACKAGE_ROOT は kata の参照先を差し替えるための変数であり、実行中の CLI 自身の
25
+ // 版とは無関係なため、ここでは参照しない。
26
+ export function specdojoPackageVersion() {
27
+ const packageJsonPath = path.join(moduleRelativePackageRoot(), "package.json");
28
+ const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
29
+ if (isRecord(parsed) && typeof parsed.version === "string" && parsed.version !== "") {
30
+ return parsed.version;
31
+ }
32
+ throw new Error(`version を読み取れません: ${packageJsonPath}`);
15
33
  }
@@ -198,7 +198,7 @@ export function registerConfigCommands(program) {
198
198
  cfg
199
199
  .command("scaffold")
200
200
  .description("Scaffold agent/settings templates for a provider")
201
- .requiredOption("--provider <name>", "Provider template to copy (claude|codex|copilot|opencode)")
201
+ .requiredOption("--provider <name>", "Provider template to copy (antigravity|claude|codex|copilot|opencode)")
202
202
  .option("--force", "Overwrite existing files", false)
203
203
  .option("--dry-run", "Show planned files without writing", false)
204
204
  .action(async (opts) => {
package/dist/specdojo.js CHANGED
@@ -2,6 +2,7 @@
2
2
  import { fileURLToPath } from "node:url";
3
3
  import { Command } from "commander";
4
4
  import { evaluateDistFreshness, inspectDistEntryFreshness } from "./dist-freshness.js";
5
+ import { specdojoPackageVersion } from "./package-paths.js";
5
6
  import { registerConfigCommands, registerProjectCommands } from "./specdojo-config.js";
6
7
  import { registerExecCommands } from "./exec.js";
7
8
  import { registerCatalogCommands } from "./catalog.js";
@@ -37,7 +38,7 @@ async function main() {
37
38
  return;
38
39
  }
39
40
  const program = new Command();
40
- program.name("specdojo").description("SpecDojo helper CLI").version("0.4.0");
41
+ program.name("specdojo").description("SpecDojo helper CLI").version(specdojoPackageVersion());
41
42
  registerConfigCommands(program);
42
43
  registerProjectCommands(program);
43
44
  registerExecCommands(program);
@@ -46,8 +46,7 @@ mkdir app1-specdojo app1-worktrees
46
46
  git -C app1-specdojo init
47
47
  cd app1-specdojo
48
48
  npm init -y
49
- npm install specdojo
50
- npm install --save-dev @specdojo/docs-lint
49
+ npm install --save-dev specdojo @specdojo/docs-lint
51
50
  # チャット:「<project-id> の SpecDojo 設定を初期化して」
52
51
  npx specdojo config init
53
52
  ```
@@ -0,0 +1,163 @@
1
+ ---
2
+ specdojo:
3
+ id: specdojo:remote-host-development-guide
4
+ type: guide
5
+ status: draft
6
+ ---
7
+
8
+ # 常時稼働ホスト運用ガイド
9
+
10
+ Remote Host Development Guide
11
+
12
+ agent の実行を止めずに開発を続けるため、常時稼働するホストへリモート接続して作業する構成例を示します。この文書は特定の製品構成を推奨するものではなく、**構成例**です。
13
+
14
+ **対象読者**
15
+
16
+ - `routine` の定期実行や長時間の `exec run` を、作業端末の状態に依存せず継続したい開発者
17
+
18
+ **この文書で分かること**
19
+
20
+ - なぜ常時稼働ホストが要るか、どの部分がどの機能に対応するか、切断と再接続の扱い
21
+
22
+ **次に読む文書**
23
+
24
+ - 定期実行の設定は [routine運用ガイド](routine-operation-guide.md)、agent の実行設定は [exec設定ガイド](exec-config-guide.md) を参照してください。
25
+
26
+ ## 1. なぜ常時稼働ホストが要るか
27
+
28
+ SpecDojo は自律実行を前提とします。次の 2 つが作業端末の状態に依存します。
29
+
30
+ | 機能 | 依存 |
31
+ | -------------------------------- | ------------------------------------------------------------ |
32
+ | `routine`(`routine run --due`) | cron などの定期実行。ホストが動いていないと起動しない |
33
+ | `exec run` | 1 回あたり数分から数十分。完了前に端末が切断されると中断する |
34
+
35
+ ノート PC で作業する場合、蓋を閉じる、スリープする、移動する、といった操作で実行が止まります。作業端末とは別に、**動き続けるホストで実行する**構成にすると、この依存が切れます。
36
+
37
+ `exec run --worktree` は worktree を保持するため、中断しても `--resume` で再開できます。ただし再開の操作は人が行う必要があり、夜間の `routine` では翌朝まで止まります。
38
+
39
+ ## 2. 構成の要素
40
+
41
+ 次の 4 つを組み合わせます。いずれも SpecDojo の機能ではなく、一般的なツールです。
42
+
43
+ | 要素 | 役割 | 代替 |
44
+ | -------------------- | -------------------------- | ---------------------------------------------- |
45
+ | 常時稼働ホスト | 実行の場所 | 手元のデスクトップ、自宅サーバ、クラウドの VM |
46
+ | ネットワーク到達手段 | 外出先からホストへ接続する | Tailscale、WireGuard、VPN、ポート開放 + 鍵認証 |
47
+ | 端末多重化 | 切断しても shell を保つ | tmux、GNU Screen、Zellij |
48
+ | 実行環境 | 依存とツールを固定する | devcontainer、ローカルの Node.js 環境 |
49
+
50
+ この文書では Tailscale + SSH + tmux + devcontainer の組み合わせを例にしますが、役割が満たせれば置き換えて構いません。
51
+
52
+ ## 3. 構成例
53
+
54
+ ```text
55
+ 作業端末(任意の場所)
56
+ └─ SSH(Tailscale などの到達手段)
57
+ └─ 常時稼働ホスト
58
+ └─ tmux セッション
59
+ └─ devcontainer
60
+ └─ specdojo exec run / routine
61
+ ```
62
+
63
+ 要点は、**SpecDojo の実行を tmux セッションの中で開始する**ことです。SSH が切れても tmux のセッションは残り、再接続して同じ状態へ戻れます。
64
+
65
+ ## 4. 切断と再接続
66
+
67
+ ### 4.1. セッションへ入る
68
+
69
+ 接続のたびに新規作成せず、既存があればそれへ入ります。
70
+
71
+ ```bash
72
+ tmux new-session -A -s specdojo
73
+ ```
74
+
75
+ `-A` は「あれば attach、なければ作成」です。セッション名を固定すると、複数端末から同じ場所へ戻れます。
76
+
77
+ ### 4.2. 実行はセッションの中で始める
78
+
79
+ ```bash
80
+ tmux new-session -A -s specdojo
81
+ npx specdojo exec run --project <project-id> --register <PJR-XXXX> --worktree
82
+ ```
83
+
84
+ エディタの統合ターミナルで直接実行すると、エディタの接続が切れた時点で終了する場合があります。長時間の実行は tmux の中で始めます。
85
+
86
+ ### 4.3. 切断された実行の扱い
87
+
88
+ 再接続しても、実行中だった処理が自動で再開されるわけではありません。
89
+
90
+ | 対象 | 再開方法 |
91
+ | -------------------------- | ------------------------------------------------------------ |
92
+ | `exec run --worktree` | `exec run --register <id> --resume --worktree` |
93
+ | agent CLI の対話セッション | CLI ごとの再開機能(会話履歴は各 CLI が保持する) |
94
+ | `routine` | 次の起動時刻を待つか、`routine run --id <id>` で明示実行する |
95
+
96
+ `exec run` は worktree と pipeline の状態を保持するため、executor が完了していれば reporter 段だけを再開できます。
97
+
98
+ ### 4.4. セッションが消える場合
99
+
100
+ 実行環境を作り直すとセッションも消えます。
101
+
102
+ | 操作 | tmux セッション |
103
+ | ------------------------ | --------------- |
104
+ | SSH の切断・再接続 | 残る |
105
+ | エディタの再接続 | 残る |
106
+ | コンテナの再起動・再作成 | **消える** |
107
+
108
+ コンテナを作り直す前に、実行中の処理がないことを確認します。
109
+
110
+ ## 5. 定期実行
111
+
112
+ `routine` はホスト側で動き続ける必要があります。cron を使う場合、実行環境の中で cron を動かし、コンテナ停止時に定期実行も止まることを前提にします。
113
+
114
+ ```cron
115
+ 0 * * * * cd /path/to/project && npx specdojo routine run --due >> /var/log/specdojo-routine.log 2>&1
116
+ ```
117
+
118
+ 設定の詳細は [routine運用ガイド](routine-operation-guide.md) を参照してください。取りこぼした実行枠の扱い(`missed_run`)と重複起動の扱い(`overlap`)は routine 定義で指定します。
119
+
120
+ ## 6. 既知の制限
121
+
122
+ ### 6.1. 入れ子のリモート接続でポート転送が届かない
123
+
124
+ 「作業端末 → SSH → ホスト → コンテナ」という入れ子構成では、エディタが動的に張るポート転送が作業端末まで届かないことがあります。エディタ側の転送機能は、エディタを起動している接続にのみ有効なためです。
125
+
126
+ 対処として、コンテナ側で固定ポートを公開し、SSH の local forwarding で転送します。
127
+
128
+ ```text
129
+ # ~/.ssh/config
130
+ Host <ホスト名>
131
+ LocalForward 5173 127.0.0.1:5173
132
+ ```
133
+
134
+ `LocalForward` はその設定を持つ SSH 接続にだけ有効です。tmux セッションへ直接入る接続用のエントリを別に作っている場合は、そちら側へ設定します。この方式は SSH 接続が張られている間有効で、エディタの起動有無に依存しません。
135
+
136
+ ### 6.2. 実行環境の起動に失敗する
137
+
138
+ SSH 経由の非対話シェルでは `PATH` が対話シェルと異なることがあり、コンテナ起動用のコマンドが見つからない場合があります。接続元から次を実行して確認します。
139
+
140
+ ```bash
141
+ ssh <ホスト名> 'printf "PATH=%s\n" "$PATH"; command -v node || true'
142
+ ```
143
+
144
+ ## 7. 運用上のセキュリティ
145
+
146
+ この構成は、常時稼働ホストを外部から到達可能にします。次を守ります。
147
+
148
+ - ネットワーク到達手段は認証付きのものを使う。SSH を公開する場合は鍵認証のみとし、パスワード認証を無効にする。
149
+ - API key、SSH 秘密鍵、tailnet 名などをターミナルの scrollback やコマンド履歴へ残さない。
150
+ - agent の認証状態は秘密情報として扱う。リポジトリや設定ファイルへ書かない。
151
+ - agent の権限を広げる指定(全ツール許可、権限確認の省略、完全アクセス)は通常運用で使わない。境界は worktree、保護設定、commit 許可リストで作る。詳細は [exec設定ガイド](exec-config-guide.md) を参照してください。
152
+
153
+ 常時稼働させる以上、ホスト自体の更新と監視は利用者の責任範囲です。
154
+
155
+ ## 8. この構成を採らない選択
156
+
157
+ 常時稼働ホストは必須ではありません。次の場合は不要です。
158
+
159
+ - `routine` を使わず、`exec run` を都度実行する
160
+ - 実行のたびに完了まで端末を開いたままにできる
161
+ - `register` だけを使い、agent 実行を行わない
162
+
163
+ `register` の起票・状態遷移・生成物の再構築はいずれも短時間で完了するため、この構成を前提としません。
@@ -621,7 +621,7 @@ specdojo exec worktree prune --project prj-0001
621
621
  | `watch` | ファイル変更を監視して対象 build を実行する | `specdojo watch --project prj-0001 --scope exec` |
622
622
  | `build` | 全生成物または指定 scope を一括再生成する | `specdojo build --project prj-0001 --scope all` |
623
623
 
624
- `dashboard build --project <id>` は `execution/generated/dashboard.md` を再生成します。通常の進捗集計に加え、`routines/generated/routine-runs.jsonl` から昨日の実行と本日の予定を、登録簿個票から着手候補のおすすめ順を、register / exec の event から解除待ちの理由と次の行動を表示します。
624
+ `dashboard build --project <id>` は `execution/generated/dashboard.md` を再生成します。通常の進捗集計に加え、`routines/generated/routine-runs.jsonl` から昨日の実行と本日の予定を、登録簿個票から着手候補のおすすめ順を、register / exec の event から解除待ちの理由と次の行動を表示します。解除待ちの理由は、制御文字を除いた 1 行へ整形し、表の区切り文字をエスケープしたうえで、長い値を省略記号付きで打ち切ります。
625
625
 
626
626
  `--scope` は `exec`、`catalog`、`register`、`index`、`all` を指定します。
627
627
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "specdojo",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "SpecDojo CLI, schemas, and documentation for specification-driven execution workflows.",
5
5
  "license": "MIT",
6
6
  "author": "naoji3x",
@@ -79,6 +79,7 @@
79
79
  "lint:ts": "eslint 'src/**/*.ts' 'tests/**/*.ts' 'packages/docs-lint/src/**/*.ts' 'tools/e2e/**/*.ts'",
80
80
  "lint:ts:fix": "eslint --fix 'src/**/*.ts' 'tests/**/*.ts' 'packages/docs-lint/src/**/*.ts' 'tools/e2e/**/*.ts'",
81
81
  "lint:orchestrator-sync": "node tools/validate-orchestrator-sync.mjs",
82
+ "orchestrator:sync": "node tools/generate-orchestrator-wrappers.mjs",
82
83
  "lint:md": "node packages/docs-lint/bin/specdojo-docs-lint.js markdownlint '**/*.md'",
83
84
  "lint:md:fix": "node packages/docs-lint/bin/specdojo-docs-lint.js markdownlint --fix '**/*.md'",
84
85
  "format": "prettier --write '**/*.{ts,js,mjs,cjs,json,yaml,yml,md}'",
@@ -0,0 +1,35 @@
1
+ # Antigravity 向け配布原本
2
+
3
+ `npx specdojo config scaffold --provider antigravity` が配置するファイルの原本です。この README 自体はコピーされません。
4
+
5
+ ## 配置されるもの
6
+
7
+ | 原本 | 配置先 |
8
+ | ---------------------------- | -------------------------------------------------- |
9
+ | `orchestrator.md` | `.specdojo/antigravity/orchestrator.md` |
10
+ | `exec-defaults-snippet.yaml` | `.specdojo/antigravity/exec-defaults-snippet.yaml` |
11
+ | `pm-members-snippet.yaml` | `.specdojo/antigravity/pm-members-snippet.yaml` |
12
+
13
+ ## オーケストレーターの起動
14
+
15
+ Antigravity CLI(`agy`)はファイル定義の agent を持たないため、`--agent <name>` では起動できません。規範の本文を `-i` で渡します。
16
+
17
+ ```sh
18
+ agy --add-dir "$(pwd)" --model gemini-3.1-pro-high -i "$(cat .specdojo/antigravity/orchestrator.md)"
19
+ ```
20
+
21
+ `--add-dir "$(pwd)"` を付けないと、作業ディレクトリのファイルを読み書きできず、`AGENTS.md` と `.agents/rules/*.md` も読み込まれません。
22
+
23
+ `package.json` へ登録しておくと短く起動できます。
24
+
25
+ ```json
26
+ {
27
+ "scripts": {
28
+ "orch:agy": "agy --add-dir \"$(pwd)\" --model gemini-3.1-pro-high -i \"$(cat .specdojo/antigravity/orchestrator.md)\""
29
+ }
30
+ }
31
+ ```
32
+
33
+ ## executor / reporter として使う
34
+
35
+ `exec-defaults-snippet.yaml` を `.specdojo/exec-defaults.yaml` の `providers` へ、`pm-members-snippet.yaml` を `pm-members.yaml` の `members` へ写します。モデル ID は推論強度を含むため、`--effort` を併用すると起動に失敗します。
@@ -0,0 +1,38 @@
1
+ # Antigravity CLI(agy)provider 設定のスニペット。
2
+ # 利用プロジェクトの .specdojo/exec-defaults.yaml の providers へコピーして使う。
3
+ # by_nickname は member ごとにモデルを差し替える層で、Gemini 以外のモデルを
4
+ # 指名するために使う。不要な member の行は削除してよい。
5
+ # 設計の背景は sysd-antigravity-agent-settings と exec-config-guide.md を参照。
6
+
7
+ providers:
8
+ antigravity:
9
+ # Antigravity CLI(agy)は --agent による定義ファイルの選択を持たず、codex と同じく
10
+ # プロンプト(plan)だけで役割を与える。-p はプロンプトを引数に取り stdin を読まないため、
11
+ # runner が stdin へ書く plan を "$(cat)" で引数に渡す(shell: true で実行される)。
12
+ # --sandbox は書き込み先を ~/.gemini 配下の scratch へ逃がすため、--add-dir で作業
13
+ # ディレクトリ(worktree)を明示して成果物へ書けるようにする(2026-09-21 実測)。
14
+ # --dangerously-skip-permissions は非対話実行に必須。境界は worktree・保護設定・
15
+ # commit 許可リストで作る。
16
+ # agy のモデル ID は推論強度を含む(gemini-3.8-flash-{high,medium,low} など)。--effort を
17
+ # 併用すると ID と食い違ったときに "invalid model selection" で起動に失敗するため、
18
+ # 強度はモデル ID だけで指定する(2026-09-21 実測: flash-high + --effort medium で失敗)。
19
+ command_template: 'agy --sandbox --add-dir "$(pwd)" --dangerously-skip-permissions --model {model} -p "$(cat)"'
20
+ command_params:
21
+ by_proficiency:
22
+ normal: { model: gemini-3.8-flash-medium }
23
+ expert: { model: gemini-3.1-pro-high }
24
+ # Gemini 以外の Antigravity 提供モデルは member nickname で明示的に選ぶ。
25
+ # by_nickname は proficiency / mode の既定値より優先される。
26
+ by_nickname:
27
+ agy-sonnet-executor: { model: claude-sonnet-4-6 }
28
+ agy-opus-executor: { model: claude-opus-4-6-thinking }
29
+ agy-opus-review-executor: { model: claude-opus-4-6-thinking }
30
+ agy-gpt-executor: { model: gpt-oss-120b-medium }
31
+ # Gemini API の制限文言は未観測。429 / quota / RESOURCE_EXHAUSTED を初期値とし、
32
+ # 実観測した文言で更新する(observed-agent-limit-stderr と同じ扱い)。
33
+ rate_limit_detection:
34
+ stderr_patterns:
35
+ - "rate limit"
36
+ - "429"
37
+ - "quota"
38
+ - "RESOURCE_EXHAUSTED"