Example

What it looks like

A full sprint in 4 commands. The agent pushes back, scopes down and ships what matters.

nanostack sprint

you

I need Stripe payments. Users should subscribe to a monthly plan.

❯ /think

agent

A full billing system (plans, invoices, failed payments, customer portal) is a 2-week project. A Checkout link with one webhook ships today.

How many users do you have? If pre-launch, validate willingness to pay first.

you

200 active users. Some asked about a pro plan.

agent

Real demand. Ship: Checkout + webhook that flips is_pro. Cancellations come free with Stripe. Build invoices and plan switching after 50 subscribers.

Scope: REDUCE.

you

Checkout + webhook. Let's go.

plan❯ /nano4 steps, 3 files. Checkout + webhook + access gate.

review❯ /reviewStructural clean. Webhook signature missing. Auto-fixed.

security❯ /securityWebhook verified. No secrets in code. Grade: A.

ship❯ /shipPR #18 created. CI passing. Journal saved.

You said "payments." The agent said "validate willingness to pay first" and shipped a checkout link instead of a 2-week billing system. Install nanostack →

Workflow

The sprint

/think→/nano→build→/review→/qa→/security→/ship

skill	role	what they do
/think	Founder	Three intensity modes (Founder / Startup / Builder). Six forcing questions. Challenges scope before code is written.
/nano	Eng Manager	Auto-classifies scope (S/M/L). Generates product spec, tech spec, implementation plan. Every file listed in execution order.
/review	Staff Eng	Two-pass review: structural then adversarial. Scope drift detection against /nano plan. Auto-fixes mechanical issues.
/qa	QA Lead	Playwright for browser, curl for APIs, direct execution for CLIs. Screenshots at every state. WTF-likelihood heuristic stops at 20%.
/security	Sec Eng	Auto-detects stack. OWASP A01-A10 + STRIDE per component. Scans secrets, git history, dependencies. Graded A-F.
/ship	Release Eng	PR creation with mandatory preview stop. CI monitoring. Post-merge smoke test + 5-min metrics watch. Sprint journal.
/guard	Safety	28 block rules, 9 warn rules. Three-tier permissions. Deny-and-continue with safer alternatives.
/conductor	Orchestrator	Parallel agent sessions. Atomic locking via mkdir. Phase dependency resolution. No daemon.

Each skill supports --quick, --standard, --thorough. Quick requires 9/10 confidence to report. Thorough flags at 3/10.

/nano

Opinionated stack defaults

/nano doesn't just plan. It enforces product standards. When the output is user-facing, it picks specific tools. All defaults are configurable per project or globally.

Web app defaults

FrameworkNext.js (App Router)AuthClerk (5 min setup, free to 10K MAU)DatabaseSupabase (Postgres + auth + storage + realtime)ORMDrizzle (type-safe, no codegen, edge compatible)HostingVercel (zero-config Next.js)PaymentsStripeEmailResend (React components as templates)StorageCloudflare R2 (S3-compatible, zero egress)AI/LLMVercel AI SDK (streaming UI in ~20 lines)CSSTailwind v4 + shadcn/uiTestingVitest + Playwright (3-5x faster than Jest)StateZustand (3KB, hooks-based)ValidationZod (TypeScript-first)

Configurable

Stack defaults are configurable. Run bin/init-stack.sh to auto-detect your stack from package.json, go.mod or requirements.txt. Override per project (.nanostack/stack.json) or globally (~/.nanostack/stack.json). Only configure what you want to change.

Product standards enforced

UI: Dark mode from day one. Mobile responsive. shadcn/ui components, not raw CSS.

SEO: Semantic HTML, meta tags, Core Web Vitals, sitemap, robots.txt.

LLM SEO: JSON-LD structured data, llms.txt at root, clean URLs, Q&A-style content.

CLI: Color output, --json flag, progress indicators, actionable errors, exit codes (0/1/2).

Architecture

Cross-skill intelligence

Each skill persists a JSON artifact. The next skill reads it. Context flows through the entire sprint. When skills disagree, precedent rules resolve the conflict.

Scope drift detection

/nano→saves planned_files: ["src/Badge.tsx", "src/lib/freshness.ts"]

/review→compares planned_files against git diff// flags unplanned files

Conflict precedents (10 rules)

CP-001/review vs /security

Error detail vs information disclosure

Structured errors: code + generic user message. Full details to server logs only.

CP-003/review vs /security

Remove redundant validation vs defense in depth

Validate at trust boundaries. No duplication within boundaries.

CP-005/qa vs /review

Test every edge case vs tests block refactoring

Test observable behavior, not implementation details.

CP-007/nano vs /review

Ship 3 small PRs vs keep changes atomic

If subsets can't deploy independently, keep them combined.

CP-010/review vs /security

Cache expensive ops vs cache invalidation risks

Cache public queries with short TTL. Never cache auth decisions.

5 of 10. View all on GitHub →

// .nanostack/review/20260329-150000.json
{
  "schema_version": "1",
  "phase": "review",
  "branch": "feat/freshness-dot",
  "mode": "standard",
  "summary": {
    "blocking": 0, "should_fix": 1, "nitpicks": 1, "positive": 2
  },
  "scope_drift": {
    "status": "clean",
    "planned_files": ["src/Badge.tsx", "src/lib/freshness.ts"],
    "actual_files": ["src/Badge.tsx", "src/lib/freshness.ts"]
  },
  "conflicts": []
}

Safety

Guard

AI agents run destructive commands. Guard blocks them with a safer alternative. The agent reads the suggestion, retries with the safe version. No manual intervention.

BLOCKED [G-007]

Category: history-destruction
Command: git push --force origin main

RESOLVED

Alternative: git push --force-with-lease
Fails if remote has changed since last fetch.

28 block rules (sample)

G-001rm -rf /mass-deletionG-007git push --forcehistory-destructionG-014DROP TABLEdatabase-destructionG-017kubectl deleteinfra-destructionG-023curl | shremote-code-executionG-026chmod 777security-degradationG-027--no-verifysafety-bypass

7 of 28. Plus 9 warn rules. Full list →

Three tiers

1.Allowlistgit status, ls, cat, jq → skip all checks

2.In-projectFiles inside current git repo → version control is the safety net

3.Pattern match28 block + 9 warn rules → deny-and-continue with safer alternative

Orchestration

Parallel sprints & autopilot

/conductor coordinates multiple agents. /think --autopilot runs the full sprint unattended. All artifacts stay local.

/think

scope

→

/nano

plan

→

build

implement

→

parallel

/review Agent A

/qa Agent B

/security Agent C

→

/ship

deploy

/think → /nano → build ─┬─ /review   (Agent A) ─┐
                        ├─ /qa       (Agent B)  ├─ /ship
                        └─ /security (Agent C) ─┘

Autopilot mode

❯ /think --autopilot

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...
Autopilot: done. Sprint journal saved.

Stops for: blocking findings, critical vulns, test failures, or unanswerable product questions.

Persistence

The know-how system

Every sprint generates artifacts, journals and learnings. The knowledge compounds across sprints. Each new sprint benefits from every previous one.

.nanostack/
├── think/          # scope decisions, validated premises
├── plan/           # specs, planned_files for drift detection
├── review/         # findings, scope drift reports
├── qa/             # test results, screenshots, WTF scores
├── security/       # vulnerability reports, STRIDE models
├── ship/           # PR metadata, CI results, deploy status
├── conductor/      # parallel sprint state, phase locks
├── config.json     # project settings, agent detection, custom phases
└── know-how/
    ├── journal/    # dated sprint summaries (Obsidian-compatible)
    ├── learnings/  # accumulated insights across sprints
    └── conflict-precedents/  # resolution patterns

10 bin/ scripts

save-artifact.shPersist phase output with auto-injected timestamp, branch, projectfind-artifact.shLocate most recent artifact by phase (default: 30-day window)scope-drift.shCompare planned_files against actual git diffsprint-journal.shAggregate all phase artifacts into dated Obsidian markdownanalytics.shLocal-only sprint analytics (--month, --json, --obsidian)capture-learning.shAppend insights to know-how/learningsdiscard-sprint.shClean artifacts from failed sprints (--dry-run)init-project.shOne-time project setup (.gitignore, permissions)init-config.shAuto-detect agents and project typeupgrade.shUpdate nanostack via git pull + re-setup

Setup

Install

Recommended: git clone

git clone https://github.com/garagon/nanostack.git ~/.claude/skills/nanostack
cd ~/.claude/skills/nanostack && ./setup

Full features: rename, analytics, sprint journal, project setup.

Alternative: npx skills

-g installs globally (all projects). --full-depth installs all 8 skills. Copies files. No advanced features (rename, analytics, journal).

Alternative: Gemini CLI

Setup flags

--localProject-scoped install to .claude/skills/--host <agent>Target: claude, codex, cursor, opencode, gemini, auto--renameAvoid naming collisions ("review=my-review")--listShow installed skills and current names--rename resetRestore original skill names

Requires: macOS, Linux, or Windows (Git Bash / WSL). git, jq. No build step. Zero dependencies.

Extensibility

Extend

A skill is a folder with a SKILL.md file. Register custom phases in .nanostack/config.json and they compose with the core sprint. Stack defaults, skills and config follow three levels: project → user → defaults.

Example domains

Marketing/audience → /content-plan → /campaign → /measureData/explore → /hypothesis → /model → /validateDesign/research → /wireframe → /prototype → /usability

# my-skill/SKILL.md
---
name: deploy-aws
description: Deploy to AWS with CloudFormation
---

You are a deployment specialist. Follow these steps:

1. Validate CloudFormation template
2. Run preflight checks (account, region, permissions)
3. Deploy stack with change set preview
4. Verify endpoints respond with 200

## Next Step
Run /qa --quick to verify the deployment.

Full guide: Extending nanostack →

Philosophy

The Zen of Nanostack

1.Question the requirement before writing the code.

2.Delete what shouldn't exist. Don't optimize what's left until you do.

3.If nobody would use a broken v1, the scope is wrong.

4.Narrow the scope, not the ambition.

5.Evidence beats conviction. Conviction beats consensus.

6.Ship the version that ships today.

7.One sprint, one order. No step gets skipped.

8.Every step should know what the step before it decided.

9.Fix it or ask. Never ignore it.

10.Zero findings is an honest answer. Invented findings are not.

11.Security is not a tradeoff. It is a constraint.

12.The output should look better than what was asked for.

13.If the plan is hard to explain, the plan is wrong.

Get started

One sprint. Minutes, not weeks.

View on GitHub