sdd-forge 0.1.0-alpha.692 → 0.1.0-alpha.702

package/README.md

@@ -129,12 +129,12 @@ See the [configuration reference](docs/configuration.md) for details.
 <!-- {{data("cli.docs.chapters", {header: "", labels: "Chapter|Summary", ignoreError: true})}} -->
 | Chapter | Summary |
 | --- | --- |
-| [Tool Overview and Architecture](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/overview.md) | This chapter provides a concise introduction to sdd-forge — a CLI tool that generates structured technical documentat… |
-| [Technology Stack and Operations](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/stack_and_ops.md) | This chapter covers the technology stack and operational procedures for sdd-forge, a Node.js CLI tool built with ES M… |
-| [Project Structure](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/project_structure.md) | This chapter describes the source tree of sdd-forge, which is organized into five major directories: src/docs (docume… |
-| [CLI Command Reference](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/cli_commands.md) | sdd-forge exposes over 35 commands organized across three namespace groups — docs, flow, and check — plus four standa… |
-| [Configuration and Customization](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/configuration.md) | sdd-forge reads a single JSON configuration file per project, through which users can control documentation output la… |
-| [Internal Design](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/internal_design.md) | sdd-forge is a Node.js CLI tool organized into three primary source layers — src/docs/ for documentation pipeline com… |
+| [Tool Overview and Architecture](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/overview.md) |  |
+| [Technology Stack and Operations](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/stack_and_ops.md) |  |
+| [Project Structure](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/project_structure.md) |  |
+| [CLI Command Reference](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/cli_commands.md) |  |
+| [Configuration and Customization](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/configuration.md) |  |
+| [Internal Design](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/internal_design.md) |  |
 <!-- {{/data}} -->
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-forge",
-  "version": "0.1.0-alpha.692",
+  "version": "0.1.0-alpha.702",
   "description": "Spec-Driven Development tooling for automated documentation generation",
   "repository": {
     "type": "git",

package/src/docs/commands/init.js

@@ -141,7 +141,7 @@ function main(ctx) {
       console.log([h.usage, "", h.desc, "", "Options:", `  ${o.type}`, `  ${o.force}`, `  ${o.dryRun}`, `  ${o.help}`].join("\n"));
       return;
     }
-    ctx = resolveCommandContext(cli);
+    ctx = resolveCommandContext(cli, { commandId: "docs.init" });
     ctx.force = cli.force;
     ctx.dryRun = cli.dryRun;
   }

package/src/docs/commands/text.js

@@ -218,7 +218,11 @@ function applyBatchJsonToFile(text, textFills, jsonData) {
  * @returns {{ text: string, filled: number, skipped: number }}
  */
 async function processTemplateFileBatch(text, analysis, fileName, agent, timeoutMs, cwd, dryRun, _preamblePatterns, systemPrompt, _filterId, _concurrency, lang, srcRoot, retryCount) {
-  const directives = parseDirectives(text);
+  // cleanText を先に計算してから parseDirectives を呼ぶ。
+  // stripFillContent は既存コンテンツを除去するため行数が変わる。
+  // parseDirectives の行番号は applyBatchJsonToFile に渡す text と一致させる必要がある。
+  const cleanText = stripFillContent(text);
+  const directives = parseDirectives(cleanText);
   const textFills = directives.filter((d) => d.type === "text");
 
   if (textFills.length === 0) return { text, filled: 0, skipped: 0 };
@@ -227,8 +231,6 @@ async function processTemplateFileBatch(text, analysis, fileName, agent, timeout
   const hasDeep = textFills.some((d) => d.params?.mode === "deep");
   const batchMode = hasDeep ? "deep" : "light";
   const enriched = getEnrichedContext(analysis, fileName, batchMode, srcRoot);
-
-  const cleanText = stripFillContent(text);
   let prompt = buildBatchPrompt(fileName, cleanText, textFills, lang);
   if (enriched) {
     prompt = enriched + "\n\n" + prompt;

package/src/docs.js

@@ -8,6 +8,7 @@
 import fs from "fs";
 import path from "path";
 import { PKG_DIR } from "./lib/cli.js";
+import { Logger } from "./lib/log.js";
 import { resolveCommandContext } from "./docs/lib/command-context.js";
 import { resolveOutputConfig } from "./lib/types.js";
 import { EXIT_ERROR } from "./lib/exit-codes.js";
@@ -99,11 +100,13 @@ if (subCmd === "build") {
 
   try {
     // 1. scan
+    Logger.getInstance().event("pipeline-step", { step: "scan", phase: "start" });
     progress.start("scan");
     await scanMain({ ...baseCtx });
     progress.stepDone();
 
     // 2. enrich
+    Logger.getInstance().event("pipeline-step", { step: "enrich", phase: "start" });
     progress.start("enrich");
     if (hasAgent) {
       await enrichMain({ ...baseCtx, commandId: "docs.enrich" });
@@ -122,17 +125,20 @@ if (subCmd === "build") {
         process.exit(EXIT_ERROR);
       }
     } else {
+      Logger.getInstance().event("pipeline-step", { step: "init", phase: "start" });
       progress.start("init");
       await initMain({ ...baseCtx, force: hasForce, dryRun: isDryRun, commandId: "docs.init" });
       progress.stepDone();
     }
 
     // 4. data
+    Logger.getInstance().event("pipeline-step", { step: "data", phase: "start" });
     progress.start("data");
     await dataMain({ ...baseCtx, dryRun: isDryRun });
     progress.stepDone();
 
     // 5. text — delegate file selection, diff detection, and strip to text.js
+    Logger.getInstance().event("pipeline-step", { step: "text", phase: "start" });
     progress.start("text");
     if (hasAgent) {
       const textResult = await textMain({ ...baseCtx, dryRun: isDryRun, commandId: "docs.text", force: hasForce });
@@ -145,17 +151,20 @@ if (subCmd === "build") {
     progress.stepDone();
 
     // 6. readme
+    Logger.getInstance().event("pipeline-step", { step: "readme", phase: "start" });
     progress.start("readme");
     await readmeMain({ ...baseCtx, dryRun: isDryRun, commandId: "docs.readme" });
     progress.stepDone();
 
     // 7. agents
+    Logger.getInstance().event("pipeline-step", { step: "agents", phase: "start" });
     progress.start("agents");
     await agentsMain({ ...baseCtx, dryRun: isDryRun, commandId: "docs.agents" });
     progress.stepDone();
 
     // 8. Multi-language: generate non-default languages
     if (outputCfg.isMultiLang) {
+      Logger.getInstance().event("pipeline-step", { step: "translate", phase: "start" });
       progress.start("translate");
       const nonDefaultLangs = outputCfg.languages.filter((l) => l !== outputCfg.default);
       const docsDir = baseCtx.docsDir;
@@ -210,6 +219,7 @@ if (subCmd === "build") {
     progress.done();
   } catch (err) {
     progress.done();
+    Logger.getInstance().event("error", { message: err.message });
     console.error(`[build] ERROR: ${err.message}`);
     process.exit(EXIT_ERROR);
   }

package/src/flow/lib/run-gate.js

@@ -442,7 +442,7 @@ export class RunGateCommand extends FlowCommand {
 
     // Requirements check via AI
     const agent = resolveAgent(ctx.config, "spec.gate");
-    if (!agent) throw new Error("no agent configured for spec.gate");
+    if (!agent) throw new Error("no AI agent configured (agent.default or agent.profiles.<name>.spec.gate)");
 
     const reqPrompt = buildImplCheckPrompt(specText, diff);
     const reqResponse = callAgentWithLog(agent, reqPrompt);

package/src/flow/lib/run-retro.js

@@ -185,7 +185,7 @@ export class RunRetroCommand extends FlowCommand {
 
     const agent = resolveAgent(config, "flow.retro");
     if (!agent) {
-      throw new Error("no AI agent configured (agent.default or agent.commands.flow.retro)");
+      throw new Error("no AI agent configured (agent.default or agent.profiles.<name>.flow.retro)");
     }
 
     // Build prompt and call AI

package/src/flow/lib/set-step.js

@@ -9,6 +9,7 @@
 
 import { FlowCommand } from "./base-command.js";
 import { updateStepStatus } from "../../lib/flow-state.js";
+import { Logger } from "../../lib/log.js";
 
 export default class SetStepCommand extends FlowCommand {
   execute(ctx) {
@@ -19,6 +20,7 @@ export default class SetStepCommand extends FlowCommand {
     }
 
     updateStepStatus(ctx.root, id, status);
+    Logger.getInstance().event("flow-step-change", { step: id, status });
 
     return { id, status };
   }

package/src/lib/process.js

@@ -6,6 +6,7 @@
  */
 
 import { execFileSync, execFile } from "child_process";
+import { Logger } from "./log.js";
 
 /**
  * Run a command synchronously.
@@ -30,9 +31,11 @@ export function runCmd(cmd, args, opts = {}) {
       stdio: ["pipe", "pipe", "pipe"],
       ...(opts.env && { env: opts.env }),
     });
-    return { ok: true, status: 0, stdout: String(stdout || ""), stderr: "", signal: null, killed: false };
+    const result = { ok: true, status: 0, stdout: String(stdout || ""), stderr: "", signal: null, killed: false };
+    if (cmd === "git") Logger.getInstance().git({ cmd: [cmd, ...args], exitCode: 0, stderr: "" });
+    return result;
   } catch (e) {
-    return {
+    const result = {
       ok: false,
       status: e.status ?? 1,
       stdout: String(e.stdout || ""),
@@ -40,6 +43,8 @@ export function runCmd(cmd, args, opts = {}) {
       signal: e.signal ?? null,
       killed: e.killed ?? false,
     };
+    if (cmd === "git") Logger.getInstance().git({ cmd: [cmd, ...args], exitCode: result.status, stderr: result.stderr });
+    return result;
   }
 }
 
@@ -69,25 +74,28 @@ export function runCmdAsync(cmd, args, opts = {}) {
         ...(opts.env && { env: opts.env }),
       },
       (err, stdout, stderr) => {
+        let result;
         if (err) {
-          resolve({
+          result = {
             ok: false,
             status: typeof err.code === "number" ? err.code : 1,
             stdout: String(stdout || ""),
             stderr: String(stderr || err.message || ""),
             signal: err.signal ?? null,
             killed: err.killed ?? false,
-          });
+          };
         } else {
-          resolve({
+          result = {
             ok: true,
             status: 0,
             stdout: String(stdout || ""),
             stderr: String(stderr || ""),
             signal: null,
             killed: false,
-          });
+          };
         }
+        if (cmd === "git") Logger.getInstance().git({ cmd: [cmd, ...args], exitCode: result.status, stderr: result.stderr });
+        resolve(result);
       },
     );
   });

package/src/lib/skills.js

@@ -7,6 +7,12 @@ import path from "path";
 import { PKG_DIR } from "./cli.js";
 import { resolveIncludes } from "./include.js";
 
+/** Canonical path to the bundled main skill templates directory. */
+export const MAIN_SKILLS_TEMPLATES_DIR = path.join(PKG_DIR, "templates", "skills");
+
+/** Directories under workRoot where skills are deployed. */
+const SKILL_TARGET_BASES = [".agents", ".claude"];
+
 /**
  * Resolve the skill template file in the given directory.
  */
@@ -43,8 +49,8 @@ function removeIfSymlink(filePath) {
 function deploySkillsFromDir({ templatesDir, workRoot, lang, dryRun = false }) {
   if (!fs.existsSync(templatesDir)) return [];
 
-  const agentsSkillsDir = path.join(workRoot, ".agents", "skills");
-  const claudeSkillsDir = path.join(workRoot, ".claude", "skills");
+  const agentsSkillsDir = path.join(workRoot, SKILL_TARGET_BASES[0], "skills");
+  const claudeSkillsDir = path.join(workRoot, SKILL_TARGET_BASES[1], "skills");
 
   const skillDirs = fs.readdirSync(templatesDir, { withFileTypes: true })
     .filter((d) => d.isDirectory())
@@ -112,7 +118,7 @@ function deploySkillsFromDir({ templatesDir, workRoot, lang, dryRun = false }) {
  */
 export function deploySkills(workRoot, lang, opts = {}) {
   return deploySkillsFromDir({
-    templatesDir: path.join(PKG_DIR, "templates", "skills"),
+    templatesDir: MAIN_SKILLS_TEMPLATES_DIR,
     workRoot,
     lang,
     dryRun: opts.dryRun,
@@ -139,3 +145,49 @@ export function deployProjectSkills(workRoot, templatesDir, lang, opts = {}) {
     dryRun: opts.dryRun,
   });
 }
+
+/**
+ * Remove sdd-forge.* skill directories from .claude/skills/ and .agents/skills/
+ * that are no longer present in any of the provided template directories.
+ *
+ * Only directories whose names start with "sdd-forge." are considered.
+ * Skills found in any of the validTemplatesDirs are kept; all others are removed.
+ *
+ * @param {string} workRoot          Project root directory
+ * @param {string[]} validTemplatesDirs  All active skill template directories (main + experimental)
+ * @param {object} [opts]
+ * @param {boolean} [opts.dryRun=false]
+ * @returns {{ name: string, status: "removed" }[]}
+ */
+export function cleanupObsoleteSkills(workRoot, validTemplatesDirs, opts = {}) {
+  const { dryRun = false } = opts;
+
+  const validNames = new Set(
+    validTemplatesDirs.flatMap((dir) => {
+      if (!fs.existsSync(dir)) return [];
+      return fs.readdirSync(dir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name);
+    })
+  );
+
+  const obsoleteNames = new Set();
+  for (const base of SKILL_TARGET_BASES) {
+    const skillsDir = path.join(workRoot, base, "skills");
+    if (!fs.existsSync(skillsDir)) continue;
+    for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || !entry.name.startsWith("sdd-forge.")) continue;
+      if (!validNames.has(entry.name)) obsoleteNames.add(entry.name);
+    }
+  }
+
+  if (!dryRun) {
+    for (const name of obsoleteNames) {
+      for (const base of SKILL_TARGET_BASES) {
+        fs.rmSync(path.join(workRoot, base, "skills", name), { recursive: true, force: true });
+      }
+    }
+  }
+
+  return [...obsoleteNames].map((name) => ({ name, status: "removed" }));
+}

package/src/lib/types.js

@@ -4,6 +4,8 @@
  * JSDoc 型定義と config / context のバリデーション関数。
  */
 
+import { BUILTIN_PROVIDERS } from "./agent.js";
+
 // ---------------------------------------------------------------------------
 // JSDoc 型定義
 // ---------------------------------------------------------------------------
@@ -63,7 +65,7 @@
  * @property {number} [timeout]              - Agent execution timeout in seconds
  * @property {number} [retryCount]           - Retry count for docs enrich agent calls
  * @property {Object<string, AgentProvider>} [providers] - Agent provider definitions
- * @property {Object} [commands]             - Per-command agent and profile overrides
+ * @property {Object<string, Object<string, string>>} [profiles] - Named profiles mapping commandId prefixes to provider keys
  */
 
 /**
@@ -345,6 +347,37 @@ export function validateConfig(raw) {
     }
   }
 
+  // agent.profiles (省略可)
+  if (raw.agent?.profiles != null) {
+    if (typeof raw.agent.profiles !== "object" || Array.isArray(raw.agent.profiles)) {
+      errors.push("'agent.profiles' must be an object");
+    } else {
+      const allProviders = { ...BUILTIN_PROVIDERS, ...(raw.agent?.providers || {}) };
+      for (const [profileName, profile] of Object.entries(raw.agent.profiles)) {
+        if (typeof profile !== "object" || profile == null || Array.isArray(profile)) {
+          errors.push(`'agent.profiles.${profileName}' must be an object`);
+          continue;
+        }
+        for (const [commandId, providerKey] of Object.entries(profile)) {
+          if (typeof providerKey !== "string") {
+            errors.push(`'agent.profiles.${profileName}.${commandId}' must be a string`);
+          } else if (!allProviders[providerKey]) {
+            errors.push(`'agent.profiles.${profileName}.${commandId}': unknown provider "${providerKey}"`);
+          }
+        }
+      }
+    }
+  }
+
+  // agent.useProfile (省略可)
+  if (raw.agent?.useProfile != null) {
+    if (typeof raw.agent.useProfile !== "string") {
+      errors.push("'agent.useProfile' must be a string");
+    } else if (raw.agent.profiles && !raw.agent.profiles[raw.agent.useProfile]) {
+      errors.push(`'agent.useProfile': profile "${raw.agent.useProfile}" is not defined in agent.profiles`);
+    }
+  }
+
   if (errors.length > 0) {
     throw new Error(`Config validation failed:\n  - ${errors.join("\n  - ")}`);
   }

package/src/locale/en/ui.json

@@ -75,6 +75,7 @@
     "dryRunHeader": "[upgrade] DRY-RUN: showing changes without writing files.",
     "skillUpdated": "[upgrade] skill updated: {{name}}/SKILL.md",
     "skillUnchanged": "[upgrade] skill unchanged: {{name}}/SKILL.md",
+    "skillRemoved": "[upgrade] skill removed (obsolete): {{name}}",
     "agentsUpdated": "[upgrade] AGENTS.md SDD section updated.",
     "agentsNotFound": "[upgrade] AGENTS.md not found or has no SDD section. Skipped.",
     "agentsUnchanged": "[upgrade] AGENTS.md SDD section unchanged.",

package/src/locale/ja/ui.json

@@ -75,6 +75,7 @@
     "dryRunHeader": "[upgrade] DRY-RUN: ファイルを変更せず差分を表示します。",
     "skillUpdated": "[upgrade] スキル更新: {{name}}/SKILL.md",
     "skillUnchanged": "[upgrade] スキル変更なし: {{name}}/SKILL.md",
+    "skillRemoved": "[upgrade] スキル削除（廃止）: {{name}}",
     "agentsUpdated": "[upgrade] AGENTS.md の SDD セクションを更新しました。",
     "agentsNotFound": "[upgrade] AGENTS.md が見つからないか SDD セクションがありません。スキップしました。",
     "agentsUnchanged": "[upgrade] AGENTS.md の SDD セクションに変更はありません。",

package/src/sdd-forge.js

@@ -37,7 +37,7 @@ if (!subCmd || subCmd === "-h" || subCmd === "--help") {
 
 // Initialize Logger singleton (best-effort — config may not exist yet)
 try {
-  const { loadConfig } = await import("./lib/config.js");
+  const { loadConfig, sddConfigPath } = await import("./lib/config.js");
   const root = repoRoot();
   const cfg = loadConfig(root);
   const entryCommand = rawArgs.join(" ");
@@ -46,6 +46,7 @@ try {
     process.stderr.write("[sdd-forge] WARN: cfg.logs.prompts is deprecated. Use cfg.logs.enabled instead.\n");
   }
   Logger.getInstance().init(root, cfg, { entryCommand });
+  Logger.getInstance().event("config-loaded", { path: sddConfigPath(root), keys: Object.keys(cfg) });
 } catch (err) {
   /* pre-setup or missing config — Logger stays uninitialized */
   if (err?.code !== "ERR_MISSING_FILE") process.stderr.write(`[sdd-forge] Logger init failed: ${err?.message}\n`);

package/src/templates/config.example.json

@@ -12,40 +12,46 @@
     }
   },
   "agent": {
-    "default": "claude",
+    "default": "claude/sonnet",
     "workDir": ".tmp",
     "timeout": 300,
     "retryCount": 1,
     "providers": {
-      "claude": {
+      "claude/sonnet": {
         "command": "claude",
-        "args": ["-p", "{{PROMPT}}"],
+        "args": ["-p", "{{PROMPT}}", "--model", "sonnet"],
         "systemPromptFlag": "--system-prompt",
-        "jsonOutputFlag": "--output-format json",
-        "profiles": {
-          "default": ["--model", "sonnet"],
-          "opus": ["--model", "opus"],
-          "sonnet": ["--model", "sonnet"]
-        }
+        "jsonOutputFlag": "--output-format json"
       },
-      "codex": {
+      "claude/opus": {
+        "command": "claude",
+        "args": ["-p", "{{PROMPT}}", "--model", "opus"],
+        "systemPromptFlag": "--system-prompt",
+        "jsonOutputFlag": "--output-format json"
+      },
+      "codex/gpt-5.4": {
         "command": "codex",
         "args": ["exec", "--full-auto", "-C", ".tmp", "{{PROMPT}}"],
-        "profiles": {
-          "default": []
-        }
+        "jsonOutputFlag": "--json"
       }
     },
-    "commands": {
-      "docs.enrich":       { "agent": "claude", "profile": "opus" },
-      "docs.text":         { "agent": "claude", "profile": "opus" },
-      "docs.forge":        { "agent": "claude", "profile": "opus" },
-      "docs.readme":       { "agent": "claude", "profile": "sonnet" },
-      "docs.agents":       { "agent": "claude", "profile": "opus" },
-      "spec.gate":         { "agent": "claude", "profile": "sonnet" },
-      "flow.review.draft": { "agent": "codex" },
-      "flow.review.final": { "agent": "claude", "profile": "opus" },
-      "docs.translate":    { "agent": "codex" }
+    "profiles": {
+      "default": {
+        "docs.init":         "claude/sonnet",
+        "docs.enrich":       "claude/opus",
+        "docs.text":         "claude/opus",
+        "docs.forge":        "claude/opus",
+        "docs.readme":       "claude/sonnet",
+        "docs.agents":       "claude/opus",
+        "docs.translate":    "codex/gpt-5.4",
+        "spec.gate":         "claude/sonnet",
+        "flow.review.draft": "codex/gpt-5.4",
+        "flow.review.final": "claude/opus",
+        "flow.review.test":  "claude/sonnet",
+        "flow.review.spec":  "claude/sonnet",
+        "flow.retro":        "claude/sonnet",
+        "context.search":    "claude/sonnet"
+      }
     }
   }
 }

package/src/templates/partials/core-principle.md

@@ -8,6 +8,6 @@ Before presenting any choice to the user, you MUST run `sdd-forge flow get statu
 - Continue to the next step without waiting for user input only when `autoApprove: true`.
 - If a step fails (command error, gate FAIL, test failure), apply the retry limits defined in each skill. If the retry limit is reached, STOP and return control to the user.
 
-**NEVER run `sdd-forge flow set auto on` yourself.** Only the user can enable autoApprove mode (via `/sdd-forge.flow-auto-on` or explicit instruction). The AI reads `autoApprove` from flow.json but never writes it.
+**NEVER run `sdd-forge flow set auto on` yourself.** Only the user can enable autoApprove mode (via `/sdd-forge.flow-auto` or explicit instruction). The AI reads `autoApprove` from flow.json but never writes it.
 
-**NEVER chain or background `sdd-forge` commands.** Each `sdd-forge` command must be run as a separate, foreground Bash invocation. Do not use `&&`, `||`, `;`, pipes, or `run_in_background`. Every command's result determines the next action, so it must complete and be read before proceeding.
+**NEVER chain or background `sdd-forge` commands.** Each `sdd-forge` command must be run as a separate, foreground Bash invocation. Do not use `&&`, `||`, `;`, pipes, or `run_in_background`. If a command nevertheless ends up in the background (e.g., due to tool behavior), wait for its completion notification before proceeding — do not treat it as complete or advance to the next step until the command's result has been received and read.

package/src/templates/skills/{sdd-forge.flow-auto-on → sdd-forge.flow-auto}/SKILL.md

@@ -1,14 +1,31 @@
 ---
-name: sdd-forge.flow-auto-on
-description: Enable autoApprove mode for the current SDD flow. The AI will automatically select default choices (id=1) and proceed without user confirmation.
+name: sdd-forge.flow-auto
+description: Toggle autoApprove mode for the current SDD flow. Use "on" to enable (default) or "off" to disable.
 ---
 
-# SDD Flow Auto ON
+# SDD Flow Auto
 
-Enable autoApprove mode and continue the current flow automatically.
+Toggle autoApprove mode for the current SDD flow.
+
+**Usage:** `/sdd-forge.flow-auto [on|off]`
+- No argument → treated as `on`
+- `on` → enable autoApprove and continue the flow automatically
+- `off` → disable autoApprove
+- Any other argument → show error and stop
 
 ## Procedure
 
+### If argument is `off`
+
+1. Disable autoApprove.
+   - Run `sdd-forge flow set auto off`.
+   - If it fails (e.g. no active flow), display the error message and STOP.
+
+2. Confirm.
+   - Display: "autoApprove mode has been disabled. The AI will ask for confirmation at each step."
+
+### If argument is `on` or no argument
+
 1. Check flow state.
    - Run `sdd-forge flow get status`.
    - If the command fails or returns `ok: false`, display: "No active flow. Start a flow first with `/sdd-forge.flow-plan`." and STOP.
@@ -29,3 +46,7 @@ Enable autoApprove mode and continue the current flow automatically.
      - If all plan and impl steps are `done` but finalize-phase steps (commit, push, merge, pr-create, branch-cleanup) have any not `done` → invoke `/sdd-forge.flow-finalize`
      - If all steps are `done` → display "All steps are already complete." and STOP.
    - Use the Skill tool to invoke the determined skill.
+
+### If argument is anything else
+
+- Display: "Unknown argument: '<argument>'. Usage: /sdd-forge.flow-auto [on|off]" and STOP.

package/src/templates/skills/sdd-forge.flow-finalize/SKILL.md

@@ -82,7 +82,7 @@ Available status values: `pending`, `in_progress`, `done`, `skipped`
 
 - Do not run `sdd-forge flow run finalize` if resolve-context reports `dirty: true` and commit step is not included.
 - Do not proceed to next step without user confirmation.
-- **NEVER chain or background `sdd-forge` commands.** Each `sdd-forge` command must be run as a separate, foreground Bash invocation. Do not use `&&`, `||`, `;`, pipes, or `run_in_background`. Every command's result determines the next action, so it must complete and be read before proceeding.
+- **NEVER chain or background `sdd-forge` commands.** Each `sdd-forge` command must be run as a separate, foreground Bash invocation. Do not use `&&`, `||`, `;`, pipes, or `run_in_background`. If a command nevertheless ends up in the background (e.g., due to tool behavior), wait for its completion notification before proceeding — do not treat it as complete or advance to the next step until the command's result has been received and read.
 
 **autoApprove exception:** When `autoApprove: true`, the rule "do not proceed to next step without user confirmation" does NOT apply. All other hard stops remain in effect.
 

package/src/upgrade.js

@@ -19,7 +19,7 @@ import { repoRoot, parseArgs } from "./lib/cli.js";
 import { EXIT_ERROR } from "./lib/exit-codes.js";
 import { loadConfig, sddConfigPath } from "./lib/config.js";
 import { translate } from "./lib/i18n.js";
-import { deploySkills, deployProjectSkills } from "./lib/skills.js";
+import { deploySkills, deployProjectSkills, cleanupObsoleteSkills, MAIN_SKILLS_TEMPLATES_DIR } from "./lib/skills.js";
 
 
 // ---------------------------------------------------------------------------
@@ -65,7 +65,18 @@ async function main() {
     console.log(t("ui:upgrade.dryRunHeader"));
   }
 
+  function logSkillResults(results) {
+    for (const { name, status } of results) {
+      if (status === "updated") {
+        console.log(t("ui:upgrade.skillUpdated", { name }));
+      } else {
+        console.log(t("ui:upgrade.skillUnchanged", { name }));
+      }
+    }
+  }
+
   // 1. Skills upgrade
+  const validTemplatesDirs = [MAIN_SKILLS_TEMPLATES_DIR];
   let skillResults;
   try {
     skillResults = deploySkills(root, config.lang, { dryRun });
@@ -73,28 +84,23 @@ async function main() {
     console.error(`upgrade failed: ${e.message}`);
     process.exit(EXIT_ERROR);
   }
-  for (const { name, status } of skillResults) {
-    if (status === "updated") {
-      console.log(t("ui:upgrade.skillUpdated", { name }));
-    } else {
-      console.log(t("ui:upgrade.skillUnchanged", { name }));
-    }
-  }
+  logSkillResults(skillResults);
 
   // 1b. Experimental skills (opt-in via config flags)
   if (config.experimental?.workflow?.enable === true) {
     const expDir = path.join(root, "experimental", "workflow", "templates", "skills");
+    validTemplatesDirs.push(expDir);
     const expResults = deployProjectSkills(root, expDir, config.lang, { dryRun });
-    for (const { name, status } of expResults) {
-      if (status === "updated") {
-        console.log(t("ui:upgrade.skillUpdated", { name }));
-      } else {
-        console.log(t("ui:upgrade.skillUnchanged", { name }));
-      }
-    }
+    logSkillResults(expResults);
     skillResults.push(...expResults);
   }
 
+  // 1c. Remove obsolete sdd-forge.* skills no longer in any template directory
+  const removedSkills = cleanupObsoleteSkills(root, validTemplatesDirs, { dryRun });
+  for (const { name } of removedSkills) {
+    console.log(t("ui:upgrade.skillRemoved", { name }));
+  }
+
   // 2. Migrate chapters format (string[] → object[])
   const configPath = sddConfigPath(root);
   try {
@@ -111,7 +117,7 @@ async function main() {
   }
 
   // Summary
-  const hasChanges = skillResults.some((r) => r.status === "updated");
+  const hasChanges = skillResults.some((r) => r.status === "updated") || removedSkills.length > 0;
   if (!hasChanges) {
     console.log(t("ui:upgrade.noChanges"));
   } else if (dryRun) {

package/src/templates/skills/sdd-forge.flow-auto-off/SKILL.md

@@ -1,17 +0,0 @@
----
-name: sdd-forge.flow-auto-off
-description: Disable autoApprove mode for the current SDD flow. The AI will resume asking the user for confirmation at each step.
----
-
-# SDD Flow Auto OFF
-
-Disable autoApprove mode.
-
-## Procedure
-
-1. Disable autoApprove.
-   - Run `sdd-forge flow set auto off`.
-   - If it fails (e.g. no active flow), display the error message and STOP.
-
-2. Confirm.
-   - Display: "autoApprove mode has been disabled. The AI will ask for confirmation at each step."