Architecture: evolve the agentic-template into miden-agent, a versioned, agent-neutral Miden dev tool

# Summary

Building on Miden takes real expertise: smart contracts in Rust, a young SDK, and assembly-level details most developers have not seen before. miden-agent lowers that bar by putting an expert Miden developer inside your AI coding agent. Ask it anything about Miden and get an answer grounded in source, or hand it an idea and have it build a working app end to end: it writes the code, tests it, and checks its own work, so what comes out actually runs rather than just looking right. It works the same whether you know Miden deeply or have never touched the chain, on a new project or one you already have.

miden-agent builds on the agentic-template, which already works today, and takes it from a capable starter to a production-grade tool ready to ship. The refactor makes its Miden knowledge versioned so it cannot quietly drift, makes it agent-neutral instead of tied to one assistant, and packages it as an installable CLI so the same expertise travels to any project and any agent. No rewrite, the strong parts stay. This issue is the plan.

# Current state & problem

For readers who know the template exists but not how it works: today the agentic-template is a monorepo with two git submodules, `project-template` (Miden smart contracts, written in Rust) and `frontend-template` (a React app using the Miden SDK). On top of the code it ships two AI ingredients. **Skills** are Markdown files of Miden knowledge that an agent loads on demand (how to write a note script, the felt-arithmetic footguns, the React SDK hooks). **Hooks** are scripts wired into Claude Code that run automatically when you edit a file, to build the contract you touched or run the affected tests. There is also a documented build pipeline: write contracts, validate them with in-memory MockChain tests, gate on a real local node, then build the frontend against the compiled artifacts.

That foundation is strong in the one place most AI tools are weak: it already gates on real exit codes and feeds failures back to the agent, instead of trusting the model to declare "done."

But it has three structural problems, all drift and incompleteness rather than bad design:

1. **The knowledge drifts.** The skills are hand-edited copies of the upstream `0xMiden/agent-tools` skills, and they have diverged. Of 14 shared skills only one still matches upstream, and the core `miden-concepts` skill exists in three different versions: one is missing a whole section, another points at a skill that does not exist. Upstream itself has no versioning. So the expert can quietly be wrong, which undermines the one thing a Miden companion has to get right.
2. **It really only works for Claude Code, and only at the root.** The agent instructions live in a `CLAUDE.md` (Claude's instruction file). The cross-tool `AGENTS.md` is just a symlink to it, and neither submodule has one at all. So Codex, or any agent working inside a submodule where the build actually happens, gets little or nothing.
3. **The verification is not portable or fully honest.** The checks are Claude-Code-only hook scripts, partly duplicated between root and submodule, and the headline local-node gate points at a validation binary that is not actually in the repo. They also fire more often than they should.

And it is new-project-only: there is no way to bring it to a Miden repo you already have, which is half the value of a tool like this.

None of this needs a rewrite. The work is to close the drift, finish the half-built layers, and add the capabilities the foundation unlocks.

# What the refactored tool does

Three ways to use it, one set of machinery underneath.

**Build a Miden app.** Open your agent at a wired project and describe what you want. The tool decomposes the work into tasks, runs each in a fresh context, and after every change runs the verification gate (build, tests, local-node validation, frontend build). Green commits; red feeds the failure back and tries again. You get a contract, its tests, and a frontend that talks to it, each step proven rather than assumed.

**Use it as a Miden wizard.** No build, no project even. Ask anything Miden: architecture, a design review, a MASM question, why your note will not consume. It composes the relevant skills and, when a question goes past them, verifies against the actual `0xMiden` source instead of guessing. Pinned, drift-free knowledge, so the answers are trustworthy.

**Bring it to an existing project.** Point it at a Miden repo you already have. It detects what the project is and what is already wired in, then produces per-file analysis the build loop can use, without touching your code until you ask.

```
miden-agent wizard # install the Miden expert, ask anything, anywhere
miden-agent init # scaffold or wire a project (Rust contracts, MASM, or frontend)
miden-agent analyze # inspect an existing Miden repo, emit per-file facts and findings
miden-agent run # drive the build loop: one task per fresh context, gated on green
```

`init` covers the existing scaffolds (Rust contracts, React frontend) and a planned **MASM project-template** that plugs in the same way. It also works on projects that never used a template: the expertise comes from the versioned skills and the harness, so a template is a convenient starting point, not a requirement.

**Detection on existing projects.** Two things get detected. *Project shape*, by walking up for sentinel files: a Cargo project with Miden metadata is a contract project, `.masm` files a MASM project, a `package.json` with the Miden SDK a frontend, and a `.gitmodules` pointing at our templates means "one of our structures." Anything Miden-shaped but unfamiliar is treated as a custom project and still works; the tool just infers the build commands instead of assuming a layout. *Skill version*, from the tool's manifest if present, or by fingerprinting the skill files against published versions if not (which also surfaces drift, e.g. "miden-concepts is 15 lines off the pinned version"). It then offers to update, reconcile, wire the gate, or emit analysis, never acting destructively.

# Form factor and install

The repo is two things with opposite needs. The **scaffold** (the starter contract and frontend code) is clone-and-own. The **agentic layer** (skills, gate, analysis, loop) is tooling that operates on a project. So the decision: keep the monorepo template for onboarding and a runnable demo, and ship the agentic layer as an operate-on-project **Rust CLI** (`miden-agent`), distributed like any Rust tool (cargo install or a midenup component).

**Local by default, global by opt-in.** Builders want pinned, reproducible skills; a wizard wants the latest. So `install` / `init` asks once, with a two-sentence callout because at that point you just want to get going:

```
? Set up miden-agent for this project (local) or for every session on this machine (global)?
> local pinned, reproducible, nothing outside this folder (default)
global available in every session, auto-updates

global: Installs the Miden skills for all your agent sessions and adds an auto-updater so
they stay current. Pick local to pin this project to a fixed version (reproducible)
and leave your machine config untouched.
```

| | Local (default) | Global (opt-in) |
|---|---|---|
| Skills | pinned in the project | machine-level, auto-updating |
| Instruction | marker block in the project AGENTS.md | carried in the skills |
| Updates | surfaced in the gate, one prompt | automatic |
| Reproducible | yes | no (always latest) |
| Best for | building a project | wizard, asking across many repos |

# How it works

The tool is five layers that compose. Most of the machinery is shared; each mode just uses a different subset.

- **Knowledge: versioned skills.** The Miden expertise lives in one place, `0xMiden/agent-tools`, made a single cross-tool skills repo (its Claude-only slash commands dropped; the one security-review command worth keeping becomes a skill). Skills are versioned and consumed by pin, with a CI check that fails if a copy drifts. This is the brain, identical in wizard mode and in a build.
- **Instruction: a marker-managed block.** A small, agent-neutral block in `AGENTS.md` (and its `CLAUDE.md` symlink) orients any agent: the verify-in-source rule, plus pointers to the skills, the gate command, and the project map. It is written between stable markers, so the tool can install into a repo that already has an `AGENTS.md` and later update only its own block, never your content.
- **Verification: one gate.** A single `verify.sh` per project type is the source of truth for "is it correct." It runs the real checks (build, tests, local-node validation, frontend build), returns an exit code, and is callable identically by a Claude hook, the loop, or CI. It is tiered (a cheap fast tier per edit, the full gate at task boundaries) and change-aware (it runs only the checks for what actually changed, and nothing on a docs-only edit).
- **State: on-disk memory, not the context window.** The agent documents vital information automatically as it works: a task list with status, an append-only progress log, the per-file analysis, and a commit per finished task. That state lives on disk, so it survives a context reset or compaction, and you can kill the loop and restart it; nothing important is trapped in the agent's head.
- **Analysis: facts and findings per file.** For existing code, the tool emits per-file FACTS (structure, from `cargo check` and a `.masp` inspector) and FINDINGS (issues, from clippy and the MASM formatter) as compact Markdown. That is the context that lets a fresh task work safely on code it did not write.

How a build actually flows: the loop takes the next task, opens a fresh agent context loaded with the instruction, the relevant skills, and the relevant analysis, lets it edit the project, then runs the gate. On green it commits and advances; on red it feeds the failure back and retries. One task at a time, each proven before the next. Wizard mode uses only the first two layers (skills plus the rule): no project, no gate, no loop, you just ask, and the answers are grounded.

```mermaid
flowchart TD
dev([Developer]) --> agent{{miden-agent}}
agent -->|wizard| wiz[Install versioned skills,
ask anything Miden, anywhere]
agent -->|init| newp[Scaffold or wire a project]
agent -->|analyze| exist[Detect shape + skill version
on an existing repo]
newp --> ready[Wired project:
skills, AGENTS.md, gate, manifest]
exist --> ready
ready -->|miden-agent run| task

subgraph loop [Fresh-context build loop]
direction TB
task[Next task] --> work[Fresh agent:
instruction + skills + analysis]
work --> gate{verify.sh:
build, tests, node, frontend}
gate -->|red, feed failure back| work
gate -->|green| commit[Commit, update progress + task status]
commit --> task
end

subgraph mem [On-disk memory, survives context resets and compaction]
direction LR
tasks[(tasks.json
task list + status)]
prog[(progress.md
append-only log)]
analysis[(per-file analysis
facts + findings)]
gith[(git history)]
end

skills[(agent-tools
versioned skills)] -.-> wiz
skills -.-> work
exist -.writes analysis.-> mem
mem -.loads from disk, not the window.-> work
commit -.auto-saves progress + state.-> mem
```

**The files, and when they exist:**

| File | Layer and purpose | When it exists |
|---|---|---|
| `skills//SKILL.md` | Knowledge. Versioned Miden expertise, loaded on demand. | all modes (machine-level in global, pinned in the project in local) |
| `AGENTS.md` (+ `CLAUDE.md` symlink) | Instruction. Marker-managed block: the rule plus pointers to skills, gate, map. | build, existing |
| `.miden-agent.toml` | Manifest. Records the pinned skill versions; read by `analyze` for version and drift detection. | build, existing (local) |
| `verify.sh` (per project type) | Gate. The one deterministic check, tiered and change-aware. | build, existing |
| `.claude/hooks/*` + `settings.json` | Thin Claude wiring that calls `verify.sh` on edit and at stop. | build, existing (Claude users) |
| `tasks.json`, `progress.md` | Loop state. The task list and the append-only log; git holds the rest. | only while the loop runs |
| `.miden-agent/analysis/*.md` | Analysis. Per-file FACTS and FINDINGS for existing code. | existing / brownfield |
| project files (`contracts/`, `src/`, `.masm`, ...) | The actual Miden project. The tool operates on these; it does not own them. | any real project |

**Why the gate never fires redundantly.** A single dispatcher routes an edit to the one relevant check (or no-ops on docs and config), the Stop gate runs only the gates for what changed (and nothing if nothing relevant changed), and the heavy tier is tied to task boundaries, not every keystroke. This was already a real pain in the current template; `0xMiden/project-template#31` and `0xMiden/frontend-template#15` patched it reactively, and folding the logic into one scoped gate keeps it from recurring each time a hook is added.

# MASM skills and AI tooling (a gap to fill)

MASM is the weakest-covered area today. The current MASM skill coverage in `0xMiden/agent-tools` is thin, so the planned MASM project-template needs a proper MASM skill set authored fresh: writing and reviewing `.masm`, the formatting and doc-comment conventions, padding and stack discipline, and the common footguns, at the depth the Rust and frontend skills already have. On the tooling side a real CST-based formatter (`miden-format --check`) and the `.masp` inspector cover formatting, syntax, and artifact facts, but there is no tree-sitter grammar, so a repomap-style symbol index is out of reach for now. Filling the MASM skill set is a prerequisite for the MASM template, and for the wizard and the loop to be as strong on MASM as they are on Rust and the frontend.

# Getting there

Five milestones, each building on the last. The first solidifies what exists; the rest add the new surface.

**1. Solidify the foundation.** Make the current template correct, portable, and drift-proof.
- Fix the broken references: ship or re-spec the missing `validate_local` gate (see the open question), fix the dangling skill reference and the missing `miden-concepts` section, pin submodules to releases.
- Single-source the skills: make `agent-tools` the canonical cross-tool skills repo (drop the commands, turn the security review into a skill), version it, consume by pin, add a CI drift-check.
- Complete the instruction layer: an `AGENTS.md` in each submodule, agent-neutral content, and the idempotent marker writer.
- Consolidate the gate: one portable, tiered, change-aware `verify.sh` per project type; delete the duplicated hooks.
- _Unlocks: a template that is multi-agent, drift-proof, and has a gate that is real. The floor everything else stands on._

**2. Build the miden-agent CLI.** The operate-on-project tool.
- The Rust CLI with `init`, `wizard`, `analyze`, `verify`, `run`.
- Project detection (shape and skill version) and the manifest.
- The local / global install model.
- _Unlocks: bringing the agentic layer to any project, new or existing, and pure wizard use._

**3. Add brownfield analysis.**
- The `.masp` inspector (artifact facts; the underlying library exists, only a CLI front-end is missing).
- The analysis emitter (clippy / `cargo check` JSON plus the MASM formatter, into per-file facts and findings).
- The `analyze` workflow for existing repos.
- _Unlocks: the tool working safely on code it did not write, and the context the loop needs._

**4. Add the fresh-context loop.**
- Task list plus progress log plus the gate, one task per fresh context above `claude -p`, red to green to commit.
- _Unlocks: autonomous multi-task builds that cannot fake green._

**5. Add Miden domain MCP (later).**
- The `.masp` inspector as an MCP server; stateful miden-client and local-node servers.
- _Unlocks: richer, stateful tooling once the loop makes it worth it._

Running alongside: authoring the MASM skill set (the prerequisite above), which can proceed in parallel with milestones 1 to 3. Dependency order: 1 before all; 2 enables 3; 3 enables 4; 4 enables 5.