@shirayner/ace 0.1.7 → 0.2.0-SNAPSHOT

package/README.md

@@ -31,17 +31,27 @@ ACE 是一个**AI 开发环境配置工具**，基于 Claude Code 官方最佳
 - 📝 **规范驱动工作流** — OpenSpec 集成的需求管理体系
 - 🧩 **跨会话记忆系统** — 持久化的开发者画像与项目记忆
 
+### 视频教程
+
+从下载安装到实际使用的完整演示：
+
+![ACE 使用示例](assets/ace-demo.gif)
+
+动图速度过快，另有示例视频：[ACE 使用示例](assets/ace-demo.mp4)
+
+---
+
+## ✨ 一分钟速览
+
+### 安装
+
 ```bash
 # 一键安装，即刻拥有专业级 AI 开发环境
 npm install -g @shirayner/ace
-ace init
 ```
 
----
 
-## ✨ 一分钟速览
-
-### 初始化向导
+### 初始化
 
 ```bash
 $ ace init
@@ -74,38 +84,64 @@ $ ace init
 
 ### Spec Coding 完整流程
 
+进入工作目录
+
 ```bash
 # 进入工作目录
 $ mkdir my-project 
 $ cd my-project
 
+```
+
+Spec 初始化
+
+```bash
 # 执行 aspec 初始化
 $ ace spec init
 ✓ aspec 工作流已初始化
 Done! 规范驱动开发已就绪。
 
-# 在 Claude Code 中体验三命令开发流程：
+```
+
+Spec驱动开发
+
+```bash
+# 在 Claude Code 中体验Spec开发流程：
+# 输入 /opsx:proposal 命令后，一路交互式澄清、确认，然后需求完成，Spec归档
 $ claude
 
 > /opsx:proposal 帮我实现用户积分系统
 
-Claude:
-【需求澄清】积分获取规则？消费规则？过期策略？→ 3 个问题确认
-【创建提案】proposal.md
-【技术澄清】并发扣减方案？积分流水存储？→ 2 个问题确认
-【确定方案】design.md + tasks.md（8 个可执行任务）
+Claude: 【需求澄清】对需求不确定的地方提出疑问？→  请求人工澄清
+人工：选择选项，或者进行纠正，然后点击submit
+
+Claude: 【需求对齐】Claude输出自己对本需求的理解 → 请求人工确认
+人工：选择确认，或者纠正信息，然后点击submit
+
+-- 人工确认之后，Cluade会创建提案
+
+Claude: 【技术设计澄清】对技术不确定的地方提出疑问 → 请求人工确认
+人工：选择确认，或者纠正信息，然后点击submit
+
+Claude: 【技术设计对齐】Claude输出自己对本需求的技术方案设计的理解 → 请求人工确认
+人工：选择确认，或者纠正信息，然后点击submit
+
+-- 人工确认之后，Cluade会创建Design
+
+Claude: 【Design审批并创建Tasks】Claude请求人工确认Design设计，然后创建Tasks → 请求人工审批
+人工：选择确认，或者纠正信息，然后点击submit
+
+-- 人工确认之后，Cluade会创建tasks
 
-> /opsx:apply
+Claude: 【执行】Claude 请求按规划的任务进行代码实现 → 请求人工审批
+人工：选择确认，或者纠正信息，然后点击submit
 
-Claude:
-按 tasks.md 逐项实现，每步验证
-✓ 所有任务完成，测试通过
+-- 人工确认之后，Cluade会进行代码实现，然后进行经验收集
 
-> /opsx:archive
+Claude: 【归档同步】Claude 会请求进行归档同步→ 请求人工审批
+人工：选择确认，或者纠正信息，然后点击submit
 
-Claude:
-spec 归档，收敛检查
-✓ 归档完成
+-- 人工确认之后，Cluade会对Spec进行归档同步
 ```
 
 ### 健康检查

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shirayner/ace",
-  "version": "0.1.7",
+  "version": "0.2.0-SNAPSHOT",
   "description": "AI Coding Environment - One command to set up your Claude Code harness",
   "bin": {
     "ace": "./bin/ace.js"

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ace",
-  "version": "0.1.3",
+  "version": "0.2.0-SNAPSHOT",
   "description": "AI Coding Environment - Skills and commands for Claude Code",
   "author": {
     "name": "shirayner"

package/src/commands/doctor.js

@@ -27,10 +27,10 @@ export async function doctorCommand() {
       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))));
+        checks.push(await check(`ace/rules/${file}`, fs.pathExists(path.join(CLAUDE_DIR, rulesDir, file))));
       }
     } catch {
-      checks.push({ name: 'rules/ace/ directory', ok: false });
+      checks.push({ name: 'ace/rules/ directory', ok: false });
     }
   }
 
@@ -91,14 +91,21 @@ export async function doctorCommand() {
     checks.push({ name: 'settings.json parseable', ok: false });
   }
 
-  // 8. Validate CLAUDE.md @references
+  // 8. Validate CLAUDE.md references (both @refs and path-index style)
   try {
     const claudeMd = await fs.readFile(path.join(CLAUDE_DIR, 'CLAUDE.md'), 'utf-8');
-    const refs = claudeMd.match(/@~?\/?\.?claude\/[^\s)]+/g) || [];
-    for (const ref of refs) {
+    // Check @references (legacy format)
+    const atRefs = claudeMd.match(/@~?\/?\.?claude\/[^\s)]+/g) || [];
+    for (const ref of atRefs) {
       const refPath = ref.replace(/^@/, '').replace(/^~/, process.env.HOME || process.env.USERPROFILE);
       checks.push(await check(`@ref: ${path.basename(refPath)}`, fs.pathExists(refPath)));
     }
+    // Check path-index style references (new format: lines starting with "- ~/.claude/...")
+    const pathRefs = claudeMd.match(/(?:^|\n)-\s+(~\/.claude\/[^\s—]+)/g) || [];
+    for (const match of pathRefs) {
+      const refPath = match.replace(/(?:^|\n)-\s+/, '').replace(/^~/, process.env.HOME || process.env.USERPROFILE);
+      checks.push(await check(`path: ${path.basename(refPath)}`, fs.pathExists(refPath)));
+    }
   } catch {
     checks.push({ name: 'CLAUDE.md readable', ok: false });
   }

package/src/commands/init.js

@@ -91,6 +91,11 @@ export async function initCommand(options) {
 
   s.start('Installing...');
 
+  // Prepare: migrate legacy directory structure if needed
+  if (!options.dryRun) {
+    await installer.prepare();
+  }
+
   for (const componentName of components) {
     const component = COMPONENTS[componentName];
     if (!component) continue;
@@ -149,7 +154,7 @@ export async function initCommand(options) {
       '',
       'Customize',
       '  Change role      edit ~/.claude/memory/user_profile.md',
-      '  Adjust rules     edit ~/.claude/rules/ace/',
+      '  Adjust rules     edit ~/.claude/ace/rules/',
       '  Safety guards    edit ~/.claude/hookify.ace.*.local.md',
       '  Verify setup     ace doctor',
     ].join('\n'),
@@ -224,8 +229,8 @@ async function buildInstallPreview(installer, components) {
       try {
         const existing = await fs.readFile(path.join(installer.targetDir, item.dest), 'utf-8');
         const template = await fs.readFile(path.join(installer.templatesDir, item.src), 'utf-8');
-        const { added } = mergeClaudeMd(existing, template);
-        item.detail = added.length > 0 ? `adds ${added.length} new @references` : 'up to date';
+        const { content } = mergeClaudeMd(existing, template);
+        item.detail = content !== existing ? 'will update managed section' : 'up to date';
       } catch {
         item.detail = 'will merge';
       }

package/src/commands/uninstall.js

@@ -30,16 +30,35 @@ export async function uninstallCommand(options) {
   const skipped = [];
   const errors = [];
 
-  // 1. Remove rules/ace/ directory
+  // 1. Remove ace/rules/ directory (and legacy rules/ace/ if still present)
   const spinner1 = ora('Removing rules...').start();
   try {
-    const rulesDir = path.join(CLAUDE_DIR, 'rules', 'ace');
-    if (await fs.pathExists(rulesDir)) {
-      await fs.remove(rulesDir);
-      removed.push('rules/ace/');
-    } else {
-      skipped.push('rules/ace/ (not found)');
+    const newRulesDir = path.join(CLAUDE_DIR, 'ace', 'rules');
+    const newTeamDir = path.join(CLAUDE_DIR, 'ace', 'team');
+    const aceDir = path.join(CLAUDE_DIR, 'ace');
+    const legacyRulesDir = path.join(CLAUDE_DIR, 'rules', 'ace');
+
+    if (await fs.pathExists(newRulesDir)) {
+      await fs.remove(newRulesDir);
+      removed.push('ace/rules/');
+    }
+    if (await fs.pathExists(newTeamDir)) {
+      await fs.remove(newTeamDir);
+      removed.push('ace/team/');
+    }
+    // Remove ace/ parent if empty
+    if (await fs.pathExists(aceDir)) {
+      const remaining = await fs.readdir(aceDir);
+      if (remaining.length === 0) {
+        await fs.remove(aceDir);
+      }
     }
+    // Also clean legacy directory if still exists
+    if (await fs.pathExists(legacyRulesDir)) {
+      await fs.remove(legacyRulesDir);
+      removed.push('rules/ace/ (legacy)');
+    }
+
     spinner1.succeed('rules removed');
   } catch (err) {
     spinner1.fail('rules removal failed');
@@ -126,17 +145,31 @@ export async function uninstallCommand(options) {
       await fs.remove(claudeBackup);
       removed.push('CLAUDE.md (restored pre-ace backup)');
     } else if (await fs.pathExists(claudeMdPath)) {
-      // Fallback: surgically remove ace @references
+      // Fallback: surgically remove ace @references and managed section
       const content = await fs.readFile(claudeMdPath, 'utf-8');
-      const lines = content.split('\n');
-      const filtered = lines.filter(line => !line.includes('@~/.claude/rules/ace/'));
-      const cleaned = filtered.join('\n')
+      let cleaned = content;
+      // Remove the entire managed section if present
+      const managedStart = '<!-- ace:managed:start -->';
+      const managedEnd = '<!-- ace:managed:end -->';
+      const startIdx = cleaned.indexOf(managedStart);
+      const endIdx = cleaned.indexOf(managedEnd);
+      if (startIdx !== -1 && endIdx !== -1) {
+        cleaned = cleaned.slice(0, startIdx) + cleaned.slice(endIdx + managedEnd.length);
+      }
+      // Remove any remaining ace @references (legacy or new format)
+      const lines = cleaned.split('\n');
+      const filtered = lines.filter(line =>
+        !line.includes('@~/.claude/rules/ace/') &&
+        !line.includes('@~/.claude/ace/') &&
+        !line.includes('hookify.ace.')
+      );
+      cleaned = filtered.join('\n')
         .replace(/\n## Added by ace\n*/g, '\n')
         .replace(/\n{3,}/g, '\n\n')
         .trim() + '\n';
       if (cleaned !== content) {
         await fs.writeFile(claudeMdPath, cleaned, 'utf-8');
-        removed.push('CLAUDE.md ace @references (surgical)');
+        removed.push('CLAUDE.md ace content (surgical)');
       }
     }
 

package/src/core/constants.js

@@ -58,10 +58,12 @@ export const SPEC_TEMPLATE_FILES = [
 
 /**
  * Patterns for files owned by ACE - these are overwritten directly on init without prompting.
- * Used to identify ACE-owned content in rules/, hooks/, and hookify/.
+ * Used to identify ACE-owned content in ace/, hooks/, and hookify/.
  */
 export const ACE_OWNED_PATTERNS = [
-  /^rules\/ace\//,          // rules/ace/*.md
+  /^ace\/rules\//,          // ace/rules/*.md (v2.0+)
+  /^ace\/team\//,           // ace/team/*.md (v2.0+)
+  /^rules\/ace\//,          // rules/ace/*.md (legacy, for migration detection)
   /^hooks\/ace\./,          // hooks/ace.*.sh
   /^hookify\.ace\./,        // hookify.ace.*.local.md
 ];
@@ -77,12 +79,12 @@ export function isAceOwnedFile(relativePath) {
 
 /**
  * Check if an @reference path is owned by ACE.
- * @param {string} refPath - Reference path like '~/.claude/rules/ace/thinking.md' or '~/.claude/hooks/ace.java-compile-check.sh'
+ * @param {string} refPath - Reference path like '@~/.claude/rules/ace/thinking.md' or '~/.claude/hooks/ace.java-compile-check.sh'
  * @returns {boolean}
  */
 export function isAceOwnedRef(refPath) {
-  // Remove the ~/.claude/ prefix if present
-  const relativePath = refPath.replace(/^~\/\.claude\//, '');
+  // Remove the @~/.claude/ or ~/.claude/ prefix if present
+  const relativePath = refPath.replace(/^@?~\/\.claude\//, '');
   return isAceOwnedFile(relativePath);
 }
 
@@ -98,7 +100,7 @@ export const COMPONENTS = {
   rules: {
     description: 'Cognitive & code quality rules',
     required: true,
-    rulesDir: 'rules/ace',
+    rulesDir: 'ace/rules',
   },
   plugin: {
     description: 'Ace plugin (skills: auto-goal, coding, skill-creator, skill-optimize; commands: report)',

package/src/core/installer.js

@@ -94,6 +94,7 @@ export class Installer {
   async run() {
     if (!this.dryRun) {
       await fs.ensureDir(this.targetDir);
+      await this.prepare();
     }
 
     for (const componentName of this.components) {
@@ -114,6 +115,57 @@ export class Installer {
     return this.results;
   }
 
+  /**
+   * Prepare the target directory: migrate legacy structure and ensure new layout.
+   * Call this before installComponent() if not using run().
+   */
+  async prepare() {
+    await fs.ensureDir(this.targetDir);
+    await this.migrateFromLegacy();
+    await this.ensureAceStructure();
+  }
+
+  /**
+   * Migrate from legacy directory structure (rules/ace/) to new (ace/rules/).
+   * Only runs if old directory exists.
+   */
+  async migrateFromLegacy() {
+    const legacyDir = path.join(this.targetDir, 'rules', 'ace');
+    const newDir = path.join(this.targetDir, 'ace', 'rules');
+
+    if (!await fs.pathExists(legacyDir)) return;
+
+    // Move contents from legacy to new location
+    await fs.ensureDir(newDir);
+    const files = await fs.readdir(legacyDir);
+    for (const file of files) {
+      const src = path.join(legacyDir, file);
+      const dest = path.join(newDir, file);
+      await fs.move(src, dest, { overwrite: true });
+    }
+
+    // Remove empty legacy directory
+    await fs.remove(legacyDir);
+    // Clean up parent if empty
+    const rulesParent = path.join(this.targetDir, 'rules');
+    if (await fs.pathExists(rulesParent)) {
+      const remaining = await fs.readdir(rulesParent);
+      if (remaining.length === 0) {
+        await fs.remove(rulesParent);
+      }
+    }
+
+    this.results.merged.push({ file: 'ace/rules/ (migrated from rules/ace/)' });
+  }
+
+  /**
+   * Ensure the ace/ namespace directory structure exists.
+   */
+  async ensureAceStructure() {
+    await fs.ensureDir(path.join(this.targetDir, 'ace', 'rules'));
+    await fs.ensureDir(path.join(this.targetDir, 'ace', 'team'));
+  }
+
   async installComponent(name, component) {
     if (component.isPlugin) {
       await this.installPlugin();
@@ -330,15 +382,16 @@ export class Installer {
   async mergeClaudeMdFile(srcPath, destPath, fileSpec) {
     const existing = await fs.readFile(destPath, 'utf-8');
     const template = await fs.readFile(srcPath, 'utf-8');
-    const { content, added } = mergeClaudeMd(existing, template);
+    const { content, added, removed } = mergeClaudeMd(existing, template);
 
-    if (added.length === 0) {
+    // Skip if content is unchanged (no refs added/removed, managed section identical)
+    if (content === existing) {
       this.results.skipped.push(fileSpec.dest);
       return;
     }
 
     if (this.dryRun) {
-      !this.quiet && console.log(chalk.cyan(`  [dry-run] Would merge CLAUDE.md, adding ${added.length} references`));
+      !this.quiet && console.log(chalk.cyan(`  [dry-run] Would merge CLAUDE.md`));
       this.results.merged.push({ file: fileSpec.dest, added });
       return;
     }
@@ -346,7 +399,7 @@ export class Installer {
     await backupPreInstall(destPath);
     await backupFile(destPath);
     await fs.writeFile(destPath, content, 'utf-8');
-    this.results.merged.push({ file: fileSpec.dest, added });
+    this.results.merged.push({ file: fileSpec.dest, added, removed });
   }
 
   async mergeSettingsJsonFile(srcPath, destPath, fileSpec) {

package/src/core/merger.js

@@ -60,28 +60,40 @@ function mergeWithMarkers(existingContent, templateContent) {
   let result = replaceManagedSection(existingContent, templateManaged);
 
   // Clean up any obsolete ACE refs outside the managed section
+  // This includes old @~/.claude/rules/ace/ refs AND hookify @refs
   const removed = [];
   const lines = result.split('\n');
   const cleanedLines = lines.map(line => {
     const refs = extractRefs(line);
     const hasObsoleteAceRef = refs.some(ref => {
-      // Check if this is an ACE-owned ref that's NOT in the new template
       if (isAceOwnedRef(ref)) {
         const refWithAt = `@${ref}`;
         if (!templateRefs.includes(refWithAt)) {
           removed.push(ref);
-          return true; // This line has an obsolete ref
+          return true;
         }
       }
       return false;
     });
 
-    // Return null to mark for removal, otherwise keep line
+    // Also remove lines with hookify @ references (these should not be in CLAUDE.md)
+    const hasHookifyRef = refs.some(ref => /hookify\.ace\./.test(ref));
+    if (hasHookifyRef) {
+      const refBare = refs.find(ref => /hookify\.ace\./.test(ref));
+      if (refBare) removed.push(refBare);
+      return null;
+    }
+
     return hasObsoleteAceRef ? null : line;
   }).filter(line => line !== null);
 
   result = cleanedLines.join('\n');
 
+  // Clean up empty "## Added by ace" section if all its refs were removed
+  result = result.replace(/\n## Added by ace\n*(?=\n|$)/g, '\n');
+  // Normalize multiple blank lines
+  result = result.replace(/\n{3,}/g, '\n\n');
+
   // Get the new refs that were added (in the managed section)
   const existingRefs = extractRefs(existingContent);
   const added = templateRefs

package/templates/CLAUDE.md

@@ -1,21 +1,31 @@
-# 全局配置索引
+# 交互语言
+始终使用中文与用户交互。所有回复、解释、总结使用中文；代码和技术标识符保持英文。
 
 <!-- ace:managed:start -->
-## 核心原则
-- @~/.claude/rules/ace/thinking.md - 深度思考原则（序验深广辨简）
+# ACE 配置
 
-## 代码规范
-- @~/.claude/rules/ace/clean-code.md - Clean Code 核心原则（始终加载）
-- @~/.claude/rules/ace/code-quality.md - 代码质量标准（编辑代码文件时加载）
+## 核心原则（始终适用）
 
-## 工作流规则
-- @~/.claude/rules/ace/reporting.md - 报告输出规则
-- @~/.claude/rules/ace/task-recovery.md - 任务恢复规则
-- @~/.claude/rules/ace/context-hygiene.md - 上下文卫生与 Compaction 保护
+**深度思考** — 理解先于规划，规划先于行动。用事实闭环，不以假设收尾。多问一层为什么，追问前提、追问替代、追问问题本身。在系统中定位局部。主动找反证，复杂度是负债。
 
-## 质量控制
-- @~/.claude/rules/ace/memory-policy.md - Memory 质量策略
+**Clean Code** — 意图清晰（命名即意图）、单一职责（一个理由改变）、最小 Surprise（做读者期望的事）、DRY（知识只表达一次）、简洁胜于复杂（KISS/YAGNI）、渐进改进（离开时更干净）。
 
-## 交互规则
-- @~/.claude/rules/ace/interactive-clarify.md - 交互式澄清规则
+**优先级** — 正确性 > 可读性 > 清晰 > 简单 > 显式。
+
+## 编码规则（编辑代码前，先阅读对应规则文件）
+- ~/.claude/ace/rules/code-quality.md — 代码质量标准（函数/命名/结构/SOLID 检查清单）
+- ~/.claude/ace/rules/clean-code.md — Clean Code 详细原则与反模式速查
+
+## 工作流规则（对应场景时参考）
+- ~/.claude/ace/rules/context-hygiene.md — 上下文卫生与压缩保护（长任务时阅读）
+- ~/.claude/ace/rules/task-recovery.md — 任务恢复流程（用户说"继续"时阅读）
+- ~/.claude/ace/rules/reporting.md — 报告输出规则（生成报告前阅读）
+- ~/.claude/ace/rules/memory-policy.md — 记忆质量策略（保存记忆前阅读）
+- ~/.claude/ace/rules/interactive-clarify.md — 交互式澄清规则（需要提问时阅读）
+
+## 安全策略
+安全由外部机制保障，不占用上下文 token：
+- settings.json deny 规则 → 硬拦截 rm -rf、sudo 等
+- Shell hooks → 进程级检查（编译、类型检查）
+- Hookify 插件 → 模式匹配拦截（危险命令、敏感文件）
 <!-- ace:managed:end -->

package/templates/{rules/ace → ace/rules}/thinking.md

@@ -12,6 +12,11 @@
 
 **深** — 多问一层为什么。表面问题是深层问题的症状。抵达机制层和根因层才算理解。
 
+苏格拉底式追问：
+- 追问前提："这个假设成立吗？依据是什么？"
+- 追问替代："还有没有其他解释？"
+- 追问问题本身："这是正确的问题吗？问题框架对吗？"
+
 **广** — 在系统中定位局部。一切都有上下文、依赖和边界。改动一处，影响传向何方？
 
 **辨** — 主动为自己的结论找反证。方案都有代价，判断都有前提。区分事实、推断与猜测，对不确定性诚实。