Workflow Order

The default workflow is: /think → /nano → build → /review → /qa → /security → /ship

With /conductor, review + qa + security run in parallel — they all depend on build, not on each other:

think → plan → build ─┬─ review  ─┐
                      ├─ qa       ├─ ship
                      └─ security ─┘

Activate /guard at any point when operating near production or sensitive systems.

Zen

Read ZEN.md for the full set of principles. When in doubt about a decision during any skill, consult it. The short version:

• Question the requirement before writing the code.
• Delete what shouldn't exist. Don't optimize what's left until you do.
• Narrow the scope, not the ambition.
• 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.

Intensity Modes

Skills /review, /security, and /qa support intensity modes:

| Mode | Flag | When | Confidence | |------|------|------|-----------| | Quick | --quick | Trivial changes (typos, config, docs) | 9/10 — only the obvious | | Standard | (default) | Normal changes | 7/10 — anything reasonable | | Thorough | --thorough | Critical changes (auth, payments, infra) | 3/10 — flag everything suspicious |

Skills auto-suggest a mode based on the diff, but the user always decides.

Artifact Persistence

Saving artifacts is not optional. Every skill must save its artifact after completing.

Skills automatically save their output to .nanostack/ after every run:

.nanostack/<phase>/<timestamp>.json

This enables:

• Scope drift detection — /review compares planned vs actual files
• Conflict detection — /review and /security cross-reference each other's findings
• Sprint journals — /ship generates a journal entry from all phase artifacts
• Trend tracking — Are security findings decreasing over time?

Auto-saving is on by default. The user can disable it by setting auto_save: false in .nanostack/config.json.

Artifacts are validated before saving: save-artifact.sh rejects invalid JSON, missing required fields (phase, summary), and phase mismatches.

To discard artifacts from a bad session: bin/discard-sprint.sh (removes artifacts and journal entry for the current project and date).

Conflict Resolution

When skills produce contradictory guidance (e.g., /review says "more error detail" but /security says "minimize error exposure"), the conflict resolution framework applies:

1. Security has default precedence — unless the risk is theoretical or internal-only
2. Context determines final precedence — public-facing app vs internal tool vs startup vs compliance
3. Conflicts are documented, not silenced — every resolution is recorded in the skill artifact

Read reference/conflict-precedents.md for known conflict patterns and pre-defined resolutions.

Project Config

On first use in a project, run bin/init-config.sh --interactive to create .nanostack/config.json. This stores:

• Installed agents — auto-detected (claude, codex, cursor, opencode, gemini)
• Detected stack — node, go, python, docker
• Preferences — default intensity mode, auto-save, conflict precedence

If config exists, read it at the start of any skill to adapt behavior:

bin/init-config.sh  # outputs current config or {} if none

Skills use config for:

• /review, /qa, /security: read preferences.default_intensity instead of always defaulting to standard
• /security: read preferences.conflict_precedence to determine who wins in cross-skill conflicts
• /security: read detected to skip irrelevant checks (don't scan for Python vulns in a Go project)

Per-skill configs (security/config.json, guard/config.json) store skill-specific settings and are read by that skill only.

Universal Rules

• Read before acting. Every skill must read the relevant code/diff/config before producing output. Never analyze blind.
• Boil the lake, not the ocean. When completeness costs minutes more than shortcuts, do the complete thing. When it costs days, don't.
• Log failures, not just successes. When something goes wrong during a skill (script error, wrong approach, unexpected project behavior), capture it:

  ~/.claude/skills/nanostack/bin/capture-failure.sh <skill> "<what went wrong>" "<what was tried>" "<what fixed it>"
  

  Failures compound into knowledge. Next sprint, the same mistake is avoided. This does not require /compound or a successful ship — just log and move on.

Proactive Triggers

Suggest skills when context matches — don't wait for the user to remember:

| Trigger | Suggest | |---------|---------| | User says "what should I build" / unclear on direction | /think | | Task touches 3+ files or user says "how should I approach this" | /nano | | User says "done", "finished", "ready for review" | /review | | User says "does this work", "test this", bug report | /qa | | Pre-ship, user says "ready to deploy", or diff touches auth/env/infra | /security | | User says "create PR", "merge", "ship it" | /ship | | Destructive commands, production access, or sensitive operations detected | /guard |

Usage Rules

• Start with /think for new products or when the "what" is unclear
• Run /nano before building anything that touches more than 3 files
• Run /review on your own code — the adversarial pass catches what you missed
• /security is not optional before shipping to production
• /guard is on-demand — activate it, don't leave it always on
• Skills compose: /qa can invoke /security checks, /ship can invoke /review

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. The session fields that select the profile live in 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/ are the source of truth for each host.

| Level | Meaning | |-------|---------| | L0 Unsupported | Nanostack cannot provide this capability on that host. | | L1 Instructions only | The skill tells the agent what to do, but cannot block it. | | L2 Reported | Nanostack can detect and report the issue. | | L3 Enforced | Nanostack can block the action through host hooks or guard scripts. |

A detailed per-host matrix (Bash guard, Write/Edit guard, phase gate) lives further down in What enforces on which agent.

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

Choose your path

| If you are... | Start here | |---|---| | New to agent workflows | Try starter-todo, then run /nano-run | | Already shipping with AI agents | Install Nanostack, then start with /think or /feature | | Evaluating safety | Read Guard and the host enforcement matrix | | Building your own workflow | Start with EXTENDING.md and compliance-release |

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 | new and non-technical users | one HTML file | 5-10 min | | cli-notes | CLI workflows | Bash | 5-15 min | | api-healthcheck | backend flows | Node stdlib HTTP | 10-15 min | | static-landing | founders and designers | static HTML/CSS | 10-15 min | | 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/.

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

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.

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.