forgedock 1.5.1 → 1.7.0

package/docs/OPENCODE.md

@@ -1,312 +1,192 @@
 # 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
+npx forgedock opencode install --extras
 ```
 
-## Usage
-
-### Native slash commands (recommended)
-
-After running `install-opencode.sh`, use ForgeDock commands in the OpenCode
-TUI:
+Restart OpenCode after install or update. OpenCode loads commands and plugins
+at startup.
 
-```
-/work-on 967
-/review-pr 123
-/quality-gate
-```
-
-Or headlessly via `opencode run`:
-
-```bash
-opencode run --command work-on "967"
-opencode run --command review-pr "123"
-```
+The installer does not edit `opencode.json` or `opencode.jsonc`. 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:
 
-```
-Read the file /path/to/forgedock/commands/work-on.md and run the pipeline for issue 967.
+```text
+/forge/work-on 967
+/forge/review-pr 123
+/forge/quality-gate
+/forge/orchestrate milestone checkout-v2
 ```
 
-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":"..."}
-```
+## Architecture
 
-## Tool Translation
+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.
 
-OpenCode and Claude Code share the same tool names. Most pipeline operations
-run without modification:
+```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
+```
 
-| 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 |
+The generated plugin has no prompt text. It:
 
-### Nested Skill references
+- injects `FORGE_HOME` into OpenCode shell environments;
+- defaults `subagent_depth` to 2 when the user has not configured it, while
+  preserving explicit lower limits;
+- 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.
 
-When a command spec calls `Skill("x")` or references another command, read
-the referenced command spec directly:
+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.
 
-```
-# Load the referenced command spec:
-Read("/path/to/forgedock/commands/quality-gate.md")
-```
+## Token Efficiency
 
-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`
+The adapter follows these rules:
 
-## GitHub Operations
+- No global ForgeDock `instructions` entry.
+- No generated skill for every source file. Large skill catalogs add metadata
+  to every session even when ForgeDock is unused.
+- Only top-level user entry commands are registered.
+- 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.
+- GitHub state and the durable engine remain the recovery source instead of
+  replaying prior prompt context.
 
-All FORGE annotations are written to GitHub issue/PR comments via the `gh`
-CLI. Use `Bash()` for every GitHub operation.
+The generated adapter preamble is intentionally small. It maps Claude Code's
+in-conversation `Skill(...)` loading to a lazy read of the corresponding shared
+spec. It maps isolated `Task(...)` and permitted `Agent(...)` calls to
+OpenCode's native `task` tool.
 
-### Label management
+`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.
 
-```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'")
-```
-
-### Reading existing annotations
+## Lifecycle
 
 ```bash
-Bash("gh api repos/OWNER/REPO/issues/123/comments \
-  --jq '.[] | select(.body | contains(\"FORGE:INVESTIGATOR\")) | .body'")
+npx forgedock opencode status
+npx forgedock opencode install          # update/repair
+npx forgedock opencode install --extras
+npx forgedock opencode uninstall
 ```
 
-### Writing a FORGE annotation comment
-
-For multi-line comment bodies, write the content to a temp file first:
+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.
+Install also removes the previous ForgeDock-managed `~/.opencode-forge.md`
+instructions file and its exact legacy config entries when they are present.
 
-```bash
-# Write comment body to temp file (avoids shell quoting issues)
-Write("/tmp/forge_comment.md", """<!-- FORGE:INVESTIGATOR -->
-## Investigation Report
+## Locations
 
-**Verdict**: CONFIRMED
-...
-<!-- INVESTIGATION:COMPLETE -->""")
+Default global location:
 
-Bash("gh issue comment 123 -R OWNER/REPO --body \"$(cat /tmp/forge_comment.md)\"")
+```text
+~/.config/opencode/
+  commands/forge/*.md
+  plugins/forgedock.js
+  forgedock/manifest.json
 ```
 
-### Creating a PR
+`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.
 
-```bash
-Write("/tmp/pr_body.md", """## Summary
-...
+## Current Boundary
 
-Closes #967""")
+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.
 
-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)\"")
-```
+Claude's `PreToolUse` safety hook has not yet been ported to an OpenCode plugin.
+The shared workflow rules and deterministic scripts still apply, but equivalent
+mechanical enforcement must be implemented and tested before claiming complete
+Claude-runtime safety parity.
 
-## Worktrees
+OpenCode 1.18.4 keeps background subagents experimental. When they are not
+enabled, the command adapter requires independent foreground tasks to be
+launched concurrently where supported and uses ForgeDock's GitHub-label polling
+fallback. This preserves isolated review contexts but does not yet prove equal
+wall-clock behavior for `/forge/orchestrate`.
 
-ForgeDock uses git worktrees to isolate branch work. Create one with:
+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.
 
-```bash
-Bash("git fetch origin")
-Bash("git worktree add .claude/worktrees/feat-my-feature-123 \
-  -b feat/my-feature-123 origin/staging")
-```
+## Orchestration Runtime
 
-Work inside the worktree for all file edits and commits:
+OpenCode orchestration uses the native OpenCode `task` tool for isolated issue
+work and follows the shared `commands/work-on.md` state machine. 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
+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`. 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`.
 
-Every pipeline stage writes a structured annotation to GitHub. Key rules:
+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.
 
-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.
+## Runtime Paths
 
-### Label state machine
+The shared orchestration spec resolves `classify-lane.sh` by runtime:
 
-```
-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}}."
-    }
-  }
-}
-```
+| 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/` |
 
-Existing config keys (provider, model, etc.) are preserved. ForgeDock only
-adds to the `instructions` array and `command` object — never overwrites.
+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.
 
-## Reference
+## Source References
 
-- [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
+- 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.5.1",
-  "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.0",
+  "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",

package/scripts/check-spec-markers.sh

@@ -102,6 +102,7 @@ MARKER_REGISTRY="
   DESIGN
   DISPATCHER
   DOSSIER_UPDATED
+  ENGINE_FALLBACK
   FAST_PATH
   FINDING_SOURCE
   FIX_CI