AgentForge

AgentForge is a standalone Python framework for coordinating specialized software agents through reusable workflows.

A human states a Task. The Orchestrator grills them on it, writes a spec, cuts the spec into Slices, and files a GitHub issue for each -- every one carrying a frozen plan, the Roster of Roles that will execute it, and the issues that block it. agentforge implement <n> runs one Issue's Workflow and opens a draft pull request for a human to sign off. No workflow ever merges.

Status

A Workflow runs its Roles in order. The default feature Workflow invokes the Implementer, the Tester, Security, and then the Reviewer, posting each Agent Result to the Issue before starting the next Step.

$ agentforge plan "add a retry to the loader"

The Orchestrator has questions before it writes anything down.
Answer them, or press Enter on an empty line to plan with what it has.

  Which loader — the orders one, or the returns feed?
  > orders

  Retry on 5xx only, or timeouts too?
  > both, cap it at three attempts

This cuts into 1 Slice(s), each filed as its own issue:

  1. Add a bounded retry to the orders loader  [retry]
       Delivers: The orders loader retries a failed fetch up to three times.
       Blocked by: nothing -- can start immediately
       - A 5xx or a timeout is retried; a 4xx is not.

Blockers are filed first, and a Slice waits for the ones it names.

File these? [y/N] y

Interview: 2 question(s) answered

Filed issue #12: https://github.com/acme/pipelines/issues/12
  Add a bounded retry to the orders loader
  Roster: implementer (standard)

Start with:  agentforge implement 12

  Cost: $0.41

$ agentforge implement 12 --allow-commands
  [ok] implementer (standard) — Wrapped the fetch in a bounded retry.
  [ok] tester (cheap) — pytest: 24 passed.
  [ok] security (deep) — Audited the change; no findings.
  [ok] reviewer (deep) — The change matches the plan. unslop: clean on attempt 2.

Draft pull request: https://github.com/acme/pipelines/pull/13
AgentForge stops at Sign-off. A human merges.

The two commands can run on different machines. Nothing is shared between them but the issue number.

The interview happens while you are still at the keyboard, because ADR-0003 freezes the plan the moment it is filed. It is rounds of one-shot invocations rather than a conversation — the Provider port has no session — and it ends as soon as the Orchestrator has enough, or as soon as you press Enter on an empty line. With nothing interactive attached, there is no interview at all: a scheduled Run has nobody to ask, and blocking on an answer that will never arrive is worse than planning from what was typed.

A term you settle in the interview is recorded in the project's own CONTEXT.md so the same question is not asked next week. That leaves changes in your working tree; agentforge plan says which files, and they are yours to review and commit.

Opening that gate is also what makes a Run produce files nobody asked for: running a suite writes __pycache__, and possibly coverage data and a cache directory. AgentForge commits every change to a file git already tracks, and an untracked file only when the frozen plan or an agent's own result named it. Everything else stays in your working tree and is listed in the pull request under Left uncommitted, so a repository with no .gitignore still gets a diff that is only the work. AgentForge does not write a .gitignore for you. See ADR-0015.

Without --allow-commands, the Implementer remains default-deny and the Tester reports that it could not run the suite; it never substitutes reading tests and claims completion. That gate is held by the claude adapter. The codex CLI cannot hold it — codex exec discards its approval flag — so a denied Run on codex is refused before it starts rather than run under a guarantee nothing enforces (ADR-0007, amended). Security, the Reviewer, and the Architect need no such flag — auditing, reviewing, and designing are reading. All six Roles CONTEXT.md names run. Plugins carry the data-engineering conventions: a repository whose files import pyspark has its Roles told to write DataFrame expressions rather than RDDs, and a Databricks workspace gets Unity Catalog naming and the Delta MERGE idioms in the prompts that write code and the workspace's own posture in the one that audits it. A repository that matches neither hears neither. agentforge init inspects a repository and writes its .agentforge/config.yaml; the file is optional, and Project configuration below says what it holds. What is still to come is in docs/PLAN.md.

Before the first Role is invoked, AgentForge resolves a Context Pack from the frozen plan — the files it names, the symbols and imports inside them, the tables a query touches, the keys a config file sets — and hands the same pack to every Role, so six Agents do not each rediscover one repository. The pack is a head start rather than a boundary: a Role that needs a file it does not name reads that file. Every Run Log entry then ends with what that Step consumed, in whatever unit the Provider reports it — dollars from claude, tokens from codex, and "not reported" where a CLI says nothing, because a blank reads as free. The last comment carries the Run's total. To find out what the pack is worth on your own repository, run the same issue again with --no-context-pack and compare the two totals.

The Reviewer writes the prose a human reads at Sign-off, and that prose is scanned by the vendored unslop scanners before it is posted. The first draft is written with write-plainly in front of it — what the three scanners count, stated for a draft rather than as findings on one — because a rewrite reaches a phrase and one of the scanners reads the shape of the whole document. A finding sends the Reviewer its own findings to rewrite against, twice at most, and the skill is not delivered again there: a finding already names the phrase, the line, and a replacement. The scan is a Command and not a Gate: prose that still scans dirty on the third attempt is posted anyway with the report attached, because holding a finished Run on a cosmetic check trades a real cost for a stylistic one. The report reaches the Run Log either way.

Before 1.0 the stable surface is the Issue body: what AgentForge writes into an issue keeps parsing, so a Run filed by one version resumes under a later one. Everything importable under agentforge_framework.* is private and changes without notice. See ADR-0011.

Install

$ pip install agentforge-framework
$ agentforge --version
agentforge 0.2.6

That is the whole of it. The two routes below the naming note are for a machine that cannot reach PyPI, and for working on AgentForge itself.

The distribution is agentforge-framework and it imports as agentforge_framework, because an older and larger project holds agentforge on PyPI and imports under that name. Decorating both means the two can sit in one environment without either shadowing the other.

Installing puts two commands on your path, agentforge and agentforge-framework, and they are the same program. Use agentforge; the whole of this README does. Reach for the long one only if you also have that other project installed, because its 0.5.0 through 0.6.5 declare an agentforge command too and whichever was installed last wins. See ADR-0013.

From a release wheel, for a machine with no route to PyPI. Every release attaches the same wheel and sdist that were uploaded to the index; download one from the latest release and install the file:

$ pip install agentforge_framework-0.2.6-py3-none-any.whl

Publishing a release is a wizard rather than a checklist: bash scripts/publish-wizard.sh registers the Trusted Publishers on TestPyPI and PyPI, rehearses the whole upload path against TestPyPI, and stops before the one irreversible step. Whoever cuts the next release runs it instead of reading release.yml.

From a clone, to work on AgentForge itself. An editable install leaves the command pointing at the checkout, so an edit takes effect without reinstalling, and [dev] adds the pytest and ruff that CI runs:

$ git clone https://github.com/yashmhatre/AgentForge.git
$ cd AgentForge
$ pip install -e ".[dev]"

Step by step, with every command and flag: docs/GUIDE.md. What each release contains is in CHANGELOG.md.

Requirements

• Python 3.11 or newer
• git, and a repository with a GitHub remote
• The GitHub CLI, authenticated
• A coding-agent CLI. claude ships supported; codex exists to keep the provider port honest.

AgentForge never touches a model API and handles no credentials of its own. Whatever your coding-agent CLI is already authenticated with is what a Run costs.

Editors and IDEs

AgentForge is a terminal tool. It runs fine from an IDE's terminal, but the IDE is not a Provider and its assistant is not one either.

Antigravity IDE cannot be a Provider (#101). Checked by running it, so nobody has to derive it again: antigravity-ide chat accepts a prompt and reads stdin, which is the right shape for the argument vector — but it is a window launcher. Piping a prompt to it returns exit 0 immediately with Reading from stdin via: …\code-stdin-XXXX on stdout and nothing else, ever; the answer goes to a GUI session. A Provider adapter has to read the Agent's result off stdout, so there is nothing for parse_output to parse. The same is true of any editor CLI of this shape.

Do not run another agent against a checkout while a Run is going. A Run commits every change to a file git already tracks, however it got there (ADR-0015) — so a second agent's half-finished edits are committed into the Run's branch and attributed to a Role. Files nothing in the Run claimed are listed in the pull request body (ADR-0023), which makes it visible at Sign-off but does not prevent it. Use a separate clone. A second agentforge implement is refused outright rather than merely disclosed — a Run holds its checkout for the duration (ADR-0026) — but nothing else consults that lock, so an IDE assistant is still yours to keep away.

Commands

agentforge run writes into your working tree and commits nothing: review the diff and commit it yourself. It never replaces a file that is already there, and a Command that runs a process is bound by the same default-deny posture as everything else (ADR-0007) -- typing the command is the grant. Which Commands you have depends on which Plugins answer for the repository you are in, which outside a Run is what its root markers say: a dbt_project.yml gets you dbt chores. See ADR-0019.

Both agent commands take --provider and --tier. A bare --tier deep moves every Role; --tier implementer=deep moves one.

Either flag beats the issue. Without one, the tier beside a Role in the Roster table is the tier that Step runs at — the Orchestrator's judgement about how hard this particular Task is, frozen with the rest of the plan, so a resumed Run costs what the first invocation would have. A Role the Roster does not name runs at its declared default. See ADR-0014.

Workflows

Three ship. The Orchestrator picks one while it plans and names it in the Issue body, so a human reading the Issue knows which Roles are about to touch their repository and in what order — the Roster table is that Workflow's Roles. A project adds its own by dropping a definition beside them, and it becomes selectable too.

review is the only one with no Implementer. It ends at a draft pull request like the others, because the branch already carries the commits it was pointed at.

The Architect is in none of them. It runs deep, most Tasks do not need a design pass, and one on every Run would be the most expensive default in the project — so the Orchestrator selects it for design-heavy Tasks, and a project that always wants one names it in a Workflow of its own. Its design reaches the Run Log rather than the next Role's prompt, which is a limit of what a Context Pack carries today.

A step may declare a Gate that must clear before the next one starts. None of the shipped definitions do: a Gate suspends the Run until it clears, and a default Workflow that stops to wait on somebody is a choice a project makes rather than one it inherits.

Project configuration

agentforge init writes .agentforge/config.yaml for the repository you run it in. It reports what it found -- the languages git knows about, the Plugins your root markers answer for, the suite it detected and the evidence for it -- and writes the two things AgentForge reads. It refuses before creating anything if the repository has no GitHub remote, because ADR-0002 makes that a precondition for every Run. Re-running never clobbers a config you have edited: it reports what differs and writes nothing, and --force replaces it.

A Python suite is written pinned to the interpreter that will run it — [".venv/bin/python", "-m", "pytest"] rather than pytest — whenever the repository has a virtualenv to pin it to, and init checks that the interpreter can run pytest before writing the line. Bare pytest is whichever one PATH answers with, which in a project with a venv is the one the project does not use: the suite then fails on imports that are installed and reads as a broken repository rather than a misconfigured one. The interpreter is named relative to the repository root, so the file is still right on somebody else's clone, and init looks up to two directories down for the project — a suite that lives in subproject/tests/ is found, and named.

The file is not a precondition. Without one, the documented Provider capability defaults are Claude native and every other Provider fragment, and the tests Gate runs pytest — the case the pinning above exists to avoid, so a repository with a venv is better off with a file.

providers:
  claude:
    capability_tier: native
    # Optional. Overrides the adapter's own tier-to-model table; name only the
    # tiers you disagree about, and the rest keep the shipped defaults.
    models:
      deep: claude-opus-5
  codex:
    capability_tier: fragment

# Optional. A Role's two declared axes: which class of model runs it, and how
# hard that model thinks. Both default to the table in ADR-0004.
roles:
  security:
    tier: deep
    effort: max

gates:
  tests:
    suite: pytest

There is no roles.<name>.model key, and naming one is an error rather than a line that gets ignored. A Role declares a tier; the Provider maps that tier onto a model. A model named per Role does not survive the next CLI release and does not port to another Provider, which is what ADR-0004 exists to prevent -- override providers.<name>.models.<tier> if the mapping is what you disagree with.

There is no plugins: key. Which Plugins answer for a repository is decided per Run from the frozen plan's blast radius (ADR-0016), so a repository-level list would be inert and misleading -- init prints what it detected instead. The file holds what AgentForge reads and nothing else; see ADR-0020.

A Role declares the skills it needs. A native Provider receives them through its CLI's skill mechanism; a fragment Provider receives the same SKILL.md text appended to the prompt. Capability Tiers are configuration, never the result of probing an installed CLI.

Most skills are vendored third party (see skills/MANIFEST.yaml). Two are AgentForge's own. grill-with-docs is the interview and the writing-down as one job, built out of grilling and domain-modeling: a native Provider is named the composite and fans it out itself, and a fragment Provider gets the composite and both parts inlined, because it has no mechanism to fan out with. write-plainly composes nothing — it is derived from what the three unslop scanners enforce, since upstream keeps its own writing doctrine in a references/ tree this bundle does not vendor.

A Workflow step declaring gate: tests runs gates.tests.suite and holds the Run when it fails, posting the output to the Issue. The default is pytest. A string is split the way a shell would split it; a list is taken as written, which is how a path with a space in it gets named. The Gate runs the suite itself rather than believing what the Tester said about it, and it needs no --allow-commands: ADR-0007 governs what a Role may run, and this is the project's own declared suite rather than a command a model chose.

A suite that ran and failed suspends the Run — the commit that fixes it clears the Gate. A suite that could not be run at all halts the Run, because there is nothing there for a later Run to clear.

gate: security needs no configuration. It reads the Security Agent's Findings out of the Run Log: none of them clears it, and any of them suspends the Run and marks the Security Step to run again, so the audit that resumes reads the fixed code rather than the verdict about the old code.

Project layout

• core/ — the contracts, the command runner, the GitHub boundary, the plan format, and the run loop.
• agents/ — the Role definitions and their prompts.
• providers/ — one adapter per coding-agent CLI.
• workflows/ — the three shipped Workflow definitions.
• context/ — the Context Pack resolver and its per-language Extractors.
• plugins/ — one package per technology, contributing the conventions a repository is held to, the readers its files are read with, and the Gate kinds its Workflows can name; core/registry.py decides which are active for a Run.
• skills/ — vendored third-party skills. Never edited in place; see skills/MANIFEST.yaml.

Read CONTEXT.md before writing anything, and docs/adr/ for the decisions that constrain it.

Changing AgentForge

Clone it and install that clone editable. Never patch the installed copy.

$ git clone https://github.com/yashmhatre/AgentForge.git
$ cd AgentForge
$ pip install -e ".[dev]"

Editing site-packages/agentforge_framework/ appears to work and is the one change nothing will catch: the local install diverges from what ships, so the thing that works is not the thing anybody else gets, and the fix is lost the next time the package is upgraded. If a Run is failing badly enough that patching the install looks like the way forward, that is a bug worth filing — #101 is what happened the last time somebody reached for it.

Tests

$ pytest

The suite runs offline: no network, no GitHub account, and no coding-agent CLI installed. One fake command runner stands in for every external process.