@aipper/aiws-spec 0.0.29 → 0.0.30

package/templates/workspace/.opencode/plugins/aiws-inject-context.js

@@ -0,0 +1,201 @@
+/**
+ * aiws Context Injection Plugin
+ *
+ * Injects aiws context JSONL when task() is called with sub-agent types.
+ * Hook: tool.execute.before — intercepts task() calls, reads <role>-context.jsonl
+ * from changes/<id>/analysis/, and injects into the agent prompt.
+ *
+ * Reference: trellis/packages/cli/src/templates/opencode/plugins/inject-subagent-context.js
+ */
+
+import { existsSync } from "fs"
+import { join } from "path"
+import { AiwsContext, AiwsSessionJournal, debugLog } from "../lib/aiws-context.js"
+
+// Role detection — check args.subagent_type first, then fall back to prompt marker
+// Prompt should include: "role: <role>" as a line in the prompt
+const ROLE_MARKER_RE = /^\s*role\s*[:=]\s*(\w+)\s*$/im
+
+function detectRole(args, originalPrompt) {
+  // Priority 1: args.subagent_type (set by task() caller)
+  if (args?.subagent_type) {
+    const t = String(args.subagent_type).toLowerCase().replace(/^(?:trellis|aiws)-/, "")
+    if (["worker", "explorer", "reviewer", "planner"].includes(t)) return t
+  }
+  // Priority 2: "role:" marker in prompt body
+  const roleMatch = originalPrompt?.match(ROLE_MARKER_RE)
+  if (roleMatch) return roleMatch[1].toLowerCase()
+  // Priority 3: "subagent_type" or "agent_type" in prompt body
+  const typeMatch = originalPrompt?.match(/\b(?:subagent_type|agent_type)\s*[:=]\s*(\w+)\s*/im)
+  if (typeMatch) return typeMatch[1].toLowerCase().replace(/^trellis-/, "")
+  return null
+}
+
+const FIRST_REPLY_INSTRUCTION = `<aiws-context-instruction>
+After reading the JSONL context files, confirm by listing the files you read and their key points (≤3 per file).
+
+**Context file path:** changes/<change-id>/analysis/<role>-context.jsonl
+
+**Execution order:**
+1. Read the JSONL file with the Read tool
+2. Follow priority order: high → medium → low
+3. If sections defined, only read those line ranges for files > 200 lines
+4. If any file is inaccessible, flag it but continue with what's available
+
+**Your first response** must begin with:
+\`\`\`
+Read context files: [list of files read]
+Key points: [brief summary per file]
+Status: READY | NEEDS_CONTEXT
+\`\`\`
+</aiws-context-instruction>`
+
+/**
+ * Resolve the active change ID by scanning changes/ directory.
+ */
+function resolveActiveChangeId(ctx) {
+  const active = ctx.getActiveChange()
+  return active ? active.id : null
+}
+
+/**
+ * Find JSONL context file for a given role in the active change.
+ */
+function resolveRoleJsonl(ctx, changeId, role) {
+  if (!changeId || !role) return null
+  const jsonlPath = join(ctx.directory, "changes", changeId, "analysis", `${role}-context.jsonl`)
+  return existsSync(jsonlPath) ? jsonlPath : null
+}
+
+/**
+ * Build fallback context when no curated JSONL exists (G7).
+ * Injects at minimum: change ID, phase, spec index.
+ */
+function buildFallbackContext(ctx, changeId, role) {
+  const parts = []
+  parts.push(`<aiws-context-fallback>
+No curated context JSONL for role "${role}" in change "${changeId}".
+Using project context as minimal scaffold.
+</aiws-context-fallback>`)
+
+  const changeDetail = ctx.getChangeDetail(changeId)
+  if (changeDetail) {
+    const lines = [
+      `Change: ${changeDetail.id}`,
+      `Phase: ${changeDetail.phase}`,
+    ]
+    if (changeDetail.planFiles.length > 0) {
+      lines.push(`Plans: ${changeDetail.planFiles.join(", ")}`)
+    }
+    parts.push(`<change-context>\n${lines.join("\n")}\n</change-context>`)
+  }
+
+  const specIndex = ctx.getSpecIndex()
+  if (specIndex) {
+    parts.push(`<spec-index>\n${specIndex.trimEnd()}\n</spec-index>`)
+  }
+
+  parts.push(`<aiws-context-instruction>
+No JSONL context file was found for your role.
+Review the change context and spec index above for relevant constraints.
+Focus on the spec documents that apply to your task.
+If you need more context, use the Glob and Grep tools to discover the codebase.
+</aiws-context-instruction>`)
+
+  return parts.join("\n\n")
+}
+
+/**
+ * Write journal entry for a fallback context injection.
+ * Extracted to avoid repeating the sessionKey/journal creation in both fallback paths.
+ */
+function _writeFallbackJournal(ctx, input, role, changeId, reason) {
+  const sessionKey = ctx.getSessionKey({ sessionID: input?.session_id || "" })
+  if (sessionKey) {
+    try {
+      const journal = new AiwsSessionJournal(ctx.directory)
+      journal.writeDelegation(sessionKey, role, changeId, {
+        contextFiles: 0,
+        hasFallback: true,
+        reason,
+      })
+    } catch {
+      // journal write failure should never break plugin flow
+    }
+  }
+}
+
+export default async ({ directory }) => {
+  const ctx = new AiwsContext(directory)
+  debugLog("inject", "Plugin loaded, directory:", directory)
+
+  return {
+    "tool.execute.before": async (input, output) => {
+      try {
+        if (process.env.AIWS_HOOKS === "0" || process.env.AIWS_DISABLE_HOOKS === "1") {
+          return
+        }
+
+        const toolName = input?.tool?.toLowerCase()
+        if (toolName !== "task") return
+
+        const args = output?.args
+        if (!args) return
+
+        const originalPrompt = args.prompt || ""
+        if (!originalPrompt) return
+
+        // Extract role using detectRole (checks subagent_type first, then prompt markers)
+        const role = detectRole(args, originalPrompt) || "worker"
+        debugLog("inject", "Task tool called, role:", role)
+
+        // Resolve active change
+        const changeId = resolveActiveChangeId(ctx)
+        if (!changeId) {
+          debugLog("inject", "No active change found, skipping")
+          return
+        }
+
+        // Find context JSONL for this role
+        const jsonlPath = resolveRoleJsonl(ctx, changeId, role)
+        if (!jsonlPath) {
+          debugLog("inject", `No context JSONL for role "${role}" in change "${changeId}", injecting fallback`)
+          _writeFallbackJournal(ctx, input, role, changeId, "no_jsonl_file")
+          const fallbackCtx = buildFallbackContext(ctx, changeId, role)
+          args.prompt = `${fallbackCtx}\n\n---\n\n${originalPrompt}`
+          return
+        }
+
+        // Read JSONL and build context
+        const entries = ctx.readJsonlWithFiles(jsonlPath)
+        if (entries.length === 0) {
+          debugLog("inject", `Empty context JSONL for role "${role}" in change "${changeId}", injecting fallback`)
+          _writeFallbackJournal(ctx, input, role, changeId, "empty_jsonl")
+          const fallbackCtx = buildFallbackContext(ctx, changeId, role)
+          args.prompt = `${fallbackCtx}\n\n---\n\n${originalPrompt}`
+          return
+        }
+
+        const contextBlock = ctx.buildContextBlock(entries)
+        debugLog("inject", `Injected context for role "${role}", entries: ${entries.length}`)
+
+        // Record delegation event to journal
+        const sessionKey = ctx.getSessionKey({ sessionID: input?.session_id || "" })
+        if (sessionKey) {
+          const journal = new AiwsSessionJournal(ctx.directory)
+          journal.writeDelegation(sessionKey, role, changeId, {
+            contextFiles: entries.length,
+            originalPromptSnippet: originalPrompt.slice(0, 120),
+            hasFallback: false,
+          })
+        }
+
+        // Prepend context + instruction to the prompt
+        args.prompt = `${contextBlock}\n\n${FIRST_REPLY_INSTRUCTION}\n\n---\n\n${originalPrompt}`
+
+      } catch (error) {
+        debugLog("inject", "Error in tool.execute.before:", error.message, error.stack)
+      }
+    },
+  }
+}

package/templates/workspace/.opencode/plugins/aiws-session-start.js

@@ -0,0 +1,86 @@
+/**
+ * aiws Session Start Plugin
+ *
+ * Injects aiws context (spec index, change status, handoff) when user
+ * sends the first message in a new session.
+ *
+ * Hook: chat.message — modifies the output to prepend context.
+ *
+ * Reference: trellis/packages/cli/src/templates/opencode/plugins/session-start.js
+ */
+
+import { AiwsContext, buildSessionContext, contextCollector, debugLog } from "../lib/aiws-context.js"
+
+export default async ({ directory, client }) => {
+  const ctx = new AiwsContext(directory)
+  debugLog("session", "Plugin loaded, directory:", directory)
+
+  return {
+    event: ({ event }) => {
+      try {
+        if (event?.type === "session.compacted" && event?.properties?.sessionID) {
+          contextCollector.clear(event.properties.sessionID)
+          debugLog("session", "Cleared processed flag after compaction for session:", event.properties.sessionID)
+        }
+      } catch (error) {
+        debugLog("session", "Error in event hook:", error instanceof Error ? error.message : String(error))
+      }
+    },
+
+    "chat.message": async (input, output) => {
+      try {
+        const sessionKey = ctx.getSessionKey(input)
+        if (!sessionKey) {
+          debugLog("session", "No session key available, skipping")
+          return
+        }
+
+        const agent = input.agent || ""
+        if (agent && (agent.startsWith("trellis-") || agent.startsWith("aiws-"))) {
+          debugLog("session", "Skipping sub-agent turn:", agent)
+          return
+        }
+
+        if (process.env.AIWS_HOOKS === "0" || process.env.AIWS_DISABLE_HOOKS === "1") {
+          debugLog("session", "Skipping — AIWS_HOOKS disabled")
+          return
+        }
+
+        if (process.env.OPENCODE_NON_INTERACTIVE === "1") {
+          debugLog("session", "Skipping — non-interactive mode")
+          return
+        }
+
+        if (contextCollector.isProcessed(sessionKey)) {
+          debugLog("session", "Skipping — session already processed:", sessionKey)
+          return
+        }
+
+        const context = buildSessionContext(ctx, input)
+        debugLog("session", "Built context, length:", context.length)
+
+        if (!context) {
+          debugLog("session", "Empty context, nothing to inject")
+          return
+        }
+
+        const parts = output?.parts || []
+        const textPartIndex = parts.findIndex(p => p.type === "text" && p.text !== undefined)
+
+        if (textPartIndex !== -1) {
+          const originalText = parts[textPartIndex].text || ""
+          parts[textPartIndex].text = `${context}\n\n---\n\n${originalText}`
+          debugLog("session", "Injected context into chat.message text part, length:", context.length)
+        } else {
+          const injectedPart = { type: "text", text: context }
+          parts.unshift(injectedPart)
+          debugLog("session", "Prepended new text part with context, length:", context.length)
+        }
+
+        contextCollector.markProcessed(sessionKey)
+      } catch (error) {
+        debugLog("session", "Error in chat.message:", error.message, error.stack)
+      }
+    },
+  }
+}

package/templates/workspace/.opencode/plugins/aiws-workflow-state.js

@@ -0,0 +1,116 @@
+/**
+ * aiws Workflow State Injection Plugin
+ *
+ * Per-turn chat.message breadcrumb showing active change + current phase.
+ * Unlike session-start, this fires on EVERY user message so long
+ * conversations don't lose context of what's being worked on.
+ *
+ * Reference: trellis/packages/cli/src/templates/opencode/plugins/inject-workflow-state.js
+ */
+
+import { AiwsContext, AiwsSessionJournal, debugLog } from "../lib/aiws-context.js"
+
+/**
+ * Build the workflow-state breadcrumb block.
+ */
+function buildBreadcrumb(change, phase) {
+  const parts = []
+  parts.push("<workflow-state>")
+
+  if (change) {
+    parts.push(`Active Change: ${change.id}`)
+    parts.push(`Change Dir: changes/${change.id}/`)
+
+    if (change.planFiles.length > 0) {
+      parts.push(`Plans: ${change.planFiles.slice(0, 3).join(", ")}`)
+    }
+  } else {
+    parts.push("Active Change: none")
+  }
+
+  if (phase) {
+    parts.push(`Phase: ${phase} (${AiwsContext.PHASES.indexOf(phase) + 1}/${AiwsContext.PHASES.length})`)
+  }
+
+  // Phase-specific next actions — aligned with AiwsContext.PHASES state machine
+  // Subagent-first policy: ready-for-dev defaults to aiws-worker; in-progress defaults to aiws-reviewer
+  const nextActions = {
+    intake: "Next: ws-plan to create a change and execution plan",
+    planning: "Next: ws-plan-verify to review the plan, or ws-dev to begin implementation",
+    "ready-for-dev": "Next: dispatch aiws-worker (subagent-first); main session coordinates, does not write code directly",
+    "in-progress": "Next: dispatch aiws-reviewer + ws-review to audit changes",
+    review: "Next: ws-commit to validate and commit",
+    finished: "Next: ws-finish to finalize and archive the change",
+  }
+  if (phase && nextActions[phase]) {
+    parts.push(nextActions[phase])
+  }
+
+  if (!change && !phase) {
+    parts.push("No active work detected. Start with ws-preflight or ws-plan.")
+  }
+
+  // Available phases reference — aligned with AiwsContext.PHASES
+  parts.push(`Phases: ${AiwsContext.PHASES.join(" → ")}`)
+
+  parts.push("</workflow-state>")
+  return parts.join("\n")
+}
+
+export default async ({ directory }) => {
+  const ctx = new AiwsContext(directory)
+  debugLog("workflow-state", "Plugin loaded, directory:", directory)
+
+  return {
+    "chat.message": async (input, output) => {
+      try {
+        // Skip sub-agent turns
+        const agent = input?.agent || ""
+        if (agent.startsWith("trellis-") || agent.startsWith("aiws-")) {
+          debugLog("workflow-state", "Skipping subagent turn:", agent)
+          return
+        }
+
+        if (process.env.AIWS_HOOKS === "0" || process.env.AIWS_DISABLE_HOOKS === "1") {
+          return
+        }
+
+        if (process.env.OPENCODE_NON_INTERACTIVE === "1") {
+          return
+        }
+
+        if (!ctx.isAiwsProject()) {
+          return
+        }
+
+        const change = ctx.getActiveChange()
+        const phase = change ? change.phase : null
+        const breadcrumb = buildBreadcrumb(change, phase)
+
+        // Inject into the output text part (no dedup — show every turn)
+        const parts = output?.parts || []
+        const textIdx = parts.findIndex(p => p.type === "text" && p.text !== undefined)
+        if (textIdx !== -1) {
+          parts[textIdx].text = `${breadcrumb}\n\n${parts[textIdx].text}`
+        } else {
+          parts.unshift({ type: "text", text: breadcrumb })
+        }
+
+        debugLog("workflow-state", "Injected breadcrumb:", change?.id || "none", "phase:", phase || "none")
+
+        // Record breadcrumb event to journal (non-blocking)
+        try {
+          const sessionKey = ctx.getSessionKey({ sessionID: input?.session_id || "" })
+          if (sessionKey) {
+            const journal = new AiwsSessionJournal(ctx.directory)
+            journal.writeBreadcrumb(sessionKey, phase || "unknown", change?.id || null)
+          }
+        } catch {
+          // Journal write failure should never break the plugin
+        }
+      } catch (error) {
+        debugLog("workflow-state", "Error in chat.message:", error instanceof Error ? error.message : String(error))
+      }
+    },
+  }
+}

package/templates/workspace/.opencode/scripts/ws-plan-gen-submodule-targets.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# ws-plan: generate submodules.targets for the current change
+# Usage: bash ws-plan-gen-submodule-targets.sh <change-id>
+set -euo pipefail
+
+change_id="${1:?missing change_id}"
+targets=".aiws/changes/${change_id}/submodules.targets"
+
+mkdir -p ".aiws/changes/${change_id}"
+
+if [[ -f "${targets}" ]]; then
+  bak="${targets}.bak.$(date -u +%Y%m%d-%H%M%SZ)"
+  cp "${targets}" "${bak}"
+  echo "info: backup: ${bak}"
+fi
+
+: > "${targets}"
+echo "# path<TAB>target_branch<TAB>remote(optional, default=origin)" >> "${targets}"
+
+while read -r key sub_path; do
+  name="${key#submodule.}"; name="${name%.path}"
+  b="$(git config --file .gitmodules --get "submodule.${name}.branch" 2>/dev/null || true)"
+  [[ "${b:-}" == "." ]] && b="$(git branch --show-current)"  # '.' means "follow superproject branch"
+  printf "%s\t%s\t%s\n" "${sub_path}" "${b:-<fill-me>}" "origin" >> "${targets}"
+done < <(git config --file .gitmodules --get-regexp '^submodule\..*\.path$' 2>/dev/null || true)
+
+echo "ok: wrote ${targets}"

package/templates/workspace/.opencode/scripts/ws-plan-setup-worktree.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# ws-plan: create change context with worktree/submodule support
+# Usage: bash ws-plan-setup-worktree.sh <change-id>
+set -euo pipefail
+
+change_id="${1:?missing change_id}"
+
+# Guard: refuse to create context on dirty working tree
+if [[ -n "$(git status --porcelain)" ]]; then
+  echo "error: working tree dirty before ws-plan creates change context"
+  echo "hint: commit/stash first, or continue inside an existing change/<change-id> context"
+  exit 2
+fi
+
+has_commits=0
+git rev-parse --verify HEAD >/dev/null 2>&1 && has_commits=1
+
+has_submodules=0
+if [[ -f .gitmodules ]] && git config --file .gitmodules --get-regexp '^submodule\..*\.path$' >/dev/null 2>&1; then
+  has_submodules=1
+fi
+
+if [[ "${has_commits}" -eq 1 ]]; then
+  if [[ "${has_submodules}" -eq 1 ]]; then
+    aiws change start "${change_id}" --hooks --worktree --submodules
+  else
+    aiws change start "${change_id}" --hooks --worktree
+  fi
+else
+  aiws change start "${change_id}" --hooks --no-switch
+fi

package/templates/workspace/.opencode/skills/using-aiws/SKILL.md

@@ -7,6 +7,12 @@ description: 使用时机：新会话开始、不确定下一步做什么时。
 
 目标：默认入口，先读真值文件，判定当前任务 workflow，再进入具体 `ws-*` skill。若意图不明确：先澄清，不直接进入实现。
 
+## 编排约束
+
+- **不直接实现**：`using-aiws` 自身不是实现阶段；只判 workflow、读真值、路由到对应 `ws-*`。主 session 不直接写代码。
+- **上下文先于判决**：路由 `direct_implementation` 前必须先收集项目上下文——具体检查：`git status --porcelain`（已改动文件数）、`git diff --stat`（改动行范围）、`AI_WORKSPACE.md` 中声明的验证命令可行性。仅当改动文件数 ≤ 3 且改动总行数 ≤ 100 且验证入口明确时，才可判 direct。
+- **意图不明先澄清**：`routeTo=clarify` 时必须停止并问 1-3 个关键问题，不猜测。
+
 阶段定位：bootstrap/router 阶段；负责分流，不直接完成实现。
 
 ## 必需输入
@@ -36,24 +42,47 @@ description: 使用时机：新会话开始、不确定下一步做什么时。
 - 若未检测到：输出 `standard-opencode`
 - 若缺失任一真值文件 → route = `$ws-preflight`，建议先 `aiws init .`
 
+### 1.5 Per-turn Breadcrumb（必做）
+
+每轮对话开始时强制读取当前 change 状态（`changes/<change-id>/.ws-change.json` 或 phase 状态文件），输出 `[workflow-state:PHASE/N]` breadcrumb 标记。
+
+目的：即使 context 被压缩，breadcrumb 也能让 AI 知道当前处于哪个阶段、上次做到哪一步。
+
+格式：`[workflow-state:PHASE_NAME/N]`，其中 PHASE_NAME 取自 standardChain，N 为步骤序号。
+
 ### 2. 路由判定
 
 根据 `packages/spec/docs/workflow-router-rules.json` 判定：
 
+- 路由前先读上下文：判 direct_implementation 前，router 必须先收集项目上下文（git status、涉及文件范围），确认是真正的单文件修复，再决定 direct vs plan。
+
+上下文收集清单（判 direct_implementation 前必须完成）：
+- `git status --porcelain` — 确认未提交改动范围
+- `git diff --stat` — 确认改动文件数量
+- 改动涉及 ≤2 文件且均在已知路径 → 可判 direct
+- 改动涉及 ≥3 文件或含未知路径 → 必须走 ws-plan
+
 | 意图 | Route |
 |------|-------|
 | 需求/验收/合同变更 | `$ws-req-review` |
 | 评审/审计/找风险 | `$ws-review` |
 | finish/merge/push/cleanup | `$ws-finish` |
 | handoff/archive | `$ws-handoff` |
-| 先出设计方案 | `$ws-design` |
-| 更新规范/验收标准 | `$ws-spec-update` |
+| 先出设计方案 | `$ws-plan`（设计作为 plan 阶段一部分） |
+| 更新规范/验收标准 | `$ws-req-change`（需求变更需先 review） |
 | 中大型实现 | `$ws-plan` |
 | 小步明确实现/修复 | `$ws-dev` |
 | 极简修复 | `$ws-dev-lite` |
+| Subagent 不可用 | 回退单 agent + 工件模式 |
 
 注：`$ws-dev` 默认走 subagent-first 策略（详见 `packages/spec/docs/opencode-subagent-first.md`）。主 session 应优先通过 `$ws-delegate` 派发 `aiws-worker`，除非用户明确说"直接改"或"do it inline"。
 
+**Escape Hatch**：若用户明确说"跳过流程"/"直接改"/"do it inline"，允许走 `direct_implementation` 路由，但必须：
+1. 输出 `[escape-hatch: direct-implementation]` 标记
+2. 仍须归因到 Req_ID / Problem_ID
+3. 仍须有可复现验证入口
+4. 仍须落盘 evidence 标记 escape-hatch 使用原因
+
 ### 3. 意图不明确
 
 只问 1-3 个关键问题，明确缺什么（意图、Req_ID/Problem_ID、verify、change 上下文），然后停止。
@@ -82,10 +111,17 @@ description: 使用时机：新会话开始、不确定下一步做什么时。
 └──────────────────┴──────────────────────────────────────────────┘
 ```
 
+Subagent 不可用时的降级路径：
+- ready-for-dev 无 subagent → 当前 agent 直接执行 ws-dev（走 inline escape hatch）
+- in-progress 无 reviewer → 当前 agent 自审（走 evaluate-optimize 1 轮）
+- review 无 oracle → 当前 agent 本地 review（不阻断流程）
+
 特殊状态：
 - 上次 delegation 返回 `BLOCKED` → 先解决 blocker 再继续
 - 上次 delegation 返回 `NEEDS_CONTEXT` → 补 context JSONL 后重新派发
 - Subagent-first 默认：`ready-for-dev` / `in-progress` 默认派发 worker/reviewer
+- Subagent 不可用时：降级为当前 agent 直接执行，但必须在 evidence 中记录降级原因
+- Subagent 不可用时回退：单 agent 模式 + 显式维护 `changes/<id>/` 工件（handoff-evidence.md, analysis/, patches/）；不阻断流程，但须标注 `mode: single-agent`
 
 ### 5. 输出路由
 
@@ -105,3 +141,4 @@ Next: <继续执行对应 skill，或提出澄清问题>
 - Router 自己不实现代码；不给 route 前不直接改代码
 - 一次只选一个主 route
 - 若复杂度升高：`$ws-dev` 回退到 `$ws-plan`；`$ws-finish` 回退到前置门禁
+- 若 subagent 不可用：回退为单 agent 执行，但须维护与 subagent 模式等价的工件结构（handoff、evidence、review 文件），确保后续 session 可接力

package/templates/workspace/.opencode/skills/ws-commit/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: ws-commit
-description: Thin wrapper for `aiws ws-commit`
+description: Thin wrapper for `aiws commit`
 ---
 
 # ws-commit
 
-Thin skill wrapper. Delegates to `aiws ws-commit`. See `aiws ws-commit --help` for details.
+Thin skill wrapper. Delegates to `aiws commit`. See `aiws commit --help` for details.
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-commit
+  ./node_modules/.bin/aiws commit
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-commit
+  aiws commit
 else
-  npx @aipper/aiws ws-commit
+  npx @aipper/aiws commit
 fi
 ```

package/templates/workspace/.opencode/skills/ws-delegate/SKILL.md

@@ -7,6 +7,11 @@ description: 使用时机：需要拆分子任务、委托给子 agent 时。触
 
 目标：在 OpenCode 中，优先借用 `oh-my-opencode` 的现有 agent 做任务拆分；若 oMo 不可用，再回退为普通 OpenCode delegation / 单 agent 执行。
 
+## 核心约束
+
+- **Subagent-First**：主 session 只做编排与收敛，不直接写实现代码。所有产出必须由 subagent 完成并可追溯到具体 worker。
+- **Handoff 证据**：每轮委托完成后，worker 必须产出结构化 handoff 到 `changes/<id>/handoff-evidence.md`（完成项、未完成项、残余风险），供主 session 收敛判断。handoff 文件缺失等同于委托未完成。
+
 ## 必需输入
 
 - 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
@@ -24,12 +29,18 @@ description: 使用时机：需要拆分子任务、委托给子 agent 时。触
 - `Evidence:` 产物路径
 - `Next:` 回到 `ws-dev` / `ws-review` / `ws-commit` / `ws-finish`
 
+## 执行要求
+
+- 主 session 不直接改代码：所有实现与验证产物必须由 subagent 产出并向 handoff 记录可追溯
+- handoff 证据：手交材料中须含 delegate round number、产出文件路径、已知未关闭项
+
 ## 阻断条件
 
 - 任务未绑定
 - 没有写清委托边界
 - 上下文策展未执行（未生成 JSONL 或未在 prompt 中引用）
 - 无法判断当前是否可用 oMo，又不能接受回退
+- handoff 文件 `changes/<id>/handoff-evidence.md` 缺失或为空（委托返回后必须检查）
 
 ## 角色映射
 
@@ -40,6 +51,16 @@ description: 使用时机：需要拆分子任务、委托给子 agent 时。触
 | `reviewer` | `@oracle` |
 | `integrator` | 当前主 agent |
 
+**推荐标准角色**（source: `workflow-delegation-contracts.json` standardRoles）：
+
+| 角色 | 职责 | 读取范围 | 写入范围 |
+|------|------|----------|----------|
+| `implementer` | 代码+测试实现 | 真值文件+change上下文 | 代码文件+测试文件+evidence/ |
+| `reviewer` | 独立审查 | 真值文件+diff+evidence | review/*.md |
+| `researcher` | 分析探索 | 真值文件+外部文档 | analysis/*.md |
+
+这些角色为建议非强制；委托时优先参考但允许根据任务需要调整。
+
 ## 连续执行循环（Worker → Reviewer → Fix）
 
 默认闭环（详见 `packages/spec/docs/opencode-subagent-first.md`）：
@@ -109,6 +130,7 @@ Context Curation: changes/<id>/analysis/worker-context.jsonl
 - [ ] 解析 Status 行
 - [ ] 非 DONE → 按状态处理规则行动
 - [ ] 非 DONE → 记录决策到 `delegation-decisions.md`
+- [ ] handoff 文件 `changes/<id>/handoff-evidence.md` 已存在且非空
 
 安全：
 - 不让 `ws-delegate` 变成第二套 orchestrator

package/templates/workspace/.opencode/skills/ws-deliver/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: ws-deliver
-description: Thin wrapper for `aiws ws-deliver`
+description: Thin wrapper for `aiws deliver`
 ---
 
 # ws-deliver
 
-Thin skill wrapper. Delegates to `aiws ws-deliver`. See `aiws ws-deliver --help` for details.
+Thin skill wrapper. Delegates to `aiws deliver`. See `aiws deliver --help` for details.
 
 ```bash
 if [[ -x "./node_modules/.bin/aiws" ]]; then
-  ./node_modules/.bin/aiws ws-deliver
+  ./node_modules/.bin/aiws deliver
 elif command -v aiws >/dev/null 2>&1; then
-  aiws ws-deliver
+  aiws deliver
 else
-  npx @aipper/aiws ws-deliver
+  npx @aipper/aiws deliver
 fi
 ```