@fitlab-ai/agent-infra 0.3.2 → 0.4.1

package/README.md

@@ -144,7 +144,7 @@ ai init
 # or: agent-infra init
 ```
 
-The CLI collects project metadata, installs the `update-agent-infra` seed command for all supported AI TUIs, and generates `.airc.json`.
+The CLI collects project metadata, installs the `update-agent-infra` seed command for all supported AI TUIs, and generates `.agents/.airc.json`.
 
 > `ai` is a shorthand for `agent-infra`. Both commands are equivalent.
 
@@ -159,7 +159,7 @@ Open the project in any AI TUI and run `update-agent-infra`:
 | Gemini CLI | `/{{project}}:update-agent-infra` |
 | OpenCode | `/update-agent-infra` |
 
-This pulls the latest templates and renders all managed files. The same command is used both for first-time setup and for future template upgrades.
+This detects the packaged template version and renders all managed files. The same command is used both for first-time setup and for future template upgrades.
 
 <a id="architecture-overview"></a>
 
@@ -170,8 +170,8 @@ agent-infra is intentionally simple: a bootstrap CLI creates the seed configurat
 ### End-to-End Flow
 
 1. **Install** — `npm install -g @fitlab-ai/agent-infra` (or use the shell script wrapper)
-2. **Initialize** — `ai init` in the project root to generate `.airc.json` and install the seed command
-3. **Render** — run `update-agent-infra` in any AI TUI to pull templates and generate all managed files
+2. **Initialize** — `ai init` in the project root to generate `.agents/.airc.json` and install the seed command
+3. **Render** — run `update-agent-infra` in any AI TUI to detect the bundled template version and generate all managed files
 4. **Develop** — use 28 built-in skills to drive the full lifecycle: `analysis → design → implementation → review → fix → commit`
 5. **Update** — run `update-agent-infra` again whenever a new template version is available
 
@@ -197,7 +197,7 @@ block-beta
 
     block:project:4
         columns 4
-        agents[".agents/"] config[".airc.json"] workspace[".agent-workspace/"] governance["AGENTS.md"]
+        agents[".agents/"] config[".agents/.airc.json"] workspace[".agents/workspace/"] governance["AGENTS.md"]
     end
 
     tui -- "slash commands" --> shared
@@ -215,19 +215,15 @@ After setup, your project gains a complete AI collaboration infrastructure:
 ```text
 my-project/
 ├── .agents/               # Shared AI collaboration config
+│   ├── .airc.json         # Central configuration
+│   ├── workspace/         # Task workspace (git-ignored)
 │   ├── skills/            # 28 built-in AI skills
 │   ├── workflows/         # 4 prebuilt workflows
 │   └── templates/         # Task and artifact templates
-├── .agent-workspace/      # Task workspace (git-ignored)
 ├── .claude/               # Claude Code config and commands
 ├── .gemini/               # Gemini CLI config and commands
 ├── .opencode/             # OpenCode config and commands
-├── .github/               # PR templates, issue forms, workflows
-├── AGENTS.md              # Universal AI agent instructions
-├── CONTRIBUTING.md        # Contribution guide
-├── SECURITY.md            # Security policy (English)
-├── SECURITY.zh-CN.md      # Security policy (Chinese)
-└── .airc.json             # Central configuration
+└── AGENTS.md              # Universal AI agent instructions
 ```
 
 <a id="built-in-ai-skills"></a>
@@ -375,20 +371,19 @@ import-issue #42                    Import task from GitHub Issue
 
 ## Configuration Reference
 
-The generated `.airc.json` file is the central contract between the bootstrap CLI, templates, and future updates.
+The generated `.agents/.airc.json` file is the central contract between the bootstrap CLI, templates, and future updates.
 
-### Example `.airc.json`
+### Example `.agents/.airc.json`
 
 ```json
 {
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateSource": "templates/",
-  "templateVersion": "v0.3.2",
-  "modules": ["ai", "github"],
+  "templateVersion": "v0.4.1",
   "files": {
     "managed": [
+      ".agents/workspace/README.md",
       ".agents/skills/",
       ".agents/templates/",
       ".agents/workflows/",
@@ -399,9 +394,7 @@ The generated `.airc.json` file is the central contract between the bootstrap CL
     "merged": [
       ".agents/README.md",
       ".gitignore",
-      "AGENTS.md",
-      "CONTRIBUTING.md",
-      "SECURITY.md"
+      "AGENTS.md"
     ],
     "ejected": []
   }
@@ -415,18 +408,9 @@ The generated `.airc.json` file is the central contract between the bootstrap CL
 | `project` | Project name used when rendering commands, paths, and templates. |
 | `org` | GitHub organization or owner used by generated metadata and links. |
 | `language` | Primary project language or locale used by rendered templates. |
-| `templateSource` | Local template root used during rendering. |
 | `templateVersion` | Installed template version for future upgrades and drift tracking. |
-| `modules` | Enabled template bundles. Supported values are `ai` and `github`. |
 | `files` | Per-path update strategy configuration for managed, merged, and ejected files. |
 
-### Module reference
-
-| Module | Includes |
-|--------|----------|
-| `ai` | `.agents/`, `.claude/`, `.gemini/`, `.opencode/`, `AGENTS.md`, and related collaboration assets |
-| `github` | `.github/`, contribution templates, release config, and GitHub governance assets |
-
 <a id="file-management-strategies"></a>
 
 ## File Management Strategies
@@ -446,15 +430,14 @@ Each generated path is assigned an update strategy. That strategy determines how
   "files": {
     "managed": [
       ".agents/skills/",
-      ".github/workflows/pr-title-check.yml"
+      ".agents/workspace/README.md"
     ],
     "merged": [
       ".gitignore",
-      "AGENTS.md",
-      "CONTRIBUTING.md"
+      "AGENTS.md"
     ],
     "ejected": [
-      "SECURITY.md"
+      "docs/architecture.md"
     ]
   }
 }
@@ -462,7 +445,7 @@ Each generated path is assigned an update strategy. That strategy determines how
 
 ### Moving a file from `managed` to `ejected`
 
-1. Remove the path from the `managed` array in `.airc.json`.
+1. Remove the path from the `managed` array in `.agents/.airc.json`.
 2. Add the same path to the `ejected` array.
 3. Run `update-agent-infra` again so future updates stop managing that file.
 
@@ -472,7 +455,7 @@ Use this when a file starts as template-owned but later becomes project-specific
 
 ## Version Management
 
-agent-infra uses semantic versioning through Git tags and GitHub releases. The installed template version is recorded in `.airc.json` as `templateVersion`, which gives both humans and AI tools a stable reference point for upgrades.
+agent-infra uses semantic versioning through Git tags and GitHub releases. The installed template version is recorded in `.agents/.airc.json` as `templateVersion`, which gives both humans and AI tools a stable reference point for upgrades.
 
 <a id="contributing"></a>
 

package/README.zh-CN.md

@@ -144,7 +144,7 @@ ai init
 # 或：agent-infra init
 ```
 
-CLI 会收集项目元数据，向所有支持的 AI TUI 安装 `update-agent-infra` 种子命令，并生成 `.airc.json`。
+CLI 会收集项目元数据，向所有支持的 AI TUI 安装 `update-agent-infra` 种子命令，并生成 `.agents/.airc.json`。
 
 > `ai` 是 `agent-infra` 的简写命令，两者等价。
 
@@ -159,7 +159,7 @@ CLI 会收集项目元数据，向所有支持的 AI TUI 安装 `update-agent-in
 | Gemini CLI | `/{{project}}:update-agent-infra` |
 | OpenCode | `/update-agent-infra` |
 
-该命令会拉取最新模板并渲染所有受管理文件。首次安装和后续升级都使用同一条命令。
+该命令会检测当前打包模板版本并渲染所有受管理文件。首次安装和后续升级都使用同一条命令。
 
 <a id="architecture-overview"></a>
 
@@ -170,8 +170,8 @@ agent-infra 的结构刻意保持简单：引导 CLI 负责生成种子配置，
 ### 端到端流程
 
 1. **安装** — `npm install -g @fitlab-ai/agent-infra`（或使用 shell 脚本便捷封装）
-2. **初始化** — 在项目根目录运行 `ai init`，生成 `.airc.json` 并安装种子命令
-3. **渲染** — 在任意 AI TUI 中执行 `update-agent-infra`，拉取模板并生成所有受管理文件
+2. **初始化** — 在项目根目录运行 `ai init`，生成 `.agents/.airc.json` 并安装种子命令
+3. **渲染** — 在任意 AI TUI 中执行 `update-agent-infra`，检测当前打包模板版本并生成所有受管理文件
 4. **开发** — 使用 28 个内置 skill 驱动完整生命周期：`analysis → design → implementation → review → fix → commit`
 5. **升级** — 有新模板版本时再次执行 `update-agent-infra` 即可
 
@@ -197,7 +197,7 @@ block-beta
 
     block:project:4
         columns 4
-        agents[".agents/"] config[".airc.json"] workspace[".agent-workspace/"] governance["AGENTS.md"]
+        agents[".agents/"] config[".agents/.airc.json"] workspace[".agents/workspace/"] governance["AGENTS.md"]
     end
 
     tui -- "slash commands" --> shared
@@ -215,19 +215,15 @@ GitHub 原生支持 Mermaid 渲染。即使某些下游渲染器不支持，上
 ```text
 my-project/
 ├── .agents/               # 共享 AI 协作配置
+│   ├── .airc.json         # 中央配置文件
+│   ├── workspace/         # 任务工作区（git 忽略）
 │   ├── skills/            # 28 个内置 AI skills
 │   ├── workflows/         # 4 个预置工作流
 │   └── templates/         # 任务与产物模板
-├── .agent-workspace/      # 任务工作区（git 忽略）
 ├── .claude/               # Claude Code 配置与命令
 ├── .gemini/               # Gemini CLI 配置与命令
 ├── .opencode/             # OpenCode 配置与命令
-├── .github/               # PR 模板、Issue 表单、工作流
-├── AGENTS.md              # 通用 AI agent 指令
-├── CONTRIBUTING.md        # 贡献指南
-├── SECURITY.md            # 安全策略（英文）
-├── SECURITY.zh-CN.md      # 安全策略（中文）
-└── .airc.json             # 中央配置文件
+└── AGENTS.md              # 通用 AI agent 指令
 ```
 
 <a id="built-in-ai-skills"></a>
@@ -375,20 +371,19 @@ import-issue #42                    从 GitHub Issue 导入任务
 
 ## 配置参考
 
-生成出的 `.airc.json` 是引导 CLI、模板系统和后续升级之间的中心契约。
+生成出的 `.agents/.airc.json` 是引导 CLI、模板系统和后续升级之间的中心契约。
 
-### `.airc.json` 示例
+### `.agents/.airc.json` 示例
 
 ```json
 {
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateSource": "templates/",
-  "templateVersion": "v0.3.2",
-  "modules": ["ai", "github"],
+  "templateVersion": "v0.4.1",
   "files": {
     "managed": [
+      ".agents/workspace/README.md",
       ".agents/skills/",
       ".agents/templates/",
       ".agents/workflows/",
@@ -399,9 +394,7 @@ import-issue #42                    从 GitHub Issue 导入任务
     "merged": [
       ".agents/README.md",
       ".gitignore",
-      "AGENTS.md",
-      "CONTRIBUTING.md",
-      "SECURITY.md"
+      "AGENTS.md"
     ],
     "ejected": []
   }
@@ -415,18 +408,9 @@ import-issue #42                    从 GitHub Issue 导入任务
 | `project` | 用于渲染命令、路径和模板内容的项目名。 |
 | `org` | 生成元数据和链接时使用的 GitHub 组织或拥有者。 |
 | `language` | 渲染模板时采用的项目主语言或区域设置。 |
-| `templateSource` | 本地模板根目录。 |
 | `templateVersion` | 当前安装的模板版本，用于升级和差异追踪。 |
-| `modules` | 启用的模板模块。可选值为 `ai` 和 `github`。 |
 | `files` | 针对具体路径配置 `managed`、`merged`、`ejected` 三类更新策略。 |
 
-### 模块说明
-
-| 模块 | 包含内容 |
-|------|----------|
-| `ai` | `.agents/`、`.claude/`、`.gemini/`、`.opencode/`、`AGENTS.md` 及相关协作资产 |
-| `github` | `.github/`、贡献模板、发布配置以及 GitHub 治理相关文件 |
-
 <a id="file-management-strategies"></a>
 
 ## 文件管理策略
@@ -446,15 +430,14 @@ import-issue #42                    从 GitHub Issue 导入任务
   "files": {
     "managed": [
       ".agents/skills/",
-      ".github/workflows/pr-title-check.yml"
+      ".agents/workspace/README.md"
     ],
     "merged": [
       ".gitignore",
-      "AGENTS.md",
-      "CONTRIBUTING.md"
+      "AGENTS.md"
     ],
     "ejected": [
-      "SECURITY.md"
+      "docs/architecture.md"
     ]
   }
 }
@@ -462,7 +445,7 @@ import-issue #42                    从 GitHub Issue 导入任务
 
 ### 如何把文件从 `managed` 改为 `ejected`
 
-1. 在 `.airc.json` 中把该路径从 `managed` 数组移除。
+1. 在 `.agents/.airc.json` 中把该路径从 `managed` 数组移除。
 2. 将同一路径加入 `ejected` 数组。
 3. 再次执行 `update-agent-infra`，让后续升级不再管理这个文件。
 
@@ -472,7 +455,7 @@ import-issue #42                    从 GitHub Issue 导入任务
 
 ## 版本管理
 
-agent-infra 通过 Git tag 和 GitHub release 使用语义化版本号。当前安装的模板版本记录在 `.airc.json` 的 `templateVersion` 字段中，方便人和 AI 工具在升级时都能基于同一个版本基线工作。
+agent-infra 通过 Git tag 和 GitHub release 使用语义化版本号。当前安装的模板版本记录在 `.agents/.airc.json` 的 `templateVersion` 字段中，方便人和 AI 工具在升级时都能基于同一个版本基线工作。
 
 <a id="contributing"></a>
 

package/lib/defaults.json

@@ -4,15 +4,11 @@
       ".agents/skills/",
       ".agents/templates/",
       ".agents/workflows/",
-      ".agent-workspace/README.md",
+      ".agents/workspace/README.md",
       ".claude/commands/",
-      ".editorconfig",
+      ".claude/hooks/",
       ".gemini/commands/",
-      ".github/hooks/",
-      ".github/ISSUE_TEMPLATE/",
-      ".github/PULL_REQUEST_TEMPLATE.md",
-      ".github/release.yml",
-      ".github/workflows/pr-title-check.yml",
+      ".github/hooks/check-version-format.sh",
       ".opencode/commands/"
     ],
     "merged": [
@@ -31,14 +27,11 @@
       ".claude/settings.json",
       ".codex/README.md",
       ".gemini/settings.json",
-      ".github/dependabot.yml",
+      ".github/hooks/pre-commit",
       ".gitignore",
-      ".mailmap",
       ".opencode/COMMAND_STYLE_GUIDE.md",
       ".opencode/README.md",
-      "AGENTS.md",
-      "CONTRIBUTING.md",
-      "SECURITY.md"
+      "AGENTS.md"
     ],
     "ejected": []
   }

package/lib/init.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { execSync } from 'node:child_process';
 import { info, ok, err } from './log.js';
 import { prompt, closePrompt } from './prompt.js';
-import { resolveTemplateDir, resolveInstallDir, isCloneInstall } from './paths.js';
+import { resolveTemplateDir } from './paths.js';
 import { renderFile, copySkillDir } from './render.js';
 import { VERSION } from './version.js';
 
@@ -50,28 +50,15 @@ async function cmdInit() {
   if (!templateDir) {
     err('Template directory not found.');
     err('Install via npm: npm install -g @fitlab-ai/agent-infra');
-    err('Or via clone: curl -fsSL https://raw.githubusercontent.com/fitlab-ai/agent-infra/main/install.sh | sh');
     process.exitCode = 1;
     return;
   }
 
-  // auto-update: only for clone installs
-  if (isCloneInstall()) {
-    const installDir = resolveInstallDir();
-    if (fs.existsSync(path.join(installDir, '.git'))) {
-      info('Updating templates to latest version...');
-      try {
-        execSync('git pull --rebase --quiet', { cwd: installDir, stdio: 'pipe' });
-        ok('Templates updated.');
-      } catch {
-        err('Failed to update templates (network issue?). Using local version.');
-      }
-    }
-  }
+  const configPath = path.join('.agents', '.airc.json');
 
-  // check existing .airc.json
-  if (fs.existsSync('.airc.json')) {
-    err('This project already has a .airc.json.');
+  // check existing config
+  if (fs.existsSync(configPath)) {
+    err('This project already has agent-infra configuration.');
     err('Use /update-agent-infra in your AI TUI to update.');
     process.exitCode = 1;
     return;
@@ -113,7 +100,6 @@ async function cmdInit() {
     return;
   }
 
-  const modules = 'ai,github';
   const project = projectName;
   const replacements = { project, org: orgName };
 
@@ -170,20 +156,18 @@ async function cmdInit() {
   );
   ok('Installed .opencode/commands/update-agent-infra.md');
 
-  // generate .airc.json
-  const modulesArray = modules.split(',');
+  // generate .agents/.airc.json
   const config = {
     project: projectName,
     org: orgName,
     language,
-    templateSource: 'templates/',
     templateVersion: VERSION,
-    modules: modulesArray,
     files: structuredClone(defaults.files)
   };
 
-  fs.writeFileSync('.airc.json', JSON.stringify(config, null, 2) + '\n', 'utf8');
-  ok('Generated .airc.json');
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  ok(`Generated ${configPath}`);
 
   // done
   console.log('');

package/lib/paths.js

@@ -1,48 +1,9 @@
-import path from 'node:path';
 import fs from 'node:fs';
-import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 
-function resolveBundledTemplateDir() {
-  return fileURLToPath(new URL('../templates', import.meta.url));
-}
-
-function resolveCloneTemplateDir() {
-  return path.join(os.homedir(), '.agent-infra', 'templates');
-}
-
-function normalizePath(targetPath) {
-  try {
-    return fs.realpathSync(targetPath);
-  } catch {
-    return path.resolve(targetPath);
-  }
-}
-
 function resolveTemplateDir() {
-  // npm install mode: templates shipped alongside the package
-  const npmPath = resolveBundledTemplateDir();
-  if (fs.existsSync(npmPath)) {
-    return npmPath;
-  }
-
-  // clone install mode: ~/.agent-infra/templates
-  const clonePath = resolveCloneTemplateDir();
-  if (fs.existsSync(clonePath)) {
-    return clonePath;
-  }
-
-  return null;
-}
-
-function resolveInstallDir() {
-  return path.join(os.homedir(), '.agent-infra');
-}
-
-function isCloneInstall() {
-  const npmPath = resolveBundledTemplateDir();
-  const clonePath = resolveCloneTemplateDir();
-  return fs.existsSync(npmPath) && normalizePath(npmPath) === normalizePath(clonePath);
+  const bundledDir = fileURLToPath(new URL('../templates', import.meta.url));
+  return fs.existsSync(bundledDir) ? bundledDir : null;
 }
 
-export { resolveTemplateDir, resolveInstallDir, isCloneInstall };
+export { resolveTemplateDir };

package/lib/update.js

@@ -1,15 +1,29 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { execSync } from 'node:child_process';
 import { info, ok, err } from './log.js';
-import { resolveTemplateDir, resolveInstallDir, isCloneInstall } from './paths.js';
+import { resolveTemplateDir } from './paths.js';
 import { renderFile, copySkillDir } from './render.js';
 
 const defaults = JSON.parse(
   fs.readFileSync(new URL('./defaults.json', import.meta.url), 'utf8')
 );
 
+const CONFIG_DIR = '.agents';
+const CONFIG_PATH = path.join(CONFIG_DIR, '.airc.json');
+
 function syncFileRegistry(config) {
+  config.files ||= {};
+  const before = JSON.stringify({
+    files: {
+      managed: config.files.managed || [],
+      merged: config.files.merged || [],
+      ejected: config.files.ejected || []
+    }
+  });
+  config.files.managed = config.files.managed || [];
+  config.files.merged = config.files.merged || [];
+  config.files.ejected = config.files.ejected || [];
+
   const allExisting = [
     ...config.files.managed,
     ...config.files.merged,
@@ -30,7 +44,15 @@ function syncFileRegistry(config) {
     }
   }
 
-  return added;
+  const after = JSON.stringify({
+    files: {
+      managed: config.files.managed,
+      merged: config.files.merged,
+      ejected: config.files.ejected
+    }
+  });
+
+  return { added, changed: before !== after };
 }
 
 async function cmdUpdate() {
@@ -39,9 +61,9 @@ async function cmdUpdate() {
   console.log('  ==================================');
   console.log('');
 
-  // check .airc.json exists
-  if (!fs.existsSync('.airc.json')) {
-    err('No .airc.json found in current directory.');
+  // check config exists
+  if (!fs.existsSync(CONFIG_PATH)) {
+    err(`No ${CONFIG_PATH} found in current directory.`);
     err('Run "ai init" first to initialize the project.');
     process.exitCode = 1;
     return;
@@ -52,27 +74,12 @@ async function cmdUpdate() {
   if (!templateDir) {
     err('Template directory not found.');
     err('Install via npm: npm install -g @fitlab-ai/agent-infra');
-    err('Or via clone: curl -fsSL https://raw.githubusercontent.com/fitlab-ai/agent-infra/main/install.sh | sh');
     process.exitCode = 1;
     return;
   }
 
-  // auto-update: only for clone installs
-  if (isCloneInstall()) {
-    const installDir = resolveInstallDir();
-    if (fs.existsSync(path.join(installDir, '.git'))) {
-      info('Updating templates to latest version...');
-      try {
-        execSync('git pull --rebase --quiet', { cwd: installDir, stdio: 'pipe' });
-        ok('Templates updated.');
-      } catch {
-        err('Failed to update templates (network issue?). Using local version.');
-      }
-    }
-  }
-
   // read project config
-  const config = JSON.parse(fs.readFileSync('.airc.json', 'utf8'));
+  const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
   const { project, org, language } = config;
   const replacements = { project, org };
 
@@ -130,20 +137,24 @@ async function cmdUpdate() {
   ok('Updated .opencode/commands/update-agent-infra.md');
 
   // sync file registry
-  const added = syncFileRegistry(config);
+  const { added, changed } = syncFileRegistry(config);
   const hasNewEntries = added.managed.length > 0 || added.merged.length > 0;
 
-  if (hasNewEntries) {
+  if (changed) {
     console.log('');
-    info('New file entries synced to .airc.json:');
-    for (const entry of added.managed) {
-      ok(`  managed: ${entry}`);
-    }
-    for (const entry of added.merged) {
-      ok(`  merged: ${entry}`);
+    if (hasNewEntries) {
+      info(`New file entries synced to ${CONFIG_PATH}:`);
+      for (const entry of added.managed) {
+        ok(`  managed: ${entry}`);
+      }
+      for (const entry of added.merged) {
+        ok(`  merged: ${entry}`);
+      }
+    } else {
+      info(`File registry changed in ${CONFIG_PATH}.`);
     }
-    fs.writeFileSync('.airc.json', JSON.stringify(config, null, 2) + '\n', 'utf8');
-    ok('Updated .airc.json');
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', 'utf8');
+    ok(`Updated ${CONFIG_PATH}`);
   }
 
   // done

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -42,6 +42,7 @@
   ],
   "scripts": {
     "build": "node scripts/build-inline.js",
+    "prepare": "git config core.hooksPath .github/hooks || true",
     "test": "node scripts/build-inline.js --check && node --test tests/*.test.js",
     "prepublishOnly": "node scripts/build-inline.js --check && node --test tests/*.test.js"
   }