@ecc-hgy/ae 0.3.0 → 0.5.0

package/src/commands/init.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { createDirectories, renderEntryFiles } from '../skeleton.js';
 import { templatesPath } from '../utils/paths.js';
 import { formatInitReport } from '../utils/report.js';
+import { PLATFORMS, getPlatformSkillsDir } from '../platforms.js';
 
 const DEFAULT_GOAL = 'TODO: 用一句话说明这个项目要解决什么问题。';
 
@@ -111,10 +112,12 @@ async function ensureTargetDirectory(target, dryRun) {
 }
 
 async function hasInstalledAssets(target) {
-  return (
-    (await isDirectory(path.join(target, '.claude', 'skills'))) ||
-    (await isDirectory(path.join(target, '.codex', 'skills')))
-  );
+  for (const platform of PLATFORMS) {
+    if (await isDirectory(path.join(target, getPlatformSkillsDir(platform)))) {
+      return true;
+    }
+  }
+  return false;
 }
 
 async function statMaybe(value) {

package/src/commands/setup.js

@@ -1,15 +1,28 @@
 import { mkdir, stat } from 'node:fs/promises';
 import path from 'node:path';
+import { createInterface } from 'node:readline/promises';
 import { copyTreeIdempotent } from '../utils/copy.js';
 import { skillsPath } from '../utils/paths.js';
 import { formatSetupReport } from '../utils/report.js';
+import {
+  PLATFORMS,
+  detectPlatforms,
+  getPlatformSkillsDir,
+  listPlatformIds,
+  parsePlatformList,
+  resolvePlatforms,
+} from '../platforms.js';
 
 const HELP = `Usage: ae setup [options]
 
 Options:
   --target <path>  Install AE assets into this project directory. Defaults to cwd.
+  --platform <ids> Install for comma-separated platforms, e.g. claude,codex,cursor.
   --dry-run        Show what would be installed without writing files.
-  -h, --help       Show help`;
+  -h, --help       Show help
+
+Platforms:
+  ${listPlatformIds().join(', ')}`;
 
 export async function run(argv = []) {
   const options = parseArgs(argv);
@@ -22,20 +35,20 @@ export async function run(argv = []) {
   const target = path.resolve(options.target ?? process.cwd());
 
   try {
+    const explicitPlatforms =
+      options.platformIds.length > 0 ? resolvePlatforms(options.platformIds) : undefined;
     await ensureTargetDirectory(target, options.dryRun);
+    const selectedPlatforms = explicitPlatforms ?? (await selectPlatforms(target));
 
     const created = [];
     const skipped = [];
-    const skillGroups = [
-      {
-        dest: path.join(target, '.claude', 'skills'),
-        prefix: path.join('.claude', 'skills'),
-      },
-      {
-        dest: path.join(target, '.codex', 'skills'),
-        prefix: path.join('.codex', 'skills'),
-      },
-    ];
+    const skillGroups = selectedPlatforms.map((platform) => {
+      const skillsDir = getPlatformSkillsDir(platform);
+      return {
+        dest: path.join(target, skillsDir),
+        prefix: skillsDir,
+      };
+    });
 
     for (const group of skillGroups) {
       const result = await copyTreeIdempotent(skillsPath(), group.dest, {
@@ -57,6 +70,7 @@ export async function run(argv = []) {
 function parseArgs(argv) {
   const options = {
     target: undefined,
+    platformIds: [],
     dryRun: false,
     help: false,
   };
@@ -67,6 +81,13 @@ function parseArgs(argv) {
       options.help = true;
     } else if (arg === '--dry-run') {
       options.dryRun = true;
+    } else if (arg === '--platform') {
+      const value = argv[index + 1];
+      if (!value) {
+        throw new Error('--platform requires a comma-separated platform list');
+      }
+      options.platformIds.push(...parsePlatformList(value));
+      index += 1;
     } else if (arg === '--target') {
       const value = argv[index + 1];
       if (!value) {
@@ -82,6 +103,44 @@ function parseArgs(argv) {
   return options;
 }
 
+async function selectPlatforms(target) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error(
+      `No platforms selected. In non-interactive mode, pass --platform <ids>. Available: ${listPlatformIds().join(', ')}`,
+    );
+  }
+
+  const detected = await detectPlatforms(target);
+  const detectedIds = detected.map((platform) => platform.id);
+  const defaultIds = detectedIds;
+
+  console.log('Select target platforms for AE skills:');
+  for (const [index, platform] of PLATFORMS.entries()) {
+    const marker = defaultIds.includes(platform.id) ? '*' : ' ';
+    console.log(`  ${index + 1}. [${marker}] ${platform.name} (${platform.id}) -> ${getPlatformSkillsDir(platform)}/`);
+  }
+
+  const defaultPrompt = defaultIds.length > 0 ? ` [${defaultIds.join(',')}]` : '';
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question(`Platform ids or numbers, comma-separated${defaultPrompt}: `);
+    const selected = answer.trim() ? parseInteractivePlatformAnswer(answer) : defaultIds;
+    return resolvePlatforms(selected);
+  } finally {
+    rl.close();
+  }
+}
+
+function parseInteractivePlatformAnswer(answer) {
+  return parsePlatformList(answer).map((item) => {
+    const number = Number(item);
+    if (Number.isInteger(number) && number >= 1 && number <= PLATFORMS.length) {
+      return PLATFORMS[number - 1].id;
+    }
+    return item;
+  });
+}
+
 async function ensureTargetDirectory(target, dryRun) {
   try {
     const current = await stat(target);

package/src/platforms.js

@@ -0,0 +1,132 @@
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+
+export const PLATFORMS = [
+  { id: 'claude', name: 'Claude Code', skillsDir: '.claude', aliases: ['claude-code'] },
+  { id: 'codex', name: 'Codex', skillsDir: '.codex' },
+  { id: 'windsurf', name: 'Windsurf', skillsDir: '.windsurf' },
+  {
+    id: 'github-copilot',
+    name: 'GitHub Copilot',
+    skillsDir: '.github',
+    aliases: ['copilot', 'github'],
+    detectionPaths: [
+      '.github/copilot-instructions.md',
+      '.github/instructions',
+      '.github/prompts',
+      '.github/skills',
+    ],
+  },
+  { id: 'kilocode', name: 'Kilo Code', skillsDir: '.kilocode', aliases: ['kilo-code'] },
+  { id: 'kimicode', name: 'Kimi Code', skillsDir: '.kimi-code', aliases: ['kimi', 'kimi-code'] },
+  { id: 'codebuddy', name: 'CodeBuddy', skillsDir: '.codebuddy', aliases: ['codebuddy-code'] },
+  { id: 'qoder', name: 'Qoder', skillsDir: '.qoder' },
+  { id: 'trae', name: 'Trae', skillsDir: '.trae' },
+  { id: 'cursor', name: 'Cursor', skillsDir: '.cursor' },
+  { id: 'opencode', name: 'OpenCode', skillsDir: '.opencode', aliases: ['open-code'] },
+  { id: 'antigravity', name: 'Antigravity', skillsDir: '.agents' },
+  { id: 'gemini', name: 'Gemini CLI', skillsDir: '.gemini', aliases: ['gemini-cli'] },
+  { id: 'qwen', name: 'Qwen Code', skillsDir: '.qwen', aliases: ['qwen-code'] },
+  { id: 'kiro', name: 'Kiro', skillsDir: '.kiro' },
+];
+
+const PLATFORM_BY_ID_OR_ALIAS = new Map(
+  PLATFORMS.flatMap((platform) => [
+    [platform.id, platform],
+    ...(platform.aliases ?? []).map((alias) => [alias, platform]),
+  ]),
+);
+
+export function listPlatformIds() {
+  return PLATFORMS.map((platform) => platform.id);
+}
+
+export function resolvePlatforms(ids) {
+  const resolved = [];
+  const seen = new Set();
+  const unknown = [];
+
+  for (const rawId of ids) {
+    const id = rawId.trim().toLowerCase();
+    if (!id) {
+      continue;
+    }
+
+    const platform = PLATFORM_BY_ID_OR_ALIAS.get(id);
+    if (!platform) {
+      unknown.push(rawId);
+      continue;
+    }
+
+    if (!seen.has(platform.id)) {
+      resolved.push(platform);
+      seen.add(platform.id);
+    }
+  }
+
+  if (unknown.length > 0) {
+    throw new Error(`Unknown platform(s): ${unknown.join(', ')}. Available: ${listPlatformIds().join(', ')}`);
+  }
+
+  if (resolved.length === 0) {
+    throw new Error(`No platforms selected. Available: ${listPlatformIds().join(', ')}`);
+  }
+
+  return resolved;
+}
+
+export function parsePlatformList(value) {
+  return value
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+export function getPlatformSkillsDir(platform) {
+  return path.join(platform.skillsDir, 'skills');
+}
+
+export async function detectPlatforms(target) {
+  const detected = [];
+
+  for (const platform of PLATFORMS) {
+    if (platform.detectionPaths?.length > 0) {
+      for (const detectionPath of platform.detectionPaths) {
+        if (await pathExists(path.join(target, detectionPath))) {
+          detected.push(platform);
+          break;
+        }
+      }
+      continue;
+    }
+
+    if (await isDirectory(path.join(target, platform.skillsDir))) {
+      detected.push(platform);
+    }
+  }
+
+  return detected;
+}
+
+async function pathExists(value) {
+  try {
+    await stat(value);
+    return true;
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return false;
+    }
+    throw error;
+  }
+}
+
+async function isDirectory(value) {
+  try {
+    return (await stat(value)).isDirectory();
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return false;
+    }
+    throw error;
+  }
+}

package/src/skeleton.js

@@ -27,6 +27,10 @@ const ENTRY_FILES = [
   'handoff.md',
   path.join('spec', 'README.md'),
   path.join('spec', 'INDEX.md'),
+  path.join('spec', 'AGENTS.md'),
+  path.join('spec', 'CLAUDE.md'),
+  path.join('spec', 'ADR', 'AGENTS.md'),
+  path.join('spec', 'ADR', 'CLAUDE.md'),
 ];
 
 export async function createDirectories(target, options = {}) {

package/templates/entries/AGENTS.md

@@ -1,24 +1,3 @@
 # {{PROJECT_NAME}}
 
 > {{PROJECT_GOAL}}
-
-## Project-Specific Rules
-
-<!-- 在这里写本项目的稳定规则,例如:
-     - 代码风格 / 注释语言
-     - 提交规范
-     - 协作偏好
-     这些规则会被 Claude Code / Codex 在每次 session 自动加载。
-     未来新规则直接追加到本段,不需要其他工具命令。 -->
-
-## Stack
-
-TODO: 简述项目技术栈与运行环境。
-
-## Structure
-
-TODO: 简述目录结构,标注关键入口。
-
-## Operating Guidelines
-
-TODO: 简述代码、测试、提交、PR 的操作规范。

package/templates/entries/README.md

@@ -1,18 +1,32 @@
 # {{PROJECT_NAME}}
 
-{{PROJECT_GOAL}}
+> {{PROJECT_GOAL}}
 
-## Setup
+<!--
+根 README 的核心:让别人 30 秒搞清「为什么有用、能做什么、怎么用」。
+下面是建议骨架,按需增删、不必都填,也不必拘泥小节名:
+- 它是什么 + 一句话价值 → 上面的标题 + 一行(已占位)
+- 为什么 / 给谁 → 解决什么问题、面向谁
+- Quick Start → 最快见效的一段命令 / 步骤(装好 + 第一个能见效的操作)
+- 使用示例 → 典型场景(必要时再贴一段真实用法)
+- 目录地图 / 文档入口 → 关键目录 + 深入文档的链接
+-->
 
-TODO: 记录安装和启动方式。
+## 这是什么
 
-## Usage
+TODO: 一段话说清它解决什么问题、给谁用、用它能做什么。
 
-TODO: 记录常用操作。
+## Quick Start
 
-## Project Map
+TODO: 最快跑起来的命令或步骤。
 
-- `reference/`: 原始素材，只读心态。
-- `spec/`: SDD/TDD 规格产物。
-- `data/`: 运行产物、导出和缓存。
-- `scripts/`: 辅助脚本。
+<!-- ## 使用示例 —— 有典型场景时再加,贴一段真实用法 -->
+
+## 目录地图
+
+- `spec/`:SDD/TDD 规格产物——需求索引看 `spec/INDEX.md`,项目地图看 `spec/README.md`。
+- `reference/`:原始素材,只读心态。
+- `data/`:运行产物、导出、缓存。
+- `scripts/`:辅助脚本。
+
+<!-- 文档入口:AGENTS.md(项目指令)· handoff.md(当前态快照)· spec/INDEX.md(需求索引) -->

package/templates/entries/spec/ADR/AGENTS.md

@@ -0,0 +1,30 @@
+# spec/ADR/ 规则
+
+> 架构决策记录(ADR)规则。在 `spec/ADR/` 下创建或修改 ADR 时遵守本文件。
+
+## 命名
+
+`NNNN-<标题>.md`,**4 位序号**,kebab-case 标题。例:`0001-postgres-as-primary-store.md`。
+
+## frontmatter
+
+```yaml
+---
+status: accepted          # proposed | accepted | superseded
+date: 2026-06-14
+supersedes: 0000-xxx.md   # 仅当取代旧 ADR 时填
+---
+```
+
+正文按具体决策自然组织(背景 / 决策 / 理由 / 影响),不强加重模板。
+
+## 状态机
+
+```text
+proposed ─(评审接受)─► accepted ─(新 ADR 取代)─► superseded
+```
+
+- `proposed`:新提案,未拍板(由 writing-plans / review / improve-codebase-architecture 创建时默认)。
+- `accepted`:已评审接受;视为**约束**,其他需求不得违背。
+- `superseded`:被新 ADR 取代;新 ADR 的 `supersedes` 指回旧编号,**不删旧文件**。
+

package/templates/entries/spec/ADR/CLAUDE.md

@@ -0,0 +1,5 @@
+# spec/ADR/
+
+**Always read [AGENTS.md](./AGENTS.md) in this directory before creating or editing an ADR.**
+
+`spec/ADR/AGENTS.md` defines ADR naming, frontmatter, and the proposed/accepted/superseded state machine.

package/templates/entries/spec/AGENTS.md

@@ -0,0 +1,35 @@
+# spec/ 规则
+
+> 本目录(`spec/`)的工作规则。在 `spec/` 下读写文件时遵守本文件。
+
+## 总领
+
+S1 节点 → 产物 → skill 的路由总览,见随包的 `using-agentic-engineering` skill——它判定"进不进 AE 流程"并分发到各节点。
+
+两道硬门禁:**A1 未对齐不写 prd**;**B2 期望态未对齐不修复**。
+
+
+## R1:落盘后同步 INDEX
+落盘 `spec/needs/<需求名>/` 下任何文件后,**必须同步更新 `spec/INDEX.md`** 对应行。若不确定如何更新,按上面「INDEX 推导规则」手动重算(未来可用 `ae index-rebuild` 幂等重扫)。
+
+### INDEX 推导规则
+
+`spec/INDEX.md` 给模型看:一次扫描看到所有需求 + 状态 + 进度。`当前节点` 列**不存储**在任何 frontmatter,由该需求下文件状态**实时推导**:
+
+| 条件 | 当前节点 |
+|------|---------|
+| prd 不存在 或 status=draft | A1 / A2 |
+| prd active + design 不存在/draft | A3 设计 |
+| prd+design active + todo 不存在 | A4 拆解 |
+| prd+design active + todo 有未完成项 | A5 执行 |
+| todo 全勾 + 未端到端验证 | A6 verify |
+| 所有 issues 已验收 + 已交付 | 已完成 |
+| 存在 active 的 issues | 进 B 子路径,按 issues 状态推 B2…B7 |
+| prd / design 任一 archived | 已归档 |
+
+- INDEX 是**推导态**:文件状态变就重新推导,**不要手编 `当前节点` 列**。
+
+
+## 何时升 ADR
+
+决策影响**多个需求**或属项目级不变量时,从 `design.md` 升到`spec/ADR`(判断:推翻它会改动 >1 个需求)。单需求的技术决策留在该需求的 `design.md`。

package/templates/entries/spec/CLAUDE.md

@@ -0,0 +1,5 @@
+# spec/
+
+**Always read [AGENTS.md](./AGENTS.md) in this directory before working under `spec/`.**
+
+`spec/AGENTS.md` defines the S1 node map, the INDEX derivation table, and the post-write INDEX sync rule (R1).

package/templates/entries/spec/INDEX.md

@@ -2,14 +2,27 @@
 
 ## 需求
 
+<!--
+各列怎么填:
+- 需求名:`spec/needs/<需求名>/` 的 kebab 目录名
+- prd / design:对应文件 frontmatter 的 status(draft/active/archived);文件不存在填 -
+- todo:todo.md 的 已勾数/总数(如 5/8,即拆解任务的完成进度);无 todo.md 填 -。这是 A5 内部子进度,不是节点位次(节点看「当前节点」列)
+- issues:该需求 issues/ 下文件数 + 是否有未结(如 0 / 1 active);无则 -
+- 当前节点:由文件状态推导得出,不手编(推导规则见 spec/AGENTS.md「INDEX 推导规则」)
+-->
+
 | 需求名 | prd | design | todo | issues | 当前节点 |
 |--------|-----|--------|------|--------|----------|
 
 ## ADR
 
+<!-- 编号 4 位 / 状态 proposed|accepted|superseded / 日期,均取自各 ADR frontmatter(详见 spec/ADR/AGENTS.md) -->
+
 | 编号 | 标题 | 状态 | 日期 |
 |------|------|------|------|
 
 ## 跨需求引用
 
+<!-- 从各 prd/design frontmatter 的 related-needs 聚合 -->
+
 - 暂无

package/templates/entries/spec/README.md

@@ -1,5 +1,7 @@
 # Spec Map
 
+> 给人看:回忆"项目长什么样"。以 ASCII 图为主,可省细节、突出全貌。**README ≠ INDEX 镜像**——INDEX 给模型看进度,这里给人看全貌。
+
 ## Needs
 
 ```text
@@ -12,6 +14,8 @@ TODO: 用 ASCII 图画出需求地图。
 TODO: 用 ASCII 图画出核心业务流程。
 ```
 
+> 全局架构总览画在这里(而非写进某个需求的 design.md)。
+
 ## Relationships
 
 ```text