From 8c41d22102a3b4f5395ba49f964e74d1e36f76ff Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 5 Jul 2026 20:57:34 +0000 Subject: [PATCH] docs: restructure docs, fix install story, add complete usage guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Redesign the documentation and install story around the cognitive-substrate paper, applying a ponytail (YAGNI / reuse-first / shortest-diff) discipline — no source rewrites, only what the docs actually needed. Install (the main ask — stop leading with `bash install.sh`): - Recommended paths are now the plugin (Claude Code / Codex) and a token-free CLI install `npm install -g github:CodeWithJuber/forgekit` (verified: installs in seconds, no clone, no GitHub Packages token). `bash install.sh` is demoted to the symlink/dev path; the GitHub Packages route is marked CI-only. - Applied across README, ONBOARDING, docs/cognitive-substrate/README, and the landing page (install snippet + stale version 0.2.0 -> 0.3.1). Docs: - README rewritten to a professional standard: value prop, install matrix, quickstart, three-layer "how it works" table, auto-use section, command list, honest limits, docs index. Dropped the broken public-npm version badge. - New docs/GUIDE.md: every command with a worked example and its REAL output (captured from a live run), the everyday workflow, auto-use inside an agent, recipes, and how to extend each layer. - CHANGELOG updated. Verified: 147/147 tests pass; the substrate auto-use wiring is genuine end to end (Claude hooks + the forge-cortex MCP server exposing substrate_check / predict_impact / assumption_gate / route_task / scope_files + the emitted rule). Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01Eh3SNx15EeVbTmU4nH36XC --- CHANGELOG.md | 4 + ONBOARDING.md | 22 +- README.md | 279 ++++++++++--------- docs/GUIDE.md | 426 +++++++++++++++++++++++++++++ docs/cognitive-substrate/README.md | 7 +- landing/index.html | 24 +- 6 files changed, 620 insertions(+), 142 deletions(-) create mode 100644 docs/GUIDE.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 5fedd0f..959ed9f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,10 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - **Substrate now auto-runs in Claude Code.** The `UserPromptSubmit` hook injects the full substrate advisory (assumption gate + model routing + blast radius + memory + verify) when it matters, silent otherwise. Load-only — never builds/writes `.forge/` from a hook, fail-safe, never blocks. - **Cross-tool auto-use.** Added a `substrate` section to `source/rules.json` so `forge init` emits the "run substrate before risky work" rule into every tool's config (AGENTS.md, .cursor/rules, …). - **Docs rewritten** — `docs/cognitive-substrate/README.md` is a professional, example-rich guide (real command output, auto-use setup, extension points); README/SKILL aligned. +- **README restructured** to a professional standard — clear value prop, an install matrix, quickstart, a "how it works" three-layer table, an auto-use section, a full command list, honest limits, and a docs index. +- **Install story fixed.** The recommended paths are now the **plugin** (Claude Code / Codex) and a token-free CLI install, `npm install -g github:CodeWithJuber/forgekit` — no `curl | bash`, no clone. `bash install.sh` is documented as the symlink/dev path and the GitHub Packages route as CI-only. Updated across README, ONBOARDING, `docs/cognitive-substrate/README.md`, and the landing page. +- **New `docs/GUIDE.md`** — the complete guide: every command with a worked example and its real output, the everyday workflow, auto-use inside an agent, recipes, and how to extend each layer (rules, tools, guards, crew, routing signals, emitters, rebrand). +- **Landing page** — install snippet uses the token-free CLI command; version string corrected to 0.3.1. ### Fixed diff --git a/ONBOARDING.md b/ONBOARDING.md index f0ca1b0..b17ff65 100644 --- a/ONBOARDING.md +++ b/ONBOARDING.md @@ -2,14 +2,23 @@ ## 1. Install (once) +Pick one — no `curl | bash`, no clone required for either: + ```bash -bash install.sh # symlink global/ → ~/.forge + ~/.claude, put `forge` on PATH -# then merge the printed hooks/statusline block into ~/.claude/settings.json -# — or skip that and install the plugin, which auto-wires the guards: -# /plugin marketplace add → /plugin install forgekit +# A) Claude Code / Codex — the plugin (recommended; guards auto-wire, nothing to merge) +/plugin marketplace add CodeWithJuber/forgekit +/plugin install forgekit + +# B) Any tool — the CLI (no token, no clone) +npm install -g github:CodeWithJuber/forgekit + forge doctor # everything green? ``` +Hacking on Forge itself? Clone and `npm link`, or `bash install.sh` to symlink the +tree into `~/.claude` (idempotent, reversible, prints the hook block to merge). See +[README → Install](README.md#install) for the full matrix. + ## 2. Configure a repo (once per repo) ```bash @@ -120,5 +129,6 @@ file memory, not weight-level learning. - **Add a guard** → `global/guards/.sh` (source `_guardlib.sh` for fields + the lock), then wire it in `global/settings.template.json` and `hooks/hooks.json`. - **Rebrand** → edit `brand.json` (+ `package.json` bin, `.claude-plugin/plugin.json` name). -Full architecture, the pain-point evidence, and the cross-tool matrix live in -[ARCHITECTURE.md](ARCHITECTURE.md). +Every command with worked examples and the full extension guide live in +[docs/GUIDE.md](docs/GUIDE.md); the architecture, pain-point evidence, and cross-tool +matrix live in [ARCHITECTURE.md](ARCHITECTURE.md). diff --git a/README.md b/README.md index c04d41e..86cd7b7 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,58 @@ # Forge [![CI](https://github.com/CodeWithJuber/forgekit/actions/workflows/ci.yml/badge.svg)](https://github.com/CodeWithJuber/forgekit/actions/workflows/ci.yml) -[![npm](https://img.shields.io/npm/v/forgekit.svg)](https://www.npmjs.com/package/forgekit) -[![license: MIT](https://img.shields.io/npm/l/forgekit.svg)](./LICENSE) -[![node](https://img.shields.io/node/v/forgekit.svg)](https://www.npmjs.com/package/forgekit) -[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](./package.json) +[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE) +[![node: >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](./package.json) +[![runtime deps: 0](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen.svg)](./package.json) -**One config, every AI coding tool.** +**One config, every AI coding tool — plus the memory, foresight, and guardrails a +frozen model structurally lacks.** -> **Status: beta.** The core (`sync`, `verify`, `brain`, `scan`, `cost`, guards) is tested -> and in daily use; some flags/APIs may still change before `1.0`. +Forge is a cross-tool configuration layer for agentic coding assistants. You author +your rules **once**; Forge emits each tool's native config, enforces the +non-negotiables as deterministic guards, and adds a code-graph, cross-session memory, +a cost governor, and a **cognitive substrate** that runs a fast pre-action check +before an agent touches your code. Works with **Claude Code, Codex, Cursor, Gemini +CLI, Aider, Copilot, Windsurf/Devin, Zed, Continue, and Roo**. -Forge is a cross-tool configuration layer for agentic AI coding assistants. You -author your rules and workflow **once**; Forge emits each tool's native config, -enforces the non-negotiables as deterministic guards, and adds a code-graph, -cross-session memory, and a cost governor. Works with **Claude Code, Codex, -Cursor, Gemini CLI, Aider, Copilot, Windsurf/Devin, and Zed**. +> **Status: beta.** The core (`init`, `sync`, `substrate`, `impact`, `cortex`, guards) +> is tested and in daily use; some flags may still change before `1.0`. -**Install** — pick one: +- **New here?** → [Install](#install) then the [5-minute onboarding](ONBOARDING.md). +- **Want every command with worked examples?** → [`docs/GUIDE.md`](docs/GUIDE.md). +- **Want the theory?** → the [cognitive-substrate white paper](docs/cognitive-substrate/). -```bash -# A) Claude Code / Codex — as a plugin (recommended) -/plugin marketplace add CodeWithJuber/forgekit -/plugin install forgekit +--- -# B) Clone and run the installer (puts `forge` on your PATH) -git clone https://github.com/CodeWithJuber/forgekit.git -cd forgekit && bash install.sh -``` +## Install + +Pick the row that matches how you work. **No `curl | bash`, no clone required** for +the two recommended paths. + +| You use… | Run this | What you get | +| --- | --- | --- | +| **Claude Code / Codex** *(recommended)* | `/plugin marketplace add CodeWithJuber/forgekit`
`/plugin install forgekit` | The full plugin — tools, crew, and **ambient guards** wired automatically. Zero setup. | +| **Any tool, from the CLI** | `npm install -g github:CodeWithJuber/forgekit` | The `forge` command on your `PATH`. No token, no clone. | +| **Contributors / local dev** | `git clone https://github.com/CodeWithJuber/forgekit.git`
`cd forgekit && npm link` | An editable checkout with `forge` linked to your working copy. | -**Use** — in any repository: +Verify any install with one command: ```bash -forge init # emit every tool's config from one source -forge substrate "task" # assumption gate + route + impact + scope + verify -forge doctor # verify everything is wired +forge doctor # health-check: tools, guards, MCP auth, config drift ```
-CI / devcontainer install via npm (GitHub Packages) +Alternative installs (symlink dev setup · GitHub Packages · CI) -Forge publishes to GitHub Packages as `@codewithjuber/forgekit`. GitHub Packages requires a -token even for public installs, so authenticate the scope once, then run it: +**Symlink `global/` into `~/.claude` (dev setup).** From a clone, `bash install.sh` +symlinks the tree into `~/.forge` + `~/.claude` and prints the hook block to merge. +It is idempotent, reversible (`bash install.sh --uninstall`), offline, and never +edits your `settings.json` for you. Prefer the plugin unless you're hacking on Forge +itself. + +**GitHub Packages (`@codewithjuber/forgekit`).** Published to GitHub Packages, which +requires an auth token even for public installs — so it's only worth it in CI that +already authenticates: ```bash echo "@codewithjuber:registry=https://npm.pkg.github.com" >> ~/.npmrc @@ -51,100 +62,95 @@ npx @codewithjuber/forgekit init
-All channels drive the **same** `global/` tree. - -## Why - -A single developer now juggles several AI coding tools, and each one: - -- reads a **different** config file (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, `GEMINI.md`…), -- **acknowledges your rules then ignores them**, especially after context compaction, -- has **no memory** across sessions, and -- can quietly rack up a surprise token bill. - -Forge answers each of these with a specific mechanism, not a vibe — see -[ARCHITECTURE.md](ARCHITECTURE.md) for the evidence behind every one. - -## Start Here — `forge catalog` - -| Layer | What | Examples | -| ---------- | ---------------------------------------------------- | -------------------------------------------------------------- | -| **tools** | model-invoked skills (know-how, on demand) | `lean` · `reuse-first` · `tech-selector` · `atlas` · `recall` | -| **crew** | isolated-context sub-agents | `scout` · `verifier` · `frontend-verifier` | -| **guards** | deterministic hooks — the only layer that _enforces_ | `protect-paths` · `cost-budget` · `lean-guard` · `recall-load` | - -Run `forge catalog` for the full list with a one-line _why_ per item. +All three front doors drive the **same** `global/` + `source/` tree — no duplication. -## The one idea that matters +--- -**Rules the model can drift from live in prose; rules it must never break live in -guards.** A guard is a shell hook — it runs regardless of what the model -"remembers." So Forge demotes enforceable invariants (don't touch `.env`, watch -the token budget, keep diffs small) out of `CLAUDE.md` prose and into guards, and -keeps the prose thin and single-sourced. Guards _reduce_ the "ignored my rules" -problem to the semantic rules that genuinely can't be a hook — and says so plainly. +## Quickstart -## Forge Cortex — self-correcting project memory +```bash +cd your-project -An LLM is stateless: it relearns your repo every session and repeats the correction you -gave it last week. **Cortex** is the layer that fixes that. It watches for a _genuine_ -recurring mistake on this repo — a test that failed then passed after edits, a `git revert`, -repeated edits to the same symbol, an explicit "undo" — distills a durable lesson, and -re-confirms it against fresh outcomes. Next time you touch that file, the lesson is there. +forge init # emit every tool's native config from one shared source +forge substrate "add rate limiting to the /login route" # pre-action check before you edit +``` -What keeps it trustworthy (this is the hard part, and it's built in): +`forge init` configures Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Zed, +Continue, and Roo — each reads the **same** rules from its own native file. On Claude +Code the substrate then runs **on every prompt, automatically** (see [below](#it-runs-itself)). -- **Injection is never confirmation.** Only independent outcomes (tests, builds, a human) - move a lesson's confidence — it can't grade its own homework. -- **A green build / human reversal always wins.** A mistake is a bad _outcome_, not - "differs from a lesson"; change your mind and the lesson retires instead of fighting you. -- **A wrong lesson decays out.** Confidence is a time-decayed `Beta` posterior; unconfirmed - or contradicted lessons quarantine, then retire. It can't ossify. -- **Advisory, never blocking.** The hooks are fail-safe by construction — worst case, they - do nothing. +--- -On **Claude Code** it's fully ambient (hooks). Other tools read the lessons from `AGENTS.md` -and a zero-dependency MCP server (`forge cortex-mcp`). Everything lives in `.forge/lessons/` -— git-committable and auditable. Try it: `node examples/cortex-demo.mjs`. +## Why Forge exists -## Forge Cognitive Substrate — the check that runs before every edit +A single developer now juggles several AI coding tools, and each one: -A frozen model can't remember, can't foresee, and can't see what an edit will break. The -**cognitive substrate** supplies those faculties from the outside: a fast, mostly-deterministic -check (no extra LLM call) that runs _before_ the agent touches code. One command does it all: +- reads a **different** config file (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, `GEMINI.md`…), +- **acknowledges your rules, then ignores them** — especially after context compaction, +- has **no memory** across sessions, re-learning your repo every time, +- **can't see what an edit breaks** beyond the files in its window, and +- can quietly run up a surprise token bill. + +Forge answers each with a specific mechanism, not a vibe. The mechanisms come straight +from a first-principles read of what a frozen language model *is* — a stateless +function `y = f(x)` with fixed weights and a bounded window — and what that shape +structurally prevents. The full argument, with evidence graded against primary +sources, is the [cognitive-substrate white paper](docs/cognitive-substrate/). + +## How it works — three layers + +| Layer | Named | What it does | Enforcement | +| --- | --- | --- | --- | +| **tools** | model-invoked skills | know-how loaded on demand: `lean`, `reuse-first`, `atlas`, `recall`, `cognitive-substrate` | the model chooses to use them | +| **crew** | isolated sub-agents | fresh-context specialists: `scout`, `verifier`, `frontend-verifier` | spawned per task | +| **guards** | deterministic hooks | the **only** layer that *enforces*: `protect-paths`, `cost-budget`, `doom-loop`, `cortex` | runs regardless of what the model "remembers" | + +**The one idea that matters:** rules the model can drift from live in prose; rules it +must **never** break live in **guards**. A guard is a shell hook — it can't be +forgotten after a context compaction. So Forge demotes enforceable invariants (don't +touch `.env`, watch the token budget, keep diffs small) out of `CLAUDE.md` prose and +into guards, and keeps the prose thin and single-sourced. + +Two subsystems build on those layers: + +- **Forge Cortex — self-correcting memory.** An LLM relearns your repo every session + and repeats last week's correction. Cortex watches for a *genuine* recurring mistake + (a test that failed then passed, a `git revert`, an explicit "undo"), distills a + durable lesson, and re-confirms it against fresh outcomes. Injection never confirms a + lesson — only independent outcomes (tests, builds, a human) move its confidence, so a + wrong lesson decays out instead of ossifying. Advisory, never blocking. + +- **Forge Cognitive Substrate — the check before every edit.** One fast, mostly- + deterministic command supplies the faculties a frozen model can't have: is the task + clear enough to start (**assumption gate**), which model is cheapest-but-capable + (**route**), what will this edit break (**impact / blast radius**), what can be split + into separate sessions (**scope**), and how do we prove it worked (**verify**) — all + from the repo you already have, with no extra LLM call. ```bash forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" ``` -It returns, in one contract: the **assumption gate** (is the task clear enough to start?), -the cheapest **capable model**, the predicted **blast radius** (which files an edit breaks), -**scope** clusters (what to split into separate sessions), relevant **Cortex lessons**, -**minimality** warnings, and a **verification** checklist. +returns, in one pass: the assumption verdict, the cheapest capable model, the predicted +blast radius (including the coupled files you *didn't* name), scope clusters, relevant +Cortex lessons, and a verification checklist. -**It runs itself.** In Claude Code a `UserPromptSubmit` hook fires the substrate on every -prompt and adds a short advisory only when something needs attention — never blocking, never -nagging on a clean task. Other tools (Codex, Cursor, Gemini, Aider…) get a rule in their -config telling the agent to run it, plus the MCP tools `substrate_check`, `assumption_gate`, -`predict_impact`, `route_task`, and `scope_files`. +## It runs itself -Each check is also its own command: +You don't have to remember to use any of this. -| Command | Answers | -| ----------------------------- | ------------------------------------------------------------------ | -| `forge preflight ""` | Is this clear enough to start? (flags unknown names + vague words) | -| `forge route ""` | Cheapest capable model — Haiku → Sonnet → Opus → Fable | -| `forge impact ` | What will this edit break? (reverse-dependency blast radius) | -| `forge scope ` | Independent vs. coupled files → separate sessions | -| `forge uicheck ` | Exact WCAG contrast math for UI work | +- **In Claude Code** — a `UserPromptSubmit` hook runs the substrate on **every prompt** + and adds a short advisory *only when something needs attention* (unclear task, big + blast radius, pricey model). It never blocks and never nags on a clean, simple task. +- **In other AI tools** (Codex, Cursor, Gemini, Aider…) — `forge init` writes a rule + into their native config telling the agent to run the check itself, and exposes it as + MCP tools any MCP-capable agent can call: `substrate_check`, `assumption_gate`, + `predict_impact`, `route_task`, `scope_files`. -Deterministic checks (repo grounding, graph traversal, routing arithmetic) are **asserted**; -model fit, minimality, and memory relevance stay **advisory**. Everything is advisory overall -and never blocks — tests and human corrections always win. +Forge never pretends it can force a hook into a tool that has none — it's **ambient on +Claude Code, agent-invoked everywhere else**, and says so plainly. -**→ Full guide with worked examples, auto-use setup, and how to extend it: -[`docs/cognitive-substrate/`](docs/cognitive-substrate/)** (also holds the white paper, -evidence map, and ecosystem map). +--- ## Commands @@ -152,37 +158,58 @@ evidence map, and ecosystem map). forge init emit this repo's config for every tool (one command) forge sync recompile source/ → each tool's native files (idempotent) forge doctor pass/fail health check (layers, install, drift, cortex) -forge catalog Start-Here index of every tool/crew/guard -forge cortex self-correcting memory — status / why +forge catalog Start-Here index of every tool / crew / guard + forge substrate full pre-action cognitive-substrate check -forge impact predict blast radius for a symbol or file forge preflight assumption check — what a task names that the repo doesn't define forge route cheapest capable model for a task (+ gateway config) +forge impact predict blast radius for a symbol or file forge scope decompose files into independent clusters +forge verify independent verification — tests + hallucinated-symbol check forge uicheck deterministic WCAG contrast check -forge atlas build/query the code-graph (where-is-X, has-symbol) -forge recall cross-session memory (list/add/consolidate) -forge brand show the brand token map + +forge cortex self-correcting memory — status / why +forge atlas build / query the code-graph (where-is-X, has-symbol) +forge recall cross-session memory (list / add / consolidate) +forge brain portable project memory inlined into AGENTS.md +forge cost real per-day spend via ccusage + the cost ceiling +forge scan vet a skill/MCP for injection/RCE before install +forge harden wire gitleaks pre-commit + sandbox settings +forge brand print the active brand token map ``` -## What's honest about it +**→ Every command with a worked example, expected output, and how to extend it: +[`docs/GUIDE.md`](docs/GUIDE.md).** -- **Guards reduce, don't eliminate**, the "ignored my rules" problem — semantic - rules still live in prose and can still be missed. -- **`recall` is file + prompt memory**, not weight-level learning. No RL, no - fine-tuning. Consolidation is deterministic (exact-dupe prune), not a model call. -- **`atlas` v1 indexes symbol definitions + membership**, not a full call graph. - It flags likely-hallucinated symbols; it does not certify correctness. -- **Cortex is new and unproven on your repo.** The signal thresholds are hand-tuned and the - learned predictor starts with zero data — it holds itself to the heuristic until it earns - more. It's advisory memory, not a guarantee; judge it after a couple of weeks of real use. +--- -## Layout +## What's honest about it -One tree, three front doors — `install.sh`, the plugin manifest, and the npm bin -all point at `global/` and `source/` (no duplication). See -[ARCHITECTURE.md](ARCHITECTURE.md) for the full map, and [ONBOARDING.md](ONBOARDING.md) -to get productive in five minutes. +Forge states its own ceiling everywhere — the same discipline the substrate applies to +your edits. + +- **Guards reduce, don't eliminate** the "ignored my rules" problem — semantic rules + still live in prose and can still be missed. +- **`recall` / `cortex` are file + prompt memory**, not weight-level learning. No RL, + no fine-tuning. Consolidation is deterministic, not a model call. +- **`atlas` / `impact` is a regex-approximate graph.** It flags likely-hallucinated + symbols and catches the obvious dependents; it is *conservative*, not a sound call + graph, and can miss dynamic dispatch or generated code. +- **The substrate's rubrics are heuristic, not benchmarked** — tuned on small + hand-labeled sets. What's *asserted* (safe to gate on): repo grounding, graph + traversal, scope decomposition, routing arithmetic, and the test/build commands. + What's *advisory* (flagged, never asserted): model fit, minimality, and memory + relevance. **Tests and human corrections always win.** + +## Documentation + +| Doc | What's in it | +| --- | --- | +| [`ONBOARDING.md`](ONBOARDING.md) | Five minutes to productive + the design principles. | +| [`docs/GUIDE.md`](docs/GUIDE.md) | Every command, worked examples, all cases, how to extend. | +| [`docs/cognitive-substrate/`](docs/cognitive-substrate/) | The white paper, evidence map, ecosystem map, and prototype sources. | +| [`ARCHITECTURE.md`](ARCHITECTURE.md) | The four-layer compiler, the pain-point evidence, and the cross-tool emit matrix. | +| [`CHANGELOG.md`](CHANGELOG.md) | What changed, per release. | ## Community & support @@ -197,4 +224,6 @@ The name lives in one place: `brand.json` (`FORGE_BRAND`). Change it there (plus `bin` key in `package.json` and `name` in `.claude-plugin/plugin.json`) and the whole CLI, banner, and emitted headers follow. -MIT licensed. +--- + +MIT licensed. Built by [CodeWithJuber](https://github.com/CodeWithJuber). diff --git a/docs/GUIDE.md b/docs/GUIDE.md new file mode 100644 index 0000000..7ac9584 --- /dev/null +++ b/docs/GUIDE.md @@ -0,0 +1,426 @@ +# Forge — the complete guide + +Every command with a worked example and its **real** output, the everyday workflow, +how to make it run itself inside any agent, common recipes, and how to extend each +piece. If you just want to get going, the [5-minute onboarding](../ONBOARDING.md) is +shorter; this is the reference you come back to. + +- [Mental model](#mental-model) +- [The everyday workflow](#the-everyday-workflow) +- [Command reference](#command-reference) — every command, with examples +- [Auto-use inside an agent](#auto-use-inside-an-agent) +- [Reading substrate output](#reading-substrate-output) +- [Recipes](#recipes) — common situations, start to finish +- [Extending Forge](#extending-forge) +- [Honest limits](#honest-limits) + +--- + +## Mental model + +A language model at inference time is a fixed function `y = f(x)` — frozen weights, a +bounded window, no state between calls. From that shape, five things follow that no +prompt can fix: it can't **remember** across sessions, can't **learn** from outcomes, +can't **imagine** what an edit breaks, can't reliably **check itself**, and can't see +**what already exists** beyond its window. + +Forge supplies those faculties from the *outside*, in three layers: + +- **tools** — know-how the model loads on demand (`lean`, `atlas`, `recall`…). +- **crew** — isolated sub-agents for focused work (`scout`, `verifier`…). +- **guards** — deterministic shell hooks that *enforce* what prose can't (the only + layer the model can't drift from). + +Two subsystems sit on top: **Cortex** (self-correcting memory) and the **cognitive +substrate** (`forge substrate` — the pre-action check). The full argument is the +[white paper](cognitive-substrate/). + +--- + +## The everyday workflow + +```bash +cd your-project +forge init # once per repo: emit every tool's config +forge atlas build # once: index symbols so impact/scope work well + +# then, for any non-trivial change: +forge substrate "" # is it clear? which model? what breaks? split? +# …make the edit… +forge verify # prove it — real tests + hallucinated-symbol check +``` + +On **Claude Code** the `forge substrate` step happens automatically on every prompt +(see [Auto-use](#auto-use-inside-an-agent)); on other tools you or the agent run it. + +--- + +## Command reference + +Outputs below are copied verbatim from a real run against a four-file demo repo where +`src/login.js` and `src/session.js` both `import { verifyToken } from "./auth.js"`. + +### `forge substrate ""` — the one pre-action check + +Bundles assumption gate + route + impact + scope + memory + verify into one verdict. +This is the command you'll use most. + +**A clear task — cleared to proceed, with the blast radius:** + +```console +$ forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" + +Forge substrate — pre-action check + + proceed: yes + assumption: medium risk · completeness 0.63 + + route: Haiku 4.5 (simple) · complexity 0.15 + driven by: base cost of any task + + impact: 3 file(s) predicted + - src/auth.js + - src/login.js + - src/session.js + + verify: + - review impacted files before editing + - run the narrowest affected test first, then the broader suite +``` + +It found `login.js` and `session.js` — the two files that import `verifyToken` but you +never named. That's the "forgot the coupled file" bug, caught *before* the edit. + +**A vague task — it tells you to ask first:** + +```console +$ forge substrate "make the auth better" + +Forge substrate — pre-action check + + proceed: ASK FIRST + assumption: high risk · completeness 0.23 + + clarify: + - What exactly should this produce, and how will we know it is correct? + + route: Haiku 4.5 (simple) · complexity 0.15 + impact: 0 file(s) predicted +``` + +Add `--json` for machine-readable output (see [Use it in a script](#use-it-in-a-script)). + +### `forge preflight ""` — is this clear enough to start? + +The assumption gate on its own. Flags names the repo doesn't define and vague wording. + +```console +$ forge preflight "fix the thing in authManager so it works properly" + +Forge preflight — assumption check + + info-gap: 1.00 · completeness 0.01 (referenced 1 symbol(s), 0 file(s)) + +## Before starting — clarify (Forge Preflight) +This task has unknowns that would otherwise become assumptions: + +- `authManager` — not found in the code. Different name, or should it be created? +- Ambiguous: "properly" — state concrete acceptance criteria. +- Which specific file, module, component, or symbol should this change touch? +- How will we verify it: tests, acceptance criteria, benchmark, or reference behavior? + +_Advisory: ask rather than assume._ +``` + +### `forge route ""` — the cheapest capable model + +A transparent additive rubric (never a second LLM call). Every point is attributable +to a named signal you can inspect and override. + +```console +$ forge route "write an is_prime function" + → Haiku 4.5 (simple, $1/$5 per M tok) + lint, formatting, docs, stubs, trivial well-defined edits + complexity 0.13 · driven by: ambiguity, base cost of any task + +$ forge route "design and implement a distributed rate limiter with sliding windows across 3 services" + → Fable 5 (extreme, $10/$50 per M tok) + complexity 0.95 · driven by: algorithmic/systems difficulty, architectural/design scope +``` + +Run `forge route gateway` to emit a LiteLLM config so the routing happens automatically. + +### `forge impact ` — what will this edit break? + +Reverse-dependency blast radius from the atlas graph. Run `forge atlas build` first. + +```console +$ forge impact verifyToken +Forge impact — blast radius + + target: verifyToken ✓ found + impacted files: 3 + - src/auth.js + - src/login.js + - src/session.js +``` + +### `forge scope ` — can this be split into sessions? + +Groups the files you name into independent clusters and surfaces coupled files you +*didn't* name — so you split cleanly instead of overloading one session. + +```console +$ forge scope src/auth.js src/report.js +Forge scope — task decomposition + + 2 independent groups → consider a separate session per group: + + [1] src/auth.js + ! also coupled (you didn't name): src/session.js, src/login.js + [2] src/report.js +``` + +### `forge verify` — did it actually work? + +The independent check: runs the real test suite and flags edited symbols that aren't in +the codebase (possible hallucinations). This is what turns "the model says it's done" +into "the tests say it's done." + +```console +$ forge verify +Forge verify + + changed files: 2 + tests: ✓ pass + symbols checked: 7 + provenance: .forge/provenance.json + + PASS +``` + +### `forge atlas build | query | has` — the code-graph + +```console +$ forge atlas build + indexed 5 symbols in 4 files → .forge/atlas.json + +$ forge atlas query verifyToken + src/auth.js:1 function verifyToken + +$ forge atlas has doesNotExistSymbol + ✗ not found (possible hallucinated symbol): doesNotExistSymbol +``` + +`query` costs a few hundred tokens instead of reading five files; `has` is a cheap +"is this symbol real?" check before an agent calls it. + +### `forge recall add | list | consolidate` — cross-session memory + +Durable facts, one per file, injected at the start of the next session by the +`recall-load` guard. Secrets are refused. + +```console +$ forge recall add "db-port" "Postgres runs on 5433 here, not 5432" + saved: db-port +$ forge recall list + - db-port +``` + +### `forge cortex [status | why ]` — self-correcting memory + +Status of the lessons Cortex has learned from *this repo's* correction history. + +```console +$ forge cortex +Forge cortex — self-correcting project memory + + lessons: 0 (active 0 · candidate 0 · quarantined 0 · retired 0) + + (no active lessons yet — Cortex learns from corrections as you work) + + stored in .forge/lessons/ (git-committable, auditable) +``` + +`forge cortex why ` shows the lessons that would be injected when you touch it. + +### `forge uicheck ` — deterministic WCAG contrast + +Exact contrast math for UI work — asserted, never guessed. + +```console +$ forge uicheck "#777" "#fff" + contrast #777 on #fff: 4.48:1 → fail (FAILS AA) +``` + +### The rest + +| Command | Answers | +| --- | --- | +| `forge init` | Emit every tool's native config from one source. | +| `forge sync` | Recompile `source/` → each tool's files (idempotent). | +| `forge doctor` | Health check: layers, install, drift, cortex. | +| `forge catalog` | Start-Here index of every tool / crew / guard. | +| `forge brain` / `forge remember` | Portable project memory inlined into `AGENTS.md`. | +| `forge cost` | Real per-day spend (via `ccusage`) + the cost ceiling. | +| `forge scan ` | Vet a skill/MCP for injection/RCE before install. | +| `forge harden` | Wire gitleaks pre-commit + sandbox settings. | +| `forge spec [init\|lock\|check]` | Spec-as-contract drift check. | +| `forge brand` | Print the active brand token map. | + +### Use it in a script + +```bash +forge substrate "update verifyToken in src/auth.js" --json +``` + +```jsonc +{ + "okToProceed": false, + "assumption": { "risk": "high", "shouldAsk": true, "questions": ["…"] }, + "route": { "tier": "simple", "model": { "name": "Haiku 4.5" } }, + "impact": { "impactedFiles": ["src/auth.js", "src/login.js"] }, + "verification": { "checklist": ["npm test", "npm run typecheck"] } +} +``` + +Gate your agent's next step on `okToProceed`; feed `route.tier` to your model picker; +read `impact.impactedFiles` before editing. `forge impact --json` is available +too. + +--- + +## Auto-use inside an agent + +The point of Forge is that you don't have to *remember* to run these checks. + +### Claude Code — fully ambient + +Install the plugin and the substrate runs on **every prompt** via a `UserPromptSubmit` +hook. It adds a short advisory only when something needs attention and never blocks: + +```text +Forge substrate — pre-action advisory (advisory, never blocks): +- Under-specified (high risk). Ask before editing: + • What constraints must be respected: performance, dependencies, style, compatibility? +- Suggested model: Haiku 4.5 (simple); escalate only on a verifier failure. +- Predicted blast radius (2): login.js, auth.js. Review these before editing. +- Verify with: review impacted files before editing · run the narrowest affected test first +``` + +Nothing to wire — the plugin's [`hooks/hooks.json`](../hooks/hooks.json) installs the +`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` guards for you. + +### Every other tool — a rule + MCP tools + +`forge init` writes a rule into each tool's native config (`AGENTS.md`, `.cursor/rules`, +`GEMINI.md`, …) telling the agent to run the check itself: + +> Before ambiguous, expensive, multi-file, or mutating work, run +> `forge substrate "" --json` (or the MCP tool `substrate_check`). If +> `okToProceed` is false, ask the questions first; read `impact.impactedFiles` before editing. + +…and exposes the substrate as MCP tools any MCP-capable agent can call directly: + +| MCP tool | Does | +| --- | --- | +| `substrate_check` | full pre-action check | +| `assumption_gate` | ask/proceed + questions | +| `predict_impact` | blast radius | +| `route_task` | model recommendation | +| `scope_files` | independent vs. coupled | + +Forge never pretends it can force a hook into a tool that has none — **ambient on Claude +Code, agent-invoked everywhere else.** + +--- + +## Reading substrate output + +| Field | What it means | Do this | +| --- | --- | --- | +| `proceed: ASK FIRST` / `okToProceed: false` | task is under-specified | ask the `clarify` questions, don't guess | +| `route` | cheapest capable model | start there; escalate only if a verifier fails | +| `impact` | predicted blast radius | read these files before editing | +| `scope` | independent vs. coupled work | split independent groups into separate sessions | +| `memory` | past Cortex lessons for this area | context, not law — tests override it | +| `verify` | how to prove it works | run it, show the output, then say "done" | + +--- + +## Recipes + +**Before a risky refactor.** `forge impact ` (or `forge substrate ""`) to +see every dependent, including the ones the ticket didn't name; read them; edit the +shared function once at the root, not each caller. + +**Splitting a big change.** `forge scope ` → if it reports more than one +independent group, do a session per group; keep coupled files together. + +**Controlling cost.** `forge route ""` before you pick a model; `forge cost` for +real spend; the `cost-budget` guard warns when a day exceeds `FORGE_COST_CEILING`. + +**Teaching the repo a fact.** `forge recall add "" ""` — it's injected next +session. For learned-from-mistakes memory, just work: Cortex captures recurring +corrections on its own. + +**UI work.** `forge uicheck ` for exact contrast; the `ui-workflow` and +`taste` tools for the rest. + +--- + +## Extending Forge + +Everything is small, single-sourced, and testable. Change one piece, run `npm test`. + +### Add or change a rule +Edit [`source/rules.json`](../source/rules.json), then `forge sync`. The rule is +re-emitted into every tool's native file with a content-hash header. + +### Add a tool (skill) +Create `global/tools//SKILL.md` with `name` + `description` frontmatter. It's +picked up by the plugin and by `forge catalog`. + +### Add a guard (enforced hook) +Create `global/guards/.sh` (source `_guardlib.sh` for the shared fields + the +re-entrancy lock), then wire it in `global/settings.template.json` **and** +[`hooks/hooks.json`](../hooks/hooks.json). Guards must be idempotent and fail-safe — +worst case they do nothing. + +### Add a crew member (sub-agent) +Create `global/crew/.md` with frontmatter. It installs into `~/.claude/agents/`. + +### Tune the cognitive substrate +| To change… | Edit | +| --- | --- | +| how often it asks | `source/substrate.json` → `defaults.askThreshold` (0.6) | +| blast-radius sensitivity | `source/substrate.json` → `defaults.impactThreshold` (0.1) | +| a routing signal | `src/route.js` → `rubricComplexity()` | +| model tiers / prices | `src/model_tiers.js` | +| an assumption question | `src/preflight.js` → `DIMENSIONS[]` | +| the verify checklist | `src/substrate.js` → `verificationChecklist()` | +| when the ambient hook speaks | `src/substrate.js` → `substrateContext()` | +| the cross-tool rule wording | `source/rules.json` → `substrate` section (then `forge init`) | + +### Support a new tool +Add an emitter module in `src/emit/.js` (mirror an existing one like +`src/emit/cursor.js`), then register it in `src/sync.js`. A golden-file test in +`test/sync.test.js` keeps it honest. + +### Rebrand +Edit `brand.json` (`FORGE_BRAND`), the `bin` key in `package.json`, and `name` in +`.claude-plugin/plugin.json`. The whole CLI, banner, and emitted headers follow. + +--- + +## Honest limits + +- **Guards reduce, don't eliminate** the "ignored my rules" problem — semantic rules + still live in prose. +- **`recall` / `cortex` are file + prompt memory**, not weight-level learning. +- **The atlas graph is regex-approximate** — conservative, not a sound call graph; + dynamic dispatch and generated code can be missed. +- **The substrate's rubrics are heuristic, not benchmarked** — judge them after real + use. What's *asserted* (safe to gate on): repo grounding, graph traversal, scope + decomposition, routing arithmetic, and the test/build commands. Everything else is + *advisory*. **Tests and human corrections always win.** diff --git a/docs/cognitive-substrate/README.md b/docs/cognitive-substrate/README.md index c47d7aa..3a1e8c3 100644 --- a/docs/cognitive-substrate/README.md +++ b/docs/cognitive-substrate/README.md @@ -17,13 +17,12 @@ In Claude Code it runs **automatically**. In other tools you (or the agent) run ## Install (about 2 minutes) ```bash -# Claude Code / Codex — install as a plugin +# Claude Code / Codex — the plugin (recommended; the check then runs on every prompt) /plugin marketplace add CodeWithJuber/forgekit /plugin install forgekit -# …or clone and run the installer (puts `forge` on your PATH) -git clone https://github.com/CodeWithJuber/forgekit.git -cd forgekit && bash install.sh +# …or the CLI, any tool (no token, no clone) +npm install -g github:CodeWithJuber/forgekit ``` Then, inside any project: diff --git a/landing/index.html b/landing/index.html index 67976ff..4a34639 100644 --- a/landing/index.html +++ b/landing/index.html @@ -746,10 +746,15 @@

$ git clone … && bash - install.sh$ npm install -g + github:CodeWithJuber/forgekit - +
See how it learns @@ -1067,10 +1072,15 @@

Give your agent a memory that gets better the more it's wrong.

$ git clone … && bash - install.sh$ npm install -g + github:CodeWithJuber/forgekit + + copy +
Give your agent a memory that gets better the more it's wrong.