[!NOTE]
A prompt is an operator, not a key. You don't retrieve the right answer by
finding magic words — you construct it, section by justified section, the way you
build a circuit. Agents and workflows are just the largest things you build that way.

At a glance

Three pillars, each with its own section below — click a card to jump.

Three modes → Build from scratch, refactor, or manage a live agent.

Six phases → Shape → interview → draft → audit → score → deliver.

Always verified → Static, single-run, and cross-run checks on every artifact.

Contents

• ⚡ Quick start
• What it is
• Core idea: prompts as operators
• What it builds
• Three modes · Manage mode (MAPE-K)
• The Fabrication Cycle
• Verification
• Install
• Repository layout
• Documentation
• License

⚡ Quick start

1. Get the skill — download the zip, or clone:

git clone https://github.com/Samuele95/prometheus.git

2. Drop it on your agent's skill search path (Claude Code shown; keep
references/, operators/, templates/, manage/ intact):

cp -a prometheus ~/.claude/skills/prometheus

3. Describe what you need — a prompt, an agent, or a workflow. No build step,
no dependencies. The host auto-routes to Prometheus the moment it sees the intent:

build an agent that triages support tickets and files them with our tools

[!TIP]
Using Gemini instead? Prometheus ships a filesystem-free Gem port — jump to
Install → Gemini Gem.

What it is

Prometheus is a portable agent skill and a build-time engine for agentic
systems. Give it an intent and it engineers the artifact end to end — a prompt, a
full agent, or a multi-step workflow — audits it, scores it, and ships it with
a verifier. It runs entirely at build time: it designs, audits, refactors, and
maintains the things your agents are made of; it never sits in your request path at
runtime.

It is deliberately not prompt-only: a system prompt is the smallest thing it
produces; a self-adaptive agent kept healthy across its lifetime is the largest. One
always-loaded SKILL.md router (~23 KB) plus a companion corpus pulled into
context only at the step that needs it. No build step, no dependencies, MIT.

Core idea: prompts as operators

Every section of a prompt is an operator acting on the task — it amplifies some
readings of the intent, suppresses others, and mixes the rest. Order is load-bearing:
a later operator's meaning depends on the reading an earlier one already selected. One
operator is set apart — Collapse, the measurement act, where the prompt commits to
a single interpretation. Agents and workflows are assembled from the same operators,
which is why the discipline scales from a one-line instruction to a lifecycle-managed
system.

What it builds

The same operator model compiles into whatever the task needs. The six outputs stack
into three layers, the way a network stacks: raw instructions in, agents in the
middle, judgement on the way out.

Three modes

Manage mode — a MAPE-K loop over a live agent

The mode that makes Prometheus more than a prompt tool. Point it at a managed-agent
package — a directory that is the agent's identity — and it runs a Monitor →
Analyze → Plan → Execute loop over it, always between runs, never driving it live:

Step	What it does
Monitor	Reconstructs the behaviour the current prompt actually induces, from recent run evidence.
Analyze	Keeps candidate adaptations in weighted superposition and prunes the ones a ledger says already regressed.
Plan	Collapses to a single edit.
Execute	Applies it at a controlled lifecycle seam — write-ahead-logged and reversible by snapshot.

[!IMPORTANT]
Strict control-plane / data-plane split: the prompt, tools, and knowledge files
are manager-owned (the control plane it rewrites); the agent's own memory/ is
agent-owned (the data plane) and is read as a probe, never hand-edited. It reads
run evidence and rewrites the agent — it never sits in the request path.

The Fabrication Cycle

From-scratch design compiles a raw task into a delivered artifact across six ordered
phases. Data flows forward; a single feedback edge returns a failing audit from
Phase 4 to Phase 3 — the only loop in the pipeline.

#	Phase	What it does
1	Shape	Infer the structural shape and strength tier
2	Interview	Recover the runtime and the definition of done
3	Draft	Lay out the artifact as ordered operators
4	Audit	Check the draft against the failure-mode checklists
5	Score	Rate token economy, task fit, operator coherence
6	Deliver	Ship the artifact with a verifier

Verification

Every artifact — prompt, agent, or workflow — ships with a verifier defined across
three layers: static properties of the artifact, single-run properties of one
output or trajectory, and cross-run properties visible only across many. Cross-run
is where agent regressions hide. A scaffold-to-trigger list records which capability is
actually tested versus merely source-backed.

For hard multi-step reasoning on a tool-calling runtime, Prometheus can also emit a
cognitive-tools scaffold: a system prompt plus four tool definitions you register in
your own runtime.

Multi-agent teams are first-class: five canonical topologies (orchestrator-workers,
sectioning, voting, evaluator-optimizer, swarm/shared-forum), each audited against an
empirically grounded failure-mode catalog — conformity collapse, hidden-profile
information loss, missing epistemic vigilance, collusion, turf wars — drawn from
published swarm experiments and traced in CITATIONS.md.

Install

Prometheus is one folder containing a SKILL.md with valid frontmatter. How you make
it discoverable depends on your runtime.

Agentic runtimes — Claude Code, OpenAI Codex, opencode, Cursor, …

Clone the repository and copy it onto your host's skill search path, keeping
references/, operators/, templates/, and manage/ intact:

git clone https://github.com/Samuele95/prometheus.git
cp -a prometheus ~/.claude/skills/prometheus

gem/, docs/, and .github/ are packaging, not corpus — the skill works with or
without them. There is no build step and no dependencies. The host reads the frontmatter
description and routes to the skill whenever it sees the intent — "write a prompt for
X", "build an agent", "design an agentic workflow", "grade these outputs", "fix my
prompt", or "manage this agent".

Gemini Gem — filesystem-free port

Gemini has no filesystem and caps a Gem's knowledge base at ten files, so the framework
is ported, not copied: the twenty-four source files are consolidated into one
standing instruction plus eight knowledge files. See
gem/GEM-DESCRIPTION.md for port details, features, and
limitations, and gem/en/setup-guide.md to install.

In short: create a Gem named Prometheus, paste gem/en/gem-instructions.md into its
instruction field, upload the eight gem/knowledge/*.txt files without renaming them
(retrieval is selective, so the wiring table's filenames are load-bearing), and start
describing your task.

Repository layout

SKILL.md         # always-loaded router: mode detection + from-scratch procedure
references/      # shared knowledge (quantum principles, shapes, reasoning, …)
operators/       # the operator catalog
templates/       # interview branches, output templates
manage/          # manage-mode MAPE-K loop, operators, and replay-verifier.py
gem/             # the Gemini Gem port (+ GEM-DESCRIPTION.md)
docs/            # the documentation site (GitHub Pages)
assets/          # figures, banner, social preview
CITATIONS.md     # every technique traced to a primary source

The only script, manage/replay-verifier.py, imports nothing outside the Python
standard library.

Documentation

The full documentation — the operator model, the seven shapes, the three modes, the
manage-mode loop, the audit checklist, and per-runtime install guides — is published
from docs/:

It includes an interactive source browser that shows the exact corpus for the runtime
you pick, so you can read what the model will read before installing.

License

MIT. Every technique is traced to a primary source in
CITATIONS.md.