forgedock 1.2.0 → 1.3.0

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

package/docs/eval/README.md

@@ -8,8 +8,8 @@ Per-release pipeline evaluation results for ForgeDock. Every scorecard here was
 
 | Field | Value |
 |-------|-------|
-| Scorecard | [claude-sonnet-5-2026-07-04.json](published/claude-sonnet-5-2026-07-04.json) |
-| Model | claude-sonnet-5 |
+| Scorecard | [claude-sonnet-4-6-2026-07-04.json](published/claude-sonnet-4-6-2026-07-04.json) |
+| Model | claude-sonnet-4-6 |
 | Corpus | seed-v1 |
 | Run date | 2026-07-04 |
 | One-shot success rate | — (pending harness) |
@@ -17,7 +17,7 @@ Per-release pipeline evaluation results for ForgeDock. Every scorecard here was
 
 > **Note**: The baseline above is a format placeholder. The harness (#1285) and CI gate (#1286) must be operational before real scorecard values can be populated. When the first real run completes, update this table and remove this note.
 >
-> **Model upgrade**: Default model was updated from `claude-sonnet-4-5` to `claude-sonnet-5` in PR #1441 (issue #1248, committed 2026-07-04). The `--model` flag and `FORGEDOCK_MODEL` env var override the default at runtime.
+> **Model upgrade**: Default model was updated from `claude-sonnet-4-5` to `claude-sonnet-5` in PR #1441 (issue #1248, committed 2026-07-04). The `--model` flag and `FORGEDOCK_MODEL` env var override the default at runtime. No `claude-sonnet-5` scorecard has been published yet — see the Published results table below.
 
 ---
 
@@ -25,7 +25,7 @@ Per-release pipeline evaluation results for ForgeDock. Every scorecard here was
 
 | Run ID | Model | Corpus | Date | One-shot success | Human interventions/issue | Scorecard |
 |--------|-------|--------|------|-----------------|--------------------------|-----------|
-| claude-sonnet-5-2026-07-04 | claude-sonnet-5 | seed-v1 | 2026-07-04 | pending | pending | [scorecard](published/claude-sonnet-5-2026-07-04.json) |
+| claude-sonnet-5-2026-07-04 | claude-sonnet-5 | seed-v1 | 2026-07-04 | pending | pending | not yet published |
 | claude-sonnet-4-6-2026-07-04 | claude-sonnet-4-6 | seed-v1 | 2026-07-04 | pending | pending | [scorecard](published/claude-sonnet-4-6-2026-07-04.json) |
 
 ---

package/docs/launch/show-hn.md

@@ -25,9 +25,9 @@ The fix isn't a bigger context window. It's structured memory that survives conv
 
 ForgeDock treats GitHub as that memory layer. Every pipeline stage writes machine-readable HTML annotations to issues and PRs — FORGE:INVESTIGATOR traces root cause to a specific commit, FORGE:ARCHITECT produces a typed implementation plan, FORGE:CONTEXT surfaces known pitfalls from closed issues in the same module. The next agent reads these before doing anything. The gh CLI is the query interface; no external store, no embeddings.
 
-The pipeline: /work-on #42 → investigate (reads git blame, closed issues, review findings) → architect (traces all call sites, orders changes by dependency) → build → quality gate (14+ check domains) → 9-agent review → PR. Each stage writes what it found so the next stage doesn't repeat the work. After 20,000+ issues processed across real production codebases, patterns accumulate: the context phase now flags known pitfalls in a module before the builder touches it.
+The pipeline: /work-on #42 → investigate (reads git blame, closed issues, review findings) → architect (traces all call sites, orders changes by dependency) → build → quality gate (14+ check domains) → 9-agent review → PR. Each stage writes what it found so the next stage doesn't repeat the work. ForgeDock builds itself with this pipeline — in its first 30 days, 693 issues filed and 603 PRs merged across the repo — and patterns accumulate: the context phase now flags known pitfalls in a module before the builder touches it.
 
-It's 25 markdown command specs installed via npx forgedock, no runtime server. Would love to hear what the HN community thinks about using GitHub's existing graph structure — commits, blame, cross-references — as agent memory.
+It's a set of markdown command specs installed via npx forgedock, no runtime server. Would love to hear what the HN community thinks about using GitHub's existing graph structure — commits, blame, cross-references — as agent memory.
 ```
 
 **Character count**: ~1,380 characters (well within 4,000 limit)
@@ -71,7 +71,7 @@ It's 25 markdown command specs installed via npx forgedock, no runtime server. W
 
 ### "Why HTML comments for annotations?"
 
-> GitHub renders HTML comments invisibly to humans — the issue stays readable without noise. Agents grep for `<!-- FORGE:INVESTIGATOR -->` to find structured context fast. It's a zero-dependency protocol: no API, no schema registry, no additional auth. Any tool with `gh` CLI access can read and write annotations. The downside is parsing cost (tokens to extract fields from markdown); the [Vision section of the README](https://github.com/RapierCraftStudios/ForgeDock#vision) describes replacing this with a purpose-built graph store once the protocol is proven.
+> GitHub renders HTML comments invisibly to humans — the issue stays readable without noise. Agents grep for `<!-- FORGE:INVESTIGATOR -->` to find structured context fast. It's a zero-dependency protocol: no API, no schema registry, no additional auth. Any tool with `gh` CLI access can read and write annotations. The downside is parsing cost (tokens to extract fields from markdown); the [Where it's going section of the README](https://github.com/RapierCraftStudios/ForgeDock#where-its-going) describes replacing this with a purpose-built graph store once the protocol is proven.
 
 ---
 

package/docs/site/architecture.md

@@ -0,0 +1,180 @@
+---
+title: "ForgeDock Architecture"
+description: "How ForgeDock's autonomous pipeline works. Phase-by-phase breakdown, FORGE annotation relay, worktree isolation, and how agents reconstruct context after compaction."
+---
+
+# ForgeDock Architecture
+
+ForgeDock is **not an application** — it's a set of markdown command specs that get symlinked into `~/.claude/commands/` and invoked as slash commands in Claude Code. There is no runtime process. Every pipeline operation runs inside Claude Code, using GitHub as the persistence layer.
+
+---
+
+## Repository Structure
+
+```
+commands/              # Authoritative workflow specs
+  work-on.md           # Main orchestrator: investigate → build → review → merge
+  work-on/             # Sub-phases: investigate, build, review, close
+    build/             # Sub-sub-phases: context, architect, implement, validate
+  review-pr.md         # PR review orchestrator
+  review-pr-agents.md  # 9-agent review catalog
+  orchestrate.md       # Parallel multi-issue execution
+  quality-gate.md      # Pre-commit checks (14+ domains)
+  autopilot.md         # Self-improvement cycle
+  ...                  # 25+ more commands
+
+bin/                   # npm installer
+  forgedock.mjs        # npx forgedock — symlinks commands into ~/.claude/commands/
+
+docs/                  # Reference docs and this site
+scripts/               # Verification scripts used by quality-gate
+.agents/               # Codex adapter layer (repo-local skill overrides)
+```
+
+---
+
+## The Pipeline Relay
+
+The core innovation is **structured context passing via GitHub annotations**. Every pipeline phase writes a `FORGE:` annotation as a GitHub issue comment. Every downstream phase reads prior annotations before acting.
+
+```
+Issue opened
+    │
+    ▼
+FORGE:INVESTIGATOR  — root cause, affected files, recommendation
+    │
+    ▼
+FORGE:CONTRACT      — what will be built, deliverables table, acceptance criteria
+    │
+    ▼
+FORGE:CONTEXT       — past review findings, historical bugs, related code paths
+    │
+    ▼
+FORGE:ARCHITECT     — implementation plan, ordered file changes, risk assessment
+    │
+    ▼
+FORGE:BUILDER       — branch, commits, files changed, acceptance criteria status
+    │
+    ▼
+FORGE:REVIEW        — domain agent findings, severity ratings
+    │
+    ▼
+FORGE:TRAJECTORY    — audit trail, pipeline phase results, anomalies
+```
+
+This relay means:
+- A new session can pick up exactly where a previous one left off by reading GitHub state
+- Context compaction does not lose work — the next agent re-reads annotations and continues
+- The audit trail is human-readable and queryable with the `gh` CLI
+
+---
+
+## Pipeline Phases
+
+### Phase 0: Context Load
+
+Reads issue number, labels, milestone, existing annotations. Determines which phase to resume from. Classifies lane (fast vs. feature) based on milestone presence.
+
+**Fast lane**: Issues without a milestone → PR targets `staging`.
+**Feature lane**: Issues with a milestone → PR targets `milestone/{slug}`.
+
+### Phase 1: Investigation
+
+Validates whether the issue is real. Reads domain files, traces execution paths, git blame. Posts `FORGE:INVESTIGATOR` with verdict (CONFIRMED / PARTIAL / INVALID), root cause, affected files, and decomposition assessment.
+
+### Phase 2: Decomposition (conditional)
+
+If 2+ services, 6+ files across directories, or multiple task types: creates sub-issues with dependency order. Parent issue gets `workflow:decomposed`. Each sub-issue runs its own `/work-on`.
+
+### Phase 3: Build
+
+Sub-phases in order:
+
+| Sub-phase | What Happens |
+|-----------|-------------|
+| 3C: Contract | Builder posts deliverables table, acceptance criteria, quality considerations |
+| 3C.5: Context | Surfaces institutional memory — past review findings, historical bugs, related code paths |
+| 3C.6: Architect | Traces ALL affected code paths, sequences implementation order, assesses risk |
+| 3F: Implement | Writes code in isolated git worktree per the architect plan |
+| 3G: Quality Gate | 14-category pre-commit check (runs up to 3 iterations) |
+| 3H: Format | Language-specific formatting and type checking |
+| 3K: Commit | Conventional commit with issue reference |
+| 3M: Builder comment | Posts `FORGE:BUILDER` with branch, commits, acceptance criteria status |
+
+### Phase 4: PR Creation
+
+Pushes branch, creates PR targeting the correct base branch. Updates issue to `workflow:in-review`.
+
+### Phase 5: Auto-Review
+
+Invokes `/review-pr --auto-merge`. 9 domain agents (security, billing, database, concurrency, auth, frontend, API, performance, infrastructure) review the PR. Critical/HIGH findings become separate GitHub issues. PR merges if no blocking findings.
+
+### Phase 6: Close & Cleanup
+
+Closes the issue, sets `workflow:merged`, removes worktree and local branch. If issue is a sub-issue, checks off the item in the parent tracker.
+
+### Phase 7: Trajectory Log
+
+Posts `FORGE:TRAJECTORY` with phase-by-phase results table for pipeline health monitoring.
+
+---
+
+## Git Worktree Isolation
+
+Every build phase creates an isolated git worktree:
+
+```bash
+git worktree add .claude/worktrees/feat-my-feature-42 \
+  -b feat/my-feature-42 origin/staging
+```
+
+Benefits:
+- Build operations never dirty the main working tree
+- Multiple issues can be built in parallel without branch conflicts
+- Worktree is removed in Phase 6 after merge
+
+---
+
+## Quality Gate
+
+The quality gate checks code before commit across 14+ domains:
+
+- **Logic**: null checks, off-by-one errors, unreachable code
+- **Auth**: auth guards on all state-changing routes
+- **Database**: N+1 queries, missing indexes, raw SQL injection surface
+- **Security**: hardcoded credentials, injection vectors, CSRF exposure
+- **Frontend**: proxy wiring, missing error boundaries, a11y regressions
+- **Infrastructure**: Docker ownership, port binding, env var sync
+- **API contracts**: response shape changes, SDK literal sync
+- **Tests**: coverage gaps, missing edge cases
+
+Each finding is rated HIGH / MEDIUM / LOW. HIGH findings are blocking. The gate runs up to 3 iterations.
+
+---
+
+## Compaction Resilience
+
+Claude Code compacts context mid-session. ForgeDock is designed to survive this:
+
+1. **Write to GitHub after every significant step** — annotations are the durable state
+2. **Re-read GitHub at the start of each phase** — never assume in-memory context
+3. **Universal dispatcher** — any session can re-read issue labels and comments and determine exactly which phase to resume
+
+A new `/work-on 42` invocation after compaction reads the existing `FORGE:INVESTIGATOR`, `FORGE:CONTRACT`, `FORGE:ARCHITECT`, and `FORGE:BUILDER` comments and jumps straight to Phase 4 (PR creation) or Phase 5 (review) without re-running earlier phases.
+
+---
+
+## Command Specs Are Prompts
+
+The `.md` files in `commands/` are detailed prompt engineering documents — some exceed 50KB. They constrain LLM behavior at every step:
+
+- **Phase boundaries** are explicit with entry conditions and exit actions
+- **Universal continuation rule** prevents premature stopping after intermediate results
+- **Structured output requirements** (e.g., `<!-- INVESTIGATION:COMPLETE -->` marker) are machine-readable gates that downstream phases check before proceeding
+- **Domain-specific rules** (INFRA footguns, type invariant verification, sibling pattern sweeps) encode institutional memory directly into the prompt
+
+---
+
+## Contributing
+
+The pipeline dogfoods itself. Bug reports, improvements, and new command specs all flow through `/work-on`. See [CONTRIBUTING.md](https://github.com/RapierCraftStudios/ForgeDock/blob/main/CONTRIBUTING.md) and [devdocs/project/architecture.md](https://github.com/RapierCraftStudios/ForgeDock/blob/main/devdocs/project/architecture.md) for the full strategic context.

package/docs/site/command-reference.md

@@ -453,6 +453,23 @@ Measures pipeline performance, correlates with prompt changes, and proposes impr
 
 ---
 
+### `/upgrade-deps`
+
+**Autonomous dependency upgrade pipeline.**
+
+Detects outdated packages, triages them by semver risk, creates GitHub issues for eligible upgrades, and runs each through `/work-on` — so every upgrade gets investigation, compatibility verification, quality gate, review, and merge rather than a blind version bump. Major upgrades are flagged for human review unless `--allow-major` is passed.
+
+```bash
+/upgrade-deps                     # Detect + triage + report only
+/upgrade-deps --dry-run           # All phases, but create nothing
+/upgrade-deps --ecosystem npm     # Limit to one ecosystem (npm|pip|cargo)
+/upgrade-deps --allow-major       # Include major upgrades in issue creation
+/upgrade-deps --limit 5           # Cap issue creation (default: 10)
+/upgrade-deps --batch             # Group patch upgrades into one issue
+```
+
+---
+
 ## Investigation & Validation
 
 ---