nanostack — Claude Code plugin: what it does, how to install

<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">
  An agent harness for planning, reviewing, and testing the code you ship.
</p>

<p align="center">
  <em>A delivery workflow for your AI coding agent.</em>
</p>

<p align="center">
  Give your agent a repeatable process, with plans and check results you can inspect. Use the built-in skills or build your own workflow stack.
</p>

<p align="center"><strong>Open source. Editable skills. Inspectable results.</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> &middot;
  <a href="#quick-start">Install</a> &middot;
  <a href="#the-sprint">The Sprint</a> &middot;
  <a href="#visual-artifacts">Visual artifacts</a> &middot;
  <a href="#build-on-nanostack">Extend</a> &middot;
  <a href="RELEASE_NOTES.md">Release notes</a> &middot;
  <a href="README.es.md">Español</a>
</p>

<br>


Nanostack adds planning, code review, security checks, and testing to your AI coding workflow. It saves the plan and results as files, so you can see what changed and how it was checked.

Verified adapters: **Claude Code, Cursor, OpenAI Codex, OpenCode, and Gemini CLI**. Claude Code supports blocking hooks; the other adapters use guided instructions. See the [per-agent capabilities](#what-enforces-on-which-agent) and [verification records](adapters/) for dates and test scope. Installation checks do not guarantee a full sprint on every host version.

## Quick start

```bash
npx create-nanostack
```

Run `/nano-run` in your agent to configure the project. See [requirements](#requirements) and [installation options](#install).

Start with `/think` to work through an idea, or `/nano` to plan a defined change. For an autonomous sprint in an existing project, use `/feature <goal>`; it automatically approves the plan and continues through the phases.

## What changes after installing Nanostack

- **Plan the change.** Record the scope, files, risks, and checks before implementation.
- **Review the result.** Check the code against the plan, audit security, and test behavior.
- **Inspect the work.** Read saved reports or open them as [visual artifacts](#visual-artifacts) in your browser.
- **Adapt the workflow.** Edit the skills or add your own phases with [custom stacks](#build-on-nanostack).

Inspired by [gstack](https://github.com/garrytan/gstack) from [Garry Tan](https://x.com/garrytan). Apache 2.0. No Nanostack cloud. See [privacy](#privacy) for telemetry and agent-provider details, and [release notes](RELEASE_NOTES.md) for recent changes.

## 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.

## 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. Reports proposed repairs and decisions needing your input. 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. Reports reproducible bugs without editing product code. |
| `/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 proposed repairs, 1 decision). 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 (advanc...