sdd-forge 0.1.0-alpha.8 → 0.1.0-alpha.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-forge",
-  "version": "0.1.0-alpha.8",
+  "version": "0.1.0-alpha.9",
   "description": "Spec-Driven Development tooling for automated documentation generation",
   "type": "module",
   "bin": {

package/src/docs/commands/agents.js

@@ -10,10 +10,10 @@
 
 import fs from "fs";
 import path from "path";
-import { execFileSync } from "child_process";
 import { fileURLToPath } from "url";
 import { sourceRoot, repoRoot, parseArgs } from "../../lib/cli.js";
 import { loadJsonFile, loadConfig, resolveProjectContext } from "../../lib/config.js";
+import { callAgent } from "../../lib/agent.js";
 
 const PKG_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 
@@ -45,45 +45,33 @@ function loadAgentConfig(cfg, agentName) {
   return provider;
 }
 
-function callAgent(agent, prompt, timeoutMs) {
-  const args = Array.isArray(agent.args) ? [...agent.args] : [];
-  const resolvedArgs = args.map((a) =>
-    typeof a === "string" ? a.replaceAll("{{PROMPT}}", prompt) : a
-  );
-  const hasToken = args.some((a) => typeof a === "string" && a.includes("{{PROMPT}}"));
-  const finalArgs = hasToken ? resolvedArgs : [...resolvedArgs, prompt];
-
-  const env = { ...process.env };
-  delete env.CLAUDECODE;
-
-  return execFileSync(agent.command, finalArgs, {
-    encoding: "utf8",
-    maxBuffer: 20 * 1024 * 1024,
-    timeout: timeoutMs,
-    env,
-  }).trim();
-}
-
 // ---------------------------------------------------------------------------
 // AI 要約プロンプト構築
 // ---------------------------------------------------------------------------
 
+/**
+ * agents コマンド用のシステムプロンプトを構築する。
+ * 出力ルール（PROJECT タグ形式、構造要件）を含む。
+ */
+function buildAgentsSystemPrompt() {
+  return [
+    "以下のソースコード解析データ (analysis.json) を要約し、AGENTS.md の Project Context セクションを生成してください。",
+    "",
+    "## 出力ルール（厳守）",
+    "- <!-- PROJECT:START --> と <!-- PROJECT:END --> タグで囲むこと",
+    "- 最初の行は `<!-- PROJECT:START — managed by sdd-forge. Do not edit manually. -->` とすること",
+    "- 最後の行は `<!-- PROJECT:END -->` とすること",
+    "- `## Project Context` の見出しで始めること",
+    "- AI エージェントがプロジェクトを理解するのに役立つ情報を構造的にまとめること",
+    "- 技術スタック、プロジェクト構造の概要、主要コンポーネント、DB 構成、利用可能なコマンドを含めること",
+    "- マークダウンのテーブルやリストを活用して読みやすくすること",
+    "- 前置き・メタコメンタリーは含めないこと",
+  ].join("\n");
+}
+
 function buildSummaryPrompt(analysis, config, srcRoot) {
   const parts = [];
 
-  parts.push("以下のソースコード解析データ (analysis.json) を要約し、AGENTS.md の Project Context セクションを生成してください。");
-  parts.push("");
-  parts.push("## 出力ルール（厳守）");
-  parts.push("- <!-- PROJECT:START --> と <!-- PROJECT:END --> タグで囲むこと");
-  parts.push("- 最初の行は `<!-- PROJECT:START — managed by sdd-forge. Do not edit manually. -->` とすること");
-  parts.push("- 最後の行は `<!-- PROJECT:END -->` とすること");
-  parts.push("- `## Project Context` の見出しで始めること");
-  parts.push("- AI エージェントがプロジェクトを理解するのに役立つ情報を構造的にまとめること");
-  parts.push("- 技術スタック、プロジェクト構造の概要、主要コンポーネント、DB 構成、利用可能なコマンドを含めること");
-  parts.push("- マークダウンのテーブルやリストを活用して読みやすくすること");
-  parts.push("- 前置き・メタコメンタリーは含めないこと");
-  parts.push("");
-
   // config info
   if (config.type) {
     parts.push(`## プロジェクト設定`);
@@ -313,10 +301,11 @@ function main() {
     }
 
     console.error("[agents] generating PROJECT section with AI...");
+    const systemPrompt = buildAgentsSystemPrompt();
     const prompt = buildSummaryPrompt(analysis, config, srcRoot);
 
     try {
-      const result = callAgent(agent, prompt, 180000);
+      const result = callAgent(agent, prompt, 180000, undefined, { systemPrompt });
 
       // Extract PROJECT section from AI response
       const projectMatch = result.match(/<!-- PROJECT:START[^>]*-->[\s\S]*?<!-- PROJECT:END -->/);

package/src/docs/commands/forge.js

@@ -12,6 +12,7 @@
  */
 
 import fs from "fs";
+import os from "os";
 import path from "path";
 import readline from "readline";
 import { execFile, spawn } from "child_process";
@@ -28,11 +29,12 @@ import { createResolver } from "../lib/resolver-factory.js";
 // パッケージディレクトリを保持する
 const PKG_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 
-const DEFAULT_AGENT_TIMEOUT_MS = 600000;
+const DEFAULT_AGENT_TIMEOUT_MS = 300000;
 const DEFAULT_WAIT_LOG_SEC = 1;
 const DEFAULT_MAX_RUNS = 3;
 const DEFAULT_REVIEW_CMD = "sdd-forge review";
 const DEFAULT_MODE = "local";
+const DEFAULT_CONCURRENCY = 3;
 
 function getTargetFiles(root) {
   const docsDir = path.join(root, "docs");
@@ -152,8 +154,8 @@ function printHelp() {
       "  --prompt <text>        開始プロンプト",
       "  --prompt-file <path>   開始プロンプトファイル",
       "  --spec <path>          入力仕様書（spec.md）",
-      "  --max-runs <n>         反復回数 (default: 5)",
-      "  --review-cmd <cmd>     docs レビューコマンド (default: npm run sdd:review)",
+      "  --max-runs <n>         反復回数 (default: 3)",
+      "  --review-cmd <cmd>     docs レビューコマンド (default: sdd-forge review)",
       "  --agent <name>         AIエージェント: codex|claude (default: config.json の defaultAgent)",
       "  --mode <mode>          実行モード: local|assist|agent (default: local)",
       "  --dry-run              ファイル書き込み・review・agent 呼び出しをスキップ（1 ラウンドで終了）",
@@ -161,27 +163,59 @@ function printHelp() {
       "  -v, --verbose          エージェント実行ログを逐次表示",
       "  -h, --help             このヘルプを表示",
       "",
-      "NEEDS_INPUT:",
-      "  追加情報が必要な場合、AI は次形式で出力すること:",
-      "  NEEDS_INPUT",
-      "  - 質問1",
-      "  - 質問2",
+      "Per-file mode:",
+      "  provider に systemPromptFlag が設定されている場合、ファイルごとに非同期で agent を呼び出します。",
+      "  同時実行数は config.json の limits.concurrency で設定可能（default: 3）。",
       "",
     ].join("\n")
   );
 }
 
-function buildArgs(agent, prompt) {
+function buildArgs(agent, prompt, systemPrompt) {
   const args = Array.isArray(agent.args) ? [...agent.args] : [];
+
+  // Prepend system prompt flag if provider supports it and systemPrompt given
+  const flag = agent.systemPromptFlag;
+  let prefix = [];
+  let cleanupFile;
+  if (flag && systemPrompt) {
+    if (flag === "--system-prompt-file") {
+      // Write to temp file for providers that require file-based system prompts
+      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sdd-forge-"));
+      const tmpFile = path.join(tmpDir, "system-prompt.md");
+      fs.writeFileSync(tmpFile, systemPrompt, "utf8");
+      prefix = [flag, tmpFile];
+      cleanupFile = tmpFile;
+    } else {
+      prefix = [flag, systemPrompt];
+    }
+  }
+
   const hasToken = args.some(
     (a) => typeof a === "string" && a.includes("{{PROMPT}}")
   );
+  let finalArgs;
   if (hasToken) {
-    return args.map((a) =>
+    finalArgs = args.map((a) =>
       typeof a === "string" ? a.replaceAll("{{PROMPT}}", prompt) : a
     );
+  } else {
+    finalArgs = [...args, prompt];
   }
-  return [...args, prompt];
+
+  // If systemPromptFlag not set but systemPrompt given, prepend to prompt
+  if (!flag && systemPrompt) {
+    const combined = systemPrompt + "\n\n" + prompt;
+    if (hasToken) {
+      finalArgs = (Array.isArray(agent.args) ? [...agent.args] : []).map((a) =>
+        typeof a === "string" ? a.replaceAll("{{PROMPT}}", combined) : a
+      );
+    } else {
+      finalArgs = [...(Array.isArray(agent.args) ? [...agent.args] : []), combined];
+    }
+  }
+
+  return { args: [...prefix, ...finalArgs], cleanupFile };
 }
 
 function runAgent(agent, prompt, options = {}) {
@@ -198,7 +232,13 @@ function runAgent(agent, prompt, options = {}) {
     options.label || agent?.name || agent?.command || "agent"
   );
   const streamOutput = options.streamOutput === true;
-  const args = buildArgs(agent, prompt);
+  const { args, cleanupFile } = buildArgs(agent, prompt, options.systemPrompt);
+
+  function cleanup() {
+    if (cleanupFile) {
+      try { fs.unlinkSync(cleanupFile); fs.rmdirSync(path.dirname(cleanupFile)); } catch (_) {}
+    }
+  }
 
   return new Promise((resolve, reject) => {
     const ticker =
@@ -239,12 +279,14 @@ function runAgent(agent, prompt, options = {}) {
       child.on("error", (err) => {
         if (ticker) clearInterval(ticker);
         clearTimeout(timeoutTimer);
+        cleanup();
         reject(new Error(`Agent failed: ${agent.command}\n${err.message}`));
       });
 
       child.on("close", (code, signal) => {
         if (ticker) clearInterval(ticker);
         clearTimeout(timeoutTimer);
+        cleanup();
         if (code === 0 && !signal) {
           resolve(stdoutBuf.trim());
           return;
@@ -272,6 +314,7 @@ function runAgent(agent, prompt, options = {}) {
       { maxBuffer: 20 * 1024 * 1024, timeout: timeoutMs, cwd: runCwd },
       (err, stdout, stderr) => {
         if (ticker) clearInterval(ticker);
+        cleanup();
         if (err) {
           const timedOut = err.killed === true;
           reject(
@@ -476,6 +519,57 @@ function summarizeNeedsInput(reviewOut) {
   return uniq.slice(0, 8);
 }
 
+/**
+ * Build the system prompt (shared across all files in a round).
+ * Contains: role, rules, user request, spec, analysis summary.
+ */
+function buildForgeSystemPrompt({
+  userPrompt,
+  specPath,
+  specText,
+  analysisSummary,
+}) {
+  const specBlock = specPath
+    ? ["[SPEC_PATH]", specPath, "", "[SPEC_CONTENT]", specText || "(empty)", ""]
+    : [];
+  return [
+    "あなたは docs-forge です。指定されたドキュメントファイルの品質を改善してください。",
+    "",
+    "[USER_PROMPT]",
+    userPrompt,
+    "",
+    ...specBlock,
+    "[RULES]",
+    "- 編集対象は指定された TARGET_FILE のみ",
+    "- 推測は避け、ソースコードの事実を優先",
+    "- 変更は必要最小限にする",
+    "- 説明文は簡潔で主語を明確にする",
+    "- 不明な場合は編集せずスキップする",
+    "",
+    ...(analysisSummary
+      ? ["[SOURCE_ANALYSIS]", analysisSummary, ""]
+      : []),
+  ].join("\n");
+}
+
+/**
+ * Build the user prompt for a single file.
+ */
+function buildForgeFilePrompt({ targetFile, round, maxRuns, reviewFeedback }) {
+  return [
+    `round: ${round}/${maxRuns}`,
+    "",
+    "[TARGET_FILE]",
+    targetFile,
+    "",
+    "[PREVIOUS_REVIEW_FEEDBACK]",
+    reviewFeedback || "なし",
+  ].join("\n");
+}
+
+/**
+ * Build a combined prompt (for providers without system prompt support).
+ */
 function buildForgePrompt({
   userPrompt,
   round,
@@ -504,13 +598,10 @@ function buildForgePrompt({
     "",
     "[RULES]",
     "- 編集対象は TARGET_FILES のみ",
-    "- 推測は避け、app/ sdd-forge/ specs/ の事実を優先",
-    "- 既存の指摘を潰すために必要な最小限の変更を行う",
-    "- 変更後に説明文は簡潔で主語を明確にする",
-    "- 追加情報が必要で確定できない場合は、編集せず次だけを出力する:",
-    "  NEEDS_INPUT",
-    "  - 質問1",
-    "  - 質問2",
+    "- 推測は避け、ソースコードの事実を優先",
+    "- 変更は必要最小限にする",
+    "- 説明文は簡潔で主語を明確にする",
+    "- 不明な場合は編集せずスキップする",
     "",
     ...(analysisSummary
       ? ["[SOURCE_ANALYSIS]", analysisSummary, ""]
@@ -520,6 +611,63 @@ function buildForgePrompt({
   ].join("\n");
 }
 
+/**
+ * Run agent for each file with concurrency control.
+ * Returns an array of { file, ok, error? } results.
+ */
+async function runPerFile({ agent, targetFiles, systemPrompt, round, maxRuns, reviewFeedback, root, timeoutMs, concurrency, verbose }) {
+  const results = [];
+  let running = 0;
+  let idx = 0;
+
+  return new Promise((resolve) => {
+    function next() {
+      // All dispatched and all done
+      if (idx >= targetFiles.length && running === 0) {
+        resolve(results);
+        return;
+      }
+
+      // Dispatch up to concurrency limit
+      while (running < concurrency && idx < targetFiles.length) {
+        const file = targetFiles[idx++];
+        running++;
+
+        const filePrompt = buildForgeFilePrompt({
+          targetFile: file,
+          round,
+          maxRuns,
+          reviewFeedback,
+        });
+
+        output.write(`[forge] start: ${file}\n`);
+
+        runAgent(agent, filePrompt, {
+          label: `forge:${path.basename(file)}`,
+          cwd: root,
+          timeoutMs,
+          streamOutput: verbose,
+          systemPrompt,
+        })
+          .then(() => {
+            output.write(`[forge] done: ${file}\n`);
+            results.push({ file, ok: true });
+          })
+          .catch((e) => {
+            output.write(`[forge] failed: ${file} — ${String(e.message || e).slice(0, 200)}\n`);
+            results.push({ file, ok: false, error: e.message });
+          })
+          .finally(() => {
+            running--;
+            next();
+          });
+      }
+    }
+
+    next();
+  });
+}
+
 /**
  * forge の review 成功後に projectContext を自動更新する。
  * docs/ の各章ファイル先頭を LLM に渡し、プロジェクト概要を生成させる。
@@ -686,6 +834,8 @@ async function main() {
     return;
   }
 
+  const concurrency = Number(cfg.limits?.concurrency || 0) || DEFAULT_CONCURRENCY;
+
   let reviewFeedback = "";
   for (let round = 1; round <= effectiveMaxRuns; round += 1) {
     output.write(`\n[forge] round ${round}/${effectiveMaxRuns}\n`);
@@ -698,45 +848,70 @@ async function main() {
           output.write("[forge] assist mode: agent not configured, run local-only.\n");
         }
       } else {
-        const prompt = buildForgePrompt({
-          userPrompt,
-          round,
-          maxRuns: effectiveMaxRuns,
-          reviewFeedback,
-          specPath: specPath ? path.relative(root, specPath) : "",
-          specText,
-          analysisSummary,
-          targetFiles: getTargetFiles(root),
-        });
-        try {
-          const out = await runAgent(agent, prompt, {
-            label: "forge.generate",
-            cwd: root,
+        const targetFiles = getTargetFiles(root);
+        const usePerFile = !!agent.systemPromptFlag;
+
+        if (usePerFile) {
+          // Per-file async processing with system prompt separation
+          const systemPrompt = buildForgeSystemPrompt({
+            userPrompt,
+            specPath: specPath ? path.relative(root, specPath) : "",
+            specText,
+            analysisSummary,
+          });
+
+          output.write(`[forge] per-file mode: ${targetFiles.length} files, concurrency=${concurrency}\n`);
+
+          const results = await runPerFile({
+            agent,
+            targetFiles,
+            systemPrompt,
+            round,
+            maxRuns: effectiveMaxRuns,
+            reviewFeedback,
+            root,
             timeoutMs,
-            streamOutput: cli.verbose,
+            concurrency,
+            verbose: cli.verbose,
           });
-          usedAgent = true;
-
-          const needsInput = extractNeedsInput(out);
-          if (needsInput.length > 0) {
-            output.write("\n[forge] NEEDS_INPUT detected.\n");
-            output.write("追加情報が必要です。以下に回答してください:\n");
-            for (const q of needsInput) {
-              output.write(`- ${q}\n`);
+
+          const succeeded = results.filter((r) => r.ok).length;
+          const failed = results.filter((r) => !r.ok).length;
+          output.write(`[forge] per-file done: ${succeeded} ok, ${failed} failed\n`);
+
+          if (succeeded > 0) usedAgent = true;
+          if (failed > 0 && succeeded === 0) agentFailed = true;
+        } else {
+          // Legacy: single prompt with all files
+          const prompt = buildForgePrompt({
+            userPrompt,
+            round,
+            maxRuns: effectiveMaxRuns,
+            reviewFeedback,
+            specPath: specPath ? path.relative(root, specPath) : "",
+            specText,
+            analysisSummary,
+            targetFiles,
+          });
+          try {
+            await runAgent(agent, prompt, {
+              label: "forge.generate",
+              cwd: root,
+              timeoutMs,
+              streamOutput: cli.verbose,
+            });
+            usedAgent = true;
+          } catch (e) {
+            agentFailed = true;
+            if (mode === "agent") {
+              throw e;
             }
-            process.exitCode = 2;
-            return;
+            output.write(
+              `[forge] agent step failed. continue with local pipeline.\n${String(
+                e instanceof Error ? e.message : e
+              ).slice(0, 500)}\n`,
+            );
           }
-        } catch (e) {
-          agentFailed = true;
-          if (mode === "agent") {
-            throw e;
-          }
-          output.write(
-            `[forge] agent step failed. continue with local pipeline.\n${String(
-              e instanceof Error ? e.message : e
-            ).slice(0, 500)}\n`,
-          );
         }
       }
     }
@@ -790,7 +965,13 @@ async function main() {
   throw new Error("forge: max runs reached but review still failing.");
 }
 
-export { main };
+export {
+  main,
+  buildArgs,
+  buildForgeSystemPrompt,
+  buildForgeFilePrompt,
+  runPerFile,
+};
 
 const isDirectRun = process.argv[1] &&
   path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));

package/src/docs/commands/setup.js

@@ -575,6 +575,7 @@ async function main() {
           name: "claude-cli",
           command: "claude",
           args: ["--model", "sonnet", "-p", "{{PROMPT}}"],
+          systemPromptFlag: "--system-prompt",
         },
       };
     } else if (defaultAgent === "codex") {
@@ -583,6 +584,7 @@ async function main() {
           name: "codex-cli",
           command: "codex",
           args: ["-p", "{{PROMPT}}"],
+          systemPromptFlag: "--system-prompt-file",
         },
       };
     }

package/src/docs/commands/text.js

@@ -12,12 +12,12 @@
 
 import fs from "fs";
 import path from "path";
-import { execFileSync } from "child_process";
 import { fileURLToPath } from "url";
 import { parseDirectives } from "../lib/directive-parser.js";
 import { repoRoot, parseArgs } from "../../lib/cli.js";
 import { loadConfig, resolveProjectContext } from "../../lib/config.js";
 import { createLogger } from "../../lib/progress.js";
+import { callAgent as callAgentBase } from "../../lib/agent.js";
 
 const logger = createLogger("text");
 
@@ -230,7 +230,35 @@ function formatLimitRule(params) {
   return "簡潔かつ正確に（3〜15行程度）";
 }
 
-function buildPrompt(directive, fileName, lines, contextData, projectContext, documentStyle, lang) {
+/**
+ * システムプロンプトを構築する。
+ * documentStyle + projectContext + 共通出力ルールを含む。
+ * per-directive / batch 両モードで共有し、provider のプロンプトキャッシュを活用する。
+ *
+ * @param {string} projectContext
+ * @param {import("../lib/types.js").DocumentStyle|undefined} documentStyle
+ * @param {string} lang
+ * @returns {string}
+ */
+function buildTextSystemPrompt(projectContext, documentStyle, lang) {
+  const header = buildPromptHeader(projectContext, documentStyle, lang);
+  return [
+    ...header,
+    "",
+    "以下の指示に従い、ドキュメントに挿入するマークダウンテキストを生成してください。",
+    "",
+    "## 出力ルール（厳守）",
+    "- 本文のマークダウンテキストのみを出力すること",
+    "- 前置き・メタコメンタリーは絶対に含めないこと（例: 「以下に生成します」「Based on the analysis data」「Here is the generated text」等は禁止）",
+    "- 水平線（---）を装飾目的で使わないこと",
+    "- コードブロック（```）で全体を囲まないこと",
+    "- セクション見出し（#）は含めない（挿入先に既にある）",
+    "- 解析データに基づく事実のみ記述（推測は避ける）",
+    "- 1行目から本文を開始すること（空行や導入文で始めない）",
+  ].join("\n");
+}
+
+function buildPrompt(directive, fileName, lines, contextData) {
   const directiveLine = directive.line;
 
   // ±20行のコンテキストを抽出
@@ -244,24 +272,11 @@ function buildPrompt(directive, fileName, lines, contextData, projectContext, do
     ? contextJson.slice(0, 8000) + "\n... (truncated)"
     : contextJson;
 
-  const header = buildPromptHeader(projectContext, documentStyle, lang);
-  header.push("", "以下の指示に従い、ドキュメントに挿入するマークダウンテキストを生成してください。");
-
   return [
-    ...header,
-    "",
     "## 指示",
     directive.prompt,
     "",
-    "## 出力ルール（厳守）",
-    "- 本文のマークダウンテキストのみを出力すること",
-    "- 前置き・メタコメンタリーは絶対に含めないこと（例: 「以下に生成します」「Based on the analysis data」「Here is the generated text」等は禁止）",
-    "- 水平線（---）を装飾目的で使わないこと",
-    "- コードブロック（```）で全体を囲まないこと",
-    "- セクション見出し（#）は含めない（挿入先に既にある）",
-    "- 解析データに基づく事実のみ記述（推測は避ける）",
     `- ${formatLimitRule(directive.params)}`,
-    "- 1行目から本文を開始すること（空行や導入文で始めない）",
     "",
     `## 挿入先コンテキスト（${fileName}）`,
     surroundingLines,
@@ -328,9 +343,7 @@ function countFilledInBatch(fileText) {
  * ファイル全体を1つのプロンプトにまとめるバッチプロンプトを構築する。
  * ±20行ウィンドウ・解析データは不要（ファイル全体が文脈になる）。
  */
-function buildBatchPrompt(fileName, text, projectContext, textFills, documentStyle, lang) {
-  const header = buildPromptHeader(projectContext, documentStyle, lang);
-
+function buildBatchPrompt(fileName, text, textFills) {
   // ディレクティブごとの個別制限ルールがあれば列挙
   const perDirectiveRules = [];
   for (const d of textFills) {
@@ -343,8 +356,6 @@ function buildBatchPrompt(fileName, text, projectContext, textFills, documentSty
     : "- 個別制限のないディレクティブは3〜15行程度の本文を生成すること";
 
   return [
-    ...header,
-    "",
     `以下の ${fileName} にある <!-- @text: 指示 --> ディレクティブをすべて埋めてください。`,
     "",
     "## 出力ルール（厳守）",
@@ -370,14 +381,14 @@ function buildBatchPrompt(fileName, text, projectContext, textFills, documentSty
  *
  * @returns {{ text: string, filled: number, skipped: number }}
  */
-function processTemplateFileBatch(text, analysis, fileName, agent, timeoutMs, cwd, dryRun, _preamblePatterns, projectContext, documentStyle, lang) {
+function processTemplateFileBatch(text, analysis, fileName, agent, timeoutMs, cwd, dryRun, _preamblePatterns, systemPrompt) {
   const directives = parseDirectives(text);
   const textFills = directives.filter((d) => d.type === "text");
 
   if (textFills.length === 0) return { text, filled: 0, skipped: 0 };
 
   const cleanText = stripFillContent(text);
-  const prompt = buildBatchPrompt(fileName, cleanText, projectContext, textFills, documentStyle, lang);
+  const prompt = buildBatchPrompt(fileName, cleanText, textFills);
 
   if (dryRun) {
     console.log(`[text] DRY-RUN batch ${fileName}: ${textFills.length} directive(s) → 1 call (${prompt.length} chars)`);
@@ -389,7 +400,7 @@ function processTemplateFileBatch(text, analysis, fileName, agent, timeoutMs, cw
   let result;
   try {
     // バッチはファイル全体を返すので preamble パターンは使わない
-    result = callAgent(agent, prompt, timeoutMs, cwd, []);
+    result = callAgent(agent, prompt, timeoutMs, cwd, [], systemPrompt);
   } catch (err) {
     const parts = [err.message];
     if (err.signal) parts.push(`signal: ${err.signal}`);
@@ -422,28 +433,9 @@ function processTemplateFileBatch(text, analysis, fileName, agent, timeoutMs, cw
 // ---------------------------------------------------------------------------
 // エージェント呼び出し
 // ---------------------------------------------------------------------------
-function callAgent(agent, prompt, timeoutMs, cwd, preamblePatterns) {
-  const args = Array.isArray(agent.args) ? [...agent.args] : [];
-  const resolvedArgs = args.map((a) =>
-    typeof a === "string" ? a.replaceAll("{{PROMPT}}", prompt) : a
-  );
-  // {{PROMPT}} トークンがなかった場合は末尾に追加
-  const hasToken = args.some((a) => typeof a === "string" && a.includes("{{PROMPT}}"));
-  const finalArgs = hasToken ? resolvedArgs : [...resolvedArgs, prompt];
-
-  // CLAUDECODE を外してネスト起動ガードを回避（claude CLI 呼び出し時に必要）
-  const env = { ...process.env };
-  delete env.CLAUDECODE;
-
-  const result = execFileSync(agent.command, finalArgs, {
-    encoding: "utf8",
-    maxBuffer: 20 * 1024 * 1024,
-    timeout: timeoutMs,
-    cwd,
-    env,
-  });
-
-  return stripPreamble(result.trim(), preamblePatterns);
+function callAgent(agent, prompt, timeoutMs, cwd, preamblePatterns, systemPrompt) {
+  const result = callAgentBase(agent, prompt, timeoutMs, cwd, { systemPrompt });
+  return stripPreamble(result, preamblePatterns);
 }
 
 /**
@@ -501,7 +493,7 @@ function stripPreamble(text, preamblePatterns) {
  * @param {boolean} dryRun     - dry-run モード
  * @returns {{ text: string, filled: number, skipped: number }}
  */
-function processTemplate(text, analysis, fileName, agent, timeoutMs, cwd, dryRun, preamblePatterns, projectContext, documentStyle, lang, filterId) {
+function processTemplate(text, analysis, fileName, agent, timeoutMs, cwd, dryRun, preamblePatterns, systemPrompt, filterId) {
   const directives = parseDirectives(text);
   let textFills = directives.filter((d) => d.type === "text");
   if (filterId) {
@@ -518,7 +510,7 @@ function processTemplate(text, analysis, fileName, agent, timeoutMs, cwd, dryRun
   // 後ろから処理して行番号のズレを防ぐ
   for (let i = textFills.length - 1; i >= 0; i--) {
     const d = textFills[i];
-    const prompt = buildPrompt(d, fileName, lines, contextData, projectContext, documentStyle, lang);
+    const prompt = buildPrompt(d, fileName, lines, contextData);
 
     if (dryRun) {
       console.log(`[text] DRY-RUN ${fileName}:${d.line + 1}: ${d.prompt.slice(0, 80)}`);
@@ -531,7 +523,7 @@ function processTemplate(text, analysis, fileName, agent, timeoutMs, cwd, dryRun
 
     let generated;
     try {
-      generated = callAgent(agent, prompt, timeoutMs, cwd, preamblePatterns);
+      generated = callAgent(agent, prompt, timeoutMs, cwd, preamblePatterns, systemPrompt);
     } catch (err) {
       logger.log(`ERROR calling agent for ${fileName}:${d.line + 1}: ${err.message.slice(0, 200)}`);
       skipped++;
@@ -599,6 +591,7 @@ export function textFillFromAnalysis(root, analysis, agentName) {
   const projectContext = resolveProjectContext(root);
   const documentStyle = cfg.documentStyle;
   const lang = cfg.lang || "ja";
+  const systemPrompt = buildTextSystemPrompt(projectContext, documentStyle, lang);
   const docsDir = path.join(root, "docs");
   const docsFiles = fs.readdirSync(docsDir)
     .filter((f) => /^\d{2}_/.test(f) && f.endsWith(".md"))
@@ -611,7 +604,7 @@ export function textFillFromAnalysis(root, analysis, agentName) {
   for (const file of docsFiles) {
     const filePath = path.join(docsDir, file);
     const original = fs.readFileSync(filePath, "utf8");
-    const result = processTemplate(original, analysis, file, agent, 120000, root, false, preamblePatterns, projectContext, documentStyle, lang);
+    const result = processTemplate(original, analysis, file, agent, 120000, root, false, preamblePatterns, systemPrompt);
 
     totalFilled += result.filled;
     totalSkipped += result.skipped;
@@ -671,6 +664,7 @@ function main() {
   const projectContext = resolveProjectContext(root);
   const documentStyle = cfg.documentStyle;
   const lang = cfg.lang || "ja";
+  const systemPrompt = buildTextSystemPrompt(projectContext, documentStyle, lang);
   const docsDir = path.join(root, "docs");
   const docsFiles = fs.readdirSync(docsDir)
     .filter((f) => /^\d{2}_/.test(f) && f.endsWith(".md"))
@@ -702,14 +696,14 @@ function main() {
       if (!hasId) continue;
     }
 
-    let result = processFn(original, analysis, file, agent, cli.timeout, root, cli.dryRun, preamblePatterns, projectContext, documentStyle, lang, cli.id || undefined);
+    let result = processFn(original, analysis, file, agent, cli.timeout, root, cli.dryRun, preamblePatterns, systemPrompt, cli.id || undefined);
 
     // バッチモードで 0 filled になった場合は per-directive モードで再試行
     if (!cli.perDirective && !cli.dryRun && result.filled === 0) {
       const textFills = parseDirectives(original).filter((d) => d.type === "text");
       if (textFills.length > 0) {
         logger.verbose(`Batch returned 0 filled for ${file}. Falling back to per-directive mode...`);
-        result = processTemplate(original, analysis, file, agent, cli.timeout, root, cli.dryRun, preamblePatterns, projectContext, documentStyle, lang, cli.id || undefined);
+        result = processTemplate(original, analysis, file, agent, cli.timeout, root, cli.dryRun, preamblePatterns, systemPrompt, cli.id || undefined);
       }
     }
 

package/src/docs/commands/upgrade.js

@@ -146,6 +146,30 @@ function upgradeAgentsSddSection(workRoot, lang, dryRun) {
   return "updated";
 }
 
+// ---------------------------------------------------------------------------
+// Config hints (non-destructive — just prints suggestions)
+// ---------------------------------------------------------------------------
+
+const SYSTEM_PROMPT_FLAGS = {
+  claude: "--system-prompt",
+  codex: "--system-prompt-file",
+};
+
+/**
+ * Check config.json for missing new settings and print hints.
+ */
+function checkConfigHints(config, t) {
+  if (!config.providers) return;
+
+  for (const [key, prov] of Object.entries(config.providers)) {
+    if (prov.systemPromptFlag) continue;
+    const suggested = SYSTEM_PROMPT_FLAGS[key] || SYSTEM_PROMPT_FLAGS[prov.command];
+    if (suggested) {
+      console.log(t("upgrade.hintSystemPromptFlag", { provider: key, flag: suggested }));
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -202,6 +226,9 @@ async function main() {
     console.log(t("upgrade.agentsUnchanged"));
   }
 
+  // 3. Config hints — check for missing new settings
+  checkConfigHints(config, t);
+
   // Summary
   const hasChanges = skillResults.some((r) => r.status === "updated") || agentsStatus === "updated";
   if (!hasChanges) {

package/src/lib/agent.js

@@ -5,39 +5,87 @@
  * Provides a shared interface for calling configured AI agents.
  */
 
+import fs from "fs";
+import os from "os";
+import path from "path";
 import { execFileSync } from "child_process";
 
 /**
  * Call an AI agent with a prompt and return the response.
  *
- * @param {Object} agent        - Agent config ({ command, args })
+ * When `options.systemPrompt` is provided:
+ *   - If agent.systemPromptFlag is set (e.g. "--system-prompt"),
+ *     the flag + systemPrompt are prepended to the argument list.
+ *   - If agent.systemPromptFlag is "--system-prompt-file",
+ *     a temp file is written and cleaned up after execution.
+ *   - If no systemPromptFlag but systemPrompt is given,
+ *     the system prompt is prepended to the user prompt (fallback).
+ *
+ * @param {Object} agent        - Agent config ({ command, args, systemPromptFlag? })
  * @param {string} prompt       - The prompt text
  * @param {number} [timeoutMs]  - Timeout in milliseconds (default: 120000)
  * @param {string} [cwd]        - Working directory
+ * @param {Object} [options]    - Additional options
+ * @param {string} [options.systemPrompt] - System prompt text
  * @returns {string} Agent response (trimmed)
  */
-export function callAgent(agent, prompt, timeoutMs, cwd) {
+export function callAgent(agent, prompt, timeoutMs, cwd, options) {
+  const { systemPrompt } = options || {};
   const args = Array.isArray(agent.args) ? [...agent.args] : [];
-  const resolvedArgs = args.map((a) =>
-    typeof a === "string" ? a.replaceAll("{{PROMPT}}", prompt) : a,
-  );
+
+  // Build system prompt prefix args
+  const flag = agent.systemPromptFlag;
+  let prefix = [];
+  let cleanupFile;
+  if (flag && systemPrompt) {
+    if (flag === "--system-prompt-file") {
+      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sdd-forge-"));
+      const tmpFile = path.join(tmpDir, "system-prompt.md");
+      fs.writeFileSync(tmpFile, systemPrompt, "utf8");
+      prefix = [flag, tmpFile];
+      cleanupFile = tmpFile;
+    } else {
+      prefix = [flag, systemPrompt];
+    }
+  }
+
+  // Combine system prompt into user prompt when no flag is available
+  let effectivePrompt = prompt;
+  if (!flag && systemPrompt) {
+    effectivePrompt = systemPrompt + "\n\n" + prompt;
+  }
 
   const hasToken = args.some((a) => typeof a === "string" && a.includes("{{PROMPT}}"));
-  const finalArgs = hasToken ? resolvedArgs : [...resolvedArgs, prompt];
+  let resolvedArgs;
+  if (hasToken) {
+    resolvedArgs = args.map((a) =>
+      typeof a === "string" ? a.replaceAll("{{PROMPT}}", effectivePrompt) : a,
+    );
+  } else {
+    resolvedArgs = [...args, effectivePrompt];
+  }
+
+  const finalArgs = [...prefix, ...resolvedArgs];
 
   // Remove CLAUDECODE env to avoid nested launch guard
   const env = { ...process.env };
   delete env.CLAUDECODE;
 
-  const result = execFileSync(agent.command, finalArgs, {
-    encoding: "utf8",
-    maxBuffer: 20 * 1024 * 1024,
-    timeout: timeoutMs || 120000,
-    cwd: cwd || process.cwd(),
-    env,
-  });
+  try {
+    const result = execFileSync(agent.command, finalArgs, {
+      encoding: "utf8",
+      maxBuffer: 20 * 1024 * 1024,
+      timeout: timeoutMs || 120000,
+      cwd: cwd || process.cwd(),
+      env,
+    });
 
-  return result.trim();
+    return result.trim();
+  } finally {
+    if (cleanupFile) {
+      try { fs.unlinkSync(cleanupFile); fs.rmdirSync(path.dirname(cleanupFile)); } catch (_) {}
+    }
+  }
 }
 
 /**

package/src/lib/types.js

@@ -35,6 +35,7 @@ import { buildTypeAliases } from "../docs/presets/registry.js";
  * @property {string} command    - 実行コマンド
  * @property {string[]} args     - コマンド引数（{{PROMPT}} プレースホルダー対応）
  * @property {number} [timeoutMs] - タイムアウト (ms)
+ * @property {string} [systemPromptFlag] - system prompt フラグ (例: "--system-prompt", "--system-prompt-file")
  */
 
 /**
@@ -56,6 +57,7 @@ import { buildTypeAliases } from "../docs/presets/registry.js";
  * @property {string} type                    - Project type ("webapp/cakephp2" | "cli" | ...)
  * @property {Object} [limits]                - Limit settings
  * @property {number} [limits.designTimeoutMs] - Timeout (ms)
+ * @property {number} [limits.concurrency]    - Per-file concurrency (default: 3)
  * @property {DocumentStyle} [documentStyle]  - Document style settings
  * @property {TextFillConfig} [textFill]      - text-fill settings
  * @property {string} [defaultAgent]          - Default agent name

package/src/templates/config.example.json

@@ -7,7 +7,8 @@
   "lang": "ja",
   "type": "webapp/cakephp2",
   "limits": {
-    "designTimeoutMs": 900000
+    "designTimeoutMs": 900000,
+    "concurrency": 3
   },
   "documentStyle": {
     "purpose": "developer-guide",
@@ -25,7 +26,8 @@
     "claude": {
       "name": "claude-cli",
       "command": "claude",
-      "args": ["--model", "sonnet", "-p", "{{PROMPT}}"]
+      "args": ["--model", "sonnet", "-p", "{{PROMPT}}"],
+      "systemPromptFlag": "--system-prompt"
     }
   }
 }

package/src/templates/locale/en/ui.json

@@ -102,7 +102,8 @@
     "agentsUnchanged": "[upgrade] AGENTS.md SDD section unchanged.",
     "noChanges": "[upgrade] All files are up to date.",
     "dryRunFooter": "[upgrade] DRY-RUN: no files were modified. Run without --dry-run to apply.",
-    "done": "[upgrade] Upgrade complete."
+    "done": "[upgrade] Upgrade complete.",
+    "hintSystemPromptFlag": "[upgrade] Hint: Add \"systemPromptFlag\": \"{{flag}}\" to providers.{{provider}} to enable per-file async processing in forge."
   },
   "common": {
     "choicePrompt": "> ({{min}}-{{max}}): ",

package/src/templates/locale/ja/ui.json

@@ -102,7 +102,8 @@
     "agentsUnchanged": "[upgrade] AGENTS.md の SDD セクションに変更はありません。",
     "noChanges": "[upgrade] すべてのファイルは最新です。",
     "dryRunFooter": "[upgrade] DRY-RUN: ファイルは変更されませんでした。--dry-run なしで実行してください。",
-    "done": "[upgrade] アップグレード完了。"
+    "done": "[upgrade] アップグレード完了。",
+    "hintSystemPromptFlag": "[upgrade] ヒント: providers.{{provider}} に \"systemPromptFlag\": \"{{flag}}\" を追加すると、forge のファイル単位非同期処理が有効になります。"
   },
   "common": {
     "choicePrompt": "> ({{min}}-{{max}}): ",