mgratzer/forge

Agent skills for structured development with pluggable issue tracking. One workflow. Ten skills. From idea to merged code.

Quick start · How it works · Skills · Lens · Architecture · Contributing

---

A forge is where raw material meets intention. You bring the codebase; these skills shape the workflow from issue to implementation to review.

---

Quick Start

Install forge one way per machine:

# Claude Code: the skills plus the lens above
/plugin install forge --marketplace mgratzer/forge

# any other agent that reads Agent Skills
npx skills add mgratzer/forge

Then, in your project:

/forge-setup-project       # once per repo: AGENTS.md and the docs agents work from
/forge-ship 42             # implement Issue #42, review it in fresh context, open the PR
/forge-ship --guard 42     # and keep going: CI, review feedback, then a risk verdict

With the plugin, the commands are namespaced (/forge:forge-ship), and /forge demo replays a guarded run in the lens without touching GitHub.

How It Works

forge-setup-project → [forge-shape →] forge-create-issue → forge-implement → forge-reflect → forge-address-pr-feedback → forge-guard → forge-land
                                                                        ╰──── forge-ship ────╯╰────────── forge-ship --guard ───────────╯

Ship implements a change from an Issue, a plan file or a description: it researches the codebase, works in vertical phases with tests, runs the app on the changed path when the project says how, and opens a PR. A fresh-context reviewer, not the session that wrote the code, reviews the diff before you see it.

Guard drives the open PR to review-ready without anyone watching: a simplification pass, a security pass when the diff calls for one, CI, the peer reviewer, and feedback in bounded rounds. It never merges.

Land judges a green PR’s risk on its head commit and writes the verdict into the PR. Low risk means you can merge without reading the diff; anything else comes with a list of where to look. It merges by itself only when the project opts in.

Issues live wherever you keep them: GitHub, a markdown plan/ folder in the repo, or a tracker you declare in AGENTS.md. For many Issues at once, forge-batch groups them into Waves that can ship in parallel; see Unattended Shipping.

Skills

Every skill takes optional trailing guidance: /forge-ship 42 -- keep the diff minimal.

The Lens

The Claude Code plugin adds the lens: a pane beside the session that follows a forge run, with its current state, the command that most likely comes next, the PR’s CI and review state, review findings, and the risk verdict. /forge says where a run is and what to do next. The lens only reads what the skills already print, so the skills work the same without it. See Lens.

Install Details

Claude Code plugin. /plugin install forge --marketplace mgratzer/forge brings the skills and the lens. The plugin tracks commits on main: update with claude plugin update forge@forge, or turn on auto-update for the marketplace under /plugin.

npx skills. npx skills add mgratzer/forge detects your agents and installs the skills to each of them (skills.sh).

Manual. Symlink the skills into your agent’s skills directory:

ln -s /path/to/forge/skills/forge-* /

Each skill carries its own copy of the shared modules in _shared/, so nothing else needs installing. Use one channel per machine: with both the plugin and npx, Claude Code lists every skill twice, once as /forge-ship and once as /forge:forge-ship. npx skills update -g recreates the ~/.claude/skills links when ~/.claude exists, so removing them doesn’t last while the npx install remains.

Contributing

AGENTS.md has the commands CI runs and an index of the docs. Exercise a skill change in a sandbox repository, not a real project (Testing), and use conventional commits (feat(skills): add a skill).

License

MIT