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 you build. Refines a rough idea through questions, explores alternatives, walks the design in sections.	—	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 → /security → /qa → /ship

With /conductor, review + security + qa 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