@fitlab-ai/agent-infra 0.9.9 → 0.9.11

package/templates/.agents/skills/update-agent-infra/SKILL.en.md

@@ -51,7 +51,7 @@ The script outputs JSON to stdout. Parse and record the report.
 - `managed.conflicts`: guarded managed files with unknown origin, two-sided changes, or ownership that cannot be proven during a platform switch; list each target, reason, and three-way hash
 - `managed.removed`: deleted managed files (including old paths removed during template migrations)
 - `managed.skippedPlatform`: managed / merged entries skipped because they belong to a different platform
-- `managed.skippedTUI`: managed / merged entries skipped because they are owned by a built-in Agent Client whose `agentClients[].enabled` is `false` (legacy `tuis` is migration-only; customTUI command files under the same path prefix are preserved)
+- `managed.skippedTUI`: managed / merged entries skipped because they are owned by a built-in Agent Client whose `agentClients[].enabled` is `false` (customTUI command files under the same path prefix are preserved)
 - `merged.pending`: list of merged files for AI to process
   - Each item has `target` (project-relative path) and `template` (template-root-relative path)
 - `registryAdded`: newly added file registry entries
@@ -131,7 +131,7 @@ warning to the end of the report:
 > **Rationale**: The current execution used the old skill logic; the new version
 > may contain additional processing steps. Running again ensures the new logic
 > is fully applied.
-> Alternatively, users can run `ai update` before executing the skill to
+> Alternatively, users can run `ai sync` before executing the skill to
 > pre-update the seed files and avoid the need for a second run.
 
 ### Output report

package/templates/.agents/skills/update-agent-infra/SKILL.zh-CN.md

@@ -43,7 +43,7 @@ node .agents/skills/update-agent-infra/scripts/sync-templates.js
 - `managed.conflicts`：来源未知、双边修改或平台切换时无法证明官方所有权的 guarded managed 冲突；必须逐项展示 target、reason 与三方哈希
 - `managed.removed`：被删除的 managed 文件（包括模板迁移时移除的旧路径）
 - `managed.skippedPlatform`：因归属其他平台而被跳过的 managed / merged 条目
-- `managed.skippedTUI`：因对应内建 Agent Client 的 `agentClients[].enabled` 为 `false` 而被跳过的 managed / merged 条目（旧 `tuis` 仅用于迁移；落在同一路径前缀下的 customTUI 命令文件会被保留）
+- `managed.skippedTUI`：因对应内建 Agent Client 的 `agentClients[].enabled` 为 `false` 而被跳过的 managed / merged 条目（落在同一路径前缀下的 customTUI 命令文件会被保留）
 - `merged.pending`：需要 AI 处理的 merged 文件列表
   - 每项包含 `target`（项目中的目标路径）和 `template`（模板根目录下的相对路径）
 - `registryAdded`：新增的文件注册条目
@@ -116,7 +116,7 @@ node .agents/skills/update-agent-infra/scripts/sync-templates.js
 
 > **原因**：本次执行使用的是旧版技能逻辑，新版技能可能包含额外的处理步骤。
 > 再次执行可确保新逻辑完整应用。
-> 用户也可以在执行前先运行 `ai update` 来预先更新技能文件，避免需要两次执行。
+> 用户也可以在执行前先运行 `ai sync` 来预先更新技能文件，避免需要两次执行。
 
 ### 输出报告
 

package/templates/.agents/skills/update-agent-infra/scripts/sync-templates.js

@@ -48,6 +48,11 @@ const DEFAULTS = {
       "id": "opencode",
       "enabled": true,
       "installInSandbox": true
+    },
+    {
+      "id": "traecli",
+      "enabled": true,
+      "installInSandbox": true
     }
   ],
   "sandbox": {
@@ -111,6 +116,10 @@ const DEFAULTS = {
     ],
     "ejected": [],
     "retiredManaged": [
+      {
+        "path": ".trae/skills/",
+        "templateHashes": []
+      },
       {
         "path": ".agents/workspace/README.md",
         "templateHashes": [
@@ -189,6 +198,24 @@ const AGENT_CLIENT_MANIFEST = [
       },
       "argumentsToken": "$ARGUMENTS"
     }
+  },
+  {
+    "id": "traecli",
+    "displayName": "TraeCode CLI",
+    "invocation": "/${skillName}",
+    "ownedPathPrefixes": [
+      ".traecli/"
+    ],
+    "managed": [
+      ".traecli/commands/"
+    ],
+    "merged": [],
+    "ejected": [],
+    "customCommand": {
+      "target": ".traecli/commands/${skillName}.md",
+      "frontmatter": {},
+      "argumentsToken": "$ARGUMENTS"
+    }
   }
 ];
 const CUSTOM_TUI_CONTRACT = {
@@ -206,84 +233,19 @@ const CUSTOM_TUI_CONTRACT = {
 const KNOWN_PLATFORMS = new Set(['github', 'none']);
 const KNOWN_LANGUAGES = new Set(['en', 'zh-CN']);
 
-const BUILTIN_TUI_IDS = AGENT_CLIENT_MANIFEST.map((entry) => entry.id);
+const AGENT_CLIENT_IDS = AGENT_CLIENT_MANIFEST.map((entry) => entry.id);
 
 function normalizeAgentClientConfig(cfg) {
   const own = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
-  const diagnostics = [];
   const failure = (code, path) => ({
-    source: null,
     state: null,
     canonical: null,
-    remainingSandboxTools: undefined,
-    removeLegacyTuis: false,
-    changed: false,
-    diagnostics,
     error: `${code} at ${path}`,
     errorCode: code,
     errorPath: path
   });
-  const projectTuis = (value) => {
-    if (!Array.isArray(value)) {
-      return Object.fromEntries(BUILTIN_TUI_IDS.map((id) => [id, true]));
-    }
-    const enabled = new Set();
-    for (const [index, candidate] of value.entries()) {
-      if (BUILTIN_TUI_IDS.includes(candidate)) enabled.add(candidate);
-      else diagnostics.push({ code: 'LEGACY_VALUE_IGNORED', path: `tuis[${index}]` });
-    }
-    return Object.fromEntries(BUILTIN_TUI_IDS.map((id) => [id, enabled.has(id)]));
-  };
-  const projectSandbox = (value) => {
-    if (!Array.isArray(value) || value.length === 0) {
-      return {
-        installed: Object.fromEntries(BUILTIN_TUI_IDS.map((id) => [id, true])),
-        clientSignals: new Set(),
-        remainingTools: Array.isArray(value) ? [] : undefined
-      };
-    }
-    const installed = new Set();
-    const remainingTools = [];
-    for (const [index, candidate] of value.entries()) {
-      if (BUILTIN_TUI_IDS.includes(candidate)) installed.add(candidate);
-      else if (typeof candidate === 'string') remainingTools.push(candidate);
-      else diagnostics.push({ code: 'LEGACY_VALUE_IGNORED', path: `sandbox.tools[${index}]` });
-    }
-    return {
-      installed: Object.fromEntries(BUILTIN_TUI_IDS.map((id) => [id, installed.has(id)])),
-      clientSignals: installed,
-      remainingTools
-    };
-  };
-  const serialize = (state) => BUILTIN_TUI_IDS.map((id) => ({ id, ...state[id] }));
-  const hasCanonical = own(cfg, 'agentClients');
-  const hasLegacyTuis = own(cfg, 'tuis');
-  const sandbox = cfg.sandbox && typeof cfg.sandbox === 'object' && !Array.isArray(cfg.sandbox)
-    ? cfg.sandbox
-    : undefined;
-  const hasSandboxTools = sandbox !== undefined && own(sandbox, 'tools');
-  const tuiProjection = projectTuis(cfg.tuis);
-  const sandboxProjection = projectSandbox(sandbox?.tools);
-
-  if (!hasCanonical) {
-    const state = Object.fromEntries(BUILTIN_TUI_IDS.map((id) => [id, {
-      enabled: tuiProjection[id],
-      installInSandbox: sandboxProjection.installed[id]
-    }]));
-    return {
-      source: 'legacy',
-      state,
-      canonical: serialize(state),
-      remainingSandboxTools: sandboxProjection.remainingTools,
-      removeLegacyTuis: hasLegacyTuis,
-      changed: true,
-      diagnostics,
-      error: null,
-      errorCode: null,
-      errorPath: null
-    };
-  }
-
+  const serialize = (state) => AGENT_CLIENT_IDS.map((id) => ({ id, ...state[id] }));
+  if (!own(cfg, 'agentClients')) return failure('MISSING_AGENT_CLIENT', 'agentClients');
   if (!Array.isArray(cfg.agentClients)) return failure('INVALID_AGENT_CLIENTS', 'agentClients');
   const entries = new Map();
   for (const [index, candidate] of cfg.agentClients.entries()) {
@@ -301,7 +263,7 @@ function normalizeAgentClientConfig(cfg) {
     ) {
       return failure('INVALID_AGENT_CLIENTS', entryPath);
     }
-    if (!BUILTIN_TUI_IDS.includes(candidate.id)) {
+    if (!AGENT_CLIENT_IDS.includes(candidate.id)) {
       return failure('UNKNOWN_AGENT_CLIENT', `${entryPath}.id`);
     }
     if (entries.has(candidate.id)) return failure('DUPLICATE_AGENT_CLIENT', `${entryPath}.id`);
@@ -311,24 +273,44 @@ function normalizeAgentClientConfig(cfg) {
     let orchestration;
     if (own(candidate, 'orchestration')) {
       const policy = candidate.orchestration;
-      const exact = (value) => typeof value === 'string' && value.length > 0 && value.trim() === value;
-      const validRole = (role) => role
-        && typeof role === 'object'
-        && !Array.isArray(role)
-        && Object.keys(role).length === 2
-        && exact(role.model)
-        && exact(role.reasoningEffort);
       if (
         !policy
         || typeof policy !== 'object'
         || Array.isArray(policy)
         || Object.keys(policy).length !== 2
-        || !validRole(policy.executor)
-        || !validRole(policy.reviewer)
+        || !own(policy, 'executor')
+        || !own(policy, 'reviewer')
       ) {
         return failure('INVALID_AGENT_CLIENTS', `${entryPath}.orchestration`);
       }
-      orchestration = structuredClone(policy);
+      const parseExact = (value, path) => {
+        if (typeof value !== 'string' || value.length === 0 || value.trim() !== value) {
+          return failure('INVALID_AGENT_CLIENTS', path);
+        }
+        return value;
+      };
+      const parseRole = (role, rolePath) => {
+        if (
+          !role
+          || typeof role !== 'object'
+          || Array.isArray(role)
+          || Object.keys(role).length !== 2
+          || !own(role, 'model')
+          || !own(role, 'reasoningEffort')
+        ) {
+          return failure('INVALID_AGENT_CLIENTS', rolePath);
+        }
+        const model = parseExact(role.model, `${rolePath}.model`);
+        if (typeof model !== 'string') return model;
+        const reasoningEffort = parseExact(role.reasoningEffort, `${rolePath}.reasoningEffort`);
+        if (typeof reasoningEffort !== 'string') return reasoningEffort;
+        return { model, reasoningEffort };
+      };
+      const executor = parseRole(policy.executor, `${entryPath}.orchestration.executor`);
+      if (executor.errorCode) return executor;
+      const reviewer = parseRole(policy.reviewer, `${entryPath}.orchestration.reviewer`);
+      if (reviewer.errorCode) return reviewer;
+      orchestration = { executor, reviewer };
     }
     entries.set(candidate.id, {
       enabled: candidate.enabled,
@@ -336,25 +318,29 @@ function normalizeAgentClientConfig(cfg) {
       ...(orchestration ? { orchestration } : {})
     });
   }
-  if (BUILTIN_TUI_IDS.some((id) => !entries.has(id))) {
+  if (AGENT_CLIENT_IDS.some((id) => !entries.has(id))) {
     return failure('MISSING_AGENT_CLIENT', 'agentClients');
   }
-  const state = Object.fromEntries(BUILTIN_TUI_IDS.map((id) => [id, entries.get(id)]));
-  if (hasLegacyTuis && BUILTIN_TUI_IDS.some((id) => state[id].enabled !== tuiProjection[id])) {
-    return failure('LEGACY_CONFLICT', 'tuis');
+  for (const [index, id] of AGENT_CLIENT_IDS.entries()) {
+    if (cfg.agentClients[index]?.id !== id) {
+      return failure('INVALID_AGENT_CLIENTS', `agentClients[${index}].id`);
+    }
   }
-  if ([...sandboxProjection.clientSignals].some((id) => !state[id].installInSandbox)) {
-    return failure('LEGACY_CONFLICT', 'sandbox.tools');
+  if (own(cfg, 'tuis')) return failure('INVALID_AGENT_CLIENTS', 'tuis');
+  const sandbox = cfg.sandbox && typeof cfg.sandbox === 'object' && !Array.isArray(cfg.sandbox)
+    ? cfg.sandbox
+    : undefined;
+  if (Array.isArray(sandbox?.tools)) {
+    for (const [index, tool] of sandbox.tools.entries()) {
+      if (AGENT_CLIENT_IDS.includes(tool)) {
+        return failure('INVALID_AGENT_CLIENTS', `sandbox.tools[${index}]`);
+      }
+    }
   }
-  const sameOrder = cfg.agentClients.every((entry, index) => entry.id === BUILTIN_TUI_IDS[index]);
+  const state = Object.fromEntries(AGENT_CLIENT_IDS.map((id) => [id, entries.get(id)]));
   return {
-    source: 'canonical',
     state,
     canonical: serialize(state),
-    remainingSandboxTools: hasSandboxTools ? sandboxProjection.remainingTools : undefined,
-    removeLegacyTuis: hasLegacyTuis,
-    changed: hasLegacyTuis || sandboxProjection.clientSignals.size > 0 || !sameOrder,
-    diagnostics,
     error: null,
     errorCode: null,
     errorPath: null
@@ -363,16 +349,6 @@ function normalizeAgentClientConfig(cfg) {
 
 function materializeAgentClientConfig(cfg, normalized) {
   cfg.agentClients = normalized.canonical;
-  delete cfg.tuis;
-  if (normalized.remainingSandboxTools !== undefined) {
-    cfg.sandbox = {
-      ...(cfg.sandbox || {}),
-      tools: [
-        'agent-infra',
-        ...normalized.remainingSandboxTools.filter((tool) => tool !== 'agent-infra')
-      ]
-    };
-  }
 }
 
 function assetMatches(entry, target) {
@@ -459,6 +435,17 @@ function isInsideProject(projectRoot, relativePath) {
   return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
 }
 
+function isInsideProjectDirectory(projectRoot, directory, relativePath) {
+  if (!isInsideProject(projectRoot, directory) || !isInsideProject(projectRoot, relativePath)) {
+    return false;
+  }
+
+  const root = path.resolve(projectRoot, directory);
+  const resolved = path.resolve(projectRoot, relativePath);
+  const rel = path.relative(root, resolved);
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
 function isPathOwnedByOtherPlatform(relativePath, platformType) {
   const normalized = norm(relativePath).replace(/^\.\//, '');
   const top = normalized.split('/')[0];
@@ -1286,7 +1273,7 @@ function syncTemplates(projectRoot, templateRootOverride) {
     return { error: enabledResolution.error };
   }
   const enabledTUIs = new Set(
-    BUILTIN_TUI_IDS.filter((id) => enabledResolution.state[id].enabled)
+    AGENT_CLIENT_IDS.filter((id) => enabledResolution.state[id].enabled)
   );
   materializeAgentClientConfig(cfg, enabledResolution);
   const customTUIsConfig = Array.isArray(cfg.customTUIs) ? cfg.customTUIs : [];
@@ -1306,6 +1293,10 @@ function syncTemplates(projectRoot, templateRootOverride) {
       (descriptor.templateHashes || []).map(trustedBaseline).filter(Boolean)
     )];
   }));
+  const retiredManagedForTarget = (target) => [...retiredManaged.entries()].find(
+    ([entry]) => assetMatches(entry, target)
+      && (!entry.endsWith('/') || isInsideProjectDirectory(projectRoot, entry, target))
+  );
   const planningRegistry = {
     ...currentRegistry,
     managed: currentRegistry.managed.filter((entry) => !retiredManaged.has(norm(entry)))
@@ -1334,7 +1325,7 @@ function syncTemplates(projectRoot, templateRootOverride) {
   for (const target of Object.keys(managedBaselines)) {
     if (
       !guardedManaged.has(norm(target))
-      && !retiredManaged.has(norm(target))
+      && !retiredManagedForTarget(target)
       && !allClientManaged.some((entry) => assetMatches(entry, target))
     ) {
       delete managedBaselines[target];
@@ -1410,8 +1401,72 @@ function syncTemplates(projectRoot, templateRootOverride) {
   );
 
   for (const [entry, historicalTemplateHashes] of retiredManaged) {
-    const target = path.join(projectRoot, entry);
+    const target = path.join(projectRoot, entry.endsWith('/') ? entry.slice(0, -1) : entry);
     const owned = currentRegistry.managed.some((candidate) => norm(candidate) === entry);
+    if (entry.endsWith('/')) {
+      if (fs.existsSync(target)) {
+        const targetStat = fs.lstatSync(target);
+        if (!targetStat.isDirectory() || targetStat.isSymbolicLink()) {
+          report.managed.protected.push({
+            target: entry,
+            reason: 'invalid-type',
+            baseline: null,
+            local: null,
+            template: null
+          });
+          continue;
+        }
+      }
+      const candidates = new Set(
+        Object.keys(managedBaselines).filter((candidate) =>
+          assetMatches(entry, candidate)
+            && isInsideProjectDirectory(projectRoot, entry, candidate)
+        )
+      );
+      if (owned && fs.existsSync(target)) {
+        for (const filePath of walkDir(target)) {
+          candidates.add(norm(path.relative(projectRoot, filePath)));
+        }
+      }
+
+      for (const candidate of candidates) {
+        const candidatePath = path.join(projectRoot, candidate);
+        const baseline = trustedBaseline(managedBaselines[candidate]);
+        if (!fs.existsSync(candidatePath)) {
+          if (Object.prototype.hasOwnProperty.call(managedBaselines, candidate)) {
+            delete managedBaselines[candidate];
+            baselinesChanged = true;
+          }
+          continue;
+        }
+        const stat = fs.lstatSync(candidatePath);
+        const localHash = stat.isFile() && !stat.isSymbolicLink()
+          ? sha256(fs.readFileSync(candidatePath))
+          : null;
+        const safeToRemove = localHash !== null
+          && (localHash === baseline || historicalTemplateHashes.has(localHash));
+        if (safeToRemove) {
+          fs.unlinkSync(candidatePath);
+          report.managed.removed.push(candidate);
+        } else {
+          report.managed.protected.push({
+            target: candidate,
+            reason: localHash === null
+              ? 'invalid-type'
+              : (baseline !== null ? 'user-modified' : 'unknown-origin'),
+            baseline,
+            local: localHash,
+            template: null
+          });
+        }
+        if (Object.prototype.hasOwnProperty.call(managedBaselines, candidate)) {
+          delete managedBaselines[candidate];
+          baselinesChanged = true;
+        }
+      }
+      removeEmptyDirs(target);
+      continue;
+    }
     if (!fs.existsSync(target)) continue;
     const stat = fs.lstatSync(target);
     const baseline = trustedBaseline(managedBaselines[entry]);

package/templates/.agents/skills/watch-pr/SKILL.en.md

@@ -21,7 +21,7 @@ Version stamp rule: before creating or updating `task.md` frontmatter, read `.ag
 
 ## Task Context Resolution
 
-> Keep `--pr <number>` and PR URLs on the existing PR-anchored path. Otherwise, the task path may omit the task ref and also accepts a legacy positional ref or `--task <ref>` / `-t <ref>`. Separate task scope from the full arguments, then call `agent-infra-internal task-context resolve {task-scope}` and bind `{task-id}` to the returned full `taskId`. A PR anchor and task scope are mutually exclusive.
+> Keep `--pr <number>` and PR URLs on the existing PR-anchored path. Otherwise, the task path may omit the task ref; explicit task scope accepts only `--task <ref>` or `-t <ref>`, and positional task refs are not interpreted. Separate task scope from the full arguments, then call `agent-infra-internal task-context resolve {task-scope}` and bind `{task-id}` to the returned full `taskId`. A PR anchor and task scope are mutually exclusive.
 
 ## Step Start: Write the started Marker
 
@@ -40,7 +40,7 @@ After prerequisites pass and before this round's first artifact action, append a
 Resolve the target PR number `{pr#}` and an optional `{task-id}` via these deterministic branches:
 
 - Scenario A (argument omitted): reverse-lookup the active task from the current branch, then read its `pr_number`.
-- Scenario B (omitted task ref, positional task ref, or `--task/-t`, **task-anchored primary path**): resolve the full `{task-id}` via "Task Context Resolution" and read `.agents/workspace/active/{task-id}/task.md` for `pr_number` as `{pr#}`; if `pr_number` is empty, follow "Error Handling" to prompt running `create-pr` first, then stop.
+- Scenario B (omitted task ref or `--task/-t`, **task-anchored primary path**): resolve the full `{task-id}` via "Task Context Resolution" and read `.agents/workspace/active/{task-id}/task.md` for `pr_number` as `{pr#}`; if `pr_number` is empty, follow "Error Handling" to prompt running `create-pr` first, then stop.
 - Scenario C (`--pr <number>` or a PR URL): use that PR number directly as `{pr#}`; then determine `{task-id}` via "Reverse-lookup task".
 - Reverse-lookup task (scenarios A / C): use task context/query capabilities to find the unique active task bound to `{pr#}`. If none exists, stop and request binding first; the typed checks intent does not create a second taskless state machine.
 

package/templates/.agents/skills/watch-pr/SKILL.zh-CN.md

@@ -21,7 +21,7 @@ description: >
 
 ## 任务上下文解析
 
-> 入口允许省略 task ref，也接受旧位置 task ref 或 `--task <ref>` / `-t <ref>`。先从完整参数中分离 task scope 并原样保留其他业务操作数，再调用 `agent-infra-internal task-context resolve {task-scope}`；`{task-scope}` 为空、位置 ref 或 task flag 之一。只读取结构化结果的 `taskId`，后续把 `{task-id}` 绑定为该完整 `TASK-YYYYMMDD-HHMMSS`。解析失败时透传非零退出码，不自行扫描任务。
+> 入口允许省略 task ref，也接受 `--task <ref>` / `-t <ref>`。先从完整参数中分离 task scope 并原样保留其他业务操作数，再调用 `agent-infra-internal task-context resolve {task-scope}`；`{task-scope}` 为空或 task flag 之一。只读取结构化结果的 `taskId`，后续把 `{task-id}` 绑定为该完整 `TASK-YYYYMMDD-HHMMSS`。解析失败时透传非零退出码，不自行扫描任务。
 
 ## 步骤开始：写入 started 标记
 
@@ -40,7 +40,7 @@ description: >
 按以下确定性分支解析出目标 PR 号 `{pr#}` 与可选 `{task-id}`：
 
 - 场景 A（省略入参）：从当前分支反查 active task；定位后读取其 `pr_number`。
-- 场景 B（省略 task ref、旧位置 task ref 或 `--task/-t`，**任务锚定主路径**）：按「任务上下文解析」取得完整 `{task-id}`。读 `.agents/workspace/active/{task-id}/task.md` 取 `pr_number` 作为 `{pr#}`；`pr_number` 为空时按「错误处理」提示先 `create-pr`，停止。
+- 场景 B（省略 task ref 或 `--task/-t`，**任务锚定主路径**）：按「任务上下文解析」取得完整 `{task-id}`。读 `.agents/workspace/active/{task-id}/task.md` 取 `pr_number` 作为 `{pr#}`；`pr_number` 为空时按「错误处理」提示先 `create-pr`，停止。
 - 场景 C（`--pr <number>` 或 PR URL）：直接取该 PR 号为 `{pr#}`；随后按「反查任务」确定 `{task-id}`。
 - 反查任务（场景 A / C）：通过任务上下文/任务查询取得与 `{pr#}` 唯一绑定的 active task。未命中时停止并提示先绑定 PR；typed checks intent 不建立第二套无任务状态机。
 

package/templates/.agents/templates/task.en.md

@@ -80,7 +80,7 @@ pr_status: pending             # PR status: pending (default) | created (PR crea
 
 ## Human Rulings
 
-<!-- Use ai decide <task-ref> <ordinal|ledger-id> [--needs-implementation true|false] <decision> for needs-human-decision rulings; upstream AI predeclares implementation intent for new code decisions, while the explicit option remains for legacy tasks or consistency checks. -->
+<!-- Use ai decide [--task <ref> | -t <ref>] (--item <ordinal|ledger-id> | -i <ordinal|ledger-id>) [--needs-implementation true|false] <decision> for needs-human-decision rulings; upstream AI predeclares implementation intent for new code decisions, while the explicit option remains for legacy tasks or consistency checks. -->
 
 ## Implementation Inputs
 

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

@@ -80,7 +80,7 @@ pr_status: pending             # PR 状态：pending（默认）| created（已
 
 ## 人工裁决
 
-<!-- 使用 ai decide <task-ref> <序号|账本ID> [--needs-implementation true|false] <裁决内容> 写入 needs-human-decision 裁定；新建 code 裁决的实现意图由上游 AI 预先声明，显式参数仅用于历史任务兼容或一致性复核。 -->
+<!-- 使用 ai decide [--task <ref> | -t <ref>] (--item <序号|账本ID> | -i <序号|账本ID>) [--needs-implementation true|false] <裁决内容> 写入 needs-human-decision 裁定；新建 code 裁决的实现意图由上游 AI 预先声明，显式参数仅用于历史任务兼容或一致性复核。 -->
 
 ## 实现输入
 

package/templates/.claude/commands/analyze-task.en.md

@@ -1,6 +1,6 @@
 ---
 description: "Analyze a task and produce a requirements document"
-usage: "/analyze-task [task-ref | --task <ref>]"
+usage: "/analyze-task [--task <ref> | -t <ref>]"
 ---
 
 Read and execute the analyze-task skill from `.agents/skills/analyze-task/SKILL.md`.

package/templates/.claude/commands/analyze-task.zh-CN.md

@@ -1,6 +1,6 @@
 ---
 description: "分析任务并输出需求分析文档"
-usage: "/analyze-task [task-ref | --task <ref>]"
+usage: "/analyze-task [--task <ref> | -t <ref>]"
 ---
 
 读取并执行 `.agents/skills/analyze-task/SKILL.md` 中的 analyze-task 技能。

package/templates/.claude/commands/block-task.en.md

@@ -1,6 +1,6 @@
 ---
 description: "Mark a task as blocked and record the reason"
-usage: "/block-task [task-ref | --task <ref>] [reason]"
+usage: "/block-task [--task <ref> | -t <ref>] [reason]"
 disable-model-invocation: true
 ---
 

package/templates/.claude/commands/block-task.zh-CN.md

@@ -1,6 +1,6 @@
 ---
 description: "标记任务为阻塞状态并记录原因"
-usage: "/block-task [task-ref | --task <ref>] [reason]"
+usage: "/block-task [--task <ref> | -t <ref>] [reason]"
 disable-model-invocation: true
 ---
 

package/templates/.claude/commands/cancel-task.en.md

@@ -1,6 +1,6 @@
 ---
 description: "Cancel a task and archive it"
-usage: "/cancel-task [task-ref | --task <ref>] <reason>"
+usage: "/cancel-task [--task <ref> | -t <ref>] <reason>"
 disable-model-invocation: true
 ---
 

package/templates/.claude/commands/cancel-task.zh-CN.md

@@ -1,6 +1,6 @@
 ---
 description: "取消任务并归档"
-usage: "/cancel-task [task-ref | --task <ref>] <reason>"
+usage: "/cancel-task [--task <ref> | -t <ref>] <reason>"
 disable-model-invocation: true
 ---
 

package/templates/.claude/commands/check-task.en.md

@@ -1,6 +1,6 @@
 ---
 description: "Check a task's current status and progress"
-usage: "/check-task [task-ref | --task <ref>]"
+usage: "/check-task [--task <ref> | -t <ref>]"
 disable-model-invocation: true
 ---
 

package/templates/.claude/commands/check-task.zh-CN.md

@@ -1,6 +1,6 @@
 ---
 description: "查看任务的当前状态和进度"
-usage: "/check-task [task-ref | --task <ref>]"
+usage: "/check-task [--task <ref> | -t <ref>]"
 disable-model-invocation: true
 ---
 

package/templates/.claude/commands/code-task.en.md

@@ -1,6 +1,6 @@
 ---
 description: "Code a task from its technical plan and output a report"
-usage: "/code-task [task-ref | --task <ref>]"
+usage: "/code-task [--task <ref> | -t <ref>]"
 ---
 
 Read and execute the code-task skill from `.agents/skills/code-task/SKILL.md`.

package/templates/.claude/commands/code-task.zh-CN.md

@@ -1,6 +1,6 @@
 ---
 description: "根据技术方案编码任务并输出报告"
-usage: "/code-task [task-ref | --task <ref>]"
+usage: "/code-task [--task <ref> | -t <ref>]"
 ---
 
 读取并执行 `.agents/skills/code-task/SKILL.md` 中的 code-task 技能。

package/templates/.claude/commands/commit.en.md

@@ -1,6 +1,6 @@
 ---
 description: "Commit the current changes to Git"
-usage: "/commit [task-ref | --task <ref>]"
+usage: "/commit [--task <ref> | -t <ref>]"
 ---
 
 Read and execute the commit skill from `.agents/skills/commit/SKILL.md`.

package/templates/.claude/commands/commit.zh-CN.md

@@ -1,6 +1,6 @@
 ---
 description: "提交当前变更到 Git"
-usage: "/commit [task-ref | --task <ref>]"
+usage: "/commit [--task <ref> | -t <ref>]"
 ---
 
 读取并执行 `.agents/skills/commit/SKILL.md` 中的 commit 技能。

package/templates/.claude/commands/complete-manual-validation.en.md

@@ -1,6 +1,6 @@
 ---
 description: "Mark PR manual validation as completed and update the summary comment"
-usage: "/complete-manual-validation [task-ref | --task <ref>] [pr-ref] <verification-summary>"
+usage: "/complete-manual-validation [--task <ref> | -t <ref>] [pr-ref] <verification-summary>"
 disable-model-invocation: true
 ---
 

package/templates/.claude/commands/complete-manual-validation.zh-CN.md

@@ -1,6 +1,6 @@
 ---
 description: "标记 PR 人工验证已完成并更新摘要评论"
-usage: "/complete-manual-validation [task-ref | --task <ref>] [pr-ref] <verification-summary>"
+usage: "/complete-manual-validation [--task <ref> | -t <ref>] [pr-ref] <verification-summary>"
 disable-model-invocation: true
 ---
 

package/templates/.claude/commands/complete-task.en.md

@@ -1,6 +1,6 @@
 ---
 description: "Mark a task as completed and archive it"
-usage: "/complete-task [task-ref | --task <ref>]"
+usage: "/complete-task [--task <ref> | -t <ref>] [--skip-pr] [--force]"
 ---
 
 Read and execute the complete-task skill from `.agents/skills/complete-task/SKILL.md`.

package/templates/.claude/commands/complete-task.zh-CN.md

@@ -1,6 +1,6 @@
 ---
 description: "标记任务完成并归档"
-usage: "/complete-task [task-ref | --task <ref>]"
+usage: "/complete-task [--task <ref> | -t <ref>] [--skip-pr] [--force]"
 ---
 
 读取并执行 `.agents/skills/complete-task/SKILL.md` 中的 complete-task 技能。

package/templates/.claude/commands/create-pr.en.md

@@ -1,6 +1,6 @@
 ---
 description: "Create a Pull Request to a target branch"
-usage: "/create-pr [task-ref | --task <ref>] [target-branch]"
+usage: "/create-pr [--task <ref> | -t <ref>] [target-branch]"
 ---
 
 Read and execute the create-pr skill from `.agents/skills/create-pr/SKILL.md`.

package/templates/.claude/commands/create-pr.zh-CN.md

@@ -1,6 +1,6 @@
 ---
 description: "创建 Pull Request 到目标分支"
-usage: "/create-pr [task-ref | --task <ref>] [target-branch]"
+usage: "/create-pr [--task <ref> | -t <ref>] [target-branch]"
 ---
 
 读取并执行 `.agents/skills/create-pr/SKILL.md` 中的 create-pr 技能。

package/templates/.claude/commands/plan-task.en.md

@@ -1,6 +1,6 @@
 ---
 description: "Design a technical plan for a task"
-usage: "/plan-task [task-ref | --task <ref>]"
+usage: "/plan-task [--task <ref> | -t <ref>]"
 ---
 
 Read and execute the plan-task skill from `.agents/skills/plan-task/SKILL.md`.