forgedock 1.0.9 → 1.0.11

package/docs/site/getting-started.md

@@ -0,0 +1,168 @@
+---
+title: "Getting Started with ForgeDock in 5 Minutes"
+description: "Install ForgeDock and run your first autonomous Claude Code pipeline in under 5 minutes. Complete tutorial: install, configure, and ship your first issue."
+keywords: ["claude code commands setup", "forgedock install", "claude code pipeline", "ai agent setup"]
+---
+
+# Getting Started with ForgeDock in 5 Minutes
+
+ForgeDock turns GitHub issues into shipped code — automatically. You open an issue, type one command, and an AI agent investigates it, writes the fix, runs a quality gate, opens a PR, reviews it, and merges it.
+
+This tutorial gets you from zero to your first autonomous pipeline run in under 5 minutes.
+
+---
+
+## Prerequisites
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
+- Git and GitHub CLI (`gh`) installed and authenticated (`gh auth login`)
+- Node.js 18 or higher
+
+---
+
+## Step 1: Install ForgeDock
+
+Run the installer with `npx`:
+
+```bash
+npx forgedock
+```
+
+This symlinks all 25+ ForgeDock command specs into `~/.claude/commands/` — making them available as slash commands in every Claude Code session.
+
+**Verify the install:**
+
+```bash
+ls ~/.claude/commands/ | grep -E "work-on|review-pr|quality-gate"
+```
+
+You should see `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:
+
+```bash
+cd /path/to/your/project
+# Open Claude Code in this directory, then run:
+/forgedock-init
+```
+
+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:**
+
+```yaml
+project:
+  name: "My App"
+  owner: "my-github-org"
+  repo: "my-app"
+
+paths:
+  root: "/path/to/my-app"
+  worktree_base: "/path/to/my-app/.claude/worktrees"
+
+branches:
+  staging: "staging"
+  default: "staging"
+```
+
+---
+
+## Step 3: Open an Issue
+
+Create a GitHub issue for something real in your repo — a bug, a feature, a refactor. ForgeDock works best with issues that have:
+
+- A clear problem description
+- Expected behavior
+- Acceptance criteria
+
+You can create one manually on GitHub, or use:
+
+```bash
+/issue "The login button is misaligned on mobile Safari"
+```
+
+Note the issue number — let's say it's `#42`.
+
+---
+
+## Step 4: Run Your First Pipeline
+
+Open Claude Code in your project directory and run:
+
+```bash
+/work-on 42
+```
+
+That's it. ForgeDock now:
+
+1. **Investigates** — reads the issue, traces the code, identifies the root cause
+2. **Architects** — plans the implementation order, identifies all affected files
+3. **Builds** — implements the fix in an isolated git worktree
+4. **Quality gates** — checks for 14+ categories of common defects
+5. **Reviews** — runs 9 domain-specific review agents (security, logic, UX, etc.)
+6. **Merges** — opens a PR and merges it when review passes
+
+---
+
+## Step 5: See the Result
+
+While the pipeline runs, you can watch it in real time on the GitHub issue. ForgeDock writes structured comments at every stage:
+
+```
+<!-- FORGE:INVESTIGATOR -->   ← What it found
+<!-- FORGE:CONTRACT -->       ← What it will build
+<!-- FORGE:ARCHITECT -->      ← Implementation plan
+<!-- FORGE:BUILDER -->        ← What was built
+<!-- FORGE:TRAJECTORY -->     ← Full audit trail
+```
+
+When it's done, you'll have a merged PR, a closed issue, and a complete audit trail in GitHub.
+
+---
+
+## What Just Happened?
+
+ForgeDock uses **GitHub as a knowledge graph**. Every stage writes structured data that the next stage reads. This means:
+
+- A new agent session can pick up exactly where the last one left off
+- Review agents can see the full investigation context, not just the diff
+- Future issues touching the same code can learn from what was found here
+
+For a deep dive into how this works, read [How ForgeDock's Knowledge Graph Works](./how-it-works.md).
+
+---
+
+## Next Steps
+
+- [How ForgeDock's Knowledge Graph Works](./how-it-works.md) — understand the architecture
+- [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
+
+**`/work-on` not found in Claude Code**
+
+The symlink wasn't created. Re-run `npx forgedock` and check `ls ~/.claude/commands/`.
+
+**`forge.yaml` not found**
+
+Run `/forgedock-init` in your project directory inside Claude Code, or copy `forge.yaml.example` from the ForgeDock repo and edit it.
+
+**`gh` auth errors**
+
+Run `gh auth login` and complete the OAuth flow. ForgeDock uses `gh` for all GitHub operations.
+
+**Pipeline stops at investigation**
+
+The issue may have been marked `workflow:invalid`. Check the issue comments for the investigation report — it will explain why.

package/docs/site/how-it-works.md

@@ -0,0 +1,191 @@
+---
+title: "How ForgeDock's Knowledge Graph Works"
+description: "Deep dive into how ForgeDock uses GitHub as a persistent AI agent memory system. FORGE annotations, context passing, and cross-issue knowledge explained."
+keywords: ["ai agent memory", "ai agent knowledge graph", "forge annotations", "claude code memory", "ai agent context"]
+---
+
+# How ForgeDock's Knowledge Graph Works
+
+Every AI coding agent faces the same fundamental problem: **it forgets everything between sessions.**
+
+When a conversation ends or context compacts, the agent loses all the context it gathered — why the code looks the way it does, which approaches were already tried, which files are connected. The next session starts from scratch.
+
+ForgeDock solves this by treating GitHub as a persistent, structured memory system that every agent can read and write.
+
+---
+
+## The Core Insight: GitHub Is Already a Knowledge Graph
+
+Your repository already contains everything an agent needs to know:
+
+- **Issues** — what problems were reported and why
+- **Pull requests** — what was changed and the reasoning behind it
+- **Commits** — the exact changes, with references back to issues
+- **Comments** — investigator notes, architectural decisions, review findings
+- **Labels** — current workflow state at a glance
+- **Blame** — who changed each line and when, tracing back to the originating issue
+
+These aren't just records for humans. They're **queryable, structured data** that an agent can use as memory.
+
+ForgeDock adds the coordination layer that makes agents use this data systematically.
+
+---
+
+## FORGE Annotations: Machine-Readable Comments
+
+The key mechanism is **FORGE annotations** — structured HTML comment blocks posted to GitHub issues and PRs at every pipeline stage.
+
+Each annotation has a type that identifies which pipeline agent wrote it and what it contains:
+
+```
+<!-- FORGE:INVESTIGATOR -->   Root cause, affected files, confidence level
+<!-- FORGE:CONTRACT -->       What will be built — deliverables, acceptance criteria
+<!-- FORGE:ARCHITECT -->      Implementation plan — file order, consistency checks, risks
+<!-- FORGE:CONTEXT -->        Historical pitfalls, past bugs, patterns to avoid
+<!-- FORGE:BUILDER -->        What was built — commits, files changed, criteria status
+<!-- FORGE:REVIEWER -->       Review findings — severity, pattern, prevention rule
+<!-- FORGE:TRAJECTORY -->     Full audit trail — every phase, every decision
+```
+
+Every downstream agent reads these before starting work. The builder reads the investigator's root cause analysis. The reviewer reads the builder's implementation notes. The architect reads the context agent's historical findings.
+
+**The result**: agents that follow structured data, not guesses.
+
+---
+
+## The Pipeline: A Relay Race
+
+When you run `/work-on 42`, ForgeDock runs a sequential pipeline where each stage hands off structured context to the next:
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                     GITHUB (Knowledge Graph)                        │
+│                                                                     │
+│  Issues:  FORGE:INVESTIGATOR → FORGE:CONTRACT → FORGE:ARCHITECT     │
+│           → FORGE:CONTEXT → FORGE:BUILDER → FORGE:TRAJECTORY        │
+│                                                                     │
+│  PRs:     FORGE:REVIEWER (9 domain agents)                          │
+│                                                                     │
+│  Labels:  workflow:investigating → workflow:building →              │
+│           workflow:in-review → workflow:merged                      │
+│                                                                     │
+│  Every agent reads this. Every agent writes to it.                  │
+│  Nothing is lost between conversations.                             │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Stage 1: Investigation
+
+The investigator agent reads the issue, explores the relevant code files, traces git blame, and searches for related issues. It posts a `<!-- FORGE:INVESTIGATOR -->` comment containing:
+
+- **Verdict**: CONFIRMED, PARTIAL, or INVALID
+- **Root Cause**: specific file:line references
+- **Affected Files**: complete list of what needs to change
+- **Evidence**: function names, behavior observed
+- **Decomposition Assessment**: whether to split into sub-issues
+
+### Stage 2: Architecture
+
+Before writing any code, the architect agent traces all affected code paths, identifies data flow, and checks for consistency invariants. This prevents the most common build failures — missing callers, type mismatches, broken imports.
+
+The `<!-- FORGE:ARCHITECT -->` comment contains an ordered implementation plan. The builder follows this exactly.
+
+### Stage 3: Context Gathering
+
+The context agent surfaces **institutional memory** — past review findings on the same files, historical bugs in the same module, patterns that have caused bugs before. This is the agent equivalent of asking a senior engineer "what should I know before touching this?"
+
+### Stage 4: Build
+
+The builder reads the architecture plan and implements in the specified order. It works in an isolated git worktree (not the main repo checkout) to avoid interfering with other in-flight work.
+
+### Stage 5: Quality Gate
+
+Before committing, the quality gate runs 14+ checks covering: security, SQL safety, auth model, env var completeness, frontend proxy wiring, deployment config, and more. The builder iterates until the gate passes (max 3 iterations).
+
+### Stage 6: Review
+
+Nine specialized review agents examine the PR simultaneously: security, business logic, frontend, backend, database, infrastructure, documentation, test coverage, and dependency audit. Each finding becomes a separate GitHub issue that flows through the same pipeline.
+
+---
+
+## Compaction Resilience: The Agent Can Always Resume
+
+Claude Code sessions have context limits. When a session compacts, the in-memory state is lost. ForgeDock is designed for this.
+
+**The rule**: Write state to GitHub after every significant step. Re-read GitHub state at the start of every phase.
+
+When a new session runs `/work-on 42`, it:
+
+1. Reads the issue body and all comments
+2. Checks existing FORGE annotations to determine the current phase
+3. Reads the workflow label (`workflow:investigating`, `workflow:building`, etc.)
+4. Picks up exactly where the last session left off
+
+A new agent session running `/work-on 42` should always know what to do next by reading GitHub state alone — with no reliance on any in-memory context from previous sessions.
+
+---
+
+## Labels as State Machine
+
+GitHub labels track the workflow state of every issue:
+
+| Label | Meaning |
+|-------|---------|
+| `workflow:investigating` | Investigator agent is running |
+| `workflow:ready-to-build` | Investigation complete, queued for build |
+| `workflow:building` | Builder agent is running |
+| `workflow:in-review` | PR created, review agents running |
+| `workflow:merged` | PR merged, issue closed |
+| `workflow:invalid` | Issue was not a real problem |
+| `workflow:decomposed` | Split into sub-issues |
+
+The pipeline reads these labels to determine what to do next. A human can also manually set a label to nudge the pipeline or override its routing.
+
+---
+
+## Cross-Issue Knowledge: How History Informs the Present
+
+When the context agent runs for a new issue, it searches for:
+
+1. **Past review findings on the same files** — issues labeled `review-finding` that mention the affected filenames
+2. **Past bugs in the same module** — closed bug issues found by mining `git log` references on the affected files
+3. **Related code paths** — callers and importers of the functions being changed
+
+This means that every bug that gets fixed, and every review finding that gets filed, makes the pipeline smarter for future work on the same codebase.
+
+---
+
+## forge.yaml: The Configuration Layer
+
+The `forge.yaml` file in your repo root tells ForgeDock how your project is structured:
+
+```yaml
+project:
+  name: "My App"
+  owner: "my-github-org"
+  repo: "my-app"
+
+paths:
+  root: "/path/to/repo"
+  worktree_base: "/path/to/worktrees"
+
+branches:
+  staging: "staging"          # Fast-lane PR target
+  default: "staging"
+  feature_pattern: "milestone/{slug}"  # Milestone-gated feature lane
+
+project_board:
+  owner: "my-github-org"
+  project_number: 1
+```
+
+ForgeDock resolves this once at the start of every pipeline run. Every `gh` command uses the correct repo. Every branch creation targets the correct base.
+
+---
+
+## Next Steps
+
+- [Getting Started with ForgeDock in 5 Minutes](./getting-started.md) — run your first pipeline
+- [ForgeDock vs. Manual Claude Code Workflows](./vs-manual-workflows.md) — why this beats ad-hoc prompting
+- [The FORGE Annotation Protocol](./forge-annotation-protocol.md) — technical spec for FORGE annotations
+- [Complete Command Reference](./command-reference.md) — all 25 commands

package/docs/site/index.md

@@ -0,0 +1,59 @@
+---
+title: "ForgeDock Documentation"
+description: "Official documentation for ForgeDock — the autonomous AI development pipeline that uses GitHub as a structured knowledge graph for Claude Code agents."
+keywords: ["forgedock docs", "claude code pipeline", "ai agent documentation", "forgedock guide"]
+---
+
+# ForgeDock Documentation
+
+ForgeDock is an autonomous development pipeline for Claude Code. You open a GitHub issue, type `/work-on`, and an AI agent investigates the problem, architects a solution, builds it, runs quality checks, reviews it with 9 specialized agents, and merges the PR.
+
+No more coordinating between agent sessions. No more lost context. No more starting from scratch.
+
+---
+
+## Get Started
+
+**New to ForgeDock?** Start here:
+
+- **[Getting Started in 5 Minutes](./getting-started.md)** — Install, configure, and run your first pipeline
+- **[How It Works](./how-it-works.md)** — The knowledge graph architecture explained
+
+---
+
+## Guides
+
+| Page | What You'll Learn |
+|------|-------------------|
+| [Getting Started](./getting-started.md) | Install ForgeDock, configure forge.yaml, run `/work-on` on your first issue |
+| [How It Works](./how-it-works.md) | FORGE annotations, the pipeline relay, compaction resilience, workflow labels |
+| [ForgeDock vs. Manual Workflows](./vs-manual-workflows.md) | Why structured pipelines beat ad-hoc Claude Code sessions |
+| [FORGE Annotation Protocol](./forge-annotation-protocol.md) | Technical spec — annotation types, completion markers, querying |
+| [Command Reference](./command-reference.md) | All 25+ commands with usage, options, and examples |
+
+---
+
+## Quick Links
+
+- [GitHub Repository](https://github.com/RapierCraftStudios/ForgeDock)
+- [npm Package](https://www.npmjs.com/package/forgedock)
+- [Configuration Reference](../CONFIG.md)
+- [Report an Issue](https://github.com/RapierCraftStudios/ForgeDock/issues/new)
+
+---
+
+## Install
+
+```bash
+npx forgedock
+```
+
+Symlinks all commands into `~/.claude/commands/`. No global install, no dependencies.
+
+**Requirements**: Claude Code, Node.js 18+, `gh` CLI authenticated with GitHub.
+
+---
+
+## License
+
+ForgeDock is open source under the [AGPL-3.0 license](https://github.com/RapierCraftStudios/ForgeDock/blob/main/LICENSE).

package/docs/site/vs-manual-workflows.md

@@ -0,0 +1,167 @@
+---
+title: "ForgeDock vs. Manual Claude Code Workflows"
+description: "Compare ForgeDock's structured AI pipeline against ad-hoc Claude Code sessions. Real examples of time savings, consistency, and institutional memory."
+keywords: ["claude code workflow", "claude code best practices", "ai coding workflow", "claude code vs manual", "autonomous ai development"]
+---
+
+# ForgeDock vs. Manual Claude Code Workflows
+
+Claude Code is powerful. But out of the box, it's a blank slate — you describe what you want, it tries to figure it out, and you review what it produces. Every session is independent. Every agent starts with no memory of what came before.
+
+ForgeDock adds structure, memory, and determinism to that workflow.
+
+This page compares what a typical developer workflow looks like with and without ForgeDock — using real examples.
+
+---
+
+## The Same Bug, Two Approaches
+
+**Scenario**: Your API is returning 500 errors for free-tier users on the payments endpoint. Someone filed an issue.
+
+---
+
+### Without ForgeDock
+
+```
+You:    "I'm seeing 500 errors on /api/payments for free users. Can you fix it?"
+
+Agent:  *reads the payments file*
+        "I see a potential issue here. I'll add a nil-check for the billing profile."
+
+You:    *runs locally* "It's still broken."
+
+Agent:  "Let me look at the auth middleware too."
+        *reads middleware*
+        "I found another issue. Let me also check..."
+
+        *[session compacts — context lost]*
+
+Agent:  "I'm ready to help! What are we working on?"
+
+You:    "We were fixing the 500 errors on /api/payments..."
+```
+
+What went wrong:
+- No investigation before jumping to a fix
+- Context was lost mid-session
+- No memory that PR #38 introduced this bug 3 weeks ago
+- No knowledge that the same nil-check pattern was missed in 2 other files
+- You are the coordination layer between the agent and reality
+
+---
+
+### With ForgeDock
+
+```
+You:    /work-on 42
+
+ForgeDock:
+  → Investigates — traces bug to commit e8f21a3 (PR #38). Payment validation
+    gate assumed all users have a billing profile. Free-tier users don't.
+    12 affected users, 94 failed requests in the last 24h.
+
+  → Reads context — past bug #29 found the same nil-check pattern missing.
+    Prevention rule on file: "always null-check billing profile before
+    any payment validation."
+
+  → Architects — 2-file fix. Orders: auth guard first, then API handler.
+    Notes that 3 other files use the same pattern and may need the same fix.
+
+  → Builds — implements nil-check in both files, following the pattern from
+    the previous safe fix. Quality gate passes on first iteration.
+
+  → Reviews — 9 agents check the PR. Security agent confirms no auth bypass.
+    Logic agent confirms free-tier path is handled at every branch.
+
+  → Merges — PR opened and merged.
+
+You:    *reviews merged PR on GitHub*
+```
+
+What was different:
+- Root cause identified before any code was touched
+- Historical context surfaced automatically (past nil-check bug)
+- Sibling files checked for the same pattern
+- Complete audit trail on the GitHub issue
+- You reviewed, not coordinated
+
+---
+
+## Side-by-Side Comparison
+
+| | Manual Claude Code | ForgeDock |
+|---|---|---|
+| **Investigation** | Agent reads what you point it at | Systematic root-cause analysis with git blame, related issues |
+| **Context** | What you remember to include | Historical findings, past bugs, known pitfalls — all automatic |
+| **Planning** | Agent decides as it goes | Explicit architecture plan, implementation order, consistency checks |
+| **Compaction** | Work lost, restart from scratch | Full resume — reads GitHub state to pick up exactly where it left off |
+| **Quality** | You notice what's wrong in review | 14-category quality gate before commit |
+| **Review** | Manual PR review | 9 specialized domain agents |
+| **Findings** | Ad-hoc comments | Structured issues that flow through the same pipeline |
+| **Audit trail** | Scattered conversation | Complete `FORGE:TRAJECTORY` on every issue |
+| **Repeatability** | Varies by prompt | Same structured process every time |
+
+---
+
+## Where Manual Workflows Still Win
+
+ForgeDock isn't the right tool for everything. Manual Claude Code sessions are better for:
+
+- **Exploratory work** — when you're not sure what you want yet
+- **Rapid prototyping** — throwaway code that won't go to production
+- **One-off questions** — "how does this library work?"
+- **Interactive design** — iterative UI tweaks that need constant visual feedback
+
+ForgeDock is optimized for **production work on real codebases** — bugs, features, refactors that need to be investigated, implemented correctly, reviewed, and shipped.
+
+---
+
+## The Memory Problem in Practice
+
+Here's a real pattern that happens constantly without structured memory:
+
+1. **Month 1**: Bug #12 — nil-check missing in payments. Fixed.
+2. **Month 2**: PR #38 adds new payment flow. Nobody remembered rule from Bug #12. Same nil-check missing.
+3. **Month 3**: Bug #67 — 500 errors for free users. Root cause: the nil-check from Month 1 pattern wasn't followed.
+
+With ForgeDock, when the context agent runs for Bug #67, it searches for past review findings on the payments files. It finds Bug #12's root cause and the nil-check prevention rule. That rule is surfaced to the builder before any code is written.
+
+The same mistake doesn't happen twice.
+
+---
+
+## The Coordination Cost
+
+In a manual workflow, **you are the coordination layer**. You:
+
+- Remember what the agent found in the last session
+- Decide what files to point it at
+- Notice when it's missing related files
+- Check if the fix has side effects in other modules
+- Run the tests and relay results back
+- Manage the PR and review process
+
+ForgeDock handles all of this. The human's job narrows to: open issue, type `/work-on`, review merged PR.
+
+That's not a small difference. For a team shipping 20+ issues per week, eliminating coordination overhead compounds.
+
+---
+
+## What the Workflow Looks Like at Scale
+
+With ForgeDock, you can run multiple pipelines in parallel:
+
+```bash
+/orchestrate milestone launch-campaign
+```
+
+This spawns sub-agents that each run the full `/work-on` pipeline on every open issue in the milestone, in parallel — each in its own isolated git worktree, each writing to its own GitHub issue thread. No interference between agents. No coordination needed.
+
+---
+
+## Next Steps
+
+- [Getting Started with ForgeDock in 5 Minutes](./getting-started.md) — try it yourself
+- [How ForgeDock's Knowledge Graph Works](./how-it-works.md) — understand the architecture
+- [The FORGE Annotation Protocol](./forge-annotation-protocol.md) — the specification behind the pipeline
+- [Complete Command Reference](./command-reference.md) — all 25 commands