Forge

Drop forge into any repo and it drives the whole development loop — bite-sized tasks, a test written before each change, git hooks that enforce the cadence, and specialized Claude agents that do the work. State is markdown in git. No database, no lock-in.

What you get

• One procedure in every repo — the same task lifecycle, branch cadence, and review gates everywhere. No per-project reinvention of "how we do things here."
• Small, tested changes — a goal becomes tasks of ≤ 3 files / ≤ 100 LOC, each with a test written first. Small diffs are reviewable; every line has a reason.
• Hooks enforce it, not vibes — commit, push, PR, and deploy each have a gate that blocks when the rules aren't met. The same gates in every repo.
• You keep the decisions that matter — forge stops and asks at goal definition, look-and-feel, cost, and production deploy. It surfaces; you decide.
• Markdown is the source of truth — tasks are files in git; GitHub issues are a one-way copy (/forge:sync). Nothing to lock you in.

Install

Install the package once (npm puts forge on your PATH), set up the shared runtime, then adopt repos one at a time.

npm install -g @bluearch/forge   # the `forge` command, on your PATH
forge setup                      # populate the ~/.claude/forge runtime + adopt hook

Update later with npm update -g @bluearch/forge, then forge setup again — that's the package level. At the project level, forge upgrade pulls the new runtime into a repo.

From source instead (contributors) — this drops forge at ~/.local/bin/forge, so make sure ~/.local/bin is on your PATH:

git clone [email protected]:bluearchio/forge.git ~/src/forge
cd ~/src/forge && bash install.sh

As a Claude Code plugin:

/plugin marketplace add bluearchio/forge
/plugin install forge@forge

Bundle/offline install for teammates without repo access: docs/distribution.md.

Your first three commands

/forge:init                     # wire forge into this repo (hooks + tasks/ + CLAUDE.md)
/forge:goal "add CSV ingest"    # clarify → decompose into bite-sized, tested tasks
/forge:status                   # dashboard + what to do next

That's the loop: a goal becomes tasks, each task gets a failing test then an implementation, each commit moves the task to done, and you push a batch when it's ready. Full walkthrough: docs/usage.md.

What forge enforces vs. suggests

Forge is strict where a machine can be, advisory where only judgment works.

Enforced — a git hook blocks it (override only with FORGE_SKIP=1, logged):

| Gate | When | Blocks unless | |------|------|---------------| | bite-size · secrets · Formatting (docs/formatting.md) | commit | ≤ 3 files / ≤ 100 LOC, no secret, formatter clean | | tests · recorded task · security | push | tests pass, the work is recorded as a task, no open critical finding | | plan complete · security | PR | every planned task is done, security review is green | | pillars · cost · security | deploy | 6 Well-Architected pillars pass, in budget, review green |

Suggested — an instruction or a /forge:doctor warning (relies on the agent or human): plain-language communication, no-sycophancy / verify-with-data, docs-as-contracts, the per-commit security drain. A bash hook can't score prose or judgment, so these are guided, not gated.

Use forge as a CLI

Install once, then adopt any repo with a one-liner from inside it:

cd my-repo
forge init        # adopt this repo (= install.sh --project .)
forge status      # task dashboard (warns if this repo is behind the runtime)
forge doctor      # check this repo follows forge's rules
forge upgrade     # sync the runtime, then bring adopted projects current
forge remove      # un-adopt this repo

Full CLI contract: docs/cli.md.

How projects get adopted

Open any un-forged git repo in Claude Code and forge offers a one-line /forge:init — no scan, no daemon, just an offer. Run it and the repo is wired (hooks, tasks/ tree, CLAUDE.md fragment). Decline and forge writes a .forge/declined marker and never asks there again; running /forge:init later clears it. The offer stays silent on already-forged repos, non-git directories, and the forge source repo itself.

Keep every project current

Pull a newer forge, re-run the install, and your adopted repos are now behind. Forge makes that visible instead of silent:

• forge doctor / forge status warn when the current repo is behind the runtime.
• /forge:rollout scans every git repo for coverage and offers guided adoption.
• forge upgrade syncs the runtime, then walks your repos with a default-safe [y/N] re-wire per project. Contract: docs/upgrade.md.

Commands

Run these as slash commands inside Claude Code:

| Command | What it does | |---------|--------------| | /forge:init | Wire forge into this repo (safe to run again) | | /forge:goal "<goal>" | Start a feature — clarify, decompose, plan | | /forge:status | Task dashboard + task↔issue parity | | /forge:doctor | Verify the repo conforms to every forge directive | | /forge:deploy <target> | Gated cloud deploy (pillars + cost + security) | | /forge:sync | Reconcile the task tree with GitHub issues | | /forge:rollout | Scan every git repo for coverage + guided adopt | | /forge:improve | Usage telemetry → improvement tasks |

Learn more

• docs/architecture.md — how agents, hooks, and skills fit together
• docs/substack-forge.md — the one-page pitch, with diagrams
• CONTRIBUTING.md — forge develops itself through its own task/agent/hook machinery

Pairs well with

session-health — a zero-dependency, per-session quality score for any Claude Code session. Independent of forge; install either or both from the same marketplace.

Versioning & license

VERSION is the module semver — bump on schema changes to agents/hooks/templates; consumers re-run install.sh to pick them up. Changelog: CHANGELOG.md. MIT © 2026 bluearchio.