forgedock 1.0.14 → 1.0.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +114 -255
  2. package/docs/demo.gif +0 -0
  3. package/package.json +9 -1
package/README.md CHANGED
@@ -4,342 +4,199 @@
4
4
 
5
5
  <h1>ForgeDock</h1>
6
6
 
7
- <p><strong>GitHub as a knowledge graph for AI agents.</strong></p>
7
+ <p><strong>Autonomous software development for Claude Code.</strong></p>
8
8
 
9
- <p>An autonomous development pipeline for Claude Code that uses GitHub issues, PRs, commits, and blame as structured memory — so every agent knows what happened before it, why the code looks the way it does, and what to do next.</p>
9
+ <p>A sub-agent orchestration layer with a deterministic pipeline that converts developer intent into structured GitHub issues, giving each agent a tightly scoped prompt with GitHub as its secondary context layer. Builds, fixes, researches, and ships end-to-end with a strict code quality bar that raises the baseline of your entire codebase over time. Fewer tokens, less time, better software. Built for production systems and security from the ground up. Benchmarked across 20,000+ GitHub issues on production codebases.</p>
10
10
 
11
- <a href="LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg" alt="License: AGPL-3.0" /></a>
12
- <a href="https://github.com/RapierCraftStudios/ForgeDock/stargazers"><img src="https://img.shields.io/github/stars/RapierCraftStudios/ForgeDock?style=social" alt="GitHub Stars" /></a>
13
- <a href="https://docs.anthropic.com/en/docs/claude-code"><img src="https://img.shields.io/badge/Built%20for-Claude%20Code-blueviolet" alt="Claude Code" /></a>
14
- <a href="https://github.com/RapierCraftStudios/ForgeDock/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome" /></a>
15
- <a href="https://github.com/sponsors/RapierCraftStudios"><img src="https://img.shields.io/badge/Sponsor-❤-ea4aaa.svg" alt="Sponsor" /></a>
11
+ <a href="https://www.npmjs.com/package/forgedock"><img src="https://img.shields.io/npm/dm/forgedock?label=npm%20downloads&style=flat-square&color=CB3837" alt="npm downloads/month" /></a>&nbsp;
12
+ <a href="https://www.npmjs.com/package/forgedock"><img src="https://img.shields.io/npm/v/forgedock?style=flat-square&color=CB3837" alt="npm version" /></a>&nbsp;
13
+ <a href="https://nodejs.org/"><img src="https://img.shields.io/node/v/forgedock?style=flat-square&color=339933" alt="node version" /></a>&nbsp;
14
+ <a href="https://docs.anthropic.com/en/docs/claude-code"><img src="https://img.shields.io/badge/Built%20for-Claude%20Code-7C3AED?style=flat-square" alt="Claude Code" /></a>
15
+ <br />
16
+ <a href="LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg?style=flat-square" alt="License: AGPL-3.0" /></a>&nbsp;
17
+ <a href="https://github.com/RapierCraftStudios/ForgeDock/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" alt="PRs Welcome" /></a>
16
18
 
17
19
  <br /><br />
18
20
 
19
- <!-- demo-gif-placeholder: generate with `vhs docs/demo.tape` -->
20
- <img src="docs/demo.gif" alt="ForgeDock demo — zero to PR speedrun" width="900" />
21
+ <img src="docs/demo.gif" alt="ForgeDock demo — parallel orchestration across 15+ issues" width="900" />
21
22
 
22
- <p><em>Zero to PR in one command. Agent investigates → architects → builds → opens PR with full context chain.</em></p>
23
+ <p><em>15+ issues orchestrated in parallel — investigated, built, reviewed, and shipped autonomously.</em></p>
23
24
 
24
25
  </div>
25
26
 
26
27
  <br />
27
28
 
28
- **Your AI coding agent forgets everything after every session. ForgeDock fixes that.**
29
-
30
- - Uses GitHub as structured memory — every pipeline stage writes findings agents can read later
31
- - Runs the full issue lifecycle autonomously: investigate → build → review → merge
32
- - False positive rate dropped from 44% to under 10% through a self-improving review loop
29
+ ## Why ForgeDock
33
30
 
34
- ```bash
35
- npx forgedock # install in 10 seconds
36
- ```
31
+ 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.
37
32
 
38
- > ⭐ **If ForgeDock saves you time, [star this repo](https://github.com/RapierCraftStudios/ForgeDock/stargazers)** — it helps more developers find it.
33
+ 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.
39
34
 
40
35
  ---
41
36
 
42
- ## Without ForgeDock vs. With ForgeDock
37
+ ## How Is This Different
43
38
 
44
- | Without ForgeDock | With ForgeDock |
45
- |---|---|
46
- | Agent starts every session blind — no context from prior work | Agent reads structured investigation findings, root cause, and history from GitHub |
47
- | Same bugs get introduced repeatedly across PRs | Review agents surface known pitfalls from past PRs before you commit |
48
- | Investigation gets repeated after every compaction | GitHub is the memory — a new session picks up exactly where the last one left off |
49
- | Manual: you write the issue, plan the fix, open the PR, review it | Autonomous: `/work-on #42` → investigated, built, reviewed, merged |
50
- | Review depends on whoever has capacity | 9 domain-specialist agents (security, billing, DB, concurrency, etc.) review every PR |
39
+ 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.
51
40
 
52
- ---
53
-
54
- ```
55
- You: /work-on #42
56
- ForgeDock: Investigates → Architects → Builds → Quality gates → Reviews → Opens PR
57
- You: *click merge*
58
- ```
41
+ | | ForgeDock | Plain Claude Code | Cursor / Windsurf | Devin / Sweep |
42
+ |---|---|---|---|---|
43
+ | Memory across sessions | Structured annotations on GitHub | CLAUDE.md + manual notes | Per-project context | Proprietary cloud state |
44
+ | Autonomous pipeline | Full lifecycle: investigate → merge | Manual, step by step | Autocomplete + chat | Autonomous but opaque |
45
+ | Review quality | 9 domain-specialist agents | You review everything | Basic suggestions | Varies |
46
+ | Infrastructure needed | None — just `npx forgedock` | None | IDE-specific | Cloud service |
47
+ | Codebase visibility | Everything stays on GitHub | Local | Local + cloud sync | Cloud-only |
59
48
 
60
49
  ---
61
50
 
62
- ## The Problem
63
-
64
- AI coding agents have **no lookback.** They don't know why the code they're touching was written. They can't tell that a function was shaped by a bug fix in issue #347, that a similar approach was tried and reverted in PR #891, or that three other files use the same pattern and need the same fix. They start every task blind — even within a single session.
51
+ ## What You Get
65
52
 
66
- Context window isn't the bottleneck. **Memory is.** When an agent compacts or a conversation ends, everything it learned is gone. The next agent starts from scratch. The investigation gets repeated. The same mistakes get made. There's no institutional knowledge.
53
+ | Capability | How it works |
54
+ |---|---|
55
+ | **Full-lifecycle automation** | `/work-on #42` — investigates the issue, architects a fix, builds it, runs quality gates, opens a PR, and reviews it. You click merge. |
56
+ | **Persistent agent memory** | Structured `FORGE:` annotations on GitHub issues/PRs survive context resets and session boundaries. Agents never start blind. |
57
+ | **9 specialist review agents** | Security, billing, database, concurrency, auth, frontend, API, performance, infrastructure — every PR gets domain-expert review. |
58
+ | **Cross-issue knowledge graph** | Agent fixing issue #43 reads the investigation from #42 and applies the known pattern — no re-investigation. |
59
+ | **Self-improving pipeline** | Review agents learn from past findings — recurring patterns automatically become new quality gate checks. |
60
+ | **Parallel orchestration** | `/orchestrate` decomposes milestones into waves and runs `/work-on` on each in parallel. |
67
61
 
68
- ## The Insight
62
+ > **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.
69
63
 
70
- GitHub already stores everything an agent needs to know — commits, PRs, issues, blame, cross-references. It's a knowledge graph. But AI agents don't use it that way.
64
+ <details>
65
+ <summary><strong>See a real pipeline run</strong></summary>
71
66
 
72
- ForgeDock changes that. Every pipeline stage writes **structured, machine-readable annotations** to GitHub issues and PRs. Every downstream agent reads what came before. The `gh` CLI becomes the query interface to institutional memory.
67
+ 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:
73
68
 
74
69
  ```
75
- ┌─────────────────────────────────────────────────────────────────────┐
76
- │ GITHUB (Knowledge Graph) │
77
- │ │
78
- │ Issues: FORGE:INVESTIGATOR → FORGE:CONTRACT → FORGE:ARCHITECT │
79
- │ PRs: FORGE:BUILDER → FORGE:REVIEW → FORGE:TRAJECTORY │
80
- │ Links: git blame → commit → PR → issue → related issues │
81
- │ │
82
- │ Every agent reads this. Every agent writes to it. │
83
- │ Nothing is lost between conversations. │
84
- └─────────────────────────────────────────────────────────────────────┘
85
- ```
70
+ FORGE:INVESTIGATOR → CONFIRMED. All 27 command spec files (848KB) load into
71
+ context at session start via symlinks. ~200K tokens wasted.
86
72
 
87
- When the builder agent starts, it doesn't explore the codebase from scratch. It reads the investigation comment that already traced the root cause, identified affected files, and referenced the commit that introduced the bug. When the architect agent plans the implementation, it reads historical findings from related PRs so it doesn't repeat known mistakes. When a review agent flags a finding, that finding becomes a new issue that enters the same pipeline — investigated, built, reviewed, and merged.
73
+ FORGE:CONTRACT → Replace symlink-based install with stub-file pattern.
74
+ Installer parses frontmatter, writes minimal stubs.
88
75
 
89
- The result: agents that are **deterministic**, not guessing. They follow structured data, not vibes.
76
+ FORGE:CONTEXT → Issue #577: install() had overly broad catch{} — fixed to
77
+ check err.code === 'ENOENT'. Issue #587: Windows writes
78
+ regular files, not symlinks — keep both paths working.
90
79
 
91
- ---
80
+ FORGE:ARCHITECT → 3 new functions in bin/forgedock.mjs: parseFrontmatter(),
81
+ generateStubContent(), updated install() flow.
92
82
 
93
- ## See It Working
83
+ FORGE:BUILDER → Branch feat/stub-install-pattern-619, 1 file changed.
94
84
 
95
- > **Generate the demo GIF**: Install [VHS](https://github.com/charmbracelet/vhs) and run `vhs docs/demo.tape` — it outputs `docs/demo.gif` from the tape script in this repo.
96
-
97
- Here's what a real pipeline run looks like. A user reports that an API endpoint is returning 500 errors — the pipeline takes it from there.
98
-
99
- ### Example 1: Bug fix with full context chain
100
-
101
- A user opens issue #42: *"POST /api/payments returns 500 for free-tier users."*
85
+ FORGE:REVIEW → Auto-merged to staging.
102
86
 
87
+ FORGE:TRAJECTORY → Full audit trail recorded.
103
88
  ```
104
- FORGE:INVESTIGATOR → Traced bug to commit e8f21a3 (PR #38). The payment validation
105
- gate assumed all users have a billing profile — free-tier users don't.
106
- Quantified impact: 12 affected users, 94 failed requests in the last 24h.
107
-
108
- FORGE:CONTRACT → 2-file fix: add nil-check in payment validator,
109
- add free-tier guard in the API router
110
-
111
- FORGE:CONTEXT → Surfaced 2 historical bugs in the same module:
112
- #29 (missing nil-check on subscription lookup) and
113
- #34 (billing profile race condition on signup).
114
- Known pitfall: don't skip the audit log write on early returns.
115
-
116
- FORGE:ARCHITECT → Ordered implementation plan with exact file/function/line table
117
89
 
118
- FORGE:BUILDER → Branch fix/payment-validation-free-tier-42, 2 files changed
90
+ 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)
119
91
 
120
- FORGE:REVIEW → 4 review agents, 0 findings, auto-merged to staging
121
- ```
92
+ </details>
122
93
 
123
- The context phase knew about the audit log pitfall from issue #34 — a completely different bug, months earlier, in the same module. That's institutional memory.
94
+ ---
124
95
 
125
- ### Example 2: Cross-issue knowledge graph
96
+ ## Install
126
97
 
127
- The fix for #42 only covered the `/payments` endpoint. But the same nil-check bug exists in `/invoices` and `/subscriptions`. The pipeline spawns issue #43.
98
+ **Requirements:** [Node.js 18+](https://nodejs.org/) and [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
128
99
 
129
- The context phase reads the structured data from #42 and says: *"Billing profile nil-check was already fixed in payment_validator.py (#42) — same pattern must be applied consistently."* It doesn't re-investigate. It reads the knowledge graph and applies the known fix to the remaining endpoints. 7 minutes, start to merge.
100
+ ```bash
101
+ # Install pipeline commands
102
+ npx forgedock
130
103
 
131
- ### Example 3: Review agents catch bugs across service boundaries
104
+ # Generate config for your repo
105
+ npx forgedock init
106
+ ```
132
107
 
133
- A staging-to-main deploy PR gets reviewed by four specialized agents:
108
+ 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`.
134
109
 
135
- - **Concurrency agent** — verified idempotency keys through PostgreSQL advisory locks
136
- - **Security agent** — flagged a `force_https` default change with broad blast radius
137
- - **API agent** — verified route registration consistency across all endpoints
138
- - **Billing Integrity agent** — found that the `/invoices` query still referenced an old column name that was renamed in a recent migration
110
+ <details>
111
+ <summary><strong>Other install methods & commands</strong></summary>
139
112
 
140
- That billing finding becomes a new issue — enters the same pipeline, gets investigated, built, reviewed, and merged. Bug caught before it hits production.
113
+ **Claude Code Plugin Marketplace** (v2.1.143+):
114
+ ```
115
+ /plugin marketplace add RapierCraftStudios/ForgeDock
116
+ /plugin install forgedock@forgedock
117
+ ```
141
118
 
142
- ### Example 4: The pipeline catches its own false positives
119
+ **CLI commands:**
120
+ ```bash
121
+ npx forgedock update # Pull latest commands
122
+ npx forgedock uninstall # Remove all ForgeDock commands from ~/.claude/commands/
123
+ npx forgedock help # Show all available commands
124
+ ```
143
125
 
144
- A review agent flags "no input size cap on the system key path." The investigation phase traces the full call chain and finds the cap *already exists* in a downstream quality gate module. Closed as `workflow:invalid` with an explanation of why the review agent missed it (it only inspected the text-building logic, not the downstream gate). The trajectory recorded: *"Investigation revealed fix already present."*
126
+ **AI-powered setup** (inside Claude Code):
127
+ ```
128
+ /forgedock-init # Guided config walkthrough — scans your repo, queries GitHub, auto-fills forge.yaml
129
+ ```
145
130
 
146
- The pipeline self-corrects. No wasted work. Full audit trail.
131
+ </details>
147
132
 
148
133
  ---
149
134
 
150
135
  ## How It Works
151
136
 
152
- ### The Pipeline
153
-
154
137
  ```
155
138
  Issue → Investigate → Architect → Build → Quality Gate → Review → Merge
156
- ↓ ↓ ↓ ↓ ↓
157
- writes to reads from reads from reads from writes to
158
- GitHub GitHub GitHub GitHub GitHub
139
+ ↓ ↓ ↓ ↓ ↓
140
+ writes to reads from reads from reads from writes to
141
+ GitHub GitHub GitHub GitHub GitHub
159
142
  ```
160
143
 
161
- Each stage reads the structured output of previous stages and writes its own findings back:
162
-
163
- | Stage | Reads | Writes |
164
- | --- | --- | --- |
165
- | **Investigate** | Issue body, `git blame`, related issues/PRs | `FORGE:INVESTIGATOR` — verdict, root cause, affected files, severity |
166
- | **Context** | Historical findings from related PRs, known pitfalls | `FORGE:CONTEXT` — institutional memory for this module |
167
- | **Architect** | Investigation + context findings | `FORGE:ARCHITECT` — ordered implementation plan, code paths, risks |
168
- | **Build** | Investigation + context + architect plan | `FORGE:BUILDER` — branch, commits, files changed, checklist |
169
- | **Quality Gate** | Builder output, 14+ domain-specific checks | `FORGE:QUALITY_GATE` — findings by domain (security, auth, DB, etc.) |
170
- | **Review** | PR diff, builder contract, quality gate results | `FORGE:REVIEW` — per-agent findings with evidence and confidence |
171
- | **Close** | All of the above | `FORGE:TRAJECTORY` — full audit trail of the entire run |
172
-
173
- ### GitHub as Database
174
-
175
- Every annotation is wrapped in an HTML comment tag (`<!-- FORGE:INVESTIGATOR -->`, `<!-- FORGE:CONTRACT -->`, etc.) that makes it machine-parseable. When an agent starts — even in a brand new conversation after compaction — it queries the issue via `gh` and reconstructs full context from these tags. Nothing depends on conversation history.
176
-
177
- Labels track workflow state (`workflow:investigating`, `workflow:building`, `workflow:in-review`, `workflow:merged`, `workflow:invalid`). The pipeline resumes from whatever state GitHub says it's in.
144
+ 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.
178
145
 
179
- The annotation format is an open standard. See [FORGE Annotation Protocol](docs/FORGE-PROTOCOL.md) for the full specification — annotation types, schemas, context-passing chain, and conformance tests.
180
-
181
- ### Review Agents
182
-
183
- PRs are reviewed by domain-specific agents, each with deep expertise:
184
-
185
- | Agent | Focus |
186
- | --- | --- |
187
- | Billing Integrity | Payment flows, credit debit paths, column renames |
188
- | Auth & Access Control | Endpoint auth dependencies, resource ownership |
189
- | Database | Migrations, unbounded queries, NOT NULL without DEFAULT |
190
- | Security | SQL injection, SSRF, XSS, hardcoded secrets |
191
- | Concurrency | Idempotency, advisory locks, race conditions |
192
- | Frontend | useEffect cleanup, error states, hook dependencies |
193
- | API | Route registration, proxy paths, response contracts |
194
- | Performance | N+1 queries, unbounded loops, missing indexes |
195
- | Infrastructure | Dockerfile changes, volume permissions, CI/CD |
196
-
197
- Each agent posts structured findings with confidence levels — `CONFIRMED` (traced full code path), `LIKELY` (pattern match), or `POSSIBLE` (needs verification). Findings above a severity threshold become new GitHub issues that enter the same pipeline.
198
-
199
- ### The Self-Improvement Loop
200
-
201
- Review findings from real PRs feed back into the pipeline:
202
-
203
- 1. Review agents flag patterns (e.g., "async code keeps missing cleanup")
204
- 2. `/pipeline-health` correlates findings with prompt changes and build failures
205
- 3. The quality gate evolves — new domain checks get added from recurring patterns
206
- 4. False positive rate dropped from 44% to under 10% through this loop
146
+ | Stage | What it does |
147
+ |---|---|
148
+ | **Investigate** | Traces root cause via `git blame`, related issues/PRs. Writes verdict, affected files, severity. |
149
+ | **Context** | Surfaces historical bugs and known pitfalls from the same module. Institutional memory. |
150
+ | **Architect** | Produces ordered implementation plan with exact file/function/line targets. |
151
+ | **Build** | Writes code, creates branch, makes commits. Follows the architect's plan. |
152
+ | **Quality Gate** | 14+ domain-specific checks (security, auth, DB, concurrency, etc.) |
153
+ | **Review** | 9 specialist agents review the PR diff with confidence-rated findings. |
154
+ | **Close** | Records full audit trail as `FORGE:TRAJECTORY`. |
207
155
 
208
- `/autopilot` takes this further: it pulls production signals (errors, CI failures, stale issues, analytics), creates issues from findings, and optionally runs `/work-on` on the top issues. Each cycle's fixes compound into the next.
156
+ 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.
209
157
 
210
158
  ---
211
159
 
212
160
  ## Commands
213
161
 
214
162
  | Command | What it does |
215
- | --- | --- |
216
- | **`/work-on`** | Full issue lifecycle: investigate → build → quality gate → review → merge |
217
- | `/issue` | Creates pipeline-ready GitHub issues |
218
- | `/orchestrate` | Parallel execution: decomposes milestones into waves, runs `/work-on` on each |
219
- | `/review-pr` | Context-aware PR review with 9 specialized agents |
163
+ |---|---|
164
+ | **`/work-on #N`** | Full issue lifecycle: investigate → build → review → merge |
165
+ | `/issue` | Create a pipeline-ready GitHub issue |
166
+ | `/orchestrate` | Parallel execution across a milestone's issues |
167
+ | `/review-pr` | PR review with 9 domain-specialist agents |
220
168
  | `/quality-gate` | Pre-commit checks across 14+ domains |
221
- | `/milestone` | Create, manage, and ship milestones |
169
+ | `/milestone` | Plan and ship milestones |
222
170
  | `/deploy-info` | Staging vs main diff with risk assessment |
223
- | `/review-pr-staging` | Comprehensive staging-to-main review gate |
171
+ | `/review-pr-staging` | Staging-to-main review gate |
224
172
  | `/rollback` | Automated revert PR for production incidents |
225
173
  | `/incident-response` | P0 coordination: hotfix, timeline, postmortem |
226
- | `/pipeline-health` | Self-analysis: measures performance, proposes improvements |
227
- | `/autopilot` | Autonomous improvement cycle: recon → triage → fix |
174
+ | `/autopilot` | Autonomous improvement: recon → triage → fix |
175
+ | `/pipeline-health` | Self-analysis and prompt tuning |
228
176
  | `/security-audit` | 4-phase security posture audit |
229
- | `/cleanup` | Sweeps stale issues, branches, worktrees |
230
- | `/analytics` | Pull metrics from GSC, Clarity, Umami, Stripe, and more |
231
177
  | `/qa-sweep` | Full platform QA via browser automation |
178
+ | `/analytics` | Pull metrics from GSC, Clarity, Umami, Stripe |
179
+ | `/cleanup` | Sweep stale issues, branches, worktrees |
232
180
 
233
181
  ---
234
182
 
235
- ## Vision
236
-
237
- ForgeDock today uses GitHub as its knowledge graph. It works — 20,000+ issues processed, real production codebases shipping autonomously. But GitHub wasn't designed for this. Issue comments are append-only text blobs. Labels are flat strings. Cross-references are implicit links, not queryable edges. Every annotation costs tokens to parse because it's wrapped in markdown meant for humans, not machines.
238
-
239
- The end state is a **purpose-built knowledge graph** — a structured, token-efficient store designed from the ground up for AI agents to read and write. Not a GitHub overlay. Not a vector database bolted on the side. A first-class system where:
240
-
241
- **In-house knowledge layer.** Replace GitHub comments with a native graph store where relationships are edges, not hyperlinks. An agent asking "what bugs has this module had in the last 30 days?" should be a graph query returning structured data — not parsing 50 issue comment bodies hoping to find `<!-- FORGE:INVESTIGATOR -->` tags. Annotations become nodes with typed relationships (caused-by, fixed-in, blocks, related-to) instead of flat text.
242
-
243
- **Token-efficient by design.** Today, an agent reads a 3,000-character investigation comment to extract 5 fields. A purpose-built store returns those 5 fields directly — 50 tokens instead of 800. At pipeline scale (investigation + context + architect + builder + review), this compresses the context budget dramatically. Agents get more lookback within the same window.
244
-
245
- **Self-improving feedback loops, closed tighter.** Right now, the improvement loop runs through `/pipeline-health` — a command a human invokes. In the end state, the pipeline continuously measures its own accuracy (false positive rates, investigation-to-build time, review-finding recurrence), identifies degrading patterns, and adjusts its own prompts, quality gate checks, and review focus areas without human intervention. Not "suggest improvements" — actually ship them, validate them, and roll back if metrics regress.
246
-
247
- **Fully autonomous development cycles.** Today, `/autopilot` runs recon and creates issues, but a human gates every fix. The vision is a pipeline that can run continuously — detecting production issues, creating issues, investigating, building, reviewing, deploying to staging, validating, and promoting to production — with human oversight moving from "approve every action" to "set policy and review outcomes." The human becomes the architect, not the operator.
248
-
249
- **Provider-agnostic agent runtime.** ForgeDock currently runs on Claude Code. The pipeline logic — the state machine, the annotation protocol, the review agent catalog — is model-agnostic. The goal is an agent runtime that can orchestrate any LLM (Claude, GPT, Gemini, open-source models) as specialized workers, choosing the right model for each task based on capability, cost, and latency.
250
-
251
- The path from here to there is incremental. Each piece — the knowledge store, the tighter feedback loop, the autonomous deploy gate — can ship independently and compound with the others.
252
-
253
- ---
254
-
255
- ## Install
256
-
257
- ### Option A: npx (recommended)
258
-
259
- **Step 1: Install commands**
260
-
261
- ```bash
262
- npx forgedock
263
- ```
264
-
265
- This symlinks all pipeline commands into your Claude Code environment (`~/.claude/commands/`).
266
-
267
- > **Note:** If you run `npx forgedock` from inside the ForgeDock repository, it uses the local working-tree binary rather than the published package. Run from your own project directory, or use `npx forgedock@latest` to pin to the published release.
268
-
269
- **Step 2: Generate config**
270
-
271
- ```bash
272
- npx forgedock init # Auto-detects your repo, owner, and branches
273
- ```
274
-
275
- Creates `forge.yaml` in your project root — the config file that makes ForgeDock work with your repo instead of a hardcoded one. It also injects a concise **ForgeDock usage block** into your project's `CLAUDE.md` so every Claude Code session in the repo automatically knows that ForgeDock drives development here and which commands to use.
276
-
277
- To regenerate the block later (e.g. after a ForgeDock update):
278
-
279
- ```bash
280
- npx forgedock integrate
281
- ```
282
-
283
- **Step 3: AI-powered setup (optional)**
284
-
285
- ```
286
- /forgedock-init # Inside Claude Code — guided full config walkthrough
287
- ```
288
-
289
- Requires [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [GitHub CLI](https://cli.github.com/).
290
-
291
- **Other commands:**
183
+ ## Uninstall
292
184
 
293
185
  ```bash
294
- npx forgedock update # Pull latest commands
295
- npx forgedock uninstall # Remove all commands
296
- npx forgedock help # Show all commands
186
+ npx forgedock uninstall
297
187
  ```
298
188
 
299
- ### Option B: Claude Code Plugin Marketplace
300
-
301
- If you're running Claude Code v2.1.143 or later, you can install ForgeDock directly through the plugin marketplace:
302
-
303
- ```
304
- /plugin marketplace add RapierCraftStudios/ForgeDock
305
- /plugin install forgedock@forgedock
306
- ```
307
-
308
- After install, commands are available as `/forgedock:work-on`, `/forgedock:review-pr`, etc. You still need to run `npx forgedock init` (or `/forgedock-init` inside Claude Code) to generate your `forge.yaml` config.
309
-
310
- ---
311
-
312
- ## Show Your Support
313
-
314
- If you're using ForgeDock to power your development pipeline, add a badge to your README to let the community know:
315
-
316
- ```markdown
317
- [![Built with ForgeDock](https://img.shields.io/badge/Built_with-ForgeDock-blue?logo=github)](https://github.com/RapierCraftStudios/ForgeDock)
318
- ```
319
-
320
- Rendered: [![Built with ForgeDock](https://img.shields.io/badge/Built_with-ForgeDock-blue?logo=github)](https://github.com/RapierCraftStudios/ForgeDock)
321
-
322
- This creates a discovery channel — each badge is a backlink and a signal to other developers that the project is AI-pipeline driven.
323
-
324
- ### Star History
325
-
326
- <a href="https://star-history.com/#RapierCraftStudios/ForgeDock&Date">
327
- <picture>
328
- <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=RapierCraftStudios/ForgeDock&type=Date&theme=dark" />
329
- <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=RapierCraftStudios/ForgeDock&type=Date" />
330
- <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=RapierCraftStudios/ForgeDock&type=Date" />
331
- </picture>
332
- </a>
189
+ Removes all ForgeDock command symlinks from `~/.claude/commands/`. Your `forge.yaml` config and any `FORGE:` annotations on GitHub issues/PRs are left untouched.
333
190
 
334
191
  ---
335
192
 
336
193
  ## Documentation
337
194
 
338
- - [Getting Started in 5 Minutes](docs/site/getting-started.md) — install, configure, run your first pipeline
339
- - [How ForgeDock's Knowledge Graph Works](docs/site/how-it-works.md) — FORGE annotations, the pipeline relay, compaction resilience
340
- - [ForgeDock vs. Manual Claude Code Workflows](docs/site/vs-manual-workflows.md) — why structured pipelines beat ad-hoc prompting
341
- - [The FORGE Annotation Protocol](docs/site/forge-annotation-protocol.md) — technical spec, open standard for AI context passing
342
- - [Complete Command Reference](docs/site/command-reference.md) — all 25+ commands with usage and examples
195
+ - [Getting Started in 5 Minutes](docs/site/getting-started.md) — install, configure, first pipeline run
196
+ - [How the Knowledge Graph Works](docs/site/how-it-works.md) — FORGE annotations, context relay, compaction resilience
197
+ - [ForgeDock vs. Manual Workflows](docs/site/vs-manual-workflows.md) — structured pipelines vs. ad-hoc prompting
198
+ - [FORGE Annotation Protocol](docs/site/forge-annotation-protocol.md) — open standard spec for AI context passing
199
+ - [Command Reference](docs/site/command-reference.md) — all 25+ commands with usage and examples
343
200
 
344
201
  ---
345
202
 
@@ -349,7 +206,7 @@ PRs welcome. Every change goes through a PR, tested against 3+ scenarios, using
349
206
 
350
207
  ## License
351
208
 
352
- [AGPL-3.0](LICENSE) — free to use, modify, and distribute. If you modify ForgeDock and offer it as a service (including over a network), you must open-source your modifications under the same license.
209
+ [AGPL-3.0](LICENSE) — free to use, modify, and distribute. If you modify ForgeDock and offer it as a service, you must open-source your modifications under the same license.
353
210
 
354
211
  ---
355
212
 
@@ -357,4 +214,6 @@ PRs welcome. Every change goes through a PR, tested against 3+ scenarios, using
357
214
 
358
215
  <p>Built by <a href="https://github.com/RapierCraftStudios">RapierCraft Studios</a></p>
359
216
 
217
+ <a href="https://github.com/sponsors/RapierCraftStudios"><img src="https://img.shields.io/badge/Sponsor-%E2%9D%A4-ea4aaa.svg?style=flat-square" alt="Sponsor" /></a>
218
+
360
219
  </div>
package/docs/demo.gif ADDED
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forgedock",
3
- "version": "1.0.14",
3
+ "version": "1.0.16",
4
4
  "description": "GitHub as a knowledge graph for AI agents. Autonomous dev pipeline for Claude Code.",
5
5
  "bin": {
6
6
  "forgedock": "bin/forgedock.mjs"
@@ -46,5 +46,13 @@
46
46
  },
47
47
  "engines": {
48
48
  "node": ">=18"
49
+ },
50
+ "peerDependencies": {
51
+ "@anthropic-ai/claude-code": ">=2.0.0"
52
+ },
53
+ "peerDependenciesMeta": {
54
+ "@anthropic-ai/claude-code": {
55
+ "optional": false
56
+ }
49
57
  }
50
58
  }