Cognitive mode switching for every coding agent.
29 rules. 6 modes. Drop into any project.
Coding agents work better when you tell them what kind of brain to use. Planning is not review. Review is not shipping. Founder taste is not engineering rigor. Generic mode produces generic output.
NanoForge gives your coding agent 6 specialized modes — each a distinct engineering persona with explicit rules, boundaries, and behaviors. Switch gears intentionally. Get dramatically better output.
Inspired by gstack. Grounded in 29 universal rules. Agent-agnostic by design.
| Mode | Persona | What It Does | What It Doesn't |
|---|---|---|---|
| @vision | Founder/CEO | Rethinks the problem, finds the 10-star product | Write code or specs |
| @architect | Engineering Lead | Architecture diagrams, contracts, test plans | Question product direction |
| @sentinel | Staff Engineer | Paranoid code audit — finds production bugs | Fix the code |
| @ship | Release Engineer | Sync → Test → Push → PR. Lands the plane. | Decide what to build |
| @qa | QA Lead | Diff-aware testing, health-scored reports | Fix bugs it finds |
| @retro | Engineering Manager | Git-based retrospective with real data | Make code changes |
| Prompt | What It Does |
|---|---|
/plan-review |
Have Architect assess your plan |
/diff-review |
Have Sentinel audit your current diff |
/ship |
Run the Ship release workflow |
/qa |
Run QA testing |
/retro |
Run a retrospective |
# Clone and copy the config files
git clone https://github.com/MrUnreal/NanoForge.git .nanoforge-tmp
cp -r .nanoforge-tmp/.github .github/
cp .nanoforge-tmp/AGENTS.md ./AGENTS.md
cp .nanoforge-tmp/CLAUDE.md ./CLAUDE.md
cp -r .nanoforge-tmp/.cursor .cursor/
rm -rf .nanoforge-tmpWindows (PowerShell):
git clone https://github.com/MrUnreal/NanoForge.git .nanoforge-tmp
Copy-Item -Recurse .nanoforge-tmp\.github .github\
Copy-Item .nanoforge-tmp\AGENTS.md .\AGENTS.md
Copy-Item .nanoforge-tmp\CLAUDE.md .\CLAUDE.md
Copy-Item -Recurse .nanoforge-tmp\.cursor .cursor\
Remove-Item -Recurse -Force .nanoforge-tmpThat's it. Your agent will pick up the modes automatically.
| Agent | How It Works |
|---|---|
| GitHub Copilot | Modes appear in the agent picker. Skills/prompts appear after / in chat. |
| Claude Code | Reads CLAUDE.md → imports AGENTS.md. Invoke modes by name. |
| Cursor | .cursor/rules/nanoforge.mdc loads automatically. |
| OpenAI Codex | Reads AGENTS.md at project root natively. |
| Cline / Roo | Auto-detects AGENTS.md. |
| Kiro | Uses AGENTS.md as steering file. |
1. @vision → Rethink: "What should we actually build?"
2. @architect → Plan: "How do we build it? What could go wrong?"
3. [you code]
4. @sentinel → Review: "What bugs did I miss?"
5. [you fix]
6. @ship → Land: sync, test, push, PR
7. @qa → Verify: systematic testing with evidence
8. @retro → Reflect: data-driven retrospective
You don't have to use all modes. Use the ones that fit your workflow. The key insight: switching modes intentionally produces better output than staying in generic mode.
Vision mode — rethink a feature request:
@vision I want to add a notifications feature to our app.
Vision will challenge the literal request and propose the version that actually solves the user's problem.
Sentinel mode — review your changes:
@sentinel Review the changes in this branch.
Sentinel will read every changed file and produce a severity-rated audit report.
Ship mode — land a branch:
@ship Land this branch.
Ship will sync, test, push, and open a PR — stopping if anything fails.
your-project/
├── AGENTS.md ← 29 rules (read by all agents)
├── .github/
│ ├── agents/
│ │ ├── vision.agent.md ← Founder/CEO
│ │ ├── architect.agent.md ← Eng Lead
│ │ ├── sentinel.agent.md ← Paranoid Reviewer
│ │ ├── ship.agent.md ← Release Engineer
│ │ ├── qa.agent.md ← QA Lead
│ │ └── retro.agent.md ← Eng Manager
│ ├── skills/
│ │ ├── ship/ ← Release automation (ps1 + sh)
│ │ ├── qa/ ← QA testing (scripts + templates)
│ │ └── retro/ ← Retrospective (scripts + templates)
│ └── prompts/
│ ├── plan-review.prompt.md ← Quick: review a plan
│ └── diff-review.prompt.md ← Quick: review a diff
├── CLAUDE.md ← Claude Code wrapper
└── .cursor/rules/nanoforge.mdc ← Cursor wrapper
- Agent-agnostic — native files for every major agent, no vendor lock-in
- Rules-grounded — each mode maps to specific rules from a researched framework
- Progressive loading — AGENTS.md is ~200 tokens; modes load only when invoked
- Cross-platform — PowerShell + Bash scripts, no compilation required
- No dependencies — pure markdown and shell scripts, nothing to install
NanoForge is built on 29 universal coding agent rules distilled from 400+ authoritative sources. Every mode activates a specific subset.
See AGENTS.md for the full list, or the agent-rules project for the research behind them.
| Most-Used Rules | Modes That Use Them |
|---|---|
| Rule 3 (Verify Work) | Sentinel, Ship, QA |
| Rule 14 (Agent Environments) | Architect, QA, Retro |
| Rule 8 (Structured Workflows) | Architect, Ship |
| Rule 2 (Plan First) | Vision, Architect |
- gstack by Garry Tan — the original "explicit gears" idea. NanoForge is the agent-agnostic equivalent.
- agent-rules — 29 rules from 400+ sources. The rules backbone that makes NanoForge's modes precise rather than just opinionated.
MIT — use it, fork it, ship it.