bin/ scripts
18 shell scripts for automation and analysis.
Sprint management
session.sh
Session lifecycle: init, phase-start, phase-complete, resume, status, archive. Tracks sprint state and enables crash recovery.
session.sh init <type> [--issue <url>] session.sh phase-start <phase> session.sh phase-complete <phase> session.sh resume session.sh status session.sh archive
save-artifact.sh
Write a phase artifact to disk with integrity checksums. Secret scanning and redaction happen inline (lines 106-117 of the script) before the artifact is persisted.
save-artifact.sh <phase> <json-file> save-artifact.sh review /tmp/review-output.json
find-artifact.sh
Locate and read a phase artifact with optional integrity verification.
find-artifact.sh <phase> find-artifact.sh <phase> --verify find-artifact.sh --all
budget.sh
Token budget enforcement. Set a max spend per sprint and check usage at phase transitions. Warns at 80%, stops at 95%.
budget.sh set 500000 budget.sh check budget.sh status
circuit.sh
Circuit breaker for retry loops. Tracks consecutive failures and opens the circuit after a threshold. A new approach resets the counter.
circuit.sh record-failure <phase> circuit.sh record-success <phase> circuit.sh status
restore-context.sh
Reads all phase checkpoints from the current sprint and produces a compact summary for session recovery after a crash.
restore-context.sh
Analysis
analytics.sh
Sprint analytics: timing, finding counts, phase durations, trends.
analytics.sh # current sprint analytics.sh --history 10 # last 10 sprints analytics.sh --export csv # export to CSV analytics.sh --tokens # merge token data
scope-drift.sh
Compares planned files from the /nano artifact against the actual git diff. Reports added, missing, and out-of-scope files. Used by /review internally.
scope-drift.sh scope-drift.sh --plan .nanostack/plan/artifact.json
token-report.sh
Token usage from Claude Code session logs. Per-session and per-subagent breakdown with cache-aware pricing and anomaly detection. Claude Code only — skips gracefully on other agents.
token-report.sh # current project token-report.sh --all # all projects token-report.sh --since 7d # last 7 days token-report.sh --subagents # per-subagent breakdown token-report.sh --check # anomaly detection token-report.sh --json # machine-readable
pattern-report.sh
Cross-sprint pattern detection. Recurring findings, risk prediction accuracy, phase bottlenecks, and solution reuse stats.
pattern-report.sh # current month pattern-report.sh --since 30d pattern-report.sh --json
Knowledge
find-solution.sh
Search the knowledge base for relevant bugs, patterns, and decisions. Staleness is handled inline: results older than the configured threshold are flagged. Validated solutions rank higher than untested ones.
find-solution.sh --tags "timezone,dates" find-solution.sh --files "src/routes/streaks.ts" find-solution.sh --query "streak calculation"
save-solution.sh
Write a new bug, pattern, or decision to the knowledge base.
save-solution.sh bug /tmp/timezone-fix.json save-solution.sh pattern /tmp/error-handling.json save-solution.sh decision /tmp/no-orm.json
sprint-journal.sh
Generates a sprint summary by reading all phase artifacts. Saves the result to know-how/journal/.
sprint-journal.sh
capture-learning.sh
Appends a learning to know-how/learnings/ongoing.md. Used throughout a sprint to capture insights before /compound formalises them.
capture-learning.sh "Summary of the learning"
Team
validate-dependencies.sh
Checks if phase dependencies are satisfied before a phase is claimed in /conductor. Prevents agents from racing ahead when upstream artifacts are missing.
validate-dependencies.sh <phase> validate-dependencies.sh review
Safety
Safety scripts live under guard/bin/, not bin/. The main entries are:
- guard/bin/check-dangerous.sh— intercepts commands against the block and warn rules in guard/rules.json.
- guard/bin/phase-gate.sh— blocks commit/push until review, security, and qa have finished.
Setup and maintenance
init-project.sh
Configure project permissions and .gitignore for nanostack. Writes .claude/settings.json so autopilot can run uninterrupted.
init-project.sh
upgrade.sh
Pull the latest version from GitHub. Used internally by /nano-update.
upgrade.sh
discard-sprint.sh
Remove artifacts from a bad sprint. Supports filters so you can discard a single phase or everything from a given day.
discard-sprint.sh --dry-run discard-sprint.sh --phase review discard-sprint.sh --date 2026-04-11
Flags common to all scripts
- --help — show usage information
- --quiet — suppress non-error output
- --json — output results as JSON (where applicable)