forgedock 1.0.21 → 1.0.22

package/README.md

@@ -26,25 +26,17 @@
 
 <br />
 
-## Why ForgeDock
-
-AI coding agents forget everything between sessions. They re-investigate the same bugs, miss context from past PRs, and make mistakes that were already caught and fixed last week. There's no institutional memory.
+## What ForgeDock Does
 
-ForgeDock fixes this by using **GitHub itself** as the memory layer. Every pipeline stage writes structured `FORGE:` annotations to issues and PRs. Every downstream agent reads them. When a new session starts — even after Claude's context resets — the agent queries GitHub and picks up exactly where the last one left off.
-
----
+ForgeDock runs the full issue lifecycle inside Claude Code — **investigate, architect, build, quality-gate, review, and merge** — autonomously. You open an issue, run `/work-on #42`, and click merge. Every stage writes structured context back to GitHub, so the next agent starts smart, not blind.
 
-## How Is This Different
+```
+You:        /work-on #42
+ForgeDock:  Investigate → Architect → Build → Quality Gate → Review → open PR
+You:        click merge
+```
 
-ForgeDock is **not another AI coding agent.** It's a set of prompt-engineered command specs (`.md` files) that run inside Claude Code. No new runtime, no separate process, no vendor lock-in beyond what you already use.
-
-| | ForgeDock | Plain Claude Code | Cursor / Windsurf | Devin / Sweep |
-|---|---|---|---|---|
-| Memory across sessions | Structured annotations on GitHub | CLAUDE.md + manual notes | Per-project context | Proprietary cloud state |
-| Autonomous pipeline | Full lifecycle: investigate → merge | Manual, step by step | Autocomplete + chat | Autonomous but opaque |
-| Review quality | 9 domain-specialist agents | You review everything | Basic suggestions | Varies |
-| Infrastructure needed | None — just `npx forgedock` | None | IDE-specific | Cloud service |
-| Codebase visibility | Everything stays on GitHub | Local | Local + cloud sync | Cloud-only |
+No new runtime, no separate process, no cloud service — just prompt-engineered command specs that run inside the Claude Code you already use.
 
 ---
 
@@ -61,35 +53,30 @@ ForgeDock is **not another AI coding agent.** It's a set of prompt-engineered co
 
 > **Cost note:** ForgeDock itself is free and open-source. It orchestrates Claude Code sessions, so you pay your normal Anthropic API usage. A typical `/work-on` run on a straightforward bug uses roughly the same tokens as a 15–20 minute manual Claude Code session.
 
-<details>
-<summary><strong>See a real pipeline run</strong></summary>
+---
 
-Here's what a real run looks like on [issue #619](https://github.com/RapierCraftStudios/ForgeDock/issues/619) — a performance bug where command specs were burning ~200K tokens in context:
+## How It Works
 
 ```
-FORGE:INVESTIGATOR  →  CONFIRMED. All 27 command spec files (848KB) load into
-                        context at session start via symlinks. ~200K tokens wasted.
-
-FORGE:CONTRACT      →  Replace symlink-based install with stub-file pattern.
-                        Installer parses frontmatter, writes minimal stubs.
-
-FORGE:CONTEXT       →  Issue #577: install() had overly broad catch{} — fixed to
-                        check err.code === 'ENOENT'. Issue #587: Windows writes
-                        regular files, not symlinks — keep both paths working.
-
-FORGE:ARCHITECT     →  3 new functions in bin/forgedock.mjs: parseFrontmatter(),
-                        generateStubContent(), updated install() flow.
-
-FORGE:BUILDER       →  Branch feat/stub-install-pattern-619, 1 file changed.
-
-FORGE:REVIEW        →  Auto-merged to staging.
-
-FORGE:TRAJECTORY    →  Full audit trail recorded.
+Issue → Investigate → Architect → Build → Quality Gate → Review → Merge
+              ↓            ↓         ↓          ↓            ↓
+        writes to     reads from  reads from  reads from   writes to
+         GitHub        GitHub      GitHub      GitHub       GitHub
 ```
 
-The context phase surfaced two historical bugs (#577, #587) in the same module — preventing the builder from repeating known mistakes. [View the full issue →](https://github.com/RapierCraftStudios/ForgeDock/issues/619)
+Each stage writes a structured annotation (`<!-- FORGE:INVESTIGATOR -->`, `<!-- FORGE:CONTRACT -->`, etc.) to the GitHub issue or PR. Each downstream stage reads what came before. The `gh` CLI is the query interface.
 
-</details>
+| Stage | What it does |
+|---|---|
+| **Investigate** | Traces root cause via `git blame`, related issues/PRs. Writes verdict, affected files, severity. |
+| **Context** | Surfaces historical bugs and known pitfalls from the same module. Institutional memory. |
+| **Architect** | Produces ordered implementation plan with exact file/function/line targets. |
+| **Build** | Writes code, creates branch, makes commits. Follows the architect's plan. |
+| **Quality Gate** | 14+ domain-specific checks (security, auth, DB, concurrency, etc.) |
+| **Review** | 9 specialist agents review the PR diff with confidence-rated findings. |
+| **Close** | Records full audit trail as `FORGE:TRAJECTORY`. |
+
+Labels track workflow state (`workflow:investigating`, `workflow:building`, `workflow:in-review`, `workflow:merged`). The pipeline resumes from whatever state GitHub says it's in — restart-safe by design.
 
 ---
 
@@ -109,9 +96,14 @@ npx forgedock
 
 # Generate config for your repo
 npx forgedock init
+
+# Verify everything is wired up correctly
+npx forgedock doctor
 ```
 
-This symlinks 25+ pipeline commands into `~/.claude/commands/` and generates a `forge.yaml` config in your project root. That's it — open Claude Code and run `/work-on #42`.
+This symlinks 25+ pipeline commands into `~/.claude/commands/` and generates a `forge.yaml` config in your project root. `npx forgedock doctor` runs an installation health check — command symlinks, `forge.yaml`, required tools (`gh`, `yq`, Claude Code), GitHub workflow labels, and Playwright MCP — printing a clear pass/fail/warn line with a fix hint for each, and exiting non-zero if anything is broken. Run it any time your setup feels off. That's it — open Claude Code and run `/work-on #42`.
+
+**Try it risk-free:** Follow the [5-minute Getting Started walkthrough](docs/site/getting-started.md) to install, configure, and run your first pipeline end-to-end. New to the commands? Start with the [Command Reference](docs/site/command-reference.md) for a guided tour of what each one does.
 
 <details>
 <summary><strong>Other install methods & commands</strong></summary>
@@ -129,6 +121,22 @@ npx forgedock uninstall    # Remove all ForgeDock commands from ~/.claude/comman
 npx forgedock help         # Show all available commands
 ```
 
+**Standalone runner** (run pipelines outside Claude Code — CI/CD, headless batch):
+```bash
+# Preview the assembled prompt + tool plan (no API key needed)
+npx forgedock run work-on 42 --dry-run
+
+# Execute headlessly via the Anthropic API directly
+export ANTHROPIC_API_KEY=sk-ant-...
+npm install @anthropic-ai/sdk        # optional dependency — only needed for live runs
+npx forgedock run work-on 42
+```
+`forgedock run` loads the same `commands/*.md` specs and drives an Anthropic
+tool-use loop directly, so the pipeline no longer depends on the Claude Code
+agent loop. Claude Code remains the recommended interactive experience; the
+runner adds CI/CD and non-Claude-Code paths. Flags: `--dry-run`, `--model <id>`,
+`--max-iterations <n>`.
+
 **AI-powered setup** (inside Claude Code):
 ```
 /forgedock-init            # Guided config walkthrough — scans your repo, queries GitHub, auto-fills forge.yaml
@@ -136,57 +144,49 @@ npx forgedock help         # Show all available commands
 
 </details>
 
----
-
-## Global Command Namespace
+<details>
+<summary><strong>See a real pipeline run</strong></summary>
 
-ForgeDock owns the **global** `~/.claude/commands/` namespace. When `npx forgedock` runs, it symlinks all pipeline commands there and writes a `.symlink-source` sentinel file so other installers can detect the owner:
+Here's what a real run looks like on [issue #619](https://github.com/RapierCraftStudios/ForgeDock/issues/619) — a performance bug where command specs were burning ~200K tokens in context:
 
 ```
-~/.claude/commands/
-  .symlink-source       ← sentinel: "ForgeDock owns this namespace"
-  work-on.md            → /path/to/forgedock/commands/work-on.md
-  review-pr.md          → /path/to/forgedock/commands/review-pr.md
-  ...
-```
+FORGE:INVESTIGATOR  →  CONFIRMED. All 27 command spec files (848KB) load into
+                        context at session start via symlinks. ~200K tokens wasted.
 
-**Project-specific commands** should install to the **project-local** `.claude/commands/` directory instead:
+FORGE:CONTRACT      →  Replace symlink-based install with stub-file pattern.
+                        Installer parses frontmatter, writes minimal stubs.
 
-```
-your-project/
-  .claude/
-    commands/
-      my-custom-command.md   ← project-local — Claude Code merges these in
+FORGE:CONTEXT       →  Issue #577: install() had overly broad catch{} — fixed to
+                        check err.code === 'ENOENT'. Issue #587: Windows writes
+                        regular files, not symlinks — keep both paths working.
+
+FORGE:ARCHITECT     →  3 new functions in bin/forgedock.mjs: parseFrontmatter(),
+                        generateStubContent(), updated install() flow.
+
+FORGE:BUILDER       →  Branch feat/stub-install-pattern-619, 1 file changed.
+
+FORGE:REVIEW        →  Auto-merged to staging.
+
+FORGE:TRAJECTORY    →  Full audit trail recorded.
 ```
 
-Claude Code merges global (`~/.claude/commands/`) and project-local (`.claude/commands/`) automatically. Project-local commands win on name collisions.
+The context phase surfaced two historical bugs (#577, #587) in the same module — preventing the builder from repeating known mistakes. [View the full issue →](https://github.com/RapierCraftStudios/ForgeDock/issues/619)
 
-If another tool runs its own install script that targets `~/.claude/commands/`, it will silently repoint ForgeDock's symlinks to its own source path — breaking all ForgeDock commands globally. The `.symlink-source` sentinel is a machine-readable warning to other installers; ForgeDock also emits a per-command warning during `npx forgedock install` when it detects a collision.
+</details>
 
 ---
 
-## How It Works
+## Where to Start
 
-```
-Issue → Investigate → Architect → Build → Quality Gate → Review → Merge
-              ↓            ↓         ↓          ↓            ↓
-        writes to     reads from  reads from  reads from   writes to
-         GitHub        GitHub      GitHub      GitHub       GitHub
-```
-
-Each stage writes a structured annotation (`<!-- FORGE:INVESTIGATOR -->`, `<!-- FORGE:CONTRACT -->`, etc.) to the GitHub issue or PR. Each downstream stage reads what came before. The `gh` CLI is the query interface.
+ForgeDock installs 25+ commands, but **you only need three to start.** They cover the entire issue-to-merge loop:
 
-| Stage | What it does |
+| Command | What it does |
 |---|---|
-| **Investigate** | Traces root cause via `git blame`, related issues/PRs. Writes verdict, affected files, severity. |
-| **Context** | Surfaces historical bugs and known pitfalls from the same module. Institutional memory. |
-| **Architect** | Produces ordered implementation plan with exact file/function/line targets. |
-| **Build** | Writes code, creates branch, makes commits. Follows the architect's plan. |
-| **Quality Gate** | 14+ domain-specific checks (security, auth, DB, concurrency, etc.) |
-| **Review** | 9 specialist agents review the PR diff with confidence-rated findings. |
-| **Close** | Records full audit trail as `FORGE:TRAJECTORY`. |
+| `/issue` | Describe what you want — get a pipeline-ready issue |
+| **`/work-on #N`** | Investigate, build, review, and merge it automatically |
+| `/review-pr` | Review a PR with domain-specialist agents |
 
-Labels track workflow state (`workflow:investigating`, `workflow:building`, `workflow:in-review`, `workflow:merged`). The pipeline resumes from whatever state GitHub says it's in — restart-safe by design.
+Everything else is additive — add commands as your workflow grows: **Team Workflows** (`/orchestrate`, `/milestone`) when you run work in parallel, **Operations** (`/rollback`, `/incident-response`) when production needs it, and **Pipeline Tuning** (`/autopilot`, `/pipeline-health`) once it's routine. See the [Command Learning Path](docs/site/command-learning-path.md) for the full tiered guide.
 
 ---
 
@@ -213,13 +213,52 @@ Labels track workflow state (`workflow:investigating`, `workflow:building`, `wor
 
 ---
 
-## Uninstall
+## Global Command Namespace
 
-```bash
-npx forgedock uninstall
+ForgeDock owns the **global** `~/.claude/commands/` namespace. When `npx forgedock` runs, it symlinks all pipeline commands there and writes a `.symlink-source` sentinel file so other installers can detect the owner:
+
+```
+~/.claude/commands/
+  .symlink-source       ← sentinel: "ForgeDock owns this namespace"
+  work-on.md            → /path/to/forgedock/commands/work-on.md
+  review-pr.md          → /path/to/forgedock/commands/review-pr.md
+  ...
 ```
 
-Removes all ForgeDock command symlinks from `~/.claude/commands/`. Your `forge.yaml` config and any `FORGE:` annotations on GitHub issues/PRs are left untouched.
+**Project-specific commands** should install to the **project-local** `.claude/commands/` directory instead:
+
+```
+your-project/
+  .claude/
+    commands/
+      my-custom-command.md   ← project-local — Claude Code merges these in
+```
+
+Claude Code merges global (`~/.claude/commands/`) and project-local (`.claude/commands/`) automatically. Project-local commands win on name collisions.
+
+If another tool runs its own install script that targets `~/.claude/commands/`, it will silently repoint ForgeDock's symlinks to its own source path — breaking all ForgeDock commands globally. The `.symlink-source` sentinel is a machine-readable warning to other installers; ForgeDock also emits a per-command warning during `npx forgedock install` when it detects a collision.
+
+---
+
+## Why ForgeDock
+
+AI coding agents forget everything between sessions. They re-investigate the same bugs, miss context from past PRs, and make mistakes that were already caught and fixed last week. There's no institutional memory.
+
+ForgeDock fixes this by using **GitHub itself** as the memory layer. Every pipeline stage writes structured `FORGE:` annotations to issues and PRs. Every downstream agent reads them. When a new session starts — even after Claude's context resets — the agent queries GitHub and picks up exactly where the last one left off.
+
+---
+
+## How Is This Different
+
+ForgeDock is **not another AI coding agent.** It's a set of prompt-engineered command specs (`.md` files) that run inside Claude Code. No new runtime, no separate process, no vendor lock-in beyond what you already use.
+
+| | ForgeDock | Plain Claude Code | Cursor / Windsurf | Devin / Sweep |
+|---|---|---|---|---|
+| Memory across sessions | Structured annotations on GitHub | CLAUDE.md + manual notes | Per-project context | Proprietary cloud state |
+| Autonomous pipeline | Full lifecycle: investigate → merge | Manual, step by step | Autocomplete + chat | Autonomous but opaque |
+| Review quality | 9 domain-specialist agents | You review everything | Basic suggestions | Varies |
+| Infrastructure needed | None — just `npx forgedock` | None | IDE-specific | Cloud service |
+| Codebase visibility | Everything stays on GitHub | Local | Local + cloud sync | Cloud-only |
 
 ---
 
@@ -237,14 +276,29 @@ Removes all ForgeDock command symlinks from `~/.claude/commands/`. Your `forge.y
 
 ---
 
+## Uninstall
+
+```bash
+npx forgedock uninstall
+```
+
+Removes all ForgeDock command symlinks from `~/.claude/commands/`. Your `forge.yaml` config and any `FORGE:` annotations on GitHub issues/PRs are left untouched.
+
+---
+
 ## Documentation
 
+- [Try ForgeDock Risk-Free](examples/forgedock-demo/) — a tiny demo repo with 5 pre-written issues; clone, `npx forgedock`, `/work-on 1`, and watch a full pipeline run without touching your real code
 - [Getting Started in 5 Minutes](docs/site/getting-started.md) — install, configure, first pipeline run
 - [How the Knowledge Graph Works](docs/site/how-it-works.md) — FORGE annotations, context relay, compaction resilience
+- [What Are Those FORGE Comments?](docs/site/annotations-explained.md) — 2-minute newcomer explainer for the annotations on your issues
 - [ForgeDock vs. Manual Workflows](docs/site/vs-manual-workflows.md) — structured pipelines vs. ad-hoc prompting
 - [ForgeDock vs. DeepWiki, AGENTS.md, and Cursor Memories](docs/comparison.md) — structural differences between context tools
 - [FORGE Annotation Protocol](docs/site/forge-annotation-protocol.md) — open standard spec for AI context passing
+- [FORGE Annotation Protocol v1.0 (formal spec)](docs/spec/forge-protocol-v1.md) — standalone, versioned, CC-BY-4.0 specification you can implement in any agent pipeline
+- [Command Learning Path](docs/site/command-learning-path.md) — which commands to learn first, tiered by when you need them
 - [Command Reference](docs/site/command-reference.md) — all 25+ commands with usage and examples
+- [Troubleshooting & Recovery Guide](docs/site/troubleshooting.md) — symptom, cause, and fix for the most common pipeline failures
 
 ---