Documentation
Prometheus is built from a corpus of markdown knowledge files. The panes below explain the framework in English prose derived from the source analysis. Use the runtime pill above the sidebar to switch between an agentic runtime (Claude Code, Codex, opencode & other filesystem-based hosts) and the Gemini Gem — the install and reading-map panes rewrite themselves to the runtime you pick.
hub Overview — how the pieces fit
Prometheus is a build-time framework for designing, auditing, and refactoring prompts for tool-calling agents. It reads a task, picks a mode, and runs an ordered pipeline that draws on shared catalogs and ships the prompt with a verifier. Everything below is a live map: click any node to jump to its section, and expand its source under that section.
boltA prompt is an operator, not a search for magic words.Meaning in a language model is constructed by context, not retrieved by it. So a prompt section is not a hint pointing at a pre-existing answer — it is a transformation applied to the model’s distribution over interpretations. The whole framework exists to help you choose those transformations deliberately, in the right order, and prove they worked.
The architecture & workflow
Router→modes→the six-phase pipeline→the shared catalogs→the verifier layers
Read the map in five moves
1 · The router.
SKILL.md is the one file always in context. It reads the request and selects a mode; it also
carries the from-scratch procedure itself. Nothing else is read until a phase pulls it in.
2 · Two modes (plus manage). From-scratch designs a new prompt; refactor repairs one you already have (audit-only, surgical, or full rewrite by risk). A third capability, manage mode, runs a MAPE-K loop over a managed agent package and rewrites its prompt at a controlled seam.
3 · Six ordered phases. Shape inference → adaptive interview → operator-design drafting → audit → honest evaluation → delivery. Each phase consumes the last one’s output; the order cannot be rearranged because a later operator’s meaning depends on the subspace an earlier one already selected.
4 · Shared catalogs. The phases don’t invent their material — they draw on the operator catalog and seven shapes, and pull reasoning-pattern scaffolds in only when a task shows the hard-reasoning signals. A cross-cutting quantum-semantic frame is the vocabulary all of them speak.
5 · The verifier. Every prompt ships with a verifier defined across three layers — static properties of the artifact, single-run properties of one output, and cross-run properties visible only across many. An honesty ledger travels with delivery, marking each capability as tested or merely source-backed.
terminal Core System
Most prompt-engineering advice is a bag of tips: add keywords, give examples, be specific. Prometheus rejects that framing at the root. It starts from a claim it takes literally rather than metaphorically — that meaning in a language model is constructed by context, not retrieved by it. Under that claim a prompt section is not a hint pointing at a pre-existing answer; it is a transformation applied to the model's distribution over interpretations, and the framework's entire job is to help a designer choose those transformations deliberately.
The problem it solves is therefore disciplined prompt construction: given a task, produce a prompt in the right structural shape, with each section justified as an operator, audited against known failure modes, scored honestly, and shipped with a runnable verifier. Its users are people building agents and prompt systems who want rigor and traceability rather than vibes — and who are willing to be disagreed with when a request would produce a worse prompt.
The framework reaches its users as a self-contained package, and the way it is packaged is
itself part of the design. It is delivered as a portable agent skill that runs in any agentic
environment supporting skills, and is additionally ported to run as a Gemini Gem.
Its single always-loaded file, SKILL.md, carries the YAML
frontmatter that lets a skill-aware host such as Claude Code, OpenAI Codex, or opencode discover it and decide when to
trigger it, followed by the controlling procedure.Its single always-loaded file, SKILL.md, carries the YAML
frontmatter that lets a skill-aware host such as the Codex CLI discover it and decide when to
trigger it, followed by the controlling procedure.Ported to a Gem, the same controlling procedure ships as the Gem's system instructions, with
no filesystem beneath it.
Two dozen further Markdown files sit alongside it and are pulled into context only at the step
that needs them — the framework is written to be read progressively, not all at once, which is
itself a design response to the same attention-budget concern it teaches its users to respect.
What it actually does
The framework exposes three capabilities, one per mode. They share a substrate of reference knowledge but run different procedures.
From-scratch design
The defaultGiven a task description, the framework produces a prompt through six ordered phases: it infers the task's shape, runs an adaptive interview to recover the constraints an operator needs, drafts the prompt as a sequence of named operators, audits that draft against a structural-and-quantum checklist, scores it honestly on three axes, and delivers it with a verifier. The ordering is load-bearing, because operators do not commute.
Refactor a prompt
On an existing promptGiven a prompt the user already has, the framework recovers its intent and takes one of three sub-modes by risk: Mode A audits only, a report with zero edits; Mode B localizes a named symptom to its operator-level cause and proposes a surgical diff; Mode C rewrites wholesale, preserving the original and presenting both with an explicit trade-off analysis.
Manage an agent
Over its lifetimeGiven a managed-agent package — a directory that is the agent's identity — the framework runs a Monitor–Analyze–Plan–Execute loop over it, reusing the same audit checklist, refactor sub-modes, and verifier rather than inventing new machinery. It is a build-time manager that reads run evidence and rewrites prompts; it does not drive a live runtime.
From-scratch delivery is not a fixed bundle; what ships is a function of the run. The pipeline can emit up to eight distinct artifacts, though most runs emit far fewer. The prompt itself always ships, as do a usage instruction, an audit-and-evaluation summary, a verifier specification, and an always-on static-mode verifier. The rest are conditional: dynamic and cross-run verifiers appear only when the stakes warrant them, and a set of four cognitive-tool definitions ships only when the task tripped the hard-reasoning signals during inference. As a skill host with a filesystem and sub-agents, this runtime can write those deliverables to files and fan out checks in parallel.As a skill host with a filesystem and sub-agents, this runtime can write those deliverables to files and fan out checks in parallel.Because a Gem has no filesystem, sub-agents, or parallel fan-out, every artifact is delivered as a clearly delimited copy-paste block and each check runs inline or is handed to the human to paste into a fresh chat — the framework never claims a degraded capability is intact, and never silently drops one. What ships, and why each piece is present, is reported back as a scaffold-to-trigger list: the framework is built to justify its own additions rather than pad the delivery.
The shape of the system
Those three capabilities are not three separate programs. Architecturally the framework is a layered knowledge framework with a plugin-style catalog and a stateful control loop — not a monolith, and not a pipeline alone. Four strata stack cleanly, and one concern cuts across all of them. At the top a thin router reads the request and selects a mode. Beneath it sit the three procedures — from-scratch, refactor, and manage — each a sequence of phases. All three draw on a shared substrate of reference knowledge: the shape catalog, the operator catalog, the audit checklist, the evaluation rubric, the verifier specification, the reasoning patterns, and the consumability discipline — a body of knowledge none of them owns and all of them consume. Below the substrate, manage mode alone adds a state layer: the file-backed agent package and the runnable replay verifier that guards it.
The one cross-cutting concern is the quantum-semantic frame — the nine principles that give the framework its operator vocabulary. It is not a layer; it is a language every other component speaks. And it is enforced rather than encouraged: an invariant requires every managed-mode concept to be anchored to a real section of the source paper or to a numbered principle. The frame is the reason the pieces cohere — remove it and the skill becomes an ordinary checklist. That layered view has a companion in a module dependency map that makes the router-to-reference delegation concrete, one file per phase: no reference file calls back into the controller, and the dependency direction points one way, from controller to reference, which keeps the modules independently readable.
Routing rules
Before any design work begins, the framework decides which of the three modes a message asks for, and it decides from surface signals rather than by asking. A message that pastes a prompt and then requests a fix, audit, or improvement routes to refactor; direct phrasings such as “audit this prompt” trigger it immediately. A message that points at an agent package or uses a lifecycle verb — “run an adaptation cycle,” “why did my agent regress,” “restart my agent” — routes to manage. On a Gem the managed package cannot live on disk beneath the framework, so manage mode runs in a human-mediated form: the operator pastes the package contents in and copies the rewritten prompt back out. Absent clear refactor or manage signals, the framework defaults to from-scratch. When a prompt is pasted but the intent is genuinely unclear, it asks exactly one disambiguating question rather than guessing.
Routing chooses the mode, not the shape. Within from-scratch, the framework still refuses to ask the author what kind of prompt they want; it infers the structural shape from the request's own linguistic signals in a Bayesian pass, and asks a forced-choice question only when the two likeliest shapes fall within roughly thirty percent of each other. That inference logic lives on the following panes.
The flows
Two flows carry the system: the linear from-scratch pipeline and the cyclic manage-mode loop that the state layer governs. The pipeline is the one the default mode runs. A task description enters Phase 1, where it is classified into a shape and a tier; those two facts flow into Phase 2's interview, which recovers the runtime and the definition of done. Phase 3 drafts the prompt as ordered operators drawn from the catalog; Phase 4 audits that draft and can send it back for revision; Phase 5 scores it; Phase 6 delivers the prompt plus a verifier. Data accretes forward — each phase's output is the next phase's input — and the ordering is not rearrangeable, because a later operator's meaning depends on the subspace an earlier one already selected.
The dataflow underneath is a steady narrowing: a free-form task string becomes a signal vector, then a shape with gathered constraints, then an ordered sequence of operator-sections, then an audited and scored artifact, then a delivered bundle. Nothing that is projected away at one phase returns at a later one, which is why the framework insists the phases run in order. The one edge that runs backward is the audit's: a failing Phase 4 returns the draft to Phase 3 for revision rather than passing a defective prompt forward.
Walking one concrete request makes the phase transformations visible. Suppose the author asks for an LLM-as-judge prompt that scores support replies for empathy, running on the OpenAI API. In Phase 1 the words “judge” and “scores” concentrate the posterior on the grader shape with no serious rival, so the framework commits without disambiguating; the runtime is named but no specific model is, so the tier defaults to strong; and because empathy scoring is evaluative judgment rather than multi-step reasoning, the hard-reasoning signals do not fire and no cognitive-tools scaffold is attached. Phase 2 loads the grader question bank and runs its calibration pass, eliciting a clear-pass and clear-fail anchor and proposing the borderline. Phase 3 draws the grader spine — reasoning forced before the score, calibration anchors, bias controls — and selects the explicit-format delivery path. Phase 4 runs the grader's branch-specific audit together with the blocking cross-cutting checks; Phase 5 scores the three axes honestly and confirms no untriggered scaffold survived; and Phase 6 ships the grader prompt, a usage note, the audit summary, a verifier specification, and an auto-generated static-mode verifier — after the framework runs that verifier against its own draft and finds it clean.
balance Where the design strains
A handful of load-bearing decisions give the framework its character, and the same decisions are where it feels its own tension. The build-time boundary comes first: by refusing to be a runtime orchestrator, the framework keeps its analytical clarity and its scope small, at the cost of leaving the author to actually run and wire the artifacts it produces. The operator metaphor is treated as a real design tool rather than decoration — it is the source of the most distinctive rules, from non-commutative ordering to substrate-relative strength. Two further commitments, compositionality and honest self-assessment as a shipped feature, keep the framework small and make its own limitations visible rather than hidden. A related choice, self-reference through closure, builds the managing system out of framework-designed prompts, so the Monitor, Analyze, and grader operators are themselves audited and verified like any delivered prompt; this is elegant and it forced real rigor, but it also concentrates risk, because a flaw in the frame propagates into the manager's own reasoning.
The design strains in three visible places, and the source is candid about each. First, behavioral validation is deferred: the whole management loop is verified mechanically but never run against a live agent, so “validated” means the machinery, not the behavior. Second, intent-level anti-oscillation is only partially mechanical — the runnable verifier pre-filters on trigger-and-section and leaves intent to a grader that itself needs a live model to render a verdict, so a fully autonomous ship-gate is not yet closed. Third, the frame's anchors must be maintained by hand: an earlier revision introduced several citations to non-existent paper sections that passed format-only checks and were caught only by a review that validated anchors against the actual source — a reminder that the frame's rigor depends on a check that now exists but did not at first.
Underneath all three sits one honest admission: the framework's guarantees are prompt-enforced, not mechanism-enforced. The blocking audit checks, the dogfood refusal, and the honesty disciplines are all instructions to the executing agent; nothing structurally prevents an agent under time pressure from skipping them. The source is candid that this is the central risk, and that roughly half the framework's surface — the agent-team path end to end, refactor mode, and the verifier infrastructure — is source-backed but not yet exercised against real tasks. A faithful reader should treat the framework as a well-grounded design whose validation is still partly outstanding, exactly as its own ledger states.
Open questions
Three things are genuinely unclear from the source alone. They are marked here rather than guessed at, because inventing an answer would teach the reader a certainty the material does not support.
How the Monitor operator's greppable text becomes structured YAML.
The source states the markers map one-to-one onto the environment.yaml
fields and that the phase serializes them, but the serializer itself is described rather
than shown, so the exact contract is asserted, not demonstrated.
Who invokes the manage loop, and on what cadence. The min-N gate says not to adapt on too few runs, but the external process that accumulates those runs and triggers a Monitor pass sits outside the package and is left unspecified.
How the autonomy envelope's bounds are enforced at Execute time. The envelope schema is defined — option classes, a maximum diff size, a review cadence — but whether anything mechanically blocks an out-of-envelope edit, versus relying on the grader's judgment, is not settled in the source.
codeShow source: SKILL.mdSKILL.mdexpand_more
science Quantum Principles
The framework treats every prompt — and every section within it — as an operator: a transformation applied to the model's semantic state, not a key that unlocks an answer already sitting inside the model. Drafting, on this view, is not a search for the right words but the design of the right transformation, applied in the right order. This pane covers the rule that decides how hard each transformation should push — because operator strength is not a fixed property of a section. It is calibrated to the substrate the section acts on.
ORDERING — structural, not cosmetic Operators do not commute (§5.1): “Prompt operations don't commute. [A,B] ≠ 0.” The first operators dominate — they set the subspace inside which every later operator acts — so sequence runs from the broadest framing to the final format, never the reverse.
Each operator carries a profile: what it amplifies, what it suppresses, what it mixes, its strength, its place in the sequence, and its failure mode.
- add_circle Amplifiers raise the probability of the interpretations you want — a persona's expertise, few-shot examples, concrete nouns, a domain's vocabulary.
- remove_circle Suppressors lower the probability of the readings you don't — off-domain drift, generic-assistant defaults, outputs that violate a constraint. Each constraint is its own operator; total strength scales with their count.
- merge Mixers combine states rather than sharpen one — a deliberately hybrid domain, or stacked personas, which never simply concatenate but produce a different operator entirely.
Designing one section
A single section is drafted in four moves. Identify the interpretations it should amplify and the ones it should suppress; choose its strength; place it in sequence, from the broadest framing down to the final format; then check it for interference with its neighbours, because combining two sections produces interference, not addition — “expert + dry tone” sharpens into a recognizable voice, while “warm assistant + brutally honest” can cancel until the model settles on neither.
The third move — choosing strength — is where the substrate tier bites.
Operator strength is calibrated to the substrate
Strength is not intrinsic to a section; it is relative to the model the section runs on. On a highly capable substrate a prescriptive operator over-projects — it collapses states the model's own defaults would have resolved better than the prescription. The same enumerated behavior list that corrected a weaker model's drift becomes, on a stronger model, an information-destroying constraint on a state that no longer needed collapsing. So the framework reads a substrate capability tier from the runtime answer during the interview and dials its default operator strength against it: the more capable the model, the lighter the hand.
Prefer brief, general instructions. Reserve intensity language — MUST, CRITICAL, repeated prohibitions, exhaustive enumeration — for constraints with a demonstrated failure mode, and let the model's own priors resolve the residual ambiguity.
The assumed tier when the runtime is unknown. Moderate projection — strong enough to hold the shape, restrained enough to avoid over-collapsing states a capable model handles on its own.
Stronger projection is often warranted. Instructions that would over-trigger a newer model are exactly what corrects a weaker one's drift, so heavier enumeration and firmer intensity earn their place here.
One category is exempt from the dialing-down. Capability lockdown for a role with destructive powers — a worker told what it may not touch, an agent barred from an irreversible action — stays loud on every tier, frontier included. Its justification is risk, not model weakness, so the reasoning that lightens other operators on a strong substrate does not apply to it.
Four rules that hold across every shape
Whatever the substrate and whatever the shape being drafted, four rules always apply.
- straighten Aim for the right altitude — between brittle hardcoding that breaks on the first unforeseen case and vague hand-waving that decides nothing.
- data_usage Spend the smallest viable token set. Every added instruction is another projection; the ones that don't earn their place cost information, not just length.
- lightbulb Prefer worked examples to abstract rules — while remembering that an example silently teaches every judgment call it happens to contain, including the ones you did not mean to encode.
- sort Order sections by operator strength — strongest first to set the subspace, output format last unless the format is itself the dominant requirement.
Two standing rules on what the framework will add at all
Where a rule is load-bearing, the worked example must sit beside it. An output format stated without an example of it is treated as a defect, not a stylistic gap — the reader has been told the shape without being shown it.
The framework applies its own smallest-viable-token-set discipline to its own generative tendency. An optional scaffold may be added only against a named trigger — a debugged failure, a stated requirement, a measured risk — and a scaffold that is declined is named anyway, together with the condition that would re-trigger it.
View source excerpt · Principle 9 expand_more
## Principle 9: Operator strength is substrate-relative
Operator strength is not intrinsic to a section; it is relative to the substrate it acts on. On a high-instruction-following substrate, a prescriptive operator over-projects — it collapses states the model's own defaults would have resolved better than the prescription. The same enumerated behavior list that corrected a weaker model's drift becomes, on a stronger model, an information-destroying constraint on a state that no longer needed collapsing.
Operationally: calibrate default operator strength down as substrate capability rises. Intensity language ("CRITICAL", "MUST", repeated prohibitions) and exhaustive enumeration are strong projections justified only when the substrate demonstrably fails without them. On stronger substrates, prefer brief general instructions and let the substrate's own priors resolve the residual superposition.
The framework infers a substrate capability tier (frontier / strong / legacy; unknown → assume strong) from the runtime answer in Phase 1, and conditions default operator strength, scaffold-triggering thresholds, and delivery guidance on it.
codeShow source: quantum-principles.mdreferences/quantum-principles.mdexpand_more
architecture Shapes & the three axes
The framework refuses one-size-fits-all templates. Before a single line is drafted it classifies the task along three orthogonal axes: the shape — the prompt's structural archetype; the domain — the field the work sits in; and the substrate tier — how capable the target model is. The three are independent: fixing one tells you nothing about the other two, which is why the same shape can be drafted for engineering or for research, or aimed at a frontier or a legacy model, without changing which sections appear.
The shape catalog is shared substrate. All three modes — from-scratch, refactor, and manage — draw on the same seven archetypes; none of them owns the catalog and all of them consume it, so what follows reads the same whichever runtime you are targeting.
The seven shapes
A shape is the structural skeleton a task calls for. There are exactly seven; each has a different anatomy, different sections, and a different failure mode. Most requests fall cleanly into one, a few are genuine hybrids.
all_inclusive S1 · Long-horizon agentic loop
The skeleton for open-ended work a model pursues over many turns against tools, correcting itself as it goes. Signalled by the noun loop and by markers of ongoing rather than single-call use, and by an explicitly named agentic runtime.
bolt S2 · One-shot task
A single model call that produces one deliverable — classify, extract, summarize, transform — with no multi-turn interaction. This is the shape the hard-reasoning detector watches most closely, because a task that looks one-shot may still need a cognitive-tools scaffold.
linear_scale S3 · Multi-stage workflow / chain
Several coordinated model calls where one stage consumes the measured output of the last, held together by gates and validators. Each stage is a complete operator in its own right.
handyman S4 · Sub-agent / tool prompt
A prompt or tool description that lives inside a larger system rather than addressing a human user — consumed by another model or by an agent's tool-use mechanism.
badge S5 · System persona
A system prompt that shapes behavior over unknown future inputs, where the stability of the persona is what matters. Signalled by the noun persona and by continuous conversational use.
gavel S6 · LLM-as-judge grader
A prompt that takes candidate outputs and returns a judgment. Its spine forces reasoning before the score, anchors each score level with calibration examples, and adds bias controls. Signalled by the noun judge and verbs like grade.
groups S7 · Multi-agent agent team
A coordinated set of prompts — an orchestrator, one or more workers, an optional synthesizer — plus a coordination contract. The topology is the dominant operator at team level; each role's prompt is drafted using the spine of whichever of the other six shapes it happens to be.
A new shape is not a code change but a new entry in this catalog, paired with a matching question bank for the interview and a matching branch in the audit checklist — the same extension pattern the framework uses for a new operator or a new quality concern.
Shape inference is Bayesian, never a routing question
The framework does not, as a rule, ask the author what kind of prompt they want. Asking would be a routing question, and routing throws away the information carried in how the request is phrased. Instead it reads linguistic signals — verbs such as build, grade, or extract; nouns such as loop, persona, or judge; scale markers that separate a single call from ongoing use; and any named runtime — and forms an internal posterior distribution over the seven shapes.
It commits to the highest-mass shape only when the runner-up is clearly behind. The threshold is explicit: when two shapes fall within roughly thirty percent of each other, the inference is treated as genuinely ambiguous, and the framework asks a single forced-choice question between the top two — never an open-ended one. This is deliberate collapse: the ambiguity is preserved until asking is cheap and being wrong would be expensive, then resolved with the narrowest question that settles it.
The same inference pass does double duty. It fixes the domain axis and reads the substrate tier from the runtime answer, so a single reading of the request settles all three axes at once.
The domain axis changes content, not structure
The domain — engineering, research, writing, ops, or generic — is a secondary axis. It changes the content of sections without changing which sections appear: an engineering task fills the spine with a concrete stack and tooling-specific failure modes, a research task with source-quality rules and citation conventions, a writing task with voice and length anchors, an ops task with safety boundaries and rollback for irreversible actions, and a generic task with the minimum, leaving the author to fill the rest. Because the domain rides orthogonally to the shape, the seven skeletons times five domains give the same procedure thirty-five ways to be filled in.
The substrate tier sets the strength of the hand
The substrate capability tier — frontier, strong, or legacy, defaulting to strong when the model is unknown — describes the model the prompt will run on, and it conditions how hard the framework's operators should push. The governing intuition is that the more capable the model, the lighter the hand: on a highly capable substrate a prescriptive operator over-projects, collapsing states the model's own defaults would have handled better. So at drafting time the framework prefers brief general instructions on a frontier substrate and reserves intensity language for constraints with a demonstrated failure mode, while on a legacy substrate stronger projection is often warranted.
The tier also gates hard-reasoning detection. When two or more hard-reasoning signals fire — mathematical or logical tasks, multi-step planning, code analysis, several simultaneous constraints, or an author who reports the model fails on the first try — the cognitive-tools scaffold normally becomes a structural default. But that default holds only on the legacy and strong tiers, where the cited empirical result applies; on the frontier tier it is downgraded to an opt-in, because general instructions there tend to outperform prescriptive decomposition. It is the framework's clearest instance of narrowing an empirical claim to the scope it was actually measured on.
One category is explicitly exempt from this dialing-down. Capability lockdown for a role with destructive powers stays loud on every tier, because its justification is risk rather than model weakness — the reason to constrain a delete or a shell command has nothing to do with how clever the model is.
codeShow source: shape-catalog.mdtemplates/shape-catalog.mdexpand_more
codeShow source: section-operators.mdoperators/section-operators.mdexpand_more
codeShow source: minimum-viable-prompt.yamltemplates/minimum-viable-prompt.yamlexpand_more
codeShow source: agent-team-topologies.mdreferences/agent-team-topologies.mdexpand_more
psychology Reasoning & Cognitive Tools
Some prompts need more than a single instruction-and-example shape: they need to scaffold the model's reasoning into discrete, named steps. The framework's reasoning layer is a sub-pattern, not one of the seven shapes. It is invoked inside a shape — inside a one-shot task, a workflow stage, a sub-agent, an LLM-as-judge, or a checkpoint of an agentic loop — wherever the reasoning itself is the bottleneck. When the scaffold is triggered, the framework emits a system prompt plus four tool definitions as copy-and-paste artifacts that you register in your own tool-calling runtime; the framework does not execute the tools itself, and nothing in the pattern requires it to hold tools of its own. The empirical advantage comes from you wiring the per-tool system prompts into your runtime's tool execution.
Hard-reasoning detection is gated by tier
During shape inference the framework watches the request for hard-reasoning signals: mathematical or logical tasks, multi-step planning, code analysis, several simultaneous constraints, or an author's report that the model fails on the first try. Two or more such signals would ordinarily make the cognitive-tools scaffold a structural default rather than an optional extra — the signals trigger inclusion automatically during drafting. But that default is not unconditional: it is conditioned on the substrate capability tier.
The published gains were measured on the model generations available at publication — what the framework's substrate axis calls the legacy and strong tiers — and the result has not been demonstrated on frontier-tier substrates. On a frontier substrate, vendor guidance points the other way: brief general instructions tend to outperform prescriptive step-by-step decomposition, and an over-prescriptive scaffold can degrade output quality. So the rule is narrowed to exactly the scope it was actually measured on. This is the clearest instance in the framework of an empirical claim being held to its measured envelope rather than generalized past it.
Verbatim — reasoning-patterns.md, tier gating“On legacy and strong tiers, the two-signal structural default stands — hard-reasoning signals plus tool-calling runtime → ship the scaffold. On the frontier tier, the scaffold is downgraded to an M5-triggered option: include it only when the user reports a demonstrated first-try failure on that substrate, or explicitly requests it; otherwise prefer a brief general reasoning instruction … and let the substrate decompose for itself.”
When a scaffold is shipped onto a frontier substrate anyway, the delivery must note that the empirical evidence does not cover that tier — the honesty discipline that runs throughout the framework applies here too.
The four cognitive tools
The pattern defines a small set of cognitive operations as modular tool calls. Each tool is a separate LLM invocation carrying a role-prompt that isolates one cognitive operation; the main reasoning model decides when to invoke which tool, and each tool's structured output flows back into the main loop. Modularity is the load-bearing property — the source reports that modular tools consistently beat a single monolithic reasoning prompt, because each tool runs in a sandboxed context with only the inputs it needs, reducing interference. Naming the operations also gives the model explicit permission to backtrack.
understand_question
Restates what is being asked, identifies the goal, surfaces assumptions, names the unknowns, and extracts the relevant symbols and variables. It does not answer.
recall_related
Surfaces two or three similar problems with full solutions as analogical examples. It does not solve the current problem.
examine_answer
Given the current reasoning trace, verifies it against the problem's constraints — catching miscalculations, wrong assumptions, and missing edge cases. It critiques rather than answers.
backtracking
Given a flawed trace, identifies where the first error occurred and proposes a revision from that point — or a fresh strategy when the whole approach was invalid.
The recommended default is to enable all four; if you are optimizing token economy on a strong reasoner, test which subset suffices, since the per-model gains vary widely across tools.
Where it fits — and where it does not
The scaffold earns its cost — extra tokens, latency, and a runtime that supports tool calling —
on hard multi-step reasoning, on tasks whose answer space has dead ends so backtracking matters,
on tasks where verifying an answer is far easier than producing it, and on high-stakes
single-shot work. It is not worth the cost for simple
extraction or classification, for open-ended creative generation (where backtracking
has no verifiable target), for latency-sensitive paths, or on any runtime without tool calling —
there the pattern degenerates into weaker monolithic prompting.
Across the seven shapes the fit is uneven. It is the primary, default choice for a hard-reasoning one-shot task (Shape 2). Inside a workflow (Shape 3) it belongs in a single hard stage — synthesis or decision — not in every stage, because the overhead compounds. In an agentic loop (Shape 1) it lives inside the individual checkpoints where reasoning is hard, never in the loop scaffolding itself. A sub-agent (Shape 4) uses it only when its job is itself reasoning-heavy, and a system persona (Shape 5) generally does not, since personas govern behavior over time rather than a single reasoning episode.
The judge case (Shape 6) turns on a distinction the framework reuses from Shape 2. Evaluative judges — open-ended quality assessment where the score has to be discovered — are a strong fit. Checklist verifiers, whose items are each directly checkable against the artifact, are not: the decomposition is already done, and adding cognitive tools is ceremony. The test is whether scoring an item requires discovering a judgment or merely checking presence against evidence; a mixed judge scopes the tools to its evaluative items only. In an agent team (Shape 7) the tools apply per role, not at the team level.
Operator profile and the reasoning-channel guard
In the framework's operator vocabulary the pattern is strong for hard reasoning and mid otherwise. It amplifies structured decomposition, explicit verification, and a willingness to backtrack; it suppresses premature commitment, monolithic forward-only reasoning, and outputs that look confident but are wrong. It is placed after the constraints and before the output format, and it is non-commutative with that format: if the output format comes first, the model tends to jump straight to the format and skip the reasoning structure entirely.
The scaffold is also designed to pass the audit's reasoning-channel check
(M6). Each tool emits structured intermediate work as
tool results — a sanctioned output channel — and nothing in it instructs the model to
transcribe its internal thinking as response text, which on some substrates both conflates the
reasoning and output channels and can trip a refusal. This is distinct from
M4, the sibling blocking check: a cognitive-tools
scaffold that is described but not actually shipped gives the author the framing of modular
reasoning without its substance, and is treated as a defect.
View the verbatim orchestrator system prompt expand_more
The paper publishes the exact prompts that produced its results, and the framework ships them verbatim because the empirical claim depends on them. You adapt the domain framing (the published prompts target math; the structure generalizes) but preserve the operational specifics. The orchestrator system prompt that wires the four tools together:
You are an expert assistant who solves problems thoughtfully and effectively. You have access to a list of tools — these are functions that you can call to help you reason through or solve the problem more efficiently.
You are encouraged to use tools when they make the task easier, clearer or more robust — especially for complex, elaborated or ambiguous questions.
Use your best judgment to decide when to call tools.
You may call tools at any point in your reasoning process. Only use the tools listed below. If you choose to use a tool, describe your reasoning and clearly call it using their name.
You can solve problems however you find most appropriate.
When you are ready to provide the final answer to the problem or the question always follow the syntax: 'ANSWER: answer'.
You only have access to these tools, do not use any others:
{{cognitive_tools_signature}}
Here are the rules you should always follow to solve your task:
1. Call a tool when needed. If you call a tool, only use the available ones and use its full name to do so.
2. Don't give up! You're in charge of solving the problem.
3. Do not give an answer without reasoning about it.
4. Never hallucinate results. Wait for tool responses before continuing.
5. Only write your final answer after you are confident, and always in the form: 'ANSWER: your final answer here'.
If the question is already clear, you may skip the 'understand_question' step when the corresponding tool is available. But when unsure, it's good practice to use it.
Now Begin!The constant across every runtime — Anthropic, OpenAI, Gemini, or a local model with function calling — is that each per-tool system prompt must reach the model that executes that tool. Where a runtime does not pass a tool's description through as a system prompt (most do not), your wrapper code must do it; registering the tools without wiring their system prompts is the most common deployment failure and yields tool-call routing without the modularity benefit.
codeShow source: reasoning-patterns.mdreferences/reasoning-patterns.mdexpand_more
forum The Adaptive Interview
Once Phase 1 has inferred a shape and a substrate tier, a handful of constraints still cannot be read from the request — chiefly where the prompt will run and how its success will be checked. The interview recovers exactly those, and it is designed around a single conviction the framework holds everywhere: ambiguity is a superposition of readings to be preserved and deliberately collapsed, not a defect to interrogate away. Asking too much collapses that superposition prematurely; asking the wrong thing re-asks what the request already settled and destroys information. So the interview is deliberately small, ordered, and bounded.
The governing rule states the tension plainly: the framework should preserve ambiguity wherever asking is cheap but being wrong is expensive. Where a wrong guess is costly and a question is easy, it asks; everywhere else it records the weighted readings and moves on rather than forcing a premature commitment.
Six flat questions, and no more
The flat interview is capped at six questions in total. Three of them are universal, asked of every shape: the runtime the prompt will execute in, a checkable definition of done, and the deployment context — the last omitted when the request already makes it obvious. The remaining two or three are drawn from the inferred shape, targeting the gaps that shape specifically leaves open. If a disambiguating question survived from Phase 1, it too is counted against the budget; there is one cap, and everything spends from it.
The cap is lifted only for the richer co-authoring passes — the workflow chain, the LLM-as-judge grader, and the multi-agent team — where the decomposition, the calibration anchors, or the role roster is itself the highest-leverage decision and a flat list would produce shallow answers. Those passes propose a candidate first and then refine it, rather than soliciting a specification cold.
How the questions are asked
Four rules govern the manner of asking, and each earns its place by protecting the answers. Questions go out one per turn, because a turn crowded with several questions reliably yields shallower replies to all of them. Anything the request already answered is skipped, because re-asking it discards information the author already gave. The broadest question comes first, because the first answer fixes the subspace every later question operates within. And across all of them the framework leans toward silence wherever a wrong guess is cheap to make and easy to correct, spending its scarce questions only where being wrong would be expensive.
A single question per turn keeps each answer considered; multi-question turns trade depth for the illusion of speed.
Whatever the request has already specified or clearly implied is never asked again, since re-asking it destroys the information the author supplied.
Scope and persona are settled before format and edge cases, because the first answer selects the subspace the narrower ones then refine.
A question is spent only where a wrong guess is expensive; where it is cheap, the reading is recorded and left open rather than forced.
Routing by the type of unknown
Not every gap is answerable by a question, so when intent is unclear the framework first asks what kind of unknown it faces and routes accordingly. The interview handles only the first of the four; the other three send the work somewhere cheaper or denser than a conversation before any drafting begins.
When the author knows the question they have, the interview itself resolves it — this is the ordinary case the six-question budget is sized for.
A criterion the author cannot verbalize is routed to cheap measurement outside the prompt — a throwaway prototype or a brainstorm of variants to react to — before drafting.
Signals that the author does not yet know what to ask trigger a blind-spot pass that enumerates the questions they have not thought to raise.
When intent cannot be put into words, the framework asks for a reference artifact — source code above all — as the densest available way to transfer it.
The summary collapse
The interview may not slide silently into drafting. It must close with a summary collapse: a restatement of the inferred shape, the constraints gathered, and every default the framework has assigned in the author's silence, handed back for a single round of correction. A collapse performed silently would throw away precisely the information the designer — and, later, anyone managing the agent — would need; making it explicit turns the measurement step into something the author can see and override.
"The interview must end with a summary collapse — a restatement of the inferred shape, gathered constraints, and assigned defaults, offered to the author for one override before drafting begins."
— Rules & decision logic
codeShow source: interview-branches.mdtemplates/interview-branches.mdexpand_more
fact_check Audit & Evaluation
Two passes stand between a finished draft and delivery, and they do different work. Phase 4 runs a checklist that catches structural and behavioral failures — the things that make a prompt wrong rather than merely mediocre. Phase 5 then scores what the checklist deliberately does not cover, on three axes, under an explicit instruction to be honest rather than generous. The audit is not a rubber stamp: it is where the framework turns adversarial against its own output.
Before shipping, the framework runs its own static-mode verifier against its own draft and refuses to deliver anything carrying a blocking failure — the discipline the source calls eating its own dogfood. As a skill host with sub-agents, this runtime can run that verifier as a separate check rather than grading purely inline.As a skill host with sub-agents, this runtime can run that verifier as a separate check rather than grading purely inline.On a Gem that verifier runs inline, in the same context that wrote the draft, because the runtime cannot spawn a separate verifier agent — a deliberately degraded form of the check that the framework names as degraded rather than passing off as intact.
Phase 4 · the checklist
The checklist runs the drafted prompt through checks A–O plus a measurement-focused M-series. It is structural and behavioral, not stylistic: it asks whether each directive sits at the right altitude between brittle hardcoding and vague hand-waving, whether every section spends the smallest viable set of tokens, whether load-bearing rules carry a worked example beside them, whether each section's operator profile — what it amplifies, suppresses, and mixes — is articulated, whether the ordering runs from strongest operator to final format, whether adjacent operators interfere destructively, and whether critical context is preserved rather than pre-collapsed. The M-series adds the measurement checks the classical list omits, including one that flags any instruction telling a model to transcribe its internal reasoning as output.
How hard a finding bites depends on where the prompt came from. Auditing a from-scratch draft — the framework's own output — it assumes intent: every section was added deliberately, so a failure is a real defect to fix and re-audit. Auditing a user-supplied prompt in refactor mode, it cannot tell which sections are deliberate, which constraints reflect external requirements, or which apparent weaknesses are load-bearing for reasons it cannot see; it runs the same checks but treats the results as candidates for the user's review rather than blocking issues, because the user knows things about their prompt the framework does not.
The checks that encode the strongest opinions
Three M-series checks are where the framework holds its hardest line — each guards a failure mode the framework is itself most prone to.
Cognitive-tools completeness
If hard-reasoning signals triggered the cognitive-tools scaffold, all four tool definitions must be present in the delivered artifact, not merely named in prose. A prompt that describes the pattern without shipping the tools gives the author cognitive framing without cognitive substance — the one outcome the framework will never deliver.
Scaffold restraint
The framework applies its own smallest-viable-token discipline to its own generative tendency. Every optional scaffold must trace to a specific, named trigger — a fired signal, a cited answer, a stated stake. “It might help” is not a trigger. The test: would an engineer hand-writing this prompt include this scaffold, or is it here only because the framework had it on the shelf?
Reasoning-channel separation
Telling a model to echo its internal thinking as response text conflates two channels and trips a refusal category on some runtimes. It is flagged as a defect — but carefully distinguished from a task-mandated justification field, such as a judge's written reasoning before a score, which is legitimate output on every runtime.
Phase 5 · scored honestly, then restrained
Once the checklist has caught the structural failures, evaluation scores the draft from one to ten on three axes the checklist does not cover. The rule that governs the whole pass is a hard one — “be honest, not generous” — because an inflated score hurts the author more than a low one: a seven with a named gap tells them whether to iterate or ship, while a padded nine costs them the next session.
Token economy
Are the tokens spent buying behaviors that matter? A top score means every section addresses a specific failure mode or enables a concrete behavior, examples are load-bearing, and no preemptive edge case or ritual structure survives.
Task fit
Does the prompt cover what the user actually needs delivered — not only the immediate build but the downstream needs it implies, such as a reviewer audience, an audit trail, or calibration data? Deductions and credits are tuned per shape.
Operator coherence
Do the sections work as one coordinated transformation, or a loose collection? A top score means ordering reflects operator strength, interference pairs are examined and resolved, every section has a clear profile, and nothing is decoration.
Scoring is also where scaffold restraint runs: the framework lists every optional scaffold it added alongside its one-line trigger, and strikes any that exist only because the machinery was available. And it does not ship silently past a weak score — a score below six must be named and offered a fix rather than quietly delivered; if two or more axes fall below seven, the framework proposes a revision pass the author can decline but should at least see.
A deliberate correction against its own bias. The temptation to award a high score grows with the effort already spent, so the rubric builds in a sunk-cost correction: after several revisions the framework's perception is upward-biased and it adjusts down, scores the artifact rather than the author's mood during drafting, and when tempted to write a nine asks what a ten would look like — if that answer is concrete and reachable, the draft is not a nine yet.
The empirical extension is authored, not run
For high-stakes prompts the audit can offer a measured score on top of the heuristic one — a fidelity test across two section orderings, an interference test on a suspect pair, a variance sweep across temperatures. These cost real model calls, so the framework writes them for the human to run rather than executing N samples itself, and reserves them for prompts that will run thousands of times; for a one-off task they are skipped.
codeShow source: audit-checklist.mdreferences/audit-checklist.mdexpand_more
codeShow source: evaluation-rubric.mdreferences/evaluation-rubric.mdexpand_more
codeShow source: agent-consumability.mdreferences/agent-consumability.mdexpand_more
verified Verification
Verification is the framework's closing discipline: a prompt is not finished when it reads well, but when it has been checked against a written statement of what would count as success. Two things travel with every delivered prompt for that reason — a verifier specification that says, separately from the prompt itself, what correct behavior is, and one or more runnable verifiers that exercise that specification. The recursive twist is that a verifier is itself just another prompt, so the framework builds it out of machinery it already owns rather than as a new subsystem.
What ships depends on the stakes
Delivery is conditioned on the run rather than fixed. Some pieces are always present: the prompt, a short usage note, the audit summary with its three-axis score, the verifier specification, and the static-mode verifier that inspects the prompt text without executing it. The heavier verifiers — the single-run verifier that judges one output, and the cross-run verifier that watches for calibration drift and distributional bias across many outputs — appear only when the stakes justify them, at production scale or high volume. Cognitive-tool definitions ship only when the drafting phase actually triggered them, and are formatted for the runtime the author named.
The three levels of a verifier specification
Static. Properties of the prompt artifact that can be judged without running it — section presence, schema validity, structural coherence. This largely mirrors the audit checklist, re-exposed as a re-runnable check.
Single-run. Properties of one output on one input — schema conformance, each named constraint satisfied, forbidden patterns absent, the author's named failure modes handled.
Cross-run. Properties over many outputs — calibration drift, distributional bias, edge-case coverage, consistency on identical inputs. Often empty for low-stakes prompts; often the most important level for anything in production.
The specification doubles as a cross-check on the prompt itself. A specification that comes out thin — fewer than a handful of single-run checks, no cross-run worth running — is a signal that the prompt may be under-specified, or genuinely simple. One so dense that running it would cost more than the prompt it guards signals over-engineering. Delivery guidance is likewise tuned to substrate and runtime: prefilling, once a default, is now emitted only as a legacy path for runtimes that still accept it, with an explicit-format instruction as the standard substitute.
Eating its own dogfood
The framework holds itself to the same bar it sets for others. Before shipping, it runs its own static-mode verifier against its own draft and refuses to deliver anything with a blocking failure — the discipline the source calls eating its own dogfood. If that self-check finds a blocking defect, such as a cognitive-tools scaffold that was described but never actually included, the artifact is not presented as finished; the problem is named and a revision offered. It is worth being candid that this guarantee is prompt-enforced, not mechanism-enforced: the refusal is an instruction to the executing agent, and nothing structural prevents a rushed run from skipping it.
On the Gemini Gem runtime, which has no sub-agents and cannot re-run a prompt N times, this gate degrades to an inline self-check the framework performs on its own draft, and the runnable verifiers are emitted as copy-paste Shape 6 prompts for the human to run in a second chat and report back. The parallel fan-out a skill host would use — per-role and cross-run verifiers running concurrently — is lost, and the framework says so rather than pretending the checks ran. Where the runtime does provide sub-agents, the same verifiers can be dispatched as separate agents and run in parallel; where it does not, they run in series or by hand. The recursive insight survives every runtime intact: a verifier is a Shape 6 LLM-as-judge prompt, so it inherits that shape's machinery — calibration anchors, bias checks, reasoning forced before scoring, and the Goodhart framing that a mis-specified verifier produces sharply wrong outputs rather than merely noisy ones.
The scaffold-to-trigger list
The self-check only earns trust if the artifact carries an honest account of what it actually contains, and that is the job of the scaffold-to-trigger list. A prompt is more than its prose: it may attach optional scaffolds — cognitive-tool definitions for hard reasoning, clarification-seeking behavior for interactive deployments, verifier prompts for consequential outputs — but each of those is supposed to appear only when a specific condition in the run called for it. The ledger is the running record that keeps that promise auditable: for every scaffold it names what was scaffolded and what its trigger was, so a reader can trace each attachment back to the condition that justified it rather than taking its presence on faith. A scaffold in the delivery with no trigger behind it, or a trigger that fired with no scaffold behind it, is exactly the kind of blocking discrepancy the dogfood gate is meant to catch.
That scaffold-to-trigger accounting extends into an honesty discipline the source calls the validated-versus-unproven ledger. Every capability the delivery claims is tagged as one of two things and no third: tested, meaning a verifier actually exercised it and passed, or merely source-backed, meaning it rests on the framework's own reasoning but has not been run. The point of separating them is that the status travels with the delivery — the recipient is never left to guess which guarantees were checked and which are promissory. Read together, the two ledgers make the same commitment from two directions: the artifact states what it did, not merely what it aspires to, and it states so plainly enough that the claim can be checked against the record.
Mechanical versus judged verification
Not every property wants the same kind of checker, and one of the framework's cleaner seams runs exactly along that line. Properties that are decidable — whether an adaptation history replays byte-for-byte, whether a proposed change repeats one the ledger already recorded as a regression — are delegated to a deterministic runnable script. Properties that genuinely need judgment — whether a control-plane seam holds, whether persistence and write-ahead conditions are respected — go to a Shape 6 grader. That grader carries one firm rule: when the mechanical report it depends on is missing, it must abstain and mark the result UNVERIFIED rather than guess. Keeping the deterministic and the judged checks on opposite sides of this boundary is what lets each be trusted for what it actually establishes.
codeShow source: verifier-specification.mdreferences/verifier-specification.mdexpand_more
codeShow source: verifier-agent-patterns.mdreferences/verifier-agent-patterns.mdexpand_more
autorenew Manage Mode
Manage mode is the third of the framework's procedures. Where from-scratch designs an agent and refactor reshapes a single prompt, manage mode runs an agent across its whole lifetime — always between its runs, never driving it live: it monitors the agent's runs, analyzes goal violations, plans an adaptation, and executes it at one controlled seam, then remembers what it did so it does not repeat a mistake. It adds almost no new analytical machinery; it schedules the machinery the other modes already own — the audit checklist, refactor mode, the cross-run verifier — into four canonical phases. Throughout, the agent's prompt is treated as an operator Ôv, and an adaptation is simply the manager producing the next version Ôv+1.
Everything a managed agent is lives in one directory, the managed-agent
package. Inside it, Knowledge (K) is the file-backed state
the four phases share — split into the semantic-state model of the current prompt
(managed-system.yaml),
the environment model of aggregated run facts
(environment.yaml),
the goals model
(goals.yaml),
the ordered adaptation ledger
(ledger.md),
and transient working models. A goal counts as well-formed only when it pins three things: an
observable, an
observer — the measurement operator that reads it —
and an aggregation. Because meaning is observer-dependent,
“the agent succeeded” is a property of a transcript and a measurement together, never of
the transcript alone.
A sharp seam runs through that package — the framework's cleanest one in manage mode. The prompt, tools, and knowledge files are manager-owned: the control plane the manager rewrites. The agent's own memory/ is agent-owned: the data plane, which the manager reads as a probe but never hand-edits. Keeping the two apart is what lets the manager steer the agent between runs without the agent knowing, while still leaving it a persistent memory of its own.
hub The MAPE-K loop
This is the richest flow in the framework, and its discipline reduces to a single rule:
K is the bloodstream. The four phases never call one another.
Each reads from the Knowledge store and writes back to it, and the next phase reads only what the previous one
persisted — because each pass is an irreversible measurement, and nothing survives it except what is
written to K. The loop begins when enough runs have accumulated against the current version on an active agent;
the agent is deactivated, its transcript flushed to
runs/, and
control enters the loop.
Monitor
Reads runs/
and goals.yaml
and writes tomography facts — cluster probabilities, variance, failure-taxonomy counts — to
environment.yaml.
It reconstructs the distribution a version induces rather than reacting to any single run.
Analyze
Reads that environment model, the ledger.md
prior, and the managed-system semantic-state model, and writes a weighted set of candidate edits to
working/.
It reasons over the operator model, never the raw prompt text, and keeps its options in superposition.
Plan
Collapses the candidate set to a single edit and writes it to
working/
together with an interference re-check list for every section the edit touches. This is the deliberate
measurement — the one place a choice is actually made.
Execute
The only writer. Entering the ADAPTING state, it logs a write-ahead ledger entry, snapshots the current prompt, persists the diff as a patch, applies it, re-audits, bumps the version, and updates the semantic-state model last.
account_tree The lifecycle state machine
The loop is allowed to write in exactly one place, and the lifecycle machine is what makes that checkable. Six states — UNCONFIGURED, CONFIGURED, ACTIVE, INACTIVE, ADAPTING, and the terminal FINALIZED — connect through named transitions. Effectors fire only inside ADAPTING; every other transition preserves the prompt's hash and version. Stop-and-restart is the same seam as adaptation: an agent that can be cleanly deactivated is, by construction, one that can be adapted. And a re-audit failure inside ADAPTING rolls back to the prior snapshot rather than leaving the machine in a dangling state, which is what keeps it closed.
agent-state.md.
ADAPTING is the only state where the prompt may change; FINALIZED is a terminal archive, and every other
transition preserves the prompt's hash and version.
gavel The rules that keep it safe
Manage mode is governed by nine invariants and
three runtime rules. The invariants are the standing contract
— that every phase communicate only through K, that Execute log its ledger entry before it touches
the prompt, that Execute stay human-gated unless an explicit bounded envelope in
manifest.yaml
says otherwise. The three runtime rules are the moment-to-moment decisions the loop makes as it runs.
Min-N gate
Never adapt on fewer than N accumulated runs against the current version. A single run is one sample of the distribution the prompt induces; reacting to it is reacting to measurement noise.
Anti-oscillation
Analyze may not re-propose an option the ledger records as having regressed against the same trigger. The mechanical verifier pre-filters on trigger-and-section; a grader judges intent.
Replay property
The first snapshot plus the ordered ledger diffs must reconstruct the current prompt exactly, byte for byte — the property that makes an adaptation history trustworthy and a rollback safe.
codeShow source: refactor-mode.mdreferences/refactor-mode.mdexpand_more
install_desktop Setup
Prometheus ships as one portable agent skill. The controlling file,
SKILL.md,
is the single always-loaded file — roughly 22 KB of YAML frontmatter plus the controlling
procedure — and twenty-three companion files (the reference corpus under
references/,
operators/,
templates/, and
manage/)
sit alongside it and are pulled into context only at the step that needs them. Because it is written to
be read progressively, installation is mostly a matter of making the folder discoverable to your runtime.
Install as a Gemini Gem
source gem-instructions.md + knowledge/
Gemini does not read a skill folder from disk, so the framework is ported to a Gem. Its twenty-four
source files are consolidated into one standing instruction, gem-instructions.md, plus eight knowledge/ files.
Nothing runs locally — the whole framework lives in the Gem's context.
Create a new Gem
Open Gemini and choose Create a Gem from the sidebar. Name it Prometheus.
Paste the instructions
Copy the entire contents of gem-instructions.md and paste it into the Gem's instruction field. It carries the core stance, the three modes, the from-scratch procedure, and the wiring table that makes the knowledge files reachable.
Upload the knowledge base
Attach all eight knowledge/*.txt files as the Gem's knowledge base, without renaming them — the wiring table names each one exactly, and under selective retrieval a renamed file is unreachable. They ship as .txt because the upload accepts text, not .md.
Save and start a session
Save the Gem and begin by simply stating your prompt-design task; the interview runs from there. The Gem is Prometheus; the framework it carries is Prompt Architect v2, so the corpus refers to itself that way.
Install on an agentic runtime
source <skills-path>/prompt-architect/
Every filesystem-based agent — Claude Code, OpenAI Codex, opencode, Cursor and any other skill-aware host — installs Prometheus the same way, because the skill is just a directory holding a SKILL.md with valid frontmatter, placed on the host's skills search path so it is discovered by folder name. There is no build step and no dependency install — the one script it carries, manage/replay-verifier.py, imports nothing outside the Python standard library.
~/.claude/skills/
Codex · ~/.codex/skills/
opencode · ~/.config/opencode/skills/
Place the skill folder
Copy the whole prompt-architect/ folder onto your host's skills search path (see the paths above for the common runtimes), keeping references/, operators/, templates/, and manage/ intact.
Match the folder name to the frontmatter
The loader discovers the skill by folder name, and that name must equal the frontmatter name:. Both are prompt-architect; the frontmatter also carries a description: and license: MIT. Leave them unchanged.
Let the auto-trigger do the rest
There is nothing to enable. The host reads the frontmatter description and routes to the skill on prompt-design intent — "write a prompt for X", "design a grader", "build an agent", "fix my prompt". The skill then runs its own interview and names the host's memory file — CLAUDE.md, AGENTS.md or equivalent — as the target.
account_tree Reading Map & Source Layout
The framework is one body of source read three ways. It ships as a portable agent skill that any skill-aware host can discover — Claude Code, OpenAI Codex, and opencode among them — and it is additionally ported to run as a Gemini Gem. The files are the same; what changes per runtime is how the host loads them and, for the ports, a small band of audit artifacts that record how faithfully the port was carried out.
Below is the reading map rendered for the runtime you have selected in the version pill above — the
order to read the files in, a one-line note on when each one earns its place in context, and the exact
install path. Start with SKILL.md:
it is the router, and it frames everything else.
folder_open Source browser
Every file in the framework, viewed with the same offline viewer used by the in-context panels. Pick a file on the left.
Select a file to view its complete source.
auto_awesome Gemini Gem
Ported to Gemini Advanced, the framework’s twenty-four source files are consolidated into a single
standing instruction — gem-instructions.md — plus
eight knowledge/ files, so it fits the Gem’s instruction
field and its ten-file knowledge cap. Retrieval is selective rather than a directory walk, so the same
progressive-disclosure discipline holds: a knowledge file surfaces only when the task’s wiring-table entry names it.
The instructions — always loaded
One standing instruction carries the whole controlling procedure and the wiring table that makes the knowledge files reachable at all.
gem-instructions.md 19 KB
Pasted into the Gem’s instruction field. The core stance that a prompt is an operator, the three modes, the six-phase from-scratch procedure, and — load-bearing under selective retrieval — the wiring table that names each knowledge file and the moment to pull it.
The knowledge base — eight files, pulled on demand
The twenty-four source files consolidated into eight uploads — nothing renamed, because under selective retrieval a renamed file is an unreachable file. Each surfaces only when the task’s wiring-table entry names it.
knowledge/quantum-core.txt 60 KB
The quantum-semantic principle catalog and the section-as-operator catalog, the cognitive-tools reasoning sub-pattern with its verbatim per-tool prompts, and the permutation test. Pulled for any drafting or audit that needs operator profiles or the frame’s operational mapping.
knowledge/shapes-and-build.txt 46 KB
The seven shape spines, the per-shape interview question banks and conduct rules, and the minimum-viable-prompt six-slot fallback. Pulled for Phase-1 shape inference, the Phase-2 interview, and shape-specific drafting.
knowledge/verifier-and-audit.txt 57 KB
The audit checklist, the evaluation rubric, the verifier specification across three layers, and the verifier-agent construction patterns. Pulled for the Phase-4 audit, Phase-5 evaluation, and shipping any verifier.
knowledge/manage-core.txt 34 KB
The MAPE-K procedure, the managed-agent package layout, the six-state lifecycle machine, and the write-ahead ledger. Pulled to understand a managed package, its lifecycle transitions, and ledger discipline.
knowledge/manage-operators.txt 27 KB
The four MAPE operator prompts, the manage-mode verifier, the dogfood audit, and the runnable external replay verifier. Pulled when running a manage phase, gating an adaptation, or replaying outside.
knowledge/manage-agent-design.txt 21 KB
Agent-consumability output design for Shapes 4 and 6, and the four agent-team topologies for Shape 7. Pulled when the output is consumed by another agent, or when drafting an agent team.
knowledge/provenance.txt 32 KB
Citations tracing every technique to its primary source, the changelog, and the license. Pulled to trace a claim to its named source or to answer provenance and legal questions.
knowledge/refactor-mode.txt 15 KB
The full 1R–6R refactor procedure and its sub-mode selection — audit, targeted refactor, or wholesale rewrite. Pulled when refactor mode is detected.
Install as a Gem
The Gem is assembled from two things: gem-instructions.md becomes the standing instruction, and the eight knowledge/ files become the base it pulls from as each phase needs them. Filenames are load-bearing — the wiring table names each one exactly.
Create a new Gem
In Gemini Advanced, choose to create a Gem from the sidebar and name it Prometheus.
Paste the instructions
Copy the entire contents of gem-instructions.md into the Gem’s instruction field — 19,249 characters, within the verified 30,000 working cap.
Upload the eight knowledge files
Attach all eight knowledge/*.txt files without renaming them. They ship as .txt because the knowledge upload accepts text, not .md; a renamed file is unreachable under selective retrieval.
Save and start a session
Name the Gem and save it, then begin by stating your prompt-design task; the interview runs from there. Naming note: the Gem is Prometheus, the framework it carries is Prompt Architect v2, so the corpus refers to itself that way.
terminal Claude Code
This is the canonical, portable skill. Its single always-loaded file, SKILL.md,
carries YAML frontmatter — name, description, license — that lets a skill-aware host discover it and
decide when to trigger it. Two dozen further Markdown files sit alongside and are pulled into context only at
the step that needs them.
The router — read first
The one file that is always loaded; it selects the mode and carries the from-scratch procedure.
SKILL.md 22 KB
Read first. The router, the core stance that a prompt is an operator rather than a keyword search, and the six-phase from-scratch procedure. It frames every other file.
The frame — read before the rest
Nine principles the whole corpus speaks; without them the rest reads as arbitrary rules.
references/quantum-principles.md 10 KB
Read second. The nine quantum-semantic principles, each paired with a concrete drafting or audit action. It is a vocabulary every other component uses, not a layer.
Design vocabulary — shapes and operators
The shapes are the skeletons; the operators are the muscles. Read the pair together.
templates/shape-catalog.md 22 KB
The seven prompt shapes and each one's anatomy — which sections apply and how it is evaluated. Read when you need to place a task into its structural archetype.
operators/section-operators.md 18 KB
Each prompt section described as an operator: what it amplifies, suppresses, and mixes, its strength, and whether it commutes with its neighbours. Read while drafting a section.
templates/interview-branches.md 20 KB
The per-shape question banks for the Phase-2 interview and the six-question cap conduct rules. Read when conducting the adaptive interview.
templates/minimum-viable-prompt.yaml 2 KB
The smallest scaffold a delivered prompt must fill. Read when you want the floor, not the full anatomy.
How quality is judged
The audit catches structural failures; the rubric scores what the audit does not cover.
references/audit-checklist.md 25 KB
The pre-ship checklist, combining classical context-engineering and quantum-semantic checks. Read before declaring a prompt done; fix, re-audit, ship only when clean.
references/evaluation-rubric.md 7 KB
Scores the prompt on three axes the audit leaves untouched, to give the user calibrated information about what they are getting. Read in Phase 5.
The management layer — read agent-state first
Manage mode alone adds a state layer; everything in it depends on the package definition, so read that before the loop.
references/agent-state.md 23 KB
Read first in this layer. The managed-agent package, the six-state lifecycle machine, and the ledger that everything else in manage mode depends on.
references/manage-mode.md 11 KB
The four MAPE phases — Monitor, Analyze, Plan, Execute — run over a managed agent, communicating only through the knowledge store. Read to understand the loop.
manage/monitor-operator.md 5 KB
The shipped Monitor pass, which reads accumulated runs and writes state-tomography facts. Read when the loop needs to observe the agent.
manage/analyze-operator.md 6 KB
The shipped Analyze pass, a Bayesian collapse over candidate adaptations that reasons over the operator model rather than the raw prompt text.
manage/manage-mode-verifier.md 6 KB
The Shape-6 grader that checks a managed package for well-formedness. Read when verifying an agent package.
manage/replay-verifier.py 5 KB
The one piece of genuinely executable code. It makes the replay property and the anti-oscillation rule concrete, and it imports nothing outside the Python standard library.
manage/dogfood-audit.md 4 KB
The framework auditing its own inner MAPE operator prompts, satisfying the closure requirement that the managing system is itself made of prompts.
Provenance — the honest-status trail
These carry the version history and trace every borrowed idea to its source.
CHANGELOG.md 13 KB
The full version history and the honest status legend that runs through the corpus. Read for what changed and how confident each claim is.
CITATIONS.md 17 KB
Every borrowed idea traced to its source; the architecture is original but nearly every principle is attributed. Read to check where a claim comes from.
LICENSE 1 KB
The MIT license. This file remains authoritative regardless of the frontmatter license key.
Optional depth — read last
The from-scratch pipeline only sometimes pulls these in. Save refactor mode for last, since it is the alternate path and makes the most sense once from-scratch is familiar.
references/reasoning-patterns.md 31 KB
Cognitive-tool scaffolds invoked inside a shape for hard-reasoning tasks. Read when a task shows two or more hard-reasoning signals.
references/agent-team-topologies.md 15 KB
Four canonical multi-agent topologies and the operator profile of each role. Read when a task is decomposed across coordinated agents.
references/verifier-specification.md 11 KB
What a delivered prompt's verifier must check — the language of record for what counts as success. Read when specifying a verifier.
references/verifier-agent-patterns.md 13 KB
How to turn that specification into a runnable verifier agent that judges outputs against it. Read after the specification.
references/agent-consumability.md 6 KB
Designing a prompt's output when another agent, not a human, will consume it — the output is itself an operator on the next agent's context. Read for agent-to-agent handoffs.
references/refactor-mode.md 15 KB
Read last. The inverse path — auditing, fixing, or rewriting an existing prompt across its own six phases. It makes the most sense once the from-scratch pipeline is familiar.
Install as a skill
A skill is a directory containing a SKILL.md with valid
frontmatter, placed on the host's skills search path so the loader can discover it by folder name. There is
nothing to build and no dependency to install — the skill runs in the model's context window, and its
one script is standard-library only.
Place the folder on the skills path
Copy the prompt-architect/ folder into Claude Code's skills directory so the loader discovers it under the folder name.
Let the frontmatter do the routing
The name, description, and license in SKILL.md are what the host reads to decide when to trigger; no wiring is required.
Invoke by describing the work
Ask for prompt-design work — “write a prompt for…”, “design a grader”, “audit this prompt” — and the skill runs its own interview and delivers. For a Claude Code target the memory file it names is CLAUDE.md.