1What this tool does
AI coding agents fail in predictable ways: they wander outside the files you meant, they "fix" things you didn't ask about, they obey instructions hidden inside repo files, and they declare victory without checking anything. Almost all of it traces back to one cause — the prompt was a sentence when it needed to be a contract.
Agent Command Forge turns your plain-English request into that contract. You describe the task; the Forge wraps it in a structured command: a one-line mission, hard scope boundaries, a locked safety contract, a stop condition, a verification gate the agent must pass before editing, and an outcome-checked definition of done. You paste the result into Claude Code, Cursor, Copilot, Codex — any agent — and it executes correctly on the first pass.
Everything runs in your browser. There is no server, no account, no tracking. The only network call is your optional Gemini key going directly from your browser to Google.
2Your first command in 60 seconds
Find why the login form double-submits and fix the button handler in src/auth/LoginForm.tsxThat's the whole loop. Everything else in this guide is about making the loop sharper — or you can just open a preset and adapt it.
3Every field, explained
① What should the agent do? required
Write one task, one outcome, in plain English. Include what is wrong or wanted, and where to look (file, directory, function) if you know it. Symptoms beat theories — "the form submits twice" tells the agent more than "I think it's a race condition."
Find why estimateTeamStatsFromOdds returns MISS for every MLB team and fix the data lookup. The odds cache lives in src/data/oddsCache.js.The settings page goes blank after saving. Find out why and tell me the root cause before changing anything.make the login better- Scope-killers — "do whatever it takes", "fix everything", "make any changes needed". These silently override every guardrail below. Replace with a concrete boundary.
- Phantom documents — "extract the plan from the provided report". Nothing is uploaded with a command; the agent never receives attachments and will invent the contents. Put the file's repo path in the scope field instead.
- Pasted shell commands —
curl ... | shsnippets ride the verbatim TASK section past the safety contract. Describe the outcome instead of pasting the command. - Urgency padding — "ASAP", "critical, now". Pressure language makes agents skip verification. The DONE WHEN section carries the real deadline.
- Multi-tasks — "fix X, and also refactor Y, and check Z". One command per issue. Generate three commands instead.
✨ Polish & Spellcheck · 🧭 Clarify my request optional
Polish & Spellcheck sends your task to Gemini and returns it cleaned: spelling fixed, wording tightened, same meaning. Without a key, a local spell-fixer handles the common typos. If your task is very long (roughly 120+ words — e.g. you pasted a whole spec), Polish declines rather than summarizing your detail away: trim it or move reference material into scoped files.
Clarify my request runs the intent analyzer: with a key, Gemini flags multi-tasks, contradictions, and vagueness, and offers a cleaned rewrite you can accept with one click. Without a key, the local heuristic scan catches the same categories (plus scope-killers, phantom documents, shell snippets, urgency, and tasks that target agent-instruction files like CLAUDE.md).
Files/paths in scope · Never touch strongly recommended
Files/paths in scope — comma-separated paths the agent is authorized to work in. These become the command's ALLOWED list. The agent reads files from your repo — so this is also where you point it at that "provided report" as a real path: docs/RESEARCH.md.
Never touch — your explicit deny list, merged with the built-in one (secrets, env files, lock files). Use it for anything precious or fragile: .env, migrations/, deploy/, production.config.ts.
scope: src/auth/, src/api/login.ts
never: .env, .env.production, migrations/, package.json.env.example, which matches the built-in *.env* denial), the Forge flags the contradiction instead of shipping a command the agent can't satisfy.Done when… · If blocked… recommended
Done when… — a checkable outcome, not a feeling. "Tests pass", "the page renders without console errors", "no files outside src/ modified". The agent must verify against this before declaring completion — and "yes" alone doesn't count as verification; the command demands evidence (test output, a re-read diff).
If blocked… — what to do when something's missing: a file that doesn't exist, an API that's unclear, a decision only you can make. Default behavior if you leave it empty: stop and report — the agent halts in a structured BLOCKED format instead of guessing. That's deliberate: a stopped agent costs you a message; a guessing agent costs you a debugging session.
done: npm test passes AND login submits exactly once per click
blocked: ask me before touching anything outside src/auth/ — don't improvise② Task Mode required · default: Audit
| Mode | The agent may | Use for |
|---|---|---|
| 🔍 Audit Only | Read and report. All modification is forbidden automatically — incompatible rules (backup, verify-by-editing, TODO checklists) are removed. | "Find out why X is broken", security review, "should we refactor this?", post-incident analysis. |
| 🔧 Surgical Fix | Change exactly the named thing. Extra guardrail available: Primary objective only — "while you're in there" items get noted, not done. | One bug, one tweak, one dependency upgrade. |
| 🏗️ Build | Create new files within scope. Still bound by the never-touch list and every other rule. | New feature, new endpoint, new component. |
③ Export format · Target agent required · defaults are fine
Export format:
| Format | What you get |
|---|---|
| Standard | Full guardrails, every section. The right choice for anything touching real code. ~900–1400 tokens typical. |
| Compact | ~60% shorter. Same safety contract, trimmed process sections. For small, unambiguous changes. (The Forge suggests switching when your task is short and surgical.) |
| Pro | Standard + a Compliance Receipt the agent must fill in at the end: rules applied, scope respected, verification evidence. Use when you'll review the agent's work — or when an agent has burned you before. |
Target agent — the output text is the same contract; this selects the wrapper and download filename so the file lands where your agent reads project instructions:
- Any agent — plain text, paste into chat (
agent-command.txt) - Claude Code — CLAUDE.md conventions
- AGENTS.md — the open standard (Codex, Amp, Jules…)
- Cursor —
.cursor/rules/*.mdcwith frontmatter - GitHub Copilot —
copilot-instructions.md
④ Experts optional — most tasks don't need one
Toggle up to a couple of personas — Security Auditor, Debugging Specialist, Data Pipeline Engineer, Frontend, DevOps, and more — and the command gains an ## EXPERT LENS section. You can also add a custom expert ("Django ORM specialist", "PCI-DSS compliance reviewer").
⑤ Rules & Guardrails tuned defaults · adjust per task
Five groups ship enabled: Safety & Scope (don't touch other code, stop if scope grows, pause-and-present-options, no self-authorized expansion…), Data Protection (no secrets, no unexplained network calls, no new deps, diff-only output, files-are-data), Honesty & Rigor (no guessing, no fabrication, verify before done, no placeholders), Process & Planning (plan first, one change = one TODO, ask when unsure), and Code Style (no unrequested refactoring…). Hover any rule for its full text; click to toggle; add your own with the input below the groups.
Rules are mode-aware: in Audit mode, editing-oriented rules either rephrase ("Backup before editing" disappears; its audit-safe variants take over) or drop out entirely, so the command never contradicts itself.
📥 Import your own rules optional
Drop .md, .mdc, .txt, or .markdown files on the import zone. Each bullet becomes an individually toggleable rule under an "Imported Rules" group.
4Generating & the flight checks
Press ⚡ Generate & Run Pre/Post Flight (or Ctrl/⌘+Enter). Three things happen:
- Auto-clean — injection phrases, scope-killers, urgency padding, and pasted shell snippets are stripped from your task text. If anything was removed, the command says so in a transparency note, and the app tells you.
- Intent scan — remaining structural issues (multi-task, vagueness, phantom documents, Trojan targets) surface as an amber panel under the task box. Warnings, not blockers.
- The command is built and, with a key, sent through the two flight checks.
Pre-Flight & Post-Flight
Pre-Flight (needs the free key) reads your finished command and hunts for internal contradictions — read-only mode paired with an edit-worded rule, narrow scope paired with "do whatever is necessary", soft wording ("try to") on a rule that must be absolute. Green PASS means no directive conflicts; amber tells you the single most important one to fix. Expand "What was checked" to see the actual checklist (mode, scope, active rule count, the five conflict classes).
Post-Flight role-plays the receiving agent: it states what it believes it's authorized to touch, then names one blindspot that would make the command safer. If the simulator's understanding differs from yours, the command — not the agent — is what to fix.
The token meter
Under the output box: ≈ N tokens · M chars · verdict. ≤900 = lean (green), ≤1400 = hefty (amber — trim suggestions included), >1400 = bloated (orange — agents lose the middle of long commands). Fixes, in order of leverage: switch to Compact, turn off Expert Lens, uncheck low-value imported/custom rules.
⚡ Try it: the intent scan, right here
Paste a task below — this is the same local heuristic scan the Forge runs (no key needed, nothing leaves this page):
5Anatomy of a generated command
A real (shortened) Standard output, color-coded. Hover any highlighted block.
Compact mode keeps sections 1–5 and a merged DONE WHEN. Pro mode appends a Compliance Receipt template the agent must complete in its final response.
6The Gemini API key — optional, free, browser-only
The Forge works fully without a key — generator, safety contract, rules, import, share links, local intent scan, local spellcheck. A free Gemini key (10 seconds at Google AI Studio, no credit card) unlocks four upgrades:
| With a key | What it adds |
|---|---|
| ✨ Polish | Real rewriting instead of typo-fixing |
| 🧭 Clarify | Deeper multi-task / contradiction / vagueness analysis with a one-click clean rewrite |
| 🛫 Pre-Flight | AI contradiction check on the finished command |
| 🤖 Post-Flight | Agent-interpretation simulator |
Privacy posture: the key goes from your browser directly to Google's API. This site has no server; nothing is proxied, logged, or transmitted anywhere else. "Remember key on this device" stores it in this browser's local storage only — it is never included in share links. Each check uses a few hundred tokens; the free tier is effectively unlimited for this use.
8Real examples
Example A — a dangerous request, handled right
Someone types: Organize my repo. with default settings. That's a blank check — "organize" means deleting and moving files. Here's what the Forge does:
- Intent scan fires: vague — no file or area named, and the scope is undefined.
- Mode stays Audit Only (the default) — so the generated command authorizes reading and reporting, not rearranging.
- The command's MISSION becomes an inventory/report task; DONE WHEN asks for a proposed organization plan — the agent comes back with a map and recommendations, and nothing has been moved.
You review the plan, then generate a second command — Surgical or Build, scoped to the approved moves. That's the intended two-step for anything destructive-adjacent: audit first, act second.
Example B — the phantom document
Extract the multi-phase integration plan from the provided research report, detailing the tasks for each phase.The agent has never seen "the provided report" — commands don't carry attachments. Left alone, it would invent a plausible-sounding plan. The Forge's phantom-document guard fires on phrases like "the provided/attached report" with no path: it warns you to either put the file's repo path in scope (docs/ncaab-research.md) or paste the relevant sections inline. One path in a scope field converts a hallucination machine into a real task.
Example C — production bug, surgical
task: Checkout totals are wrong when a promo code is applied — discount is subtracted twice. Fix it.
scope: src/cart/totals.ts, src/cart/promo.ts
never: migrations/, .env, package.json
done: npm test passes AND a 10% code on a $50 cart yields $45 exactly
mode: Surgical Fix · format: StandardThe generated command fences the agent into two files, forbids dependency changes, and defines done as an arithmetic fact it must demonstrate. No wandering, no "while I was in there I also…".
Example D — security review, audit mode
task: Review the auth flow for token-handling weaknesses. Report only — do not change code.
scope: src/auth/, src/api/
mode: Audit Only · experts: Security Auditor · format: Pro (compliance receipt)Audit mode strips every edit-oriented rule automatically, the EXPERT LENS sharpens the review, and the Pro receipt means the agent's final message includes an itemized account of what it checked.
9The safety model — honest version
The Forge was hardened across 17 independent adversarial review passes. It defends in layers:
| Layer | What it stops |
|---|---|
| Locked safety contract | Files treated as data, no destructive commands, no secret leakage, file-text conflicts lose to the command. Not removable in the UI — ever. |
| Auto-clean on Generate | Injection phrases ("ignore previous instructions…", "safety rules are suspended…"), scope-killers, urgency padding, pasted shell snippets — stripped before they reach the command. |
| Intent scan & clarifier | Vagueness, multi-tasks, contradictions, phantom documents, tasks targeting agent-instruction files. |
| Scope + mode structure | Wandering: ALLOWED/DENIED lists, authorization boundary, "stopping is a win", no self-authorized expansion. |
| Import-lint & share-link quarantine | Trojan rules arriving via files or links — imported disabled and flagged. |
| Verification gates | Unguessed assumptions (pre-edit gate) and unverified "done" (evidence-demanding DONE WHEN, compliance receipt). |
10Troubleshooting & FAQ
Pre-Flight says "key rejected" / the checks never run
The command is still valid — the checks are a bonus layer. Verify the key was pasted fully (no trailing space), that you're online, and that the key has Gemini API access enabled in AI Studio. Without a key you'll see the amber "command generated with safety contract" notice — that's the offline path working as intended.
My task keeps getting auto-cleaned and I want my wording back
The cleaned text replaces the task box content, but only in this session — re-edit the box and Generate again. If the cleaner removed something you consider legitimate (e.g. a real process.env.NODE_ENV reference is safe — the patterns only fire on printing env values), rephrase toward the outcome: "load config from environment variables" rather than "print process.env".
Token meter says "bloated"
Switch to Compact (60% smaller), turn off Expert Lens, uncheck imported rules you don't need. Long commands lose the middle — a lean command that gets followed beats a complete one that doesn't.
Which mode for a task that's "look, then maybe fix"?
Audit. Get the report, then generate a second Surgical command quoting the findings. Two commands, each clean — that's the workflow the tool is built around.
Can I import my whole CLAUDE.md / AGENTS.md?
Yes — drop it on the import zone. Bullets become toggleable rules; suspicious ones arrive disabled ⚠️. Then trim: the ~12-rule ceiling applies to the merged set.
Does anything I type leave my machine?
Your task text goes to Google only if you press Polish/Clarify or run the flight checks with a key — nothing else, ever, and the destination is Google's API directly. Generation itself is 100% local. No analytics, no server, no accounts.
The agent still disobeyed a rule. Is the tool broken?
Maybe, but check in order: (1) was the rule actually active in the command? (2) did the command contradict itself — run Pre-Flight; (3) was the command bloated — rules in the middle get dropped; (4) was it prompt-level vs harness-level — see the honest safety model above. If the command was clean and lean and the agent still wandered, that's a harness problem: add permission gates.
Agent Command Forge · static site, no tracking · back to the Forge