@fitlab-ai/agent-infra 0.5.7 → 0.5.9

package/README.md

@@ -236,6 +236,47 @@ agent-infra is intentionally simple: a bootstrap CLI creates the seed configurat
 └───────────────────────────────────────────────────────┘
 ```
 
+<a id="platform-support"></a>
+
+## Platform Support
+
+agent-infra runs on macOS and Linux. The CLI itself only needs Node.js (>=18); container-related features (`ai sandbox *`) additionally need Docker.
+
+### macOS
+
+- `ai init`, `ai sync`, etc.: works out of the box after `npm install -g @fitlab-ai/agent-infra` (or Homebrew).
+- `ai sandbox *`: requires Colima, OrbStack, or Docker Desktop. Colima is the default engine on macOS — when it is selected and the `colima` command is missing, agent-infra auto-installs and starts Colima via Homebrew on first run. To use OrbStack or Docker Desktop instead, set `sandbox.engine` in `.agents/.airc.json`.
+
+### Linux
+
+- `ai init`, `ai sync`, etc.: works out of the box after `npm install -g @fitlab-ai/agent-infra`.
+- `ai sandbox *`: requires Docker Engine on the host. Quick setup:
+
+  ```bash
+  # 1. Install Docker Engine — see https://docs.docker.com/engine/install/
+  # 2. Start the daemon and enable on boot
+  sudo systemctl enable --now docker
+  # 3. Skip 'sudo' for docker: add yourself to the docker group
+  sudo usermod -aG docker $USER && newgrp docker
+  ```
+
+  Validate with `docker info` — it should succeed without sudo.
+
+  GPG signing works when the host `gpg-agent` and signing key are available; if key sync fails, `ai sandbox create` falls back to a sanitized Git config so commits still work without host signing state.
+
+#### Known limitations on Linux
+
+These configurations are not actively tested in this release:
+
+- **Rootless Docker**: Track [#256](https://github.com/fitlab-ai/agent-infra/issues/256).
+- **Podman** instead of Docker: Track [#257](https://github.com/fitlab-ai/agent-infra/issues/257).
+- **SELinux-enforcing** hosts (Fedora / RHEL) may need manual mount labels: Track [#258](https://github.com/fitlab-ai/agent-infra/issues/258).
+- `ai sandbox vm` is a no-op on Linux. Linux uses native Docker directly with no VM to manage; use `ai sandbox create`, `ai sandbox exec`, `ai sandbox ls`, `ai sandbox rebuild`, `ai sandbox rm` directly.
+
+### Windows
+
+WSL2 support is tracked in [#184](https://github.com/fitlab-ai/agent-infra/issues/184).
+
 <a id="what-you-get"></a>
 
 ## What You Get
@@ -268,7 +309,7 @@ agent-infra ships with **a rich set of built-in AI skills**. They are organized
 
 | Skill | Description | Parameters | Recommended use case |
 |-------|-------------|------------|----------------------|
-| `create-task` | Create a task scaffold from a natural-language request. | `description` | Start a new feature, bug-fix, or improvement from scratch. |
+| `create-task` | Create a task scaffold from a natural-language request and cascade Issue creation through the platform rule when available. | `description` | Start a new feature, bug-fix, or improvement from scratch. |
 | `import-issue` | Import a GitHub Issue into the local task workspace. | `issue-number` | Convert an existing Issue into an actionable task folder. |
 | `analyze-task` | Produce a requirement analysis artifact for an existing task. | `task-id` | Capture scope, risks, and impacted files before designing. |
 | `plan-task` | Write the technical implementation plan with a review checkpoint. | `task-id` | Define the approach after analysis is complete. |
@@ -293,7 +334,6 @@ agent-infra ships with **a rich set of built-in AI skills**. They are organized
 
 | Skill | Description | Parameters | Recommended use case |
 |-------|-------------|------------|----------------------|
-| `create-issue` | Create a GitHub Issue from a task file. | `task-id` | Push a local task into GitHub tracking. |
 | `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. |
 
 <a id="code-quality"></a>
@@ -499,7 +539,7 @@ The simplest end-to-end delivery loop looks like this:
 
 ```text
 import-issue #42                    Import task from GitHub Issue
-(or: create-task "add dark mode")   Or create a task from a description
+(or: create-task "add dark mode")   Or create a task from a description; Issue creation cascades when the platform rule supports it
          |
          |  --> get task ID, e.g. T1
          v
@@ -545,7 +585,7 @@ The generated `.agents/.airc.json` file is the central contract between the boot
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.5.7",
+  "templateVersion": "v0.5.9",
   "templates": {
     "sources": [
       { "type": "local", "path": "~/private-templates" }

package/README.zh-CN.md

@@ -236,6 +236,47 @@ agent-infra 的结构刻意保持简单：引导 CLI 负责生成种子配置，
 └───────────────────────────────────────────────────────┘
 ```
 
+<a id="platform-support"></a>
+
+## 平台支持
+
+agent-infra 支持 macOS 和 Linux。CLI 本身只需要 Node.js (>=18)；容器相关功能（`ai sandbox *`）额外需要 Docker。
+
+### macOS
+
+- `ai init`、`ai sync` 等：执行 `npm install -g @fitlab-ai/agent-infra`（或 Homebrew 安装）后开箱即用。
+- `ai sandbox *`：需要 Colima、OrbStack 或 Docker Desktop。macOS 默认引擎是 Colima —— 当选用 Colima 且宿主机没有 `colima` 命令时，agent-infra 会在首次运行时通过 Homebrew 自动安装并启动。如需使用 OrbStack 或 Docker Desktop，请在 `.agents/.airc.json` 中设置 `sandbox.engine`。
+
+### Linux
+
+- `ai init`、`ai sync` 等：执行 `npm install -g @fitlab-ai/agent-infra` 后开箱即用。
+- `ai sandbox *`：需要宿主机已安装 Docker Engine。三步配置：
+
+  ```bash
+  # 1. 安装 Docker Engine —— 见 https://docs.docker.com/engine/install/
+  # 2. 启动 daemon 并设置开机自启
+  sudo systemctl enable --now docker
+  # 3. 让当前用户免 sudo 跑 docker：加入 docker 组
+  sudo usermod -aG docker $USER && newgrp docker
+  ```
+
+  验证：执行 `docker info` 应在不带 sudo 的情况下成功。
+
+  当宿主机 `gpg-agent` 和签名 key 可用时，GPG signing 可正常工作；如果 key 同步失败，`ai sandbox create` 会回退到清理后的 Git config，让提交仍可在没有宿主签名状态的情况下继续。
+
+#### Linux 已知限制
+
+下列场景在本期未做主动验证：
+
+- **Rootless Docker**：后续跟踪 [#256](https://github.com/fitlab-ai/agent-infra/issues/256)。
+- 用 **Podman** 替代 Docker：后续跟踪 [#257](https://github.com/fitlab-ai/agent-infra/issues/257)。
+- **SELinux enforcing** 宿主机（Fedora / RHEL）可能需要手动加挂载标签：后续跟踪 [#258](https://github.com/fitlab-ai/agent-infra/issues/258)。
+- `ai sandbox vm` 在 Linux 上是空操作。Linux 直接使用 native Docker，没有 VM 需要管理；请直接使用 `ai sandbox create`、`ai sandbox exec`、`ai sandbox ls`、`ai sandbox rebuild`、`ai sandbox rm`。
+
+### Windows
+
+WSL2 支持在 [#184](https://github.com/fitlab-ai/agent-infra/issues/184) 跟踪。
+
 <a id="what-you-get"></a>
 
 ## 安装效果
@@ -268,7 +309,7 @@ agent-infra 提供 **丰富的内置 AI skills**。它们按使用场景分组
 
 | Skill | 描述 | 参数 | 推荐场景 |
 |-------|------|------|---------|
-| `create-task` | 根据自然语言请求创建任务骨架。 | `description` | 从零开始记录新功能、缺陷或改进需求。 |
+| `create-task` | 根据自然语言请求创建任务骨架，并在平台规则可用时级联创建 Issue。 | `description` | 从零开始记录新功能、缺陷或改进需求。 |
 | `import-issue` | 将 GitHub Issue 导入本地任务工作区。 | `issue-number` | 把已有 Issue 转成可执行的任务目录。 |
 | `analyze-task` | 为已有任务输出需求分析产物。 | `task-id` | 在设计前明确范围、风险和受影响文件。 |
 | `plan-task` | 编写技术实施方案，并设置人工审查检查点。 | `task-id` | 分析完成后定义具体实现路径。 |
@@ -293,7 +334,6 @@ agent-infra 提供 **丰富的内置 AI skills**。它们按使用场景分组
 
 | Skill | 描述 | 参数 | 推荐场景 |
 |-------|------|------|---------|
-| `create-issue` | 根据任务文件创建 GitHub Issue。 | `task-id` | 需要把本地任务同步到 GitHub 跟踪时。 |
 | `create-pr` | 向推断出的目标分支或显式指定分支创建 Pull Request。 | `task-id`（可选）、`target-branch`（可选） | 变更准备合入时创建 PR；清空上下文后也可显式传入任务关联。 |
 
 <a id="code-quality"></a>
@@ -499,7 +539,7 @@ agent-infra 内置 **4 个预置工作流**。其中 3 个共享同一条分阶
 
 ```text
 import-issue #42                    从 GitHub Issue 导入任务
-(或: create-task "添加暗色模式")      或直接从描述创建任务
+(或: create-task "添加暗色模式")      或直接从描述创建任务；平台规则支持时会级联创建 Issue
          |
          |  --> 得到任务 ID，例如 T1
          v
@@ -545,7 +585,7 @@ import-issue #42                    从 GitHub Issue 导入任务
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.5.7",
+  "templateVersion": "v0.5.9",
   "templates": {
     "sources": [
       { "type": "local", "path": "~/private-templates" }

package/lib/defaults.json

@@ -36,22 +36,24 @@
       ".claude/commands/",
       ".claude/hooks/",
       ".gemini/commands/",
-      ".github/hooks/check-version-format.sh",
+      ".git-hooks/check-version-format.sh",
       ".github/scripts/",
       ".opencode/commands/"
     ],
     "merged": [
+      "**/post-release.*",
       "**/release.*",
       "**/test-integration.*",
       "**/test.*",
       "**/upgrade-dependency.*",
+      ".agents/skills/post-release/SKILL.*",
       ".agents/skills/release/SKILL.*",
       ".agents/skills/test-integration/SKILL.*",
       ".agents/skills/test/SKILL.*",
       ".agents/skills/upgrade-dependency/SKILL.*",
       ".claude/settings.json",
       ".gemini/settings.json",
-      ".github/hooks/pre-commit",
+      ".git-hooks/pre-commit",
       ".gitignore"
     ],
     "ejected": []

package/lib/init.js

@@ -12,6 +12,23 @@ const defaults = JSON.parse(
   fs.readFileSync(new URL('./defaults.json', import.meta.url), 'utf8')
 );
 
+function isPathOwnedByOtherPlatform(relativePath, platformType) {
+  const top = String(relativePath || '').replace(/\\/g, '/').replace(/^\.\//, '').split('/')[0];
+  if (!top.startsWith('.')) return false;
+
+  const candidate = top.slice(1);
+  if (!KNOWN_PLATFORMS.has(candidate)) return false;
+  return candidate !== platformType;
+}
+
+function buildDefaultFiles(platformType) {
+  return {
+    managed: (defaults.files.managed || []).filter((entry) => !isPathOwnedByOtherPlatform(entry, platformType)),
+    merged: (defaults.files.merged || []).filter((entry) => !isPathOwnedByOtherPlatform(entry, platformType)),
+    ejected: structuredClone(defaults.files.ejected || [])
+  };
+}
+
 function detectProjectName() {
   try {
     const url = execSync('git remote get-url origin', { stdio: ['pipe', 'pipe', 'pipe'] })
@@ -222,7 +239,7 @@ async function cmdInit() {
     templateVersion: VERSION,
     sandbox: structuredClone(defaults.sandbox),
     labels: structuredClone(defaults.labels),
-    files: structuredClone(defaults.files)
+    files: buildDefaultFiles(platformType)
   };
 
   if (sandboxEngine) {

package/lib/sandbox/commands/vm.js

@@ -15,7 +15,13 @@ import { runOk, runSafe } from '../shell.js';
 
 const USAGE = `Usage: ai sandbox vm <status|start|stop> [--cpu <n>] [--memory <n>]`;
 
-function ensureManagedVm(engine) {
+export function ensureManagedVm(engine) {
+  if (engine === 'native') {
+    throw new Error(
+      "Linux native Docker does not use a managed VM. Use 'ai sandbox create' directly."
+    );
+  }
+
   if (!isManagedEngine(engine)) {
     throw new Error(`VM management is unavailable for engine '${engineDisplayName(engine)}'.`);
   }

package/lib/sandbox/constants.js

@@ -88,6 +88,9 @@ export function parsePositiveIntegerOption(value, optionName) {
 }
 
 export function detectHostResources() {
+  // Resource hints are for engines that pre-allocate a managed VM. macOS uses
+  // sysctl for Colima defaults, while the generic fallback supports WSL2 or
+  // other direct callers that need conservative CPU and memory defaults.
   if (process.platform === 'darwin') {
     try {
       const hostCpu = Number(execFileSync('sysctl', ['-n', 'hw.ncpu'], { encoding: 'utf8' }).trim());

package/lib/sandbox/engine.js

@@ -8,8 +8,21 @@ export const ENGINES = Object.freeze({
   DOCKER_DESKTOP: 'docker-desktop'
 });
 
+export const ENGINE_DOCKER_CONTEXT = Object.freeze({
+  [ENGINES.COLIMA]: 'colima',
+  [ENGINES.ORBSTACK]: 'orbstack',
+  [ENGINES.DOCKER_DESKTOP]: 'desktop-linux'
+});
+
 const VALID_CONFIG_ENGINES = new Set(Object.values(ENGINES));
 
+function applyDockerContext(engine) {
+  const context = ENGINE_DOCKER_CONTEXT[engine];
+  if (context) {
+    process.env.DOCKER_CONTEXT = context;
+  }
+}
+
 export function validateSandboxEngine(engine) {
   if (engine === null || engine === undefined) {
     return null;
@@ -68,6 +81,8 @@ export async function ensureColima(
   onMessage,
   { runOkFn = runOk, runSafeFn = runSafe, runVerboseFn = runVerbose } = {}
 ) {
+  applyDockerContext(ENGINES.COLIMA);
+
   if (!runOkFn('which', ['colima'])) {
     onMessage?.('Installing colima + docker via Homebrew...');
     runVerboseFn('brew', ['install', 'colima', 'docker']);
@@ -88,6 +103,8 @@ export async function ensureOrbStack(
   onMessage,
   { runOkFn = runOk, runVerboseFn = runVerbose } = {}
 ) {
+  applyDockerContext(ENGINES.ORBSTACK);
+
   if (!runOkFn('which', ['orb'])) {
     onMessage?.('Installing OrbStack via Homebrew...');
     runVerboseFn('brew', ['install', '--cask', 'orbstack']);
@@ -108,11 +125,50 @@ export async function ensureDockerDesktop(
   onMessage,
   { runOkFn = runOk } = {}
 ) {
+  applyDockerContext(ENGINES.DOCKER_DESKTOP);
+
   if (!runOkFn('docker', ['info'])) {
     throw new Error('Docker Desktop is not running. Please start Docker Desktop manually.');
   }
 }
 
+export async function ensureNativeDocker(
+  _config,
+  _onMessage,
+  { runOkFn = runOk, runSafeFn = runSafe } = {}
+) {
+  if (!runOkFn('which', ['docker'])) {
+    throw new Error([
+      'Docker is not installed.',
+      'Install Docker Engine for your distribution: https://docs.docker.com/engine/install/',
+      'Then start the daemon with: sudo systemctl enable --now docker',
+      'If you want to run Docker without sudo, add your user to the docker group: sudo usermod -aG docker $USER'
+    ].join('\n'));
+  }
+
+  if (runOkFn('docker', ['info'])) {
+    return;
+  }
+
+  const serverVersion = runSafeFn('docker', ['version', '--format', '{{.Server.Version}}']);
+  if (!serverVersion) {
+    throw new Error([
+      'Docker daemon is not running or is unreachable.',
+      'Start it with: sudo systemctl start docker',
+      'Enable it on boot with: sudo systemctl enable docker',
+      'If you use rootless or remote Docker, verify DOCKER_HOST points at a reachable socket.',
+      'Then retry: ai sandbox create <branch>'
+    ].join('\n'));
+  }
+
+  throw new Error([
+    'Docker is installed, but the current user may lack permission to use the daemon.',
+    'Add your user to the docker group: sudo usermod -aG docker $USER',
+    'Open a new login shell or run: newgrp docker',
+    'For rootless Docker, make sure DOCKER_HOST points at the rootless daemon socket.'
+  ].join('\n'));
+}
+
 export async function ensureDocker(config, onMessage) {
   const engine = detectEngine(config);
 
@@ -132,9 +188,7 @@ export async function ensureDocker(config, onMessage) {
   }
 
   if (engine === 'native') {
-    if (!runOk('docker', ['info'])) {
-      throw new Error('Docker daemon is not running. Please start Docker first.');
-    }
+    await ensureNativeDocker(config, onMessage);
     return;
   }
 

package/lib/sandbox/runtimes/base.dockerfile

@@ -7,8 +7,15 @@ ENV TZ=Asia/Shanghai
 
 ARG HOST_UID=1000
 ARG HOST_GID=1000
-RUN (groupadd -g ${HOST_GID} devuser || true) && \
-    useradd -u ${HOST_UID} -g ${HOST_GID} -m -s /bin/bash devuser
+# Root host uid 0 collides with container root; -o lets devuser share uid 0
+# while keeping a real passwd entry that USER devuser can resolve.
+RUN if [ "${HOST_UID}" = "0" ]; then \
+        (groupadd -o -g ${HOST_GID} devuser || true) && \
+        useradd -o -u ${HOST_UID} -g ${HOST_GID} -m -s /bin/bash devuser; \
+    else \
+        (groupadd -g ${HOST_GID} devuser || true) && \
+        useradd -u ${HOST_UID} -g ${HOST_GID} -m -s /bin/bash devuser; \
+    fi
 
 RUN apt-get update && apt-get install -y \
     curl wget git vim file \

package/lib/sandbox/shell.js

@@ -60,10 +60,44 @@ export function runOk(cmd, args, opts = {}) {
   return result.status === 0;
 }
 
+export function restoreTerminal() {
+  if (!process.stdout.isTTY) {
+    return;
+  }
+
+  try {
+    process.stdout.write([
+      '\x1b[?1049l',
+      '\x1b[?25h',
+      '\x1b>',
+      '\x1b[?1000l',
+      '\x1b[?1002l',
+      '\x1b[?1003l',
+      '\x1b[?1006l'
+    ].join(''));
+  } catch {
+    // Best-effort cleanup only; preserve the original command result.
+  }
+
+  if (process.platform === 'win32') {
+    return;
+  }
+
+  try {
+    execFileSync('stty', ['sane'], { stdio: 'inherit' });
+  } catch {
+    // Some environments do not provide stty or reject sane; ANSI reset still helps.
+  }
+}
+
 export function runInteractive(cmd, args, opts = {}) {
   const resolved = resolveCommand(cmd);
-  const result = spawnSync(resolved, args, commandOptions(resolved, normalizeOptions(opts, 'inherit')));
-  return result.status ?? 1;
+  try {
+    const result = spawnSync(resolved, args, commandOptions(resolved, normalizeOptions(opts, 'inherit')));
+    return result.status ?? 1;
+  } finally {
+    restoreTerminal();
+  }
 }
 
 export function runVerbose(cmd, args, opts = {}) {

package/lib/update.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { info, ok, err } from './log.js';
 import { resolveTemplateDir } from './paths.js';
-import { renderFile, copySkillDir } from './render.js';
+import { renderFile, copySkillDir, KNOWN_PLATFORMS } from './render.js';
 
 const defaults = JSON.parse(
   fs.readFileSync(new URL('./defaults.json', import.meta.url), 'utf8')
@@ -11,7 +11,16 @@ const defaults = JSON.parse(
 const CONFIG_DIR = '.agents';
 const CONFIG_PATH = path.join(CONFIG_DIR, '.airc.json');
 
-function syncFileRegistry(config) {
+function isPathOwnedByOtherPlatform(relativePath, platformType) {
+  const top = String(relativePath || '').replace(/\\/g, '/').replace(/^\.\//, '').split('/')[0];
+  if (!top.startsWith('.')) return false;
+
+  const candidate = top.slice(1);
+  if (!KNOWN_PLATFORMS.has(candidate)) return false;
+  return candidate !== platformType;
+}
+
+function syncFileRegistry(config, platformType) {
   config.files ||= {};
   const before = JSON.stringify({
     files: {
@@ -32,12 +41,14 @@ function syncFileRegistry(config) {
   const added = { managed: [], merged: [] };
 
   for (const entry of defaults.files.managed) {
+    if (isPathOwnedByOtherPlatform(entry, platformType)) continue;
     if (!allExisting.includes(entry)) {
       config.files.managed.push(entry);
       added.managed.push(entry);
     }
   }
   for (const entry of defaults.files.merged) {
+    if (isPathOwnedByOtherPlatform(entry, platformType)) continue;
     if (!allExisting.includes(entry)) {
       config.files.merged.push(entry);
       added.merged.push(entry);
@@ -139,7 +150,7 @@ async function cmdUpdate() {
   ok('Updated .opencode/commands/update-agent-infra.md');
 
   // sync file registry
-  const { added, changed } = syncFileRegistry(config);
+  const { added, changed } = syncFileRegistry(config, platformType);
   const hasNewEntries = added.managed.length > 0 || added.merged.length > 0;
   const platformAdded = !config.platform;
   const sandboxAdded = !config.sandbox;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -47,8 +47,10 @@
   "scripts": {
     "build": "node scripts/build-inline.js",
     "demo:regen": "sh scripts/demo-regen.sh",
-    "prepare": "git config core.hooksPath .github/hooks || true",
-    "test": "node scripts/build-inline.js --check && node --test tests/cli/*.test.js tests/templates/*.test.js tests/core/*.test.js",
-    "prepublishOnly": "node scripts/build-inline.js --check && node --test tests/cli/*.test.js tests/templates/*.test.js tests/core/*.test.js"
+    "prepare": "git config core.hooksPath .git-hooks || true",
+    "test:smoke": "node scripts/build-inline.js --check && node --test tests/templates/*.test.js tests/core/airc.test.js tests/core/release.test.js tests/core/metadata-sync-workflow.test.js tests/core/pr-label-workflow.test.js tests/core/status-label-workflow.test.js tests/core/test-tier-coverage.test.js tests/cli/lib.test.js tests/cli/sync-templates.test.js tests/scripts/sync-templates-platform-gating.test.js",
+    "test:core": "node scripts/build-inline.js --check && node --test tests/templates/*.test.js tests/core/airc.test.js tests/core/release.test.js tests/core/metadata-sync-workflow.test.js tests/core/pr-label-workflow.test.js tests/core/status-label-workflow.test.js tests/core/test-tier-coverage.test.js tests/cli/lib.test.js tests/cli/sync-templates.test.js tests/scripts/sync-templates-platform-gating.test.js tests/cli/cli.test.js tests/cli/merge.test.js tests/cli/sandbox.test.js tests/core/custom-skills.test.js tests/core/custom-tuis.test.js tests/core/demo-regen.test.js tests/scripts/find-existing-task.test.js tests/scripts/platform-adapter-defaults.test.js",
+    "test": "node scripts/build-inline.js --check && node --test tests/cli/*.test.js tests/templates/*.test.js tests/core/*.test.js tests/scripts/*.test.js",
+    "prepublishOnly": "node scripts/build-inline.js --check && node --test tests/cli/*.test.js tests/templates/*.test.js tests/core/*.test.js tests/scripts/*.test.js"
   }
 }

package/templates/.agents/QUICKSTART.en.md

@@ -13,10 +13,10 @@ This guide walks you through using multiple AI coding assistants together on a p
 Enable the shared Git hooks path before relying on the template hook chain:
 
 ```bash
-git config core.hooksPath .github/hooks
+git config core.hooksPath .git-hooks
 ```
 
-This makes Git invoke the hooks synced into `.github/hooks/`, including `pre-commit` and `check-version-format.sh`.
+This makes Git invoke the hooks in the project repository's `.git-hooks/` directory, including `pre-commit` and `check-version-format.sh`.
 
 ## External Templates And Skills
 

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

@@ -13,10 +13,10 @@
 在依赖模板中的 Git hook 链路前，先启用共享 hooks 路径：
 
 ```bash
-git config core.hooksPath .github/hooks
+git config core.hooksPath .git-hooks
 ```
 
-这样 Git 才会调用同步到 `.github/hooks/` 下的 hook，包括 `pre-commit` 和 `check-version-format.sh`。
+这样 Git 才会调用项目仓库 `.git-hooks/` 目录下的 hook，包括 `pre-commit` 和 `check-version-format.sh`。
 
 ## 外部模板与 Skill
 

package/templates/.agents/README.en.md

@@ -108,7 +108,7 @@ This project uses the following collaboration label prefixes, each with a define
 | `status:` | Yes | — | PRs already have their own state flow (Open / Draft / Merged / Closed); Issues use `status:` labels for project tracking states |
 | `in:` | Yes | Yes | Both Issues and PRs can be filtered by module |
 
-The default GitHub setup initializes these labels with the `/init-labels` command.
+Run the `/init-labels` command to initialize these labels via the platform adapter.
 
 ## Private Platform Extensions
 

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

@@ -108,7 +108,7 @@
 | `status:` | Yes | — | PR 有自身状态流转（Open / Draft / Merged / Closed）；Issue 使用 `status:` label 标记等待反馈、已确认等项目管理状态 |
 | `in:` | Yes | Yes | Issue 和 PR 均可按模块筛选 |
 
-默认 GitHub 配置下，可使用 `/init-labels` 命令一次性创建标准 labels。
+使用 `/init-labels` 命令可通过平台适配器一次性创建标准 labels。
 
 ## 私有平台扩展
 

package/templates/.agents/rules/create-issue.en.md

@@ -0,0 +1,5 @@
+# Issue Creation
+
+This code platform does not provide an Issue creation rule.
+
+`create-task` skips the cascade Issue creation step on this platform; the local `task.md` remains a valid artifact. If you later want to bind the task to an Issue, manually write `issue_number` into `task.md` and the subsequent skills (`commit` / `refine-task` / `complete-task`, etc.) will pick up Issue metadata syncing through the existing cascade rules.