{ "markdown": "# GE Agent Factory\n\n**An agent is a contract with the external world.** It reads your systems,\nacts on your data, and speaks to your users — so it should be built from a\ncontract, proven with evidence, and admitted to production by policy through\na repeatable engineering process.\n\nGE Agent Factory builds agents exactly that way. A user interview, a BRD,\nor a PRD becomes a canonical spec — an Enterprise Agent Contract, captured\nin [OKF](docs/reference/okf.md), Google Cloud's Open Knowledge Format:\nplain Markdown, portable, vendor-agnostic. The spec generates the agent's\ncode, evals, synthetic data, and simulated source systems; the evidence is\nsealed into a signed Agent Passport; and an admission gate verifies that\npassport before the agent ships to\n[agents-cli](https://google.github.io/agents-cli/), ADK Agent Engine, and\nGemini Enterprise. The factory does not replace those tools — it produces\nthe contract and proof they need.\n\n## Start with one local proof\n\nInstall directly from this GitHub repository — no npm package or registry\nlookup is involved:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/vamsiramakrishnan/ge-agent-factory/main/packages/create-ge-agent-factory/bin/create-ge-agent-factory.mjs \\\n | bun - -- --yes --skills agents\n```\n\nThe installer clones or reuses the repository, sets up the toolchain, exposes\nthe agent skills, and runs the first local proof. From an existing checkout,\nuse the shorter path:\n\n```bash\nmise run setup\nge prove\nmise run console\n```\n\nCloud credentials are only needed when you run `ge handoff agents-cli`.\n\n[![Open in Cloud Shell](https://gstatic.com/cloudssh/images/open-btn.svg)](https://shell.cloud.google.com/?cloudshell_git_repo=https://github.com/vamsiramakrishnan/ge-agent-factory&cloudshell_workspace=installer&cloudshell_tutorial=installer/TUTORIAL.md)\n\n

\n \"Flow\n

\n\n## Why generate agents from a spec\n\nHand-writing an agent from a business requirements document works for one\ndemo, because one person can hold the whole intent in their head while\nwiring up prompts and tool calls. It stops working at the second agent:\nthe promises end up scattered across prompts, tool definitions, mocks, and\ntest notebooks, and the evidence that any of it holds lives nowhere — it\nmight behave, but nothing can prove it will. Skipping the document and\nwriting straight from judgment calls is worse, not better: there's no\nrequirement left to check the agent against, so nothing catches it\ndrifting from what the business asked for until a user does.\n\nSpec-driven development is not a new idea. What is new is the spec itself:\none canonical Enterprise Agent Contract, captured in\n[OKF](docs/reference/okf.md) — the Open Knowledge Format from Google Cloud.\nOKF is plain Markdown with structured frontmatter: portable,\nvendor-agnostic, readable by a business owner, and compilable by the\nfactory. That one spec drives every artifact downstream — machine-verifiable\nbusiness logic, evals, synthetic data, and simulated third-party SaaS\nsystems — and every stage after capture is checked against that same\ncontract, not just generated from it once and left to drift:\n\n1. **Capture** — start from a user interview or an existing BRD; the\n factory compiles it into a contract.\n2. **Generate** — the contract generates the agent's ADK code and tools; a\n spec-to-code trace checks the result against the contract's tool intents.\n3. **Evaluate** — the contract and the generated code produce the eval\n suite, in agents-cli's own eval format, scored against the contract's\n success criteria.\n4. **Simulate** — the contract's declared source systems become simulated\n third-party SaaS backends, seeded with synthetic data, so every tool\n call is exercised against them before any production integration exists.\n5. **Admit** — the evidence from every checked stage is sealed into a\n signed Agent Passport, and an admission gate — a required prerequisite,\n not a suggestion — verifies it before the agent ships through agents-cli\n to ADK Agent Engine.\n6. **Run** — the deployed agent is published to Gemini Enterprise, where\n your business users talk to it.\n\nThe passport carries standard in-toto attestations, so admission\ncontrollers you may already run — sigstore policy-controller, Kyverno,\nBinary Authorization — can verify the same evidence downstream.\n\nOn the command line, that path is three verbs:\n\n```bash\nge capture # interview or BRD → Enterprise Agent Contract\nge prove # contract → code, evals, data, simulations → a validated workspace\nge handoff agents-cli # proven workspace → Agent Engine → Gemini Enterprise\n```\n\n`ge capture` opens the conversational Interview in your browser;\n`ge capture --from ` registers a contract you already\nhave. At any point, bare `ge` (or `ge status`) reports where you are on the\npath, what blocks you, and the exact next command. A capture flow that\nlives entirely in the terminal is on the\n[roadmap](#roadmap-the-golden-path).\n\nDeciding whether you need this layer at all? Read\n[GE Agent Factory vs agents-cli](https://vamsiramakrishnan.github.io/ge-agent-factory/start/vs-agents-cli/).\n\n## Works with your coding agent\n\n

\n \"Claude \n \"Antigravity\" \n \"Codex\" \n \"Gemini \n \"MCP\"\n

\n\nEvery factory job ships as an agent skill — including the install itself\n([`installing-the-factory`](skills/installing-the-factory/SKILL.md)) — so a\ncoding agent can set up a bare machine, verify each step, and operate the\nfactory end to end:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/vamsiramakrishnan/ge-agent-factory/main/packages/create-ge-agent-factory/bin/create-ge-agent-factory.mjs \\\n | bun - -- --yes --skills agents # GitHub-backed clone + guided, verified install\n```\n\n| Agent | Install |\n| --- | --- |\n| **Claude Code** | `/plugin marketplace add vamsiramakrishnan/ge-agent-factory` then `/plugin install factory-bootstrap@ge-agent-factory` |\n| **Gemini CLI** | `gemini extensions install https://github.com/vamsiramakrishnan/ge-agent-factory` |\n| **Antigravity · Codex · agents-cli-style sessions** | `curl -fsSL https://raw.githubusercontent.com/vamsiramakrishnan/ge-agent-factory/main/packages/create-ge-agent-factory/bin/create-ge-agent-factory.mjs \\| bun - -- --yes --skills agents` (in a checkout: `mise run skills-install`) |\n| **Any MCP client** | `bun tools/mcp-server.mjs` — the `factory_*` tools, same functions as the CLI verbs |\n\nGenerated workspaces still hand off to [Google agents-cli](https://google.github.io/agents-cli/) / ADK / Gemini Enterprise; skills automate the setup and operations layer above that handoff.\n\n## See it\n\n\n\n\n\n\n\n\n\n\n
\n\"Console\n
\nOverview. Where every agent sits between capture and handoff, and what to do next.\n		\n
\nPipeline. The build & deploy flow for one spec or a batch — same stages the CLI runs.\n\"Console\n
\n
\n\"Agent\n
\nAgent detail. Every stage's evidence in one place, down to the exact command to ship it.\n		\n\"Repair\n
\nRepair Queue. Triage what's blocked across every agent at once instead of re-running everything.\n
\n\n

\n \"The\n
\n The full catalog — 363 agents across five departments — laid out as a periodic table. One tile per agent, click to explore.\n

\n\nThe CLI, recorded from real runs:\n\n\n\n\n\n\n\n
\n\"Terminal\n
\nge — status board with the next step.\n		\n\"Terminal\n
\nge init — discovers config, writes .ge.json.\n		\n\"Terminal\n
\nge doctor — every layer of the platform checked, one command.\n
\n\n## Do this at scale\n\nThe same contract, generated code, checked evals, and simulated systems\nexist today for 363 horizontal agents across HR, Finance, IT, Marketing,\nand Procurement, plus 150 industry-vertical agents across retail, banking,\ninsurance, telco, and manufacturing. Browse the canonical spec and\ngenerated source for any of them, laid out as a periodic table — one tile\nper agent, click through to its Enterprise Agent Contract and code:\n\n| | |\n|---|---|\n| **[Horizontal catalog](https://vamsiramakrishnan.github.io/ge-agent-factory/catalog/)** | 363 shared-services agents across five departments |\n| **[Vertical catalog](https://vamsiramakrishnan.github.io/ge-agent-factory/catalog-verticals/)** | 150 industry agents across five verticals |\n| **[Catalog explorer](https://vamsiramakrishnan.github.io/ge-agent-factory/catalog/explorer/)** | both halves together, filterable by industry, function, and value stream |\n\nNone of it is hand-maintained: the catalog is generated from the same\ndrift-gated registry the factory itself builds from\n(`apps/factory/src/agent-spec-registry.generated.json`), so it can never\ndrift from the specs it's showing.\n\n## Quickstart\n\nNo cloud credentials required until the handoff step; ~10 minutes end to\nend:\n\n```bash\ncurl https://mise.run | sh # once, if you don't have mise — see SETUP.md\nmise run setup # toolchain + the `ge` CLI on PATH (~5-10 min, one time)\nge init # discover config, write .ge.json (~30 s)\nge capture # capture a contract in the console Interview — or skip: prove starts from a built-in starter contract\nge prove # build + evals → one validated agent workspace (~5 min, all local)\nge handoff agents-cli # when ready: deploy proven agents to your own Google Cloud project\n```\n\nThe result on disk after `ge prove` is the whole layer in miniature: the\ncontract (`usecase-spec.json` with its `behaviorContract`), generated ADK\ncode and tools, synthetic fixture data, smoke tests, an eval suite in\n`agents-cli`'s own format, and the artifacts the promotion gate reads.\nEverything before handoff is pure local computation, so it is safe to\nrepeat; `ge prove --watch` re-proves automatically whenever a contract\nchanges.\n\n
\nUnder the hood: what each verb runs\n\n| Golden-path verb | What it runs today |\n|---|---|\n| `ge capture` | opens the console **Interview** at `http://localhost:18260/#/interview` (starting the console if needed) — conversational capture, document grounding, contract editing. `ge capture --from ` registers an already-captured contract with the catalog. |\n| `ge prove` | fresh machine → health check + one validated canary workspace; workspaces already built → `ge agents build` rebuilds their proof (evals + spec-to-code trace + harness verdicts + promotion gate). `--watch` re-proves on contract change. |\n| `ge handoff agents-cli` | hands locally proven workspaces to the cloud — `load_data` → deploy via `agents-cli deploy` → Agent Engine → register tools → publish to Gemini Enterprise. |\n\nThe machinery each verb drives is first-class and directly operable too —\nsee [Operate](#operate).\n
\n\n**→ Full setup path: [`SETUP.md`](SETUP.md). Ten-minute tutorial:\n[contract to handoff](https://vamsiramakrishnan.github.io/ge-agent-factory/start/quickstart/).**\n\n## How it fits\n\n

\n \"GE\n

\n\n| Layer | Owned by |\n|---|---|\n| Intent → contract → simulations → evals → proof | **GE Agent Factory** (this repo) |\n| Agent project scaffold, build, deploy | **agents-cli / ADK** (generated and driven by the factory) |\n| Runtime | **ADK Agent Engine** |\n| End-user surface | **Gemini Enterprise** |\n\nEverything up to *proof* is pure computation on your machine; everything\nafter touches your Google Cloud project. Building on this machine is the\ndefault — billable cloud work is opt-in — and `ge handoff` bridges the two\nsides by handing a locally proven workspace to the cloud for the release\nstages only. (The switch that selects the side, and the rest of the\nmachinery, live under [Operate](#operate).)\n\n

\n \"Author\n

\n\n## Documentation\n\nPublished docs site (search, sidebar, light and dark themes):\n**→ https://vamsiramakrishnan.github.io/ge-agent-factory/**\n\n| | |\n|---|---|\n| **[Start Here](https://vamsiramakrishnan.github.io/ge-agent-factory/start/what-is-the-factory/)** | What the factory is, the mental model, the ten-minute tutorial, vs agents-cli. |\n| **[Core Concepts](https://vamsiramakrishnan.github.io/ge-agent-factory/concepts/)** | The Enterprise Agent Contract, the Authority Graph, source-system twins, evals as proof, the passport & proof pack, handoff targets. |\n| **[Guides](https://vamsiramakrishnan.github.io/ge-agent-factory/cookbooks/)** | Capture → compile → simulate → prove → hand off, task by task. |\n| **[Console](https://vamsiramakrishnan.github.io/ge-agent-factory/console/)** | The operator UI, view by view. |\n| **[Operations](https://vamsiramakrishnan.github.io/ge-agent-factory/operations/)** | Provision, run, observe, troubleshoot. |\n| **[Reference](https://vamsiramakrishnan.github.io/ge-agent-factory/reference/)** | CLI (generated from the command tree), contract schema (generated from the zod source), console APIs, config, architecture. |\n| **[Contributor Docs](https://vamsiramakrishnan.github.io/ge-agent-factory/contributing/)** | Developer guide, extending the CLI/console, docs rules. |\n\nThe site is sourced from [`docs/`](docs/) (start at [`docs/index.md`](docs/index.md)).\nUnfamiliar term? The [Glossary](docs/GLOSSARY.md) translates every internal\nterm into plain language — the operator vocabulary included.\n\n## Roadmap: the golden path\n\nAll three verbs are working commands today. Two pieces remain ahead:\n\n- **CLI-native capture** — a conversational capture flow in the terminal\n itself; today `ge capture` opens the console Interview.\n- **Additional handoff targets** — `agents-cli` (→ Agent Engine → Gemini\n Enterprise) is the one supported target today.\n\n## Operate\n\nEverything below this line is the machinery behind the three verbs, in the\noperator register — planes, modes, canary, harness, and fleet, each defined\nin the [Glossary](docs/GLOSSARY.md).\n\nThe golden path, one lever at a time:\n\n```bash\nge prove # compile + prove one canary agent workspace (~5 min): health check → build → validate\nge mode local\nge agents build --canary # compile one contract → validated workspace (build boundary)\nmise run console # watch runs live in the operator console → http://localhost:18260\nge handoff agents-cli # hand off: cloud runs load_data → deploy → register → publish\n```\n\nThe mode switch (`ge mode local|remote`, default **local** — billable work\nis opt-in) selects which side of the build boundary does the work;\n`ge handoff agents-cli` bridges them by handing a locally proven workspace\nto the cloud for the release stages only.\n\n## Deploy the platform to your own GCP project\n\nSingle-tenant, ~15 min: click **Open in Cloud Shell** above for the guided\ninstaller ([`installer/TUTORIAL.md`](installer/TUTORIAL.md)), or from an\nauthenticated checkout:\n\n```bash\nexport GEMINI_ENTERPRISE_APP_ID=projects//locations/global/collections/default_collection/engines/\nCANARY=1 mise run bootstrap-cloud # toolchain → ge init → ge up (all three planes) → prove one agent\n```\n\n## Monorepo layout\n\nA Bun workspace monorepo driven by one operator core\n(`tools/lib/factory-core.mjs`) behind three surfaces — the `ge` CLI, the web\nconsole, and an MCP server — that share a single command registry and can\nnever disagree. Full layout, conventions, and how to run one app locally:\n[`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n| Path | What it is |\n|------|------------|\n| [`apps/console`](apps/console) | The operator UI: Overview · Pipeline · Interview · Fleet · Repair Queue · Runs · Readiness, plus Agent detail. |\n| [`apps/factory`](apps/factory) | The generator: compiles contracts into workspaces, the simulator runtime, the multi-tenant FastMCP service. |\n| [`apps/presentation`](apps/presentation) | The transformation deck and source use-case catalog — including the periodic table above. |\n| [`apps/docs`](apps/docs) | The Astro/Starlight docs site (content sourced from `docs/`). |\n| [`tools/`](tools) | The `ge` CLI, the MCP server, the shared operator core + local runtime daemon. |\n| [`packages/`](packages) | Shared contracts and engines: the agent-spec schema, the run ledger, OKF, design tokens, plus the extracted `@ge/synthkit` (deterministic synthetic data) and `@ge/evalkit` (behavioral eval compiler + metrics) engines — see [`packages/README.md`](packages/README.md). |\n\nThe map from station skill → capability → `ge` commands → engine package →\nreference docs is the\n[factory-line matrix](skills/README.md#the-factory-line-matrix) in\n`skills/README.md` — generated from source and drift-gated in CI, like the\nCLI reference.\n\n## The `ge` CLI\n\nBare `ge` prints a status board with the next step; `ge --help` groups the\ngolden path first. Every command supports `--json` and is also an HTTP route\n(console) and an MCP tool — one registry, three surfaces.\n\n```bash\nge # status board: mode · planes ✓/○ · next step\nge capture # golden path: capture a contract (console Interview; --from registers a file)\nge prove # golden path: prove contracts → validated workspaces (--watch to loop)\nge handoff agents-cli # golden path: ship proven agents to Agent Engine / Gemini Enterprise\nge init # discover config → .ge.json\nge devex check # fast read-only gate: doctor + docs + workspace contracts\nge agents build --canary\nge handoff agents-cli --ids \nge agents status --watch\nge pipeline run --scenario # orchestrate the end-to-end pipeline\nge fleet status # fleet convergence; ge fleet repair --ids fixes blockers in bulk\nge runs list # every recorded run; ge runs events --follow streams one live\nge doctor # health with runnable fixes (console: Readiness)\n```\n\nFull reference (generated from the command tree, drift-gated in CI):\n[CLI reference](https://vamsiramakrishnan.github.io/ge-agent-factory/reference/cli/).\n\n## Contributing\n\n```bash\nbun install # workspace deps\nmise run devex-check # fast local gate\nmise run ci # the CI gate: hygiene + lint + typecheck + docs gate + tests\n```\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md), the\n[Contributor Docs](https://vamsiramakrishnan.github.io/ge-agent-factory/contributing/),\nand [`docs/OPERATIONS.md`](docs/OPERATIONS.md) for the operator runbook.\n", "bytes": 21443, "sha": "b07574f06342d8a1d2c44982c4914464b1679357a875e63a76b2c1788e125936", "repo_slug": "vamsiramakrishnan/ge-agent-factory", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/okf_vamsiramakrishnan_ge_agent_factory_okf_s_45bea4fc/readme" }