forgedock 1.1.11 → 1.3.0

package/docs/AUTOPILOT-CRON.md

@@ -0,0 +1,130 @@
+# Autopilot Cron Mode — GitHub Actions Setup
+
+Run [`/autopilot`](../commands/autopilot.md) on a schedule so your repo gets better while you sleep.
+
+---
+
+## Quick Start
+
+1. **Copy the workflow template** into your repo:
+
+   ```bash
+   mkdir -p .github/workflows
+   curl -o .github/workflows/forgedock-autopilot.yml \
+     https://raw.githubusercontent.com/RapierCraftStudios/ForgeDock/milestone/developer-experience-distribution/templates/github-actions/forgedock-autopilot.yml
+   ```
+
+2. **Add your Anthropic API key** as a repository secret:
+   - Go to: `Settings → Secrets and variables → Actions → New repository secret`
+   - Name: `ANTHROPIC_API_KEY`
+   - Value: your key from [console.anthropic.com](https://console.anthropic.com)
+
+3. **Commit the workflow file** — GitHub Actions picks it up automatically.
+
+That's it. The workflow runs every Monday at 9 AM UTC in `recon` mode (safe, read-only).
+
+---
+
+## Modes
+
+### `recon` (default — safe)
+
+Runs [`/autopilot --recon-only`](../commands/autopilot.md):
+
+- Pulls signals: production health, CI/CD, issue backlog, analytics
+- Creates GitHub issues for findings
+- **No branches, no PRs, no code changes**
+
+This is the default for scheduled runs. Safe to enable immediately.
+
+### `fix` (explicit opt-in)
+
+Runs [`/autopilot --fix --limit N`](../commands/autopilot.md):
+
+- Everything in `recon` mode, plus:
+- Picks up the top N open issues and runs `/work-on` on each
+- Creates branches and PRs targeting `staging` (never `main`)
+- **Requires explicit selection** — not available on scheduled runs without editing the workflow
+
+To enable `fix` mode on a scheduled run, edit the `Resolve autopilot arguments` step in the workflow and change the default `MODE` to `fix`.
+
+To run `fix` mode on demand, use the **Run workflow** button on GitHub Actions and select `fix` from the mode dropdown.
+
+---
+
+## Permissions
+
+The workflow requires these GitHub token permissions (already set in the template):
+
+| Permission | Required for |
+|------------|-------------|
+| `contents: write` | Creating branches and pushing commits (`fix` mode) |
+| `issues: write` | Creating and labeling issues (both modes) |
+| `pull-requests: write` | Creating PRs (`fix` mode) |
+
+`GITHUB_TOKEN` is provided automatically — no extra setup needed.
+
+---
+
+## Adjusting the Schedule
+
+The default cron runs every Monday at 9 AM UTC. To change it, edit the `cron` line:
+
+```yaml
+on:
+  schedule:
+    - cron: '0 9 * * 1'   # Monday 9 AM UTC
+    # - cron: '0 8 * * *'  # Daily at 8 AM UTC
+    # - cron: '0 9 1 * *'  # Monthly on the 1st
+```
+
+Cron syntax: `minute hour day-of-month month day-of-week`. Use [crontab.guru](https://crontab.guru) to verify expressions.
+
+---
+
+## Changing the Fix Limit
+
+The `limit` input controls how many issues are picked up per run in `fix` mode (default: 3). To change the default for manual runs, edit the `default` value under `inputs.limit` in the workflow file.
+
+---
+
+## Non-Interactive Confirmation Bypass
+
+`/autopilot` Phase 4B normally requires interactive user confirmation before running `/work-on` on any issues. In GitHub Actions (a non-interactive environment), this gate is bypassed automatically when the `CI` environment variable is `true` — which is always the case in GHA.
+
+**The `workflow_dispatch` mode input serves as the human opt-in.** When you select `fix` and click **Run workflow**, you are explicitly approving the fix run. For scheduled runs, the mode embedded in the workflow YAML is your standing approval.
+
+This bypass is narrow: it only skips Phase 4B's interactive prompt. All other safety rules in `/autopilot` remain in force — `needs-human` issues are never picked up, milestone issues are excluded, and the `FIX_LIMIT` cap is always enforced.
+
+---
+
+## Cost Estimates
+
+| Mode | Typical token usage | Approximate cost |
+|------|--------------------|--------------------|
+| `recon` | ~5,000–15,000 tokens | ~$0.02–$0.05/run |
+| `fix` (1 issue) | ~50,000–150,000 tokens | ~$0.15–$0.45/run |
+| `fix` (3 issues) | ~150,000–450,000 tokens | ~$0.45–$1.35/run |
+
+Estimates based on `claude-sonnet-4` pricing ($3.00/M input, $15.00/M output). Actual usage varies by issue complexity and codebase size.
+
+To control costs, keep `mode: recon` for scheduled runs and use `fix` mode only on demand.
+
+---
+
+## Frequently Asked Questions
+
+**Will this merge code to `main`?**
+No. `/autopilot` (and `/work-on`) never merge to `main`. All PRs target `staging` or a milestone branch. You deploy when ready.
+
+**What if an autopilot run fails?**
+The workflow exits with a non-zero status. GitHub sends a notification email (configurable). The run is logged in the Actions tab. No partial state is left — issues are only created after a full recon cycle.
+
+**Can I run this in a private repo?**
+Yes. `GITHUB_TOKEN` has full access to your repo. Only the Anthropic API key is external.
+
+**Can I use this with Codex / OpenAI models?**
+No. `/autopilot` requires Claude Code CLI, which runs Anthropic models. The `ANTHROPIC_API_KEY` is mandatory.
+
+**What does `/autopilot` do if there are open P0 issues?**
+It skips normal recon and immediately routes to `fix` mode targeting the P0 issues, regardless of the selected mode. P0 always takes priority.

package/docs/CI.md

@@ -128,6 +128,24 @@ This is not recommended without understanding the security implications.
 
 ---
 
+## `forgedock run` Execution Backend
+
+This guide's `forgedock-review.yml` workflow invokes `/review-pr` directly via the `claude --print` CLI, so it always needs `ANTHROPIC_API_KEY` as shown above — the CLI itself authenticates against your Anthropic account.
+
+Separately, `npx forgedock run <command>` (the standalone, non-Claude-Code command runner in `bin/runner.mjs`) has its own **backend selection**, independent of this CI workflow:
+
+| Backend | When used | Credential needed |
+|---------|-----------|--------------------|
+| `cli` (via `--backend cli` or `FORGEDOCK_BACKEND=cli`) | Explicit, or auto-selected when a working `claude` CLI is detected on PATH | None — reuses the CLI's own authentication (Pro/Max OAuth or a CLI-managed key) |
+| `api` (via `--backend api` or `FORGEDOCK_BACKEND=api`) | Explicit, or auto-selected fallback when `claude` is not detected | `ANTHROPIC_API_KEY` |
+| `auto` (default) | No `--backend` / `FORGEDOCK_BACKEND` given | Prefers `cli`, falls back to `api` |
+
+**When CI still needs `ANTHROPIC_API_KEY` for `forgedock run`**: CI runners generally do not have an interactively-authenticated `claude` CLI (no browser/OAuth flow available in a headless job), so `auto` detection will typically fall back to `api` there anyway. If your CI runner does install and log in the `claude` CLI (e.g. via a headless API-key-based login), you can force `--backend cli` to skip the SDK/API path entirely. Otherwise, keep `ANTHROPIC_API_KEY` configured as a repository secret (see Setup above) and either let `auto` fall back naturally or set `--backend api` / `FORGEDOCK_BACKEND=api` explicitly for a deterministic CI backend regardless of what happens to be on the runner's PATH.
+
+`npx forgedock run <command> --dry-run` always reports which backend it resolved to, without making any network call or requiring a key either way.
+
+---
+
 ## Customization
 
 ### Skip review for certain PRs

package/docs/CONFIG.md

@@ -29,9 +29,12 @@ echo "forge.yaml" >> .gitignore  # if your credentials path is sensitive
 |----------|----------|
 | `FORGE_NO_MOTION=1` | Same effect as `--fast` — disables animation frames. Color is unaffected. |
 | `NO_COLOR=1` | Disables ANSI color output only. Motion is unaffected (monochrome choreography). |
+| `FORGEDOCK_INIT_BACKEND=cli\|api\|none\|auto` | Overrides AI-enrichment backend selection for `init` (see below). Default `auto` (or unset) preserves the CLI-first ladder. |
 | Non-TTY / piped output (or `CI=1`) | Plain sequential log: no color **and** no animation. |
 
-The default (no flags) is the annotated review screen: detection runs, AI enrichment fills in what it can (when an API key is available), and you review the result on a single screen — Enter accepts everything, low-confidence fields are flagged with a `# TODO(forgedock:<field>)` comment if left unedited.
+The default (no flags) is the annotated review screen: detection runs, AI enrichment fills in what it can — using a local, authenticated `claude` CLI when available, otherwise falling back to the Anthropic API when `ANTHROPIC_API_KEY` is set, otherwise skipped — and you review the result on a single screen — Enter accepts everything, low-confidence fields are flagged with a `# TODO(forgedock:<field>)` comment if left unedited.
+
+If you have both a local `claude` CLI and `ANTHROPIC_API_KEY` set and want to pin one explicitly instead of letting `init` prefer the CLI, set `FORGEDOCK_INIT_BACKEND=api` (or `=cli`, or `=none` to skip enrichment entirely). This is independent of `FORGEDOCK_BACKEND`, which controls the separate `forgedock run` engine backend.
 
 ---
 
@@ -207,6 +210,9 @@ repos:
 | `satellites[].local_path` | string | No | Absolute local path to the satellite repo's checkout |
 | `satellites[].subpaths` | map(string→string) | No | Named sub-directory paths within `local_path`, for monorepo satellites that publish multiple packages. Each key is a logical name; the value is the relative path to that package's root. Used by `/sync-ecosystem` to locate per-package version files and publish workflows. |
 | `satellites[].billing_enabled` | boolean | No | Set to `true` to run Phase 4 (Financial Integrity) of `/security-audit` against this satellite repo. Mirrors the top-level [`billing.enabled`](#billing-optional) flag but scoped per-satellite. Defaults to `false` when absent. |
+| `satellites[].trigger_on_merge` | boolean | No | When `true`, fires a cross-repo trigger when a PR merges in the parent repo and touches paths matching `trigger_paths`. Set to `false` to disable triggering for this satellite. Defaults to `true` when `trigger_paths` is present; otherwise has no effect until runtime trigger support is configured. |
+| `satellites[].trigger_paths` | list of strings | No | Path glob patterns that constrain when the trigger fires. Uses GitHub Actions glob syntax (same as `on: push: paths:`). The trigger fires only when at least one changed file matches a pattern in this list. When omitted, the trigger fires on every merge (if `trigger_on_merge: true`). |
+| `satellites[].auto_run` | boolean | No | When `true`, automatically invokes `/work-on` on the satellite issue when the cross-repo trigger fires. Requires a running Claude Code session with ForgeDock installed in the satellite repo. Advanced opt-in — defaults to `false`. Do not set to `true` unless a persistent Claude Code session is available in the satellite repo. |
 
 **Routing syntax in commands**: `<prefix>:<issue_number>` — e.g., `mcp:5`, `sdk:12`
 
@@ -606,6 +612,39 @@ Colors are grouped by semantic meaning:
 
 ---
 
+## `branding` (OPTIONAL)
+
+Controls attribution in FORGE annotation comments posted to GitHub issues and PRs by pipeline commands.
+
+When `show_attribution` is `true` (the default), every annotation comment (`FORGE:INVESTIGATOR`, `FORGE:CONTRACT`, `FORGE:BUILDER`, `FORGE:TRAJECTORY`, `FORGE:DECOMPOSED`, etc.) ends with a one-line footer:
+
+```
+> Pipeline powered by [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock)
+```
+
+This follows the pattern established by Dependabot, Renovate, and similar tools. It helps new users discover the tooling when they encounter FORGE: annotations in a public thread. Set to `false` to suppress the attribution entirely.
+
+```yaml
+branding:
+  show_attribution: true
+```
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `show_attribution` | boolean | No | `true` | When `true`, annotation comments posted by the pipeline include a one-line attribution footer. Set to `false` to suppress it entirely. Opt-out model — attribution is on by default. |
+
+**Commands that use this section**: `work-on` (all phases that post FORGE: annotation comments)
+
+**Config read pattern** (yq, with default-true fallback):
+
+```bash
+SHOW_ATTRIBUTION=$(yq '.branding.show_attribution // "true"' forge.yaml 2>/dev/null || echo "true")
+[ "$SHOW_ATTRIBUTION" = "false" ] && ATTRIBUTION_LINE="" || ATTRIBUTION_LINE="
+> Pipeline powered by [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock)"
+```
+
+---
+
 ## GitHub App Install
 
 During `npx forgedock`, the installer prompts you to install the ForgeDock GitHub App (`rapiercraft-forgedock`) on your account or org.
@@ -741,7 +780,7 @@ const draft = await detectConfig(process.cwd());
 
 Downstream consumers read `field.value` for the raw value and `field.confidence` to decide how to handle it:
 
-- **`init-enrich`** (AI enrichment): passes `low`- and `medium`-confidence fields to the AI backend to raise their confidence; leaves `high`-confidence fields untouched.
+- **`init-enrich`** (AI enrichment): passes `low`- and `medium`-confidence fields to the selected AI backend (a local `claude` CLI when available, otherwise the Anthropic API with `ANTHROPIC_API_KEY`) to raise their confidence; leaves `high`-confidence fields untouched.
 - **`review-render`** (TUI review screen): shows each field with its source and why; highlights `low`-confidence fields with a `# TODO(forgedock:<field>)` annotation in the generated YAML.
 
 ---

package/docs/CURSOR.md

@@ -0,0 +1,135 @@
+# Cursor Support
+
+ForgeDock has a Cursor adapter that lets Cursor Agent mode run the ForgeDock pipeline via shell commands and the `gh` CLI.
+
+## Architecture
+
+Shared source:
+- `commands/**/*.md` remains the canonical workflow spec for all runtimes
+
+Cursor wrapper:
+- `templates/cursor/forge.mdc` — a static Cursor rules file that instructs Cursor Agent to execute pipeline phases using shell commands, `gh` CLI, and `git`
+- Users install this file into their repo's `.cursor/rules/forge.mdc`
+
+This is a static injection model, not a dynamic skill-loading mechanism. The adapter cannot replicate Claude Code's `Skill()` invocation or Codex's installed skill wrappers. Instead, it instructs the agent to read command specs directly from `commands/` and execute them using available terminal tools.
+
+## Install
+
+### Automatic (via `npx forgedock`)
+
+If your project already has a `.cursor/` directory, `npx forgedock` will detect it and automatically write `templates/cursor/forge.mdc` to `.cursor/rules/forge.mdc`:
+
+```bash
+npx forgedock
+```
+
+The installer skips this step if `.cursor/rules/forge.mdc` already exists (idempotent — never overwrites customizations).
+
+### Manual
+
+Copy the template directly:
+
+```bash
+mkdir -p .cursor/rules
+cp node_modules/forgedock/templates/cursor/forge.mdc .cursor/rules/forge.mdc
+# or, if installed globally:
+cp "$(npx forgedock which-dir)/templates/cursor/forge.mdc" .cursor/rules/forge.mdc
+```
+
+Commit the file to version control so all team members get it:
+
+```bash
+git add .cursor/rules/forge.mdc
+git commit -m "chore: add ForgeDock Cursor rules adapter"
+```
+
+## Usage
+
+### Running the Pipeline
+
+Open a Cursor Agent session and describe the pipeline task:
+
+```
+Work on GitHub issue #123 using the ForgeDock pipeline.
+Read commands/work-on.md and follow all phases.
+```
+
+The rules file will instruct Cursor Agent to:
+
+1. Load issue context from GitHub using `gh issue view`
+2. Follow the Universal Phase Dispatcher in `commands/work-on.md`
+3. Write FORGE annotations (HTML comments) to issue comments after each phase
+4. Transition `workflow:*` labels as phases complete
+5. Continue until a terminal label is set
+
+### Checking Pipeline State
+
+```bash
+# See current workflow state
+gh issue view NUMBER --json labels --jq '[.labels[].name]'
+
+# Read existing pipeline annotations
+gh api repos/OWNER/REPO/issues/NUMBER/comments \
+  --jq '.[] | select(.body | contains("FORGE:")) | {body: .body[:200]}'
+```
+
+### Continuing After a Phase
+
+Because Cursor Agent mode does not persist between invocations, start a new session and describe the resume:
+
+```
+Resume the ForgeDock pipeline for GitHub issue #123.
+Read commands/work-on.md — it will re-read GitHub state and pick up from the current label.
+```
+
+The pipeline is designed for compaction resilience — every phase re-reads GitHub state at the start, so a new Cursor Agent session picks up exactly where the previous session left off.
+
+## Limitations
+
+| Capability | Claude Code | Cursor (this adapter) |
+|------------|-------------|----------------------|
+| Skill loading | Dynamic (`~/.claude/commands/`) | Static (this rules file) |
+| Multi-phase pipeline | Automatic (single continuous session) | Manual (re-invoke agent per phase) |
+| Sub-skill invocation | `Skill("review-pr")` | Read `commands/review-pr.md` directly |
+| Session continuity | Native compaction resilience | Re-read GitHub state each invocation |
+| Tool set | Claude-native (`Bash`, `Read`, `Grep`, `Glob`, `WebFetch`) | Cursor Agent terminal tools |
+
+### Multi-Phase Pipeline
+
+The ForgeDock pipeline has 7 phases (investigate → build → review → merge → close → trajectory). Cursor Agent mode does not automatically advance through all phases in a single session. After each phase completes, you will need to start a new agent invocation and ask it to continue.
+
+The pipeline's compaction resilience handles this correctly: each invocation re-reads the issue's labels and comments, determines the current phase, and continues from there. No context is lost between sessions.
+
+### Sub-Skill Invocation
+
+When the pipeline spec calls `Skill("review-pr")` or `Skill("quality-gate")`, Cursor Agent should read the referenced command spec file directly:
+
+```bash
+cat commands/review-pr.md   # Then execute that spec
+cat commands/quality-gate.md
+```
+
+### Project Board Steps
+
+Some pipeline phases (0C: Sync to Project board) call GitHub Projects API operations. These work via `gh` CLI but require the project number and field IDs from `forge.yaml`. Verify your `forge.yaml` has the correct project configuration before running the pipeline.
+
+## Configuration
+
+ForgeDock reads `forge.yaml` for project-specific settings:
+
+```bash
+cat forge.yaml   # Review before running the pipeline
+```
+
+Key fields used by the pipeline:
+- `project.github.owner` / `project.github.repo` — GitHub repo coordinates
+- `branches.staging` — target branch for fast-lane PRs
+- `branches.main` — default branch
+
+## Reference
+
+- `commands/work-on.md` — Full pipeline spec (all phases)
+- `commands/review-pr.md` — PR review spec
+- `commands/quality-gate.md` — Pre-commit quality checks (14+ domains)
+- `docs/FORGE-PROTOCOL.md` — FORGE annotation protocol specification
+- `docs/CODEX.md` — Codex CLI adapter (dynamic skill model)

package/docs/OPENCODE.md

@@ -0,0 +1,312 @@
+# 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.
+
+## Install
+
+### Option A — standalone bash installer
+
+```bash
+cd /path/to/forgedock
+./install-opencode.sh
+```
+
+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.
+
+```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
+```
+
+Or headlessly via `opencode run`:
+
+```bash
+opencode run --command work-on "967"
+opencode run --command review-pr "123"
+```
+
+### Manual pipeline loading
+
+Read a pipeline command spec directly and follow it:
+
+```
+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:
+
+```bash
+Bash("/path/to/forgedock/scripts/forge-run.sh work-on 967 -R OWNER/REPO")
+```
+
+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
+
+When a command spec calls `Skill("x")` or references another command, read
+the referenced command spec directly:
+
+```
+# 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'")
+```
+
+### Reading existing annotations
+
+```bash
+Bash("gh api repos/OWNER/REPO/issues/123/comments \
+  --jq '.[] | select(.body | contains(\"FORGE:INVESTIGATOR\")) | .body'")
+```
+
+### 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 -->""")
+
+Bash("gh issue comment 123 -R OWNER/REPO --body \"$(cat /tmp/forge_comment.md)\"")
+```
+
+### Creating a PR
+
+```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)\"")
+```
+
+## 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")
+```
+
+Work inside the worktree for all file edits and commits:
+
+```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 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