Metadata-Version: 2.5
Name: microwave-method
Version: 0.1.18
Summary: An agent factory with a governed memory. One command drops it into your repo and hands you to your coding agent for a guided welcome.
Project-URL: Homepage, https://github.com/microphage-create/microwave-method
Author: Microphage Intelligence
License-Expression: MIT
License-File: LICENSE
License-File: NOTICE.md
Keywords: agents,factory,governance,llm,wiki
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Microwave Method

**Point it at your folder of repos. It scans them and proposes one AI agent to guard each repo, plus the shared services they call, then governs the whole set: a factory that gates every creation, a registry you can read, and a markdown memory that compounds.**

*A method, not a runtime. Not a SaaS. Dependency-free scripts your coding agent (Claude Code, Codex, Cursor) runs. It takes you by the hand from the repos you already have, not from a blank page.*

[![gates](https://github.com/microphage-create/microwave-method/actions/workflows/gates.yml/badge.svg)](https://github.com/microphage-create/microwave-method/actions/workflows/gates.yml)
[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

```bash
uvx microwave-method
```

## What it does, concretely

Point Microwave at the folder where your repos live. It:

1. scans every repo and detects its stack,
2. proposes a map: one **context** agent per repo (the guard that carries that
   repo's conventions) plus the transversal **services** they share,
3. creates the ones you approve, through a factory that gates each creation and
   files it in a registry one line long,
4. governs the set from then on: gates in CI, a readable memory that compounds,
   and a lifecycle (`gates/decay.py`) that names the dead.

That is the whole pitch, and every word of it is in the repo you just cloned. It
is honest about its own reach: what a machine refuses is the FORM of a creation;
the substance is made reviewable, not guaranteed (see "What is enforced" below).

## Context and service: anti-sprawl from the model, not a slogan

Two kinds of agent, and the difference does the work (ADR-028):

- A **context** agent guards one repo and names it. One per repo is a natural
  cardinality, so the registry does not fill with near-duplicates.
- A **service** agent is transversal and shared, never copied. A context agent
  declares the services it `uses`, and `gate_uses` refuses one that does not exist.

"Nobody creates on the side" is a convention an agent can ignore. "One guard per
repo, tools shared" is a structure that holds whether or not anyone is watching.
That is the real anti-sprawl, and it is why the registry stays mappable.

## Taken by the hand, from your estate

BMAD-METHOD and spec-kit take you by the hand from a blank page. Microwave starts
from what you already have:

```
$ python gates/scan_estate.py ~/Documents/GitHub
Scanned ~/Documents/GitHub: 3 repo(s) (direct children).

Proposed context agents (one guard per repo):
  - api-service  [Python]  -> context, slug: api-service
  - cli-tool     [Go]  -> context, slug: cli-tool
  - web-app      [Next.js, Node/JS, TypeScript]  -> context, slug: web-app

Suggested transversal services (shared, create once):
  code-review, copywriter, release-notes, test-writer
```

The scan writes nothing. The welcome flow then drives creation with you, one agent
at a time, asking before every write, and escalating to questions or the brainstorm
bank when a repo's purpose is unclear rather than guessing. Say
*"run the Microwave welcome flow"* to your coding agent after install.

## The memory is a wiki, not a vector store

Most tools make a vector store the memory itself: chunks cut mid-thought, opaque
vectors, nothing governed, so a stale chunk lives forever. Microwave's memory is a
governed wiki of atoms in the Zettelkasten lineage: one idea per file, plain
markdown, tagged and linked.

- **Readable both ways.** The same file serves the human who corrects it and the
  agent that opens it on demand. You can see, in plain text, what your system knows.
- **Targeted, not fuzzy.** A compact index lets the agent open the atom it needs by
  name, instead of hoping a similarity search surfaced the right chunk.
- **Governed and alive.** Gates refuse duplicates, wikilinks make a graph, and
  `decay.py` names the atoms nothing links and nobody touched.

Retrieval (reranking, hybrid search) composes ON TOP of the atoms when the corpus
outgrows a scannable index. It is not an alternative to the readable substrate.

## Gates, not meetings

A creation passes a series of **machine gates**, a CI for agent creation:

<!-- microwave:gates start -->
<!-- generated by gates/docgen.py, do not edit by hand -->

| Gate | Guarantee |
|---|---|
| `gate_antidup` | no unjustified overlap with the registry |
| `gate_brief` | the 3-section brief is complete |
| `gate_schema` | the agent card matches the template contract |
| `gate_testable` | every done-criterion names a real check, not a filler word |
| `gate_embodiment` | the agent has a body when it needs one |
| `gate_uses` | an agent's declared services actually exist in the registry |
| `gate_slop` | durable artifacts do not read like slop |
| `gate_wiki` | the wiki is linked, indexed, and its atoms carry their contract |
| `gate_docs` | generated doc sections match their source |

<!-- microwave:gates end -->

This table is generated from the gates themselves and cannot go stale: `gate_docs`
fails the build if it drifts (ADR-022). The slop bank (`slop/slop-rules.csv`) ships
as a starter that warns on style and blocks only objective defects (a leftover
placeholder, assistant leakage); promote a rule to `reject` if your org wants it
stricter.

### What is enforced, and what is not

Stated plainly, because the difference is where most tools oversell.

**Structural** (a machine refuses; goodwill is not involved): the pre-commit hook
and the CI workflow run the gates and block a commit that fails them; `CODEOWNERS`
plus branch protection gate who merges. These exit non-zero. The gates and the
stdlib YAML parser they rely on (no dependency, deliberately: a governance tool
should not widen your supply chain) are covered by a test suite in that same CI.

**Cooperative** (the agent has to play along): the flows, the elicitation, the
devil pass, and the gatekeeper's judgment are conventions, not code that exits
non-zero. And precisely what the gates check, so "gate" does not oversell:
`gate_antidup` is a lexical overlap test, not semantic, with a written-rationale
escape hatch; `gate_slop` is surface regexes, not a quality score; `gate_testable`
checks a criterion names a check, not that it ran. They catch common failures
cheaply; the proof is the devil pass, the gatekeeper, and your own tests.

**Rolling out to a live team?** `MICROWAVE_SHADOW=1` makes the gates report what
they would block without failing, for a grace period. Unset to enforce.

## Where it sits

You already have pieces of this. What Microwave adds, against each:

- **Native skills / subagents** (Claude Code, etc.): great for building one agent.
  No registry, no anti-dup across many, no lifecycle. Microwave keeps a hundred of
  them mappable.
- **`AGENTS.md` / `CLAUDE.md`**: a context file. Microwave ships one too and wraps
  it in a factory, a governed memory, and gates.
- **spec-kit, BMAD-METHOD**: structure, but from a blank page and with ceremony per
  object. Microwave scans your existing estate, deletes any step nothing reads, and
  scales ceremony to blast radius.
- **Provider memory tools**: a store, usually opaque and provider-owned. Microwave's
  memory is a readable, git-native wiki you own and can `git blame`.

The honest risk: providers are absorbing the memory and subagent layers fast, and a
markdown method above them could look redundant in two releases. The bet is the
substrate: a readable, git-native, provider-agnostic wiki survives a provider
swapping its memory tool and composes with whatever retrieval they ship.

## The economics, honestly

No headline percentage, because the honest version is unglamorous. Reading context
is a large, repeated share of agent cost. Prompt caching cuts the cost of
re-reading the SAME context inside the cache window, so a stable, reused context
file is cheaper on the second hit; the size of that win depends on your provider and
workload. The slower, compounding win is not re-discovering knowledge across
sessions, because it was captured once as an atom and reopened by id. Measure your
own: the method instruments itself (`docs/method.md`), so diff your token spend
before and after on the same tasks.

## Install

```bash
uvx microwave-method
```

One line, any OS, run inside the repo you want governed (`git`, Python 3.10+ and
`uv` required; the tool itself is standard-library-only). No `uv`? A shell bootstrap
clones the repo and does the same. Try it with nothing touched: `uvx
microwave-method --dry-run`. Per-OS walkthrough, uninstall and troubleshooting:
`docs/install.md`. The generated reference (flows, gates, decisions):
`docs/reference.md`. The longer thinking behind the method: `docs/manifesto.md`.

## Status

Extracted from a system its author runs daily on a private stack, then squashed and
cleaned for release. The scale behind it (dozens of skills, a multi-generation rule
corpus) lives in that private system, not here, so take it as provenance, not proof.
What this repo demonstrates on its own: it self-hosts (its own agent cards pass the
same gates the factory imposes) and its CI is green. Judge it on that, and on what
you build with it.

MIT. See `NOTICE.md` for attributions.

---

```
⣾⣿⣿⣿⣿⣿⣿⣿⣧⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢰⣿⣿⣿⣿⣿⣿⣿⣿⡄⠀⠀⠀⠀
⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⡇⠀⠀⠀⠀
⠈⠉⠉⠉⠉⠉⠉⠉⠙⣷⣶⣶⣶⣶⣶⣶⣶⣶⣶⣶⣶⣶⡟⠉⠉⠉⠉⠉⠉⠉⠉⢻⣶⣶⣶⣤
⠀⠀⠀⠀⠀⠀⠀⠀⠀⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⣿⣿
⠀⠀⠀⠀⢀⣤⣤⣤⣴⣿⣿⣿⣿⡿⠛⠛⠛⠛⠛⠛⠛⠛⠁⠀⠀⠀⠀⣠⣤⣤⣤⡾⠛⠛⠛⠉
⠀⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣿⣿⣿⣿⡇⠀⠀⠀⠀
⠀⠀⠀⠀⠘⠿⠿⠿⢿⣿⣿⣿⣿⣧⣀⣀⣀⡀⠀⠀⠀⠀⠀⣀⣀⣀⣠⣿⣿⣿⣿⡇⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⡇⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⢀⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣇⠀⠀⠀⠀    Microwave Method
⠀⠀⠀⠀⢰⣿⣿⣿⣿⠁⠀⠀⠀⢹⣿⣿⣿⣿⠀⠀⠀⠀⢸⣿⣿⣿⣿⠁⠀⠀⠀⢹⣿⣿⣿⣷    an agent factory with a governed memory
⠀⠀⠀⠀⢸⣿⣿⣿⣿⠀⠀⠀⠀⢸⣿⣿⣿⣿⠀⠀⠀⠀⢸⣿⣿⣿⡿⠀⠀⠀⠀⢸⣿⣿⣿⣿
⣴⣶⣶⣶⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠉⠉⠉⠙⣷⣶⣶⣶⡟⠉⠉⠉⠀⠀⠀⠀⠀⢸⣿⣿⣿⣿
⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀⠀⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⣿⣿
⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠙⠛⠛⠋⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⣿⣿
⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⣿⣿
⠛⠿⠿⠿⣿⣿⣿⣿⣿⣄⣀⣀⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣀⣀⣼⠿⠿⠿⠛
⠀⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣿⣿⣿⣿⡇⠀⠀⠀⠀
⠀⠀⠀⠀⠘⣿⣿⣿⣿⣿⣿⣿⣿⠃⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢿⣿⣿⣿⠃⠀⠀⠀⠀
```
