forgedock 1.6.0 → 1.7.1

package/docs/OPENCODE.md

@@ -1,312 +1,280 @@
 # OpenCode Support
 
-ForgeDock has an OpenCode adapter that lets OpenCode run the ForgeDock pipeline
-using its native bash tool and the `gh` CLI.
-
-## Architecture
-
-Shared source:
-- `commands/**/*.md` remains the workflow spec for all runtimes
-
-Claude Code wrapper:
-- `install.sh` (or `npx forgedock`) symlinks command files into `~/.claude/commands/`
-
-Codex wrapper:
-- `install-codex.sh` generates namespaced skills in `~/.codex/skills/`
-
-Aider wrapper:
-- `install-aider.sh` writes `~/.aider-forge.md` loaded via `--read`
-
-**OpenCode wrapper** (this document):
-- `install-opencode.sh` writes `~/.opencode-forge.md` — a conventions file
-  OpenCode loads via the `instructions` field in `opencode.json`
-- `install-opencode.sh` also patches `~/.config/opencode/opencode.json` to
-  register ForgeDock pipeline commands as native OpenCode slash commands
-  (`/work-on`, `/review-pr`, `/quality-gate`, `/orchestrate`)
-
-This is a conventions-file + command-registration architecture. The shared
-`commands/` directory remains the single source of truth — the adapter
-registers entry points that read from it.
-
-## Feasibility
-
-OpenCode is the **highest-fidelity** non-Claude Code adapter because:
-
-| Capability | Requirement | OpenCode support |
-|-----------|-------------|-----------------|
-| Load instruction files | `instructions` field in `opencode.json` | Native |
-| Execute shell commands | `gh`, `git`, standard tools | Native `Bash` tool |
-| Read/write files | File editing | Native `Read`/`Write`/`Edit` tools |
-| GitHub API | `gh` CLI | Via `Bash("gh ...")` |
-| Multi-step workflows | Follow sequential instructions | Supported |
-| Compaction resilience | Re-read GitHub state at phase start | Supported (via `Bash("gh ...")`) |
-| Native slash commands | `/work-on 967` in TUI | Via `command` config |
-| Tool name parity | Same tool names as Claude Code | Direct — no translation needed |
-
-**Key advantage over Aider and Cursor**: OpenCode shares Claude Code's tool
-names (`Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `WebFetch`) — no
-translation table required for most operations. Pipeline command specs run
-nearly unmodified.
+ForgeDock's OpenCode integration uses native OpenCode commands, subagents, and
+plugins while keeping `commands/**/*.md` as the only workflow source of truth.
+The older global-instructions and `opencode.json` patching adapter has been
+retired because it loaded ForgeDock prose into unrelated sessions, registered
+only four commands, used the wrong argument placeholder, and assumed OpenCode
+had neither skills nor subagents.
 
 ## Install
 
-### Option A — standalone bash installer
-
 ```bash
-cd /path/to/forgedock
-./install-opencode.sh
+npx forgedock opencode install
 ```
 
-This writes `~/.opencode-forge.md` with ForgeDock conventions and patches
-`~/.config/opencode/opencode.json` with:
-- `instructions`: adds `~/.opencode-forge.md` to OpenCode's system prompt
-- `command`: registers `/work-on`, `/review-pr`, `/quality-gate`, `/orchestrate`
-
-### Option B — via npx forgedock
-
-When `opencode` is detected on your PATH, `npx forgedock` writes
-`~/.opencode-forge.md` and patches `opencode.json` as an additional install
-step. No existing Claude Code files are affected.
+For the optional command tier:
 
 ```bash
-npx forgedock
-```
-
-## Usage
-
-### Native slash commands (recommended)
-
-After running `install-opencode.sh`, use ForgeDock commands in the OpenCode
-TUI:
-
-```
-/work-on 967
-/review-pr 123
-/quality-gate
+npx forgedock opencode install --extras
 ```
 
-Or headlessly via `opencode run`:
+Restart OpenCode after install or update. OpenCode loads commands, skills, and
+plugins at startup.
 
-```bash
-opencode run --command work-on "967"
-opencode run --command review-pr "123"
-```
+The native adapter does not add or modify user-owned OpenCode settings. It
+writes only ForgeDock-owned files under OpenCode's config directory and records
+them in `forgedock/manifest.json` for safe updates and removal.
 
-### Manual pipeline loading
+## Usage
 
-Read a pipeline command spec directly and follow it:
+Commands are namespaced to avoid collisions:
 
+```text
+/forge/work-on 967
+/forge/review-pr 123
+/forge/quality-gate
+/forge/orchestrate milestone checkout-v2
 ```
-Read the file /path/to/forgedock/commands/work-on.md and run the pipeline for issue 967.
-```
-
-OpenCode will load the spec and execute each phase using its native tools.
-
-### Phase routing with forge-run.sh
 
-`forge-run.sh` emits JSON phase state for the current issue without invoking
-an LLM. Use it to determine the current pipeline phase:
+Headless OpenCode invocation uses the same command names:
 
 ```bash
-Bash("/path/to/forgedock/scripts/forge-run.sh work-on 967 -R OWNER/REPO")
+opencode run --command forge/work-on "967"
 ```
 
-Output (NDJSON):
-```json
-{"event":"phase_detected","command":"work-on","issue":967,"phase":"no-comments","ts":"..."}
-{"event":"phase_detail","phase":"no-comments","lane":"feature","branch":"milestone/dev-exp","labels":[]}
-{"event":"action_required","phase":"no-comments","action":"No pipeline activity detected. Invoke /work-on 967 to start investigation.","ts":"..."}
-```
-
-## Tool Translation
-
-OpenCode and Claude Code share the same tool names. Most pipeline operations
-run without modification:
-
-| Claude Code | OpenCode | Notes |
-|-------------|----------|-------|
-| `Bash("git status")` | `Bash("git status")` | Direct |
-| `Read("path/to/file")` | `Read("path/to/file")` | Direct |
-| `Write("path", content)` | `Write("path", content)` | Direct |
-| `Edit("path", ...)` | `Edit("path", ...)` | Direct |
-| `Glob("**/*.md")` | `Glob("**/*.md")` | Direct |
-| `Grep(pattern, path)` | `Grep(pattern, path)` | Direct |
-| `WebFetch(url)` | `WebFetch(url)` | Direct |
-| `Skill("work-on", args="123")` | Read `commands/work-on.md` | No skill loader — read spec directly |
-| `Skill("review-pr", args="456")` | Read `commands/review-pr.md` | No skill loader — read spec directly |
-| `Agent(...)` / `Task(...)` | Continue the sub-task inline | No sub-agent model; inline it |
-
-### Nested Skill references
+## Architecture
 
-When a command spec calls `Skill("x")` or references another command, read
-the referenced command spec directly:
+The installed command files are thin entry adapters. A command loads exactly
+one authoritative spec from ForgeDock's stable installation and translates
+runtime mechanics without copying workflow behavior.
 
+```text
+OpenCode /forge/work-on
+  -> small generated command adapter
+  -> commands/work-on.md
+  -> only the nested phase spec reached by the dispatcher
+  -> GitHub labels and FORGE annotations remain durable state
 ```
-# Load the referenced command spec:
-Read("/path/to/forgedock/commands/quality-gate.md")
-```
-
-Map command names to file paths:
-- `Skill("work-on")` → `commands/work-on.md`
-- `Skill("review-pr")` → `commands/review-pr.md`
-- `Skill("quality-gate")` → `commands/quality-gate.md`
-- `Skill("orchestrate")` → `commands/orchestrate.md`
 
-## GitHub Operations
-
-All FORGE annotations are written to GitHub issue/PR comments via the `gh`
-CLI. Use `Bash()` for every GitHub operation.
-
-### Label management
-
-```bash
-Bash("gh issue edit 123 -R OWNER/REPO --add-label 'workflow:investigating'")
-Bash("gh issue edit 123 -R OWNER/REPO --remove-label 'workflow:investigating'")
+The generated plugin has no prompt text. It:
+
+- injects `FORGE_HOME` into OpenCode shell environments;
+- defaults `subagent_depth` to 2 when the user has not configured it, while
+  preserving explicit lower limits;
+- grants the built-in `general` subagent permission to invoke native `task`
+  unless the user explicitly configured a task permission;
+- opts into OpenCode background subagents by default so each completed issue can
+  wake the parent orchestrator independently; set
+  `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=false` to opt out;
+- selects Git Bash on Windows only when the user has not explicitly configured
+  an OpenCode shell, because the shared workflows and helper scripts use Bash.
+
+The adapter also registers every eligible ForgeDock workflow as a native
+OpenCode skill. Top-level and nested source paths are normalized to valid
+hyphenated skill names while the wrapper continues to point at the authoritative
+source file:
+
+```text
+commands/work-on.md             -> skills/work-on/SKILL.md
+commands/work-on/investigate.md -> skills/work-on-investigate/SKILL.md
+commands/review-pr.md           -> skills/review-pr/SKILL.md
 ```
 
-### Reading existing annotations
-
-```bash
-Bash("gh api repos/OWNER/REPO/issues/123/comments \
-  --jq '.[] | select(.body | contains(\"FORGE:INVESTIGATOR\")) | .body'")
+The wrapper is intentionally thin. It carries the workflow's `name` and
+`description` frontmatter, preserves the current-context arguments, and loads
+only the referenced `commands/**/*.md` spec.
+
+OpenCode's provider configuration remains entirely user-owned. ForgeDock does
+not require Anthropic when invoked through OpenCode; any provider and model
+supported by the user's OpenCode configuration can execute the commands.
+
+## Token Efficiency
+
+The adapter follows these rules:
+
+- No global ForgeDock `instructions` entry.
+- Top-level user entry commands are registered under `/forge/*`.
+- Every eligible workflow is registered as a native skill so nested
+  `Skill(...)` dispatch resolves through OpenCode's `skill` tool instead of
+  filesystem guessing.
+- Nested phase specs are loaded only when their dispatcher reaches them.
+- Task/Agent work uses OpenCode subagents only for the parallelism, isolation,
+  or context-pressure cases required by the shared workflow.
+- Orchestration dispatches independent issues with `task(background=true)` and
+  processes each injected task-result event immediately; it does not wait for a
+  wave or the slowest sibling.
+- GitHub state and the durable engine remain the recovery source instead of
+  replaying prior prompt context.
+
+The generated adapter preamble is intentionally small. It maps Claude Code's
+in-conversation `Skill(...)` loading to the normalized native skill name and
+authoritative shared spec. It maps isolated `Task(...)` and permitted
+`Agent(...)` calls to OpenCode's native `task` tool. Before the shared review
+specs evaluate Claude's literal `Task`/`Agent` names, an OpenCode runtime marker
+selects `DISPATCH_TOOL=task`; the absence of those Claude names must not produce
+a false `FORGE:REVIEW_BLOCKED` result.
+
+Every isolated review dispatch uses the explicit native argument shape. Every
+native task call must include the schema-required `subagent_type` at the top
+level alongside its `description` and `prompt`:
+
+```js
+{ description: "...", prompt: "...", subagent_type: "general", background: true }
 ```
 
-### Writing a FORGE annotation comment
-
-For multi-line comment bodies, write the content to a temp file first:
-
-```bash
-# Write comment body to temp file (avoids shell quoting issues)
-Write("/tmp/forge_comment.md", """<!-- FORGE:INVESTIGATOR -->
-## Investigation Report
-
-**Verdict**: CONFIRMED
-...
-<!-- INVESTIGATION:COMPLETE -->""")
+Implementation and review work uses `general`; read-only discovery uses
+`explore`. Claude `general-purpose` maps to `general` and
+`codebase-explorer` maps to `explore`. When a source task omits its type, the
+generated adapter safely defaults it to `general`; unsupported types stop with
+`FORGE_OPENCODE_CAPABILITY_ERROR` instead of reaching schema validation.
+If the native `task` capability itself is unavailable, the workflow posts
+`FORGE:REVIEW_BLOCKED` and stops rather than falling back to inline review or
+another pipeline controller.
+The generated plugin adds `background: true` unless
+`OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=false` is explicitly set.
 
-Bash("gh issue comment 123 -R OWNER/REPO --body \"$(cat /tmp/forge_comment.md)\"")
-```
+`commands/work-on.md` is still a large entry dispatcher and is loaded in full,
+matching the Claude Code path. The adapter prevents additional eager loading,
+but reducing that entry cost requires decomposing the shared authoritative spec
+rather than maintaining an OpenCode-only copy.
 
-### Creating a PR
+## Lifecycle
 
 ```bash
-Write("/tmp/pr_body.md", """## Summary
-...
-
-Closes #967""")
-
-Bash("gh pr create -R OWNER/REPO \
-  --base milestone/developer-experience-distribution \
-  --head feat/opencode-adapter-967 \
-  --title 'feat: OpenCode adapter (#967)' \
-  --body \"$(cat /tmp/pr_body.md)\"")
+npx forgedock opencode status
+npx forgedock opencode install          # update/repair
+npx forgedock opencode install --extras
+npx forgedock opencode uninstall
 ```
 
-## Worktrees
-
-ForgeDock uses git worktrees to isolate branch work. Create one with:
-
-```bash
-Bash("git fetch origin")
-Bash("git worktree add .claude/worktrees/feat-my-feature-123 \
-  -b feat/my-feature-123 origin/staging")
+`npx forgedock update` also refreshes an existing managed OpenCode adapter,
+including its plugin and generated skills. It preserves the installed core vs.
+`--extras` tier, migrates the sentinel-marked legacy adapter, and does not
+install OpenCode files when no ForgeDock adapter is already registered.
+
+Updates are deterministic and prune stale ForgeDock-owned command files.
+Uninstall removes only files listed in the ownership manifest and still marked
+with a ForgeDock sentinel. User-owned commands, plugins, and files placed in
+the `forgedock/` namespace are never removed; that namespace is pruned only
+when it is empty.
+For backward compatibility, install and uninstall may rewrite `opencode.json`
+only to remove legacy entries whose two-key `description` and `template` still
+exactly match one of the definitions emitted by the retired adapter and point to
+the active ForgeDock home (or the home recorded in the ownership manifest during
+uninstall), and the sentinel-marked legacy instructions file is present. It also
+removes references to that managed `~/.opencode-forge.md` instructions file. The
+migration does not rewrite `opencode.jsonc`. User-owned settings and customized commands are preserved;
+definitions with extra keys, edited fields, different
+paths, a missing ownership marker, or ambiguous ownership are left in place. If
+a legacy config cannot be parsed or written, the migration leaves the legacy
+artifacts in place.
+
+## Locations
+
+Default global location:
+
+```text
+~/.config/opencode/
+  commands/forge/*.md
+  skills/<workflow-name>/SKILL.md
+  plugins/forgedock.js
+  forgedock/manifest.json
 ```
 
-Work inside the worktree for all file edits and commits:
+`XDG_CONFIG_HOME` and `OPENCODE_CONFIG_DIR` are honored when set. An npm/npx
+installation first persists the required ForgeDock payload under `~/.forge` so
+generated commands never point into an evictable package cache. A stable Git
+clone is referenced directly.
+
+## Current Boundary
+
+This integration provides native interactive command and subagent execution.
+The separate `forgedock run` and `forgedock run-issue` backend still supports
+only Claude CLI and the Anthropic API. An OpenCode engine backend must be added
+and validated before ForgeDock can claim provider-neutral headless parity.
+
+The ForgeDock plugin provides the OpenCode-specific runtime boundary for shell
+and task execution. Its `tool.execute.before` hook rejects Claude-backed and
+recursive ForgeDock controller commands, and normalizes native task arguments
+before execution; the shared workflow rules and deterministic scripts remain
+the source of truth for all other behavior.
+
+OpenCode 1.18.4 keeps background subagents experimental. ForgeDock opts into
+that feature by default because the streaming DAG depends on the parent session
+receiving one completion event per child. A native background task returns a
+`<task id="..." state="running">` marker immediately and later injects a
+`state="completed"` or `state="error"` result into the parent session. The
+orchestrator maps that id to the issue, re-reads GitHub state, and dispatches
+newly unlocked successors in the same response.
+
+If `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=false` is explicitly set,
+ForgeDock uses independent foreground tasks where OpenCode can execute them
+concurrently and labels the run as degraded. Foreground tasks cannot provide
+the same per-completion wake behavior, so this opt-out intentionally restores a
+wave-like fallback rather than silently claiming Claude-equivalent throughput.
+
+Commands that inspect Claude-specific transcripts or Claude installation state
+remain runtime-specific and should not be represented as portable until they
+receive dedicated implementations.
+
+## Orchestration Runtime
+
+OpenCode orchestration uses the native OpenCode `task` tool for isolated issue
+work and follows the shared `commands/work-on.md` state machine. Each ready
+issue is launched as `task(subagent_type="general", background=true)` and its
+task-result event is treated as the completion notification for that issue. It
+must not
+route through `forgedock run-issue` when that would select the Claude CLI or
+Anthropic API backend. If the host does not expose an OpenCode runtime marker,
+set the runtime explicitly before launching a headless command:
 
 ```bash
-Read("/path/to/repo/.claude/worktrees/feat-my-feature-123/file.py")
-Edit("/path/to/repo/.claude/worktrees/feat-my-feature-123/file.py", ...)
-Bash("git -C /path/to/repo/.claude/worktrees/feat-my-feature-123 status")
+FORGE_RUNTIME=opencode opencode run --command forge/orchestrate "fast-lane"
 ```
 
-## FORGE Annotation Protocol
-
-Every pipeline stage writes a structured annotation to GitHub. Key rules:
-
-1. **Idempotency**: Check for existing annotations BEFORE starting a phase.
-   Do not re-run a completed phase.
-2. **Compaction resilience**: Write annotations AFTER completing each
-   significant step. GitHub is the persistent state layer.
-3. **Restart partial annotations**: If an annotation exists without its
-   `:COMPLETE` sentinel, delete it and restart the phase.
-4. **Respect label state**: Labels track workflow state. Read and set them
-   at each phase boundary.
-
-### Label state machine
-
-```
-workflow:investigating
-    → workflow:ready-to-build   (investigation complete)
-    → workflow:building         (build started)
-    → workflow:in-review        (PR created)
-    → workflow:merged           (PR merged) [TERMINAL]
-
-workflow:invalid                [TERMINAL]
-workflow:decomposed             [TERMINAL]
-needs-human                     [TERMINAL]
-```
-
-Stop the pipeline when any terminal label is set.
-
-## Limitations
-
-| Capability | Claude Code | OpenCode (this adapter) |
-|------------|-------------|------------------------|
-| Skill loading | Dynamic (`~/.claude/commands/`) | Read `commands/*.md` directly |
-| Native slash commands | `/work-on 967` | `/work-on 967` (via `command` config) |
-| Tool name parity | Native | Direct (same names) |
-| Sub-agent invocation | `Skill("review-pr")` | Read `commands/review-pr.md` directly |
-| Session continuity | Native compaction resilience | Re-read GitHub state each session |
-| Multi-phase pipeline | Automatic (single continuous session) | Supported (GitHub state is persistent) |
-
-**Sub-skill invocation**: When a command spec calls `Skill("x")`, OpenCode
-has no native skill loader. Read the referenced command spec file directly
-instead.
-
-**Parallel tasks**: When a command spec calls `Agent(...)` or `Task(...)` for
-parallelism (e.g., multi-agent review in `review-pr-agents.md`), execute the
-sub-tasks sequentially. OpenCode runs one agent context at a time.
-
-## Configuration
-
-`install-opencode.sh` patches `~/.config/opencode/opencode.json`. Example
-of what is added:
-
-```json
-{
-  "instructions": [
-    "~/.opencode-forge.md"
-  ],
-  "command": {
-    "work-on": {
-      "description": "Run the ForgeDock full issue pipeline (investigate → build → review → merge)",
-      "template": "Read /path/to/forgedock/commands/work-on.md and execute the pipeline for issue {{args}}."
-    },
-    "review-pr": {
-      "description": "Run the ForgeDock PR review pipeline",
-      "template": "Read /path/to/forgedock/commands/review-pr.md and execute the PR review for PR {{args}}."
-    },
-    "quality-gate": {
-      "description": "Run ForgeDock pre-commit quality checks",
-      "template": "Read /path/to/forgedock/commands/quality-gate.md and run all quality gate checks."
-    },
-    "orchestrate": {
-      "description": "Run ForgeDock parallel multi-issue orchestration",
-      "template": "Read /path/to/forgedock/commands/orchestrate.md and orchestrate the issues: {{args}}."
-    }
-  }
-}
-```
-
-Existing config keys (provider, model, etc.) are preserved. ForgeDock only
-adds to the `instructions` array and `command` object — never overwrites.
-
-## Reference
-
-- [FORGE Protocol spec](FORGE-PROTOCOL.md) — annotation format, label state machine
-- [Aider adapter](AIDER.md) — parallel adapter reference (Aider uses `/run` translation)
-- [Codex adapter](CODEX.md) — parallel adapter reference (Codex skill model)
-- [Pipeline commands](../commands/) — shared workflow specs (authoritative for all runtimes)
-- [`install-opencode.sh`](../install-opencode.sh) — installer script
-- [`scripts/forge-run.sh`](../scripts/forge-run.sh) — universal shell phase router
+Each task re-reads GitHub labels and `FORGE:*` comments after every phase and
+continues until `workflow:merged`, `workflow:invalid`, `needs-human`, or
+`workflow:awaiting-merge`. The parent orchestrator processes every child
+completion independently, so a completed predecessor can unlock and dispatch
+its successors while unrelated issues continue running. If native task
+dispatch is unavailable, post a
+`FORGE:OPENCODE_BLOCKED` diagnostic naming the missing capability and add
+`needs-human`; do not leave an issue stranded at `workflow:engine-error`.
+
+If a generated command or skill cannot load its authoritative workflow, it must
+stop with an actionable `FORGE_OPENCODE_CAPABILITY_ERROR`. It must not recover
+by invoking `forgedock run-issue`, `npx forgedock run-issue`, or a recursive
+`opencode run`; those paths select a competing controller or Claude-backed
+backend.
+
+The same boundary is enforced below the plugin for direct CLI callers. With
+`FORGE_RUNTIME=opencode`, `forgedock run`, `forgedock run-issue`, and Claude
+backend preflight fail before selecting a provider. The stable error is
+`FORGE_OPENCODE_CAPABILITY_ERROR`; continue by using the registered native
+Skill and Task workflow instead.
+
+This runtime branch is additive. Claude keeps its existing engine and
+background-agent paths, and Codex keeps its installed namespaced skills and
+repo-local adapters.
+
+## Runtime Paths
+
+The shared orchestration spec resolves `classify-lane.sh` by runtime:
+
+| Runtime | Helper precedence | Worktree root |
+|---------|-------------------|---------------|
+| Claude | `${FORGE_HOME}/scripts`, then `~/.claude/scripts`, then the repository `scripts/` | `.claude/worktrees/` |
+| OpenCode | `${FORGE_HOME}/scripts`, then the repository `scripts/`, then `~/.opencode/scripts` | `.opencode/worktrees/` |
+| Codex | `${FORGE_HOME}/scripts`, then the repository `scripts/` | `.codex/worktrees/` |
+
+Set `FORGE_RUNTIME=opencode` for headless OpenCode sessions when no native
+OpenCode marker is available. The resolver is used by initial dispatch and all
+review-finding classification loops, so an OpenCode installation never needs
+`~/.claude` while the Claude precedence and fallback remain unchanged.
+
+## Source References
+
+- Shared workflows: [`commands/`](../commands/)
+- Installer implementation: [`bin/opencode-adapter.mjs`](../bin/opencode-adapter.mjs)
+- FORGE protocol: [`docs/spec/forge-protocol-v1.md`](spec/forge-protocol-v1.md)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "forgedock",
-  "version": "1.6.0",
-  "description": "Autonomous dev pipeline for Claude Code. GitHub as institutional memory — every issue, PR, and annotation survives context resets and makes the next agent smarter.",
+  "version": "1.7.1",
+  "description": "Autonomous development pipeline for coding agents. GitHub as institutional memory, with native Claude Code and OpenCode entrypoints.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"
   },
@@ -16,6 +16,7 @@
     "llm",
     "knowledge-graph",
     "claude",
+    "opencode",
     "anthropic",
     "agentic-ai",
     "devtools",