nanostack
Minimal AI coding agent skills covering the full engineering workflow. Eight skills run an entire sprint: clarify intent, plan specs, detect
Open source Open in the app JSON README (API)
About
Minimal AI coding agent skills covering the full engineering workflow. Eight skills run an entire sprint: clarify intent, plan specs, detect scope drift, test with visual QA, audit security, and ship with quality checks. Skills share artifacts, accumulate knowledge between sessions, and can run end-to-end to a PR with --autopilot.
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- garagon
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 205
- Forks
- 15
- Open pull requests
- 1
- Last push
- 2026-06-15T00:03:59Z
- Repository state
- ativo
- Language
- Shell
- License
- Apache-2.0
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
garagon/nanostack/nanostack
README
<p align="center">
<img width="404" height="139" alt="Image" src="https://github.com/user-attachments/assets/839805e9-979f-4c95-9e24-eba9d7ae6236" />
</p>
<br>
<p align="center">
Your AI agent writes code. Nanostack makes sure it ships work you can trust.
</p>
<p align="center">
<em>Local delivery workflow harness for AI coding agents.</em>
</p>
<p align="center">
Scope, plan, build, review, security, QA, ship. Every step leaves evidence you can read, in plain files on your disk. Use the default sprint, or build your own workflow stack on top.
</p>
<p align="center"><strong>Open source. Plain text skills. Local artifacts. Verified adapters. No Nanostack cloud.</strong></p>
<p align="center">
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License"></a>
<a href="https://github.com/garagon/nanostack/stargazers"><img src="https://img.shields.io/github/stars/garagon/nanostack?style=flat" alt="GitHub Stars"></a>
<a href="https://skills.sh/garagon/nanostack"><img src="https://img.shields.io/badge/skills.sh-available-brightgreen" alt="skills.sh"></a>
</p>
<p align="center">
<a href="#what-is-nanostack">What is it</a> ·
<a href="#quick-start">Install</a> ·
<a href="#the-sprint">The Sprint</a> ·
<a href="#visual-artifacts">Visual artifacts</a> ·
<a href="#build-on-nanostack">Extend</a> ·
<a href="RELEASE_NOTES.md">Release notes</a> ·
<a href="README.es.md">Español</a>
</p>
<br>
Inspired by [gstack](https://github.com/garrytan/gstack) from [Garry Tan](https://x.com/garrytan). Nanostack gives your agent the working method of a small product team: it questions the scope, plans, reviews the code, audits security, tests, and ships, leaving a paper trail you can inspect at every step. Everything is plain text and local scripts under Apache 2.0, so you can read every rule your agent follows. No Nanostack cloud, no daemon, no app runtime.
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 those five have a verified adapter and capability declaration in [`adapters/`](adapters/).
What changed in the latest release (custom workflow stacks, visual artifacts, stronger safety contracts): see [`RELEASE_NOTES.md`](RELEASE_NOTES.md).
## See it work
```
You: I need to add notifications to my app. Users keep missing
replies on their posts.
You: /think
Agent: Before we build anything, how are users coping today?
You: They open the app 3-4 times a day just to check. Sometimes
they miss replies for hours. People are frustrated.
Agent: I'm going to push back on "notifications." You said users open
the app 3-4 times a day. That's high engagement. They already
come back. The problem isn't that they can't be reached. The
problem is that when they arrive, they can't tell what changed.
That's a freshness problem, not a messaging problem.
A notification system (email, push, in-app, preferences,
digest, unsubscribe) is a 3-week project. A red dot on the
nav icon that says "something new" ships this afternoon.
One solves the symptom (they're not being told). The other
solves the cause (they can't see what's new when they look).
RECOMMENDATION: Reduce. Ship the dot. See if complaints drop.
If they do, you just saved 3 weeks. If they don't, then build
push notifications, but now you have data, not a guess.
You: Makes sense. Let's do the dot.
You: /nano
[3 steps, 2 files, product standards: shadcn/ui + Tailwind]
You: [builds it]
You: /review
Review: 2 findings (1 auto-fixed, 1 nit). 2 things done well.
You: /security
No secrets, auth changes, or unsafe data flows introduced. Grade A.
You: /qa
Opened the app, posted a reply, refreshed, confirmed the dot
appears and clears. 4 checks pass.
You: /ship
PR explains why the change exists, how it was checked, and what
remains. CI green. Sprint journal saved.
```
That is the difference: not just code generation, but a delivery loop you can inspect.
## What changes after installing Nanostack
| Without Nanostack | With Nanostack |
| --- | --- |
| ❌ A vague prompt turns into code immediately. | ✅ `/think` turns the idea into a brief, risk, and smallest useful starting point. |
| ❌ The plan disappears in chat. | ✅ `/nano` saves a plan with files, risks, checks, and out-of-scope items. |
| ❌ The agent quietly refactors three things you did not ask for. | ✅ `/review` compares the code against the plan. Scope drift is visible before merge. |
| ❌ QA and security happen only if someone remembers. | ✅ `/qa` opens your app and exercises it. `/security` runs on every ship and catches the mistakes that make headlines. |
| ❌ Your PR says "add notifications" and nobody knows what actually changed or why. | ✅ `/ship` explains why the change exists, how it was checked, and what remains. |
| ❌ You rush-commit Friday 5pm and Monday find out it broke something unrelated. | ✅ The sprint blocks `git commit` until `/review`, `/security`, and `/qa` pass. (Enforcement varies by agent; see honesty matrix below.) |
| ❌ Every session re-pastes the same context: what we use, what is fragile. | ✅ Every skill reads the artifact the previous skill wrote. Sprint journals preserve decisions in `.nanostack/`. |
## Nanostack is right for you if
- ✅ You have an AI agent open all day and still feel like you ship slowly
- ✅ You want reviews that catch scope drift, not just typos
- ✅ You want a security audit before every ship, not once a quarter
- ✅ You want PR descriptions that explain the WHY, not just list files
- ✅ You want a process that works across Claude Code, Cursor, OpenAI Codex, OpenCode, and Gemini CLI
- ✅ You want the skills on disk, inspectable, not locked in a SaaS
## Try it safely first
Not sure yet? Start with a disposable sandbox from the Examples Library. It gives you a real sprint without risking your product.
| Example | Best for | Stack | Time |
|---|---|---|---|
| [`starter-todo`](examples/starter-todo/) | new and non-technical users | one HTML file | 5-10 min |
| [`cli-notes`](examples/cli-notes/) | CLI workflows | Bash | 5-15 min |
| [`api-healthcheck`](examples/api-healthcheck/) | backend flows | Node stdlib HTTP | 10-15 min |
| [`static-landing`](examples/static-landing/) | founders and designers | static HTML/CSS | 10-15 min |
| [`compliance-release`](examples/custom-stack-template/compliance-release/) | teams building a custom workflow stack | license + privacy + release gate | 15-30 min |
Each example has a copy-paste prompt, expected sprint flow, success criteria, and reset steps. Full Examples Library: [`examples/`](examples/).
`compliance-release` is advanced. It is not a starter app and it is not a compliance certification. It shows how several custom skills can compose into one release workflow.
## Quick start
```bash
npx create-nanostack
```
One command. Detects your agents, installs everything, runs setup.
Then run `/nano-run` in your agent to configure your project through a conversation. On your first sprint, `/think` shows the full pipeline so you know what comes next.
If you want to see the workflow before installing into a real repo, use one of the sandbox examples above.
## Choose your path
| If you are... | Start here |
|---|---|
| New to agent workflows | Try [`starter-todo`](examples/starter-todo/), then run `/nano-run` |
| Already shipping with AI agents | Install Nanostack, then start with `/think` or `/feature` |
| Evaluating safety | Read [Guard](#guard) and the [host enforcement matrix](#what-enforces-on-which-agent) |
| Building your own workflow | Start with [`EXTENDING.md`](EXTENDING.md) and [`compliance-release`](examples/custom-stack-template/compliance-release/) |
| Inspecting what the agent did | Render any phase as local HTML with [visual artifacts](#visual-artifacts) (`bin/render-artifact.sh`) |
## What is Nanostack?
Your agent can already edit files and run commands. Nanostack gives it a method: 13 built-in skills, a seven-phase default sprint, and a framework for composing your own workflow stacks.
The default sprint turns a request into a scoped, reviewed, security-checked, tested change with a PR and a sprint journal. Each phase writes a structured artifact: a small local file that records what was decided and what was checked. Later phases read those files instead of depending only on chat history.
The bet is artifact-first delivery:
- Skills are plain text.
- Artifacts are local JSON.
- Gates verify evidence before release.
- Visual artifacts render the same evidence as local HTML.
- Custom workflow stacks extend the same pipeline with your own phases.
On Claude Code, Nanostack can enforce parts of the workflow through PreToolUse hooks. On other agents, the same workflow runs as guided instructions. See [What enforces on which agent](#what-enforces-on-which-agent) for the honest per-host table.
The built-in sprint is the default stack:
| | Step | What the specialist does |
| ------ | ----------------- | ----------------------------------------------------------------------- |
| **01** | `/think` | Refines your rough idea through questions. Finds the smallest useful version. |
| **02** | `/nano` | Plans the implementation. Names files, risks, and checks. |
| **03** | build | You or the agent writes the code. |
| **04** | `/review` | Two-pass code review. Scope drift detection. Auto-fixes the mechanical. |
| **05** | `/security` | OWASP A01-A10 audit + STRIDE threat modeling. Graded A-F. |
| **06** | `/qa` | Tests the thing. Browser, API, CLI, or root-cause debug. |
| **07** | `/ship` | PR creation, CI verification, release notes, sprint journal. Production deployment stays explicit and user-controlled. |
## Two profiles, same rigor
Nanostack adapts the explanation, not the standard.
| Profile | What changes |
|---------|--------------|
| **Guided** | Plain language, one next action, safer defaults, no hidden jargon. |
| **Professional** | Denser output, deeper tradeoffs, explicit files, commands, and risks. |
Local mode uses Guided language by default. A git project can still use Guided if the user wants simpler explanations.
The wording rules live in [`reference/plain-language-contract.md`](reference/plain-language-contract.md). The session fields that select the profile live in [`reference/session-state-contract.md`](reference/session-state-contract.md).
## What is enforced depends on your agent
Nanostack is agent-agnostic, but agent hosts do not expose the same control points. The adapter files in [`adapters/`](adapters/) are the source of truth for each host.
| Level | Meaning |
|-------|---------|
| **L0 Guided** | The skill tells the agent what to do but cannot block it. Also covers a capability the host cannot provide at all. |
| **L1 Checked** | Nanostack can detect and report the issue, but cannot block it. |
| **L2 Guarded** | The host runs a nanostack hook before the action. |
| **L3 Enforced** | The hook can block the action and the host honors the block. |
| **L4 Continuously verified** | A CI job exercises the capability on every change. |
A detailed per-host matrix (Bash guard, Write/Edit guard, phase gate) lives further down in [What enforces on which agent](#what-enforces-on-which-agent).
## The sprint
Nanostack is a process, not a collection of tools. The skills run in the order a sprint runs:
```
/think → /nano → build → /review → /security → /qa → /ship
```
Each skill feeds into the next. `/nano` writes an artifact that `/review` reads for scope drift detection. `/review` catches conflicts with `/security` findings. `/ship` verifies everything is clean before creating the PR. On Claude Code the phase gate enforces the pipeline at the hook layer: `git commit` is blocked until review, security, and qa have fresh artifacts. On agents without hook support the same gate runs as guided instructions, so the safety depends on the agent following them; see [What enforces on which agent](#what-enforces-on-which-agent).
| Skill | Your specialist | What they do |
|-------|----------------|--------------|
| `/think` | **Product discovery** | Activates before you build. Refines a rough idea through questions, one at a time. Explores 2-3 approaches with trade-offs. Walks the design with you, section by section. Saves a brief your next steps read. Supports guided archetypes, search privacy modes (`local_only`, `private`, `public`), `--retro` for sprint reflection, and `--autopilot` after the brief is complete. |
| `/nano` | **Eng Manager** | Auto-generates product specs (Medium scope) or product + technical specs (Large scope) before implementation steps. Product standards for web (shadcn/ui), CLI/TUI (Bubble Tea, Rich, Ink, Ratatui). Stack defaults with CLI preference for beginners. |
| `/review` | **Staff Engineer** | Two-pass code review: structural then adversarial. Auto-fixes mechanical issues, asks about judgment calls. Detects scope drift against the plan. Cross-references `/security` with 10 conflict precedents. |
| `/qa` | **QA Lead** | Functional testing + Visual QA. Takes screenshots and analyzes UI against product standards. Browser, API, CLI and debug modes. WTF heuristic stops before fixes cause regressions. |
| `/security` | **Security Engineer** | Auto-detects your stack, scans secrets, injection, auth, CI/CD, AI/LLM vulnerabilities. Graded report (A-F). Cross-references `/review` for conflict detection. Every finding includes the fix. |
| `/ship` | **Release Engineer** | Pre-flight + repo quality checks. PR creation, CI monitoring, sprint journal. After commit, asks: run locally, deploy to production, or done. Production path guides through hosting, domain, monitoring, costs. |
### Power tools
| Skill | What it does |
|-------|-------------|
| `/compound` | **Knowledge** | Documents solved problems after each sprint. Three types: bug, pattern, decision. Solutions evolve across sprints: validated and applied_count track which solutions actually work. `/nano` and `/review` search past solutions automatically, ranked by proven value. Checks if any solutions are ready to graduate into skill files. |
| `/guard` | **Safety** | Layered safety: block rules run first, then the global gates run before any allowlist or in-project shortcut (phase-aware concurrency that blocks writes during read-only phases, phase gate that blocks commit/push until review+security+qa pass, and budget gate), so a safe-listed or in-project command cannot skip them. Safe reads (git status, ls, cat) are allowlisted only after those gates pass. Write/Edit hooks deny protected secret and system paths after resolving symlinks, and block every Write/Edit/MultiEdit during a read-only phase via the same shared concurrency check. Blocked commands get a safer alternative. `/freeze` asks the agent to keep edits within one directory (guided, not hook-enforced). Rules in `guard/rules.json`. |
| `/conductor` | **Orchestrator** | Parallel agent sessions with auto-batching. `sprint.sh batch` reads skill concurrency metadata and groups parallel-safe phases. Session resume on crash. Dependency validation before each phase. No daemon, just atomic file ops. |
| `/feature` | **Builder** | Add functionality to an existing project. Skips /think, goes straight to plan, build, review, audit, test, ship. |
| `/nano-run` | **Onboarding** | First-time setup. Reads session profile and host capabilities, writes a setup artifact, detects legacy installs, and refuses silent permission repair. Configures stack, permissions, and work preferences through a conversation. |
| `/nano-help` | **Reference** | Quick reference for all nanostack commands and how to use them. |
### Intensity modes
Not every change needs a full audit. `/review`, `/qa` and `/security` support three modes:
| Mode | Flag | When to use |
|------|------|-------------|
| **Quick** | `--quick` | Typos, config, docs. Only report the obvious. |
| **Standard** | (default) | Normal features and bug fixes. |
| **Thorough** | `--thorough` | Auth, payments, infra. Flag everything suspicious. |
### Specs by scope
`/nano` generates specs automatically based on project complexity:
| Scope | What you get |
|-------|-------------|
| **Small** (1-3 files) | Implementation steps only |
| **Medium** (4-10 files) | Product spec + implementation steps |
| **Large** (10+ files) | Product spec + technical spec + implementation steps |
The product spec covers: problem, solution, user stories, acceptance criteria, user flow, edge cases, out of scope. The technical spec adds: architecture, data model, API contracts, integrations, technical decisions, security considerations, migration/rollback.
Specs are presented for approval before implementation. If the spec is wrong, everything downstream is wrong.
## Full sprint walkthrough
```
You: I want to build a security scanner for cloud misconfigurations.
We keep finding S3 buckets left public and IAM roles that are
way too broad. Last month a public bucket caused an incident.
You: /think
Agent: I'm going to push back on "security scanner." A scanner finds
problems after they exist. But you said last month a public
bucket caused an incident. You don't want to find misconfigs,
you want to stop them from reaching production.
That's a prevention gate, not a scanner. Different product.
The scanner is 10% better than what you have (manual audits).
A pre-deploy gate is 10x. The misconfiguration never ships.
Who would use a broken v1 tomorrow? Your platform team. They
got paged for that incident. They'd use anything that blocks
public S3 buckets before deploy, even if it only checks one rule.
RECOMMENDATION: Reduce scope. One rule. S3 public access check,
pre-deploy. Ship tomorrow. The full scanner is a 3-month project.
You: That makes sense. Let's start with S3.
You: /nano
[5 steps, 4 files, risks listed, out-of-scope explicit]
You: [builds the feature]
You: /review
Review: 3 findings (2 auto-fixed, 1 ask). Scope drift: CLEAN.
You: /security
Security: CRITICAL (0) HIGH (0) MEDIUM (1) LOW (1). Score: A.
You: /qa
Provisioned a sandbox bucket, attempted a public-grant
action, confirmed the gate blocked it, confirmed normal
ops still work. 8 checks pass.
You: /ship
PR ready. CI passed. Sprint journal saved.
```
You said "security scanner." The agent said "you're building a prevention gate" because it listened to your pain, not your feature request. Seven commands, start to shipped.
## Think brief
Every `/think` run saves a shareable markdown brief to `.nanostack/know-how/briefs/`. Not the JSON artifact. A clean document you can send to your team, paste into a doc, or open in Obsidian.
```markdown
# Think Brief: S3 Public Access Prevention Gate
**Date:** 2026-04-12
**Mode:** Startup
**Scope:** Reduce
## Value Proposition
Prevent public S3 buckets from reaching production.
## Target User
Platform team. They got paged for the incident.
## Starting Point
One rule: block S3 public access pre-deploy.
## Key Risk
False positives blocking legitimate public assets (CDN, static sites).
## Premise
Validated. Scanner finds problems after they exist, gate prevents them.
```
The brief answers: what are we building, for whom, why this scope, and what could go wrong. Share it before writing code.
On your second sprint onward, `/think` reads your last 3 briefs and the latest retro. Instead of starting from zero, it opens with context: "Last sprints: webhook signature gate, IAM role checks. The retro recommended rate limiting. What are we working on next?"
## Retro
After a sprint, use `/think --retro` to reflect on what shipped:
```
You: /think --retro
Agent: Reading sprint data...
Sprint Retro
Shipped: S3 public access gate (4 files, PR #42)
Right problem? Yes, prevention not detection. The gate
blocked 2 misconfigs in staging within 24 hours of deploy.
Surprises: /security found the gate itself had no rate
limiting. Fixed in the sprint but wasn't in the plan.
Recurring: This is the third sprint with missing rate
limiting findings. Consider adding it to /review's
graduated rules.
Recommendation: Next sprint should add IAM role scope
checks. Same gate pattern, broader coverage.
```
Retro reads the sprint journal, compound solutions, pattern report, and git metrics (`bin/sprint-metrics.sh` for commits, lines changed, cycle time per phase). It applies the same forcing questions to what was built, not what will be built. It doesn't start a new sprint. It's standalone reflection.
## Autopilot
Discuss the idea, approve the brief, walk away. The agent runs the full sprint:
```
/think --autopilot
```
`/think` is interactive: the agent asks questions, you answer, you align on the brief. After you approve, everything else runs automatically:
```
/nano → build → /review → /security → /qa → /ship
```
On Claude Code the phase gate enforces the pipeline at the hook layer: even if the agent judges a task as "simple" and tries to skip review or security, `git commit` is blocked until all phases have fresh artifacts. The hook stops the commit, no instructions involved. On agents that do not support pre-action hooks the same gate runs as a rule the agent reads; the gate is honest about the difference and `/nano-doctor` reports the actual level for your install.
**Autopilot continues after a complete brief, not after blind guessing.** `/think --autopilot` always produces a brief first. If the brief has the required fields (`value_proposition`, `target_user`, `narrowest_wedge`, `key_risk`, `premise_validated`), `/think` continues to `/nano` without pausing. If any required field is missing, `/think` stops once and asks one focused question. It does not invent fields to keep moving.
If the premise is not validated yet, that is allowed as long as the brief says so explicitly. Nanostack will steer the sprint toward a probe instead of pretending the idea is proven.
Autopilot only stops if:
- `/think` cannot fill the brief from context (asks one question, then continues)
- `/review` finds blocking issues that need your decision
- `/security` finds critical or high vulnerabilities
- `/qa` tests fail
- A product question comes up the agent can't answer from context
- The loop guard detects 2+ phases with no repository changes (agent is stuck)
Between steps the agent shows status:
```
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...
```
## Parallel sprints
Nanostack works well with one agent. It gets interesting with three running at once.
`/conductor` coordinates multiple sessions. Each agent claims a phase, executes it and the next agent picks up the artifact. Review, QA and security run in parallel because they all depend on build, not on each other.
```
/think → /nano → build ─┬─ /review (Agent A) ─┐
├─ /qa (Agent B) ├─ /ship
└─ /security (Agent C) ─┘
```
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 batches. Review, QA and security are all `read` and share the same dependency, so they batch together automatically.
### Coordination commands
`sprint.sh next` prints the first phase that is not done, has all dependencies met, and is not currently locked. An agent that just joined the sprint runs this to know what to claim, without parsing `status` JSON.
`sprint.sh unstuck <phase>` force-releases a stuck lock when its owner PID is dead, so a crashed agent does not block the sprint for the 1-hour grace period that auto-recovery uses. Refuses if the PID is alive; pass `--force` to override with a warning.
### Session resume
If the agent crashes mid-sprint, `session.sh resume` detects the last session state and `restore-context.sh` reads all completed phase checkpoints. The agent skips completed phases and restarts from where it left off. Each checkpoint is a compact summary (~50 tokens) with the key findings, files and decisions from that phase.
### Goal context
Pass a business objective when starting a sprint:
```bash
session.sh init development --goal "Pass SOC2 audit by July"
```
The goal propagates through the resolver to every phase. `/think` uses it to frame scope decisions: "does this feature serve the goal, or is it a tangent?" `/review` uses it to prioritize findings. `/security` uses it to weight compliance-related checks. The goal is optional; sprints work fine without one.
### Budget and circuit breaker
`budget.sh set --max-usd 15 --model opus-4` sets a cost limit for the sprint. At each phase transition, `budget.sh check` calculates spent vs budget. Warns at 80%. At 95%, the guard pipeline hard-blocks all non-allowlisted commands. Not a suggestion the model can ignore, a wall. The agent can still run `git status` and `ls` (to save work) but can't execute anything else. Override with `NANOSTACK_SKIP_BUDGET=1`.
`circuit.sh` tracks consecutive failures. After 3 failures on the same approach, the circuit opens and the agent must pivot or stop. Changing approach resets the counter.
## Guard
AI agents make mistakes. They run `rm -rf` when they mean `rm -r`, force push to main when they mean to push to a branch, pipe untrusted URLs to shell. `/guard` catches these before they execute.
### Six tiers
Inspired by [Claude Code auto mode](https://www.anthropic.com/engineering/claude-code-auto-mode), guard evaluates every Bash command through six tiers in this order. The order matters: the global gates run before the allowlist and in-project shortcuts, so a safe-listed or in-project command cannot skip them.
**Tier 1: Block rules.** Patterns for mass deletion, history destruction, database drops, production deploys, remote code execution, secret reads, security degradation and safety bypasses run first. A match exits 1 immediately, even if the command's binary is on the allowlist below. This ordering closes the bypass class where `find . -delete` or `cat .env` slipped past the allowlist because `find` and `cat` were safe-listed. Block rule definitions live in [`guard/rules.json`](guard/rules.json); query the live count with `jq '[.tiers.block.rules[].id] | length' guard/rules.json`.
**Tier 2: Phase-aware concurrency.** During read-only phases (review, security, qa), write operations are blocked so phases that run in parallel cannot mutate shared state. Detection covers more than the obvious utilities: output redirection, in-place editors (`sed -i`, `perl -i`), inline interpreter code (`python -c`, `node -e`, `sh -c`, `eval`), package-manager writes, and git index, worktree, or ref mutations. The agent reports findings instead of auto-fixing. Locked by `ci/e2e-read-phase-writes.sh`.
**Tier 3: Phase gate.** When a sprint is active, `git commit` and `git push` are blocked until review, security, and qa artifacts exist and are fresher than the latest code change. This prevents the agent from skipping pipeline phases on simple tasks. Bypass with `NANOSTACK_SKIP_GATE=1` for non-sprint commits.
**Tier 4: Budget gate.** When a sprint budget is set and 95%+ spent, all non-allowlisted commands are blocked. The agent can still run safe commands (`ls`, `git status`, `cat`) to save work, but cannot execute builds, tests, or deploys. Bypass with `NANOSTACK_SKIP_BUDGET=1`.
**Tier 5: Allowlist.** Only after the gates above clear do safe reads like `git status`, `ls`, `cat`, `jq` short-circuit the rest. They are read-only or otherwise side-effect-free for safe arguments. Running the allowlist after the global gates is what stops a safe-listed binary from skipping a read-only phase or the phase gate.
**Tier 6: In-project.** Operations that only touch files inside the current git repo pass through, after the gates have run. If the agent writes a bad file, you revert it. Version control is the safety net.
Plus a Tier 7 of warn rules for operations that need attention but not blocking. Warn rule definitions also live in `guard/rules.json`.
### Write and Edit are hooked too
`Write`, `Edit`, and `MultiEdit` go through their own PreToolUse hook (`guard/bin/check-write.sh`) that denies a narrow list of paths: secret files (`.env` and variants, `*.pem`, `*.key`, SSH keys, shell history), credential JSON basenames (`credentials.json`, `secrets.json`, `service-account*.json`, `firebase-adminsdk*.json`, `google-credentials*.json`, `aws-credentials*.json`, plus the same-stem variants with environment or region suffixes), and system or user-secret directories (`/etc`, `/var`, `/usr/bin`, `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.gcp`, `~/.kube`). Safe templates (`.env.example`, `.env.sample`, `.env.template`, `credentials.example.json`, `service-account.template.json`, etc.) pass through so first-run onboarding does not fight the guard. Matching is case-insensitive and mirrors the read-side G-035 rule. Symlinks are resolved before matching so `mylink/config -> ~/.ssh/config` is treated as the resolved target. See [`SECURITY.md`](SECURITY.md) for the full denylist and the manual wire-up for installs that predate the hook.
### Deny-and-continue
When guard blocks a command, it doesn't just say "no." It suggests a safer alternative:
```
BLOCKED [G-007] Force push overwrites remote history
Category: history-destruction
Command: git push --force origin main
Safer alternative: git push --force-with-lease (safer, fails if remote changed)
```
The agent reads this and retries with the safer command. No manual intervention needed.
### Configurable rules
All rules live in [`guard/rules.json`](guard/rules.json). Each rule has an ID, regex pattern, category, description and (for block rules) a safer alternative. Add your own:
```json
{
"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"
}
```
### What enforces on which agent
Honest scope. Nanostack ships skill files that work the same in every supported agent, but the **enforcement layer** (hooks that block commands before they run) depends on what each agent supports today. The capability that ships for each host lives in [`adapters/`](adapters/) as a small JSON file; setup, doctor, and this table all read from those files. Levels follow the L0-L4 vocabulary documented in [`reference/host-adapter-schema.md`](reference/host-adapter-schema.md).
| Agent | Bash guard | Write/Edit guard | Phase gate | What this means |
|---|---|---|---|---|
| Claude Code | enforced (L3) | enforced (L3) | enforced (L3) | Block rules and the Write/Edit denylist run before every tool call. The user does not have to read the rules; the hook does. CI continuously verifies the hook still blocks. |
| Cursor | guided (L0) | guided (L0) | guided (L0) | Skills are exposed as rules text. The agent reads the rules and is expected to follow them. No pre-tool-use hook on Cursor today. |
| OpenAI Codex | guided (L0) | guided (L0) | guided (L0) | Skill folder under `~/.codex/skills/`; no hook integration today. |
| OpenCode | guided (L0) | guided (L0) | guided (L0) | Native skill folder; no hook integration today. |
| Gemini CLI | guided (L0) | guided (L0) | guided (L0) | Installed as a Gemini extension; no hook integration today. |
When hooks are not available, the protection downgrades from "blocked at the system call" to "agent should know better." Run `/nano-doctor` after install on any agent to see the actual state, including any drift between what the adapter declares and what your install really wires. If you want hard enforcement, use Claude Code; if you accept agent-level discipline, the rest still ship the same workflow.
This gap is the single biggest known caveat in the framework. The roadmap is to add the same enforcement layer per agent as their tooling exposes the right hooks. Each adapter file carries a `last_verified` date and a verification source so users can tell which guarantees are CI-asserted today and which are manual.
## Install
### Recommended
```bash
npx create-nanostack
```
Detects your agents, installs all skills, runs setup. Verified adapters today: Claude Code, Cursor, OpenAI Codex, OpenCode, and Gemini CLI.
Update from your agent:
```
/nano-update
```
### Alternative: git clone (advanced)
Full control including skill rename, analytics, sprint journal and project setup.
```bash
git clone https://github.com/garagon/nanostack.git <path>
cd <path> && ./setup --host auto
```
Targets: `claude`, `codex`, `cursor`, `opencode`, `gemini`, `auto`.
### Alternative: Gemini CLI
```bash
gemini extensions install https://github.com/garagon/nanostack --consent
```
### Rename skills
If you have other skill sets installed (gstack, superpowers, etc.) and names collide, rename the ones that conflict. Requires git clone install.
```bash
cd ~/.claude/skills/nanostack
./setup --rename "review=my-review,security=my-security"
```
Renames persist between updates. Other useful commands:
```bash
./setup --list # show current skill names
./setup --rename reset # restore original names
```
### Project setup
Run once in each project to configure permissions and .gitignore. Requires git clone install.
```bash
~/.claude/skills/nanostack/bin/init-project.sh
```
This creates `.claude/settings.json` with permissions so Claude Code doesn't interrupt the workflow asking for approval on every file create or bash command. Also adds `.nanostack/` to `.gitignore`.
### Windows
Requires [Git for Windows](https://git-scm.com/downloads/win) which includes Git Bash. Claude Code uses Git Bash internally, so the setup script and all bin/ scripts work without changes. Alternatively use WSL or `npx skills add`.
## Requirements
- macOS or Linux shell environment (Windows works with Git Bash or WSL)
- `bash`
- [`git`](https://git-scm.com/)
- [`jq`](https://jqlang.github.io/jq/) (`brew install jq`, `apt install jq`, or `choco install jq`)
- One AI coding agent with a verified adapter: Claude Code, Cursor, OpenAI Codex, OpenCode, or Gemini CLI
Nanostack has no app runtime dependency and no build step. The scripts use standard local tools.
Nanostack works best with git but adapts automatically when there is no repo. With git, artifacts are stored relative to the git root, the phase gate verifies sprint compliance, scope drift compares planned files against `git diff`, and guard uses the repo boundary for in-project safety. Without git, Nanostack detects local mode and adapts the sprint: review checks files from the plan instead of a diff, ship opens the result instead of creating a PR, and all skills use plain language without git terminology.
## The Zen of Nanostack
```
Question the requirement before writing the code.
Delete what shouldn't exist.
If nobody would use a broken v1, the scope is wrong.
Narrow the scope, not the ambition.
Ship the version that ships today.
Fix it or ask. Never ignore it.
Security is not a tradeoff. It is a constraint.
The output should look better than what was asked for.
If the plan is hard to explain, the plan is wrong.
```
Full version in [`ZEN.md`](ZEN.md).
## Know-how
Most AI coding tools are stateless. Every session starts from zero. Nanostack builds knowledge as you work without extra commands.
### Every skill saves automatically
Every skill persists its output to `.nanostack/` after every run. You don't add flags. It just happens.
```
/think → .nanostack/think/20260325-140000.json
/nano → .nanostack/plan/20260325-143000.json
/review → .nanostack/review/20260325-150000.json
/qa → .nanostack/qa/20260325-151500.json
/security → .nanostack/security/20260325-152000.json
/ship → .nanostack/ship/20260325-160000.json
```
A review artifact captures everything: findings, scope drift, conflicts resolved.
```json
{
"phase": "review",
"mode": "standard",
"summary": { "blocking": 0, "should_fix": 2, "nitpicks": 1, "positive": 3 },
"scope_drift": { "status": "drift_detected", "out_of_scope_files": ["src/unplanned.ts"] },
"conflicts": [
{ "finding_id": "REV-005", "conflicts_with": "SEC-003",
"tension": "complementary", "resolution": "structured error codes" }
]
}
```
Every artifact `bin/save-artifact.sh` writes carries a SHA-256 `integrity` field over the canonical JSON, so a downstream consumer can detect a tampered file. Strict consumers call `bin/find-artifact.sh --require-integrity` to also reject artifacts whose `.integrity` field is missing. The save path validates the structured shape per phase (see `bin/lib/artifact-schemas.sh`); the legacy `--from-session` form still works for manual recovery but writes `schema_legacy: true` so downstream tools know the artifact was reconstructed instead of produced by the structured flow.
Full schema in [`reference/artifact-schema.md`](reference/artifact-schema.md). To disable auto-save, set `auto_save: false` in `.nanostack/config.json`.
### Skills read each other
Every skill starts with one call to `bin/resolve.sh`, a centralized context resolver. It loads upstream artifacts, past solutions, conflict precedents, diarizations and project config in one JSON blob. Each phase has its own routing table: `/review` gets the plan artifact and solutions matched by file overlap with the current diff. `/security` gets the plan, review artifact (up to 30 days back) and conflict precedents. `/compound` gets all six phase artifacts.
The resolver also exposes trust state to the caller. `upstream_status` per phase reports `verified`, `integrity_missing`, `integrity_mismatch`, or `missing`, so a release gate can tell a tampered artifact apart from a never-saved one. Custom skills can declare a `phase_context` block in `.nanostack/config.json` to ask the resolver for `trust: strict` (rejects integrity-missing upstreams), a per-phase `max_age_days`, required vs optional upstreams, and tagged solution / diarization lookup. The applied context comes back in `routing` so consumers see what the resolver did, not just what they asked for.
`/review` checks scope drift: did you touch files outside the plan? Did you skip files that were in it?
```
/nano → saves planned_files list
/review → resolver loads plan, compares against git diff, reports:
"drift_detected: src/unplanned.ts out of scope, tests/auth.test.ts missing"
```
`/security` detects conflicts with `/review`. `/review` says "add detail to error messages." `/security` says "don't expose internals." The resolution gets matched against [10 built-in precedents](reference/conflict-precedents.md) and recorded.
```
/review → saves "REV-003: error messages too vague"
/security → resolver loads review, detects conflict, resolves:
"structured errors: code + generic msg to user, details to logs"
```
No flags needed. The resolver knows what each phase needs. If an artifact exists, the next skill reads it.
### Sprint journal on /ship
When you run `/ship` and the PR lands, it automatically generates a sprint journal:
```
/ship → saves PR data
→ runs bin/sprint-journal.sh
→ writes .nanostack/know-how/journal/2026-03-25-myproject.md
```
The journal reads every phase artifact from the sprint and writes one file with the full decision trail: what `/think` reframed, what `/nano` scoped, what `/review` found, how conflicts were resolved, what `/security` graded.
### Visual artifacts
Every phase artifact is JSON. JSON is what every skill reads, what trust verification hashes, what the sprint journal aggregates. That layer stays canonical.
On top of it, `bin/render-artifact.sh` renders core and registered custom phase artifacts, sprint journals, and custom stack DAGs as local HTML views so a human can inspect the same evidence in a browser:
```bash
bin/render-artifact.sh plan --latest # render the latest plan
bin/render-artifact.sh review --latest # review with severity counters
bin/render-artifact.sh security --latest # OWASP / STRIDE breakdown
bin/render-artifact.sh license-audit --latest # registered custom phase
bin/render-artifact.sh journal --today # whole sprint timeline
bin/render-artifact.sh stack compliance-release # custom workflow DAG
```
Output lands under `.nanostack/visual/` next to the JSON it came from. Every render writes a companion manifest that records source path, source integrity, render timestamp, and renderer version. Delete a generated HTML file at any time; the JSON is unchanged and the view can be regenerated from it.
The renderer is offline-only: every page ships its own CSS, the Content-Security-Policy header blocks external network, no fonts or scripts are loaded from a CDN. A `--strict` flag fails the render when any source artifact's SHA-256 integrity hash does not match (`integrity_mismatch`) or is missing (`integrity_missing`).
`--interactive` adds copy-only buttons to `/plan` and `/review` views: copy as prompt, copy as Markdown, copy as JSON patch. The buttons use the local clipboard API only. No filesystem writes, no network calls, no form submission.
Visual artifacts are an optional inspection layer. Nothing depends on them: removing `.nanostack/visual/` does not change skill behavior or sprint state. The contract lives in `reference/visual-artifact-contract.md`.
### Knowledge compounding on /compound
After shipping, run `/compound` to 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/
```
Next sprint, `/nano` automatically searches past solutions before planning. `/review` checks if current code follows documented resolutions. Solutions that reference files no longer on disk are ranked lower automatically.
Solutions evolve over time. Each time `/compound` confirms a solution was applied, it increments `applied_count`, marks it `validated`, adjusts `confidence` (1-10 scale: +2 if it worked perfectly, -2 if it failed), and rewrites the compiled truth (Problem, Solution, Prevention) to reflect the current best understanding. The History section is append-only evidence of how that understanding evolved. Solutions are ranked by confidence, validation status, severity, and recency, so high-confidence proven solutions surface first.
Search manually:
```bash
bin/find-solution.sh "stripe webhook" # by keyword
bin/find-solution.sh --type bug # by type
bin/find-solution.sh --tag security # by tag
bin/find-solution.sh --file src/api/webhooks # by file
```
### Failure capture
`/compound` captures what worked. Failures get captured too, automatically, without waiting for a successful ship.
```bash
bin/capture-failure.sh review "scope-drift.sh failed" "manual file comparison" "save plan artifact first"
```
Appends to `.nanostack/know-how/learnings/failures.jsonl`. Every skill can call this when something goes wrong: CLI errors, wrong approaches, project quirks. Next sprint, the same mistake is avoided. No `/compound` needed, no success needed. Just log and move on.
### Skill graduation
Solutions that prove themselves get promoted into skill files. When a solution has been applied 3+ times, is validated, and its referenced files still exist, `bin/graduate.sh` proposes inserting it as a permanent rule in the target skill's `## Graduated Rules` section.
```bash
bin/graduate.sh # dry run: show candidates
bin/graduate.sh --apply # insert rules into SKILL.md files
bin/graduate.sh --status # show budget: how many rules per skill
bin/graduate.sh --prune # detect stale rules (referenced files gone)
```
Bug solutions graduate into `/review` (adversarial pass checklist). Pattern and decision solutions graduate into `/nano` (planning constraints). Security-tagged solutions graduate into `/security` (audit checklist). Each skill has a cap: review 10 rules, plan 8, security 8.
A graduated rule is a one-line check the skill applies every sprint without searching for solutions at runtime. The original solution is marked `graduated: true` but not deleted, so it retains the full history. If a graduated rule goes stale (source files deleted), `--prune` detects it.
```
Sprint 1: /compound documents "webhook signature verification" bug
Sprint 2: /compound updates it, applied_count: 2, validated: true
Sprint 3: /compound updates it, applied_count: 3
/compound runs graduate.sh, reports:
"1 solution ready to graduate into security/SKILL.md"
You: bin/graduate.sh --apply
Rule is now baked into /security. No more runtime lookup.
```
### Diarization
When you revisit a module after weeks, context is scattered across artifacts, solutions and git history. `bin/gather-subject.sh` collects everything about a subject into one JSON blob for synthesis.
```bash
bin/gather-subject.sh src/api/webhooks/ # directory
bin/gather-subject.sh auth # keyword
bin/gather-subject.sh src/lib/errors.ts # exact file
```
Output includes: matched files, git history, ownership (who contributed most), related solutions, related artifacts from past sprints, and any existing diarization. The model reads the gathered sources and produces a structured brief: what the module does, who owns it, what keeps breaking, what the docs say versus what the code actually does, and unresolved tensions between skills.
Diarizations are stored in `.nanostack/know-how/diarizations/` and surfaced by the resolver when changed files overlap with the subject. Skills decide whether to read one based on age and relevance.
### Analytics, token usage and patterns
```bash
bin/analytics.sh --tokens # phase counts, security trends, token usage
bin/token-report.sh # token consumption per session and subagent
bin/token-report.sh --all # all projects with cost breakdown
bin/pattern-report.sh # recurring issues, risk accuracy, phase bottlenecks
bin/graduate.sh --status # graduation budget: rules per skill vs caps
bin/doctor.sh # know-how health: stale, unused, unvalidated solutions
bin/sprint-metrics.sh # git stats + cycle time per phase (used by /think --retro and /nano)
bin/about.sh # generate .nanostack/ABOUT.md (compact self-description for any agent)
bin/capture-learning.sh "..." # append a learning to the knowledge base
```
`token-report.sh` reads Claude Code's session logs and breaks down where tokens go. Cache-aware pricing (reads at 10%, creation at 125%). Flags runaway sessions and heavy subagents. Requires Claude Code; skips silently on other agents.
`pattern-report.sh` detects patterns across sprints: which findings keep recurring, whether predicted risks materialized, which phases take the longest, and how often solutions get reused.
`doctor.sh` checks know-how health: solutions referencing deleted files (stale), solutions never applied after 60 days (unused), solutions unvalidated after 90 days. Scores 0-10, reports issues, and `--fix` auto-removes stale entries. Run it periodically to keep the knowledge base clean.
Every sprint lifecycle event is logged to `.nanostack/audit.log` (JSONL, append-only): session init, phase start/complete with duration, artifact saves, solution creation, graduation. When a sprint goes wrong, the audit trail shows exactly what happened and when.
### Discard a bad session
If a sprint went wrong (agent hallucinated findings, aborted halfway, bad data), discard it:
```bash
bin/discard-sprint.sh # discard all artifacts from today for this project
bin/discard-sprint.sh --phase review # discard only review artifacts
bin/discard-sprint.sh --date 2026-03-24 # discard artifacts from a specific date
bin/discard-sprint.sh --dry-run # show what would be deleted without deleting
```
This removes artifacts and the journal entry. Analytics recalculate on next run.
### The Obsidian vault
Open `.nanostack/know-how/` in Obsidian. Sprint journals link to conflict precedents. The dashboard links to journals. Graph view shows how sprints, conflicts and learnings connect over time.
## Build on nanostack
Use Nanostack as-is, or build your own workflow stack on top. Custom skills can compose into a domain workflow that gates `/ship`, and they inherit the same artifact store, resolver, sprint journal, analytics, conductor, and local vault that the built-in skills run on. No SaaS, no daemon, no build step.
### Single skill
Scaffold a skill from the template, validate it, restart your agent:
```bash
bin/create-skill.sh license-audit --concurrency read --depends-on build
bin/check-custom-skill.sh .nanostack/skills/license-audit
```
The framework guarantees that one skill inherits, all proven by `ci/e2e-custom-stack-flows.sh`:
- `save-artifact.sh license-audit` and `find-artifact.sh license-audit` accept the custom phase the same way they accept a core phase.
- `resolve.sh license-audit` returns `phase_kind: "custom"` with `upstream_artifacts` driven by the skill's `depends_on` (or by `phase_graph` in `.nanostack/config.json`).
- `sprint-journal.sh` emits a `## /license-audit` section with the skill's status, headline, and artifact path.
- `analytics.sh --json` adds the skill to `sprints.custom.license-audit` and counts it in `sprints.total`.
- `discard-sprint.sh --dry-run` lists the skill's artifacts alongside the core ones.
- `conductor/bin/sprint.sh start --phases <json>` accepts a graph that includes the custom phase; `conductor/bin/sprint.sh batch` reads its `concurrency:` from `SKILL.md`.
### Workflow stack
A stack is multiple custom skills wired together with a `phase_graph` so the conductor knows the dependency order. The compliance-release example proves the framework: three custom phases (`/license-audit` + `/privacy-check` + `/release-readiness`) compose into a release decision before `/ship`. `ci/e2e-custom-stack-examples.sh` walks the full new-user journey on a real `/tmp` project (scaffold, validate, save, resolve, journal, analytics, discard, conductor scheduling) and runs in the opt-in E2E workflow. 15 cells, 51 assertions.
Copy the stack starting point:
```
examples/custom-stack-template/compliance-release/
```
The stack's [README](examples/custom-stack-template/compliance-release/README.md) walks through the install. The directory contract for any new stack is in [`reference/custom-stack-examples-technical-spec.md`](reference/custom-stack-examples-technical-spec.md); the framework contract those skills inherit is in [`reference/custom-stack-contract.md`](reference/custom-stack-contract.md).
A marketing team builds `/audience` and `/campaign`. A data team builds `/explore` and `/model`. A design team builds `/wireframe` and `/usability`. A compliance team builds `/license-audit`, `/privacy-check`, and `/release-readiness`. All compose with Nanostack's `/think` for ideation, `/review` for quality, and `/ship` for delivery.
Full walkthrough: [`EXTENDING.md`](EXTENDING.md).
## Privacy
Nanostack itself has no cloud service.
By default, sprint artifacts, plans, journals, and know-how are written locally under `.nanostack/`.
Nanostack itself stores sprint state, artifacts, and know-how locally. It does not send your code, prompts, project names, or file paths to a Nanostack server. Your AI agent provider may still process the context you give it. Use your agent provider's privacy settings and your own data policies for sensitive work.
`/think` supports `local_only`, `private`, and `public` search modes, so sensitive ideas do not require public web search.
Telemetry is opt-in and limited to aggregate usage events. It is not required for the workflow. If you opt in, events go to the Cloudflare Worker documented in [`TELEMETRY.md`](TELEMETRY.md); the Worker source, schema, privacy invariants, and adversarial smoke tests all live in this repo.
Tiers: `off` (default), `anonymous`, `community`. Installs from v0.4 and earlier default to `off` and see no prompt. New installs see a one-time prompt on first skill run.
Change your tier at any time:
```sh
nanostack-config set telemetry off
nanostack-config set telemetry anonymous
nanostack-config set telemetry community
```
Run `bin/analytics.sh` to see your own usage: which skills you run, how often, in what mode. Reads local artifacts only.
## Troubleshooting
Quick fixes for the most common issues. For the full guide (Windows setup, proxy installs, stuck sprints, name conflicts, autopilot loops), see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
**Skills don't appear as slash commands.**
Restart your agent (Cursor and Codex need this; Claude Code does not). Re-run `./setup` if symlinks broke.
**`jq: command not found` when running scripts.**
Install jq: `brew install jq` (macOS) or `apt install jq` (Linux).
**Port in use when running /qa browser tests.**
Find it: `lsof -ti:3000`. Kill it: `kill $(lsof -ti:3000)`.
**`/conductor` claim fails with BLOCKED.**
Dependencies not finished. Run `conductor/bin/sprint.sh status` to check.
**Phase gate blocked my git commit.**
Complete `/review`, `/security`, `/qa` for the active sprint, or bypass with `NANOSTACK_SKIP_GATE=1 git commit ...` for non-sprint commits.
**Skills seem outdated.**
Run `/nano-update` from Claude Code, or `~/.claude/skills/nanostack/bin/upgrade.sh` from the terminal.
## Uninstall
```bash
# Claude Code
cd ~/.claude/skills && rm -f think nano review qa security ship guard conductor compound && rm -rf nanostack
# Codex
rm -rf ~/.agents/skills/nanostack*
# Cursor
rm -f .cursor/rules/nanostack.md
# OpenCode
rm -rf ~/.agents/skills/nanostack
# Gemini CLI
gemini extensions remove nanostack
```
## Contributing
Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, project structure and PR guidelines.
- [Bug reports](https://github.com/garagon/nanostack/issues/new?template=bug_report.yml)
- [Feature requests](https://github.com/garagon/nanostack/issues/new?template=feature_request.yml)
- Security vulnerabilities: [SECURITY.md](SECURITY.md)
## License
Apache 2.0