bin/ scripts

18 shell scripts for automation and analysis.

Sprint management

sprint.sh

Manage sprint state, phase claiming, and locking.

sprint.sh start <sprint-id>
sprint.sh claim <phase>
sprint.sh claim --force <phase>
sprint.sh complete <phase>
sprint.sh status
sprint.sh batch

save-artifact.sh

Write a phase artifact to disk with integrity checksums and secret scanning.

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

Knowledge base

find-solution.sh

Search the knowledge base for relevant bugs, patterns, and decisions.

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

check-staleness.sh

Flag knowledge base entries older than the configured threshold.

check-staleness.sh
check-staleness.sh --days 60
check-staleness.sh --archive   # move stale entries to archive/

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

drift-check.sh

Compare planned files against actual git diff. Used by /review internally.

drift-check.sh
drift-check.sh --plan .nanostack/plan/artifact.json

conflict-check.sh

Detect conflicting findings across phase artifacts. Used by /ship internally.

conflict-check.sh

Security

scan-secrets.sh

Scan a file or directory for hardcoded secrets using built-in patterns.

scan-secrets.sh <file>
scan-secrets.sh <directory> --recursive
scan-secrets.sh --patterns custom-patterns.json

redact.sh

Redact secrets in a file, preserving the configured prefix length.

redact.sh <file>
redact.sh <file> --prefix-length 4
redact.sh <file> --dry-run

guard-check.sh

Check a command against guard rules without executing it.

guard-check.sh "rm -rf node_modules"   # → allowed
guard-check.sh "rm -rf /"              # → blocked (G-002)
guard-check.sh "npm publish"           # → depends on phase

Stack detection

detect-stack.sh

Auto-detect the project stack from configuration files.

detect-stack.sh
detect-stack.sh --format json
detect-stack.sh --verbose    # show detection reasoning

detect-agent.sh

Identify which AI agent is running the current session.

detect-agent.sh
# Output: claude-code | codex | cursor | gemini | opencode | amp | cline | unknown

Setup and maintenance

setup.sh

Initialize nanostack for a project. Creates directories, detects stack, writes initial config.

setup.sh

verify.sh

Verify that all symlinks, permissions, and configs are correct.

verify.sh
verify.sh --fix    # auto-fix issues where possible

update.sh

Pull the latest version and re-apply symlinks and renames.

update.sh

Flags common to all scripts

  • --help — show usage information
  • --quiet — suppress non-error output
  • --json — output results as JSON (where applicable)
Previous← Artifact schemaNextTroubleshooting →