agentforge-framework 0.2.0__py3-none-any.whl

agentforge_framework/.claude-plugin/plugin.json

@@ -0,0 +1,4 @@
+{
+  "name": "agentforge",
+  "description": "Skills AgentForge delivers natively: its own, and the vendored bundle"
+}

agentforge_framework/__init__.py

@@ -0,0 +1,3 @@
+"""AgentForge — coordination of specialized software agents through reusable workflows."""
+
+__version__ = "0.2.0"

agentforge_framework/agents/__init__.py

@@ -0,0 +1,92 @@
+"""Built-in AgentForge Roles.
+
+A Role is a definition — a name, a default Model Tier, and standing instructions
+(CONTEXT.md). The tiers here are ADR-0004's default table; a user overrides them
+per Run on the command line, and per project in configuration once
+`agentforge init` exists.
+
+All six Roles CONTEXT.md names can run. The Architect is in no shipped Workflow
+even so — most Tasks do not need a design pass, and one at `deep` on every Run
+would be the most expensive default in the project.
+"""
+
+from __future__ import annotations
+
+from ..core.contracts import ModelTier, Role
+from .architect import ARCHITECT, Architect
+from .implementer import IMPLEMENTER, Implementer
+from .orchestrator import ORCHESTRATOR
+from .reviewer import REVIEWER, Reviewer
+from .security import SECURITY, Security
+from .tester import TESTER, Tester
+
+#: Roles that can actually run today.
+ROLES: dict[str, Role] = {
+    ORCHESTRATOR.name: ORCHESTRATOR,
+    ARCHITECT.name: ARCHITECT,
+    IMPLEMENTER.name: IMPLEMENTER,
+    TESTER.name: TESTER,
+    SECURITY.name: SECURITY,
+    REVIEWER.name: REVIEWER,
+}
+
+#: How to run each Role, keyed the same way. A runner takes a Provider and
+#: exposes `run(plan=, context=, cwd=, role=, tier=)`.
+#:
+#: This registry is why the Workflow runtime names no Role: it looks a runner up
+#: by the name the Workflow step declared. Adding a Role is an entry here and a
+#: line of YAML, never an edit to the engine. The Orchestrator is absent
+#: deliberately — it produces Issues rather than running inside a Workflow.
+RUNNERS: dict[str, type] = {
+    ARCHITECT.name: Architect,
+    IMPLEMENTER.name: Implementer,
+    TESTER.name: Tester,
+    SECURITY.name: Security,
+    REVIEWER.name: Reviewer,
+}
+
+#: The full cast from CONTEXT.md, with ADR-0004's default tiers. Every name here
+#: now has a runner, so the two sets are equal — the difference between them is
+#: what the Orchestrator uses to recognize a reasonable-but-unavailable choice
+#: and say so, and it is what makes naming a seventh Role's tier before writing
+#: its runner safe. The Architect was the last name to sit in the gap.
+KNOWN_TIERS: dict[str, ModelTier] = {
+    "orchestrator": ModelTier.DEEP,
+    "architect": ModelTier.DEEP,
+    "security": ModelTier.DEEP,
+    "reviewer": ModelTier.DEEP,
+    "implementer": ModelTier.STANDARD,
+    "tester": ModelTier.CHEAP,
+}
+
+
+class UnknownRole(LookupError):
+    """A Roster names a Role this version of AgentForge cannot run."""
+
+
+def resolve_role(name: str) -> Role:
+    """Look a Role up by name, for rebuilding a Roster out of an Issue body."""
+    key = name.strip().lower()
+    if key in ROLES:
+        return ROLES[key]
+    if key in KNOWN_TIERS:
+        raise UnknownRole(
+            f"the {key!r} Role is not implemented in this version of AgentForge; "
+            f"runnable Roles: {', '.join(sorted(ROLES))}"
+        )
+    raise UnknownRole(f"no Role named {name!r}; available: {', '.join(sorted(ROLES))}")
+
+
+__all__ = [
+    "ARCHITECT",
+    "IMPLEMENTER",
+    "KNOWN_TIERS",
+    "ORCHESTRATOR",
+    "REVIEWER",
+    "ROLES",
+    "RUNNERS",
+    "SECURITY",
+    "TESTER",
+    "UnknownRole",
+    "resolve_role",
+]

agentforge_framework/agents/architect.py

@@ -0,0 +1,146 @@
+"""The Architect: decides the shape of a change it will not make.
+
+It runs `deep` because a design error is the expensive kind. An Implementer's
+mistake is caught by a Tester; a boundary drawn in the wrong place is caught
+six months later by whoever has to work across it.
+
+It is in none of the three shipped Workflows, and that is deliberate: most
+Tasks do not need a design pass, and paying `deep` for one on every Run would
+be the most expensive default in the project. The Orchestrator selects it for
+Tasks that are design-heavy, and a project may name it in a Workflow of its own.
+
+What it does not do is plan. The Plan is frozen before any Agent runs
+(ADR-0003), and a Role that re-planned would be a second Orchestrator with none
+of the human's context. The Architect decides how the frozen Plan should be
+built, and escalates when it cannot be built as described.
+
+Know this before putting it in a Workflow: its design reaches the Run Log and
+not the next Role's prompt. Every Role is handed the frozen Plan and the Context
+Pack, and nothing today folds an earlier Step's result into a later Step's
+invocation. So an Architect Step informs the human reading the Issue, and an
+Implementer only through them. Closing that gap is a change to what a Context
+Pack carries rather than a change to this Role.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..context.prompt import render_context_block
+from ..core.contracts import AgentResult, ContextPack, ModelTier, Plan, Role
+from ..core.plan_format import RESULT_CLOSE, RESULT_OPEN
+from .implementer import render_steps
+
+INSTRUCTIONS = """\
+You are the Architect in AgentForge. The Plan below is frozen and you are not \
+rewriting it. Somebody decided what to build; you decide how it should be \
+shaped.
+
+Say where the seam goes: which module owns which decision, what the interface \
+between them is, and what must not leak across it. Name the approach you \
+rejected and why, because the next person to read this will otherwise rediscover \
+it as a good idea.
+
+Prefer the shape the repository already uses. A design that is better in the \
+abstract and unlike everything around it costs every reader afterwards.
+
+Write no code and change no files. What you produce is a decision, recorded on \
+the Issue for the human who reads it before the work is built.
+
+If the Plan cannot be built as described -- two steps require incompatible \
+designs, or a step assumes a structure the repository does not have -- escalate \
+rather than designing around it. That mismatch is the Orchestrator's to fix.\
+"""
+
+PROMPT = """\
+{instructions}
+
+## The frozen Plan
+
+{summary}
+
+### Steps
+
+{steps}
+{constraints}{context}
+## Working directory
+
+{cwd}
+
+Read the modules the Plan names and the code they reach into, so the design you \
+give back fits the repository rather than a description of it.
+
+## Required output
+
+End your reply with this block and nothing after it:
+
+{result_open}
+```json
+{{
+  "outcome": "completed",
+  "summary": "one line: the shape you chose",
+  "detail": "the design: the seam, the interfaces, what each module owns, and the approach you rejected",
+  "files_changed": []
+}}
+```
+{result_close}
+
+Use `"outcome": "escalated"` when the Plan cannot be built as written. Name the \
+step and the mismatch in `summary`.\
+"""
+
+#: The Architect runs `deep`: a boundary in the wrong place outlives the Run.
+ARCHITECT = Role(name="architect", tier=ModelTier.DEEP, instructions=INSTRUCTIONS)
+
+
+def build_prompt(
+    plan: Plan,
+    context: ContextPack,
+    cwd: Path,
+    role: Role = ARCHITECT,
+) -> str:
+    constraints = ""
+    if plan.constraints:
+        constraints = "\n### Constraints\n\n" + "\n".join(f"- {c}" for c in plan.constraints) + "\n"
+
+    return PROMPT.format(
+        instructions=role.instructions,
+        summary=plan.summary.strip(),
+        steps=render_steps(plan),
+        constraints=constraints,
+        context=render_context_block(context),
+        cwd=cwd,
+        result_open=RESULT_OPEN,
+        result_close=RESULT_CLOSE,
+    )
+
+
+class Architect:
+    """One Architect invocation through the shared Provider port.
+
+    No denial path: designing is reading, so ADR-0007's shut gate costs it
+    nothing.
+    """
+
+    def __init__(self, provider) -> None:
+        self.provider = provider
+
+    def run(
+        self,
+        *,
+        plan: Plan,
+        context: ContextPack,
+        cwd: Path,
+        role: Role = ARCHITECT,
+        tier: ModelTier | None = None,
+    ) -> AgentResult:
+        return self.provider.invoke(
+            role=role,
+            prompt=build_prompt(plan, context, cwd, role),
+            context=context,
+            tier=tier or role.tier,
+            cwd=cwd,
+        )
+
+
+__all__ = ["ARCHITECT", "INSTRUCTIONS", "Architect", "build_prompt"]

agentforge_framework/agents/implementer.py

@@ -0,0 +1,162 @@
+"""The Implementer: executes a Plan it did not write.
+
+It is handed the Plan and the Context Pack and never the human's original
+phrasing (ADR-0003). The pack is the reading already done for it, so that six
+Roles do not each rediscover one repository — but it is a head start rather than
+a boundary, and a step that needs a file the pack does not name is a step that
+reads it (ADR-0010). What the Implementer does not do is re-scope: it executes
+the Plan it was given and nothing adjacent to it.
+
+Its second job is to refuse. A plan written on Monday can be wrong by Thursday,
+and an Agent that improvises a correction produces confident wrong work that
+looks like success all the way to the pull request. So the prompt gives it an
+escalation path and the runtime treats escalation as a result rather than an
+error.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..context.prompt import render_context_block
+from ..core.contracts import AgentResult, ContextPack, ModelTier, Plan, Role
+from ..core.plan_format import RESULT_CLOSE, RESULT_OPEN
+
+INSTRUCTIONS = """\
+You are the Implementer in AgentForge. Another Role planned this work and is \
+not available to answer questions.
+
+Execute the plan below and nothing else. Do not re-scope it, do not add \
+improvements it did not ask for, and do not widen it because something nearby \
+looks wrong.
+
+If the plan does not match the repository -- a file it names is gone, a step \
+assumes something untrue, two steps contradict each other -- stop and escalate. \
+Do not guess at what was meant. A wrong plan caught now costs a comment; a \
+wrong plan improvised around costs a review.\
+"""
+
+PROMPT = """\
+{instructions}
+
+## Plan
+
+{summary}
+
+### Steps
+
+{steps}
+{constraints}{context}
+## Working directory
+
+{cwd}
+
+You are on a branch created for this work. Commit nothing; AgentForge commits \
+for you. It commits every file it already tracks that you changed, and a file it \
+does not yet track only if the plan above names it or your `files_changed` does. \
+List every new file you create there, or it will not reach the pull request.
+{execution}
+## Required output
+
+End your reply with this block and nothing after it:
+
+{result_open}
+```json
+{{
+  "outcome": "completed",
+  "summary": "one line stating what you changed",
+  "detail": "anything a reviewer needs to know",
+  "files_changed": ["path/one.py"]
+}}
+```
+{result_close}
+
+Use `"outcome": "escalated"` instead if the plan cannot be executed as written. \
+Put the specific mismatch in `summary` -- which step, and what the repository \
+actually contains. Change no files when you escalate.\
+"""
+
+#: The Implementer runs at `standard`: it executes a plan it did not write.
+IMPLEMENTER = Role(name="implementer", tier=ModelTier.STANDARD, instructions=INSTRUCTIONS)
+
+
+def render_steps(plan: Plan) -> str:
+    if not plan.steps:
+        return "_The plan carries no steps. Escalate rather than inventing them._"
+
+    lines = []
+    for index, step in enumerate(plan.steps, start=1):
+        lines.append(f"{index}. **{step.id}** — {step.intent}")
+        if step.files:
+            lines.append("   - Files: " + ", ".join(f"`{path}`" for path in step.files))
+        if step.acceptance:
+            lines.append(f"   - Done when: {step.acceptance}")
+    return "\n".join(lines)
+
+
+#: What a Role is told when ADR-0007's gate is shut. The posture itself lives in
+#: the argument vector; this is only what to do on hitting it. Without it the
+#: Agent does what the M1 acceptance run did -- trace the tests by hand and
+#: report `completed`, which is the one failure a Run cannot detect.
+DENIED_COMMANDS = """
+## Commands
+
+You cannot run commands in this Run. You may read and edit files, and nothing \
+else. If a step's acceptance criterion asks you to run something, do not \
+substitute reading for running: state in `detail` which criterion you could \
+not verify, and escalate if that leaves the step unfinished. Reporting \
+`completed` on a criterion you could not check is worse than stopping.
+"""
+
+
+def build_prompt(
+    plan: Plan,
+    context: ContextPack,
+    cwd: Path,
+    role: Role = IMPLEMENTER,
+    allow_commands: bool = False,
+) -> str:
+    constraints = ""
+    if plan.constraints:
+        constraints = "\n### Constraints\n\n" + "\n".join(f"- {c}" for c in plan.constraints) + "\n"
+
+    return PROMPT.format(
+        instructions=role.instructions,
+        summary=plan.summary.strip(),
+        steps=render_steps(plan),
+        constraints=constraints,
+        context=render_context_block(context),
+        cwd=cwd,
+        execution="" if allow_commands else DENIED_COMMANDS,
+        result_open=RESULT_OPEN,
+        result_close=RESULT_CLOSE,
+    )
+
+
+class Implementer:
+    """One Provider invocation against a frozen Plan."""
+
+    def __init__(self, provider) -> None:
+        self.provider = provider
+
+    def run(
+        self,
+        *,
+        plan: Plan,
+        context: ContextPack,
+        cwd: Path,
+        role: Role = IMPLEMENTER,
+        tier: ModelTier | None = None,
+    ) -> AgentResult:
+        tier = tier or role.tier
+        allow_commands = getattr(self.provider, "allow_commands", False)
+        return self.provider.invoke(
+            role=role,
+            prompt=build_prompt(plan, context, cwd, role, allow_commands=allow_commands),
+            context=context,
+            tier=tier,
+            cwd=cwd,
+        )
+
+
+__all__ = ["IMPLEMENTER", "INSTRUCTIONS", "Implementer", "build_prompt", "render_steps"]