Hephaestus
A coding abstraction layer forged in fire. Hephaestus orchestrates specialized agents — each purpose-built, model-aware, and disposable — to turn intent into infrastructure. The framework is the shim. The agents are the hands. The forge never cools.
Design Principles
Hephaestus exists because coding agents are disposable shims over durable infrastructure. The framework you use today will be deprecated tomorrow — but the patterns of orchestration, the discipline of isolation, and the philosophy of how agents should serve a human operator endure.
Every agent in the forge has a role, a model budget, and a leash. None of them are general-purpose. Generality is a tax on precision. The forge builds specialists, wires them into workflows, and keeps a human hand on the bellows.
No agent definition is precious. Models change, capabilities shift, costs fluctuate. The roster is a living document — agents get promoted, deprecated, and replaced without ceremony. The forge endures; the tools do not.
A reviewer should not build. A scout should not architect. Each agent carries a system prompt tuned to its role, a model matched to its cognitive load, and constraints that prevent scope creep. Sharp tools cut clean.
Autonomy is granted in degrees, not absolutes. Every agent operates under supervision — some on a long leash, some on a short one. The forge is not a democracy. The smith decides when to quench.
Every token has a price. Agents are assigned to model tiers based on the complexity of their task, not the prestige of the model. A scout on Haiku is not lesser than an architect on Opus — it is correctly sized.
Agent Roster
The default. Quick questions, simple edits, chat, exploration. Cheap, fast, and stronger than it looks. Can delegate to scouts, Dev, Hammer, Ember, and debugger. Does not pre-screen tasks — starts working immediately.
Direction & Discovery
The foreman. Decomposes tasks, delegates to specialists, tracks progress, and synthesizes results. Handles work that needs multiple agents but not frontier-level tradeoff reasoning; hard decisions escalate to Powerhouse. Does not write code.
The escalation path. Opus 5 handles genuinely hard tradeoffs, complex decompositions where the right split is not obvious, and conflicting agent results. The most expensive agent in the forge is invoked deliberately, then hands routine work back to @lead once the hard decisions are made.
The prime mover. Architect evaluates designs, stress-tests assumptions, and turns settled decisions into buildable changelists. Long-horizon reasoning at 1M context — it holds the full picture, names its weakest assumption, and produces decision records other agents execute against. Read-only by design: it plans, never builds.
The cheapest paid eyes in the forge, kept for the wide nets — whole-subsystem questions, web research, search spaces too big to name a target in. Greps codebases, reads files, traces logic, searches the web for docs/APIs, and delivers structured findings reports. Parallel-safe — spawn many simultaneously. Returns specific answers with file paths and snippets, never vague leads. Read-only by design.
Thinks with you, not for you. Reads code, reasons about systems, generates ideas, and discusses tradeoffs to build shared understanding. Produces no artifacts, plans, or code — the conversation is the output before an approach becomes a task.
First stop for targeted recon and high-volume, well-scoped work: trace a flow, run tests, sweep mechanical edits, scaffold, or scan logs. Give it a named target and done-state; dispatch up to four in parallel. Wide-net exploration goes to Scout, while deep reasoning or design judgment goes to Hammer or the paid fleet.
Development
Full tool access. Reads the code, understands the context, and implements the right fix. Give it the problem and location; it figures out the solution, keeps the diff minimal, verifies its own work, and ships the change.
Different model, different training, different instincts. Gets called when Dev is stuck — not because it's smarter, but because it sees differently. Reads the original task fresh, ignores Dev's approach, and forms its own understanding. Available as both a primary agent and subagent.
Hand it one well-scoped task with a clear spec: implement a function, apply a localized fix, wire a component, or make a defined config/code change. The stronger reasoner of the free pair runs up to three in parallel; route well-scoped implementation here first and save the paid fleet for open-ended design or known-hard problems.
Quality
The forensic specialist. Patient, methodical, trace-first. Loads the systematic-debugging skill before tracing — the iron law: no fixes without root-cause investigation. Reproduces the failure, reads the actual error, builds the causal chain, then applies the minimum correct fix. Available as both a primary agent and a subagent.
The second set of eyes. Verifies intent is delivered, traces flow, and checks for bugs and security issues with lint plus scan. Returns severity-rated findings and a ship/block verdict — never fixes, only describes problems. Deliberately a different model family from the agents it reviews.
Modes
The roster is who works the forge; modes are how the floor is run. A mode is an operating posture — a lead-shaped orchestrator whose whole identity is a dispatch doctrine, switched into mid-session like plan mode. Doctrine that would lose to an agent's system prompt as a skill is baked in as the only voice, and enforced below the prompt where it counts: cyclopes-free's spending gate lives in the permission layer.
Twelve hammers, not one. Aggressive decomposition, recon fired immediately, waves of subagents across the whole fleet — volume work swarms down to the free tier, judgment work fans across the paid one. Parallel edits always end in a synthesize pass.
Converts goals into targets and sends them down — Ember and Hammer, free local models on the Spark, grind the work in waves. Scout is allowed for open-ended hunts; every other dispatch is metered and stops for the smith's sign-off. A permission gate, not prose.
The Forge Floor
Agents come and go — the machinery beneath them is what endures. Subagents, Batch, and Memory are not entries in a tool list; they are runtime equipment wired into the session layer under every agent: the dispatch system that isolates and lands parallel work, the fan-out engine that turns a five-hundred-item sweep into one call, and the ledger that makes the fleet remember. Most coding harnesses hand the model a tool list. The forge has a floor.
Every dispatch is the same headless child; background: true changes only when the report arrives. Background writers work in a worktree branched from a snapshot of the working tree — uncommitted edits included — and finished work auto-applies back as uncommitted edits, with a patch artifact kept for one-command reversal. Ten concurrent runs across both modes, delegation three levels deep, every child watched live in the fleet viewer. Reports collapse to one line until asked for.
Point it at a spec and a file of items and it runs one agent per line — concurrency capped to what the free Spark tenants actually sustain, each result appended atomically to a JSONL as it lands. A crash keeps everything already done; a re-run reads the output file and skips it. The loop is deterministic code, not a model improvising control flow — and the grinding lands on the free tier, where five hundred items cost nothing but time.
A profile-scoped ledger written deliberately and read two ways: a capped digest rides into every agent’s system prompt — free-tier subagents included, standing preferences always, project facts following the repo you’re in — and ranked recall reaches the whole ledger on demand. New rows supersede old ones instead of overwriting; subagents read but never write; a human-in-the-loop skill curates the taxonomy. The ✦ memory line in the transcript shows exactly what an agent is carrying.
Skills
Skills are capabilities agents draw on — loaded conditionally based on the task, not baked into the system prompt. They augment agents without defining them. An agent decides which skill to reach for; permissions gate which agents see which skills at all.
The boundary with modes is deliberate: skills add — a methodology, a domain, an environment’s etiquette. Guidance that must override an agent’s defaults isn’t a skill; it’s a mode.
Craft & Method
loaded by task shapeKeeps system prompts, agent definitions, tool descriptions, skills, repository guidance, and memory focused on judgment rather than rule accumulation. Routes each context surface to just the reference it needs, with progressive disclosure and live sources over stale copies.
Rewrites text a machine must parse — tool descriptions, error messages, agent output, system prompts, inter-agent instructions, safety warnings — in ASD-STE100 discipline: one meaning per word, active voice, short single-instruction sentences, hedges preserved. The goal is not the shortest text; it is exactly one reading. Not for creative or marketing copy.
Four phases — investigate, analyze pattern, hypothesize, implement — under an iron law: no fixes without root-cause investigation first. Escalates to architectural review after three failed fix attempts. Adapted from obra/superpowers (MIT).
Enforces distinctive aesthetics — bold tone commitments, cohesive palettes, real animations — and blocks generic AI-looking output. Replaces the former frontend agent: the implementation agents now load this skill automatically when touching UI files, instead of handing off to a dedicated actor.
Data & Documents
ingest → route → queryPulls text, tables, and specific values out of PDFs, DOCX, PPTX, XLSX, and images via the lit CLI — parse once to a file, search the file with disciplined patterns instead of pasting whole documents into chat. Pairs with ontology for structured data and knowledge-base for ingest workflows.
Turns a CSV/XLSX/JSON/YAML into a compact sidecar an agent can route over without re-sniffing the data — a deterministic script does the mechanical pass (types, cardinality, samples), the agent fills the semantic labels. Tabular data becomes CSV + .ontology.json for pandas; nested documents stay native with a .shape.json of ready-to-run jq/yq queries.
Builds a folder-as-KB (marked by a single kb.index.json router) the agent greps and queries by file shape — markdown via grep, tabular via pandas + ontology sidecars, nested docs via jq/yq, nested sub-KBs descended by topic. No vector embeddings, no central registry: the folder is the database, portable and version-controllable.
Designs and reviews DynamoDB tables from real access patterns through key and GSI design, single-table tradeoffs, and migrations. It rejects fake joins and filter-dependent queries, then routes into focused strategy references for the problem at hand.
Analysis & Reporting
figure → pageForm chosen from the finding, colour set explicitly, and a linter that decides the machine-checkable anti-patterns straight off the figure JSON — dual axes, truncated bar baselines, ramps on nominal categories, oversized pies, and colourblind separation by OKLab ΔE under simulated CVD. The palette and the design stay the model’s; only the ways a chart can misstate its data are enforced.
Documents the friction rather than a house style, because the models that produced the reference brief needed no help inventing one. Names the walls: file:// blocked by playwright-cli, Plotly’s class sitting on the container rather than a child, edits that fail silently, glyphs correct in the source and wrong on screen. Ships a verifier that serves the page and reports console errors, unrendered charts, clipped and overlapping text.
Environment & Forge
host etiquetteOverrides the shipped playwright-cli skill with host-specific etiquette: always headed, always persistent, never auto-close. The smith watches the window and may drive it from a separate terminal while agents work — skills preserve the shared session instead of fighting it.
Attaches to the real, authenticated Chrome session in extension mode — bill pay, statements, sites that only exist visually. In and out, never browse: the target is always named, irreversible actions get confirmed first, and every state change ends with a confirmation screenshot.
Drives browser interactions, web-page testing, and Playwright workflows through a concise CLI. Paired with dev-browser whenever an agent opens, navigates, snapshots, evaluates, or captures a browser session.
Host detection (gh vs glab), a full command crosswalk, and mandatory guardrails for mutating operations — PRs, MRs, issues, CI runs, releases. Loaded for any forge task that touches a code host, so every agent speaks both dialects safely.