agentforge-framework 0.2.0__tar.gz

agentforge_framework-0.2.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Yash Mhatre
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

agentforge_framework-0.2.0/PKG-INFO

@@ -0,0 +1,321 @@
+Metadata-Version: 2.4
+Name: agentforge-framework
+Version: 0.2.0
+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 files a GitHub issue carrying a frozen plan and the Roster of Roles that will execute it. `agentforge implement <n>` runs the 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
+
+The Workflow runtime now runs multiple 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
+
+Filed issue #12: https://github.com/acme/pipelines/issues/12
+  Roster: implementer (standard)
+  Interview: 2 question(s) answered
+
+Run it with:  agentforge implement 12
+
+$ 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. Security, the Reviewer, and the Architect need no such flag —
+auditing, reviewing, and designing are reading. All six Roles `CONTEXT.md` names
+now run. Plugins have landed, and with them the data-engineering ones: 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` is still to come. See
+[`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
+
+AgentForge publishes to no package index yet, so neither route below is
+`pip install agentforge-framework`. Both put the same `agentforge` command on
+your path.
+
+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**, to run AgentForge against your own repositories.
+Download the wheel attached to the
+[latest release](https://github.com/yashmhatre/AgentForge/releases/latest) and
+install the file you downloaded:
+
+```console
+$ pip install agentforge_framework-0.2.0-py3-none-any.whl
+$ agentforge --version
+agentforge 0.2.0
+```
+
+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]"
+```
+
+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.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `agentforge plan "<task>"` | Runs the Orchestrator at the `deep` tier and files an issue carrying the plan and roster. |
+| `agentforge implement <n>` | Reads Issue `<n>`, runs its Workflow on a branch, posts each Agent Result, and opens a draft PR. 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.
+
+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`.
+
+```yaml
+providers:
+  claude:
+    capability_tier: native
+  codex:
+    capability_tier: fragment
+
+gates:
+  tests:
+    suite: pytest
+```
+
+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.
+
+## Tests
+
+```console
+$ pip install -e ".[dev]"
+$ 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.