nanostack

---
name: nanostack
description: Use when the user asks about available workflow skills, wants an overview of the engineering workflow, or references "nanostack". Also triggers on /nanostack.
---

# Nanostack — Engineering Workflow Skills

You have access to a set of composable engineering workflow skills. Each skill is a folder with supporting files — read them as needed for context.

## Available Skills

| Skill | When to use | Modes | Key files |
|-------|-------------|-------|-----------|
| `/think` | Before planning — strategic product thinking, premise validation, scope decisions. | — | `think/references/forcing-questions.md`, `think/references/cognitive-patterns.md` |
| `/nano` | Before starting any non-trivial work. Produces a scoped, actionable plan. | — | `plan/templates/plan-template.md` |
| `/review` | After code is written. Two-pass review + scope drift detection + conflict resolution. | `--quick` `--standard` `--thorough` | `review/checklist.md`, `reference/conflict-precedents.md` |
| `/qa` | To verify code works. Browser-based testing with Playwright, plus root-cause debugging. | `--quick` `--standard` `--thorough` | `qa/bin/screenshot.sh` |
| `/security` | Before shipping. OWASP Top 10 + STRIDE + variant analysis + conflict detection. | `--quick` `--standard` `--thorough` | `security/references/owasp-checklist.md`, `security/templates/security-report.md` |
| `/ship` | To create PRs, merge, deploy, and verify. Generates sprint journal on success. | — | `ship/templates/pr-template.md` |
| `/guard` | When working near production, destructive operations, or sensitive systems. | — | `guard/bin/check-dangerous.sh` |
| `/feature` | Add a feature to an existing project. Skips /think, goes straight to plan → build → review → security → qa → ship. | — | `feature/SKILL.md` |
| `/conductor` | Orchestrate parallel agent sessions through a sprint. Coordinate task claiming and artifact handoff. | `start` `claim` `complete` `status` | `conductor/bin/sprint.sh` |
| `/nano-run` | First-time setup. Configures stack, permissions, and preferences conversationally. Guides first sprint. | — | `start/SKILL.md` |
| `/nano-help` | Quick reference for all nanostack commands and how to use them. | — | `help/SKILL.md` |

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

```bash
.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:
```bash
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:
  ```bash
  ~/.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`