Forge

Forge runs multi-step, resumable workflows for AI-assisted delivery: sketch fuzzy intent, investigate and design, plan, implement, review, test, audit UX, diagnose, and ship. A takeover mode chains those skills autonomously until the work is ship-ready.

The same install works in Cursor, Claude Code, and OpenAI Codex. Cursor and Claude use slash commands (/forge:plan); Codex uses $forge:plan-style skills. Most skills call the forge CLI under the hood — you don't need to type forge … yourself inside any of these apps. For terminals and CI, see Advanced.

Install once with pipx install forge-next, then run forge install. This repository is the source tree for the prompts, templates, and orchestrators that package ships.

Command notation

On disk, Codex skill folders use hyphens (forge-diagnose/) because : isn't valid in paths, but each SKILL.md sets name: forge:diagnose, which Codex shows as $forge:diagnose. If a handoff prints a plain forge: … label, treat it as shorthand and use the slash or $ form for your app.

Overview

Forge skills share one process spine — Frame, Orient, Deepen, Decide, Act, Verify, Handoff — and a --ceremony flag that selects a job, not four volumes of the same spine. --ceremony wins over estimate. Honor light as produce-and-stop — do not auto-continue unused steps. Mode axes (evaluate pre/post, test run/flows) stay orthogonal. Full contract: docs/ceremony.md.

Unused band names alias down to the highest job that skill actually implements. Integrity floors (design spec gate, diagnose high-severity techniques, plan skeleton) stay hard at light.

A few things carry across every skill:

• State lives in .forge/. Runs are interruptible; resume with forge takeover (or the matching slash/$forge: command).
• Sessions are isolated but shareable. Multiple runs can be active at once under .forge/sessions/{id}/, coordinating through a shared memory/project.md. Details: docs/sessions.md.
• Handoffs are a numbered menu, not a hard fork. The last step of a skill prints a default next command plus alternatives; reply yes, a number, or stop.
• Sub-agents report progress. Dispatched agents write heartbeats so a parent chat isn't silent mid-task.
• Every run leaves an audit trail in memory/<skill>-runs.jsonl (last 30 entries).

Graphify, Beads, pstack, and structural-quality probes (knip, madge, jscn, pyscn, skylos) are optional add-ons that several skills touch — they're covered together in Integrations rather than repeated here.

Requirements

• Python 3.10+
• pipx recommended so forge lands on your PATH — see the pipx docs (on Windows: py -m pip install --user pipx, then pipx ensurepath)
• A project that's a git repo or has a README.md, so the launcher can find the root

Installation

1. Install the launcher once per machine:

pipx install forge-next

2. Install app integrations:

forge install

Or pick specific apps:

forge install --cursor
forge install --claude
forge install --codex

--cursor installs the Cursor plugin and bundles workflow skills into it directly. --codex installs skills under ~/.codex/skills/forge/. --claude installs commands under ~/.claude/commands/forge/ and wires up Graphify hooks. Useful flags: --ref, --repo-url, --cursor-dir, --claude-dir, --codex-dir.

forge install also copies allowlisted pstack skills, sets up structural-quality probes, and prints Graphify onboarding hints — see Integrations for what those do and how to skip them.

Running from Windows installs to Windows app locations; running from WSL installs to WSL locations.

3. First run, inside the app (not a terminal):

1. /forge:doctor (Cursor/Claude) or $forge:doctor (Codex) to check setup.
2. /forge:plan or $forge:plan to start.
3. Follow the printed steps and re-run the same command, or the next one the handoff suggests.

To upgrade later: pipx upgrade forge-next. To pin a version: pipx install 'forge-next==1.17.0'.

Commands in your apps

All 14 workflows are defined in integrations/spec/commands.json. In a terminal, invoke any of them as forge <subcommand> … (for example forge design --step 1); forge develop is a deprecated alias for forge design.

Quick index

Delivery pipeline

The default linear order — evaluate, diagnose, and ux-review can also run standalone:

forge takeover drives evaluate pre/post as quality gates rather than a fixed pipeline step — follow the last handoff menu when in doubt. Ship isn't a pipeline step either; it's a finalize utility that handoffs after implement, code-review, and test commonly suggest. If intent is fuzzy, start at sketch.

Plan discovery: evaluate (--plan), implement, and code-review search markdown plans in the repo and native IDE plan folders (.cursor/plans, .claude/plans, .codex/plans, and their home-directory equivalents).

Sketch

Organizes intent when the problem, constraints, or terminology are still fuzzy, asking one question at a time with a suggested answer. It records decisions rather than investigating solutions — that's design's job.

When to use: before design, when requirements aren't settled yet. Optional --with-domain-docs also updates CONTEXT.md and light ADRs.

Artifacts: memory/sketch-decisions.md (Destination / Decisions so far / Not yet specified / Out of scope).

Default handoff: design. Protocol: templates/sketch-protocol.md.

Design

Back-and-forth discovery: surface opportunities, brainstorm requirements, and score solution directions before anyone plans tasks.

When to use: after sketch (if you ran it), or whenever you have a defined problem to investigate. Read-only on the codebase unless you explicitly allow edits.

Artifacts: session memory; memory/design-scope.json; for medium/large scope, a named spec at docs/forge/specs/YYYY-MM-DD-<slug>-design.md with gates at steps 6–8 (those floors stay hard even at --ceremony light).

Notable flags: --ceremony light|medium|detailed|comprehensive (job; --quick maps to light); --auto1/--auto2/--auto3 for autonomy; step-8 bypasses --allow-spec-incomplete / --allow-issues-incomplete (each needs an override reason and a follow-up). Honor light as produce-and-stop.

Default handoff: plan (evaluate-pre is a common alternative). forge develop still works as a deprecated CLI alias, but there's no /forge:develop command.

Methodologies: evidence-first investigation, 5 Whys, systematic debugging, brainstorming gates, HMW framing, Pugh scoring, cross-review. Template: templates/design-spec.md.

Plan

Turns an approved direction into a concrete implementation plan: waves, tasks, and documentation sections.

Artifacts: plan file under memory/plans/; memory/planner.md.

Notable flags: --quick; --ceremony light|medium|detailed|comprehensive; --save-ceremony-preference. Light collapses the run to three steps (Frame+Orient → Act → Handoff); medium+ stays seven. Honor light as produce-and-stop.

Default handoff: evaluate --mode pre (implement is a common alternative).

Methodologies: architecture overview, INVEST-shaped tasks, parallelization map, risk register, pre-mortem.

Evaluate

Structured critique — --mode pre before implementation, --mode post after. For a full-team review, use code-review instead (--mode review is deprecated).

Artifacts: .evaluate-state.json and per-step findings sidecars.

Notable flags: --mode pre|post (orthogonal to ceremony); --ceremony light|medium|detailed|comprehensive. Honor light as produce-and-stop.

Default handoff: pre → implement; post → code-review.

Methodologies: feasibility ratings, completeness audit, correctness/quality/performance/operational-readiness lenses, optional team dispatch.

Implement

Executes the plan in waves, with a review loop after each task.

Artifacts: handoff-implement.md; documentation gate at step 8.

Notable flags: --plan <path>; --ceremony light|medium|detailed|comprehensive. Honor light as produce-and-stop (step count stays 8).

Default handoff: code-review.

Methodologies: branch setup, wave dispatch, per-task review loop (templates/review-loop.md), integration check, documentation gate.

Code review

Structured PR/diff/architecture review with two passes: Pass A checks the change against intent and requirements, Pass B checks engineering quality against templates/standards-review-baseline.md. Findings from each pass are reported separately.

Artifacts: memory/code-review-report.md.

Notable flags: --ceremony light|medium|detailed|comprehensive (job; honor light as produce-and-stop). --effort light|standard|thorough (or --quick for light) still sets reviewer fan-out: Architect + QA at light; standard adds Security when auth/data is in play; thorough is the full six-role team. Structural probes run by default and can hold steps 4–6 — --no-structural turns them off, --allow-structural-probes-incomplete bypasses a pending gate. See Integrations.

Default handoff: test (ship is a common alternative).

Test

Runs the test suite (default run mode), or authors mock flows with --mode flows.

Artifacts: memory/test-report.md; flows mode also updates the scenario index when it parses cleanly.

Notable flags: --mode run|flows (orthogonal to ceremony); --ceremony light|medium|detailed|comprehensive. Honor light as produce-and-stop.

Default handoff: ship when green, diagnose on failures.

Methodologies: discovery, execution, failure analysis, coverage gaps; flows mode adds eight quality criteria plus pytest reliability checks.

For a real-browser product audit, use ux-review — forge test --mode ux just redirects there.

UX review

Real-browser audit of a running web app. It maps purpose, users, IA, and journeys; walks reachable pages and controls (including empty/loading/error/success states across viewports); then writes a prioritized findings report.

When to use: usability audits of a live app — not a replacement for test suite runs or mock-flow authoring.

Artifacts: memory/ux-review-report.md plus session sidecars for orientation, plan, coverage, and findings.

Notable flags: --base-url; --quick.

Default handoff: ship, or diagnose when blocker/high findings remain.

Methodologies: templates/ux-review-criteria.md; full detail in skills/ux-review/SKILL.md.

Diagnose

Evidence-led root-cause analysis with gated JSON sidecars, for incidents, regressions, and flaky failures.

Notable flags: --ceremony light|medium|detailed|comprehensive. Honor light as produce-and-stop; high-severity technique gates stay hard.

Default handoff: design when the fix is classified large, plan when complex.

Methodologies: playbooks in templates/diagnose-execution-playbooks.md, 5 Whys, hypothesis register, technique coverage. Full detail: skills/diagnose/SKILL.md.

Takeover

Infers what's in flight from sessions, handoffs, design specs, and an optional --issue, then drives child skills (plan → evaluate pre → implement → evaluate post → code-review → test) until the work is ship-ready.

When to use: after an interruption, to run an epic autonomously, or to skip manually picking each skill.

CLI: --design <path>, --issue <n|url>, --goal <text>; --cleanup / --cleanup --force to remove stale state.

Full detail: skills/takeover/SKILL.md.

Status

Read-only dashboard of handoffs, active sessions, and the suggested next workflow. Detail: skills/status/SKILL.md.

Doctor

Checks installation, PATH, encoding, the .forge/ runtime root, and common misconfiguration. Run it right after installing, or first thing in a new repo.

Ship

Finalizes coding work: preflight, commit, push, PR, merge, publish. Not a pipeline step — you reach for it after implement, code-review, or test when you're ready to land changes.

forge ship --step 1 runs the Graphify preflight first (see Integrations), then the agent follows .cursor/skills/ship/SKILL.md for the actual commit/PR/merge/publish work. Running step 1 alone doesn't commit anything by itself.

Graphify

Refreshes the optional codebase knowledge graph, or installs/uninstalls the post-commit hook. See Integrations for what the graph is used for.

CLI-only helpers not exposed as slash commands: forge session close, forge structural-tools, forge structural-probes, forge codex-agents, forge claude-graphify, forge cursor-subagent-hooks.

Integrations

Optional add-ons. Core workflows work without them; when they're missing, Forge falls back to memory files and sequential IDs.

Graphify — codebase knowledge graph

Graphify indexes the repo into graphify-out/ (god nodes, communities) so agents can orient before grepping. Install the Graphify CLI (or set FORGE_GRAPHIFY_COMMAND), then forge graphify refresh. forge graphify install-hook refreshes after each commit.

• forge ship --step 1 refreshes and prints the GRAPHIFY banner.
• Other workflow steps may start a debounced background refresh when graphify-out/ already exists — non-blocking.
• Claude: hooks via forge claude-graphify. Codex: developer_instructions via forge codex-agents. Re-run after pipx upgrade forge-next.
• Add a repo-root .graphifyignore for .forge/, .codex/, .venv/, build output, and other dumps — Graphify ignores .gitignore.

Full guide: docs/graphify.md.

pstack — optional agent skills (poteto)

pstack is a Cursor marketplace plugin. forge install copies an allowlist of optional pstack skills from cursor/plugins by default (not the marketplace). Forge does not vendor these skill bodies into the forge-next source tree. Skip with --skip-pstack or FORGE_SKIP_PSTACK=1. Named Forge skills always win. If pstack is not installed, skip — Forge continues unchanged. Canonical map: templates/pstack-contract.md. Guide: docs/pstack.md. pstack is not a /forge: command.

Uncodixfy — optional UI skill (cyxzdev)

Uncodixfy blocks generic AI UI patterns. forge install copies the skill from git by default. Forge does not vendor the skill body. Skip with --skip-uncodixfy or FORGE_SKIP_UNCODIXFY=1. Re-run forge install to update; forge uninstall removes the copied dests. Named Forge skills always win. If Uncodixfy is not installed, skip. Canonical map: templates/uncodixfy-contract.md. Web galleries for design: templates/web-design-references.md. Guide: docs/uncodixfy.md. Uncodixfy is not a /forge: command; invoke /uncodixfy when present.

Beads — issue tracking

Beads (bd CLI) can sync epics, findings, tasks, and dependencies with Forge memory and handoffs. Without it, prompts use memory files and sequential IDs. Design records beads_available on startup; nothing hard-requires Beads.

forge install and forge doctor surface whether bd is on PATH (they do not install Beads). Guide: templates/beads-integration.md.

Structural probes — knip, madge, jscn, pyscn, skylos

forge install sets these up for code-review and evaluate (warns if install fails). Skip with forge install --skip-structural-tools or FORGE_SKIP_STRUCTURAL_TOOLS=1.

In code-review they're on by default and can hold steps 4–6. Use --no-structural to disable, or --allow-structural-probes-incomplete to bypass a pending gate with a reason.

Guide: docs/structural-quality.md.

Uninstallation

Integrations (Cursor / Claude / Codex):

forge uninstall

(or --cursor, --claude, --codex)

Launcher:

pipx uninstall forge-next

Project state (optional): forge takeover --cleanup, or delete .forge/ in that repo.

How skills work

1. Pick a command — /forge:…, $forge:…, or forge … in a terminal. In Cursor and Claude, that command must run forge <skill> --step 1 first, before any manual investigation.
2. Each run advances one step at a time; output is the prompt (and sometimes todos) for that step, plus where state landed.
3. Prompts reference roles — architect, planner, implementer, critic, QA, security, doc-writer. Hosts with sub-agents follow the dispatch pattern in templates/subagent-progress.md and close agents once their slice of work is done.
4. The last step prints a handoff menu; your next command matches whatever it recommends.
5. Where supported, --quick shortens the run.

Sessions and handoffs

New runs live under .forge/sessions/{id}/: a session.json, an optional handoff.md, and a sidecars/ folder for step artifacts. index.json tracks active sessions; finished or auto-closed ones move to sessions/_archive/. Sessions stay isolated but can collaborate through a shared memory/project.md. Full detail: docs/sessions.md.

A few things worth knowing:

• Every skill appends a short record to memory/<skill>-runs.jsonl on each run (last ~30 kept).
• state/resume-context.json and memory/forge-memory-synthesis.md refresh on every save, so forge status and new chats can pick up context quickly.
• Handoffs are consumed when the next skill starts (plan reads design's handoff, code-review reads implement's, and so on).
• forge session close <id> archives a session and rewrites the pointer at handoff-{skill}.md so it keeps resolving.
• forge takeover --cleanup removes stale sessions and legacy flat state files (dry-run unless you pass --force). Env: FORGE_SESSION_MAX_AGE_DAYS (default 7), FORGE_SKIP_SESSION_CLEANUP=1.
• Older flat-JSON state under .codex/forge*/state/ or .forge/state/ still works — step 1 of any skill migrates and archives it automatically.

OpenAI Codex

After forge install --codex, skills live under ~/.codex/skills/forge/<folder>/SKILL.md (folder names are hyphenated because : isn't valid in a path, but name: forge:<subcommand> is what Codex actually shows you). Invoke with $forge:…, /use <skill>, /skills, or implicit matching on the skill description.

Most skills run forge … under the hood via <invoke cmd="…"/>; $forge:ship instead follows the agent procedure in .cursor/skills/ship/SKILL.md.

forge install --codex also merges Graphify-first delegation rules into ~/.codex/config.toml's developer_instructions (source: forge_next/graphify_policy.py), so Codex reads GRAPH_REPORT.md before broad search and allows spawn_agent/close_agent without extra prompting. If you've customized developer_instructions yourself, run forge codex-agents --force after upgrading forge-next, then restart Codex.

Claude Code

After forge install --claude:

• Slash commands live under ~/.claude/commands/forge/ (/forge:plan, …).
• Skills install flat under ~/.claude/skills/ — using-forge (meta router) plus forge-plan, forge-implement, and the other workflow skills. Claude matches these on the skill description field (same mechanism as Superpowers), so asking to “plan” should route to Forge instead of freestyle or competing process skills.
• Graphify hooks merge into ~/.claude/settings.json via forge claude-graphify (session-start reminder, pre-tool-use context on search-like tools, prompt-submit check for forge: mentions).

Re-run forge install --claude (and forge claude-graphify after upgrading forge-next), then restart Claude Code so skills are picked up.

Cursor

After forge install --cursor, the plugin under ~/.cursor/plugins/local/forge/ bundles both slash commands and the workflow skill packs, so Agents can discover them without ~/.codex/skills. forge cursor-subagent-hooks sets up Task lifecycle and progress reminders (suppress with FORGE_SKIP_SUBAGENT_LIFECYCLE=1). The ship skill also lives in this source tree at .cursor/skills/ship/SKILL.md.

This repository vs PyPI

• forge-next on PyPI installs the terminal forge binary and bundled orchestrators.
• This repo is the source for prompts/, templates/, agents/, scripts/, and integrations/ (everything commands.json installs).
• skills/ holds most agent-facing SKILL.md files — ship, doctor, and graphify live under integrations//Codex skill packs instead. Edit prompts/ and templates/ at repo root; forge_next/assets/ mirrors them at release time.

Highlights since 1.0

(There was no 1.5 release — numbering jumped 1.4 to 1.6.)

PyPI: pypi.org/project/forge-next

Source: github.com/msderganc/forge

Advanced: terminal and CI

Outside the apps, call forge <subcommand> with a space — same engine as any slash command. forge --help lists all flags.

Common environment variables:

Full list: docs/environment.md. Declarative manifests: docs/declarative-skills.md. Ceremony: docs/ceremony.md.

Contributing

Orchestration lives in scripts/shared/ (skill_runner.py, orchestrator.py, skill_chain.py, session_store.py, ceremony.py) and scripts/takeover/. Migrated skills declare phases in skills/<skill>/manifest.yaml; the shared spine is templates/skill-process-spine.md. Keep AGENTS.md, docs/README.md, and skills/ aligned with actual behavior.

Line endings: LF only (.gitattributes, .editorconfig, .vscode/settings.json). Do not commit CRLF — Git will show every line as changed.

Versions: bump semver in pyproject.toml (and the Cursor plugin's plugin.json when that bundle changes) for anything that touches the PyPI package or editor integrations — patch for narrow fixes, minor for additive behavior, major for breaking contracts. See Versioning in AGENTS.md.

PyPI: if you bump project.version, build and upload the same release (python -m build, python -m twine check dist/*, python -m twine upload dist/*, or scripts/release/publish_pypi.sh) so pipx upgrade forge-next picks it up.

Integration bundles: after changing integrations/cursor-plugin/, integrations/claude/commands/, or integrations/codex/skills/, run pytest tests/test_integration_install_layout.py to check the layout against integrations/spec/commands.json.

Tests:

python -m pytest
python scripts/smoke.py