Nanostack started as a minimal set of skills for Claude Code: think, plan, review, security, QA, and ship, each passing context to the next through local artifacts.

The recent releases turned that into something more practical for real work: easier to inspect, easier to extend, and more predictable when an agent is reading, writing, and shipping from a repo. v1.1.1 is the safety and security hardening on top of v1.1.0.

Highlights across the v1.1.x line:

• visual artifacts turn plans, reviews, security checks, QA output, and sprint journals into HTML you can open and read
• custom workflow stacks let you build your own phases on top of Nanostack, instead of adding one-off skills
• artifacts carry integrity checks, so gates and context loaders verify the evidence they read
• the test harness was reorganized into shared fixtures, a manifest, and a local runner, so it is easier to know what broke and why

What v1.1.1 adds:

• stronger guards around risky shell commands, path containment, credential redaction, and write protection
• the global gates (phase, budget) now run before any allowlist or in-project shortcut, so a safe-looking command cannot skip them
• cleaner logs and promoted context, so they no longer carry data they should not
• honest framing: /freeze is a guided instruction, not a hook-enforced block

Nanostack works with Claude Code, Cursor, OpenAI Codex, OpenCode, and Gemini CLI, with stronger enforcement where the host supports it.

Nanostack v1.1.0 is the largest release since v1.0.0: 76 merged PRs. It grows Nanostack from a fixed sprint into a composable framework, adds a way to read any phase as local HTML, and hardens the safety and CI contracts. Everything stays local. Apache 2.0.

Custom workflow stacks

Nanostack is no longer only the built-in sprint. You can declare your own phases and compose them into a domain-specific workflow with the same lifecycle support as the default sprint.

• bin/create-skill.sh scaffolds a phase skill (--from starts from a template).
• .nanostack/config.json registers phases (custom_phases, phase_graph). A shared phase registry drives the conductor, guard, session, resolver, and next-step, so a custom stack gets graph-aware progression, concurrency enforcement, artifact trust, schema validation, and routing through phase_context.
• bin/check-custom-skill.sh validates a stack. The compliance-release example composes /license-audit, /privacy-check, and /release-readiness into one gate before /ship, with static, smoke, and runtime E2E coverage.

Visual artifacts

• bin/render-artifact.sh renders any phase artifact, sprint journal, or workflow-stack graph as an offline local HTML view (own CSS, no network).
• --strict refuses unverifiable evidence; --interactive adds copy-only buttons (prompt / Markdown / JSON patch) on /plan and /review, with no writes and no network calls.
• JSON stays canonical; the HTML is a derived view you can delete and regenerate. Registered custom phases render too.

Architecture and safety hardening

• Read-only phases (/review, /security, /qa) now block file mutations through Write/Edit/MultiEdit, not just Bash, so they are safe to run as one parallel batch.
• A shared artifact-trust primitive adds SHA-256 integrity to saved artifacts; release gates require trusted (integrity-checked, filename-dated) artifacts and fail closed on tampered evidence.
• Per-phase structured artifact schemas, a graph-aware session lifecycle, and a phase_context routing contract for custom skills.
• Guard blocks credential JSON at write time and on Bash. Adapter enforcement claims are locked to named CI evidence so the docs cannot overclaim.

/think and onboarding

• /think vNext: a structured think artifact, session-first flow, an autopilot minimum-viable-brief gate, quiet preset loading, and search modes with a privacy boundary (local_only / private / public).
• Guided Archetypes: /think detects the kind of work (founder validation, CLI tooling, API backend, landing) and routes the matching lens.
• /nano-run vNext: a schema-enforced setup artifact, a session-first rewrite, and a legacy detector that refuses silent migration.

Examples library

• A normalized examples index with four starter apps (todo, CLI notes, API healthcheck, static landing) plus the compliance-release custom stack, each tied to the delivery workflow and covered by per-archetype sprint E2E.

Contributor experience

• The CI harness subsystem shares one core library and fixtures, an inventory (ci/harnesses.json) that fails when it drifts from the real scripts, and a single local runner (ci/run-harness.sh --all). The large visual suite is split into reviewable sections, and long lint contracts are extracted into reusable checks.
• Reliability fixes: real user-flow E2E, a macOS write-guard symlink bypass closed, and a delivery-matrix harness for per-adapter coverage.

Honest scope

Hard enforcement is host-dependent. Claude Code has the strongest continuous hook coverage; the other verified adapters (Cursor, OpenAI Codex, OpenCode, Gemini CLI) run the same workflow as guided instructions unless their adapters/<host>.json proves otherwise. Nanostack has no cloud or backend; everything is local under .nanostack/. The heavier runtime end-to-end suites run in the opt-in E2E workflow (workflow_dispatch), not on every PR; lighter contract checks run on every PR.

Install

npx create-nanostack

Full changelog: v1.0.0...v1.1.0

The delivery experience release. Nanostack does not only protect the workflow; it now guides delivery like a professional engineering team, understandable for technical and non-technical users.

The honesty rule from v0.8 is preserved: no skill claims deterministic enforcement when the host adapter declares instructions_only. Adapter capability remains the source of truth.

Two profiles, same rigor

The session now records a profile field that shapes the wording of every phase output. The workflow does not change; the words do.

Wording rules: reference/plain-language-contract.md. Session fields: reference/session-state-contract.md.

Session-state workflow

bin/session.sh writes schema v2 with new fields:

• profile — guided or professional. Resolved per the profile selection rule: explicit flag, then config, then no-git => guided, then all guards instructions_only => guided, else professional.
• run_mode — normal or report_only. In report_only, skills do not edit files, fix issues, commit, or push. They only describe.
• plan_approval — manual, auto, or not_required. /feature always sets auto. --run-mode report_only forces not_required.
• capabilities — snapshot of the host adapter at init time, so audit trails are honest about what the host could enforce when the sprint started.
• policy — defaults follow profile (guided blocks outside-project writes and env reads; professional warns). User overrides via .nanostack/config.json cannot downgrade guided to allow.

bin/next-step.sh --json derives the next action from session state and falls back to fresh artifacts when the session is missing. Skills no longer encode their own next-step prose.

v1 sessions still read: every reader applies a compatibility table for missing fields.

Non-technical delivery output

Every Guided phase output (think, plan, qa, ship, doctor) follows a four-block skeleton:

1. Result. One sentence: what the skill found or did.
2. How to try. The exact command or URL. One action.
3. What was checked. Two or three short bullets.
4. What remains. What this skill could not check.

Spanish parity (Resultado / Como verlo / Que revise / Pendiente) ships across every skill. Local mode implies guided.

The contract is enforced at lint time: every fenced <!-- guided-output --> block is grepped for banned terms (artifact, PR, CI, branch, diff, hook, phase, security audit, QA, scope drift). Outside the fence, those terms are allowed (they are agent instructions, not user output).

/feature is always autopilot

/feature initializes the session with --autopilot --plan-approval auto. Manual feature work uses /think + /nano. There is no --manual flag.

Spanish first-class

README.es.md mirrors the v1.0 framing as "Dos perfiles, mismo rigor". TROUBLESHOOTING.es.md (new) covers the seven highest-traffic entries (slash commands no aparecen, jq, phase gate, puerto en uso, Windows, sprint atascado, conflicto de nombres). Advanced topics still point at canonical English.

Compatibility

No breaking changes. v1 session files written by 0.x installs continue to read correctly under the v2 compatibility layer. Skill APIs and slash commands unchanged.

How v1.0 shipped

Six small PRs, each independently reviewable:

Install

```sh
npx create-nanostack
```

To migrate an existing project to the v0.8+ hook model with a backup of .claude/settings.json:

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

Then run /nano-doctor to verify.

The repair release. Existing installs that predate the v0.8 hook era can now migrate with one command, no JSON editing required. The upgrade flow itself names the next step instead of leaving warnings on the next /nano-doctor run.

Migration UX

bin/init-project.sh gains four flags. Every migration path makes a timestamped backup of .claude/settings.json before changing anything, and re-runs /nano-doctor at the end so the result is visible without a second command.

SECURITY.md "Existing installs" section now points users at these flags instead of hand-editing JSON.

upgrade.sh closes the loop

After a successful upgrade, bin/upgrade.sh inspects the current project. If .claude/settings.json exists but is missing the Bash and Write/Edit hooks, the upgrade prints the exact init-project.sh --repair command for the project. Silent in every other case (not in a project, hooks already wired, jq unavailable). No central project registry: only the cwd is inspected, with a one-step walk to the git root if needed. Privacy constraint preserved.

Already shipped during v0.8 audit rounds

These v0.9 spec items already landed in the v0.8 audit round 4:

• Symlink-resolving Write/Edit guard.
• Broader secret-disclosure rules covering grep, rg, jq, awk, sed, strings, od, xxd, hexdump, plus bare env / printenv (with env VAR=value cmd still allowed).
• CI matrix expanded with new jobs for guard regression (35 cases), write-guard regression (19 cases), supply-chain checks, adapter-schema validation.

Compatibility

No breaking changes. Default init-project.sh behavior (no flag) is unchanged: create new settings with hooks; merge into existing without touching the hooks block. Backward compatible with installs from before this release.

Install

npx create-nanostack

To migrate an existing project to the v0.8+ hook model:

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

Full diff

v0.8.0...v0.9.0

The honest-capabilities release. After three audit rounds today, this version stops claiming uniform enforcement across agents and starts reading from a single source of truth. Setup, nano-doctor, README, and README.es all consume adapters/<host>.json so the difference between Claude Code's enforced hooks and the guided workflow on Cursor / Codex / OpenCode / Gemini is named consistently across every surface.

Adapter contract

• reference/host-adapter-schema.md defines an L0-L3 capability vocabulary (Guided / Checked / Guarded / Blocked when unsafe) with explicit rules for "observation overrides declaration".
• adapters/{claude,codex,cursor,opencode,gemini}.json declare each host's real protection level today, plus last_verified and verification.method so anyone can tell which guarantees are CI-asserted and which are manual.
• New CI job host-adapter-schema validates required fields, capability values, host/filename match, and verification evidence on every PR. The contract is enforced, not aspirational.
• nano-doctor reads the adapter for each detected host CLI and reports protection per host, with drift warnings when the declaration and the observed install disagree.
• setup prints a tight protection-level summary by default. --verbose unlocks the legacy skill listing.
• README and README.es replaced "every step is enforced" with a per-host capability matrix grounded in the adapter files.

Internal audit round 4

• Write/Edit guard resolves symlinks. A mylink/config -> ~/.ssh/config no longer slips past the prefix denylist; both the original and resolved path are evaluated.
• Broader secret-read rules. G-030 now covers grep, rg, jq, awk, sed, strings, od, xxd, hexdump, wc, file, stat, tr, plus the existing cat / head / tail family. New G-031 blocks bare env / printenv while leaving env VAR=value cmd allowed.
• nano-doctor --fix wires hooks for legacy installs. Detects missing PreToolUse matchers, makes a timestamped backup of .claude/settings.json, merges the matchers in via jq. Idempotent; existing permissions stay untouched.
• Doctor JSON output preserves pipes and quotes. Internal separator switched from | to tab; envelope built with jq -R -s. Write|Edit|MultiEdit no longer truncates at the first pipe.
• /feature autopilot contract fixed. Session init now passes --autopilot, so the orchestrator no longer collides with /nano's default approval pause.
• Guard tier docs refreshed. README now describes block-before-allowlist (matching the code), and the cross-agent gap is named explicitly.

Compatibility

No wire-schema breaking changes. init-project.sh continues to leave existing .claude/settings.json untouched on merge. /nano-doctor --fix is the opt-in migration path for legacy installs that want to add the Write/Edit guard hook.

Install

npx create-nanostack

After install, run /nano-doctor to see the honest state of your permissions and hook wiring on the agents you have installed.

Full diff

v0.7.0...v0.8.0

Third security round of the day. The guard shifts from "Bash-only, allowlist-first" to an authoritative layer: block rules run before the allowlist, and a new hook covers Write, Edit, and MultiEdit. Four PRs (#139, #140, #141, #142) closed all seven findings from the round 3 audit.

Guard becomes authoritative

• Block before allowlist. Binaries on the allowlist (find, cat, head, tail) no longer short-circuit past block rules. find . -delete, find . -exec rm -rf {} +, cat .env, head .env, tail secrets.pem now return exit 1 with the matching block rule. G-005, G-006, G-030 are effective again.
• Write and Edit covered. New guard/bin/check-write.sh PreToolUse hook. Denies secrets by basename (.env and variants, *.pem, *.key, *.p12, *.pfx, SSH keys including id_rsa/id_ed25519/authorized_keys, shell history) and by path prefix (/etc, /var, /usr/bin, /usr/sbin, /usr/lib, /System, /private/etc, ~/.ssh, ~/.gnupg, ~/.aws, ~/.gcp, ~/.config/gcloud, ~/.kube).
• Fresh installs wire both hooks. init-project.sh writes a hooks.PreToolUse block alongside permissions, with matchers for Bash (check-dangerous.sh) and Write|Edit|MultiEdit (check-write.sh). Existing installs are not modified; manual wire-up is in SECURITY.md.
• git push --force-with-lease passes. G-007 tightened from git push --force to git push.*--force([[:space:]]|$) so the guard's own recommended alternative stops tripping the block.

/nano-doctor reports the full model

Five rows across permissions and hook presence:

• rm_scope, write_scope, allowlist_scope — cross-reference the relevant hook.
• bash_guard, write_guard — report hook presence directly.

A broad Write(*) with the hook wired now reads as pass with a note that the hook covers secrets and system paths. Without the hook it warns with concrete remediation pointing at SECURITY.md.

CI coverage

• Guard regression matrix expanded from 12 to 21 cases. New cases cover the allowlist-bypass class (find . -delete, cat .env, etc.) plus the --force-with-lease positive.
• New write-guard-regression job: 19 cases plus two JSON-on-stdin contract checks so a Claude Code protocol drift surfaces on every PR.

Portability and integrity

• feature/bin/enforce-sprint.sh uses BSD stat with a GNU stat fallback, mirroring the pattern in guard/bin/phase-gate.sh. Gates run on Linux agents, not just macOS.
• bin/resolve.sh passes --verify to find-artifact.sh. Tampered artifacts no longer feed downstream phases (gates, review context, conflict precedence).

Compatibility

No breaking changes to the wire telemetry schema. Existing .claude/settings.json files are not modified. The Write/Edit hook is only wired automatically for fresh installs; existing installs opt in via the copy-paste block in SECURITY.md.

Install

npx create-nanostack

Run /nano-doctor in your project to see the honest state of your permission and hook surface.

Full diff

v0.6.0...v0.7.0

Six weeks of work since the v0.1.0 baseline. This is the first tag since the VERSION file was introduced, and it reflects the features, skills, and hardening that landed along the way.

New surface

• /nano-doctor — install health-check skill. Ten checks across deps, install integrity, home directory permissions, telemetry config, pre-V5 detection, and Worker reachability. Exit code maps to severity: 0 healthy, 1 warnings, 2 critical. Flags: --json, --offline, --fix.
• Observational feedback in /think — optional ## What I noticed block when a coaching pattern fires (jump-to-solution, scope drift, strong pain observation, surprising synthesis). Silence beats a forced observation. Target firing rate under 30% of sessions.
• observational_fired v1 telemetry field — measures firing rate of the feedback block without any content leaving the machine. Additive, nullable; only /think sets it.
• NANOSTACK_DEBUG=1 — surfaces the pre-V5 detection decision (marker-present, pre-V5, or fresh-install) so future silent bugs surface on first run.
• Latent-vs-deterministic reference — linked from /think (Phase 4 Premise Challenge) and /nano (Architecture Checkpoint). Names when to trust the model versus when to build infrastructure.

Internal security round (all findings closed)

• Guard block rules run before the in-project shortcut so recursive operations that resolve inside the repo cannot bypass.
• setup --rename input validated via strict regex plus path_is_under guard before any rm.
• Audit log records built via jq -cn --arg so quoted, backslashed, or newline-laden fields cannot inject extra keys.
• Session lock records owner PID and uses kill -0 to tell stale from live; fails closed at 30s.
• Wrangler bumped from 3.60 to 4.85; bun audit went from 6 vulnerabilities to 0.
• Guard audit trail lands in .nanostack/audit.log regardless of NANOSTACK_STORE state.
• CI adds bun install --frozen-lockfile, bun audit, tsc --noEmit, and a 12-case guard regression matrix.
• Default rm scope narrowed to .nanostack/** and /tmp/**. Existing installs untouched; /nano-doctor surfaces broad legacy entries with an opt-in migration path.
• Permission model documented in SECURITY.md.

Compatibility

No breaking changes to the wire telemetry schema. observational_fired is additive and nullable. Existing opt-in installations continue to send events that pass Worker validation.

init-project.sh never removes entries from an existing .claude/settings.json; pre-v0.6 installs keep whatever they had and can migrate on their own timeline.

Install

npx create-nanostack

See README for the full set of skills and TROUBLESHOOTING.md if you hit anything.

Full diff

v0.1.0...v0.6.0