@fitlab-ai/agent-infra 0.4.0 → 0.4.2

package/README.md

@@ -1,15 +1,25 @@
-# Agent Infra
+<p align="center">
+  <img src="./assets/logo.svg" alt="Agent Infra Logo" width="200">
+</p>
 
-[![npm version](https://img.shields.io/npm/v/@fitlab-ai/agent-infra)](https://www.npmjs.com/package/@fitlab-ai/agent-infra)
-[![npm downloads](https://img.shields.io/npm/dm/@fitlab-ai/agent-infra)](https://www.npmjs.com/package/@fitlab-ai/agent-infra)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](License.txt)
-[![Node.js >= 18](https://img.shields.io/badge/Node.js-%3E%3D18-brightgreen?logo=node.js)](https://nodejs.org/)
-[![GitHub release](https://img.shields.io/github/v/release/fitlab-ai/agent-infra)](https://github.com/fitlab-ai/agent-infra/releases)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+<h1 align="center">Agent Infra</h1>
 
-The missing collaboration layer for AI coding agents — unified skills and workflows for Claude Code, Codex, Gemini CLI, and OpenCode.
+<p align="center">
+  The missing collaboration layer for AI coding agents — unified skills and workflows for Claude Code, Codex, Gemini CLI, and OpenCode.
+</p>
 
-**Semi-automated programming, powered by AI agents.** Define a requirement, let AI handle analysis, planning, coding, review, and delivery — you only step in when it matters.
+<p align="center">
+  <strong>Semi-automated programming, powered by AI agents.</strong> Define a requirement, let AI handle analysis, planning, coding, review, and delivery — you only step in when it matters.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@fitlab-ai/agent-infra"><img src="https://img.shields.io/npm/v/@fitlab-ai/agent-infra" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@fitlab-ai/agent-infra"><img src="https://img.shields.io/npm/dm/@fitlab-ai/agent-infra" alt="npm downloads"></a>
+  <a href="License.txt"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D18-brightgreen?logo=node.js" alt="Node.js >= 18"></a>
+  <a href="https://github.com/fitlab-ai/agent-infra/releases"><img src="https://img.shields.io/github/v/release/fitlab-ai/agent-infra" alt="GitHub release"></a>
+  <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
+</p>
 
 [中文版](README.zh-CN.md)
 
@@ -74,7 +84,7 @@ Just fix it at the application layer in LoginService.
 
 ```bash
 /commit
-/create-pr
+/create-pr TASK-20260319-100000
 /complete-task TASK-20260319-100000
 ```
 
@@ -264,8 +274,8 @@ agent-infra ships with **28 built-in AI skills**. They are organized by use case
 |-------|-------------|------------|----------------------|
 | `create-issue` | Create a GitHub Issue from a task file. | `task-id` | Push a local task into GitHub tracking. |
 | `sync-issue` | Post task progress updates back to the linked GitHub Issue. | `task-id` or `issue-number` | Keep stakeholders updated as the task evolves. |
-| `create-pr` | Open a Pull Request to an inferred or explicit target branch. | `target-branch` (optional) | Publish reviewed changes for merge. |
-| `sync-pr` | Sync task progress and review metadata into the Pull Request. | `task-id` | Keep PR metadata aligned with the local task record. |
+| `create-pr` | Open a Pull Request to an inferred or explicit target branch. | `task-id` (optional), `target-branch` (optional) | Publish reviewed changes for merge, with optional explicit task linkage after a fresh session. |
+| `sync-pr` | Sync task progress and review metadata into the Pull Request. | `task-id` or `pr-number` | Keep PR metadata aligned with the local task record from either task or PR entrypoints. |
 
 <a id="code-quality"></a>
 
@@ -380,8 +390,7 @@ The generated `.agents/.airc.json` file is the central contract between the boot
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateSource": "templates/",
-  "templateVersion": "v0.4.0",
+  "templateVersion": "v0.4.2",
   "files": {
     "managed": [
       ".agents/workspace/README.md",
@@ -409,7 +418,6 @@ The generated `.agents/.airc.json` file is the central contract between the boot
 | `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. |
 | `files` | Per-path update strategy configuration for managed, merged, and ejected files. |
 

package/README.zh-CN.md

@@ -1,15 +1,25 @@
-# Agent Infra
+<p align="center">
+  <img src="./assets/logo.svg" alt="Agent Infra 标志" width="200">
+</p>
 
-[![npm version](https://img.shields.io/npm/v/@fitlab-ai/agent-infra)](https://www.npmjs.com/package/@fitlab-ai/agent-infra)
-[![npm downloads](https://img.shields.io/npm/dm/@fitlab-ai/agent-infra)](https://www.npmjs.com/package/@fitlab-ai/agent-infra)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](License.txt)
-[![Node.js >= 18](https://img.shields.io/badge/Node.js-%3E%3D18-brightgreen?logo=node.js)](https://nodejs.org/)
-[![GitHub release](https://img.shields.io/github/v/release/fitlab-ai/agent-infra)](https://github.com/fitlab-ai/agent-infra/releases)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+<h1 align="center">Agent Infra</h1>
 
-AI 编程代理之间缺失的协作层 —— 为 Claude Code、Codex、Gemini CLI、OpenCode 提供统一的 skills 和工作流。
+<p align="center">
+  AI 编程代理之间缺失的协作层 —— 为 Claude Code、Codex、Gemini CLI、OpenCode 提供统一的 skills 和工作流。
+</p>
 
-**AI Agent 半自动化编程神器。** 定义需求，让 AI 完成分析、方案设计、编码、审查和交付 —— 你只需在关键节点介入。
+<p align="center">
+  <strong>AI Agent 半自动化编程神器。</strong> 定义需求，让 AI 完成分析、方案设计、编码、审查和交付 —— 你只需在关键节点介入。
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@fitlab-ai/agent-infra"><img src="https://img.shields.io/npm/v/@fitlab-ai/agent-infra" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@fitlab-ai/agent-infra"><img src="https://img.shields.io/npm/dm/@fitlab-ai/agent-infra" alt="npm downloads"></a>
+  <a href="License.txt"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D18-brightgreen?logo=node.js" alt="Node.js >= 18"></a>
+  <a href="https://github.com/fitlab-ai/agent-infra/releases"><img src="https://img.shields.io/github/v/release/fitlab-ai/agent-infra" alt="GitHub release"></a>
+  <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
+</p>
 
 [English](README.md)
 
@@ -74,7 +84,7 @@ agent-infra 的目标就是把这层协作面标准化。它为所有支持的 A
 
 ```bash
 /commit
-/create-pr
+/create-pr TASK-20260319-100000
 /complete-task TASK-20260319-100000
 ```
 
@@ -264,8 +274,8 @@ agent-infra 内置 **28 个 AI skills**。它们按使用场景分组，但共
 |-------|------|------|---------|
 | `create-issue` | 根据任务文件创建 GitHub Issue。 | `task-id` | 需要把本地任务同步到 GitHub 跟踪时。 |
 | `sync-issue` | 将任务进度同步回关联的 GitHub Issue。 | `task-id` 或 `issue-number` | 任务推进过程中持续同步状态。 |
-| `create-pr` | 向推断出的目标分支或显式指定分支创建 Pull Request。 | `target-branch`（可选） | 变更准备合入时创建 PR。 |
-| `sync-pr` | 将任务进度和审查元数据同步到 Pull Request。 | `task-id` | 让 PR 元数据与本地任务记录保持一致。 |
+| `create-pr` | 向推断出的目标分支或显式指定分支创建 Pull Request。 | `task-id`（可选）、`target-branch`（可选） | 变更准备合入时创建 PR；清空上下文后也可显式传入任务关联。 |
+| `sync-pr` | 将任务进度和审查元数据同步到 Pull Request。 | `task-id` 或 `pr-number` | 允许从任务入口或 PR 入口同步，让 PR 元数据与本地任务记录保持一致。 |
 
 <a id="code-quality"></a>
 
@@ -380,8 +390,7 @@ import-issue #42                    从 GitHub Issue 导入任务
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateSource": "templates/",
-  "templateVersion": "v0.4.0",
+  "templateVersion": "v0.4.2",
   "files": {
     "managed": [
       ".agents/workspace/README.md",
@@ -409,7 +418,6 @@ import-issue #42                    从 GitHub Issue 导入任务
 | `project` | 用于渲染命令、路径和模板内容的项目名。 |
 | `org` | 生成元数据和链接时使用的 GitHub 组织或拥有者。 |
 | `language` | 渲染模板时采用的项目主语言或区域设置。 |
-| `templateSource` | 本地模板根目录。 |
 | `templateVersion` | 当前安装的模板版本，用于升级和差异追踪。 |
 | `files` | 针对具体路径配置 `managed`、`merged`、`ejected` 三类更新策略。 |
 

package/lib/defaults.json

@@ -1,6 +1,8 @@
 {
   "files": {
     "managed": [
+      ".agents/QUICKSTART.md",
+      ".agents/README.md",
       ".agents/skills/",
       ".agents/templates/",
       ".agents/workflows/",
@@ -8,6 +10,7 @@
       ".claude/commands/",
       ".claude/hooks/",
       ".gemini/commands/",
+      ".github/hooks/check-version-format.sh",
       ".opencode/commands/"
     ],
     "merged": [
@@ -15,21 +18,14 @@
       "**/test-integration.*",
       "**/test.*",
       "**/upgrade-dependency.*",
-      ".agents/QUICKSTART.md",
-      ".agents/README.md",
       ".agents/skills/release/SKILL.*",
       ".agents/skills/test-integration/SKILL.*",
       ".agents/skills/test/SKILL.*",
       ".agents/skills/upgrade-dependency/SKILL.*",
-      ".claude/CLAUDE.md",
-      ".claude/project-rules.md",
       ".claude/settings.json",
-      ".codex/README.md",
       ".gemini/settings.json",
-      ".gitignore",
-      ".opencode/COMMAND_STYLE_GUIDE.md",
-      ".opencode/README.md",
-      "AGENTS.md"
+      ".github/hooks/pre-commit",
+      ".gitignore"
     ],
     "ejected": []
   }

package/lib/init.js

@@ -57,11 +57,7 @@ async function cmdInit() {
   const configPath = path.join('.agents', '.airc.json');
 
   // check existing config
-  if (
-    fs.existsSync(configPath) ||
-    fs.existsSync('.airc.json') ||
-    fs.existsSync(path.join('.agent-infra', 'config.json'))
-  ) {
+  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;
@@ -165,7 +161,6 @@ async function cmdInit() {
     project: projectName,
     org: orgName,
     language,
-    templateSource: 'templates/',
     templateVersion: VERSION,
     files: structuredClone(defaults.files)
   };

package/lib/update.js

@@ -10,52 +10,6 @@ const defaults = JSON.parse(
 
 const CONFIG_DIR = '.agents';
 const CONFIG_PATH = path.join(CONFIG_DIR, '.airc.json');
-const LEGACY_CONFIG_PATHS = ['.airc.json', path.join('.agent-infra', 'config.json')];
-const WORKSPACE_PATH = path.join(CONFIG_DIR, 'workspace');
-const LEGACY_WORKSPACE_PATHS = ['.agent-workspace', path.join('.agent-infra', 'workspace')];
-
-function migrateLegacyPaths() {
-  let migratedConfig = false;
-  let migratedWorkspace = false;
-  let configFrom = null;
-  let workspaceFrom = null;
-
-  if (!fs.existsSync(CONFIG_PATH)) {
-    for (const legacyPath of LEGACY_CONFIG_PATHS) {
-      if (!fs.existsSync(legacyPath)) {
-        continue;
-      }
-      fs.mkdirSync(CONFIG_DIR, { recursive: true });
-      fs.renameSync(legacyPath, CONFIG_PATH);
-      migratedConfig = true;
-      configFrom = legacyPath;
-      break;
-    }
-  }
-
-  if (!fs.existsSync(WORKSPACE_PATH)) {
-    for (const legacyPath of LEGACY_WORKSPACE_PATHS) {
-      if (!fs.existsSync(legacyPath)) {
-        continue;
-      }
-      fs.mkdirSync(CONFIG_DIR, { recursive: true });
-      fs.renameSync(legacyPath, WORKSPACE_PATH);
-      migratedWorkspace = true;
-      workspaceFrom = legacyPath;
-      break;
-    }
-  }
-
-  try {
-    if (fs.existsSync('.agent-infra') && fs.readdirSync('.agent-infra').length === 0) {
-      fs.rmdirSync('.agent-infra');
-    }
-  } catch {
-    // Ignore cleanup failures for partially migrated directories.
-  }
-
-  return { migratedConfig, migratedWorkspace, configFrom, workspaceFrom };
-}
 
 function syncFileRegistry(config) {
   config.files ||= {};
@@ -107,15 +61,6 @@ async function cmdUpdate() {
   console.log('  ==================================');
   console.log('');
 
-  const { migratedConfig, migratedWorkspace, configFrom, workspaceFrom } = migrateLegacyPaths();
-
-  if (migratedConfig) {
-    ok(`Migrated ${configFrom} -> ${CONFIG_PATH}`);
-  }
-  if (migratedWorkspace) {
-    ok(`Migrated ${workspaceFrom} -> ${WORKSPACE_PATH}`);
-  }
-
   // check config exists
   if (!fs.existsSync(CONFIG_PATH)) {
     err(`No ${CONFIG_PATH} found in current directory.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",

package/templates/.agents/QUICKSTART.md

@@ -4,10 +4,20 @@ This guide walks you through using multiple AI coding assistants together on a p
 
 ## Prerequisites
 
-- At least one AI coding tool installed (Claude Code, Codex CLI, Gemini CLI, or Cursor)
+- At least one AI coding tool installed (Claude Code, Codex CLI, Gemini CLI, or OpenCode)
 - A project with `.agents/` directory set up (this project)
 - Familiarity with your project's codebase
 
+## Git Hook Setup
+
+Enable the shared Git hooks path before relying on the template hook chain:
+
+```bash
+git config core.hooksPath .github/hooks
+```
+
+This makes Git invoke the hooks synced into `.github/hooks/`, including `pre-commit` and `check-version-format.sh`.
+
 ## Creating Your First Task
 
 1. Copy the task template to the active workspace:
@@ -22,7 +32,7 @@ cp .agents/templates/task.md .agents/workspace/active/task-001.md
 id: task-001
 type: feature          # feature | bugfix | refactor | docs | review
 status: open           # open | in-progress | review | blocked | completed
-assigned_to: claude    # claude | codex | gemini | cursor | human
+assigned_to: claude    # claude | codex | gemini | opencode | human
 ```
 
 3. Describe the task in the body of the document.
@@ -53,7 +63,7 @@ gemini
 #  create a technical design. Define interfaces and outline the approach."
 ```
 
-### Phase 3: Implementation (Recommended: Codex CLI or Cursor)
+### Phase 3: Implementation (Recommended: Codex CLI or OpenCode)
 
 ```bash
 # Switch to Codex CLI for implementation
@@ -81,7 +91,7 @@ claude
 ### Bug Fix
 
 1. **Reproduce & Analyze** (Claude Code): Identify the root cause.
-2. **Implement Fix** (Codex CLI / Cursor): Write the fix and tests.
+2. **Implement Fix** (Codex CLI / OpenCode): Write the fix and tests.
 3. **Review** (Claude Code): Verify the fix is correct and complete.
 4. **Commit**: Create PR with bug fix description.
 
@@ -90,7 +100,7 @@ claude
 cp .agents/templates/task.md .agents/workspace/active/bugfix-001.md
 # Edit the task, then:
 # 1. Use Claude Code to analyze
-# 2. Use Codex/Cursor to fix
+# 2. Use Codex/OpenCode to fix
 # 3. Use Claude Code to review
 ```
 
@@ -109,7 +119,7 @@ cp .agents/templates/review-report.md .agents/workspace/active/review-pr-42.md
 
 1. **Analyze Scope** (Claude Code / Gemini CLI): Map all affected areas.
 2. **Design** (Claude Code): Plan the refactoring approach.
-3. **Implement** (Codex CLI / Cursor): Execute the refactoring.
+3. **Implement** (Codex CLI / OpenCode): Execute the refactoring.
 4. **Verify** (Claude Code): Ensure no regressions, run tests.
 
 ```bash
@@ -146,7 +156,7 @@ Even if you're switching between AIs quickly, a brief handoff note saves time an
 ### 3. Use the Right Tool for the Job
 
 - Complex analysis? Use Claude Code or Gemini CLI.
-- Straightforward implementation? Use Codex CLI or Cursor.
+- Straightforward implementation? Use Codex CLI or OpenCode.
 - Large file review? Use Gemini CLI.
 
 ### 4. Keep Tasks Small

package/templates/.agents/QUICKSTART.zh-CN.md

@@ -4,16 +4,26 @@
 
 ## 前提条件
 
-- 至少安装一个 AI 编程工具（Claude Code、Codex CLI、Gemini CLI 或 Cursor）
+- 至少安装一个 AI 编程工具（Claude Code、Codex CLI、Gemini CLI 或 OpenCode）
 - 项目已设置 `.agents/` 目录（本项目已就绪）
 - 熟悉你的项目代码库
 
+## Git Hook 配置
+
+在依赖模板中的 Git hook 链路前，先启用共享 hooks 路径：
+
+```bash
+git config core.hooksPath .github/hooks
+```
+
+这样 Git 才会调用同步到 `.github/hooks/` 下的 hook，包括 `pre-commit` 和 `check-version-format.sh`。
+
 ## 创建第一个任务
 
 1. 将任务模板复制到活跃工作区：
 
 ```bash
-cp .agents/templates/task.zh-CN.md .agents/workspace/active/task-001.md
+cp .agents/templates/task.md .agents/workspace/active/task-001.md
 ```
 
 2. 填写任务元数据：
@@ -22,7 +32,7 @@ cp .agents/templates/task.zh-CN.md .agents/workspace/active/task-001.md
 id: task-001
 type: feature          # feature | bugfix | refactor | docs | review
 status: open           # open | in-progress | review | blocked | completed
-assigned_to: claude    # claude | codex | gemini | cursor | human
+assigned_to: claude    # claude | codex | gemini | opencode | human
 ```
 
 3. 在文档正文中描述任务。
@@ -53,7 +63,7 @@ gemini
 #  创建技术设计方案。定义接口并概述实现思路。"
 ```
 
-### 阶段 3：实现（推荐：Codex CLI 或 Cursor）
+### 阶段 3：实现（推荐：Codex CLI 或 OpenCode）
 
 ```bash
 # 切换到 Codex CLI 进行实现
@@ -81,16 +91,16 @@ claude
 ### 缺陷修复
 
 1. **复现和分析**（Claude Code）：识别根本原因。
-2. **实现修复**（Codex CLI / Cursor）：编写修复代码和测试。
+2. **实现修复**（Codex CLI / OpenCode）：编写修复代码和测试。
 3. **审查**（Claude Code）：验证修复是否正确和完整。
 4. **提交**：创建包含缺陷修复描述的 PR。
 
 ```bash
 # 快速缺陷修复工作流
-cp .agents/templates/task.zh-CN.md .agents/workspace/active/bugfix-001.md
+cp .agents/templates/task.md .agents/workspace/active/bugfix-001.md
 # 编辑任务，然后：
 # 1. 使用 Claude Code 分析
-# 2. 使用 Codex/Cursor 修复
+# 2. 使用 Codex/OpenCode 修复
 # 3. 使用 Claude Code 审查
 ```
 
@@ -101,7 +111,7 @@ cp .agents/templates/task.zh-CN.md .agents/workspace/active/bugfix-001.md
 3. **报告**：从模板生成审查报告。
 
 ```bash
-cp .agents/templates/review-report.zh-CN.md .agents/workspace/active/review-pr-42.md
+cp .agents/templates/review-report.md .agents/workspace/active/review-pr-42.md
 # 使用 Claude Code 填写审查内容
 ```
 
@@ -109,12 +119,12 @@ cp .agents/templates/review-report.zh-CN.md .agents/workspace/active/review-pr-4
 
 1. **分析范围**（Claude Code / Gemini CLI）：映射所有受影响区域。
 2. **设计**（Claude Code）：规划重构方案。
-3. **实现**（Codex CLI / Cursor）：执行重构。
+3. **实现**（Codex CLI / OpenCode）：执行重构。
 4. **验证**（Claude Code）：确保没有回归问题，运行测试。
 
 ```bash
-cp .agents/templates/task.zh-CN.md .agents/workspace/active/refactor-001.md
-# 按照 .agents/workflows/refactoring.zh-CN.yaml 中的重构工作流执行
+cp .agents/templates/task.md .agents/workspace/active/refactor-001.md
+# 按照 .agents/workflows/refactoring.yaml 中的重构工作流执行
 ```
 
 ## 创建交接文档
@@ -122,7 +132,7 @@ cp .agents/templates/task.zh-CN.md .agents/workspace/active/refactor-001.md
 在 AI 工具之间切换时，创建交接文档：
 
 ```bash
-cp .agents/templates/handoff.zh-CN.md .agents/workspace/active/handoff-task-001-phase2.md
+cp .agents/templates/handoff.md .agents/workspace/active/handoff-task-001-phase2.md
 ```
 
 填写：
@@ -146,7 +156,7 @@ cp .agents/templates/handoff.zh-CN.md .agents/workspace/active/handoff-task-001-
 ### 3. 选择合适的工具
 
 - 复杂分析？使用 Claude Code 或 Gemini CLI。
-- 直接的实现工作？使用 Codex CLI 或 Cursor。
+- 直接的实现工作？使用 Codex CLI 或 OpenCode。
 - 大文件审查？使用 Gemini CLI。
 
 ### 4. 保持任务小而精

package/templates/.agents/README.md

@@ -1,6 +1,6 @@
 # Multi-AI Collaboration Guide
 
-This project supports collaboration across multiple AI coding assistants, including Claude Code, OpenAI Codex CLI, Gemini CLI, Cursor, and others.
+This project supports collaboration across multiple AI coding assistants, including Claude Code, OpenAI Codex CLI, Gemini CLI, OpenCode, and others.
 
 ## Dual-Config Architecture
 
@@ -8,10 +8,10 @@ Different AI tools read configuration from different locations:
 
 | AI Tool | Primary Config | Fallback |
 |---------|---------------|----------|
-| Claude Code | `.claude/` (CLAUDE.md, commands/, settings/) | - |
+| Claude Code | `.claude/` (CLAUDE.md, commands/, settings.json) | - |
 | OpenAI Codex CLI | `AGENTS.md` | - |
 | Gemini CLI | `AGENTS.md` | - |
-| Cursor | `.cursorrules` or `.cursor/rules/` | `AGENTS.md` |
+| OpenCode | `AGENTS.md` | - |
 | Other AI Tools | `AGENTS.md` | Project README |
 
 - **Claude Code** uses its dedicated `.claude/` directory for project instructions, slash commands, and settings.
@@ -23,10 +23,8 @@ This dual-config approach ensures every AI tool receives appropriate project con
 
 ```
 .agents/                        # AI collaboration config (version-controlled)
-  README.md                     # This file (English)
-  README.zh-CN.md               # Chinese version
+  README.md                     # Collaboration guide
   QUICKSTART.md                 # Quick start guide
-  QUICKSTART.zh-CN.md           # Quick start guide (Chinese)
   templates/                    # Task and document templates
     task.md                     # Task template
     handoff.md                  # AI-to-AI handoff template
@@ -36,28 +34,28 @@ This dual-config approach ensures every AI tool receives appropriate project con
     bug-fix.yaml                # Bug fix workflow
     code-review.yaml            # Code review workflow
     refactoring.yaml            # Refactoring workflow
-
-.agents/workspace/         # Runtime workspace (git-ignored)
-  active/                       # Currently active tasks
-  blocked/                      # Blocked tasks
-  completed/                    # Completed tasks
-  logs/                         # Collaboration logs
+  workspace/                    # Runtime workspace (git-ignored)
+    active/                     # Currently active tasks
+    blocked/                    # Blocked tasks
+    completed/                  # Completed tasks
+    logs/                       # Collaboration logs
 
 .claude/                        # Claude Code specific config
   CLAUDE.md                     # Project instructions for Claude
   commands/                     # Slash commands
-  settings/                     # Claude settings
+  settings.json                 # Claude settings
 ```
 
 ## Collaboration Model
 
 The multi-AI collaboration follows a structured workflow:
 
-```
-1. Analysis    -->  2. Design    -->  3. Implementation
-                                            |
-6. Commit  <--  5. Fix Issues  <--  4. Review
-```
+1. Analysis
+2. Design
+3. Implementation
+4. Review
+5. Fix Issues
+6. Commit
 
 ### Phase Details
 
@@ -76,21 +74,21 @@ When one AI completes a phase, it produces a **handoff document** (see `.agents/
 
 Each AI tool has different strengths. Use them accordingly:
 
-| Capability | Claude Code | Codex CLI | Gemini CLI | Cursor |
-|-----------|-------------|-----------|------------|--------|
+| Capability | Claude Code | Codex CLI | Gemini CLI | OpenCode |
+|-----------|-------------|-----------|------------|----------|
 | Codebase analysis | Excellent | Good | Excellent | Good |
-| Code review | Excellent | Good | Good | Fair |
+| Code review | Excellent | Good | Good | Good |
 | Implementation | Good | Excellent | Good | Excellent |
-| Large context | Good | Fair | Excellent | Good |
-| Refactoring | Good | Good | Good | Excellent |
-| Documentation | Excellent | Good | Good | Fair |
+| Large context | Good | Fair | Excellent | Fair |
+| Refactoring | Good | Good | Good | Good |
+| Documentation | Excellent | Good | Good | Good |
 
 ### Recommended Assignments
 
 - **Analysis & Review** - Claude Code (strong reasoning, thorough exploration)
-- **Implementation** - Codex CLI or Cursor (fast code generation, inline editing)
+- **Implementation** - Codex CLI or OpenCode (fast code generation, command-driven editing)
 - **Large Context Tasks** - Gemini CLI (large context window for cross-file analysis)
-- **Quick Edits** - Cursor (IDE integration, fast iteration)
+- **Command-Driven Iteration** - OpenCode (workflow-friendly TUI execution)
 
 ## Quick Start
 
@@ -118,10 +116,18 @@ When writing or updating `.agents/skills/*/SKILL.md` files and their templates,
 
 1. Use consecutive integers for top-level steps: `1.`, `2.`, `3.`.
 2. Use nested numbering only for child actions that belong to a parent step: `1.1`, `1.2`, `2.1`.
-3. Use `a`, `b`, and `c` markers for branches, conditions, or alternative paths within the same step.
+3. Use `a`, `b`, and `c` markers for branches, conditions, or alternative paths within the same step; keep them scoped to child options rather than standalone decision tracks or output templates.
 4. Do not use intermediate numbers such as `1.5` or `2.5`; if a new standalone step is needed, renumber the following top-level steps.
 5. When renumbering, update every in-document step reference so the instructions remain accurate.
 6. Extract long bash scripts into a sibling `scripts/` directory; the SKILL.md should contain only a single-line invocation (e.g., `bash .agents/skills/<skill>/scripts/<script>.sh`) and a brief summary of the script's responsibilities.
+7. In SKILL.md files and their `reference/` templates, use “Scenario” naming for standalone condition branches, decision paths, or output templates (for example, “Scenario A”).
+
+### SKILL.md Size Control
+
+- Keep the SKILL.md body within about 500 tokens (roughly 80 lines / 2KB).
+- Move content beyond that threshold into a sibling `reference/` directory.
+- Use explicit navigation in the skeleton, such as: `Read reference/xxx.md before executing this step.`
+- Keep scripts in `scripts/` and execute them instead of inlining long bash blocks.
 
 ## FAQ