Agento Forge - Pollack AI Lab

What is Forge?

Agento Forge is how a developer builds and evolves agentic software: a six-phase methodology, plus a toolkit of Claude Code slash commands that scaffold and maintain the artifacts each phase produces. It answers a different question than the rest of this methodology section. The Improvement Flywheel is the control loop — how a working agent gets measured and steered once it exists. Forge is what happens before and around that loop: how the project comes into being, what artifacts it commits to, and who keeps it healthy afterwards.

Forge does not re-explain the control loop. RUN → MEASURE → DIAGNOSE → INTERVENE → VERIFY belongs to the Improvement Flywheel; Forge is the methodology that decides what gets built and hands the loop something worth measuring.

The Reading Contract

Forge is deliberately small at the point of use. The obligation is one sentence:

Read your project’s trio — VISION.md, DESIGN.md, ROADMAP.md — and the template for the phase you are in.

That is the whole contract. A session can execute a phase correctly having read only those four documents. Everything else in the corpus is reference — case law explaining why a rule is what it is. If acting correctly ever requires reading a concept page, that is treated as a defect: the rule has not been distilled into the template where the session meets it.

The Six Phases

Phase	Name	Purpose	Output
0	Vision	Define what to build and why	`VISION.md`
1	Research	Deep investigation of the problem space	Research corpus, reference implementations
2	Design	Technical specification and decisions	`DESIGN.md`, decision records
3	Roadmap	Break the design into implementable steps	`ROADMAP.md` with entry/exit criteria
4	Learning Loop	Iterative implementation with feedback	Working implementation + learnings
5	Documentation	User-facing docs and tutorials	`docs/`

Plus a phase-review template that gates the transition between stages. Two properties matter more than the phase names:

Evaluation is first-class. Judges and benchmarks are not a phase-5 afterthought; they are how phase 4 knows whether it moved.
Learnings are a primary artifact. A phase that produced working code and no recorded learning is half-finished.

Two Loops

        DISCOVERY LOOP (Phases 0-2)              EXECUTION PIPELINE (Phases 3-5)
        Iterate until stable                      Sequential after discovery stabilizes

     ┌──────────┐   ┌──────────┐   ┌──────────┐       ┌──────────┐   ┌──────────┐   ┌──────────┐
     │ Phase 0  │<─>│ Phase 1  │<─>│ Phase 2  │ ───>  │ Phase 3  │──>│ Phase 4  │──>│ Phase 5  │
     │ Vision   │   │ Research │   │ Design   │       │ Roadmap  │   │ Learning │   │   Docs   │
     └──────────┘   └──────────┘   └──────────┘       └──────────┘   │   Loop   │   └──────────┘
                                                                      └──────────┘
     <─> = Iterative refinement                       ──> = Sequential execution

The Discovery Loop iterates freely — research invalidates vision assumptions, design reveals knowledge gaps. You exit when vision, research, and design are consistent with each other. The Execution Pipeline is sequential — you commit to a roadmap, execute with feedback, and document the result. Going back to discovery from execution is allowed, but it is a decision, not a drift. The transition between them is the highest-leverage review point in the method.

Five Variants

The same six phases apply to five kinds of project. What differs is the feedback loop in phase 4:

Variant	Use when…	Phase 4 loop	Lifecycle
Eval-Agent	Building an autonomous agent evaluated by judges	Loss optimization	Finite — converges
Project	Building a library, service, or application	QA review	Finite — builds and ships
Research	Investigating a question or testing hypotheses	Vision ↔ research iteration	Finite — publishes
Steward	Keeping an existing project or domain healthy	Health monitoring	Ongoing
KB	Structuring a corpus for agent navigation	Navigation quality	Ongoing

The first three converge on a deliverable and complete. The last two do not — they are custodial.

How to Start

The methodology is executable. It ships as Claude Code slash commands that scaffold and maintain the artifacts, so the on-ramp is a command, not a document to imitate.

Bootstrap the trio

/forge-project walks you from nothing to a vision, a design, and a roadmap, with a QA review loop between them. For research, /forge-research starts at forage and vision instead. For an agent with judge-based evaluation, /forge-eval-agent scaffolds judges and benchmarks alongside the trio.

Build the knowledge layer

/forge-kb structures an existing pile of documents into a corpus an agent can navigate — routing tables, indexes, and a session bridge, validated against real questions. /forge-research-kb is the superset for corpora with named consumer projects. See Knowledge Base Design for what it builds and why.

Work the roadmap

/plan-to-roadmap converts an ad-hoc plan into roadmap steps with entry and exit criteria. /collect-status produces a timestamped status report. /kb-reindex runs freshness checks across federated knowledge bases.

Close the session, don't just stop

/prepare-handoff ends a session with a documentation currency pass and a work order for whoever picks it up next — human or agent. /prepare-kb-handoff is the knowledge-base equivalent. The handoff is an artifact, not a courtesy.

Hand the project to a steward

When the build phases are done but the project is not, /forge-steward-repo establishes ongoing custody. See The Steward Pattern below.

Beyond the commands, the repository carries 14 document templates, 25 named concepts, 9 practice guides, and 5 project variants. The commands are the interface; the corpus is what they are an interface to.

The Steward Pattern

The variants that converge produce something finished. Most software is not finished — it has users, dependencies that move, and a knowledge base that goes stale the moment nobody is accountable for it. That is what a Steward is for. A Steward is an agent that is continuously accountable for a project or domain — a persistent custodian rather than a one-shot executor. In the cognitive-altitude hierarchy it sits at Level 1: above task execution, below strategic planning, with a horizon measured in days and weeks.

Level	Role	Horizon
0	Task executor	Minutes
1	Steward	Days–weeks
2	Strategist	Weeks–months
3	Meta-architect	Months–years

It combines two roles that reinforce each other:

Curator — maintains the project’s knowledge base: updates entries as APIs and patterns change, cross-references related topics, prunes stale content, federates to other knowledge bases.
Developer — executes roadmap items, runs builds and tests, flags regressions, watches upstream for breaking changes.

Neither works alone. A curator without development context writes abstract documentation; a developer without curated knowledge repeats past mistakes.

Where a steward’s planning lives

The current model gives each stewarded project a separate repository, paired one-to-one with it, holding the project’s active planning authority — the same VISION.md / DESIGN.md / ROADMAP.md trio — plus an inbox for steward-to-steward obligations and an audit log. That separation is the point, and it is a privacy boundary rather than a filing preference: planning cannot live in a repository whose contents are world-readable. An earlier model that added stewardship inside the project has been retired for exactly that reason.

The steward-repository procedure is provisional by design — revised from observed failures rather than worked around. The bootstrap is deliberately staged into separately inspectable transitions with a validator between them, because a single opaque command must not create repositories, rewrite a project, migrate authority, and send mail without intermediate validation.

The Thesis

Knowledge + structured execution > model — what Forge is built to serve

Knowledge Base Design

JIT Retrieval, the two KB types, and what /forge-kb builds

Improvement Flywheel

The control loop Forge hands a project to

Your First Research Agent

Twenty minutes from a pile of papers to a research partner you can query

​What is Forge?

​The Reading Contract

​The Six Phases

​Two Loops

​Five Variants

​How to Start

​The Steward Pattern

​Where a steward’s planning lives

​Related

The Thesis

Knowledge Base Design

Improvement Flywheel

Your First Research Agent

What is Forge?

The Reading Contract

The Six Phases

Two Loops

Five Variants

How to Start

The Steward Pattern

Where a steward’s planning lives

Related