Add system, skill, and operations documentation

.gitignore

@@ -0,0 +1,26 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.playwright-mcp/
+.worktrees/
+prompt.txt
+
+# Local portable tool payloads and downloads. Keep small wrappers/scripts only.
+.tools/git/
+.tools/gh/
+.tools/downloads/
+
+# Local downloads, caches, and generated report runs.
+.download_wferp_*/
+.download_wferp_skill_*/
+.opencode/
+.pytest-tmp/
+.tmp/
+.wferp-llm-temp/
+pytest-cache-files-*/
+wferp-report-runs/
+
+# Runtime artifacts.
+*.sqlite3
+*.db
+*.log

.opencode/commands/phase1-start.md

@@ -0,0 +1,15 @@
+---
+description: Start the Phase 1 orchestrator checkpoint-to-new-session flow for a selected AFK issue packet
+agent: build
+subtask: false
+---
+
+Run the Phase 1 orchestrator checkpoint-to-new-session runner for issue packet `$ARGUMENTS`.
+
+1. Execute:
+!`python3 scripts/phase1_orchestrator_runner.py --issue-packet $ARGUMENTS`
+2. Read `docs/agents/runtime/context-checkpoint.yaml` after the runner updates it.
+3. Read `.opencode/runtime/new-session-request.json` after the runner writes it.
+4. Tell me the checkpoint update result, the continuation request path, and the immediate next action.
+
+Do not start worker execution yet. Stop after reporting the runner output and the generated continuation request.

.opencode/commands/show-last-root-session.md

@@ -0,0 +1,26 @@
+---
+description: Show the latest continuation root session and how to open it
+agent: build
+subtask: false
+---
+
+Read `.opencode/runtime/new-session-result.json`.
+
+Report these fields when present:
+- `status`
+- `title`
+- `reason`
+- `sourceSessionID`
+- `rootSessionID`
+- `recordedAt`
+- `tuiResumeCommand`
+- `cliOpenCommand`
+- `recommendedAction`
+- `error`
+
+If `status` is `success`, tell me exactly how to inspect the root session:
+1. In OpenCode TUI, run `/sessions` and switch to `rootSessionID`.
+2. Or run `cliOpenCommand` from a shell.
+3. In this repo's OpenCode TUI, run `/open-last-root-session` to jump directly to `rootSessionID`.
+
+If `status` is `error`, explain that no root session is available yet and include the recorded error.

.opencode/package.json

@@ -0,0 +1,9 @@
+{
+  "plugin": [
+    "./plugins/session-continuation.ts",
+    "./plugins/session-continuation-tui.ts"
+  ],
+  "dependencies": {
+    "@opencode-ai/plugin": "1.14.33"
+  }
+}

.opencode/plugins/session-continuation-tui.ts

@@ -0,0 +1,67 @@
+import { readFile } from "node:fs/promises"
+import { join } from "node:path"
+
+import type { TuiPluginModule } from "@opencode-ai/plugin/dist/tui"
+
+type NewSessionResult = {
+  status?: "success" | "error"
+  rootSessionID?: string
+  title?: string
+  error?: string
+}
+
+const NEW_SESSION_RESULT_RELATIVE_PATH = ".opencode/runtime/new-session-result.json"
+
+async function readLatestSessionResult(worktree: string): Promise<NewSessionResult | undefined> {
+  try {
+    const resultText = await readFile(join(worktree, NEW_SESSION_RESULT_RELATIVE_PATH), "utf-8")
+    return JSON.parse(resultText) as NewSessionResult
+  } catch {
+    return undefined
+  }
+}
+
+const SessionContinuationTuiPlugin: TuiPluginModule = {
+  tui: async (api) => {
+    api.command.register(() => [
+      {
+        title: "Open last root session",
+        value: "open-last-root-session",
+        description: "Open the latest continuation root session recorded by the session continuation plugin.",
+        category: "Session",
+        slash: {
+          name: "open-last-root-session",
+        },
+        onSelect: async () => {
+          const result = await readLatestSessionResult(api.state.path.worktree)
+          if (!result) {
+            api.ui.toast({
+              variant: "error",
+              title: "No continuation result",
+              message: "No .opencode/runtime/new-session-result.json file was found.",
+            })
+            return
+          }
+          if (result.status !== "success" || !result.rootSessionID) {
+            api.ui.toast({
+              variant: "error",
+              title: "Root session unavailable",
+              message: result.error ?? "The latest continuation result does not contain a root session.",
+            })
+            return
+          }
+          api.route.navigate("session", { sessionID: result.rootSessionID })
+          api.ui.toast({
+            variant: "success",
+            title: "Opened root session",
+            message: result.title
+              ? `Switched to ${result.rootSessionID} (${result.title}).`
+              : `Switched to ${result.rootSessionID}.`,
+          })
+        },
+      },
+    ])
+  },
+}
+
+export default SessionContinuationTuiPlugin

.opencode/plugins/session-continuation.ts

@@ -0,0 +1,175 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises"
+import { join } from "node:path"
+
+import { type Plugin, tool } from "@opencode-ai/plugin"
+
+const NEW_SESSION_REQUEST_RELATIVE_PATH = ".opencode/runtime/new-session-request.json"
+const NEW_SESSION_RESULT_RELATIVE_PATH = ".opencode/runtime/new-session-result.json"
+
+type NewSessionRequest = {
+  reason?: string
+  title?: string
+  agent?: string
+  prompt?: string
+}
+
+type NewSessionResult = {
+  status: "success" | "error"
+  sourceSessionID: string
+  rootSessionID?: string
+  title: string
+  reason?: string
+  error?: string
+  tuiResumeCommand?: string
+  cliOpenCommand?: string
+  recommendedAction?: string
+  recordedAt: string
+}
+
+const SAFE_PRIMARY_AGENTS = new Set(["build", "plan"])
+
+async function consumeNewSessionRequest(worktree: string): Promise<NewSessionRequest | undefined> {
+  const requestPath = join(worktree, NEW_SESSION_REQUEST_RELATIVE_PATH)
+  try {
+    const requestText = await readFile(requestPath, "utf-8")
+    await rm(requestPath, { force: true })
+    return JSON.parse(requestText)
+  } catch {
+    return undefined
+  }
+}
+
+async function writeNewSessionResult(worktree: string, result: NewSessionResult): Promise<void> {
+  const resultPath = join(worktree, NEW_SESSION_RESULT_RELATIVE_PATH)
+  await mkdir(join(worktree, ".opencode/runtime"), { recursive: true })
+  await writeFile(resultPath, `${JSON.stringify(result, null, 2)}\n`, "utf-8")
+}
+
+function buildNewSessionPrompt(request: NewSessionRequest): string {
+  return (
+    request.prompt ??
+    [
+      "Resume the autonomous Workflow ERP development workflow from checkpoint only.",
+      "Read docs/agents/runtime/context-checkpoint.yaml first.",
+      "Do not import or rely on the prior session transcript.",
+      "Use compact_payload.authoritative_refs and compact_payload.immediate_next_action as the source of truth.",
+      "Continue with the next workflow action, preserving repo role boundaries and checkpoint-only resume policy.",
+    ].join("\n")
+  )
+}
+
+function resolveBootstrapAgent(request: NewSessionRequest): string {
+  if (!request.agent) return "build"
+  const normalizedAgent = request.agent.trim().toLowerCase()
+  return SAFE_PRIMARY_AGENTS.has(normalizedAgent) ? normalizedAgent : "build"
+}
+
+async function continueInNewSession(
+  client: Parameters<Plugin>[0]["client"],
+  directory: string,
+  request: NewSessionRequest,
+): Promise<{ rootSessionID: string; title: string }> {
+  const title = request.title ?? "Continue workflow from checkpoint"
+  const created = await client.session.create({
+    query: { directory },
+    body: {
+      title,
+    },
+  })
+  if (created.error) {
+    throw new Error(`OpenCode session.create failed: ${String(created.error)}`)
+  }
+
+  const rootSessionID = created.data?.id
+  if (!rootSessionID) {
+    throw new Error("OpenCode session.create did not return a root session id")
+  }
+
+  const promptResult = await client.session.promptAsync({
+    path: { id: rootSessionID },
+    query: { directory },
+    body: {
+      agent: resolveBootstrapAgent(request),
+      parts: [
+        {
+          type: "text",
+          text: buildNewSessionPrompt(request),
+        },
+      ],
+    },
+  })
+  if (promptResult.error) {
+    throw new Error(`OpenCode session.promptAsync failed: ${String(promptResult.error)}`)
+  }
+
+  return { rootSessionID, title }
+}
+
+export const SessionContinuationPlugin: Plugin = async ({ client, directory, worktree }) => {
+  return {
+    event: async ({ event }) => {
+      if (event.type !== "session.idle") return
+
+      const newSessionRequest = await consumeNewSessionRequest(worktree)
+      if (!newSessionRequest) return
+
+      try {
+        const result = await continueInNewSession(client, directory, newSessionRequest)
+        await writeNewSessionResult(worktree, {
+          status: "success",
+          sourceSessionID: event.properties.sessionID,
+          rootSessionID: result.rootSessionID,
+          title: result.title,
+          reason: newSessionRequest.reason,
+          tuiResumeCommand: "/sessions",
+          cliOpenCommand: `opencode --session ${result.rootSessionID}`,
+          recommendedAction:
+            `Open /sessions in OpenCode TUI and switch to ${result.rootSessionID}, ` +
+            `or run opencode --session ${result.rootSessionID}.`,
+          recordedAt: new Date().toISOString(),
+        })
+      } catch (error) {
+        await writeNewSessionResult(worktree, {
+          status: "error",
+          sourceSessionID: event.properties.sessionID,
+          title: newSessionRequest.title ?? "Continue workflow from checkpoint",
+          reason: newSessionRequest.reason,
+          error: error instanceof Error ? error.message : String(error),
+          recordedAt: new Date().toISOString(),
+        })
+      }
+    },
+    tool: {
+      continue_in_new_session: tool({
+        description:
+          "Create a fresh OpenCode root session and prompt it to resume this repo workflow from docs/agents/runtime/context-checkpoint.yaml.",
+        args: {
+          reason: tool.schema.string().optional().describe("Why a fresh continuation session is being created."),
+          title: tool.schema.string().optional().describe("Optional title for the root session."),
+          agent: tool.schema.string().optional().describe("Optional OpenCode agent name for the bootstrap prompt."),
+          prompt: tool.schema.string().optional().describe("Optional custom bootstrap prompt."),
+        },
+        async execute(args, context) {
+          context.metadata({
+            title: "Continue in new session",
+            metadata: {
+              sessionID: context.sessionID,
+              reason: args.reason ?? "not specified",
+            },
+          })
+
+          const result = await continueInNewSession(client, context.directory, args)
+
+          return {
+            output: `Created root continuation session ${result.rootSessionID} from ${context.sessionID}.`,
+            metadata: {
+              sourceSessionID: context.sessionID,
+              rootSessionID: result.rootSessionID,
+              title: result.title,
+            },
+          }
+        },
+      }),
+    },
+  }
+}

.tools/activate.cmd

@@ -0,0 +1,9 @@
+@echo off
+chcp 65001 >nul
+set "PYTHONUTF8=1"
+set "PYTHONIOENCODING=utf-8"
+set "TOOL_BIN=%~dp0bin"
+set "CODEX_PYTHON=C:\Users\ivychi\.cache\codex-runtimes\codex-primary-runtime\dependencies\python"
+set "NODE_HOME=C:\Users\ivychi\util\nodejs"
+set "PATH=%TOOL_BIN%;%CODEX_PYTHON%;%NODE_HOME%;%PATH%"
+echo WFERP local tools are active for this cmd session.

.tools/activate.ps1

@@ -0,0 +1,26 @@
+$RepoRoot = Split-Path -Parent $PSScriptRoot
+
+chcp 65001 > $null
+[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+$OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+$env:PYTHONUTF8 = "1"
+$env:PYTHONIOENCODING = "utf-8"
+
+$Paths = @(
+    (Join-Path $PSScriptRoot "bin"),
+    "C:\Users\ivychi\.cache\codex-runtimes\codex-primary-runtime\dependencies\python",
+    "C:\Users\ivychi\util\nodejs"
+)
+
+$PathsToAdd = $Paths.Clone()
+[array]::Reverse($PathsToAdd)
+
+foreach ($Path in $PathsToAdd) {
+    if ((Test-Path $Path) -and (($env:Path -split ";") -notcontains $Path)) {
+        $env:Path = "$Path;$env:Path"
+    }
+}
+
+Write-Host "WFERP local tools are active for this PowerShell session."
+Write-Host "Repo: $RepoRoot"

.tools/bin/gh.cmd

@@ -0,0 +1,2 @@
+@echo off
+"%~dp0..\gh\gh.exe" %*

.tools/bin/git.cmd

@@ -0,0 +1,2 @@
+@echo off
+"%~dp0..\git\cmd\git.exe" %*

.tools/bin/pytest.cmd

@@ -0,0 +1,7 @@
+@echo off
+set "CODEX_PYTHON=C:\Users\ivychi\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe"
+if exist "%CODEX_PYTHON%" (
+  "%CODEX_PYTHON%" -m pytest %*
+) else (
+  py -3 -m pytest %*
+)

.tools/bin/python.cmd

@@ -0,0 +1,7 @@
+@echo off
+set "CODEX_PYTHON=C:\Users\ivychi\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe"
+if exist "%CODEX_PYTHON%" (
+  "%CODEX_PYTHON%" %*
+) else (
+  py -3 %*
+)