ForgeKit
ForgeKit is a personal agent-operations forge — you wire up AI providers, equip
agents with the right skills for a job, run them under operator-gated runtime policy,
and keep every result in a durable memory. It is not another chatbot: it orchestrates
multiple providers, agents and tools to carry a real task to a bounded finish.
forge (a smithy — heat metal, hammer it to shape) + kit (a set of tools).
What ForgeKit is
ForgeKit is the platform (umbrella). Its engine lives in packages/*; the things under
apps/* are execution apps that share that engine — none of them is ForgeKit:
forgekit-console — the operator app: a Claude-Code-style TUI to configure the
brain, switch runtime modes, resolve work, and read honest status. It shows and operates;
it should not own platform core.engineering-agent (yule) — an always-on, role-based engineering runtime (Discord
gateway + member bots, SQLite job queue, Obsidian vault mirror).- plus
planning-agent · discord-gateway · memory-worker · loadtest-runner.
The ForgeKit core — runtime / provider / config / contracts / Hephaistos / Nexus /
Armory — lives in packages/* (extracted out of forgekit_console/; the console keeps
only the operator surface). Alongside the ForgeKit cores, packages/* also holds shared
infra (core / storage / integrations / vcs / security / llm-gateway / memory) used by the
engineering-agent family, plus some transitional agent packages. The full classification
(which package is platform core vs named core vs shared infra vs transitional, the naming
collisions, and where to add a new feature) is in
docs/package-topology.md; owner matrix + extraction roadmap in
docs/forgekit-architecture-ownership.md.
Everything is provider-neutral (Claude / Codex / Gemini / Ollama and any openai-compatible
or enterprise endpoint sit behind one contract) and operator-gated (approval / budget /
safe-class boundaries are real, not decorative).
Core concepts
| Concept | One line | Code |
|---|
| ForgeKit | the whole platform / execution environment | this repo |
| Hephaistos | the skill-forging core — turns a request into an equip plan (agent + skills + loadout + weapons + work packet) | forgekit_console/hephaistos/ |
| Nexus | the external knowledge source (areas / patterns / snippets / troubleshooting) Hephaistos reads (never copies) | read path: hephaistos/nexus_read.py |
| Armory | the catalog of Skills / Loadouts / Weapons Hephaistos forges from | packages/armory (armory.catalog / armory.models) |
| Work Packet | a structured, executable unit (goal / scope / forbidden / commands / verify / approval / evidence) | hephaistos/models.py |
| Runtime Mode | the operator posture (Shift+Tab) that actually changes routing / budget / approval | policy/runtime_mode.py |
Mine → library → smith: Nexus is the mine/library, ForgeKit is the forge, Hephaistos is the smith.
The Code column above is the current location (still inside forgekit_console/). These are
ForgeKit core, not console-private — the WT1–WT4 refactor moves their owner to
packages/{hephaistos,nexus,armory,forgekit-runtime,forgekit-provider,...}. See the
ownership matrix. Hephaistos/Nexus/Armory are cores,
not slash commands; the console only renders their projection.
Current reality (honest)
Status is one of working / partial / planned / blocked — see the matrices
in docs/operator-surfaces.md and docs/evidence-map.md.
