forge-cc 0.1.19 → 0.1.20
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.
- package/README.md +214 -434
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,408 +1,246 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
<img src="https://img.shields.io/badge/Claude_Code-ready-7c3aed?style=flat-square" alt="Claude Code ready" />
|
|
2
|
+
<picture>
|
|
3
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/forge--cc-Autonomous_Dev_Workflow-white?style=for-the-badge&labelColor=000000" />
|
|
4
|
+
<img src="https://img.shields.io/badge/forge--cc-Autonomous_Dev_Workflow-000000?style=for-the-badge&labelColor=white" alt="forge-cc" />
|
|
5
|
+
</picture>
|
|
7
6
|
</p>
|
|
8
7
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
forge-cc gives AI coding agents the same guardrails a senior engineering team enforces: type safety, linting, test coverage, visual regression, PRD compliance, and code review -- all verified automatically before code ever hits a PR. Combined with workflow skills that manage the entire lifecycle from idea to merged code, forge-cc turns Claude Code into a self-verifying, project-aware development partner.
|
|
14
|
-
|
|
15
|
-
---
|
|
16
|
-
|
|
17
|
-
## Why forge-cc?
|
|
18
|
-
|
|
19
|
-
AI coding agents write code fast, but speed without quality gates means you spend more time reviewing than you save. forge-cc solves this by:
|
|
20
|
-
|
|
21
|
-
- **Catching errors before commit** -- TypeScript, linting, tests, visual regressions, and PRD compliance checks run automatically, so agents self-correct before you see the code.
|
|
22
|
-
- **Enforcing standards mechanically** -- Pre-commit hooks and Claude Code hooks block unverified commits. No discipline required; the machine enforces it.
|
|
23
|
-
- **Managing the full lifecycle** -- From triaging ideas into Linear to generating PRDs to executing milestones with parallel agent teams, forge-cc handles the project management plumbing so you focus on decisions.
|
|
24
|
-
- **Isolating concurrent work** -- Multiple agents can work on different milestones simultaneously using git worktrees with automatic state merging.
|
|
25
|
-
|
|
26
|
-
---
|
|
27
|
-
|
|
28
|
-
## Prerequisites
|
|
29
|
-
|
|
30
|
-
| Dependency | Required? | Purpose |
|
|
31
|
-
|------------|-----------|---------|
|
|
32
|
-
| **Node.js 18+** | Required | Runtime for forge-cc and all gates |
|
|
33
|
-
| **git** | Required | Version control, worktree isolation |
|
|
34
|
-
| **GitHub CLI (`gh`)** | Recommended | PR creation, Linear integration, codex review gate |
|
|
35
|
-
| **Playwright + Chromium** | Optional | `visual` and `runtime` gates (screenshot comparison, endpoint validation) |
|
|
8
|
+
<p align="center">
|
|
9
|
+
<strong>Idea to merged PR. Autonomous agent teams. Zero manual git.</strong>
|
|
10
|
+
</p>
|
|
36
11
|
|
|
37
|
-
|
|
12
|
+
<p align="center">
|
|
13
|
+
<a href="https://www.npmjs.com/package/forge-cc"><img src="https://img.shields.io/npm/v/forge-cc?style=flat-square&color=0969da" alt="npm" /></a>
|
|
14
|
+
<img src="https://img.shields.io/badge/Claude_Code-plugin-7c3aed?style=flat-square&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNMTIgMkw0IDdWMTdMMTIgMjJMMjAgMTdWN0wxMiAyWiIgZmlsbD0id2hpdGUiLz48L3N2Zz4=&logoColor=white" alt="Claude Code" />
|
|
15
|
+
<img src="https://img.shields.io/badge/node-%3E%3D18-339933?style=flat-square&logo=node.js&logoColor=white" alt="node" />
|
|
16
|
+
<img src="https://img.shields.io/npm/l/forge-cc?style=flat-square&color=22863a" alt="MIT" />
|
|
17
|
+
</p>
|
|
38
18
|
|
|
39
19
|
---
|
|
40
20
|
|
|
41
|
-
##
|
|
42
|
-
|
|
43
|
-
```bash
|
|
44
|
-
# Install globally
|
|
45
|
-
npm install -g forge-cc
|
|
46
|
-
```
|
|
21
|
+
## What is forge-cc?
|
|
47
22
|
|
|
48
|
-
|
|
23
|
+
forge-cc is a Claude Code plugin that turns your AI coding agent into an autonomous development team. You describe what you want to build. Forge breaks it into milestones, spins up parallel agent teams, verifies every line of code, creates the PR, gets it reviewed, and merges it -- all without you touching git.
|
|
49
24
|
|
|
50
25
|
```
|
|
51
|
-
|
|
52
|
-
✓ Skills synced to ~/.claude/commands/forge/
|
|
53
|
-
✗ Playwright (visual + runtime gates): not installed
|
|
54
|
-
→ Run: npm install -g playwright && npx playwright install chromium
|
|
55
|
-
|
|
56
|
-
Get started: forge setup
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
```bash
|
|
60
|
-
# Initialize your project
|
|
61
|
-
npx forge setup
|
|
62
|
-
|
|
63
|
-
# Check your environment
|
|
64
|
-
npx forge doctor
|
|
65
|
-
|
|
66
|
-
# Run verification
|
|
67
|
-
npx forge verify
|
|
68
|
-
|
|
69
|
-
# Check status
|
|
70
|
-
npx forge status
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
Or install as a dev dependency:
|
|
74
|
-
|
|
75
|
-
```bash
|
|
76
|
-
npm install --save-dev forge-cc
|
|
26
|
+
npm install -g forge-cc
|
|
77
27
|
```
|
|
78
28
|
|
|
79
|
-
On first run with no `.forge.json`, forge auto-detects gates from your `package.json`:
|
|
80
|
-
|
|
81
|
-
| Detected | Gate Enabled |
|
|
82
|
-
|----------|-------------|
|
|
83
|
-
| `typescript` in dependencies | **types** -- `tsc --noEmit` |
|
|
84
|
-
| `@biomejs/biome` in dependencies | **lint** -- `biome check` |
|
|
85
|
-
| `test` script in package.json | **tests** -- `npm test` |
|
|
86
|
-
|
|
87
29
|
---
|
|
88
30
|
|
|
89
|
-
## Workflow
|
|
31
|
+
## The Workflow
|
|
90
32
|
|
|
91
|
-
|
|
33
|
+
Four commands take you from raw idea to production-ready, merged code.
|
|
92
34
|
|
|
93
35
|
```
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
36
|
+
┌──────────────────────────────────────────────────────────────────────────────────┐
|
|
37
|
+
│ │
|
|
38
|
+
│ YOU HAVE AN IDEA FORGE DOES THE REST │
|
|
39
|
+
│ │
|
|
40
|
+
│ "We need auth, ┌────────────┐ ┌────────────┐ ┌────────────┐ │
|
|
41
|
+
│ a dashboard, │ │ │ │ │ │ │
|
|
42
|
+
│ and email │ TRIAGE ├──► SPEC ├──► GO │ │
|
|
43
|
+
│ notifications" │ │ │ │ │ │ │
|
|
44
|
+
│ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ │
|
|
45
|
+
│ │ │ │ │
|
|
46
|
+
│ Creates Linear Scans codebase Agent teams │
|
|
47
|
+
│ projects from + interviews build each │
|
|
48
|
+
│ brain dump you + generates milestone │
|
|
49
|
+
│ PRD + milestones in parallel │
|
|
50
|
+
│ │ │
|
|
51
|
+
│ ▼ │
|
|
52
|
+
│ ┌────────────────┐ │
|
|
53
|
+
│ │ VERIFY + PR │ │
|
|
54
|
+
│ │ + CODE REVIEW │ │
|
|
55
|
+
│ │ + AUTO-MERGE │ │
|
|
56
|
+
│ └────────────────┘ │
|
|
57
|
+
│ │
|
|
58
|
+
└──────────────────────────────────────────────────────────────────────────────────┘
|
|
105
59
|
```
|
|
106
60
|
|
|
107
|
-
###
|
|
61
|
+
### `/forge:triage` -- Brain Dump to Backlog
|
|
108
62
|
|
|
109
|
-
Paste
|
|
63
|
+
Paste sticky notes, Slack messages, or stream-of-consciousness feature ideas. Forge extracts distinct projects, deduplicates against your existing Linear backlog, and creates them after your confirmation.
|
|
110
64
|
|
|
111
|
-
|
|
112
|
-
You: /forge:triage
|
|
113
|
-
"We need auth, a dashboard with charts, and email notifications.
|
|
114
|
-
Also the onboarding flow is broken on mobile."
|
|
115
|
-
|
|
116
|
-
Forge: Extracted 4 projects:
|
|
117
|
-
1. User Authentication System
|
|
118
|
-
2. Analytics Dashboard
|
|
119
|
-
3. Email Notification Service
|
|
120
|
-
4. Mobile Onboarding Fix
|
|
121
|
-
Creating in Linear...
|
|
122
|
-
```
|
|
65
|
+
### `/forge:spec` -- Project to PRD
|
|
123
66
|
|
|
124
|
-
|
|
67
|
+
Pick a project from Linear. Forge scans your codebase in parallel (structure, routes, dependencies, patterns), then conducts an adaptive interview -- leading with recommendations based on what it found, not blank-slate questions. The output is a full PRD with milestones sized to fit agent context windows, synced back to Linear with issues and status tracking.
|
|
125
68
|
|
|
126
|
-
|
|
69
|
+
### `/forge:go` -- Milestones to Merged Code
|
|
127
70
|
|
|
128
|
-
|
|
129
|
-
You: /forge:spec
|
|
130
|
-
|
|
131
|
-
Forge: Scanning codebase... found Next.js + Prisma + tRPC
|
|
132
|
-
Based on your stack, I recommend:
|
|
133
|
-
- Milestone 1: Database schema + auth provider
|
|
134
|
-
- Milestone 2: Login/signup UI components
|
|
135
|
-
- Milestone 3: Session management + middleware
|
|
136
|
-
[Interview continues with focused questions...]
|
|
137
|
-
PRD generated -> Milestones created in Linear
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
### Step 3: Execute (`/forge:go`)
|
|
141
|
-
|
|
142
|
-
Executes milestones using a 3-tier agent team architecture:
|
|
71
|
+
This is the engine. Each milestone is executed by an autonomous agent team:
|
|
143
72
|
|
|
144
73
|
```
|
|
145
|
-
|
|
146
|
-
│
|
|
147
|
-
│ Plans waves, assigns
|
|
148
|
-
|
|
149
|
-
│
|
|
150
|
-
│ Reviews diff after each wave
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
│
|
|
154
|
-
│
|
|
155
|
-
|
|
74
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
75
|
+
│ EXECUTIVE (orchestrator) │
|
|
76
|
+
│ Plans waves, assigns tasks, resolves escalations │
|
|
77
|
+
├─────────────────────────────────────────────────────────────────────┤
|
|
78
|
+
│ REVIEWER (persistent across all waves) │
|
|
79
|
+
│ Reviews diff against PRD after each wave │
|
|
80
|
+
│ Findings go through consensus protocol with builders │
|
|
81
|
+
├────────────────────┬────────────────────┬───────────────────────────┤
|
|
82
|
+
│ BUILDER 1 │ BUILDER 2 │ BUILDER N ... │
|
|
83
|
+
│ Parallel agents │ Parallel agents │ Each gets a task, │
|
|
84
|
+
│ within each wave │ within each wave │ writes + tests code │
|
|
85
|
+
└────────────────────┴────────────────────┴───────────────────────────┘
|
|
156
86
|
```
|
|
157
87
|
|
|
158
|
-
|
|
88
|
+
**What happens during execution:**
|
|
159
89
|
|
|
160
90
|
```
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
Wave 2: [seed-agent] [test-agent] -- parallel
|
|
168
|
-
Verify: types PASS | lint PASS | tests PASS
|
|
169
|
-
Milestone 1 complete. Creating PR...
|
|
170
|
-
```
|
|
171
|
-
|
|
172
|
-
### Step 4: Auto-Chain (Optional)
|
|
173
|
-
|
|
174
|
-
Run all remaining milestones autonomously:
|
|
175
|
-
|
|
176
|
-
```bash
|
|
177
|
-
npx forge run
|
|
91
|
+
Wave 1 ─► Verify ─► Review ─► Fix ─► Wave 2 ─► ... ─► PR ─► Merge
|
|
92
|
+
│ │ │ │
|
|
93
|
+
│ │ │ └─ Fix agents spawn for accepted findings
|
|
94
|
+
│ │ └─ Reviewer + builders reach consensus on issues
|
|
95
|
+
│ └─ Types + lint + tests run automatically (self-healing loop)
|
|
96
|
+
└─ Parallel builder agents execute independent tasks
|
|
178
97
|
```
|
|
179
98
|
|
|
180
|
-
|
|
99
|
+
After the final wave passes all gates + review, forge creates the PR, waits for Codex review comments, spawns fix agents for any findings, and auto-merges when clean.
|
|
181
100
|
|
|
182
|
-
###
|
|
101
|
+
### `npx forge run` -- Auto-Chain Everything
|
|
183
102
|
|
|
184
|
-
|
|
185
|
-
|-------|---------|
|
|
186
|
-
| `/forge:setup` | Initialize or refresh project scaffolding, hooks, and config |
|
|
187
|
-
| `/forge:update` | Check for and install the latest forge-cc version |
|
|
103
|
+
Run all remaining milestones autonomously. Each gets a fresh Claude session (no context rot), with stall detection that stops on failure. Independent milestones run in parallel.
|
|
188
104
|
|
|
189
105
|
---
|
|
190
106
|
|
|
191
107
|
## Verification Gates
|
|
192
108
|
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
| Gate | What It Checks | Requires |
|
|
196
|
-
|------|---------------|----------|
|
|
197
|
-
| `types` | TypeScript compilation (`tsc --noEmit`) | `typescript` in dependencies |
|
|
198
|
-
| `lint` | Biome linting (`biome check`) | `@biomejs/biome` in dependencies |
|
|
199
|
-
| `tests` | Test suite (`npm test`) | A `test` script in package.json |
|
|
200
|
-
| `visual` | Multi-viewport screenshots (desktop, tablet, mobile) + DOM extraction + before/after comparison + console error detection | Dev server config, `playwright` |
|
|
201
|
-
| `runtime` | HTTP endpoint validation (status codes, response shape) | Dev server config, endpoint list |
|
|
202
|
-
| `prd` | Diff against PRD acceptance criteria | PRD file path, git history |
|
|
203
|
-
| `review` | Code review against PRD criteria and CLAUDE.md rules | Git history |
|
|
204
|
-
| `codex` | Post-PR review comment polling -- waits for Codex review comments on the PR and surfaces unresolved findings | `gh` CLI, open PR |
|
|
205
|
-
|
|
206
|
-
### Gate Remediation
|
|
207
|
-
|
|
208
|
-
When gates fail, forge-cc doesn't just report errors -- it generates structured remediation templates that give fix agents actionable instructions. Each error includes the file, line, message, and a specific remediation step.
|
|
109
|
+
Not just "run tests." Forge runs **8 verification gates** that catch what tests alone can't:
|
|
209
110
|
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
"maxIterations": 5,
|
|
224
|
-
"verifyFreshness": 600000,
|
|
225
|
-
"devServer": {
|
|
226
|
-
"command": "npm run dev",
|
|
227
|
-
"port": 3000,
|
|
228
|
-
"readyPattern": "ready on"
|
|
229
|
-
},
|
|
230
|
-
"prdPath": ".planning/prds/active.md",
|
|
231
|
-
"linearProject": "My Project",
|
|
232
|
-
"review": {
|
|
233
|
-
"blocking": false
|
|
234
|
-
}
|
|
235
|
-
}
|
|
111
|
+
```
|
|
112
|
+
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
|
|
113
|
+
│ TYPES │ │ LINT │ │ TESTS │ │ VISUAL │
|
|
114
|
+
│ tsc │ │ biome │ │ vitest/ │ │ 3-viewport│
|
|
115
|
+
│ --noEmit │ │ check │ │ jest │ │ screenshots│
|
|
116
|
+
└────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘
|
|
117
|
+
│ │ │ │
|
|
118
|
+
▼ ▼ ▼ ▼
|
|
119
|
+
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
|
|
120
|
+
│ RUNTIME │ │ PRD │ │ REVIEW │ │ CODEX │
|
|
121
|
+
│ endpoint │ │ acceptance│ │ AI code │ │ post-PR │
|
|
122
|
+
│ checks │ │ criteria │ │ review │ │ review │
|
|
123
|
+
└──────────┘ └──────────┘ └──────────┘ └──────────┘
|
|
236
124
|
```
|
|
237
125
|
|
|
238
|
-
|
|
|
239
|
-
|
|
240
|
-
|
|
|
241
|
-
|
|
|
242
|
-
|
|
|
243
|
-
|
|
|
244
|
-
|
|
|
245
|
-
|
|
|
246
|
-
|
|
|
247
|
-
|
|
|
248
|
-
| `review.blocking` | `boolean` | `false` | When `true`, review findings fail the gate |
|
|
249
|
-
|
|
250
|
-
### Environment Variables
|
|
251
|
-
|
|
252
|
-
| Variable | Purpose |
|
|
253
|
-
|----------|---------|
|
|
254
|
-
| `FORGE_LINEAR_API_KEY` | API key for Linear integration (preferred) |
|
|
255
|
-
| `LINEAR_API_KEY` | Alternative name for the Linear API key |
|
|
126
|
+
| Gate | What it catches |
|
|
127
|
+
|------|----------------|
|
|
128
|
+
| **types** | Compilation errors, type mismatches |
|
|
129
|
+
| **lint** | Style violations, dead imports, code smells |
|
|
130
|
+
| **tests** | Broken behavior, regressions |
|
|
131
|
+
| **visual** | UI regressions across desktop, tablet, and mobile viewports |
|
|
132
|
+
| **runtime** | Crashed endpoints, wrong status codes, malformed responses |
|
|
133
|
+
| **prd** | Missing features, acceptance criteria drift |
|
|
134
|
+
| **review** | Logic errors, missing edge cases, architectural issues |
|
|
135
|
+
| **codex** | Post-PR findings from GitHub's Codex reviewer |
|
|
256
136
|
|
|
257
|
-
|
|
137
|
+
**Self-healing:** When a gate fails, forge parses the errors into structured remediation (file, line, message, fix hint) and spawns a fix agent. This loops up to 5 times before stopping -- most failures resolve automatically.
|
|
258
138
|
|
|
259
139
|
---
|
|
260
140
|
|
|
261
|
-
##
|
|
262
|
-
|
|
263
|
-
### `forge verify`
|
|
141
|
+
## Linear Integration
|
|
264
142
|
|
|
265
|
-
|
|
143
|
+
Forge manages your Linear project lifecycle end-to-end. Every state transition happens automatically as work progresses:
|
|
266
144
|
|
|
267
|
-
```bash
|
|
268
|
-
npx forge verify # Run all configured gates
|
|
269
|
-
npx forge verify --gate types,lint # Run specific gates
|
|
270
|
-
npx forge verify --json # Output structured JSON
|
|
271
|
-
npx forge verify --prd .planning/prds/active.md # Include PRD check
|
|
272
145
|
```
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
### `forge status`
|
|
279
|
-
|
|
280
|
-
Print current project state: branch, last verification result, config source, and active sessions.
|
|
281
|
-
|
|
282
|
-
```bash
|
|
283
|
-
npx forge status
|
|
146
|
+
Linear State: Backlog ──► Planned ──► In Progress ──► In Review ──► Done
|
|
147
|
+
│ │ │ │ │
|
|
148
|
+
Forge Action: triage /forge:spec /forge:go PR created PR merged
|
|
149
|
+
creates generates PRD, executes after final auto-merge
|
|
150
|
+
projects syncs milestones milestone verification completes
|
|
284
151
|
```
|
|
285
152
|
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
Initialize a new project with forge-cc scaffolding or reinstall skills.
|
|
289
|
-
|
|
290
|
-
```bash
|
|
291
|
-
npx forge setup # Full project initialization
|
|
292
|
-
npx forge setup --skills-only # Only install skills to ~/.claude/commands/forge/
|
|
293
|
-
npx forge setup --with-visual # Auto-install Playwright without prompting
|
|
294
|
-
npx forge setup --skip-deps # Skip optional dependency checks
|
|
295
|
-
```
|
|
153
|
+
Set `FORGE_LINEAR_API_KEY` in your environment to enable. Forge creates projects, milestones, and issues during spec, transitions them through states during execution, and marks them done when the PR merges.
|
|
296
154
|
|
|
297
|
-
|
|
155
|
+
---
|
|
298
156
|
|
|
299
|
-
|
|
157
|
+
## Branch & Worktree Management
|
|
300
158
|
|
|
301
|
-
|
|
302
|
-
npx forge doctor
|
|
303
|
-
```
|
|
304
|
-
|
|
305
|
-
Example output:
|
|
159
|
+
You never touch git. Forge handles the entire branch lifecycle:
|
|
306
160
|
|
|
307
161
|
```
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
✓ gh CLI 2.67.0 (authenticated)
|
|
314
|
-
✗ Playwright — not installed
|
|
315
|
-
→ npm install -g playwright && npx playwright install chromium
|
|
316
|
-
✗ Chromium browser — not installed
|
|
317
|
-
→ npx playwright install chromium
|
|
318
|
-
|
|
319
|
-
2 issues found. Run the commands above to fix.
|
|
162
|
+
main ─────────────────────────────────────────────────────► main (updated)
|
|
163
|
+
│ ▲
|
|
164
|
+
└──► feat/auth ──► worktree 1 ──► wave 1..N ──► PR ──► merge + cleanup
|
|
165
|
+
│ │
|
|
166
|
+
└──► feat/dashboard ──► worktree 2 ──► (parallel) ┘
|
|
320
167
|
```
|
|
321
168
|
|
|
322
|
-
|
|
169
|
+
**Session isolation** -- Each milestone runs in its own git worktree (`../.forge-wt/<repo>/<session>/`). Parallel agents can't corrupt each other's git index. Multiple milestones can execute simultaneously on the same repo.
|
|
323
170
|
|
|
324
|
-
|
|
171
|
+
**Automatic cleanup** -- When a milestone finishes, its worktree and branch are deleted. When a PR merges, `npx forge cleanup` prunes the local branch. Crashed sessions are detected by PID and cleaned up. Protected branches (`main`, `master`) are never touched.
|
|
325
172
|
|
|
326
|
-
|
|
327
|
-
npx forge cleanup
|
|
328
|
-
```
|
|
173
|
+
**Cross-platform** -- Windows path limits handled with 8-char hex session IDs. Atomic file writes use retry-on-rename for Windows file locking.
|
|
329
174
|
|
|
330
|
-
|
|
175
|
+
---
|
|
331
176
|
|
|
332
|
-
|
|
177
|
+
## Quick Start
|
|
333
178
|
|
|
334
179
|
```bash
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
npx forge run --prd <slug> # Run milestones for a specific PRD
|
|
338
|
-
npx forge run --all # Run all PRDs with pending milestones
|
|
339
|
-
```
|
|
340
|
-
|
|
341
|
-
---
|
|
180
|
+
# 1. Install
|
|
181
|
+
npm install -g forge-cc
|
|
342
182
|
|
|
343
|
-
|
|
183
|
+
# 2. Set up your project
|
|
184
|
+
npx forge setup
|
|
344
185
|
|
|
345
|
-
|
|
186
|
+
# 3. Start building
|
|
187
|
+
# /forge:triage → /forge:spec → /forge:go
|
|
188
|
+
```
|
|
346
189
|
|
|
347
|
-
|
|
190
|
+
`forge setup` auto-detects your stack (TypeScript, Biome, test runner), creates `.forge.json`, installs enforcement hooks, and scaffolds planning directories. Run `npx forge doctor` anytime to check your environment.
|
|
348
191
|
|
|
349
|
-
|
|
192
|
+
### Configuration
|
|
350
193
|
|
|
351
|
-
|
|
194
|
+
`.forge.json` in your project root:
|
|
352
195
|
|
|
353
196
|
```json
|
|
354
197
|
{
|
|
355
|
-
"
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
"matcher": "Bash",
|
|
359
|
-
"hooks": [
|
|
360
|
-
{
|
|
361
|
-
"type": "command",
|
|
362
|
-
"command": "node node_modules/forge-cc/hooks/pre-commit-verify.js"
|
|
363
|
-
}
|
|
364
|
-
]
|
|
365
|
-
}
|
|
366
|
-
]
|
|
367
|
-
}
|
|
198
|
+
"gates": ["types", "lint", "tests"],
|
|
199
|
+
"maxIterations": 5,
|
|
200
|
+
"linearProject": "My Project"
|
|
368
201
|
}
|
|
369
202
|
```
|
|
370
203
|
|
|
371
|
-
|
|
204
|
+
<details>
|
|
205
|
+
<summary><b>Full configuration options</b></summary>
|
|
372
206
|
|
|
373
|
-
|
|
207
|
+
| Option | Default | Description |
|
|
208
|
+
|--------|---------|-------------|
|
|
209
|
+
| `gates` | `["types","lint","tests"]` | Which verification gates to run |
|
|
210
|
+
| `maxIterations` | `5` | Max self-healing retry loops |
|
|
211
|
+
| `verifyFreshness` | `600000` | Cache validity (ms, default 10min) |
|
|
212
|
+
| `devServer.command` | -- | Start command for visual/runtime gates |
|
|
213
|
+
| `devServer.port` | -- | Dev server port |
|
|
214
|
+
| `devServer.readyPattern` | -- | Stdout pattern for server ready |
|
|
215
|
+
| `prdPath` | -- | PRD path for acceptance criteria gate |
|
|
216
|
+
| `linearProject` | -- | Linear project name for lifecycle sync |
|
|
217
|
+
| `review.blocking` | `false` | Whether review findings block the pipeline |
|
|
374
218
|
|
|
375
|
-
|
|
219
|
+
**Environment:** Set `FORGE_LINEAR_API_KEY` to enable Linear integration.
|
|
376
220
|
|
|
377
|
-
|
|
221
|
+
</details>
|
|
378
222
|
|
|
379
|
-
|
|
223
|
+
### CLI
|
|
380
224
|
|
|
381
|
-
```
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
{
|
|
389
|
-
"type": "command",
|
|
390
|
-
"command": "node node_modules/forge-cc/hooks/version-check.js"
|
|
391
|
-
}
|
|
392
|
-
]
|
|
393
|
-
}
|
|
394
|
-
]
|
|
395
|
-
}
|
|
396
|
-
}
|
|
225
|
+
```bash
|
|
226
|
+
npx forge verify # Run all gates
|
|
227
|
+
npx forge verify --gate types # Run specific gates
|
|
228
|
+
npx forge status # Branch, config, last verification
|
|
229
|
+
npx forge doctor # Environment health check
|
|
230
|
+
npx forge cleanup # Prune stale worktrees + branches
|
|
231
|
+
npx forge run # Auto-chain all milestones
|
|
397
232
|
```
|
|
398
233
|
|
|
399
|
-
|
|
234
|
+
### Enforcement Hooks
|
|
235
|
+
|
|
236
|
+
Forge installs two Claude Code hooks automatically during setup:
|
|
400
237
|
|
|
401
|
-
|
|
238
|
+
- **Pre-commit hook** -- Blocks commits that haven't passed verification. Checks branch protection, cache freshness, and gate results.
|
|
239
|
+
- **Version check hook** -- Non-blocking notice when a newer forge-cc version is available.
|
|
402
240
|
|
|
403
|
-
|
|
241
|
+
### MCP Server
|
|
404
242
|
|
|
405
|
-
|
|
243
|
+
Expose gates as MCP tools for programmatic access:
|
|
406
244
|
|
|
407
245
|
```json
|
|
408
246
|
{
|
|
@@ -415,145 +253,87 @@ Add to `.mcp.json`:
|
|
|
415
253
|
}
|
|
416
254
|
```
|
|
417
255
|
|
|
418
|
-
**Available tools:**
|
|
419
|
-
|
|
420
|
-
| Tool | Description |
|
|
421
|
-
|------|-------------|
|
|
422
|
-
| `forge_verify_types` | Run TypeScript type checking |
|
|
423
|
-
| `forge_verify_lint` | Run Biome linting |
|
|
424
|
-
| `forge_verify_tests` | Run project test suite |
|
|
425
|
-
| `forge_verify_visual` | Multi-viewport screenshots + DOM comparison |
|
|
426
|
-
| `forge_verify_runtime` | Validate API endpoints |
|
|
427
|
-
| `forge_verify_prd` | Check changes against PRD criteria |
|
|
428
|
-
| `forge_run_pipeline` | Run full verification pipeline |
|
|
429
|
-
|
|
430
|
-
All tools accept `projectDir` (absolute path) and return structured JSON results.
|
|
431
|
-
|
|
432
256
|
---
|
|
433
257
|
|
|
434
|
-
##
|
|
435
|
-
|
|
436
|
-
forge-cc manages the full Linear project lifecycle automatically:
|
|
437
|
-
|
|
438
|
-
```
|
|
439
|
-
Backlog ──> Planned ──> In Progress ──> In Review ──> Done
|
|
440
|
-
| | | | |
|
|
441
|
-
triage spec/PRD go/execute PR created PR merged
|
|
442
|
-
```
|
|
443
|
-
|
|
444
|
-
Set `FORGE_LINEAR_API_KEY` (or `LINEAR_API_KEY`) in your environment and `linearProject` in `.forge.json` to enable.
|
|
445
|
-
|
|
446
|
-
---
|
|
447
|
-
|
|
448
|
-
## Concurrency & Session Isolation
|
|
449
|
-
|
|
450
|
-
forge-cc supports multiple simultaneous sessions on the same repository using git worktrees.
|
|
451
|
-
|
|
452
|
-
**How it works:**
|
|
258
|
+
## How It's Different
|
|
453
259
|
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
**Platform notes:**
|
|
463
|
-
- **Windows:** 8-char hex session IDs avoid the 260-character path limit. Atomic writes use retry-on-rename for Windows file locking.
|
|
464
|
-
- **Git:** Requires git 2.5+ for worktree support.
|
|
465
|
-
|
|
466
|
-
### Branch & Worktree Cleanup
|
|
467
|
-
|
|
468
|
-
Forge creates branches and worktrees automatically during `/forge:go`. You never need to create or delete them yourself -- forge handles the full lifecycle:
|
|
469
|
-
|
|
470
|
-
1. **When a milestone finishes**, forge deletes the worktree and its branch automatically.
|
|
471
|
-
2. **When a PR is merged**, GitHub deletes the remote branch. Running `forge cleanup` then deletes the matching local branch.
|
|
472
|
-
3. **When a session crashes**, `forge cleanup` removes the stale worktree and its branch.
|
|
473
|
-
|
|
474
|
-
To clean everything up at once:
|
|
475
|
-
|
|
476
|
-
```bash
|
|
477
|
-
npx forge cleanup
|
|
478
|
-
```
|
|
479
|
-
|
|
480
|
-
This does three things:
|
|
481
|
-
- Removes worktrees from crashed/stale sessions
|
|
482
|
-
- Deregisters dead sessions from the registry
|
|
483
|
-
- Deletes local branches whose remote branch is gone (i.e., the PR was merged)
|
|
484
|
-
|
|
485
|
-
**Protected branches** (`main`, `master`) are never deleted. The currently checked-out branch is also never deleted.
|
|
486
|
-
|
|
487
|
-
**TL;DR:** Just run `npx forge cleanup` periodically and branches take care of themselves. You should never need to manually delete a forge branch.
|
|
260
|
+
| Without forge | With forge |
|
|
261
|
+
|--------------|-----------|
|
|
262
|
+
| Agent writes code, you review everything | Agent teams build, verify, review, and fix their own code |
|
|
263
|
+
| Manual git branching, PRs, merges | Automatic branches, worktrees, PRs, and auto-merge |
|
|
264
|
+
| "Tests pass" = done | 8 gates including visual regression, PRD compliance, and AI code review |
|
|
265
|
+
| One agent, one task, serial | Parallel agent teams with wave-based execution |
|
|
266
|
+
| Context rot across long sessions | Fresh session per milestone, no degradation |
|
|
267
|
+
| Linear updated manually | Bidirectional sync -- forge moves issues through your pipeline |
|
|
488
268
|
|
|
489
269
|
---
|
|
490
270
|
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
Joining a project that uses forge-cc:
|
|
494
|
-
|
|
495
|
-
```bash
|
|
496
|
-
# 1. Clone and install
|
|
497
|
-
git clone <repo-url> && cd <repo>
|
|
498
|
-
npm install
|
|
499
|
-
|
|
500
|
-
# 2. Initialize forge (installs skills, hooks, scaffolding)
|
|
501
|
-
npx forge setup
|
|
502
|
-
# Add --with-visual if the project uses visual or runtime gates
|
|
503
|
-
|
|
504
|
-
# 3. Check your environment
|
|
505
|
-
npx forge doctor
|
|
506
|
-
|
|
507
|
-
# 4. Verify your environment works
|
|
508
|
-
npx forge verify
|
|
271
|
+
<details>
|
|
272
|
+
<summary><h2>Agent & Contributor Reference</h2></summary>
|
|
509
273
|
|
|
510
|
-
|
|
511
|
-
# Use /forge:go to execute milestones, or just code normally --
|
|
512
|
-
# the pre-commit hook ensures verification passes before any commit.
|
|
513
|
-
```
|
|
514
|
-
|
|
515
|
-
The gates run the same checks as CI, so if `npx forge verify` passes locally, CI will pass too.
|
|
516
|
-
|
|
517
|
-
---
|
|
518
|
-
|
|
519
|
-
## Project Structure
|
|
274
|
+
### Project Structure
|
|
520
275
|
|
|
521
276
|
```
|
|
522
277
|
forge-cc/
|
|
523
278
|
src/
|
|
524
|
-
cli.ts # CLI entry
|
|
279
|
+
cli.ts # CLI entry (npx forge)
|
|
525
280
|
server.ts # MCP server (stdio transport)
|
|
526
|
-
types.ts # Core
|
|
527
|
-
gates/ # Verification gates + remediation
|
|
281
|
+
types.ts # Core types
|
|
282
|
+
gates/ # Verification gates + remediation
|
|
528
283
|
config/ # .forge.json schema + auto-detection
|
|
529
|
-
linear/ # Linear API client + lifecycle
|
|
530
|
-
hooks/ # Pre-commit
|
|
531
|
-
reporter/ # Human
|
|
284
|
+
linear/ # Linear API client + lifecycle
|
|
285
|
+
hooks/ # Pre-commit enforcement
|
|
286
|
+
reporter/ # Human + JSON output formatting
|
|
532
287
|
state/ # Session state reader/writer
|
|
533
|
-
spec/ # Spec
|
|
534
|
-
go/ # Execution engine
|
|
288
|
+
spec/ # Spec engine (scanner, interview, generator)
|
|
289
|
+
go/ # Execution engine (verify loop, auto-chain, finalize)
|
|
535
290
|
setup/ # Project scaffolding templates
|
|
536
|
-
worktree/ #
|
|
537
|
-
utils/ # Platform utilities (atomic writes,
|
|
291
|
+
worktree/ # Worktree manager, session registry, state merge
|
|
292
|
+
utils/ # Platform utilities (atomic writes, paths)
|
|
538
293
|
skills/ # Claude Code skill definitions
|
|
539
294
|
hooks/ # Installable hook files
|
|
540
|
-
tests/ # Test suite (
|
|
295
|
+
tests/ # Test suite (vitest)
|
|
541
296
|
```
|
|
542
297
|
|
|
543
|
-
|
|
298
|
+
### Development
|
|
544
299
|
|
|
545
300
|
```bash
|
|
546
|
-
npm install #
|
|
301
|
+
npm install # Dependencies
|
|
547
302
|
npm run build # Build
|
|
548
|
-
npm test #
|
|
303
|
+
npm test # Tests
|
|
549
304
|
npm run dev # Watch mode
|
|
550
|
-
npx forge verify #
|
|
305
|
+
npx forge verify # Self-verify
|
|
551
306
|
```
|
|
552
307
|
|
|
553
|
-
**
|
|
308
|
+
**Stack:** TypeScript (ES2022 strict), Node.js 18+, MCP SDK, Commander, Playwright, Zod, Vitest
|
|
554
309
|
|
|
555
|
-
|
|
310
|
+
### Agent Team Architecture
|
|
311
|
+
|
|
312
|
+
During `/forge:go`, forge creates a 3-tier agent team:
|
|
313
|
+
|
|
314
|
+
- **Executive** -- The orchestrator. Plans waves, assigns tasks, manages state, resolves deadlocks.
|
|
315
|
+
- **Reviewer** -- Persistent Opus agent. Examines diff after each wave against PRD acceptance criteria. Sends structured findings (file/line/message/remediation). Participates in consensus protocol with builders.
|
|
316
|
+
- **Builders** -- Parallel Opus agents, one per task. Full-capability (file editing, git, shell). Can spawn subagents for research. Stage only their files.
|
|
317
|
+
- **Notetaker** -- Optional, spawned for 3+ waves or 4+ agents per wave. Tracks decisions, file ownership, cross-agent dependencies.
|
|
318
|
+
|
|
319
|
+
**Consensus protocol:** Reviewer sends findings to builders. Builders respond agree/disagree/propose alternative. Up to 2 rounds of back-and-forth. Deadlocks escalate to executive.
|
|
320
|
+
|
|
321
|
+
### Gate Pipeline Details
|
|
556
322
|
|
|
557
|
-
|
|
323
|
+
Gates run in configured order. If all core gates (types, lint, tests) fail, remaining gates are skipped. Each gate has a 2-minute timeout. Results are cached per-branch to `.forge/verify-cache/<branch>.json`.
|
|
558
324
|
|
|
559
|
-
|
|
325
|
+
The self-healing loop parses failures into structured remediation templates -- each error includes file path, line number, error message, and a specific fix hint. Fix agents receive only the errors to fix, keeping context minimal and focused.
|
|
326
|
+
|
|
327
|
+
### Worktree Internals
|
|
328
|
+
|
|
329
|
+
Each session creates a worktree at `../.forge-wt/<repo>/<session-id>/` branching from the feature branch. Active sessions are tracked in `.forge/sessions.json`. On completion, the worktree branch merges back to the feature branch, then the worktree and its branch are deleted.
|
|
330
|
+
|
|
331
|
+
The parallel scheduler analyzes milestone `dependsOn` fields, builds a DAG, detects cycles, and groups independent milestones into parallel waves that execute simultaneously in separate worktrees.
|
|
332
|
+
|
|
333
|
+
</details>
|
|
334
|
+
|
|
335
|
+
---
|
|
336
|
+
|
|
337
|
+
<p align="center">
|
|
338
|
+
<sub>MIT License • Built for <a href="https://docs.anthropic.com/en/docs/claude-code">Claude Code</a></sub>
|
|
339
|
+
</p>
|