NanoStack

Requirements

• macOS or Linux shell environment (Windows works with Git Bash or WSL)
• bash
• git
• jq (brew install jq, apt install jq, or choco install jq)
• One AI coding agent with a verified adapter: Claude Code, Cursor, OpenAI Codex, OpenCode, or Gemini CLI

Nanostack has no app runtime dependency and no build step. The scripts use standard local tools.

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

What changes after installing Nanostack

Install

Project setup

Run once in each project to configure permissions and .gitignore. Requires git clone install.

~/.claude/skills/nanostack/bin/init-project.sh

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

Build on nanostack

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

Uninstall

```bash

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.

Analytics, token usage and patterns

bin/analytics.sh --tokens      # phase counts, security trends, token usage
bin/token-report.sh            # token consumption per session and subagent
bin/token-report.sh --all      # all projects with cost breakdown
bin/pattern-report.sh          # recurring issues, risk accuracy, phase bottlenecks
bin/graduate.sh --status       # graduation budget: rules per skill vs caps
bin/doctor.sh                  # know-how health: stale, unused, unvalidated solutions
bin/sprint-metrics.sh          # git stats + cycle time per phase (used by /think --retro and /nano)
bin/about.sh                   # generate .nanostack/ABOUT.md (compact self-description for any agent)
bin/capture-learning.sh "..."  # append a learning to the knowledge base

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.

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.

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.

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

Configurable rules

All rules live in guard/rules.json. Each rule has an ID, regex pattern, category, description and (for block rules) a safer alternative. Add your own:

{
  "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"
}

Workflow stack

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

Copy the stack starting point:

examples/custom-stack-template/compliance-release/

The stack's README walks through the install. The directory contract for any new stack is in reference/custom-stack-examples-technical-spec.md; the framework contract those skills inherit is in reference/custom-stack-contract.md.

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

Full walkthrough: EXTENDING.md.

Alternative: git clone (advanced)

Full control including skill rename, analytics, sprint journal and project setup.

git clone https://github.com/garagon/nanostack.git <path>
cd <path> && ./setup --host auto

Targets: claude, codex, cursor, opencode, gemini, auto.

Alternative: Gemini CLI

gemini extensions install https://github.com/garagon/nanostack --consent

Troubleshooting

Quick fixes for the most common issues. For the full guide (Windows setup, proxy installs, stuck sprints, name conflicts, autopilot loops), see TROUBLESHOOTING.md.

Skills don't appear as slash commands. Restart your agent (Cursor and Codex need this; Claude Code does not). Re-run ./setup if symlinks broke.

jq: command not found when running scripts. Install jq: brew install jq (macOS) or apt install jq (Linux).

Port in use when running /qa browser tests. Find it: lsof -ti:3000. Kill it: kill $(lsof -ti:3000).

/conductor claim fails with BLOCKED. Dependencies not finished. Run conductor/bin/sprint.sh status to check.

Phase gate blocked my git commit. Complete /review, /security, /qa for the active sprint, or bypass with NANOSTACK_SKIP_GATE=1 git commit ... for non-sprint commits.

Skills seem outdated. Run /nano-update from Claude Code, or ~/.claude/skills/nanostack/bin/upgrade.sh from the terminal.