forgedock 1.0.21 → 1.0.22

package/docs/site/annotations-explained.md

@@ -0,0 +1,55 @@
+---
+title: "What Are Those FORGE Comments on My GitHub Issues?"
+description: "A 2-minute, plain-English explainer of FORGE annotations — the structured comments ForgeDock agents post on your GitHub issues and PRs. What they are, why they matter, and whether you should touch them."
+keywords: ["forge annotations explained", "forgedock comments", "ai agent github comments", "claude code annotations", "what are forge comments"]
+---
+
+# What Are Those Comments on My GitHub Issues?
+
+After your first ForgeDock run, your GitHub issue fills up with comments that start like this:
+
+```html
+<!-- FORGE:INVESTIGATOR -->
+<!-- FORGE:CONTRACT -->
+<!-- FORGE:ARCHITECT -->
+<!-- FORGE:BUILDER -->
+```
+
+These are **FORGE annotations** — structured notes each pipeline stage leaves behind so the next stage (and your future self) can pick up exactly where the last one stopped. They're how your agents remember things.
+
+## Before and After
+
+**A bare GitHub issue:** a title, a description, and... nothing else. Every time an agent touches it, it starts from zero — re-reading the code, re-guessing the root cause, re-deciding the approach.
+
+**An issue with FORGE annotations:** a full paper trail. The investigator's findings, the architect's plan, the builder's contract, and the review results all live on the issue. Any agent — or any teammate — can scroll the thread and see the whole story.
+
+## How It Works in 30 Seconds
+
+When you run `/work-on #42`:
+
+1. The **investigator** traces the root cause and posts its findings as a `FORGE:INVESTIGATOR` comment.
+2. The **architect** reads that comment, then posts its implementation plan.
+3. The **builder** reads the plan, writes the code, and posts what it built.
+4. **Review** reads everything above and records the outcome.
+
+Each stage builds on the last. Your agents never start blind — even after Claude's context window resets, the next session just reads the thread and resumes.
+
+Here's a real one:
+
+```
+<!-- FORGE:INVESTIGATOR -->
+Verdict: CONFIRMED. All 27 command spec files load into context
+on every session, blowing the token budget.
+Root cause: symlink-based install pulls in every file eagerly.
+Affected: bin/forgedock.mjs
+```
+
+## Do I Need to Edit Them?
+
+**No.** FORGE annotations are machine-generated and machine-consumed. You don't have to write, edit, or delete them — the pipeline manages them for you. The `<!-- ... -->` wrapper means they render as invisible HTML comments, so they won't clutter your issue's rendered view.
+
+Read them whenever you want visibility into what your agents are doing. That's the whole point: the work is transparent and auditable, right there in GitHub.
+
+## Want the Technical Details?
+
+If you're building your own agent pipeline or contributing to ForgeDock, the full machine-readable format — every annotation type, completion markers, and parsing rules — is documented in the [FORGE Annotation Protocol](./forge-annotation-protocol.md).

package/docs/site/command-learning-path.md

@@ -0,0 +1,104 @@
+---
+title: "ForgeDock Command Learning Path"
+description: "A tiered learning path for ForgeDock's slash commands. Learn the 3 essential commands first, then add team, operations, and pipeline-tuning commands as you need them."
+keywords: ["claude code commands guide", "forgedock learning path", "claude code getting started", "which claude code commands to learn", "ai pipeline commands"]
+---
+
+# Command Learning Path
+
+ForgeDock installs 25+ slash commands. You do **not** need to learn them all. Most of the time you'll use three.
+
+This page tiers every command by *when you need it* — so you can start small and add commands as your workflow grows. For an alphabetical, domain-grouped lookup of every command, see the [Complete Command Reference](./command-reference.md).
+
+---
+
+## Start here: 3 commands
+
+If you only learn three commands, learn these. They cover the entire issue-to-merge loop:
+
+```text
+/issue       →  describe what you want, get a pipeline-ready issue
+/work-on #N  →  investigate, build, review, and merge it automatically
+/review-pr   →  review a pull request with domain-specialist agents
+```
+
+Everything below is optional and additive. Come back when you hit the situation each tier describes.
+
+---
+
+## Tier 1 — Essential
+
+**When you need this:** Day 1. This is the minimum viable ForgeDock.
+
+| Command | What it does |
+|---------|-------------|
+| `/work-on #N` | Pick up an issue and run the full pipeline: investigate → build → review → merge |
+| `/issue` | Create a well-structured issue the pipeline can consume reliably |
+| `/review-pr` | Review a PR with context-aware, domain-specialist agents |
+
+With just these three, you can ship a change end-to-end: write an issue, run it, and review the result.
+
+---
+
+## Tier 2 — Team Workflows
+
+**When you need this:** Week 1, once you're running more than one issue at a time or coordinating work across a milestone.
+
+| Command | What it does |
+|---------|-------------|
+| `/orchestrate` | Run multiple issues — or an entire milestone — in parallel |
+| `/milestone` | Plan, track, and ship a milestone |
+| `/deploy-info` | See what will deploy next: staging vs. main diff with risk assessment |
+| `/quality-gate` | Run pre-commit quality checks before you push |
+
+These commands scale ForgeDock from "one issue at a time" to "a planned body of work moving in parallel."
+
+---
+
+## Tier 3 — Operations
+
+**When you need this:** When something goes wrong in production, or when you're shipping a release.
+
+| Command | What it does |
+|---------|-------------|
+| `/rollback` | Create a revert PR to roll back a shipped feature or fix |
+| `/incident-response` | Coordinate a P0 incident: hotfix validation, timeline, postmortem |
+| `/security-audit` | Run a periodic security posture audit |
+| `/changelog` | Generate release notes from merged work |
+
+You'll reach for these occasionally, not daily — but you'll be glad they exist the moment you need them.
+
+---
+
+## Tier 4 — Pipeline Tuning
+
+**When you need this:** Advanced. Once ForgeDock is part of your daily workflow and you want to make the pipeline itself faster and smarter.
+
+| Command | What it does |
+|---------|-------------|
+| `/autopilot` | Autonomous improvement cycle: recon → triage → fix |
+| `/pipeline-health` | Self-analysis: measure pipeline performance and propose improvements |
+| `/optimize` | Generate adaptive scripts to speed up repeated pipeline work |
+| `/diagnose` | Debug pipeline failures |
+
+These commands turn ForgeDock on itself — measuring, debugging, and tuning the pipeline you run every day.
+
+---
+
+## How to grow your toolkit
+
+1. **Start with the 3 Essential commands.** Ship one issue end-to-end.
+2. **Add Tier 2 when you have more than one thing in flight.** Orchestrate a milestone instead of babysitting issues one by one.
+3. **Reach for Tier 3 only when operations demand it** — a bad deploy, an incident, a release.
+4. **Explore Tier 4 once the pipeline is routine** and you want it faster and self-tuning.
+
+You never have to memorize the full command set. Learn the next tier the day you need it.
+
+---
+
+## Next Steps
+
+- [Getting Started with ForgeDock in 5 Minutes](./getting-started.md) — install and run your first pipeline
+- [Complete Command Reference](./command-reference.md) — every command, grouped by domain, with usage and examples
+- [How ForgeDock's Knowledge Graph Works](./how-it-works.md) — understand how commands share context
+- [ForgeDock vs. Manual Claude Code Workflows](./vs-manual-workflows.md) — why structured commands beat ad-hoc prompting

package/docs/site/command-reference.md

@@ -16,6 +16,8 @@ npx forgedock
 
 After installation, every command is available as `/command-name` in any Claude Code session.
 
+**New here?** You don't need to learn all of these at once. Start with the [Command Learning Path](./command-learning-path.md) — it tiers every command by when you need it, beginning with the three you'll use on Day 1.
+
 ---
 
 ## Core Pipeline Commands
@@ -417,6 +419,7 @@ These are invoked automatically by `/work-on` but can also be run standalone.
 
 ## Next Steps
 
+- [Command Learning Path](./command-learning-path.md) — which commands to learn first, tiered by when you need them
 - [Getting Started with ForgeDock in 5 Minutes](./getting-started.md) — install and run your first pipeline
 - [How ForgeDock's Knowledge Graph Works](./how-it-works.md) — understand how commands share context
 - [ForgeDock vs. Manual Claude Code Workflows](./vs-manual-workflows.md) — why structured commands beat ad-hoc prompting

package/docs/site/getting-started.md

@@ -54,31 +54,41 @@ This symlinks all 25+ ForgeDock command specs into `~/.claude/commands/` — mak
 **Verify the install:**
 
 ```bash
-ls ~/.claude/commands/ | grep -E "work-on|review-pr|quality-gate"
+npx forgedock doctor
 ```
 
-You should see `work-on.md`, `review-pr.md`, and `quality-gate.md`.
+`doctor` runs an installation health check across six categories — command symlinks, `forge.yaml`, required tools (`gh`, `yq`, Claude Code), GitHub workflow labels, and Playwright MCP — and prints a pass/fail/warn line with a fix hint for each:
+
+```
+ForgeDock Doctor — Installation Health Check
+
+  ✔  Command symlinks  25 symlinks valid
+  ✔  gh CLI  installed and authenticated
+  ✔  yq  yq (https://github.com/mikefarah/yq/) version v4.x
+  ✔  Claude Code  v2.x (compatible, >= v2.0.0)
+  ⚠  Playwright MCP  Not registered — needed for /qa-sweep
+
+  All checks passed. ForgeDock installation is healthy.
+```
+
+It exits `0` when everything passes and `1` if any check fails, so you can also use it in CI. The `forge.yaml` and GitHub-label checks will fully pass once you finish Step 2 below — re-run `doctor` any time your setup feels off.
+
+> Prefer a quick spot-check? `ls ~/.claude/commands/ | grep -E "work-on|review-pr|quality-gate"` should list `work-on.md`, `review-pr.md`, and `quality-gate.md`.
 
 ---
 
 ## Step 2: Configure Your Repository
 
-In your project root, initialize a `forge.yaml` config file:
+ForgeDock reads a single `forge.yaml` in your project root. **Start minimal** — only the `project`, `paths`, and `branches` sections are required. Everything else is optional and falls back to sensible defaults; add sections as you need them.
+
+The fastest way to get a working config is the `--minimal` flag, which scans your repo and writes just the required sections with detected values:
 
 ```bash
 cd /path/to/your/project
-# Open Claude Code in this directory, then run:
-/forgedock-init
+npx forgedock init --minimal
 ```
 
-The `/forgedock-init` command scans your repo and generates a `forge.yaml` with:
-
-- Your GitHub repo owner and name
-- Worktree base path
-- Branch strategy (staging vs. feature lanes)
-- Project board connection (optional)
-
-**Minimal `forge.yaml` example:**
+This produces a short, readable `forge.yaml` like the one below — this is essentially ForgeDock's own real-world config:
 
 ```yaml
 project:
@@ -91,10 +101,17 @@ paths:
   worktree_base: "/path/to/my-app/.claude/worktrees"
 
 branches:
+  default: "main"
   staging: "staging"
-  default: "staging"
+  feature_pattern: "milestone/{slug}"
 ```
 
+That's the whole config. Run `npx forgedock doctor` to confirm it's valid.
+
+> **The three required sections are `project`, `paths`, and `branches`** — `npx forgedock init --minimal` auto-detects `paths` for you (so worktrees land in the right place) and you rarely need to touch it. Everything else (project board, review context, verification commands, multi-repo routing) is optional and falls back to sensible defaults. Browse [`forge.yaml.example`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/forge.yaml.example) and [`docs/CONFIG.md`](https://github.com/RapierCraftStudios/ForgeDock/blob/main/docs/CONFIG.md) when you're ready to customize.
+
+**Prefer guided, AI-powered setup?** Open Claude Code in your project directory and run `/forgedock-init` instead — it scans your repo and fills in the optional sections (repo owner/name, worktree path, branch strategy, project board) for you. Plain `npx forgedock init` (no flag) generates the full annotated template with every optional section commented out.
+
 ---
 
 ## Step 3: Open an Issue
@@ -164,14 +181,19 @@ For a deep dive into how this works, read [How ForgeDock's Knowledge Graph Works
 
 ## Next Steps
 
+- [Command Learning Path](./command-learning-path.md) — which commands to learn next, tiered by when you need them
 - [How ForgeDock's Knowledge Graph Works](./how-it-works.md) — understand the architecture
+- [What Are Those FORGE Comments?](./annotations-explained.md) — a 2-minute explainer for the annotations on your issues
 - [ForgeDock vs. Manual Claude Code Workflows](./vs-manual-workflows.md) — why this beats ad-hoc prompting
 - [Complete Command Reference](./command-reference.md) — all 25 commands with examples
+- [Troubleshooting & Recovery Guide](./troubleshooting.md) — diagnose and recover from common pipeline failures
 
 ---
 
 ## Troubleshooting
 
+The quick fixes below cover the most common first-run issues. For the full list of failure modes — quality gate failures, worktree conflicts, stale labels, rate limits, and more — see the [Troubleshooting & Recovery Guide](./troubleshooting.md).
+
 **`/work-on` not found in Claude Code**
 
 The symlink wasn't created. Re-run `npx forgedock` and check `ls ~/.claude/commands/`.

package/docs/site/troubleshooting.md

@@ -0,0 +1,208 @@
+---
+title: "ForgeDock Troubleshooting & Recovery Guide"
+description: "Diagnose and recover from the most common ForgeDock pipeline failures: missing forge.yaml, gh auth errors, quality gate failures, worktree conflicts, stale labels, and API rate limits. Symptom, cause, and fix for each."
+keywords: ["forgedock troubleshooting", "claude code pipeline errors", "work-on recovery", "forge.yaml not found", "gh auth login", "quality gate failed"]
+---
+
+# ForgeDock Troubleshooting & Recovery Guide
+
+When the pipeline stops, it should tell you exactly why and how to recover. This guide covers the most common failure modes, each with its **symptom**, **cause**, and **fix**.
+
+ForgeDock is resumable by design: GitHub is the source of truth. After fixing the underlying problem, you can almost always re-run `/work-on #N` and the pipeline picks up where it left off — it reads the issue's comments and labels to reconstruct state.
+
+> Tip: `/work-on` runs a Phase 0 pre-flight check that catches several of these problems before the pipeline spends any tokens. The errors below mirror what that check reports.
+
+---
+
+## 1. `forge.yaml` not found
+
+**Symptom**
+The pipeline stalls early, or an agent guesses project values (owner, repo, paths) instead of reading them.
+
+**Cause**
+Every ForgeDock command reads `forge.yaml` from the repository root for project identity, paths, and branch configuration. If the file is missing, there is nothing to resolve `GH_REPO`, `REPO_PATH`, or branch targets from.
+
+**Fix**
+```bash
+npx forgedock init
+```
+This scans your codebase and generates a `forge.yaml`. Alternatively, copy `forge.yaml.example` from the ForgeDock repo to `forge.yaml` and edit the `project`, `paths`, and `branches` sections. Re-run `/work-on #N` afterward.
+
+---
+
+## 2. `forge.yaml` has a syntax error
+
+**Symptom**
+A parse error appears in agent output, or values that clearly exist in the file resolve as empty.
+
+**Cause**
+`forge.yaml` is not valid YAML — usually a bad indentation level, a tab character where spaces are required, or an unquoted value containing a special character (`:`, `#`, `@`).
+
+**Fix**
+Validate the file and find the offending line:
+```bash
+# With yq (recommended):
+yq '.' forge.yaml
+
+# Or with Python:
+python -c "import yaml,sys; yaml.safe_load(open('forge.yaml'))"
+```
+Both print the line and column of the first error. Fix the indentation or quote the value (e.g. `description: "turns GitHub into a knowledge graph"`), then re-run.
+
+---
+
+## 3. `gh` CLI not authenticated
+
+**Symptom**
+A `gh` command fails partway through the pipeline with `HTTP 401`, `Bad credentials`, or `gh: To use GitHub CLI, please run gh auth login`.
+
+**Cause**
+ForgeDock uses the GitHub CLI for every GitHub operation (reading issues, posting comments, creating PRs, merging). If `gh` is not authenticated — or the token expired — these calls fail.
+
+**Fix**
+```bash
+gh auth login
+gh auth status   # confirm you are logged in and the token has repo scope
+```
+Phase 0 pre-flight detects this before the pipeline starts. Re-run `/work-on #N` once `gh auth status` is clean.
+
+---
+
+## 4. Quality gate failed
+
+**Symptom**
+```
+QUALITY GATE: FAIL
+```
+The build stops after listing HIGH/MEDIUM findings, and the issue keeps a `workflow:building` label.
+
+**Cause**
+The pre-commit quality gate caught defects (security, correctness, or convention violations) that the review would otherwise flag. The pipeline retries fixes up to 3 times; if it still fails, it adds `needs-human` and stops.
+
+**Fix**
+Read the findings in the issue comment, fix the flagged issues in the worktree, then re-run `/work-on #N` to resume the build. If `needs-human` was added, address the findings and remove the label before re-running. The worktree path is recorded in the build comment on the issue.
+
+---
+
+## 5. Worktree already exists
+
+**Symptom**
+```
+fatal: '<path>' already exists
+```
+when the pipeline tries to create a git worktree for the issue.
+
+**Cause**
+A previous run created a worktree for this branch and it was never cleaned up — usually because the run was interrupted before Phase 6 cleanup.
+
+**Fix**
+Either reuse it (if it's on the correct branch) or remove and let the pipeline recreate it:
+```bash
+git worktree list                      # find the path
+git worktree remove <path> --force     # remove the stale worktree
+git branch -D <branch>                 # optional: delete the leftover branch
+```
+Re-run `/work-on #N`.
+
+---
+
+## 6. Label in the wrong state
+
+**Symptom**
+The pipeline is confused by labels that don't match reality — e.g. an issue tagged `workflow:merged` with no merged PR, or `workflow:building` with no open branch.
+
+**Cause**
+A run was interrupted between updating a label and completing the corresponding phase, leaving a stale `workflow:*` label.
+
+**Fix**
+```bash
+/cleanup
+```
+`/cleanup` sweeps closed issues and stale labels, reconciling `workflow:*` state with actual PR/branch status. Then re-run `/work-on #N` if the issue still needs work.
+
+---
+
+## 7. Branch already exists
+
+**Symptom**
+```
+fatal: a branch named 'feat/issue-N-slug' already exists
+```
+
+**Cause**
+A previous run created the implementation branch and it wasn't deleted after merge or abandonment.
+
+**Fix**
+- **To continue** the existing work: check out the branch and let the pipeline reuse it.
+- **To restart** from scratch:
+```bash
+git branch -D feat/issue-N-slug        # local
+git push origin --delete feat/issue-N-slug   # remote, if pushed
+```
+Re-run `/work-on #N`.
+
+---
+
+## 8. PR targets the wrong branch
+
+**Symptom**
+A PR is opened against `main`, or against a branch that isn't the issue's correct target.
+
+**Cause**
+ForgeDock never targets `main`. Fast-lane issues (no milestone) target `staging`; milestone issues target `milestone/{slug}`. A wrong target usually means the lane was misclassified or the PR was created manually.
+
+**Fix**
+The `/work-on` pipeline computes the correct base from the issue's milestone and re-targets automatically — close the mis-targeted PR and re-run `/work-on #N`. To retarget an existing PR without recreating it:
+```bash
+gh pr edit <PR_NUMBER> --base staging          # or milestone/<slug>
+```
+
+---
+
+## 9. Missing workflow labels
+
+**Symptom**
+The pipeline can't transition state; `gh issue edit --add-label "workflow:..."` fails with `label not found`.
+
+**Cause**
+The repository doesn't have ForgeDock's managed `workflow:*` labels yet (new repo, or labels were deleted).
+
+**Fix**
+```bash
+npx forgedock labels setup          # from the project directory
+# or, for a different repo:
+npx forgedock labels setup --repo owner/repo
+```
+This idempotently bootstraps every managed label with canonical colors and descriptions. Re-run `/work-on #N`.
+
+---
+
+## 10. GitHub API rate limit exceeded
+
+**Symptom**
+```
+API rate limit exceeded
+```
+`gh` commands fail in bursts, often during heavy orchestration runs.
+
+**Cause**
+The GitHub REST API allows 5,000 requests/hour per token, shared across all tools and agents. Parallel orchestration can exhaust this.
+
+**Fix**
+Check your remaining quota and reset time:
+```bash
+gh api rate_limit --jq '.resources.core'
+```
+Wait until the `reset` timestamp, or authenticate with a Personal Access Token that has higher limits. Reduce parallelism (fewer concurrent `/orchestrate` agents) to stay under the cap. Re-run `/work-on #N` after the limit resets.
+
+---
+
+## Still stuck?
+
+If your problem isn't listed here, or a fix didn't work:
+
+1. **Read the issue's comments.** Every phase writes a structured `FORGE:*` comment (investigation, contract, builder, trajectory). They explain what the pipeline saw and decided.
+2. **Check the labels.** The `workflow:*` label tells you which phase the issue is in.
+3. **Re-run `/work-on #N`.** The pipeline is idempotent and resumable — re-running is safe and usually cheap.
+
+If none of that resolves it, open an issue on the [ForgeDock GitHub repository](https://github.com/RapierCraftStudios/ForgeDock/issues) with the failing command, the relevant `FORGE:*` comment, and the error output.