Ed Agent

A mission-swappable one-person army — for build, review and trust.
▶ Watch the 30-second intro · MIT · zero-dependency core

Once AI writes the code, the job stops being "how do I write this" and becomes "should I trust this?" Ed Agent is built for that shift. It drives one requirement — or any content, or a diff — through nine stages with a swappable squad, but it stops at two deliberation checkpoints and surfaces the questions only a human can answer:

• Was the intent captured, or is it guessing the project? Unstated intent is the #1 flagged risk, not a silent guess.
• Should you trust this (not "is it correct") — provenance, verification, blast radius, the confidence-vs-evidence gap.
• Does the local optimum serve the global goal? It flags the technically-right, business-wrong decision that digs a global pit.
• Is it substance, or over-defensive ceremony? The "looks-rigorous, all-filler" detector.

Plus a mission-aware red team that attacks every build for what its domain cares about, claim-level grounding (Grounded / Ungrounded / Contradicted), a memory that learns your preferences, quality disciplines (ban AI-tone filler · quantify-or-flag · no blind praise), real artifacts at every stage, and a quantified ledger. Drop it into any bot via MCP or the AGENTS.md brief. Zero-dependency core (Node 18+).

New in v0.6 — the inner loop. Add --loop and the produced artifact is refined in a deterministic produce → verify → (rollback) inner loop before review, with four safety mechanisms that make a self-iterating loop survivable instead of a runaway: a severity gate, an overshoot rollback, iron-law HARD-HALTS (a crossed red line never bypasses you), and a budget fuse — plus a WHAT / WHY / PATTERN audit trail and a learning flywheel that forges a durable rule from every rejection. The model produces; the harness governs.

Click the mascot above to watch the intro.

Honest by construction. Ed Agent does not pretend to understand your business — a harness can't. It forces the intent to be captured, runs deterministic trust / coherence / substance checks, and puts the right question at the right node. The judgment, the two checkpoints, and the two gates stay human. Velocity, not autonomy.

node bin/ed-agent.mjs "Build a REST API for user onboarding with rate limiting"   # → code squad
node bin/ed-agent.mjs "Launch a landing page for a new savings product"           # → marketing squad
node bin/ed-agent.mjs "Draft an NDA with a 12-month liability cap"                # → contract squad
node bin/ed-agent.mjs "KYC onboarding with EDD source of funds"                   # → finance squad (eds-mcp)
node bin/ed-agent.mjs --mission optimize --input case-study.md                    # → optimize squad (review)

Quickstart · 使用指南

No install, no dependencies. The core is pure Node (18+). Get the code, run one command, then watch it in the dashboard.

# 1 · get it
git clone https://github.com/Edwson/Ed-Agent.git && cd Ed-Agent

# 2 · run a requirement through the governed lifecycle
#     --intent captures the business goal · --approve / --signoff are the two human gates
node bin/ed-agent.mjs "KYC onboarding with EDD source of funds" \
  --intent "let compliant clients finish onboarding" --approve "You" --signoff "You"

# 3 · open the control room to watch + tune it — no command line needed after this
node bin/ed-agent.mjs dashboard --open        # → http://127.0.0.1:4317

A run writes real artifacts to out/ and a quantified entry to Ed_agents_Claude.md (its memory). The dashboard reads that same file — it is the single source of truth, and nothing leaves your machine (the server binds to 127.0.0.1 only and makes zero external requests).

Command cheat-sheet

ed-agent below is shorthand for node bin/ed-agent.mjs (run npm link once to get the real ed-agent command).

You want to…	Command
Build / plan something	ed-agent "your requirement" (mission auto-detected)
Force a squad	ed-agent "…" --mission code|marketing|contract|finance|optimize
Review / de-AI any content	ed-agent --mission optimize --input file.md
Audit a diff — "should I trust this?"	ed-agent --audit changes.diff --intent "…" --not "a non-goal"
Run the self-correcting inner loop	ed-agent "…" --loop (severity gate · rollback · iron-laws · budget fuse)
Gate on critical red-team findings	ed-agent "…" --strict
Resolve an open checkpoint	--resolve "trust: accepted" / --resolve "ironlaw: reason"
Teach it a preference	ed-agent --remember --prefer "tone: terse"
Open the control room	ed-agent dashboard --open
Run every test	npm test && npm run test:dashboard && npm run test:mcp

Want it inside Claude / Cursor / Codex instead of the terminal? Drop it in via the MCP server or the plain-text AGENTS.md brief.

The squad swaps to the mission

The mission is auto-detected from the requirement (override with --mission):

Mission	Squad	Produces
Code	Architect · Security · QA · Doc engineer	architecture · security review (STRIDE) · test plan · README
Marketing	Creative Director · Conversion Analyst · Consumer Psychologist · SEO	creative brief · conversion model · SEO plan · copy outline
Contract	Senior Lawyer · Risk-Control Officer · Negotiator · Semantic-Logic reviewer	clause map · risk register · negotiation positions · ambiguity review
Finance (default)	Planning · Regulation · Data · Development · QA · Risk & Governance	eds-mcp compliant build — scaffolded HTML/CSS/JS + conformance tests
Optimize (grand-mentor · 総監督)	Executor A · Reviewer B · Copy C · Data/Logic D · Market/SEO E	blind-score diagnostic · adversarial debate · de-AI'd draft · three-part output

Browse committed runs in examples/ — one per mission.

Review & optimize anything — the grand-mentor (総監督) squad

The optimize mission takes existing content (a deck, a case study, a landing page, a clause) and runs the review SOP, so Ed Agent is a thinking unit, not only a build unit:

1. Diagnostic — the squad blind-scores the content across five dimensions and names the three most fatal flaws.
2. Adversarial debate — Reviewer B (a hard buyer) and Data/Logic D challenge it: how does this create a real benefit, with a number?
3. Humanize — Copy C strips the AI-tone filler (a deterministic de-AI pass) and lays out the structure to finish.
4. Optimized version — assembled in the exact three-part format: Expert diagnostic / 専門家による診断 · Optimized version / 最適化版 · Business-value assessment / ビジネス価値評価.

node bin/ed-agent.mjs --mission optimize "In conclusion, our world-class platform seamlessly leverages cutting-edge synergy to improve value."
# → REWORK (low blind score): AI-tone filler flagged · claims missing numbers · fatal flaws named

When the content is a regulated-finance surface, the Data/Logic officer calls the real eds-mcp engine to show the numbers instead of asserting them — the guardrail components the surface should map to, the regulatory anchors for the jurisdiction, and the token-contrast WCAG pass rate of the system it would ship on.

The quality disciplines — folded into every mission

Three house rules run in every review, not just optimize (the same skills/quality.mjs):

• Ban AI-tone filler — an EN + JA + ZH scanner flags in conclusion, leverage, seamless, まず, シームレス, まさに, … so the voice stays human.
• Quantify or flag — any sentence that asserts a benefit with no number is surfaced for a measured figure (ROI / cost / conversion / time saved).
• No blind praise — a blind score (five dimensions) yields a PASS / REWORK verdict; mediocre work is told it "would not pass a top-tier interview/review yet," with the reasons.

The trust & deliberation layer

The hard problems once AI writes the code aren't syntax — they're trust, lost intent, blind global judgment, and plausible-nonsense defensive code. Ed Agent stops at two deliberation checkpoints and pulls you into the reasoning instead of rubber-stamping:

Checkpoint	Asks	Catches
FRAME (after analyze)	Is the business intent captured, or is the agent guessing the project?	lost intent — the agent inferring the goal from text alone
TRUST (after review)	Should you trust it? Does the local optimum serve the global goal? Substance or ceremony?	the technically-right, business-wrong decision · over-defensive filler · LOW-trust output

A run stays IN DELIBERATION — not shippable — until you answer the open questions, even when both sign-off gates are cleared. State the intent up front; resolve the rest:

node bin/ed-agent.mjs "Add a payment retry flow"        # → IN DELIBERATION: "What is the business goal?"
node bin/ed-agent.mjs "Add a payment retry flow" \
  --intent "cut failed-payment churn" \
  --not "no auto-charge without consent; do not change the payments schema" \
  --resolve "trust: reviewed, accept the blast radius"   # → checkpoints clear

Point it at an existing artifact / diff — "should I trust this?" (no build):

node bin/ed-agent.mjs --audit pull-request.diff --intent "cut failed-payment churn" \
                      --not "do not change the payments schema"
# → Trust: LOW · ⚠ local optimum: "migrate the payments schema" does a declared NON-GOAL
#   · Substance: CEREMONY (empty catch, TODO, grand claims with no numbers) · open questions

The four assessors live in skills/trust.mjs (intent capture · trust score · global coherence · substance scan) — all deterministic, all framed as questions for you, none of them making the call.

The red team + claim grounding (v0.5)

Every build now also runs two mission-aware, deterministic passes — ~0 token (no LLM calls), because they're pure functions, not prompts. "Caring about more" costs almost nothing.

• Red team — an adversarial pass whose only job is to attack the produced artifact for what this mission cares about. The universal checks (unquantified claims · AI-tone filler · over-defensive ceremony · anything that does what a non-goal forbids) run for any business; the domain catalog adds the rest — code: injection / empty-catch / hardcoded secrets · marketing: unsourced superlatives / missing disclaimer · contract: ambiguous quantifiers / one-sided clauses · finance: a regulated claim with no anchor. It states its own coverage ("checks the loaded catalog + known anti-patterns; not exhaustive; does not replace a human expert") — so it passes its own no-confident-nonsense test.
• Claim grounding — tags every load-bearing claim Grounded (traces to a cited source or the stated goal) · Ungrounded (confident, with nothing behind it) · Contradicted (does what a non-goal forbids). The universal source is the captured intent, so it runs with zero domain pack — a bakery, a SaaS, a law firm, all the same.

Report-only by default — both are surfaced in 08b-redteam-grounding.md and do not change the verdict, so existing runs stay byte-stable. Add --strict to gate on critical findings + contradictions (they open a red-team checkpoint; resolve with --resolve "redteam: …" — the human consciously accepts; the harness never bypasses it).

node bin/ed-agent.mjs "Add a payment retry flow and migrate the payments schema" \
  --intent "cut failed-payment churn" --not "do not migrate the payments schema"
# → REDTEAM: 2 critical · grounding 1G/0U/1C   (report-only — surfaced, verdict unchanged)

node bin/ed-agent.mjs "…same…" --not "do not migrate the payments schema" --strict
# → IN DELIBERATION: red-team checkpoint open — the contradiction must be accepted or fixed

Standalone, no lifecycle: ed_agent_redteam and ed_agent_ground (MCP), or skills/redteam.mjs + skills/grounding.mjs as a library.

The inner loop — produce → verify → (rollback) (v0.6)

The whole thing so far is the chains: human gates, checkpoints, "never bypass". v0.6 adds the engine — an opt-in inner loop that refines the produced artifact before review, scored every iteration by the same deterministic assessors. It can self-correct fast precisely because four safety mechanisms keep it from running away (the "Loopmaxxing" failure mode where a loop burns the budget without converging):

1. Severity gate — a composite score from the verified assessors (red team + grounding + blind score + substance). The loop exits when severity ≤ target.
2. Overshoot rollback — a version buffer keeps the best-severity artifact. If a producer makes it worse for too long, it rolls back to the best version and stops. (The in-harness remediator is monotone so it can't overshoot; this is the safety valve for when you wire a non-deterministic host LLM as the producer.)
3. Iron-law HARD-HALT — a crossed red line (never bypass a human gate · never move a secret off-box · finance: never skip KYC/AML, never auto-move money) stops the loop immediately and opens a checkpoint. A red line is a boundary, not a judgment call — the harness never crosses it silently.
4. Budget fuse — a hard --loop-max cap. The loop can never run forever.

Every iteration writes a WHAT / WHY / PATTERN line — a court-grade audit trail of how the artifact changed and why the loop did what it did — and each iteration runs under forced amnesia (the producer sees only the current artifact + its findings, never a growing transcript, so it doesn't collapse over many iterations). The deterministic loop converges to the floor of what it can prove, then escalates the residual to a human — it never fakes a fix.

node bin/ed-agent.mjs "Add a payment retry flow" --mission code --loop   # self-correct the build
node bin/ed-agent.mjs --refine messy-draft.md --mission code --target 6   # standalone loop on a file

# → severity 47 → 18 over 4 iterations: fixed hardcoded-secret → empty-catch → AI-tone filler,
#   then PLATEAU — the residual (an unquantified claim + marketing "tell" words) is escalated, not faked.

The learning flywheel. When you reject something with a reason, Ed Agent forges a durable, machine-checkable rule into its memory and re-checks for it on every later run — each rejection makes the next run stricter about exactly what you flagged:

node bin/ed-agent.mjs --reject "trust: violates MiFID II best execution"   # forge a learned rule
# → next run lists it as a concern and the loop scores against it (deterministic, not opaque ML)

Off by default → the verdict stays byte-stable. Standalone surfaces: ed_agent_loop, ed_agent_ironcheck, ed_agent_learn (MCP), or src/loop.mjs + src/skills/ironlaws.mjs

• src/flywheel.mjs as a library. A full sample is committed in examples/sample-loop/.

The nine stages + two checkpoints

intake → context → analyze → ◆FRAME → research → ledger → plan → produce → review → ◆TRUST → certify

The middle five swap their content per mission; the spine is universal. Research cross-compares sources, compresses each claim to its load-bearing clause, and quarantines unverified ones. Plan and Certify each hold a human sign-off gate; FRAME and TRUST are deliberation checkpoints. A run is shippable only when both gates are cleared AND both checkpoints are closed.

It learns you

Ed Agent remembers your preferences in Ed_agents_Claude.md and applies them on later runs (and across hosts):

node bin/ed-agent.mjs --prefer "mission: marketing"     # default squad when none is given
node bin/ed-agent.mjs --prefer "jurisdiction: uk"
node bin/ed-agent.mjs --remember "we ship a savings product for Gen-Z in the UK"
node bin/ed-agent.mjs --like "dense data tables"  --dislike "emoji in headings"

It records likes, dislikes, preferences and concepts; recalls them at the Context stage; and applies the preferred mission / jurisdiction automatically.

The skill library — route the right method to the need

Ed Agent carries a library of 139 domain skills (src/skills/*.md — the same Markdown methods published on the portfolio). Given a need, it deterministically ranks the library by keyword/token overlap (name + id weighted, description + audience folded in) with a small mission-affinity nudge — ~0 token, no LLM. The library produces the depth; the router picks which lenses to load.

node bin/ed-agent.mjs skills "launch a marketing campaign and improve SEO conversion" --mission marketing --limit 4
# → blog-copy-humanizer · backend-data-geo-seo · seo-geo-self-audit · seo-strategy
node bin/ed-agent.mjs skills "KYC onboarding and AML for a securities broker" --mission finance
# → multi-jurisdiction-kyc-aml · us-securities-law-sec · compliance-approach …

Standalone surfaces: ed_agent_route_skills (MCP — args: need, optional mission / limit), the skills subcommand above, or src/skillrouter.mjs as a zero-dep library (routeSkills(query, {mission, limit}) · skillCatalog()). The marketing mission already loads its top methods into every plan automatically.

Run it inside Claude — pick one (no learning curve)

Full copy-paste guide: INSTALL.md. The short version:

You have	Do this	Setup
Claude Desktop	Download ed-agent.mcpb → Settings → Extensions → drag it in → Install	none — self-contained
Claude Desktop (config)	Add ed-agent → npx -y github:Edwson/Ed-Agent ed-agent-mcp to your MCP config	needs Node 18+
Claude Code	claude mcp add ed-agent -- npx -y github:Edwson/Ed-Agent ed-agent-mcp	one line

Then just talk to Claude: "list the ed-agent missions," "use ed_agent_route_skills — which methods fit launching a product with SEO?," "run ed_agent_deliberate on this diff." Nothing runs automatically; the harness surfaces the decision, you make the call.

Drop it into any bot

MCP (Claude · Cursor · Codex):

{ "mcpServers": { "ed-agent": { "command": "npx", "args": ["-y", "github:Edwson/Ed-Agent", "ed-agent-mcp"] } } }

Tools (15): ed_agent_run · ed_agent_loop (v0.6 — self-correct an artifact: severity gate · overshoot rollback · iron-law halt + the audit trail) · ed_agent_ironcheck (v0.6 — scan for crossed red lines) · ed_agent_learn (v0.6 — the flywheel: forge a learned rule from a rejection) · ed_agent_deliberate (audit any artifact/diff — "should I trust this?") · ed_agent_redteam (mission-aware adversarial scan) · ed_agent_ground (claim grounding, three states) · ed_agent_trust_scan (fast trust + substance) · ed_agent_optimize (the grand-mentor · 総監督 review) · ed_agent_quality_scan · ed_agent_missions · ed_agent_skills · ed_agent_remember · ed_agent_recall · ed_agent_route_skills (route the .md skill library to a need). Enable with npm install @modelcontextprotocol/sdk zod (optional — the CLI and library are zero-dependency).

The host loop (deep deliberation): ed_agent_run and ed_agent_deliberate return the open checkpoint questions. The host LLM (Claude/Cursor/Codex) discusses them with you, then calls the tool again with your answers in intent / resolve[] to close the deliberation. The engine surfaces the questions; the conversation — and the decision — stay between you and the host.

Any other LLM (Hermes, …): paste the operating contract from AGENTS.md into the system prompt — the host then behaves as Ed Agent.

The control room — a local dashboard

Not everyone reads code. ed-agent dashboard opens a local control room so you can see what Ed Agent is doing and tune it without the command line:

ed-agent dashboard            # → http://127.0.0.1:4317  (add --open to launch the browser)

• See every governed run — drill into any run's stages, gates, deliberation checkpoints, and per-stage estimated token cost.
• See what it cost — cumulative + per-mission est. tokens, labelled as estimates (cost governance, not a bill).
• See what it learned — the rules forged from your rejections; forget any you disagree with.
• Tune how it behaves — default mission, jurisdiction, the loop's severity target and budget, strict mode, tone, likes — saved as plain prefer:/like: lines in your Ed_agents_Claude.md (so you can still edit by hand and keep it in git). The engine applies them to unset run options next time.

It is honest by construction: a zero-dependency node:http server bound to 127.0.0.1 only, serving one page that makes zero external requests — nothing about your runs leaves the machine. It reads (and edits) the same human-readable memory file the CLI uses — the single source of truth. It's a control room over real, discrete runs, not a live always-on monitor, and it doesn't replace the CLI/MCP — it observes and tunes them.

Different from eds-mcp

eds-mcp is the design-system engine (it scaffolds compliant finance UI). Ed Agent is the special-ops orchestrator that runs the whole lifecycle across any domain — and calls eds-mcp twice over: the finance mission drives it to build compliant UI, and the optimize mission calls it to quantify a regulated surface under review (guardrail mapping · regulatory anchors · WCAG token-contrast). The engine resolves from --eds <path>, ED_AGENT_EDS_MCP, or a sibling ../eds-mcp; if absent, both run in honest contract-only mode and every other mission is unaffected.

Tests

npm test        # zero-dependency contract test: missions, skills, memory, gates
npm run test:mcp  # live MCP-protocol test (needs the optional SDK)

License

MIT © Ed Chen — edwson.com