Metadata-Version: 2.4
Name: agentforge-framework
Version: 0.2.5
Summary: A modular framework for coordinating specialized software agents.
Author: Yash Mhatre
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/yashmhatre/AgentForge
Project-URL: Issues, https://github.com/yashmhatre/AgentForge/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: src/agentforge_framework/skills/NOTICE
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

# 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.

![An Issue carries the frozen plan and the Roster. Each Agent reads that Issue and appends its result as the Run Log. The Workflow ends at a draft pull request that only a human can merge.](docs/assets/one-issue-number.svg)

## 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.

```console
$ 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](#project-configuration) below says what it holds. What
is still to come is in [`docs/PLAN.md`](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](docs/adr/0011-the-issue-body-is-the-stable-surface.md).

## Install

```console
$ pip install agentforge-framework
$ agentforge --version
agentforge 0.2.5
```

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](docs/adr/0013-the-name-stays-the-import-path-moves.md).

**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](https://github.com/yashmhatre/AgentForge/releases/latest)
and install the file:

```console
$ pip install agentforge_framework-0.2.5-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:

```console
$ 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](docs/GUIDE.md).
What each release contains is in [CHANGELOG.md](CHANGELOG.md).

## Requirements

- Python 3.11 or newer
- `git`, and a repository with a GitHub remote
- The [GitHub CLI](https://cli.github.com), 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](https://github.com/yashmhatre/AgentForge/issues/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](docs/adr/0015-a-run-commits-what-it-declared.md)) — 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](docs/adr/0023-a-commit-names-what-nothing-claimed.md)), 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](docs/adr/0026-a-run-holds-the-checkout-it-was-pointed-at.md)) — but nothing else consults that lock, so an IDE assistant is still yours to keep away.

## Commands

| Command | What it does |
| --- | --- |
| `agentforge plan "<task>"` | Grills you on the task, writes a spec, cuts it into Slices, and files one issue per Slice carrying the plan, the roster, and the issues that block it. Add `--yes` to file without reviewing the cut. |
| `agentforge decompose <path>` | The same pipeline over a plan document you already wrote. Use it when the plan is longer than a sentence and already lives in the repository. |
| `agentforge implement <n>` | Reads Issue `<n>`, runs its Workflow on a branch, posts each Agent Result, and opens a draft PR. Refuses to start while an issue it declares as a blocker has not signed off; `--ignore-blockers` overrides. Add `--allow-commands` when the Workflow must execute a suite. |
| `agentforge run [<command> args]` | Runs a chore a Plugin contributes -- `agentforge run scaffold-dbt-model orders` writes the files and exits. With no command name it lists what this repository has. No issue, no Run, no model involved. |
| `agentforge unslop <file>` | Scans prose for machine-writing tells. Deterministic; no model involved. |

`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](docs/adr/0019-a-command-runs-outside-a-run-and-decides-nothing.md).

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.

| Workflow | Steps | For |
| --- | --- | --- |
| `feature` | implementer, tester, security, reviewer | The default: build something that was not there before. |
| `bugfix` | implementer, tester, reviewer | A fix, verified and reported on. A bug that touches auth is a Task for `feature`. |
| `review` | security, reviewer | A diff AgentForge did not write. Point it at a branch somebody else wrote. |

`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.

```yaml
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](docs/adr/0004-model-tiers-declared-not-named.md) 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](docs/adr/0020-the-config-file-holds-only-what-is-read.md).

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`](CONTEXT.md) before writing anything, and [`docs/adr/`](docs/adr/) for the decisions that constrain it.

## Changing AgentForge

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

```console
$ 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](https://github.com/yashmhatre/AgentForge/issues/101) is what happened the last time somebody reached for it.

## Tests

```console
$ 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.
