@fitlab-ai/agent-infra 0.5.8 → 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.8",
+  "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.8",
+  "templateVersion": "v0.5.9",
   "templates": {
     "sources": [
       { "type": "local", "path": "~/private-templates" }

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

@@ -132,6 +132,43 @@ export async function ensureDockerDesktop(
   }
 }
 
+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);
 
@@ -151,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.5.8",
+  "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",
@@ -48,6 +48,8 @@
     "build": "node scripts/build-inline.js",
     "demo:regen": "sh scripts/demo-regen.sh",
     "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/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.

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

@@ -0,0 +1,178 @@
+# Issue Creation
+
+After `create-task` writes the local `task.md`, follow this rule to cascade Issue creation. This rule is referenced internally by `create-task` SKILL.md only; do not invoke it standalone.
+
+## Boundary
+
+- Issue title and body must come from `task.md` only
+- Do not read `analysis.md`, `plan.md`, `implementation.md`, or any review artifact
+- Persistent outputs are limited to the remote Issue and the `issue_number` written back to `task.md`
+- If Issue creation fails, do not roll back `task.md`; the current task remains valid for the workflow, and the user can later manually fill `issue_number` so other skills' cascade sync takes over
+
+## Steps
+
+### 1. Verify Prerequisites
+
+- `.agents/workspace/active/{task-id}/task.md` must exist
+- Read `.agents/rules/issue-pr-commands.md` first and run its authentication and platform detection commands to confirm `gh auth status` and the current repository are usable
+- Read `.agents/rules/issue-sync.md` first and complete `upstream_repo`, `has_triage`, and `has_push` detection; reuse these variables for every later `gh issue` and repo-level `gh api` call
+- If `task.md` already has a non-empty, non-`N/A` `issue_number`, halt the cascade immediately: return "Task already linked to Issue #{n}, skipping creation" to `create-task` and let it decide how to continue
+
+### 2. Extract Task Information
+
+Pull the following from `task.md`:
+
+- Task title (the first `# ` heading, stripped of `任务：` / `Task:` prefixes)
+- The `## Description` / `## 描述` section
+- The `## Requirements` / `## 需求` section
+- frontmatter fields `type` and (optionally) `milestone`
+
+Build the Issue title:
+
+| task.md `type` | Conventional Commits type |
+|---|---|
+| `feature` | `feat` |
+| `bugfix`, `bug` | `fix` |
+| `refactor`, `refactoring` | `refactor` |
+| `docs`, `documentation` | `docs` |
+| `chore`, `task`, others | `chore` |
+
+Scope inference: read known module names from `.agents/.airc.json`'s `labels.in` field, then semantically match them against the task title and description; omit `scope` when there is no clear hit. Final title: `{cc_type}({scope}): {task_title}` or `{cc_type}: {task_title}` (preserve the task title verbatim — do not translate or rewrite).
+
+### 3. Build the Issue Body
+
+Issue Form detection: follow the "Issue Template Detection" section in `.agents/rules/issue-pr-commands.md` to scan `.github/ISSUE_TEMPLATE/*.yml` (excluding `config.yml`).
+
+#### Scenario A: A matching template was detected
+
+Pick the form whose `name` (or filename) best matches the task type (e.g., a task with `type: bugfix` prefers a form whose name contains `bug`); if no match, fall back to a generic form like `other.yml`; if none, take the first form in the directory.
+
+Populate the form by following the field-handling rules in `.agents/rules/issue-pr-commands.md` § "Issue Template Detection":
+
+- `textarea` / `input` fields: use `attributes.label` as a markdown heading and pull values from task.md
+- `markdown` fields: skip (these are description blurbs)
+- `dropdown` / `checkboxes` fields: skip
+
+Recommended field-to-source mapping:
+
+| Template field hint | Source in task.md |
+|---|---|
+| `summary`, `title` | task title |
+| `description`, `problem`, `what happened`, `issue-description`, `current-content` | task description |
+| `solution`, `requirements`, `steps`, `suggested-content`, `impact`, `context`, `alternatives`, `expected` | requirements list (preserve checked / unchecked state as-is) |
+| Other `textarea` / `input` fields | task description, or `N/A` if missing |
+
+Whenever task.md does not provide a usable value, write `N/A`.
+
+#### Scenario B: No template, or template parsing failed
+
+Fall back to the default body:
+
+```markdown
+## Description
+
+{task description, or N/A if missing}
+
+## Requirements
+
+- [ ] {requirement-1}
+- [ ] {requirement-2}
+```
+
+If the requirements list is empty, write `N/A` in that section.
+
+### 4. Resolve labels / Issue Type / milestone
+
+#### labels (rough pass)
+
+- Call `gh api "repos/$upstream_repo/labels?per_page=100" --jq '.[].name'` to fetch the actual labels in the repo (cache as a set)
+- Pick the "expected type label" using the mapping below, keeping only those that exist in the repo set:
+
+  | task.md `type` | label |
+  |---|---|
+  | `bug`, `bugfix` | `type: bug` |
+  | `feature` | `type: feature` |
+  | `enhancement` | `type: enhancement` |
+  | `docs`, `documentation` | `type: documentation` |
+  | `dependency-upgrade` | `type: dependency-upgrade` |
+  | `task`, `chore` | `type: task` |
+  | `refactor`, `refactoring` | `type: enhancement` |
+  | others | skip |
+
+- `in:` labels (rough pass — when in doubt, leave it out): semantically match the task title and description against module names from `labels.in`; explicit mention or strong implication → add `in: {module}`; vague or uncertain → skip. `in:` labels also require the label to actually exist in the repo.
+
+If the final label set is empty, omit the `--label` argument.
+
+#### Issue Type fallback
+
+| task.md `type` | Issue Type |
+|---|---|
+| `bug`, `bugfix` | `Bug` |
+| `feature`, `enhancement` | `Feature` |
+| `task`, `documentation`, `dependency-upgrade`, `chore`, `docs`, `refactor`, `refactoring`, others | `Task` |
+
+When applying the Issue Type, follow the "Set Issue Type" command in `.agents/rules/issue-pr-commands.md`; first call `gh api orgs/{owner}/issue-types` to list the org's actually available Types, and only set the inferred value when it is present in that list. Failure to set is non-blocking.
+
+#### milestone
+
+Infer per `.agents/rules/milestone-inference.md` § "Stage 1: `create-task` (when the platform rule creates the Issue)". When the inference is empty or the repo lacks a matching milestone, omit the milestone.
+
+### 5. Call the GitHub CLI to Create the Issue
+
+Run the "Create Issue" command from `.agents/rules/issue-pr-commands.md`:
+
+```bash
+gh issue create -R "$upstream_repo" \
+  --title "{title}" \
+  --body "{body}" \
+  --assignee @me \
+  {label-args} \
+  {milestone-arg}
+```
+
+- `{label-args}` is expanded from the result of §4 into multiple `--label "..."`; if empty, omit the entire argument
+- `{milestone-arg}` is only expanded to `--milestone "..."` when `has_triage=true` and milestone is non-empty; otherwise omit
+- `--assignee @me` requires no permission probe; on failure, skip silently
+
+Permission downgrade follows `.agents/rules/issue-sync.md`: `has_triage=false` skips label / milestone settings; `has_push=false` skips Issue Type setting; the rest continues.
+
+After success, parse the Issue number from the output (match only the `https://.../issues/(\d+)` URL form; do not use a loose regex). If parsing fails, halt the cascade and propagate the error back to `create-task`.
+
+### 6. Set Issue Type (Optional)
+
+Execute only when `has_push=true` and the Issue Type inferred in §4 is in the org's actually available list:
+
+```bash
+gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH \
+  -f type="{issue-type}" --silent
+```
+
+Failure is non-blocking.
+
+### 7. Write Back task.md
+
+Update task.md:
+
+- Write `issue_number: {n}` into the frontmatter (replace if it exists; append at the end of the frontmatter otherwise)
+- Update `updated_at` to the current time (command: `date "+%Y-%m-%d %H:%M:%S%:z"`)
+- Append to the `## 活动日志` / `## Activity Log` section:
+  ```
+  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Create Issue** by {agent} — Created GitHub Issue #{n}
+  ```
+
+### 8. Return the Result
+
+Hand the following back to the caller `create-task`:
+
+- Issue number `{n}`
+- Issue URL (prefer the URL printed by `gh issue create`; fall back to `https://github.com/$upstream_repo/issues/{n}`)
+- The labels / milestone / Issue Type that were actually applied
+
+`create-task` uses these to pick the "Scenario A: Issue created" output branch and continue with task comment sync and status label setup.
+
+## Error Handling
+
+- Auth failure / command unavailable: return a structured `{code: "AUTH_FAILED", message}` to `create-task`; do not modify task.md
+- Network timeout / DNS failure: `{code: "NETWORK", message}`
+- Template parsing failure, Issue number parsing failure, other anomalies: `{code: "VALIDATION", message}`
+- All failures keep task.md untouched; `create-task` takes the "Scenario C: failure fallback" output branch and prompts the user to retry manually or fill `issue_number` later

package/templates/.agents/rules/create-issue.github.zh-CN.md

@@ -0,0 +1,178 @@
+# Issue 创建
+
+当 `create-task` 完成本地 `task.md` 落盘后，按本规则级联创建 Issue。本规则仅由 `create-task` SKILL.md 内部引用，不应独立调用。
+
+## 行为边界
+
+- Issue 标题和正文只能来自 `task.md`
+- 不读取 `analysis.md`、`plan.md`、`implementation.md` 或审查产物
+- 持久产物只有：远端 Issue + `task.md` 中回写的 `issue_number`
+- Issue 创建失败时不回滚 `task.md`；当前 task 仍可继续后续工作流，未来可由用户手动写入 `issue_number`，让其它技能的级联同步接管
+
+## 执行步骤
+
+### 1. 验证前置条件
+
+- `.agents/workspace/active/{task-id}/task.md` 必须存在
+- 先读取 `.agents/rules/issue-pr-commands.md`，按其中的认证与平台检测命令验证 `gh auth status` 和当前仓库可用
+- 先读取 `.agents/rules/issue-sync.md`，完成 `upstream_repo`、`has_triage`、`has_push` 检测；后续所有 `gh issue` 与 repo 级 `gh api` 调用都复用这些变量
+- 如果 `task.md` 中 `issue_number` 已存在且既不为空也不为 `N/A`，立即停止级联：返回"任务已绑定 Issue #{n}，跳过创建"信息给 `create-task`，由调用方决定如何继续
+
+### 2. 提取任务信息
+
+从 `task.md` 提取以下字段：
+
+- 任务标题（首个 `# ` 标题，去掉 `任务：` / `Task:` 前缀）
+- `## Description` / `## 描述` 段落
+- `## Requirements` / `## 需求` 段落
+- frontmatter 中的 `type` 与（可选的）`milestone`
+
+构造 Issue 标题：
+
+| task.md `type` | Conventional Commits type |
+|---|---|
+| `feature` | `feat` |
+| `bugfix`, `bug` | `fix` |
+| `refactor`, `refactoring` | `refactor` |
+| `docs`, `documentation` | `docs` |
+| `chore`, `task` 或其它 | `chore` |
+
+scope 推断：从 `.agents/.airc.json` 的 `labels.in` 字段读取已知模块名，再与任务标题/描述做语义匹配；没有清晰命中时省略 scope。最终标题：`{cc_type}({scope}): {task_title}` 或 `{cc_type}: {task_title}`（任务标题保留原文，不要翻译或改写）。
+
+### 3. 构建 Issue 正文
+
+Issue 模板检测：按 `.agents/rules/issue-pr-commands.md` 的 "Issue 模板检测" 规则扫描 `.github/ISSUE_TEMPLATE/*.yml`（排除 `config.yml`）。
+
+#### 场景 A：检测到匹配模板
+
+按模板顶层 `name` 与任务类型挑选最匹配的 form（如任务 `type: bugfix` 优先选名称含 `bug` 的模板）；找不到匹配时，回退到通用 form（如 `other.yml`），仍找不到时取目录中第一个 form。
+
+按 `.agents/rules/issue-pr-commands.md` 中 "Issue 模板检测" 章节的字段处理规则填充 form：
+
+- `textarea` / `input` 字段：使用 `attributes.label` 作为 markdown 标题，从 task.md 取值
+- `markdown` 字段：跳过（说明文案）
+- `dropdown` / `checkboxes` 字段：跳过
+
+字段值映射（建议）：
+
+| 模板字段提示 | task.md 来源 |
+|---|---|
+| `summary`, `title` | 任务标题 |
+| `description`, `problem`, `what happened`, `issue-description`, `current-content` | 任务描述 |
+| `solution`, `requirements`, `steps`, `suggested-content`, `impact`, `context`, `alternatives`, `expected` | 需求列表（已勾选与未勾选混合，原样保留） |
+| 其它 `textarea` / `input` 字段 | 任务描述；缺失时填 `N/A` |
+
+任何字段在 task.md 中找不到合适值时，写入 `N/A`。
+
+#### 场景 B：无模板或解析失败
+
+回退到默认正文：
+
+```markdown
+## Description
+
+{任务描述；缺失时填 N/A}
+
+## Requirements
+
+- [ ] {requirement-1}
+- [ ] {requirement-2}
+```
+
+需求列表为空时，整段写 `N/A`。
+
+### 4. 解析 labels / Issue Type / milestone
+
+#### labels（粗选）
+
+- 调用 `gh api "repos/$upstream_repo/labels?per_page=100" --jq '.[].name'` 获取仓库实际存在的 label 列表（缓存为 set）
+- 按以下映射挑出"应有的 type label"，仅保留仓库 set 中实际存在的：
+
+  | task.md `type` | label |
+  |---|---|
+  | `bug`, `bugfix` | `type: bug` |
+  | `feature` | `type: feature` |
+  | `enhancement` | `type: enhancement` |
+  | `docs`, `documentation` | `type: documentation` |
+  | `dependency-upgrade` | `type: dependency-upgrade` |
+  | `task`, `chore` | `type: task` |
+  | `refactor`, `refactoring` | `type: enhancement` |
+  | 其它 | 跳过 |
+
+- `in:` label（粗选，宁缺毋滥）：根据任务标题与描述对 `labels.in` 中的模块名做语义匹配；明确提及或强烈暗示 → 添加 `in: {module}`；模糊或不确定 → 不添加。`in:` label 同样要求仓库实际存在。
+
+最终 label 集合若为空，省略 `--label` 参数。
+
+#### Issue Type fallback
+
+| task.md `type` | Issue Type |
+|---|---|
+| `bug`, `bugfix` | `Bug` |
+| `feature`, `enhancement` | `Feature` |
+| `task`, `documentation`, `dependency-upgrade`, `chore`, `docs`, `refactor`, `refactoring` 及其它 | `Task` |
+
+实际设置时按 `.agents/rules/issue-pr-commands.md` 的 "设置 Issue Type" 命令；先调 `gh api orgs/{owner}/issue-types` 列出 org 实际可用的 Type，仅当推断值在列表中时才设置；设置失败不阻断流程。
+
+#### milestone
+
+按 `.agents/rules/milestone-inference.md` 的 "阶段 1：`create-task`（平台规则创建 Issue 时）" 规则推断；推断结果为空或仓库无对应 milestone 时省略。
+
+### 5. 调用 GitHub CLI 创建 Issue
+
+按 `.agents/rules/issue-pr-commands.md` 中的 "创建 Issue" 命令执行：
+
+```bash
+gh issue create -R "$upstream_repo" \
+  --title "{title}" \
+  --body "{body}" \
+  --assignee @me \
+  {label-args} \
+  {milestone-arg}
+```
+
+- `{label-args}` 由 §4 计算结果展开为多个 `--label "..."`；为空则整体省略
+- `{milestone-arg}` 仅当 `has_triage=true` 且 milestone 非空时展开为 `--milestone "..."`；否则整体省略
+- `--assignee @me` 不做权限预判，失败时静默跳过
+
+权限降级规则按 `.agents/rules/issue-sync.md`：`has_triage=false` 时跳过 label / milestone 设置；`has_push=false` 时跳过 Issue Type 设置；其余流程继续。
+
+创建成功后从输出中解析 Issue 编号（仅匹配 `https://.../issues/(\d+)` URL 形式，不要使用宽松正则）；解析失败时停止级联并把错误传回 `create-task`。
+
+### 6. 设置 Issue Type（可选）
+
+仅当 `has_push=true` 且 §4 推断的 Issue Type 在 org 实际可用列表中时执行：
+
+```bash
+gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH \
+  -f type="{issue-type}" --silent
+```
+
+设置失败不阻断流程。
+
+### 7. 回写 task.md
+
+更新 task.md：
+
+- 把 `issue_number: {n}` 写入 frontmatter（已存在则替换；不存在则在 frontmatter 末尾追加）
+- 更新 `updated_at` 为当前时间（命令：`date "+%Y-%m-%d %H:%M:%S%:z"`）
+- 在 `## 活动日志` / `## Activity Log` 段落追加：
+  ```
+  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Create Issue** by {agent} — Created GitHub Issue #{n}
+  ```
+
+### 8. 返回结果
+
+把以下信息回传给调用方 `create-task`：
+
+- Issue 编号 `{n}`
+- Issue URL（首选 `gh issue create` 输出中的 URL；缺失时拼 `https://github.com/$upstream_repo/issues/{n}`）
+- 实际应用的 labels / milestone / Issue Type
+
+`create-task` 据此选择"场景 A：已创建 Issue"输出分支并继续执行后续 task 评论同步与 status label 设置。
+
+## 错误处理
+
+- 认证失败 / 命令不可用：返回结构化错误 `{code: "AUTH_FAILED", message}` 给 `create-task`，不修改 task.md
+- 网络超时 / DNS 失败：`{code: "NETWORK", message}`
+- 模板解析失败、Issue 编号解析失败、其它异常：`{code: "VALIDATION", message}`
+- 任意失败均不回滚 task.md；`create-task` 走"场景 C 失败兜底"输出，提示用户手动重试或在事后写入 `issue_number`

package/templates/.agents/rules/create-issue.zh-CN.md

@@ -0,0 +1,5 @@
+# Issue 创建
+
+当前代码平台未提供 Issue 创建规则。
+
+`create-task` 在本平台上会跳过级联创建 Issue 步骤；本地 `task.md` 仍然是有效产物。如果将来需要把任务绑定到一个 Issue，可手动在 `task.md` 中写入 `issue_number`，后续技能（`commit` / `refine-task` / `complete-task` 等）会按既有的级联同步规则自动接管 Issue 元数据更新。