@agiflowai/aicode-toolkit 1.0.20 → 1.0.22

package/README.md

@@ -56,6 +56,89 @@ This will:
 | `--path <path>` | Custom templates path | `./templates` |
 | `--no-download` | Skip template download | `false` |
 
+### `sync`
+
+Generate platform config files from `.toolkit/settings.yaml` as the single source of truth.
+
+```bash
+# Generate both .claude/settings.json and mcp-config.yaml
+npx @agiflowai/aicode-toolkit sync
+
+# Generate only .claude/settings.json (Claude Code hooks)
+npx @agiflowai/aicode-toolkit sync --hooks
+
+# Generate only mcp-config.yaml (MCP server list)
+npx @agiflowai/aicode-toolkit sync --mcp
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--hooks` | Write `.claude/settings.json` only |
+| `--mcp` | Write `mcp-config.yaml` only |
+
+#### Hooks → `.claude/settings.json`
+
+Hook commands are derived automatically from `mcp-config.servers` by replacing
+`mcp-serve` with `hook --type claude-code.<method>`. Configure which methods to
+activate in `.toolkit/settings.yaml`:
+
+```yaml
+scaffold-mcp:
+  hook:
+    claude-code:
+      preToolUse:
+        args:           # extra CLI args appended to the generated hook command
+          llm-tool: gemini-cli
+      postToolUse: {}
+      stop: {}
+      userPromptSubmit: {}
+      taskCompleted: {}
+
+architect-mcp:
+  hook:
+    claude-code:
+      preToolUse:
+        args:
+          llm-tool: gemini-cli
+      postToolUse: {}
+```
+
+Generated hook entries fire on all tool calls (no matcher). Run `aicode sync --hooks`
+to write `.claude/settings.json`.
+
+#### `mcp-config` section → `mcp-config.yaml`
+
+Define MCP servers in `.toolkit/settings.yaml`:
+
+```yaml
+mcp-config:
+  servers:
+    scaffold-mcp:
+      command: bun
+      args:
+        - run
+        - packages/scaffold-mcp/src/cli.ts
+        - mcp-serve
+        - --admin-enable
+        - --prompt-as-skill
+      instruction: "Use this server for generating boilerplate code and scaffolding."
+    architect-mcp:
+      command: bun
+      args:
+        - run
+        - packages/architect-mcp/src/cli.ts
+        - mcp-serve
+      instruction: "Use this server for design pattern guidance and code review."
+  skills:
+    paths:
+      - docs/skills
+```
+
+Run `aicode sync --mcp` to write `mcp-config.yaml` from this config.
+
+---
+
 ### `add`
 
 Add templates from GitHub repositories.

package/dist/cli.cjs

@@ -2,16 +2,20 @@
 const require_utils = require('./utils-r_182Nor.cjs');
 const require_mcp = require('./mcp--A-5zuBI.cjs');
 let __agiflowai_aicode_utils = require("@agiflowai/aicode-utils");
+let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
 node_path = require_utils.__toESM(node_path);
+let liquidjs = require("liquidjs");
 let commander = require("commander");
 let __inquirer_prompts = require("@inquirer/prompts");
 let ora = require("ora");
 ora = require_utils.__toESM(ora);
 let xstate = require("xstate");
+let js_yaml = require("js-yaml");
+js_yaml = require_utils.__toESM(js_yaml);
 
 //#region package.json
-var version = "1.0.19";
+var version = "1.0.21";
 
 //#endregion
 //#region src/commands/add.ts
@@ -75,6 +79,10 @@ const addCommand = new commander.Command("add").description("Add a template to t
 	}
 });
 
+//#endregion
+//#region src/templates/settings.yaml.liquid?raw
+var settings_yaml_default = "# .toolkit/settings.yaml\n# Toolkit configuration for aicode-toolkit\n#\n# Local overrides go in .toolkit/settings.local.yaml (add to .gitignore).\n# Local settings are shallow-merged over this file — useful for per-developer\n# LLM tool preferences or API keys without committing them.\n\n# ---------------------------------------------------------------------------\n# Project identity\n# ---------------------------------------------------------------------------\n{% if projectType %}\nprojectType: {{ projectType }}\n{% else %}\n# projectType: monolith\n{% endif %}\n{% if templatesPath %}\ntemplatesPath: {{ templatesPath }}\n{% else %}\n# templatesPath: ./templates\n{% endif %}\n{% if sourceTemplate %}\nsourceTemplate: {{ sourceTemplate }}\n{% else %}\n# sourceTemplate: react-vite\n{% endif %}\nversion: '1.0'\n\n# ---------------------------------------------------------------------------\n# scaffold-mcp — configuration for the scaffold-mcp CLI\n# CLI flags always take precedence over values set here.\n# ---------------------------------------------------------------------------\n\nscaffold-mcp:\n\n  # -------------------------------------------------------------------------\n  # mcp-serve — defaults for `scaffold-mcp mcp-serve`\n  # -------------------------------------------------------------------------\n  mcp-serve:\n    # type: stdio\n    # port: 3000\n    # host: localhost\n    # adminEnable: false\n    # promptAsSkill: false\n    {% if fallbackTool %}\n    fallbackTool: {{ fallbackTool }}\n    {% if fallbackToolConfig %}\n    fallbackToolConfig:\n      {% for pair in fallbackToolConfig %}\n      {{ pair[0] }}: {{ pair[1] }}\n      {% endfor %}\n    {% else %}\n    # fallbackToolConfig:\n    #   model: gemini-2.0-flash\n    {% endif %}\n    {% else %}\n    # fallbackTool: gemini-cli\n    # fallbackToolConfig:\n    #   model: gemini-2.0-flash\n    {% endif %}\n    # Extra CLI args merged into the mcp-serve command (key: value → --key value)\n    # args:\n    #   review-tool: gemini-cli\n\n  # -------------------------------------------------------------------------\n  # hook — defaults for `scaffold-mcp hook`\n  # Keyed by agent name, then by hook method.\n  # Supported agents  : claude-code | gemini-cli\n  # Supported methods : preToolUse | postToolUse | userPromptSubmit | taskCompleted | stop\n  # -------------------------------------------------------------------------\n  hook:\n\n    claude-code:\n      preToolUse:\n        {% if fallbackTool %}\n        llm-tool: {{ fallbackTool }}\n        {% if fallbackToolConfig %}\n        tool-config:\n          {% for pair in fallbackToolConfig %}\n          {{ pair[0] }}: {{ pair[1] }}\n          {% endfor %}\n        {% endif %}\n        {% else %}\n        # llm-tool: gemini-cli\n        # tool-config:\n        #   model: gemini-2.0-flash\n        {% endif %}\n        # args:\n        #   llm-tool: gemini-cli\n\n      postToolUse:\n        {% if fallbackTool %}\n        llm-tool: {{ fallbackTool }}\n        {% if fallbackToolConfig %}\n        tool-config:\n          {% for pair in fallbackToolConfig %}\n          {{ pair[0] }}: {{ pair[1] }}\n          {% endfor %}\n        {% endif %}\n        {% else %}\n        # llm-tool: gemini-cli\n        # tool-config:\n        #   model: gemini-2.0-flash\n        {% endif %}\n        # args:\n        #   llm-tool: gemini-cli\n\n    gemini-cli:\n      postToolUse:\n        {% if fallbackTool %}\n        llm-tool: {{ fallbackTool }}\n        {% if fallbackToolConfig %}\n        tool-config:\n          {% for pair in fallbackToolConfig %}\n          {{ pair[0] }}: {{ pair[1] }}\n          {% endfor %}\n        {% endif %}\n        {% else %}\n        # llm-tool: gemini-cli\n        # tool-config:\n        #   model: gemini-2.0-flash\n        {% endif %}\n\n# ---------------------------------------------------------------------------\n# architect-mcp — configuration for the architect-mcp CLI\n# CLI flags always take precedence over values set here.\n# ---------------------------------------------------------------------------\n\narchitect-mcp:\n\n  # -------------------------------------------------------------------------\n  # mcp-serve — defaults for `architect-mcp mcp-serve`\n  # -------------------------------------------------------------------------\n  mcp-serve:\n    # type: stdio\n    # port: 3000\n    # host: localhost\n    # adminEnable: false\n    {% if fallbackTool %}\n    fallbackTool: {{ fallbackTool }}\n    {% if fallbackToolConfig %}\n    fallbackToolConfig:\n      {% for pair in fallbackToolConfig %}\n      {{ pair[0] }}: {{ pair[1] }}\n      {% endfor %}\n    {% else %}\n    # fallbackToolConfig:\n    #   model: gemini-2.0-flash\n    {% endif %}\n    {% else %}\n    # fallbackTool: gemini-cli\n    # fallbackToolConfig:\n    #   model: gemini-2.0-flash\n    {% endif %}\n    # designPatternTool: gemini-cli\n    # designPatternToolConfig:\n    #   model: gemini-2.0-flash\n    # reviewTool: gemini-cli\n    # reviewToolConfig:\n    #   model: gemini-2.0-flash\n    # Extra CLI args merged into the mcp-serve command (key: value → --key value)\n    # args:\n    #   review-tool: gemini-cli\n\n  # -------------------------------------------------------------------------\n  # hook — defaults for `architect-mcp hook`\n  # Keyed by agent name, then by hook method.\n  # Supported agents  : claude-code | gemini-cli\n  # Supported methods : preToolUse | postToolUse\n  # -------------------------------------------------------------------------\n  hook:\n\n    claude-code:\n      preToolUse:\n        {% if fallbackTool %}\n        llm-tool: {{ fallbackTool }}\n        {% if fallbackToolConfig %}\n        tool-config:\n          {% for pair in fallbackToolConfig %}\n          {{ pair[0] }}: {{ pair[1] }}\n          {% endfor %}\n        {% endif %}\n        {% else %}\n        # llm-tool: gemini-cli\n        # tool-config:\n        #   model: gemini-2.0-flash\n        {% endif %}\n        # args:\n        #   llm-tool: gemini-cli\n\n      postToolUse:\n        {% if fallbackTool %}\n        llm-tool: {{ fallbackTool }}\n        {% if fallbackToolConfig %}\n        tool-config:\n          {% for pair in fallbackToolConfig %}\n          {{ pair[0] }}: {{ pair[1] }}\n          {% endfor %}\n        {% endif %}\n        {% else %}\n        # llm-tool: gemini-cli\n        # tool-config:\n        #   model: gemini-2.0-flash\n        {% endif %}\n        # args:\n        #   llm-tool: gemini-cli\n\n    gemini-cli:\n      preToolUse:\n        {% if fallbackTool %}\n        llm-tool: {{ fallbackTool }}\n        {% if fallbackToolConfig %}\n        tool-config:\n          {% for pair in fallbackToolConfig %}\n          {{ pair[0] }}: {{ pair[1] }}\n          {% endfor %}\n        {% endif %}\n        {% else %}\n        # llm-tool: gemini-cli\n        # tool-config:\n        #   model: gemini-2.0-flash\n        {% endif %}\n\n      postToolUse:\n        {% if fallbackTool %}\n        llm-tool: {{ fallbackTool }}\n        {% if fallbackToolConfig %}\n        tool-config:\n          {% for pair in fallbackToolConfig %}\n          {{ pair[0] }}: {{ pair[1] }}\n          {% endfor %}\n        {% endif %}\n        {% else %}\n        # llm-tool: gemini-cli\n        # tool-config:\n        #   model: gemini-2.0-flash\n        {% endif %}\n\n# ---------------------------------------------------------------------------\n# mcp-config — generates mcp-config.yaml via `aicode sync --mcp`\n# Servers listed here become entries in mcp-config.yaml.\n# Run `aicode sync` to write the output file.\n# ---------------------------------------------------------------------------\n\n# mcp-config:\n#   servers:\n#     scaffold-mcp:\n#       command: bun\n#       args:\n#         - run\n#         - packages/scaffold-mcp/src/cli.ts\n#         - mcp-serve\n#         - --admin-enable\n#         - --prompt-as-skill\n#       instruction: \"Use this server for generating boilerplate code, scaffolding new projects, and adding features to existing projects.\"\n#     architect-mcp:\n#       command: bun\n#       args:\n#         - run\n#         - packages/architect-mcp/src/cli.ts\n#         - mcp-serve\n#       instruction: \"Use this server for design pattern guidance and code review.\"\n#   skills:\n#     paths:\n#       - docs/skills\n";
+
 //#endregion
 //#region src/states/init-machine.ts
 /**
@@ -721,15 +729,21 @@ const initActors = {
 	}),
 	createConfig: (0, xstate.fromPromise)(async ({ input: actorInput }) => {
 		if (actorInput.projectType === __agiflowai_aicode_utils.ProjectType.MONOLITH) {
-			const toolkitConfig = {
-				version: "1.0",
-				templatesPath: node_path.default.relative(actorInput.workspaceRoot, actorInput.templatesPath) || "templates",
+			const relativeTemplatesPath = node_path.default.relative(actorInput.workspaceRoot, actorInput.templatesPath);
+			const content = await new liquidjs.Liquid().parseAndRender(settings_yaml_default, {
 				projectType: "monolith",
+				templatesPath: relativeTemplatesPath || "templates",
 				sourceTemplate: actorInput.selectedTemplates[0]
-			};
-			__agiflowai_aicode_utils.print.info("\nCreating toolkit.yaml...");
-			await __agiflowai_aicode_utils.TemplatesManagerService.writeToolkitConfig(toolkitConfig, actorInput.workspaceRoot);
-			__agiflowai_aicode_utils.print.success("toolkit.yaml created");
+			});
+			const toolkitDir = node_path.default.join(actorInput.workspaceRoot, ".toolkit");
+			const settingsPath = node_path.default.join(toolkitDir, "settings.yaml");
+			__agiflowai_aicode_utils.print.info("\nCreating .toolkit/settings.yaml...");
+			await (0, node_fs_promises.mkdir)(toolkitDir, { recursive: true });
+			await (0, node_fs_promises.writeFile)(settingsPath, content, {
+				encoding: "utf-8",
+				flag: "w"
+			});
+			__agiflowai_aicode_utils.print.success(".toolkit/settings.yaml created");
 		}
 	}),
 	detectCodingAgent: (0, xstate.fromPromise)(async ({ input: actorInput }) => {
@@ -897,17 +911,176 @@ const initCommand = new commander.Command("init").description("Initialize projec
 	}
 });
 
+//#endregion
+//#region src/commands/sync.ts
+/**
+* Sync Command
+*
+* DESIGN PATTERNS:
+* - Command pattern with Commander for CLI argument parsing
+* - Async/await pattern for asynchronous operations
+* - Error handling pattern with try-catch and proper exit codes
+*
+* CODING STANDARDS:
+* - Use async action handlers for asynchronous operations
+* - Provide clear option descriptions and default values
+* - Handle errors gracefully with process.exit()
+* - Log progress and errors to console
+* - Use Commander's .option() and .argument() for inputs
+*
+* AVOID:
+* - Synchronous blocking operations in action handlers
+* - Missing error handling (always use try-catch)
+* - Hardcoded values (use options or environment variables)
+* - Not exiting with appropriate exit codes on errors
+*/
+const CLAUDE_SETTINGS_DIR = ".claude";
+const CLAUDE_SETTINGS_FILE = "settings.json";
+const MCP_CONFIG_FILE = "mcp-config.yaml";
+function hasHookConfig(config) {
+	return !!(config["scaffold-mcp"]?.hook?.["claude-code"] || config["architect-mcp"]?.hook?.["claude-code"]);
+}
+function argsToFlags(args) {
+	const flags = [];
+	for (const [key, value] of Object.entries(args)) {
+		if (value === false) continue;
+		flags.push(`--${key}`);
+		if (value !== true) flags.push(String(value));
+	}
+	return flags;
+}
+function buildHookCommand(server, hookType, extraFlags) {
+	const serverArgs = server.args ?? [];
+	const scriptIdx = serverArgs.findIndex((arg) => /\.(ts|js|mjs|cjs)$/.test(arg));
+	if (scriptIdx >= 0) {
+		const prefixArgs$1 = serverArgs.slice(0, scriptIdx + 1);
+		return [
+			server.command,
+			...prefixArgs$1,
+			"hook",
+			"--type",
+			hookType,
+			...extraFlags
+		].join(" ");
+	}
+	const mcpServeIdx = serverArgs.indexOf("mcp-serve");
+	const prefixArgs = mcpServeIdx >= 0 ? serverArgs.slice(0, mcpServeIdx) : serverArgs;
+	return [
+		server.command,
+		...prefixArgs,
+		"hook",
+		"--type",
+		hookType,
+		...extraFlags
+	].join(" ");
+}
+function addHookEntry(output, event, command) {
+	if (!output[event]) output[event] = [];
+	output[event].push({ hooks: [{
+		type: "command",
+		command
+	}] });
+}
+function isMcpConfigYaml(value) {
+	return typeof value === "object" && value !== null;
+}
+async function readMcpConfigYaml(workspaceRoot) {
+	try {
+		const content = await (0, node_fs_promises.readFile)(node_path.default.join(workspaceRoot, MCP_CONFIG_FILE), "utf-8");
+		const parsed = js_yaml.default.load(content);
+		if (!isMcpConfigYaml(parsed)) throw new Error(`${MCP_CONFIG_FILE} has unexpected structure`);
+		return parsed;
+	} catch (err) {
+		if (err instanceof Error && "code" in err && err.code === "ENOENT") return {};
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to read ${MCP_CONFIG_FILE}: ${message}`);
+	}
+}
+const METHOD_TO_EVENT = {
+	preToolUse: "PreToolUse",
+	postToolUse: "PostToolUse",
+	stop: "Stop",
+	userPromptSubmit: "UserPromptSubmit",
+	taskCompleted: "TaskCompleted"
+};
+async function writeClaudeSettings(config, workspaceRoot) {
+	try {
+		const mcpServers = (await readMcpConfigYaml(workspaceRoot)).mcpServers ?? {};
+		const hooksOutput = {};
+		let hasAny = false;
+		const scaffoldAgent = config["scaffold-mcp"]?.hook?.["claude-code"];
+		const scaffoldServer = mcpServers["scaffold-mcp"];
+		if (scaffoldAgent && scaffoldServer) for (const [method, methodConfig] of [
+			["preToolUse", scaffoldAgent.preToolUse],
+			["postToolUse", scaffoldAgent.postToolUse],
+			["stop", scaffoldAgent.stop],
+			["userPromptSubmit", scaffoldAgent.userPromptSubmit],
+			["taskCompleted", scaffoldAgent.taskCompleted]
+		]) {
+			if (methodConfig === void 0) continue;
+			const extraFlags = methodConfig?.args ? argsToFlags(methodConfig?.args) : [];
+			const command = buildHookCommand(scaffoldServer, `claude-code.${method}`, extraFlags);
+			addHookEntry(hooksOutput, METHOD_TO_EVENT[method], command);
+			hasAny = true;
+		}
+		const architectAgent = config["architect-mcp"]?.hook?.["claude-code"];
+		const architectServer = mcpServers["architect-mcp"];
+		if (architectAgent && architectServer) for (const [method, methodConfig] of [["preToolUse", architectAgent.preToolUse], ["postToolUse", architectAgent.postToolUse]]) {
+			if (methodConfig === void 0) continue;
+			const extraFlags = methodConfig?.args ? argsToFlags(methodConfig?.args) : [];
+			const command = buildHookCommand(architectServer, `claude-code.${method}`, extraFlags);
+			addHookEntry(hooksOutput, METHOD_TO_EVENT[method], command);
+			hasAny = true;
+		}
+		if (!hasAny) {
+			__agiflowai_aicode_utils.print.warning("No scaffold-mcp/architect-mcp hook.claude-code config found — skipping .claude/settings.json");
+			return;
+		}
+		const settings = { hooks: hooksOutput };
+		const claudeDir = node_path.default.join(workspaceRoot, CLAUDE_SETTINGS_DIR);
+		await (0, node_fs_promises.mkdir)(claudeDir, { recursive: true });
+		await (0, node_fs_promises.writeFile)(node_path.default.join(claudeDir, CLAUDE_SETTINGS_FILE), JSON.stringify(settings, null, 2), "utf-8");
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to write ${CLAUDE_SETTINGS_DIR}/${CLAUDE_SETTINGS_FILE}: ${message}`);
+	}
+}
+/**
+* Generate .claude/settings.json from .toolkit/settings.yaml and mcp-config.yaml
+*/
+const syncCommand = new commander.Command("sync").description("Generate .claude/settings.json from .toolkit/settings.yaml and mcp-config.yaml").action(async () => {
+	try {
+		const [workspaceRoot, config] = await Promise.all([__agiflowai_aicode_utils.TemplatesManagerService.getWorkspaceRoot(), __agiflowai_aicode_utils.TemplatesManagerService.readToolkitConfig()]);
+		if (!config) throw new Error("No .toolkit/settings.yaml found. Run `aicode init` first.");
+		if (hasHookConfig(config)) {
+			await writeClaudeSettings(config, workspaceRoot);
+			__agiflowai_aicode_utils.print.success("Written .claude/settings.json");
+		} else __agiflowai_aicode_utils.print.warning("No hook.claude-code config found in settings.yaml — skipping");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		__agiflowai_aicode_utils.print.error(`sync failed: ${message}`);
+		process.exit(1);
+	}
+});
+
 //#endregion
 //#region src/cli.ts
 /**
 * Main entry point
 */
 async function main() {
-	const program = new commander.Command();
-	program.name("aicode").description("AI-powered code toolkit CLI for scaffolding, architecture management, and development workflows").version(version);
-	program.addCommand(initCommand);
-	program.addCommand(addCommand);
-	await program.parseAsync(process.argv);
+	try {
+		const program = new commander.Command();
+		program.name("aicode").description("AI-powered code toolkit CLI for scaffolding, architecture management, and development workflows").version(version);
+		program.addCommand(initCommand);
+		program.addCommand(addCommand);
+		program.addCommand(syncCommand);
+		await program.parseAsync(process.argv);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.error(`aicode: ${message}`);
+		process.exit(1);
+	}
 }
 main();
 

package/dist/cli.mjs

@@ -2,14 +2,17 @@
 import { r as MCP_SERVER_INFO, t as MCPServer } from "./mcp-CBcPdzNG.mjs";
 import { a as SPEC_TOOL_INFO, c as NewProjectService, i as TemplateSelectionService, l as CodingAgentService, o as SpecTool, s as SpecToolService, t as displayBanner } from "./utils-QWjfWNVp.mjs";
 import { ProjectType, TemplatesManagerService, cloneRepository, cloneSubdirectory, detectProjectType, ensureDir, findWorkspaceRoot, icons, messages, parseGitHubUrl, pathExists, print, sections } from "@agiflowai/aicode-utils";
+import { mkdir as mkdir$1, readFile as readFile$1, writeFile as writeFile$1 } from "node:fs/promises";
 import path from "node:path";
+import { Liquid } from "liquidjs";
 import { Command } from "commander";
 import { confirm, input, select } from "@inquirer/prompts";
 import ora from "ora";
 import { assign, createActor, createMachine, fromPromise } from "xstate";
+import yaml from "js-yaml";
 
 //#region package.json
-var version = "1.0.19";
+var version = "1.0.21";
 
 //#endregion
 //#region src/commands/add.ts
@@ -73,6 +76,10 @@ const addCommand = new Command("add").description("Add a template to templates f
 	}
 });
 
+//#endregion
+//#region src/templates/settings.yaml.liquid?raw
+var settings_yaml_default = "# .toolkit/settings.yaml\n# Toolkit configuration for aicode-toolkit\n#\n# Local overrides go in .toolkit/settings.local.yaml (add to .gitignore).\n# Local settings are shallow-merged over this file — useful for per-developer\n# LLM tool preferences or API keys without committing them.\n\n# ---------------------------------------------------------------------------\n# Project identity\n# ---------------------------------------------------------------------------\n{% if projectType %}\nprojectType: {{ projectType }}\n{% else %}\n# projectType: monolith\n{% endif %}\n{% if templatesPath %}\ntemplatesPath: {{ templatesPath }}\n{% else %}\n# templatesPath: ./templates\n{% endif %}\n{% if sourceTemplate %}\nsourceTemplate: {{ sourceTemplate }}\n{% else %}\n# sourceTemplate: react-vite\n{% endif %}\nversion: '1.0'\n\n# ---------------------------------------------------------------------------\n# scaffold-mcp — configuration for the scaffold-mcp CLI\n# CLI flags always take precedence over values set here.\n# ---------------------------------------------------------------------------\n\nscaffold-mcp:\n\n  # -------------------------------------------------------------------------\n  # mcp-serve — defaults for `scaffold-mcp mcp-serve`\n  # -------------------------------------------------------------------------\n  mcp-serve:\n    # type: stdio\n    # port: 3000\n    # host: localhost\n    # adminEnable: false\n    # promptAsSkill: false\n    {% if fallbackTool %}\n    fallbackTool: {{ fallbackTool }}\n    {% if fallbackToolConfig %}\n    fallbackToolConfig:\n      {% for pair in fallbackToolConfig %}\n      {{ pair[0] }}: {{ pair[1] }}\n      {% endfor %}\n    {% else %}\n    # fallbackToolConfig:\n    #   model: gemini-2.0-flash\n    {% endif %}\n    {% else %}\n    # fallbackTool: gemini-cli\n    # fallbackToolConfig:\n    #   model: gemini-2.0-flash\n    {% endif %}\n    # Extra CLI args merged into the mcp-serve command (key: value → --key value)\n    # args:\n    #   review-tool: gemini-cli\n\n  # -------------------------------------------------------------------------\n  # hook — defaults for `scaffold-mcp hook`\n  # Keyed by agent name, then by hook method.\n  # Supported agents  : claude-code | gemini-cli\n  # Supported methods : preToolUse | postToolUse | userPromptSubmit | taskCompleted | stop\n  # -------------------------------------------------------------------------\n  hook:\n\n    claude-code:\n      preToolUse:\n        {% if fallbackTool %}\n        llm-tool: {{ fallbackTool }}\n        {% if fallbackToolConfig %}\n        tool-config:\n          {% for pair in fallbackToolConfig %}\n          {{ pair[0] }}: {{ pair[1] }}\n          {% endfor %}\n        {% endif %}\n        {% else %}\n        # llm-tool: gemini-cli\n        # tool-config:\n        #   model: gemini-2.0-flash\n        {% endif %}\n        # args:\n        #   llm-tool: gemini-cli\n\n      postToolUse:\n        {% if fallbackTool %}\n        llm-tool: {{ fallbackTool }}\n        {% if fallbackToolConfig %}\n        tool-config:\n          {% for pair in fallbackToolConfig %}\n          {{ pair[0] }}: {{ pair[1] }}\n          {% endfor %}\n        {% endif %}\n        {% else %}\n        # llm-tool: gemini-cli\n        # tool-config:\n        #   model: gemini-2.0-flash\n        {% endif %}\n        # args:\n        #   llm-tool: gemini-cli\n\n    gemini-cli:\n      postToolUse:\n        {% if fallbackTool %}\n        llm-tool: {{ fallbackTool }}\n        {% if fallbackToolConfig %}\n        tool-config:\n          {% for pair in fallbackToolConfig %}\n          {{ pair[0] }}: {{ pair[1] }}\n          {% endfor %}\n        {% endif %}\n        {% else %}\n        # llm-tool: gemini-cli\n        # tool-config:\n        #   model: gemini-2.0-flash\n        {% endif %}\n\n# ---------------------------------------------------------------------------\n# architect-mcp — configuration for the architect-mcp CLI\n# CLI flags always take precedence over values set here.\n# ---------------------------------------------------------------------------\n\narchitect-mcp:\n\n  # -------------------------------------------------------------------------\n  # mcp-serve — defaults for `architect-mcp mcp-serve`\n  # -------------------------------------------------------------------------\n  mcp-serve:\n    # type: stdio\n    # port: 3000\n    # host: localhost\n    # adminEnable: false\n    {% if fallbackTool %}\n    fallbackTool: {{ fallbackTool }}\n    {% if fallbackToolConfig %}\n    fallbackToolConfig:\n      {% for pair in fallbackToolConfig %}\n      {{ pair[0] }}: {{ pair[1] }}\n      {% endfor %}\n    {% else %}\n    # fallbackToolConfig:\n    #   model: gemini-2.0-flash\n    {% endif %}\n    {% else %}\n    # fallbackTool: gemini-cli\n    # fallbackToolConfig:\n    #   model: gemini-2.0-flash\n    {% endif %}\n    # designPatternTool: gemini-cli\n    # designPatternToolConfig:\n    #   model: gemini-2.0-flash\n    # reviewTool: gemini-cli\n    # reviewToolConfig:\n    #   model: gemini-2.0-flash\n    # Extra CLI args merged into the mcp-serve command (key: value → --key value)\n    # args:\n    #   review-tool: gemini-cli\n\n  # -------------------------------------------------------------------------\n  # hook — defaults for `architect-mcp hook`\n  # Keyed by agent name, then by hook method.\n  # Supported agents  : claude-code | gemini-cli\n  # Supported methods : preToolUse | postToolUse\n  # -------------------------------------------------------------------------\n  hook:\n\n    claude-code:\n      preToolUse:\n        {% if fallbackTool %}\n        llm-tool: {{ fallbackTool }}\n        {% if fallbackToolConfig %}\n        tool-config:\n          {% for pair in fallbackToolConfig %}\n          {{ pair[0] }}: {{ pair[1] }}\n          {% endfor %}\n        {% endif %}\n        {% else %}\n        # llm-tool: gemini-cli\n        # tool-config:\n        #   model: gemini-2.0-flash\n        {% endif %}\n        # args:\n        #   llm-tool: gemini-cli\n\n      postToolUse:\n        {% if fallbackTool %}\n        llm-tool: {{ fallbackTool }}\n        {% if fallbackToolConfig %}\n        tool-config:\n          {% for pair in fallbackToolConfig %}\n          {{ pair[0] }}: {{ pair[1] }}\n          {% endfor %}\n        {% endif %}\n        {% else %}\n        # llm-tool: gemini-cli\n        # tool-config:\n        #   model: gemini-2.0-flash\n        {% endif %}\n        # args:\n        #   llm-tool: gemini-cli\n\n    gemini-cli:\n      preToolUse:\n        {% if fallbackTool %}\n        llm-tool: {{ fallbackTool }}\n        {% if fallbackToolConfig %}\n        tool-config:\n          {% for pair in fallbackToolConfig %}\n          {{ pair[0] }}: {{ pair[1] }}\n          {% endfor %}\n        {% endif %}\n        {% else %}\n        # llm-tool: gemini-cli\n        # tool-config:\n        #   model: gemini-2.0-flash\n        {% endif %}\n\n      postToolUse:\n        {% if fallbackTool %}\n        llm-tool: {{ fallbackTool }}\n        {% if fallbackToolConfig %}\n        tool-config:\n          {% for pair in fallbackToolConfig %}\n          {{ pair[0] }}: {{ pair[1] }}\n          {% endfor %}\n        {% endif %}\n        {% else %}\n        # llm-tool: gemini-cli\n        # tool-config:\n        #   model: gemini-2.0-flash\n        {% endif %}\n\n# ---------------------------------------------------------------------------\n# mcp-config — generates mcp-config.yaml via `aicode sync --mcp`\n# Servers listed here become entries in mcp-config.yaml.\n# Run `aicode sync` to write the output file.\n# ---------------------------------------------------------------------------\n\n# mcp-config:\n#   servers:\n#     scaffold-mcp:\n#       command: bun\n#       args:\n#         - run\n#         - packages/scaffold-mcp/src/cli.ts\n#         - mcp-serve\n#         - --admin-enable\n#         - --prompt-as-skill\n#       instruction: \"Use this server for generating boilerplate code, scaffolding new projects, and adding features to existing projects.\"\n#     architect-mcp:\n#       command: bun\n#       args:\n#         - run\n#         - packages/architect-mcp/src/cli.ts\n#         - mcp-serve\n#       instruction: \"Use this server for design pattern guidance and code review.\"\n#   skills:\n#     paths:\n#       - docs/skills\n";
+
 //#endregion
 //#region src/states/init-machine.ts
 /**
@@ -598,11 +605,11 @@ const initActors = {
 	}),
 	checkTemplatesFolder: fromPromise(async ({ input: actorInput }) => {
 		try {
-			const fs = await import("node:fs/promises");
+			const fs$1 = await import("node:fs/promises");
 			const defaultTemplatesPath = path.join(actorInput.workspaceRoot, "templates");
 			let templatesExists = false;
 			try {
-				await fs.access(defaultTemplatesPath);
+				await fs$1.access(defaultTemplatesPath);
 				templatesExists = true;
 			} catch {
 				templatesExists = false;
@@ -630,7 +637,7 @@ const initActors = {
 					print.info("");
 					finalTemplatesPath = path.join(actorInput.workspaceRoot, customDir.trim());
 					try {
-						await fs.mkdir(finalTemplatesPath, { recursive: true });
+						await fs$1.mkdir(finalTemplatesPath, { recursive: true });
 						print.success(`Created templates directory at: ${finalTemplatesPath}`);
 					} catch (error) {
 						throw new Error(`Failed to create templates directory at ${finalTemplatesPath}: ${error.message}`);
@@ -719,15 +726,21 @@ const initActors = {
 	}),
 	createConfig: fromPromise(async ({ input: actorInput }) => {
 		if (actorInput.projectType === ProjectType.MONOLITH) {
-			const toolkitConfig = {
-				version: "1.0",
-				templatesPath: path.relative(actorInput.workspaceRoot, actorInput.templatesPath) || "templates",
+			const relativeTemplatesPath = path.relative(actorInput.workspaceRoot, actorInput.templatesPath);
+			const content = await new Liquid().parseAndRender(settings_yaml_default, {
 				projectType: "monolith",
+				templatesPath: relativeTemplatesPath || "templates",
 				sourceTemplate: actorInput.selectedTemplates[0]
-			};
-			print.info("\nCreating toolkit.yaml...");
-			await TemplatesManagerService.writeToolkitConfig(toolkitConfig, actorInput.workspaceRoot);
-			print.success("toolkit.yaml created");
+			});
+			const toolkitDir = path.join(actorInput.workspaceRoot, ".toolkit");
+			const settingsPath = path.join(toolkitDir, "settings.yaml");
+			print.info("\nCreating .toolkit/settings.yaml...");
+			await mkdir$1(toolkitDir, { recursive: true });
+			await writeFile$1(settingsPath, content, {
+				encoding: "utf-8",
+				flag: "w"
+			});
+			print.success(".toolkit/settings.yaml created");
 		}
 	}),
 	detectCodingAgent: fromPromise(async ({ input: actorInput }) => {
@@ -895,17 +908,176 @@ const initCommand = new Command("init").description("Initialize project with tem
 	}
 });
 
+//#endregion
+//#region src/commands/sync.ts
+/**
+* Sync Command
+*
+* DESIGN PATTERNS:
+* - Command pattern with Commander for CLI argument parsing
+* - Async/await pattern for asynchronous operations
+* - Error handling pattern with try-catch and proper exit codes
+*
+* CODING STANDARDS:
+* - Use async action handlers for asynchronous operations
+* - Provide clear option descriptions and default values
+* - Handle errors gracefully with process.exit()
+* - Log progress and errors to console
+* - Use Commander's .option() and .argument() for inputs
+*
+* AVOID:
+* - Synchronous blocking operations in action handlers
+* - Missing error handling (always use try-catch)
+* - Hardcoded values (use options or environment variables)
+* - Not exiting with appropriate exit codes on errors
+*/
+const CLAUDE_SETTINGS_DIR = ".claude";
+const CLAUDE_SETTINGS_FILE = "settings.json";
+const MCP_CONFIG_FILE = "mcp-config.yaml";
+function hasHookConfig(config) {
+	return !!(config["scaffold-mcp"]?.hook?.["claude-code"] || config["architect-mcp"]?.hook?.["claude-code"]);
+}
+function argsToFlags(args) {
+	const flags = [];
+	for (const [key, value] of Object.entries(args)) {
+		if (value === false) continue;
+		flags.push(`--${key}`);
+		if (value !== true) flags.push(String(value));
+	}
+	return flags;
+}
+function buildHookCommand(server, hookType, extraFlags) {
+	const serverArgs = server.args ?? [];
+	const scriptIdx = serverArgs.findIndex((arg) => /\.(ts|js|mjs|cjs)$/.test(arg));
+	if (scriptIdx >= 0) {
+		const prefixArgs$1 = serverArgs.slice(0, scriptIdx + 1);
+		return [
+			server.command,
+			...prefixArgs$1,
+			"hook",
+			"--type",
+			hookType,
+			...extraFlags
+		].join(" ");
+	}
+	const mcpServeIdx = serverArgs.indexOf("mcp-serve");
+	const prefixArgs = mcpServeIdx >= 0 ? serverArgs.slice(0, mcpServeIdx) : serverArgs;
+	return [
+		server.command,
+		...prefixArgs,
+		"hook",
+		"--type",
+		hookType,
+		...extraFlags
+	].join(" ");
+}
+function addHookEntry(output, event, command) {
+	if (!output[event]) output[event] = [];
+	output[event].push({ hooks: [{
+		type: "command",
+		command
+	}] });
+}
+function isMcpConfigYaml(value) {
+	return typeof value === "object" && value !== null;
+}
+async function readMcpConfigYaml(workspaceRoot) {
+	try {
+		const content = await readFile$1(path.join(workspaceRoot, MCP_CONFIG_FILE), "utf-8");
+		const parsed = yaml.load(content);
+		if (!isMcpConfigYaml(parsed)) throw new Error(`${MCP_CONFIG_FILE} has unexpected structure`);
+		return parsed;
+	} catch (err) {
+		if (err instanceof Error && "code" in err && err.code === "ENOENT") return {};
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to read ${MCP_CONFIG_FILE}: ${message}`);
+	}
+}
+const METHOD_TO_EVENT = {
+	preToolUse: "PreToolUse",
+	postToolUse: "PostToolUse",
+	stop: "Stop",
+	userPromptSubmit: "UserPromptSubmit",
+	taskCompleted: "TaskCompleted"
+};
+async function writeClaudeSettings(config, workspaceRoot) {
+	try {
+		const mcpServers = (await readMcpConfigYaml(workspaceRoot)).mcpServers ?? {};
+		const hooksOutput = {};
+		let hasAny = false;
+		const scaffoldAgent = config["scaffold-mcp"]?.hook?.["claude-code"];
+		const scaffoldServer = mcpServers["scaffold-mcp"];
+		if (scaffoldAgent && scaffoldServer) for (const [method, methodConfig] of [
+			["preToolUse", scaffoldAgent.preToolUse],
+			["postToolUse", scaffoldAgent.postToolUse],
+			["stop", scaffoldAgent.stop],
+			["userPromptSubmit", scaffoldAgent.userPromptSubmit],
+			["taskCompleted", scaffoldAgent.taskCompleted]
+		]) {
+			if (methodConfig === void 0) continue;
+			const extraFlags = methodConfig?.args ? argsToFlags(methodConfig?.args) : [];
+			const command = buildHookCommand(scaffoldServer, `claude-code.${method}`, extraFlags);
+			addHookEntry(hooksOutput, METHOD_TO_EVENT[method], command);
+			hasAny = true;
+		}
+		const architectAgent = config["architect-mcp"]?.hook?.["claude-code"];
+		const architectServer = mcpServers["architect-mcp"];
+		if (architectAgent && architectServer) for (const [method, methodConfig] of [["preToolUse", architectAgent.preToolUse], ["postToolUse", architectAgent.postToolUse]]) {
+			if (methodConfig === void 0) continue;
+			const extraFlags = methodConfig?.args ? argsToFlags(methodConfig?.args) : [];
+			const command = buildHookCommand(architectServer, `claude-code.${method}`, extraFlags);
+			addHookEntry(hooksOutput, METHOD_TO_EVENT[method], command);
+			hasAny = true;
+		}
+		if (!hasAny) {
+			print.warning("No scaffold-mcp/architect-mcp hook.claude-code config found — skipping .claude/settings.json");
+			return;
+		}
+		const settings = { hooks: hooksOutput };
+		const claudeDir = path.join(workspaceRoot, CLAUDE_SETTINGS_DIR);
+		await mkdir$1(claudeDir, { recursive: true });
+		await writeFile$1(path.join(claudeDir, CLAUDE_SETTINGS_FILE), JSON.stringify(settings, null, 2), "utf-8");
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to write ${CLAUDE_SETTINGS_DIR}/${CLAUDE_SETTINGS_FILE}: ${message}`);
+	}
+}
+/**
+* Generate .claude/settings.json from .toolkit/settings.yaml and mcp-config.yaml
+*/
+const syncCommand = new Command("sync").description("Generate .claude/settings.json from .toolkit/settings.yaml and mcp-config.yaml").action(async () => {
+	try {
+		const [workspaceRoot, config] = await Promise.all([TemplatesManagerService.getWorkspaceRoot(), TemplatesManagerService.readToolkitConfig()]);
+		if (!config) throw new Error("No .toolkit/settings.yaml found. Run `aicode init` first.");
+		if (hasHookConfig(config)) {
+			await writeClaudeSettings(config, workspaceRoot);
+			print.success("Written .claude/settings.json");
+		} else print.warning("No hook.claude-code config found in settings.yaml — skipping");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		print.error(`sync failed: ${message}`);
+		process.exit(1);
+	}
+});
+
 //#endregion
 //#region src/cli.ts
 /**
 * Main entry point
 */
 async function main() {
-	const program = new Command();
-	program.name("aicode").description("AI-powered code toolkit CLI for scaffolding, architecture management, and development workflows").version(version);
-	program.addCommand(initCommand);
-	program.addCommand(addCommand);
-	await program.parseAsync(process.argv);
+	try {
+		const program = new Command();
+		program.name("aicode").description("AI-powered code toolkit CLI for scaffolding, architecture management, and development workflows").version(version);
+		program.addCommand(initCommand);
+		program.addCommand(addCommand);
+		program.addCommand(syncCommand);
+		await program.parseAsync(process.argv);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.error(`aicode: ${message}`);
+		process.exit(1);
+	}
 }
 main();
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agiflowai/aicode-toolkit",
   "description": "AI-powered code toolkit CLI for scaffolding, architecture management, and development workflows",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "license": "AGPL-3.0",
   "author": "AgiflowIO",
   "repository": {
@@ -50,8 +50,8 @@
     "pino-pretty": "^13.1.1",
     "xstate": "^5.23.0",
     "zod": "3.25.76",
-    "@agiflowai/aicode-utils": "1.0.14",
-    "@agiflowai/coding-agent-bridge": "1.0.17"
+    "@agiflowai/aicode-utils": "1.0.16",
+    "@agiflowai/coding-agent-bridge": "1.0.19"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",