What is nanostack

Your agent can already write code. Nanostack gives it delivery structure.

The default sprint turns a vague request into a scoped, reviewed, audited, tested change with a PR and a sprint journal. Each phase reads the artifact the previous phase wrote, so context does not vanish between steps. The framework layer lets you add your own phases on top.

Default sprint

Think, plan, build, review, security, qa, and ship. Seven phases that keep product thinking, planning, implementation, review, audit, verification, and release connected.

Evidence between phases

Each phase saves a structured artifact under .nanostack/. Downstream phases read it through the resolver instead of relying on chat memory. New artifacts carry a SHA-256 integrity field.

Build your own stack

Add custom skills, wire them with phase_graph, and the same lifecycle handles routing, artifacts, journals, analytics, and conductor scheduling. Create a skill →

Example

From vague request to reviewed PR

A full delivery loop. Not just code generation. The agent pushes back on scope, ships what matters, and leaves a record behind.

nanostack sprint

you

I need Stripe payments. Users should subscribe to a monthly plan.

❯ /think

agent

A full billing system is too broad for this sprint. Start with Checkout plus one webhook that flips is_pro. Build invoices and plan switching after real subscribers.

Scope: REDUCE.

you

Checkout + webhook. Let's go.

plan❯ /nanoCheckout session, webhook verification, access gate. Files, risks, and checks listed before code.

build❯ buildAgent implements the planned files inside the agreed scope.

review❯ /reviewScope drift check and structural review. Flags webhook signature handling.

security❯ /securityVerifies secret handling, webhook verification, and auth boundary. Reports findings and grade.

qa❯ /qaExercises the subscribe path and access gate.

ship❯ /shipPR opened. CI state attached. Sprint journal saved under .nanostack/.

See full examples → · How each phase works →

Workflow

The default sprint

The default sprint is the workflow Nanostack ships out of the box. It keeps product thinking, planning, implementation, review, security, QA, and shipping connected through artifacts.

This is the default. Add your own phases or create custom skills to extend it.

/thinkthink.json
/nanoplan.json
build
/reviewreview.json
/securitysecurity.json
/qaqa.json
/shipship.json

Phases and outputs

phase	role	output
/think	Product discovery	Structured brief: user, wedge, risk, premise. Challenges scope before building.
/nano	Planning	Files, risks, checks, and out-of-scope items written before code. Searches past solutions first.
build	Implementation	Code change inside the agreed scope.
/review	Staff review	Findings, scope drift (plan vs git diff), and conflict notes. Cross-references downstream phases.
/security	Security audit	OWASP/STRIDE findings and grade. Auto-detects stack. By oktsec.
/qa	Verification	Browser, API, or CLI checks. Screenshots when relevant. WTF-likelihood heuristic before retrying.
/ship	Release	PR, CI state, release notes, and sprint journal saved under .nanostack/.

/review, /security and /qa support --quick, --standard, --thorough. All commands →

Safety

Guard catches risky actions before they run.

Security by oktsec

Guard evaluates commands before the agent executes them. Block rules run before the allowlist, so a safe binary with a dangerous argument still gets stopped.

BLOCKED [G-007]

Category: history-destruction
Command: git push --force origin main

RESOLVED

Alternative: git push --force-with-lease
Fails if remote has changed since last fetch.

Block rules (sample)

G-001block

rm -rf /

Mass deletion of root or wide paths.

G-007block

git push --force

History destruction on protected branches.

G-014block

DROP TABLE

Database destruction without an explicit WHERE guard.

G-017block

kubectl delete

Infrastructure destruction on production namespaces.

G-023block

curl | sh

Remote code execution through pipe-to-shell.

G-027block

--no-verify

Safety bypass on commit and push hooks.

Full block and warn rules →

Six tiers (evaluated in order)

1.Block rulesMass deletion, history destruction, database drops, remote code execution, secret reads, safety bypasses.

2.AllowlistSafe commands such as git status, ls, cat, and jq continue only after block rules clear.

3.In-projectRepo-local changes stay inside the project boundary.

4.Phase-aware concurrencyRead-only phases block writes, including registered custom phases.

5.Phase gateCommit and push wait for fresh review, security, and qa artifacts where host enforcement supports it.

6.Budget gateOptional sprint budget stops non-allowlisted work when the threshold is reached.

Write, Edit, and MultiEdit parity

Write, Edit, and MultiEdit go through their own hook. It blocks protected paths, credential files, credential JSON basenames, and system secret directories after resolving symlinks.

Safe templates such as .env.example and credentials.example.json remain usable.

Hard blocking depends on the host. Claude Code can enforce through hooks. Other verified adapters may run the same workflow as guided instructions or reported checks, depending on their capability file. The source of truth is adapters/<host>.json in the repo.

Architecture

Evidence moves the sprint forward.

Each phase writes a structured artifact. The next phase reads it through the resolver. New artifacts carry an integrity hash, so strict consumers can refuse to read a corrupted upstream.

Structured artifacts

Every phase writes JSON under .nanostack/. New artifacts carry a SHA-256 integrity field. Schemas catch malformed outputs before downstream phases depend on them.

Trust-aware reads

find-artifact.sh can verify integrity, and strict consumers can require it with --require-integrity. Legacy artifacts are marked instead of silently pretending to be structured evidence.

Resolver as the context gateway

Every skill starts with resolve.sh. It returns upstream artifacts, past solutions, config, phase_context, routing.trust, and upstream_status in one JSON object.

Graph-aware custom phases

Custom phases declare dependencies in phase_graph. Session state, next-step output, conductor scheduling, guard concurrency, journals, analytics, and discard all read the same graph.

Local memory across sprints

/compound and sprint journals turn solved problems into reusable knowledge, still stored locally under .nanostack/. /nano and /review search past solutions before planning.

Framework

Build your own workflow stack.

Nanostack is not only the default sprint. It is a framework for adding phases that match how your team ships.

Start with one custom skill

bin/create-skill.sh license-audit --concurrency read --depends-on build
bin/check-custom-skill.sh .nanostack/skills/license-audit

The skill can save artifacts, read upstream context, appear in journals and analytics, and be scheduled by the conductor. resolve.sh returns phase_kind: "custom", and upstream artifacts are driven by depends_on or phase_graph.

Then wire multiple skills into a stack

The compliance-release example adds /license-audit, /privacy-check, and /release-readiness before /ship. It is not a certification product. It is a worked example of a domain workflow with contract checks and runtime E2E coverage.

49 static contract checks. A 15-cell, 51-assertion runtime harness in the opt-in E2E workflow.

Framework overview → · Create your first skill → · EXTENDING.md →

Try safely

Examples by maturity

Each example runs the default sprint on a tiny app. Start with what you know, then move up.

example	best for	what it proves
starter-todo	new users	Full sprint on a tiny app.
cli-notes	CLI builders	Plan, test, review, and ship for a command-line tool.
api-healthcheck	backend / API users	Real HTTP probe and API verification.
static-landing	frontend users	Visual QA and safe static-site changes.
compliance-release	advanced framework evaluators	Custom stack with license, privacy, and release gate. Advanced example, not a starter app and not a compliance certification.

starter-todo

Best for: new users
What it proves: Full sprint on a tiny app.

cli-notes

Best for: CLI builders
What it proves: Plan, test, review, and ship for a command-line tool.

api-healthcheck

Best for: backend / API users
What it proves: Real HTTP probe and API verification.

static-landing

Best for: frontend users
What it proves: Visual QA and safe static-site changes.

compliance-release

Best for: advanced framework evaluators
What it proves: Custom stack with license, privacy, and release gate. Advanced example, not a starter app and not a compliance certification.

See full examples →

Setup

Install

Detects your agents, installs the skills, and runs setup. Then run /nano-run in your agent to configure the project.

Does not modify your code.

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

Alternative for Gemini CLI users

Options (for advanced users)

--host <agent>Pick a specific target: claude, codex, cursor, opencode, gemini, auto.--localProject-scoped install.--renameAvoid naming collisions with existing skills.--listShow installed skills.

Update

/nano-update

Requires macOS, Linux, or Windows through Git Bash or WSL. Requires git and jq. The installer itself is run through npx.

See it in action before installing →

Privacy

No Nanostack cloud.

By default, sprint artifacts, plans, journals, and know-how stay under .nanostack/ on your machine. Nanostack 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 provider's privacy settings and your own data policies for sensitive work.

/think supports local_only, private, and public search modes, so sensitive ideas do not require public web search.

Telemetry is opt-in and limited to aggregate usage events. If enabled, it is documented in TELEMETRY.md.

Start with the default sprint.

Build your own stack when the workflow needs to match your team.

View on GitHub See examples →EXTENDING.md →