Stop Shipping Broken Code: Nanostack Forces AI Agents to Think First

Stop Shipping Broken Code: Nanostack Forces AI Agents to Think First

Your AI agent just shipped a "simple notification feature" that took three weeks, introduced two security vulnerabilities, and quietly refactored half your codebase. You only noticed when production broke on a Friday evening. Sound familiar?

Here's the dirty secret nobody talks about: AI coding agents are productivity traps disguised as productivity tools. They generate code at insane speeds, but without structure, they drift, over-engineer, and ship disasters. Every vague prompt becomes an unscoped mess. Every "quick fix" mutates into a silent refactor. Security audits happen quarterly—if at all—while vulnerabilities ship daily.

What if your agent had to earn every commit? What if it challenged your requirements before writing a single line? What if review, security, and QA were non-negotiable gates, not optional afterthoughts?

Meet Nanostack—the minimal AI coding agent framework that transforms chaotic code generation into a disciplined engineering workflow. No cloud lock-in. No build steps. Just plain text skills that force your agent to think, plan, review, audit, test, and ship with a complete paper trail. Inspired by Garry Tan's gstack, Nanostack gives your AI agent the delivery structure that separates weekend hobby projects from production-grade software.

Ready to stop cleaning up your agent's messes? Let's dive into how Nanostack rewrites the rules of AI-assisted development.

What is Nanostack?

Nanostack is a minimal, local-first framework that equips AI coding agents with 13 built-in team skills across a seven-phase delivery sprint. Created by garagon and inspired by Garry Tan's gstack, it addresses a critical gap in the AI coding revolution: agents that can write code but cannot ship it responsibly.

The framework operates on a radical premise: your agent already knows how to code. What it lacks is when to challenge, what to scope, and how to verify. Nanostack provides that structure through plain text skill files that any supported agent can load and execute.

Verified adapters today: Claude Code, Cursor, OpenAI Codex, OpenCode, and Gemini CLI. The skill files are plain text, so other agents may load them, but only these five have verified adapters with capability declarations in the adapters/ directory.

What makes Nanostack genuinely different from the sea of "AI workflow tools"? Three principles:

• Plain text skills — No proprietary formats, no vendor lock-in. Skills are readable, editable, version-controllable markdown^{↗ Smart Converter} files.
• Local artifacts — Every sprint produces persistent evidence under .nanostack/: plans, reviews, security audits, QA results, and sprint journals. Your data never leaves your machine unless you choose.
• No Nanostack cloud, no build step — Install with npx create-nanostack and run. No servers to configure, no Docker^{↗ Bright Coding Blog} containers, no CI pipelines to wire up.

The framework is trending now because it arrives at a pivotal moment. Developers are waking up to the hidden costs of raw AI coding: technical debt accumulated at machine speed, security blind spots, and the cognitive overhead of reviewing AI-generated changes that lack context. Nanostack doesn't replace your agent—it disciplines it.

Key Features That Force Rigor

Nanostack's power lies in its systematic enforcement of engineering discipline. Here's what each phase delivers:

The Default Sprint: Seven Phases of Accountability

Two Profiles, Same Standard

Nanostack adapts its explanation, not its rigor:

• Guided profile: Plain language, one next action, safer defaults, no jargon. Perfect for non-technical stakeholders or learning the workflow.
• Professional profile: Denser output, deeper tradeoffs, explicit files, commands, and risks. For senior engineers who want maximum signal.

Intensity Modes for Practical Speed

Not every change needs a full audit. Three modes keep the workflow pragmatic:

• --quick: Typos, config, docs. Only report the obvious.
• Standard (default): Normal features and bug fixes.
• --thorough: Auth, payments, infrastructure. Flag everything suspicious.

The Guard: Six-Tier Safety System

Inspired by Claude Code's auto mode, /guard evaluates every command through six tiers: block rules (mass deletion, secret reads, production deploys), allowlist for safe commands, in-project verification, phase-aware concurrency (blocks writes during read-only phases), phase gate (blocks git commit until review/security/QA pass), and budget gate (hard-blocks at 95% spend). When guard blocks a command, it suggests a safer alternative—no manual intervention needed.

Knowledge Compounding with /compound

Every sprint documents solved problems: bugs, patterns, decisions. Solutions evolve across sprints with validated and applied_count tracking. /nano and /review search past solutions automatically, ranked by proven value. Solutions that prove themselves graduate into permanent skill rules.

Real-World Use Cases Where Nanostack Shines

1. The Startup Founder Shipping Solo

You're building alone with Claude Code open 14 hours a day. Without structure, every feature request becomes a rabbit hole. Nanostack's /think forces you to articulate why before how. That "notification system" becomes a "red dot on the nav icon" that ships in hours, not weeks. The sprint journal preserves decisions so you don't re-debate them in three months.

2. The Platform Team Preventing Incidents

Last month's public S3 bucket incident still stings. With Nanostack, /think reframes "build a security scanner" into "deploy a prevention gate that blocks public S3 before it reaches production." /security runs on every ship, not once per quarter. The phase gate ensures no commit bypasses audit.

3. The Agency Delivering Client Work

Clients change requirements mid-sprint. Nanostack's scope drift detection in /review catches when your agent "helpfully" refactored the auth system while adding a button. The plan artifact from /nano becomes a contract: these files, these changes, nothing else. PR descriptions from /ship explain the why, not just the what.

4. The Multi-Agent Engineering Team

Three agents running simultaneously? /conductor coordinates parallel sessions without daemons or message queues. Review, QA, and security run in parallel after build completes. Atomic locking via mkdir, JSON state, symlink handoff—brutally simple, brutally effective. Session resume after crashes. Budget circuit breakers prevent runaway spending.

5. The Compliance-Conscious Enterprise

Custom workflow stacks compose domain-specific phases: /license-audit, /privacy-check, /release-readiness. All inherit the same artifact store, resolver, journal, and analytics as built-in skills. No SaaS dependency means no vendor security review. No data leaves your infrastructure.

Step-by-Step Installation & Setup Guide

Recommended: One-Command Install

npx create-nanostack

This detects your installed agents, installs all skills, and runs interactive setup. Verified for Claude Code, Cursor, OpenAI Codex, OpenCode, and Gemini CLI.

After installation, run /nano-run in your agent to configure your project through conversation. On your first sprint, /think shows the full pipeline so you know what comes next.

Alternative: Git Clone (Advanced Users)

For full control including skill rename, analytics, sprint journal, and project setup:

git clone https://github.com/garagon/nanostack.git <path>
cd <path> && ./setup --host auto

Target options: claude, codex, cursor, opencode, gemini, or auto for detection.

Gemini CLI Specific Install

gemini extensions install https://github.com/garagon/nanostack --consent

Post-Install Project Setup

Run once per project to configure permissions and .gitignore:

~/.claude/skills/nanostack/bin/init-project.sh

This creates .claude/settings.json with permissions so Claude Code doesn't interrupt workflow for every file creation or bash command. It also adds .nanostack/ to .gitignore.

Skill Rename (If Conflicts Exist)

cd ~/.claude/skills/nanostack
./setup --rename "review=my-review,security=my-security"

Other useful commands:

./setup --list           # show current skill names
./setup --rename reset   # restore original names

Update Workflow

/nano-update

Or from terminal: ~/.claude/skills/nanostack/bin/upgrade.sh

Requirements

• macOS or Linux shell environment (Windows: Git Bash or WSL)
• bash
• git
• jq (brew install jq, apt install jq, or choco install jq)
• One verified AI coding agent

Critical note: Nanostack has no app runtime dependency and no build step. The scripts use standard local tools.

REAL Code Examples from the Repository

Let's examine actual patterns from Nanostack's implementation, with detailed explanations of how each mechanism works.

Example 1: The Phase Gate Enforcement Hook

On Claude Code, the most powerful enforcement happens at the PreToolUse hook layer. Here's how git commit gets blocked until quality gates pass:

# This runs transparently before every git commit when Nanostack is active
# The hook checks: do fresh /review, /security, and /qa artifacts exist?
# Are they newer than the latest code change?
# If NO → exit 1 with specific guidance on what's missing
# If YES → proceed normally

# Bypass for non-sprint commits:
NANOSTACK_SKIP_GATE=1 git commit -m "hotfix: emergency patch"

Why this matters: The hook operates at the system call layer, not the "please follow instructions" layer. Even if your agent judges a task as "simple" and tries to skip review, the commit physically cannot proceed. This is L3 enforcement—the strongest level Nanostack defines. Compare to Cursor or Codex where the same workflow runs as guided instructions (L0): the agent should follow them, but nothing technically prevents skipping.

Example 2: Guard Rule Configuration

All safety rules live in guard/rules.json. Here's how you add custom protection:

{
  "id": "G-100",
  "pattern": "terraform destroy",
  "category": "infra-destruction",
  "description": "Destroy all Terraform-managed infrastructure",
  "alternative": "terraform plan -destroy first to review what would be removed"
}

The six-tier evaluation order matters critically:

1. Tier 1: Block rules run first—find . -delete gets blocked even if find is on the allowlist
2. Tier 2: Allowlist skips remaining checks for safe commands like git status, ls, cat
3. Tier 3: In-project allows operations touching only files inside the git repo
4. Tier 4: Phase-aware concurrency blocks writes during read-only phases (review, QA, security)
5. Tier 5: Phase gate blocks git commit/git push until review+security+QA artifacts exist
6. Tier 6: Budget gate hard-blocks at 95% spend—agent can run ls to save work, but nothing else

The deny-and-continue pattern: When guard blocks a command, it doesn't just reject—it suggests a safer alternative. The agent reads this and retries automatically. No manual intervention, no workflow interruption.

Example 3: Autopilot Workflow Trigger

After brief approval, the full sprint runs automatically:

# Interactive phase: agent asks questions, you answer, you align on brief
/think --autopilot

# After brief approval with required fields, automatic execution:
# /nano → build → /review → /security → /qa → /ship

# Status updates between steps:
# Autopilot: build complete. Running /review...
# Autopilot: review clean (5 findings, 0 blocking). Running /security...
# Autopilot: security grade A. Running /qa...
# Autopilot: qa passed (12 tests, 0 failed). Running /ship...

Critical safety mechanisms in autopilot:

• Brief validation required: /think --autopilot always produces a brief first. If required fields (value_proposition, target_user, narrowest_wedge, key_risk, premise_validated) are missing, it stops and asks one focused question.
• No field invention: The agent cannot invent fields to keep moving.
• Explicit premise handling: If premise isn't validated, the brief must say so explicitly. Nanostack steers toward a probe instead of pretending the idea is proven.
• Loop guard: Detects 2+ phases with no repository changes (agent is stuck) and stops.

Example 4: Parallel Sprint Coordination

# Initialize session with business context
session.sh init development --goal "Pass SOC2 audit by July"

# The goal propagates through resolver to every phase:
# /think frames scope decisions against SOC2 requirements
# /review prioritizes compliance-related findings
# /security weights compliance checks higher

# Check execution batches for parallel agents
sprint.sh batch
# Output: review, qa, security can run in parallel (all depend on build, not each other)

# Agent joining mid-sprint asks: what should I claim?
sprint.sh next
# Prints first unclaimed phase with dependencies met and no active lock

# Force-release stuck lock from crashed agent (PID dead)
sprint.sh unstuck review
# Refuses if PID is alive; --force override available with warning

The atomic coordination mechanism: No daemon, no message queue. Just mkdir for atomic locking, JSON for state, symlinks for artifact handoff. sprint.sh batch reads each skill's concurrency metadata (read, write, exclusive) and outputs execution groups automatically.

Example 5: Knowledge Graduation Pipeline

# After shipping, document what you learned
/compound
# Reads sprint artifacts → identifies problems solved
# Writes to .nanostack/know-how/solutions/bug/
# Writes to .nanostack/know-how/solutions/pattern/
# Writes to .nanostack/know-how/solutions/decision/

# Solutions evolve: applied_count++, validated flag, confidence adjusted
# +2 if worked perfectly, -2 if failed

# Search past solutions manually
bin/find-solution.sh "stripe webhook"        # keyword search
bin/find-solution.sh --type bug              # filter by type
bin/find-solution.sh --tag security          # filter by tag
bin/find-solution.sh --file src/api/webhooks # file-specific

# When solution proves itself (3+ applications, validated, files exist):
bin/graduate.sh              # dry run: show candidates
bin/graduate.sh --apply      # insert as permanent rule in SKILL.md
bin/graduate.sh --status     # show budget: rules per skill vs caps
bin/graduate.sh --prune      # detect stale rules (referenced files gone)

Graduation caps prevent skill bloat: review (10 rules), plan (8 rules), security (8 rules). A graduated rule is a one-line check applied every sprint without runtime solution search. The original solution stays in the knowledge base with graduated: true for full history.

Advanced Usage & Best Practices

Start with /think --retro, Not /think

Before planning your next sprint, reflect on the last one. The retro reads sprint journals, compound solutions, pattern reports, and git metrics. It surfaces recurring issues—like "third sprint with missing rate limiting findings"—and suggests graduated rule additions.

Use Goal Context for Strategic Alignment

Pass business objectives to session.sh init. The resolver propagates this to every phase, preventing tangent features that don't serve your actual targets.

Set Budget Gates Early

budget.sh set --max-usd 15 --model opus-4

The 80% warning and 95% hard block prevent the "just one more iteration" spending spiral. Override with NANOSTACK_SKIP_BUDGET=1 only for genuine emergencies.

Run /nano-doctor After Any Install

Verifies actual enforcement levels match adapter declarations. Detects drift between what should work and what really works on your specific agent version.

Build Custom Stacks for Domain Repetition

If your team repeatedly runs /license-audit, /privacy-check, and /release-readiness before shipping, compose them into a permanent stack with phase_graph. The compliance-release example proves this pattern end-to-end.

Visual Artifacts for Human Review

bin/render-artifact.sh security --latest    # OWASP/STRIDE breakdown as HTML
bin/render-artifact.sh journal --today      # Full sprint timeline

The renderer is offline-only with CSP blocking external network. Use --strict to fail on integrity mismatches. These views are optional—removing .nanostack/visual/ doesn't affect skill behavior.

Comparison with Alternatives

When to choose what:

• Raw AI agent: Quick prototypes, throwaway scripts, learning new APIs
• gstack: If you want basic structure and prefer Garry Tan's specific approach
• Nanostack: If you need enforced quality gates, knowledge compounding, multi-agent coordination, custom workflows, or operate in compliance-sensitive environments

FAQ

Does Nanostack work with my AI coding agent?

Verified adapters exist for Claude Code, Cursor, OpenAI Codex, OpenCode, and Gemini CLI. The skill files are plain text, so other agents may load them, but only these five have verified adapters with capability declarations. Claude Code offers the strongest enforcement (L3 hooks); others run as guided instructions (L0).

Is my code sent to Nanostack's servers?

Never. Nanostack has no cloud service. All artifacts, plans, journals, and know-how stay local under .nanostack/. Your AI agent provider may process context per their own policies, but Nanostack itself is entirely local-first.

Can I skip phases for urgent hotfixes?

Yes, with explicit bypass: NANOSTACK_SKIP_GATE=1 git commit -m "hotfix". The framework is honest about when protection downgrades. For non-sprint commits or genuine emergencies, bypass is available and auditable.

How does Nanostack handle agent crashes mid-sprint?

session.sh resume detects the last session state. restore-context.sh reads all completed phase checkpoints—compact summaries of ~50 tokens with key findings, files, and decisions. The agent skips completed phases and restarts from where it left off.

What's the difference between Guided and Professional profiles?

Guided uses plain language, one next action, safer defaults—ideal for learning or non-technical stakeholders. Professional provides denser output with deeper tradeoffs, explicit files, commands, and risks. The standard remains identical; only the explanation adapts.

Can I build custom skills that integrate with the full framework?

Absolutely. Custom skills inherit the artifact store, resolver, sprint journal, analytics, conductor, and local vault. The bin/create-skill.sh scaffold generates valid skills, and ci/e2e-custom-stack-flows.sh proves framework guarantees end-to-end.

How does knowledge graduation actually work?

Solutions that prove themselves (3+ applications, validated, existing files) get promoted into permanent skill rules via bin/graduate.sh --apply. These become one-line checks applied every sprint without runtime search. Each skill has a rule cap to prevent bloat. Stale rules are detected with --prune.

Conclusion

Nanostack is not another AI coding tool. It's an engineering discipline system that happens to use AI agents as its execution layer. The seven-phase sprint, six-tier guard, knowledge compounding, and honest enforcement matrix represent a fundamentally different approach to AI-assisted development: one that prioritizes shipping confidence over shipping speed.

The framework's greatest strength is its honesty. It doesn't pretend all agents enforce equally. It doesn't claim cloud features while storing data locally. It doesn't invent fields to keep autopilot moving. Every limitation is documented, every capability level is verifiable with /nano-doctor.

If you're tired of cleaning up your agent's "helpful" refactors, if you want security audits that actually run, if you need PR descriptions that explain why not just what—Nanostack delivers.

Ready to transform your AI agent from a code generator into a delivery team?

👉 Install Nanostack now with npx create-nanostack and run your first /think command. Your future self—reviewing clean, scoped, audited, tested commits—will thank you.

The repository is open source under Apache 2.0. Star it, extend it, build your own stacks on top. The future of AI-assisted engineering isn't faster chaos. It's structured delivery, and Nanostack is how you get there.