@aipper/aiws-spec 0.0.28 → 0.0.30

package/templates/workspace/.opencode/oh-my-opencode.json.example

@@ -2,16 +2,76 @@
   "agents": {
     "planner-sisyphus": {
       "enabled": true,
-      "replace_plan": false
+      "replace_plan": false,
+      "categories": [
+        "planning",
+        "autonomous"
+      ],
+      "prompt_append": "You are running inside an AIWS workspace. Before coding, read AI_PROJECT.md, REQUIREMENTS.md, and AI_WORKSPACE.md. Stay autonomous until the task is complete. Completion means: truth files read, task/change bound, required verify commands run, review/evidence written, and aiws validate . or change validate completed when applicable. Stop early only for a real blocker: missing user decision, missing credential, external dependency failure, or sandbox/permission failure."
     },
     "librarian": {
-      "enabled": true
+      "enabled": true,
+      "categories": [
+        "docs",
+        "research"
+      ]
     },
     "explore": {
-      "enabled": true
+      "enabled": true,
+      "categories": [
+        "code",
+        "analysis"
+      ]
     },
     "oracle": {
-      "enabled": true
+      "enabled": true,
+      "categories": [
+        "review",
+        "qa"
+      ]
+    }
+  },
+  "backgroundTasks": {
+    "enabled": true,
+    "maxJobs": 3,
+    "defaultTimeoutMs": 1200000
+  },
+  "experimental": {
+    "auto_resume": true
+  },
+  "aiws": {
+    "autonomy": {
+      "approval_whitelist": {
+        "enabled": true,
+        "mode": "assist-only",
+        "host_permission_mode": "manual-only",
+        "read_only_commands": [
+          "rg",
+          "cat",
+          "sed",
+          "ls",
+          "find",
+          "git status",
+          "git diff"
+        ],
+        "write_allow_paths": [
+          ".agentdocs/tmp/",
+          "changes/*/analysis/",
+          "changes/*/review/",
+          "changes/*/evidence/"
+        ],
+        "deny_paths": [
+          "secrets/",
+          ".env*"
+        ],
+        "deny_commands": [
+          "rm",
+          "mv",
+          "git commit",
+          "git push",
+          "npm publish"
+        ]
+      }
     }
   }
 }

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