@shirayner/ace 0.1.0-snapshot.3 → 0.1.0

package/README.md

@@ -27,6 +27,15 @@ $ ace init
 Done! Your AI coding environment is ready.
 ```
 
+### Spec-driven Development
+
+```
+$ ace spec init ./my-project
+✔ openspec config installed
+✔ spec templates installed (taxonomy, issues, procedures, evolution)
+Done! Spec workflow is ready.
+```
+
 ## Why ace?
 
 Claude Code is powerful out of the box — but configuring rules, skills,
@@ -34,8 +43,9 @@ safety guards, and memory templates by hand is tedious and error-prone.
 
 **ace solves this in one command:**
 
-- **Rules** — 7 cognitive and code-quality rules (deep thinking, clean code, ...)
+- **Rules** — 8 cognitive and code-quality rules (deep thinking, clean code, ...)
 - **Skills** — 4 AI skills with namespace isolation (`ace:auto-goal`, `ace:coding`, ...)
+- **Spec** — Spec-driven development workflow with OpenSpec integration
 - **Safety** — Hookify guards that block dangerous ops and protect secrets
 - **Memory** — Templates for cross-session memory and developer profiles
 - **Non-destructive** — Smart merge preserves your existing config; uninstall restores it
@@ -54,11 +64,12 @@ That's it. Run `ace doctor` to verify.
 | Component | Contents | Preset |
 |-----------|----------|--------|
 | **Core** | `CLAUDE.md` + `settings.json` (smart merge) | all |
-| **Rules** | 7 rules: thinking, clean-code, code-quality, ... | all |
+| **Rules** | 8 rules: thinking, clean-code, code-quality, ... | all |
 | **Plugin** | 4 skills + 1 command (`ace:auto-goal`, `ace:coding`, ...) | all |
 | **Hookify** | 3 safety guards (block-dangerous-ops, protect-secrets, ...) | full, safe |
 | **Hooks** | Role-dependent scripts (e.g., Java compile check) | full |
 | **Memory** | MEMORY.md template + role-based developer profile | full, safe |
+| **Spec** | Spec-driven workflow templates (taxonomy, issues, procedures) | `ace spec init` |
 
 ## Design Philosophy
 

package/README.zh-CN.md

@@ -27,14 +27,22 @@ $ ace init
 Done! Your AI coding environment is ready.
 ```
 
-## 为什么需要 ace？
+### Spec 驱动开发
+
+```
+$ ace spec init ./my-project
+✔ openspec config installed
+✔ spec templates installed (taxonomy, issues, procedures, evolution)
+Done! Spec workflow is ready.
+```
 
 Claude Code 开箱即用已经很强大——但手动配置规则、技能、安全守卫和记忆模板既繁琐又容易出错。
 
 **ace 用一条命令解决这个问题：**
 
-- **规则** — 7 条认知与代码质量规则（深度思考、Clean Code……）
+- **规则** — 8 条认知与代码质量规则（深度思考、Clean Code……）
 - **技能** — 4 个 AI 技能，命名空间隔离（`ace:auto-goal`、`ace:coding`……）
+- **规约** — Spec 驱动开发工作流，集成 OpenSpec
 - **安全** — Hookify 守卫，拦截危险操作并保护密钥
 - **记忆** — 跨会话记忆模板和开发者画像
 - **无损安装** — 智能合并保留你的已有配置；卸载可完整还原
@@ -53,11 +61,12 @@ ace init
 | 组件 | 内容 | 预设 |
 |------|------|------|
 | **Core** | `CLAUDE.md` + `settings.json`（智能合并） | 全部 |
-| **Rules** | 7 条规则：thinking、clean-code、code-quality…… | 全部 |
+| **Rules** | 8 条规则：thinking、clean-code、code-quality…… | 全部 |
 | **Plugin** | 4 个技能 + 1 个命令（`ace:auto-goal`、`ace:coding`……） | 全部 |
 | **Hookify** | 3 条安全守卫（block-dangerous-ops、protect-secrets……） | full、safe |
 | **Hooks** | 角色相关脚本（如 Java 编译检查） | full |
 | **Memory** | MEMORY.md 模板 + 角色开发者画像 | full、safe |
+| **Spec** | Spec 驱动工作流模板（分类、问题、流程） | `ace spec init` |
 
 ## 设计理念
 

package/bin/ace.js

@@ -7,6 +7,7 @@ import { initCommand } from '../src/commands/init.js';
 import { doctorCommand } from '../src/commands/doctor.js';
 import { listCommand } from '../src/commands/list.js';
 import { uninstallCommand } from '../src/commands/uninstall.js';
+import { specInitCommand, specDoctorCommand, specUpdateCommand } from '../src/commands/spec.js';
 
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
@@ -43,4 +44,26 @@ program
   .option('-y, --yes', 'Skip confirmation prompt', false)
   .action(uninstallCommand);
 
+const spec = program
+  .command('spec')
+  .description('Manage spec-driven development workflow (project-level)');
+
+spec
+  .command('init [path]')
+  .description('Initialize spec workflow in a project')
+  .option('-f, --force', 'Overwrite existing configuration', false)
+  .option('--dry-run', 'Preview without making changes', false)
+  .option('--skip-openspec', 'Skip openspec CLI installation', false)
+  .action(specInitCommand);
+
+spec
+  .command('doctor [path]')
+  .description('Check spec workflow health')
+  .action(specDoctorCommand);
+
+spec
+  .command('update [path]')
+  .description('Update spec templates to latest version')
+  .action(specUpdateCommand);
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shirayner/ace",
-  "version": "0.1.0-snapshot.3",
+  "version": "0.1.0",
   "description": "AI Coding Environment - One command to set up your Claude Code harness",
   "bin": {
     "ace": "./bin/ace.js"
@@ -30,6 +30,7 @@
     "inquirer": "^9.2.0",
     "fs-extra": "^11.2.0",
     "deepmerge": "^4.3.1",
+    "js-yaml": "^4.1.0",
     "ora": "^8.0.0"
   },
   "files": [

package/src/commands/doctor.js

@@ -2,7 +2,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import chalk from 'chalk';
 import {
-  CLAUDE_DIR, COMPONENTS,
+  CLAUDE_DIR, COMPONENTS, TEMPLATES_DIR,
   PLUGIN_CACHE_DIR, INSTALLED_PLUGINS_FILE, PLUGIN_KEY,
   KNOWN_MARKETPLACES_FILE, MARKETPLACE_DIR, MARKETPLACE_NAME,
 } from '../core/constants.js';
@@ -19,10 +19,19 @@ export async function doctorCommand() {
   checks.push(await check('CLAUDE.md', fs.pathExists(path.join(CLAUDE_DIR, 'CLAUDE.md'))));
   checks.push(await check('settings.json', fs.pathExists(path.join(CLAUDE_DIR, 'settings.json'))));
 
-  // 3. Check rules (in ace/ namespace subdirectory)
-  const ruleFiles = COMPONENTS.rules.files;
-  for (const file of ruleFiles) {
-    checks.push(await check(`rules/ace/${path.basename(file.dest)}`, fs.pathExists(path.join(CLAUDE_DIR, file.dest))));
+  // 3. Check rules (dynamically scan templates directory)
+  const rulesDir = COMPONENTS.rules.rulesDir;
+  if (rulesDir) {
+    const templateRulesDir = path.join(TEMPLATES_DIR, rulesDir);
+    try {
+      const ruleFiles = await fs.readdir(templateRulesDir);
+      for (const file of ruleFiles) {
+        if (!file.endsWith('.md')) continue;
+        checks.push(await check(`rules/ace/${file}`, fs.pathExists(path.join(CLAUDE_DIR, rulesDir, file))));
+      }
+    } catch {
+      checks.push({ name: 'rules/ace/ directory', ok: false });
+    }
   }
 
   // 4. Check plugin installation

package/src/commands/list.js

@@ -2,7 +2,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import chalk from 'chalk';
 import {
-  CLAUDE_DIR, COMPONENTS,
+  CLAUDE_DIR, COMPONENTS, TEMPLATES_DIR,
   PLUGIN_CACHE_DIR, INSTALLED_PLUGINS_FILE, PLUGIN_KEY,
 } from '../core/constants.js';
 
@@ -59,6 +59,14 @@ async function getPluginVersion() {
 async function getComponentStatus(component) {
   const allPaths = [];
 
+  if (component.rulesDir) {
+    try {
+      const templateDir = path.join(TEMPLATES_DIR, component.rulesDir);
+      const files = await fs.readdir(templateDir);
+      allPaths.push(...files.filter(f => f.endsWith('.md')).map(f => path.join(CLAUDE_DIR, component.rulesDir, f)));
+    } catch { /* ignore */ }
+  }
+
   if (component.files) {
     allPaths.push(...component.files.map(f => path.join(CLAUDE_DIR, f.dest)));
   }
@@ -83,11 +91,21 @@ async function getComponentDetails(component) {
   const missing = [];
   const installed = [];
 
-  const allFiles = [
+  const allFiles = [];
+
+  if (component.rulesDir) {
+    try {
+      const templateDir = path.join(TEMPLATES_DIR, component.rulesDir);
+      const files = await fs.readdir(templateDir);
+      allFiles.push(...files.filter(f => f.endsWith('.md')).map(f => path.join(component.rulesDir, f)));
+    } catch { /* ignore */ }
+  }
+
+  allFiles.push(
     ...(component.files || []).map(f => f.dest),
     ...(component.directories || []),
     ...(component.conditional || []).map(f => f.dest),
-  ];
+  );
 
   for (const file of allFiles) {
     const exists = await fs.pathExists(path.join(CLAUDE_DIR, file));

package/src/commands/spec.js

@@ -0,0 +1,124 @@
+import path from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { SpecInstaller } from '../core/spec-installer.js';
+
+export async function specInitCommand(targetPath, options) {
+  const targetDir = targetPath ? path.resolve(targetPath) : process.cwd();
+
+  console.log(chalk.bold('\n  ace spec init — Initialize spec-driven workflow\n'));
+  console.log(chalk.dim(`  Target: ${targetDir}`));
+  if (options.force) console.log(chalk.yellow('  Force mode: existing files will be overwritten'));
+  if (options.dryRun) console.log(chalk.cyan('  Dry-run mode: no changes will be made'));
+  if (options.skipOpenspec) console.log(chalk.dim('  Skipping openspec CLI installation'));
+  console.log();
+
+  const installer = new SpecInstaller({
+    targetDir,
+    force: options.force,
+    dryRun: options.dryRun,
+    skipOpenspec: options.skipOpenspec,
+  });
+
+  const spinner = ora('Setting up spec workflow...').start();
+
+  try {
+    const { installed, skipped, merged, errors } = await installer.run();
+    spinner.stop();
+
+    printSummary(installed, skipped, merged, errors);
+  } catch (err) {
+    spinner.fail(`Unexpected error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+export async function specDoctorCommand(targetPath) {
+  const targetDir = targetPath ? path.resolve(targetPath) : process.cwd();
+
+  console.log(chalk.bold('\n  ace spec doctor — Checking spec workflow health\n'));
+  console.log(chalk.dim(`  Target: ${targetDir}\n`));
+
+  const installer = new SpecInstaller({ targetDir });
+  const checks = await installer.doctor();
+
+  const passed = checks.filter(c => c.ok).length;
+  const failed = checks.filter(c => !c.ok).length;
+
+  checks.forEach(c => {
+    const icon = c.ok ? chalk.green('  pass') : chalk.red('  FAIL');
+    console.log(`  ${icon}  ${c.name}`);
+  });
+
+  console.log(chalk.bold(`\n  ${passed} passed, ${failed} failed\n`));
+
+  if (failed > 0) {
+    console.log(chalk.yellow('  Run `ace spec init` to fix missing components.\n'));
+  } else {
+    console.log(chalk.green('  Spec workflow is healthy.\n'));
+  }
+}
+
+export async function specUpdateCommand(targetPath, options) {
+  const targetDir = targetPath ? path.resolve(targetPath) : process.cwd();
+
+  console.log(chalk.bold('\n  ace spec update — Updating spec templates\n'));
+  console.log(chalk.dim(`  Target: ${targetDir}`));
+  console.log();
+
+  const installer = new SpecInstaller({
+    targetDir,
+    force: true,
+    skipOpenspec: true,
+  });
+
+  const spinner = ora('Updating spec templates...').start();
+
+  try {
+    // Only run template + config installation (skip openspec init)
+    await installer.installTemplates();
+    await installer.installConfig();
+    spinner.stop();
+
+    const { installed, skipped, merged, errors } = installer.results;
+    printSummary(installed, skipped, merged, errors);
+  } catch (err) {
+    spinner.fail(`Unexpected error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+function printSummary(installed, skipped, merged, errors) {
+  console.log(chalk.bold('\n  Summary\n'));
+
+  if (installed.length > 0) {
+    console.log(chalk.green(`  Installed (${installed.length}):`));
+    installed.forEach(f => console.log(chalk.green(`    + ${f}`)));
+  }
+
+  if (merged.length > 0) {
+    console.log(chalk.blue(`  Merged (${merged.length}):`));
+    merged.forEach(m => {
+      const detail = m.version ? ` (v${m.version})` : '';
+      console.log(chalk.blue(`    ~ ${m.file}${detail}`));
+    });
+  }
+
+  if (skipped.length > 0) {
+    console.log(chalk.yellow(`  Skipped (${skipped.length}):`));
+    skipped.forEach(f => console.log(chalk.yellow(`    - ${f}`)));
+  }
+
+  if (errors.length > 0) {
+    console.log(chalk.red(`  Errors (${errors.length}):`));
+    errors.forEach(e => console.log(chalk.red(`    ! ${e.file || e.component}: ${e.error}`)));
+  }
+
+  if (errors.length === 0) {
+    console.log(chalk.green.bold('\n  Done! Spec workflow is ready.\n'));
+    console.log(chalk.dim('  Use /opsx:propose to start a new change.'));
+    console.log(chalk.dim('  Run `ace spec doctor` to verify.\n'));
+  } else {
+    console.log(chalk.yellow('\n  Completed with errors. Run `ace spec doctor` to diagnose.\n'));
+  }
+}

package/src/core/constants.js

@@ -49,6 +49,24 @@ export const ROLES = {
   },
 };
 
+// Spec (project-level) constants
+export const OPENSPEC_TEMPLATES_DIR = path.join(__dirname, '..', '..', 'templates', 'openspec');
+export const SPEC_TEMPLATE_FILES = [
+  'taxonomy/requirement-issue-taxonomy.md',
+  'taxonomy/design-issue-taxonomy.md',
+  'issues/requirement-issues.md',
+  'issues/design-issues.md',
+  'issues/retrospective-notes.md',
+  'evolution/adr.md',
+  'evolution/glossary.md',
+  'evolution/risk-map.md',
+  'procedures/requirement-clarification-flow.md',
+  'procedures/design-clarification-flow.md',
+  'procedures/interactive-clarification-protocol.md',
+  'procedures/evolution-system.md',
+  'retrospective-template.md',
+];
+
 export const COMPONENTS = {
   core: {
     description: 'Core config (CLAUDE.md + settings.json)',
@@ -61,15 +79,7 @@ export const COMPONENTS = {
   rules: {
     description: 'Cognitive & code quality rules',
     required: true,
-    files: [
-      { src: 'rules/ace/thinking.md', dest: 'rules/ace/thinking.md' },
-      { src: 'rules/ace/clean-code.md', dest: 'rules/ace/clean-code.md' },
-      { src: 'rules/ace/code-quality.md', dest: 'rules/ace/code-quality.md' },
-      { src: 'rules/ace/reporting.md', dest: 'rules/ace/reporting.md' },
-      { src: 'rules/ace/task-recovery.md', dest: 'rules/ace/task-recovery.md' },
-      { src: 'rules/ace/context-hygiene.md', dest: 'rules/ace/context-hygiene.md' },
-      { src: 'rules/ace/memory-policy.md', dest: 'rules/ace/memory-policy.md' },
-    ],
+    rulesDir: 'rules/ace',
   },
   plugin: {
     description: 'Ace plugin (skills: auto-goal, coding, skill-creator, skill-optimize; commands: report)',

package/src/core/installer.js

@@ -50,6 +50,10 @@ export class Installer {
       return;
     }
 
+    if (component.rulesDir) {
+      await this.installRulesDir(component.rulesDir);
+    }
+
     if (component.files) {
       for (const file of component.files) {
         await this.installFile(file);
@@ -148,6 +152,22 @@ export class Installer {
     this.results.merged.push({ file: 'plugins/known_marketplaces.json' });
   }
 
+  async installRulesDir(rulesDir) {
+    const srcDir = path.join(this.templatesDir, rulesDir);
+    if (!await fs.pathExists(srcDir)) {
+      this.results.errors.push({ file: rulesDir, error: 'Rules directory not found' });
+      return;
+    }
+    const files = await fs.readdir(srcDir);
+    for (const file of files) {
+      if (!file.endsWith('.md')) continue;
+      await this.installFile({
+        src: path.join(rulesDir, file),
+        dest: path.join(rulesDir, file),
+      });
+    }
+  }
+
   async installFile(fileSpec) {
     const srcPath = path.join(this.templatesDir, fileSpec.src);
     const destPath = path.join(this.targetDir, fileSpec.dest);

package/src/core/spec-installer.js

@@ -0,0 +1,205 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { execSync } from 'child_process';
+import yaml from 'js-yaml';
+import { OPENSPEC_TEMPLATES_DIR, SPEC_TEMPLATE_FILES } from './constants.js';
+import { mergeSpecConfig } from './yaml-merger.js';
+import { backupFile } from './merger.js';
+
+export class SpecInstaller {
+  constructor(options = {}) {
+    this.targetDir = options.targetDir || process.cwd();
+    this.templatesDir = OPENSPEC_TEMPLATES_DIR;
+    this.force = options.force || false;
+    this.dryRun = options.dryRun || false;
+    this.skipOpenspec = options.skipOpenspec || false;
+    this.results = { installed: [], skipped: [], merged: [], errors: [] };
+  }
+
+  get openspecDir() {
+    return path.join(this.targetDir, 'openspec');
+  }
+
+  async run() {
+    await this.ensureOpenspecCli();
+    await this.runOpenspecInit();
+    await this.installTemplates();
+    await this.installConfig();
+    return this.results;
+  }
+
+  async ensureOpenspecCli() {
+    if (this.skipOpenspec) return;
+
+    if (this.isOpenspecInstalled()) {
+      this.results.skipped.push('@fission-ai/openspec (already installed)');
+      return;
+    }
+
+    if (this.dryRun) {
+      this.results.installed.push('@fission-ai/openspec (npm global)');
+      return;
+    }
+
+    try {
+      execSync('npm install -g @fission-ai/openspec', { stdio: 'pipe' });
+      this.results.installed.push('@fission-ai/openspec (npm global)');
+    } catch (err) {
+      this.results.errors.push({
+        component: 'openspec-cli',
+        error: `Failed to install @fission-ai/openspec: ${err.message}. Use --skip-openspec to skip.`,
+      });
+    }
+  }
+
+  isOpenspecInstalled() {
+    try {
+      execSync('openspec --version', { stdio: 'pipe' });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async runOpenspecInit() {
+    if (this.skipOpenspec) return;
+
+    if (await fs.pathExists(this.openspecDir) && !this.force) {
+      this.results.skipped.push('openspec/ (already exists)');
+      return;
+    }
+
+    if (this.dryRun) {
+      this.results.installed.push('openspec/ (via openspec init)');
+      return;
+    }
+
+    if (!this.isOpenspecInstalled()) return;
+
+    try {
+      execSync('openspec init', { cwd: this.targetDir, stdio: 'inherit' });
+      this.results.installed.push('openspec/ (via openspec init)');
+    } catch (err) {
+      this.results.errors.push({
+        component: 'openspec-init',
+        error: `openspec init failed: ${err.message}`,
+      });
+    }
+  }
+
+  async installTemplates() {
+    for (const file of SPEC_TEMPLATE_FILES) {
+      const srcPath = path.join(this.templatesDir, file);
+      const destPath = path.join(this.openspecDir, 'templates', file);
+
+      if (!await fs.pathExists(srcPath)) {
+        this.results.errors.push({ file, error: 'Template not found' });
+        continue;
+      }
+
+      const exists = await fs.pathExists(destPath);
+      if (exists && !this.force) {
+        this.results.skipped.push(`openspec/templates/${file}`);
+        continue;
+      }
+
+      if (this.dryRun) {
+        this.results.installed.push(`openspec/templates/${file}`);
+        continue;
+      }
+
+      await fs.ensureDir(path.dirname(destPath));
+      await fs.copy(srcPath, destPath, { overwrite: this.force });
+      this.results.installed.push(`openspec/templates/${file}`);
+    }
+  }
+
+  async installConfig() {
+    const srcPath = path.join(this.templatesDir, 'config.yaml');
+    const destPath = path.join(this.openspecDir, 'config.yaml');
+
+    if (!await fs.pathExists(srcPath)) {
+      this.results.errors.push({ file: 'config.yaml', error: 'Template not found' });
+      return;
+    }
+
+    const exists = await fs.pathExists(destPath);
+
+    if (exists && !this.force) {
+      // Merge: system fields overwrite, user fields preserve
+      if (this.dryRun) {
+        this.results.merged.push({ file: 'openspec/config.yaml' });
+        return;
+      }
+
+      const existingContent = await fs.readFile(destPath, 'utf-8');
+      const templateContent = await fs.readFile(srcPath, 'utf-8');
+      const existing = yaml.load(existingContent);
+      const template = yaml.load(templateContent);
+      const merged = mergeSpecConfig(existing, template);
+
+      await backupFile(destPath);
+      await fs.writeFile(destPath, yaml.dump(merged, { lineWidth: -1 }), 'utf-8');
+      this.results.merged.push({ file: 'openspec/config.yaml', version: merged.version });
+      return;
+    }
+
+    if (this.dryRun) {
+      this.results.installed.push('openspec/config.yaml');
+      return;
+    }
+
+    await fs.ensureDir(path.dirname(destPath));
+    await fs.copy(srcPath, destPath);
+    this.results.installed.push('openspec/config.yaml');
+  }
+
+  async doctor() {
+    const checks = [];
+
+    // 1. Node.js version
+    const nodeVersion = process.version;
+    const major = parseInt(nodeVersion.slice(1));
+    checks.push({ name: 'Node.js >= 18', ok: major >= 18 });
+
+    // 2. openspec CLI
+    checks.push({ name: '@fission-ai/openspec CLI', ok: this.isOpenspecInstalled() });
+
+    // 3. openspec/ directory
+    checks.push({ name: 'openspec/ directory', ok: await fs.pathExists(this.openspecDir) });
+
+    // 4. config.yaml
+    const configPath = path.join(this.openspecDir, 'config.yaml');
+    const configExists = await fs.pathExists(configPath);
+    checks.push({ name: 'openspec/config.yaml', ok: configExists });
+
+    if (configExists) {
+      try {
+        const config = yaml.load(await fs.readFile(configPath, 'utf-8'));
+        checks.push({ name: 'config.yaml has schema field', ok: !!config?.schema });
+        checks.push({ name: `config.yaml version: ${config?.version || 'unknown'}`, ok: !!config?.version });
+      } catch {
+        checks.push({ name: 'config.yaml valid YAML', ok: false });
+      }
+    }
+
+    // 5. Required template files
+    for (const file of SPEC_TEMPLATE_FILES) {
+      const filePath = path.join(this.openspecDir, 'templates', file);
+      checks.push({
+        name: `template: ${file}`,
+        ok: await fs.pathExists(filePath),
+      });
+    }
+
+    // 6. Git
+    try {
+      execSync('git --version', { stdio: 'pipe' });
+      checks.push({ name: 'Git available', ok: true });
+    } catch {
+      checks.push({ name: 'Git available', ok: false });
+    }
+
+    return checks;
+  }
+}

package/src/core/yaml-merger.js

@@ -0,0 +1,45 @@
+import fs from 'fs-extra';
+import yaml from 'js-yaml';
+
+const SYSTEM_FIELDS = ['schema', 'version', 'context'];
+
+/**
+ * Merge spec config.yaml: system fields overwrite, user fields preserve, rules merge.
+ */
+export function mergeSpecConfig(existing, template) {
+  const merged = { ...existing };
+
+  for (const field of SYSTEM_FIELDS) {
+    if (template[field] !== undefined) {
+      merged[field] = template[field];
+    }
+  }
+
+  if (template.rules) {
+    merged.rules = { ...(existing.rules || {}), ...template.rules };
+  }
+
+  return merged;
+}
+
+/**
+ * Read, merge, and write config.yaml with backup.
+ * Returns { merged: true, version } or { merged: false, reason }.
+ */
+export async function mergeSpecConfigFile(existingPath, templatePath, backupDir) {
+  const existingContent = await fs.readFile(existingPath, 'utf-8');
+  const templateContent = await fs.readFile(templatePath, 'utf-8');
+
+  const existing = yaml.load(existingContent);
+  const template = yaml.load(templateContent);
+  const merged = mergeSpecConfig(existing, template);
+
+  if (backupDir) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupPath = `${existingPath}.ace-backup.${timestamp}`;
+    await fs.copy(existingPath, backupPath);
+  }
+
+  await fs.writeFile(existingPath, yaml.dump(merged, { lineWidth: -1 }), 'utf-8');
+  return { merged: true, version: merged.version };
+}

package/templates/CLAUDE.md

@@ -14,3 +14,6 @@
 
 ## 质量控制
 - @~/.claude/rules/ace/memory-policy.md - Memory 质量策略
+
+## 交互规则
+- @~/.claude/rules/ace/interactive-clarify.md - 交互式澄清规则