Align Claude Code — and opencode — to your org and its operational model.
forge is a generator, not a scaffolder. It interviews your organization — which tools you run, which process shape you're held to, and how your org actually works (how agents communicate, under what identity they act, what gates and autonomy govern them) — and emits a standalone, org-owned harness that makes agent-driven development behave like a member of your org.
Two levels, deliberately separate:
| Tier | What it is | Who owns it |
|---|---|---|
| forge (this repo) | The shared generator: adapters, method, operating-model facets, runtime templates | Everyone, upstream |
acme-forge (the emit) |
Your harness: your tools, your operating model, your compliance regime — baked in | Your org |
forge@Acme ≠ forge@Globex by design — same generator, different answers to the interview. Nobody forks forge. To upgrade, an org re-runs the generator over its .forge.org.yaml and re-emits.
The full v2 design lives in
docs/GENERATOR.md— the authoritative north star.
/forge:emit reads one .forge.org.yaml and emits either:
- A Claude Code plugin (
--target claude-code, the default) — skills + agents + hooks + a marketplace manifest, validated and ready to install. - An opencode configuration (
--target opencode) —opencode.json+agent/+command/+skill/+rubric/+node/+plugin/dispatch.js. The orchestrator's one primitive isdispatch({ agent, ticket, repo?, model?, variant?, task_id?, command? }): it launches only the workers the graph catalog declares, the ticket is the whole envelope, N calls per turn run in parallel,task_idcontinues the same worker, a worktree worker gets one git worktree per (repo, ticket), and the<run-closed>postback carries the worker's RESULT line.
The opencode artifact is back/forward compatible by construction. One emitted package runs unchanged on opencode 1.18.29+ and 2.x:
- the emitted plugins carry both host entrypoints — 2.x loads
setup(), 1.18.29+ loadsserver()— driving the same role allowlist, model policy and read-only boundary; - the rest of the layout (
agent/,command/,skill/,opencode.json) is natively understood by both hosts; 2.x translates the 1.xpermissionblock automatically (task→subagent,bash→shell); emitdetects the installed opencode and refuses hosts below the floor;- known 2.x gaps, documented in the emitted package:
instructionsentries are not loaded (itsAGENTS.mdcarries the same pointers) and the session-start toast nudge is 1.x-only until a 2.x TUI plugin ships.
- The org's pinned adapters (tracker / SCM / chat / CI) — chosen once at the org tier, not re-chosen per project.
- The operating model — rendered from the interview into a constitutional wiki chapter + machine-checkable permission blocks.
- The org brain seed — one durable wiki (operating model + accumulating tribal knowledge) with a project layer (
projects/<codename>/). - The graph catalog (
graphs:, ADR 0019) — named graphs, each its own worker agent (a bounded graph-agent that walks its nodes in one context and ends every run with one RESULT line — the build graph's worker isbuilder) or walked by the engineer's main thread (e.g. refine, with humangate:nodes). Node-sets, loop caps (max_visits) and host caps (maxTurns/steps) are data; emit refuses an uncapped loop, an unreachable node, a verb as a worker node skill, a worker named like a host built-in, and a leftover singlegraph:block. Seeexamples/graph-catalog.forge.org.yaml. - The verbs —
prime · intro · setup · inception · refine · execute · triage · wiki · handoff(renamable per org) as commands + the skills each command reads.triageemits only when a worker graph binds it.
- Generate —
/forge:emitinterviews the org and writes the standalone package, validated. - Distribute — publish the package internally (private registry, Git host, or vendored). Teams install it; agent-driven development across the org converges on one operating model, one set of role boundaries, one wiki schema.
- Re-generate to upgrade — when the generator improves upstream, re-run it over the existing config. It rebases your org's choices onto the newer generator. No fork to maintain, no drift.
/plugin marketplace add ktoulgaridis/forge
/plugin install forge@forge# 1. In the GENERATOR (this repo): emit your org's package
claude
> /forge:emit
# → interviews your org: tools, methodology, operating model, identity, gates
# → writes a standalone org-owned package, validated
# 2. Distribute the package internally, then inside it:
> /forge:new acme-platform-rebuild # opens a project subspace in the org brain
> /forge:doctor # verifies CLIs + MCPs + operating-model invariantsThe deterministic engine behind the command runs directly:
uv run --with pyyaml python lib/emit.py --config <.forge.org.yaml> --out <dir> \
[--target claude-code|opencode]forge is opinionated about how agents work together, unopinionated about which tools they use (the adapters) and how each org works (the operating model, read from the wiki at runtime):
- Karpathy schema — raw sources / wiki / schema, federated across an org-wide layer and per-project subspaces; code-as-truth holds at both.
- Graph-agents, not a cast — the emitted harness ships one agent per worker graph (
builderfor build,triagerfor triage) plus the optional read-onlyvalidatereviewer. Main-thread graphs (e.g. refine) run in the engineer's own session. - One orchestrator, one worker per task — the engineer's session dispatches one graph-agent per ready task; the worker reviews its own diff as a self-check node, the human merge gate + CI are the independent review, and the optional read-only reviewer may check a completed PR. The durable substrate (org brain + tracker + SCM) survives crashes.
- Wiki role templates —
/forge:newseeds a project wiki with six role pages (templates/wiki/roles/: orchestrator, architect, implementer, reviewer, wiki-maintainer, migration-analyst) and its ownprime/dispatch/wikiskills. These are wiki content for the project tier. The emitted harness does not run them as agents.
Full method: docs/METHOD.md · roles: docs/ROLES.md · sessions: docs/SESSIONS.md · usage: docs/USAGE.md.
| Layer | Shipped | Planned | Out of scope |
|---|---|---|---|
| Tracker | github · jira-acli · jira-mcp · jira-multi · jira-single · gitlab · linear | asana | Notion / ClickUp / Monday |
| SCM | github · gitlab | bitbucket | — |
| Chat | slack | teams | discord (a "maybe later") |
| CI | — | github-actions · gitlab-ci | circleci, jenkins |
| Cloud | informational only — forge doesn't provision | — | azure / aws / gcp provisioning |
Stay-in-scope adapters get full skill snippets + doctor checks + working examples. Out-of-scope adapters are not added speculatively. Adapter contract: docs/ADAPTERS.md.
v0.10.1 — early, opinionated, working but incomplete.
- ✅
/forge:emit— the generator entry point: interview → deterministic emit → validation, with a leak gate (zero generator identity in output) and fail-closed controls (a "read-only" role with a write-capable allow-list fails the emit, not the org) - ✅ Two emit targets from one config: Claude Code plugin + opencode configuration
- ✅ The graph catalog (
graphs:, ADR 0019): worker graphs (build →builder, triage → read-onlytriager) and main-thread graphs (refine, with human gates), linted fail-closed - ✅ A deterministic verify gate on the builder's PR create (
check: verify): the declared tests must pass at HEAD and fail with the change reverted; edited base tests are flaggedprotected-edited(a Claude Code PreToolUse hook; an opencode plugin guard) —docs/notes/verify-gate.md - ✅ Read-only code access for a read-only worker (
code: read): search + git history through a shell each host walls to the declared commands (opencode permission patterns + a plugin guard holding every call to one simple command; a Claude Code PreToolUse gate keyed on the worker's agent type) —docs/notes/read-only-code-surface.md - ✅ Emitted READMEs list exactly what the package ships; the opencode README leads with the org's Homebrew install when
opencode.distribution.homebrewis set - ✅ Back/forward-compatible opencode artifact (1.18.29+ and 2.x, one package) with host-version detection
- ✅ Method documented (METHOD / ROLES / SESSIONS / USAGE / ADAPTERS / BOOTSTRAP); project-wiki templates incl. the six role pages;
wiki lint --consolidate - ✅ Test suite: emit golden tests + behavioural tests for the emitted
dispatchtool on both host entrypoints
In implementation order:
- Org-brain templates — org-wiki schema + operating-model chapter + the
learningscapture contract with a context-isolated harvest. - Methodology bundles — Scrum, Kanban (default), RFC-first, and Formal-methods / V-model (must-have for regulated shops; USER-NEED → REQUIREMENT → SPEC → VERIFICATION → VALIDATION with traceability + audit gates; sub-variants for IEC 62304, DO-178C, ISO 26262). Composable with the operating model.
- CI adapters: github-actions, gitlab-ci — skill snippets + sample pipeline templates.
- examples/socwave.md — SocWave platform rebuild (gitlab.example.com + Azure)
MIT — see LICENSE.
See CONTRIBUTING.md for conventions (commits, versioning, releases) and the generator-vs-package boundary: improvements to the shared generator land here; an org tailoring its own package re-runs the generator instead.