{
  "markdown": "\n<p align=\"center\">\n<img width=\"404\" height=\"139\" alt=\"Image\" src=\"https://github.com/user-attachments/assets/839805e9-979f-4c95-9e24-eba9d7ae6236\" />\n</p>\n\n<br>\n\n<p align=\"center\">\n  Your AI agent writes code. Nanostack makes sure it ships work you can trust.\n</p>\n\n<p align=\"center\">\n  <em>Local delivery workflow harness for AI coding agents.</em>\n</p>\n\n<p align=\"center\">\n  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.\n</p>\n\n<p align=\"center\"><strong>Open source. Plain text skills. Local artifacts. Verified adapters. No Nanostack cloud.</strong></p>\n\n<p align=\"center\">\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/license-Apache%202.0-blue.svg\" alt=\"License\"></a>\n  <a href=\"https://github.com/garagon/nanostack/stargazers\"><img src=\"https://img.shields.io/github/stars/garagon/nanostack?style=flat\" alt=\"GitHub Stars\"></a>\n  <a href=\"https://skills.sh/garagon/nanostack\"><img src=\"https://img.shields.io/badge/skills.sh-available-brightgreen\" alt=\"skills.sh\"></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"#what-is-nanostack\">What is it</a> &middot;\n  <a href=\"#quick-start\">Install</a> &middot;\n  <a href=\"#the-sprint\">The Sprint</a> &middot;\n  <a href=\"#visual-artifacts\">Visual artifacts</a> &middot;\n  <a href=\"#build-on-nanostack\">Extend</a> &middot;\n  <a href=\"RELEASE_NOTES.md\">Release notes</a> &middot;\n  <a href=\"README.es.md\">Español</a>\n</p>\n\n<br>\n\n\nInspired 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.\n\nVerified 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/).\n\nWhat changed in the latest release (custom workflow stacks, visual artifacts, stronger safety contracts): see [`RELEASE_NOTES.md`](RELEASE_NOTES.md).\n\n## See it work\n\n```\nYou:    I need to add notifications to my app. Users keep missing\n        replies on their posts.\nYou:    /think\n\nAgent:  Before we build anything, how are users coping today?\n\nYou:    They open the app 3-4 times a day just to check. Sometimes\n        they miss replies for hours. People are frustrated.\n\nAgent:  I'm going to push back on \"notifications.\" You said users open\n        the app 3-4 times a day. That's high engagement. They already\n        come back. The problem isn't that they can't be reached. The\n        problem is that when they arrive, they can't tell what changed.\n\n        That's a freshness problem, not a messaging problem.\n\n        A notification system (email, push, in-app, preferences,\n        digest, unsubscribe) is a 3-week project. A red dot on the\n        nav icon that says \"something new\" ships this afternoon.\n\n        One solves the symptom (they're not being told). The other\n        solves the cause (they can't see what's new when they look).\n\n        RECOMMENDATION: Reduce. Ship the dot. See if complaints drop.\n        If they do, you just saved 3 weeks. If they don't, then build\n        push notifications, but now you have data, not a guess.\n\nYou:    Makes sense. Let's do the dot.\nYou:    /nano\n        [3 steps, 2 files, product standards: shadcn/ui + Tailwind]\n\nYou:    [builds it]\n\nYou:    /review\n        Review: 2 findings (1 auto-fixed, 1 nit). 2 things done well.\n\nYou:    /security\n        No secrets, auth changes, or unsafe data flows introduced. Grade A.\n\nYou:    /qa\n        Opened the app, posted a reply, refreshed, confirmed the dot\n        appears and clears. 4 checks pass.\n\nYou:    /ship\n        PR explains why the change exists, how it was checked, and what\n        remains. CI green. Sprint journal saved.\n```\n\nThat is the difference: not just code generation, but a delivery loop you can inspect.\n\n## What changes after installing Nanostack\n\n| Without Nanostack | With Nanostack |\n| --- | --- |\n| ❌ A vague prompt turns into code immediately. | ✅ `/think` turns the idea into a brief, risk, and smallest useful starting point. |\n| ❌ The plan disappears in chat. | ✅ `/nano` saves a plan with files, risks, checks, and out-of-scope items. |\n| ❌ The agent quietly refactors three things you did not ask for. | ✅ `/review` compares the code against the plan. Scope drift is visible before merge. |\n| ❌ 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. |\n| ❌ 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. |\n| ❌ 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.) |\n| ❌ 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/`. |\n\n## Nanostack is right for you if\n\n- ✅ You have an AI agent open all day and still feel like you ship slowly\n- ✅ You want reviews that catch scope drift, not just typos\n- ✅ You want a security audit before every ship, not once a quarter\n- ✅ You want PR descriptions that explain the WHY, not just list files\n- ✅ You want a process that works across Claude Code, Cursor, OpenAI Codex, OpenCode, and Gemini CLI\n- ✅ You want the skills on disk, inspectable, not locked in a SaaS\n\n## Try it safely first\n\nNot sure yet? Start with a disposable sandbox from the Examples Library. It gives you a real sprint without risking your product.\n\n| Example | Best for | Stack | Time |\n|---|---|---|---|\n| [`starter-todo`](examples/starter-todo/) | new and non-technical users | one HTML file | 5-10 min |\n| [`cli-notes`](examples/cli-notes/) | CLI workflows | Bash | 5-15 min |\n| [`api-healthcheck`](examples/api-healthcheck/) | backend flows | Node stdlib HTTP | 10-15 min |\n| [`static-landing`](examples/static-landing/) | founders and designers | static HTML/CSS | 10-15 min |\n| [`compliance-release`](examples/custom-stack-template/compliance-release/) | teams building a custom workflow stack | license + privacy + release gate | 15-30 min |\n\nEach example has a copy-paste prompt, expected sprint flow, success criteria, and reset steps. Full Examples Library: [`examples/`](examples/).\n\n`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.\n\n## Quick start\n\n```bash\nnpx create-nanostack\n```\n\nOne command. Detects your agents, installs everything, runs setup.\n\nThen 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.\n\nIf you want to see the workflow before installing into a real repo, use one of the sandbox examples above.\n\n## Choose your path\n\n| If you are... | Start here |\n|---|---|\n| New to agent workflows | Try [`starter-todo`](examples/starter-todo/), then run `/nano-run` |\n| Already shipping with AI agents | Install Nanostack, then start with `/think` or `/feature` |\n| Evaluating safety | Read [Guard](#guard) and the [host enforcement matrix](#what-enforces-on-which-agent) |\n| Building your own workflow | Start with [`EXTENDING.md`](EXTENDING.md) and [`compliance-release`](examples/custom-stack-template/compliance-release/) |\n| Inspecting what the agent did | Render any phase as local HTML with [visual artifacts](#visual-artifacts) (`bin/render-artifact.sh`) |\n\n## What is Nanostack?\n\nYour 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.\n\nThe 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.\n\nThe bet is artifact-first delivery:\n\n- Skills are plain text.\n- Artifacts are local JSON.\n- Gates verify evidence before release.\n- Visual artifacts render the same evidence as local HTML.\n- Custom workflow stacks extend the same pipeline with your own phases.\n\nOn 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.\n\nThe built-in sprint is the default stack:\n\n|        | Step              | What the specialist does                                                |\n| ------ | ----------------- | ----------------------------------------------------------------------- |\n| **01** | `/think`          | Refines your rough idea through questions. Finds the smallest useful version. |\n| **02** | `/nano`           | Plans the implementation. Names files, risks, and checks.               |\n| **03** | build             | You or the agent writes the code.                                       |\n| **04** | `/review`         | Two-pass code review. Scope drift detection. Auto-fixes the mechanical. |\n| **05** | `/security`       | OWASP A01-A10 audit + STRIDE threat modeling. Graded A-F.               |\n| **06** | `/qa`             | Tests the thing. Browser, API, CLI, or root-cause debug.                |\n| **07** | `/ship`           | PR creation, CI verification, release notes, sprint journal. Production deployment stays explicit and user-controlled. |\n\n## Two profiles, same rigor\n\nNanostack adapts the explanation, not the standard.\n\n| Profile | What changes |\n|---------|--------------|\n| **Guided** | Plain language, one next action, safer defaults, no hidden jargon. |\n| **Professional** | Denser output, deeper tradeoffs, explicit files, commands, and risks. |\n\nLocal mode uses Guided language by default. A git project can still use Guided if the user wants simpler explanations.\n\nThe 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).\n\n## What is enforced depends on your agent\n\nNanostack 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.\n\n| Level | Meaning |\n|-------|---------|\n| **L0 Guided** | The skill tells the agent what to do but cannot block it. Also covers a capability the host cannot provide at all. |\n| **L1 Checked** | Nanostack can detect and report the issue, but cannot block it. |\n| **L2 Guarded** | The host runs a nanostack hook before the action. |\n| **L3 Enforced** | The hook can block the action and the host honors the block. |\n| **L4 Continuously verified** | A CI job exercises the capability on every change. |\n\nA 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).\n\n## The sprint\n\nNanostack is a process, not a collection of tools. The skills run in the order a sprint runs:\n\n```\n/think → /nano → build → /review → /security → /qa → /ship\n```\n\nEach 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).\n\n| Skill | Your specialist | What they do |\n|-------|----------------|--------------|\n| `/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. |\n| `/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. |\n| `/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. |\n| `/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. |\n| `/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. |\n| `/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. |\n\n### Power tools\n\n| Skill | What it does |\n|-------|-------------|\n| `/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. |\n| `/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`. |\n| `/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. |\n| `/feature` | **Builder** | Add functionality to an existing project. Skips /think, goes straight to plan, build, review, audit, test, ship. |\n| `/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. |\n| `/nano-help` | **Reference** | Quick reference for all nanostack commands and how to use them. |\n\n### Intensity modes\n\nNot every change needs a full audit. `/review`, `/qa` and `/security` support three modes:\n\n| Mode | Flag | When to use |\n|------|------|-------------|\n| **Quick** | `--quick` | Typos, config, docs. Only report the obvious. |\n| **Standard** | (default) | Normal features and bug fixes. |\n| **Thorough** | `--thorough` | Auth, payments, infra. Flag everything suspicious. |\n\n### Specs by scope\n\n`/nano` generates specs automatically based on project complexity:\n\n| Scope | What you get |\n|-------|-------------|\n| **Small** (1-3 files) | Implementation steps only |\n| **Medium** (4-10 files) | Product spec + implementation steps |\n| **Large** (10+ files) | Product spec + technical spec + implementation steps |\n\nThe 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.\n\nSpecs are presented for approval before implementation. If the spec is wrong, everything downstream is wrong.\n\n## Full sprint walkthrough\n\n```\nYou:    I want to build a security scanner for cloud misconfigurations.\n        We keep finding S3 buckets left public and IAM roles that are\n        way too broad. Last month a public bucket caused an incident.\nYou:    /think\n\nAgent:  I'm going to push back on \"security scanner.\" A scanner finds\n        problems after they exist. But you said last month a public\n        bucket caused an incident. You don't want to find misconfigs,\n        you want to stop them from reaching production.\n\n        That's a prevention gate, not a scanner. Different product.\n\n        The scanner is 10% better than what you have (manual audits).\n        A pre-deploy gate is 10x. The misconfiguration never ships.\n\n        Who would use a broken v1 tomorrow? Your platform team. They\n        got paged for that incident. They'd use anything that blocks\n        public S3 buckets before deploy, even if it only checks one rule.\n\n        RECOMMENDATION: Reduce scope. One rule. S3 public access check,\n        pre-deploy. Ship tomorrow. The full scanner is a 3-month project.\n\nYou:    That makes sense. Let's start with S3.\nYou:    /nano\n        [5 steps, 4 files, risks listed, out-of-scope explicit]\n\nYou:    [builds the feature]\n\nYou:    /review\n        Review: 3 findings (2 auto-fixed, 1 ask). Scope drift: CLEAN.\n\nYou:    /security\n        Security: CRITICAL (0) HIGH (0) MEDIUM (1) LOW (1). Score: A.\n\nYou:    /qa\n        Provisioned a sandbox bucket, attempted a public-grant\n        action, confirmed the gate blocked it, confirmed normal\n        ops still work. 8 checks pass.\n\nYou:    /ship\n        PR ready. CI passed. Sprint journal saved.\n```\n\nYou 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.\n\n## Think brief\n\nEvery `/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.\n\n```markdown\n# Think Brief: S3 Public Access Prevention Gate\n\n**Date:** 2026-04-12\n**Mode:** Startup\n**Scope:** Reduce\n\n## Value Proposition\nPrevent public S3 buckets from reaching production.\n\n## Target User\nPlatform team. They got paged for the incident.\n\n## Starting Point\nOne rule: block S3 public access pre-deploy.\n\n## Key Risk\nFalse positives blocking legitimate public assets (CDN, static sites).\n\n## Premise\nValidated. Scanner finds problems after they exist, gate prevents them.\n```\n\nThe brief answers: what are we building, for whom, why this scope, and what could go wrong. Share it before writing code.\n\nOn 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?\"\n\n## Retro\n\nAfter a sprint, use `/think --retro` to reflect on what shipped:\n\n```\nYou:    /think --retro\n\nAgent:  Reading sprint data...\n\n        Sprint Retro\n\n        Shipped: S3 public access gate (4 files, PR #42)\n\n        Right problem? Yes, prevention not detection. The gate\n        blocked 2 misconfigs in staging within 24 hours of deploy.\n\n        Surprises: /security found the gate itself had no rate\n        limiting. Fixed in the sprint but wasn't in the plan.\n\n        Recurring: This is the third sprint with missing rate\n        limiting findings. Consider adding it to /review's\n        graduated rules.\n\n        Recommendation: Next sprint should add IAM role scope\n        checks. Same gate pattern, broader coverage.\n```\n\nRetro 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.\n\n## Autopilot\n\nDiscuss the idea, approve the brief, walk away. The agent runs the full sprint:\n\n```\n/think --autopilot\n```\n\n`/think` is interactive: the agent asks questions, you answer, you align on the brief. After you approve, everything else runs automatically:\n\n```\n/nano → build → /review → /security → /qa → /ship\n```\n\nOn 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.\n\n**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.\n\nIf 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.\n\nAutopilot only stops if:\n- `/think` cannot fill the brief from context (asks one question, then continues)\n- `/review` finds blocking issues that need your decision\n- `/security` finds critical or high vulnerabilities\n- `/qa` tests fail\n- A product question comes up the agent can't answer from context\n- The loop guard detects 2+ phases with no repository changes (agent is stuck)\n\nBetween steps the agent shows status:\n```\nAutopilot: build complete. Running /review...\nAutopilot: review clean (5 findings, 0 blocking). Running /security...\nAutopilot: security grade A. Running /qa...\nAutopilot: qa passed (12 tests, 0 failed). Running /ship...\n```\n\n## Parallel sprints\n\nNanostack works well with one agent. It gets interesting with three running at once.\n\n`/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.\n\n```\n/think → /nano → build ─┬─ /review   (Agent A) ─┐\n                              ├─ /qa       (Agent B)  ├─ /ship\n                              └─ /security (Agent C) ─┘\n```\n\nNo daemon. No message queue. Just `mkdir` for atomic locking, JSON for state, symlinks for artifact handoff.\n\n`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.\n\n### Coordination commands\n\n`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.\n\n`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.\n\n### Session resume\n\nIf 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.\n\n### Goal context\n\nPass a business objective when starting a sprint:\n\n```bash\nsession.sh init development --goal \"Pass SOC2 audit by July\"\n```\n\nThe 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.\n\n### Budget and circuit breaker\n\n`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`.\n\n`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.\n\n## Guard\n\nAI 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.\n\n### Six tiers\n\nInspired 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.\n\n**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`.\n\n**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`.\n\n**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.\n\n**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`.\n\n**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.\n\n**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.\n\nPlus a Tier 7 of warn rules for operations that need attention but not blocking. Warn rule definitions also live in `guard/rules.json`.\n\n### Write and Edit are hooked too\n\n`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.\n\n### Deny-and-continue\n\nWhen guard blocks a command, it doesn't just say \"no.\" It suggests a safer alternative:\n\n```\nBLOCKED [G-007] Force push overwrites remote history\nCategory: history-destruction\nCommand: git push --force origin main\n\nSafer alternative: git push --force-with-lease (safer, fails if remote changed)\n```\n\nThe agent reads this and retries with the safer command. No manual intervention needed.\n\n### Configurable rules\n\nAll 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:\n\n```json\n{\n  \"id\": \"G-100\",\n  \"pattern\": \"terraform destroy\",\n  \"category\": \"infra-destruction\",\n  \"description\": \"Destroy all Terraform-managed infrastructure\",\n  \"alternative\": \"terraform plan -destroy first to review what would be removed\"\n}\n```\n\n### What enforces on which agent\n\nHonest 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).\n\n| Agent | Bash guard | Write/Edit guard | Phase gate | What this means |\n|---|---|---|---|---|\n| 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. |\n| 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. |\n| OpenAI Codex | guided (L0) | guided (L0) | guided (L0) | Skill folder under `~/.codex/skills/`; no hook integration today. |\n| OpenCode | guided (L0) | guided (L0) | guided (L0) | Native skill folder; no hook integration today. |\n| Gemini CLI | guided (L0) | guided (L0) | guided (L0) | Installed as a Gemini extension; no hook integration today. |\n\nWhen 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.\n\nThis 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.\n\n## Install\n\n### Recommended\n\n```bash\nnpx create-nanostack\n```\n\nDetects your agents, installs all skills, runs setup. Verified adapters today: Claude Code, Cursor, OpenAI Codex, OpenCode, and Gemini CLI.\n\nUpdate from your agent:\n\n```\n/nano-update\n```\n\n### Alternative: git clone (advanced)\n\nFull control including skill rename, analytics, sprint journal and project setup.\n\n```bash\ngit clone https://github.com/garagon/nanostack.git <path>\ncd <path> && ./setup --host auto\n```\n\nTargets: `claude`, `codex`, `cursor`, `opencode`, `gemini`, `auto`.\n\n### Alternative: Gemini CLI\n\n```bash\ngemini extensions install https://github.com/garagon/nanostack --consent\n```\n\n### Rename skills\n\nIf you have other skill sets installed (gstack, superpowers, etc.) and names collide, rename the ones that conflict. Requires git clone install.\n\n```bash\ncd ~/.claude/skills/nanostack\n./setup --rename \"review=my-review,security=my-security\"\n```\n\nRenames persist between updates. Other useful commands:\n\n```bash\n./setup --list           # show current skill names\n./setup --rename reset   # restore original names\n```\n\n### Project setup\n\nRun once in each project to configure permissions and .gitignore. Requires git clone install.\n\n```bash\n~/.claude/skills/nanostack/bin/init-project.sh\n```\n\nThis 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`.\n\n### Windows\n\nRequires [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`.\n\n## Requirements\n\n- macOS or Linux shell environment (Windows works with Git Bash or WSL)\n- `bash`\n- [`git`](https://git-scm.com/)\n- [`jq`](https://jqlang.github.io/jq/) (`brew install jq`, `apt install jq`, or `choco install jq`)\n- One AI coding agent with a verified adapter: Claude Code, Cursor, OpenAI Codex, OpenCode, or Gemini CLI\n\nNanostack has no app runtime dependency and no build step. The scripts use standard local tools.\n\nNanostack 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.\n\n## The Zen of Nanostack\n\n```\nQuestion the requirement before writing the code.\nDelete what shouldn't exist.\nIf nobody would use a broken v1, the scope is wrong.\nNarrow the scope, not the ambition.\nShip the version that ships today.\nFix it or ask. Never ignore it.\nSecurity is not a tradeoff. It is a constraint.\nThe output should look better than what was asked for.\nIf the plan is hard to explain, the plan is wrong.\n```\n\nFull version in [`ZEN.md`](ZEN.md).\n\n## Know-how\n\nMost AI coding tools are stateless. Every session starts from zero. Nanostack builds knowledge as you work without extra commands.\n\n### Every skill saves automatically\n\nEvery skill persists its output to `.nanostack/` after every run. You don't add flags. It just happens.\n\n```\n/think     →  .nanostack/think/20260325-140000.json\n/nano →  .nanostack/plan/20260325-143000.json\n/review    →  .nanostack/review/20260325-150000.json\n/qa        →  .nanostack/qa/20260325-151500.json\n/security  →  .nanostack/security/20260325-152000.json\n/ship      →  .nanostack/ship/20260325-160000.json\n```\n\nA review artifact captures everything: findings, scope drift, conflicts resolved.\n\n```json\n{\n  \"phase\": \"review\",\n  \"mode\": \"standard\",\n  \"summary\": { \"blocking\": 0, \"should_fix\": 2, \"nitpicks\": 1, \"positive\": 3 },\n  \"scope_drift\": { \"status\": \"drift_detected\", \"out_of_scope_files\": [\"src/unplanned.ts\"] },\n  \"conflicts\": [\n    { \"finding_id\": \"REV-005\", \"conflicts_with\": \"SEC-003\",\n      \"tension\": \"complementary\", \"resolution\": \"structured error codes\" }\n  ]\n}\n```\n\nEvery 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.\n\nFull schema in [`reference/artifact-schema.md`](reference/artifact-schema.md). To disable auto-save, set `auto_save: false` in `.nanostack/config.json`.\n\n### Skills read each other\n\nEvery 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.\n\nThe 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.\n\n`/review` checks scope drift: did you touch files outside the plan? Did you skip files that were in it?\n\n```\n/nano     →  saves planned_files list\n/review   →  resolver loads plan, compares against git diff, reports:\n              \"drift_detected: src/unplanned.ts out of scope, tests/auth.test.ts missing\"\n```\n\n`/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.\n\n```\n/review   →  saves \"REV-003: error messages too vague\"\n/security →  resolver loads review, detects conflict, resolves:\n              \"structured errors: code + generic msg to user, details to logs\"\n```\n\nNo flags needed. The resolver knows what each phase needs. If an artifact exists, the next skill reads it.\n\n### Sprint journal on /ship\n\nWhen you run `/ship` and the PR lands, it automatically generates a sprint journal:\n\n```\n/ship  →  saves PR data\n       →  runs bin/sprint-journal.sh\n       →  writes .nanostack/know-how/journal/2026-03-25-myproject.md\n```\n\nThe 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.\n\n### Visual artifacts\n\nEvery phase artifact is JSON. JSON is what every skill reads, what trust verification hashes, what the sprint journal aggregates. That layer stays canonical.\n\nOn 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:\n\n```bash\nbin/render-artifact.sh plan --latest             # render the latest plan\nbin/render-artifact.sh review --latest           # review with severity counters\nbin/render-artifact.sh security --latest         # OWASP / STRIDE breakdown\nbin/render-artifact.sh license-audit --latest    # registered custom phase\nbin/render-artifact.sh journal --today           # whole sprint timeline\nbin/render-artifact.sh stack compliance-release  # custom workflow DAG\n```\n\nOutput 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.\n\nThe 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`).\n\n`--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.\n\nVisual 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`.\n\n### Knowledge compounding on /compound\n\nAfter shipping, run `/compound` to document what you learned:\n\n```\n/compound  →  reads sprint artifacts\n           →  identifies problems solved\n           →  writes to .nanostack/know-how/solutions/bug/\n           →  writes to .nanostack/know-how/solutions/pattern/\n           →  writes to .nanostack/know-how/solutions/decision/\n```\n\nNext 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.\n\nSolutions 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.\n\nSearch manually:\n\n```bash\nbin/find-solution.sh \"stripe webhook\"        # by keyword\nbin/find-solution.sh --type bug              # by type\nbin/find-solution.sh --tag security          # by tag\nbin/find-solution.sh --file src/api/webhooks # by file\n```\n\n### Failure capture\n\n`/compound` captures what worked. Failures get captured too, automatically, without waiting for a successful ship.\n\n```bash\nbin/capture-failure.sh review \"scope-drift.sh failed\" \"manual file comparison\" \"save plan artifact first\"\n```\n\nAppends 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.\n\n### Skill graduation\n\nSolutions 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.\n\n```bash\nbin/graduate.sh              # dry run: show candidates\nbin/graduate.sh --apply      # insert rules into SKILL.md files\nbin/graduate.sh --status     # show budget: how many rules per skill\nbin/graduate.sh --prune      # detect stale rules (referenced files gone)\n```\n\nBug 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.\n\nA 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.\n\n```\nSprint 1:  /compound documents \"webhook signature verification\" bug\nSprint 2:  /compound updates it, applied_count: 2, validated: true\nSprint 3:  /compound updates it, applied_count: 3\n           /compound runs graduate.sh, reports:\n           \"1 solution ready to graduate into security/SKILL.md\"\nYou:       bin/graduate.sh --apply\n           Rule is now baked into /security. No more runtime lookup.\n```\n\n### Diarization\n\nWhen 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.\n\n```bash\nbin/gather-subject.sh src/api/webhooks/    # directory\nbin/gather-subject.sh auth                 # keyword\nbin/gather-subject.sh src/lib/errors.ts    # exact file\n```\n\nOutput 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.\n\nDiarizations 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.\n\n### Analytics, token usage and patterns\n\n```bash\nbin/analytics.sh --tokens      # phase counts, security trends, token usage\nbin/token-report.sh            # token consumption per session and subagent\nbin/token-report.sh --all      # all projects with cost breakdown\nbin/pattern-report.sh          # recurring issues, risk accuracy, phase bottlenecks\nbin/graduate.sh --status       # graduation budget: rules per skill vs caps\nbin/doctor.sh                  # know-how health: stale, unused, unvalidated solutions\nbin/sprint-metrics.sh          # git stats + cycle time per phase (used by /think --retro and /nano)\nbin/about.sh                   # generate .nanostack/ABOUT.md (compact self-description for any agent)\nbin/capture-learning.sh \"...\"  # append a learning to the knowledge base\n```\n\n`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.\n\n`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.\n\n`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.\n\nEvery 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.\n\n### Discard a bad session\n\nIf a sprint went wrong (agent hallucinated findings, aborted halfway, bad data), discard it:\n\n```bash\nbin/discard-sprint.sh                     # discard all artifacts from today for this project\nbin/discard-sprint.sh --phase review      # discard only review artifacts\nbin/discard-sprint.sh --date 2026-03-24   # discard artifacts from a specific date\nbin/discard-sprint.sh --dry-run           # show what would be deleted without deleting\n```\n\nThis removes artifacts and the journal entry. Analytics recalculate on next run.\n\n### The Obsidian vault\n\nOpen `.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.\n\n## Build on nanostack\n\nUse 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.\n\n### Single skill\n\nScaffold a skill from the template, validate it, restart your agent:\n\n```bash\nbin/create-skill.sh license-audit --concurrency read --depends-on build\nbin/check-custom-skill.sh .nanostack/skills/license-audit\n```\n\nThe framework guarantees that one skill inherits, all proven by `ci/e2e-custom-stack-flows.sh`:\n\n- `save-artifact.sh license-audit` and `find-artifact.sh license-audit` accept the custom phase the same way they accept a core phase.\n- `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`).\n- `sprint-journal.sh` emits a `## /license-audit` section with the skill's status, headline, and artifact path.\n- `analytics.sh --json` adds the skill to `sprints.custom.license-audit` and counts it in `sprints.total`.\n- `discard-sprint.sh --dry-run` lists the skill's artifacts alongside the core ones.\n- `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`.\n\n### Workflow stack\n\nA 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.\n\nCopy the stack starting point:\n\n```\nexamples/custom-stack-template/compliance-release/\n```\n\nThe 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).\n\nA 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.\n\nFull walkthrough: [`EXTENDING.md`](EXTENDING.md).\n\n## Privacy\n\nNanostack itself has no cloud service.\n\nBy default, sprint artifacts, plans, journals, and know-how are written locally under `.nanostack/`.\n\nNanostack 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.\n\n`/think` supports `local_only`, `private`, and `public` search modes, so sensitive ideas do not require public web search.\n\nTelemetry 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.\n\nTiers: `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.\n\nChange your tier at any time:\n\n```sh\nnanostack-config set telemetry off\nnanostack-config set telemetry anonymous\nnanostack-config set telemetry community\n```\n\nRun `bin/analytics.sh` to see your own usage: which skills you run, how often, in what mode. Reads local artifacts only.\n\n## Troubleshooting\n\nQuick 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).\n\n**Skills don't appear as slash commands.**\nRestart your agent (Cursor and Codex need this; Claude Code does not). Re-run `./setup` if symlinks broke.\n\n**`jq: command not found` when running scripts.**\nInstall jq: `brew install jq` (macOS) or `apt install jq` (Linux).\n\n**Port in use when running /qa browser tests.**\nFind it: `lsof -ti:3000`. Kill it: `kill $(lsof -ti:3000)`.\n\n**`/conductor` claim fails with BLOCKED.**\nDependencies not finished. Run `conductor/bin/sprint.sh status` to check.\n\n**Phase gate blocked my git commit.**\nComplete `/review`, `/security`, `/qa` for the active sprint, or bypass with `NANOSTACK_SKIP_GATE=1 git commit ...` for non-sprint commits.\n\n**Skills seem outdated.**\nRun `/nano-update` from Claude Code, or `~/.claude/skills/nanostack/bin/upgrade.sh` from the terminal.\n\n## Uninstall\n\n```bash\n# Claude Code\ncd ~/.claude/skills && rm -f think nano review qa security ship guard conductor compound && rm -rf nanostack\n\n# Codex\nrm -rf ~/.agents/skills/nanostack*\n\n# Cursor\nrm -f .cursor/rules/nanostack.md\n\n# OpenCode\nrm -rf ~/.agents/skills/nanostack\n\n# Gemini CLI\ngemini extensions remove nanostack\n```\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, project structure and PR guidelines.\n\n- [Bug reports](https://github.com/garagon/nanostack/issues/new?template=bug_report.yml)\n- [Feature requests](https://github.com/garagon/nanostack/issues/new?template=feature_request.yml)\n- Security vulnerabilities: [SECURITY.md](SECURITY.md)\n\n## License\n\nApache 2.0\n",
  "bytes": 55251,
  "sha": "fb67563e5e16ae13a0f205ef51e9be147b19a14acf5a1c7870610deecf45b7fc",
  "repo_slug": "garagon/nanostack",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_garagon_nanostack_nanostack_d5699a2f/readme"
}