STAN is a CLI that bridges your IDE with your favorite LLM and drives a rapid, powerful, low-friction, design-first iterative development process. Real-world AI-assisted development for professional engineers!

STAN — STAN Tames Autoregressive Nonsense

STAN produces a single source of truth for AI‑assisted development: a tarball of your repo plus deterministic text outputs from your build/test/lint/typecheck scripts.

You get portable, auditable, reproducible context—locally and in CI.

Because a freaking chatbot shouldn’t gaslight your code.

Getting Started

Please see the Getting Started guide for setup instructions.

The STAN Loop

STAN drives a rigorous, iterative development process:

1. Run (Validate & Commit)

   • Run stan run to execute all scripts (test, lint, build, etc.) and generate the "Ground Truth" outputs.
   • Run git commit to save the state (green or red).

2. Snap (Sync)

   • Run stan snap to baseline the diff.
   • Upload artifacts (archive.tar/diff.tar + outputs) to the chat.

3. Patch (The Intelligence)

   • Discuss requirements and plan.
   • The assistant implements changes and drafts a commit message.
   • Run stan patch to apply changes, then return to Run.

Why STAN?

• Reproducible context: one archive captures exactly the files to read.
• Structured outputs: test/lint/typecheck/build logs are deterministic and easy to diff.
• Always‑on diffs: STAN writes archive.diff.tar for changed files automatically.
• Preflight guardrails: nudges you to update prompts when the baseline changes.
• Patch workflow: paste a unified diff or read from a file; STAN applies it safely and opens modified files in your editor. If a patch fails, STAN provides an improved patch and a full listing just for good measure.

Configuration (stan.config.yml)

Minimal example:

stanPath: .stan
includes: []
excludes: []
scripts:
  build: npm run build
  lint: npm run lint
  test: npm run test
  typecheck: npm run typecheck

See STAN Configuration for more!

Commands at a glance

• Run (build & snapshot)

  stan run                 # runs all configured scripts and writes archives
  stan run -s test         # run only “test”
  stan run -S              # do not run scripts (combine with -A/-p)
  stan run -x test         # run all except “test”
  stan run -q -s lint test # sequential run subset in provided order
  stan run -b -s test      # combine archives & outputs
  stan run -A              # do not create archives
  stan run -p              # print plan only, no side effects
  stan run -P              # do not print the plan first

• Snap (share & baseline)

  stan snap  stan snap undo | redo | set <index> | info
  stan snap -s # stash before snap; pop after

• Patch (discuss & patch)

  stan patch               # from clipboard
  stan patch --check       # validate only
  stan patch -f file.patch # from file

See CLI Usage & Examples for more!

Documentation

• API reference

• Guides:

  • Getting Started — Set up your agent and run your first loop.
  • The STAN Loop — How Build & Snapshot → Share & Baseline → Discuss & Patch work together.
  • CLI Usage & Examples — Common flags and invocation patterns, including -p, -P, -S, -A, and -c.
  • Migration — Namespaced Configuration — Upgrade legacy configs using stan init (backs up .bak; supports --dry-run).
  • Stan Configuration — All config keys, includes/excludes semantics, and phase‑scoped CLI defaults.
  • Patch Workflow & Diagnostics — Unified diff policy, diagnostics envelopes, and assistant expectations.
  • Archives & Snapshots — What goes into archive.tar/archive.diff.tar, combine mode, and snapshot history. Additional references:

• Reference: The Bootloader — How the assistant loads .stan/system/stan.system.md from attached archives.

• The following documents are maintained by STAN and live under <stanPath>/system/ in your repo:

  • stan.project.md contains your evolving project requirements.
  • stan.todo.md contains your evolving development plan.

• Case studies:

  • rrstack — how STAN enabled rapid development in a couple of days.

• Comparison: Why STAN Over Alternatives?

• FAQ — answers to common questions and pitfalls.

• Contributing: Dev Quickstart

Troubleshooting

• “system prompt missing”: ensure /system/stan.system.md is included in the attached archive; otherwise attach it directly as stan.system.md.
• Patch failures: use --check to validate first; if a patch fails, STAN writes a concise diagnostics envelope (attempt summaries + jsdiff reasons) and copies it to your clipboard (stdout fallback) so you can get a corrected patch.
• Large files: STAN may flag very long source files (~300+ LOC) and ask for a split plan before proceeding.

Contributing

• See the Contributing — Dev Quickstart for local setup and workflow tips.

• Keep the loop simple. Each stage ends with one command.

• Favor small, testable modules; treat >300 LOC as design feedback.

• Improve the project prompt (/system/stan.project.md) when repo‑specific policies evolve.

Built With Stan

aws-api-gateway-tools - Tools and get-dotenv plugin for AWS API Gateway (REST APIs, stage cache, API keys).

aws-secrets-manager-tools - Tools and get-dotenv plugin for AWS Secrets Manager env-map secrets.

aws-xray-tools - Guarded AWS X-Ray capture utilities for AWS SDK v3 clients.

cached-axios - Tag‑aware caching for Axios: stable cache IDs, simple tag invalidation, and a drop‑in Orval mutator on top of axios‑cache‑interceptor.

electron-react-template - A modern Electron + React starter built on Electron Forge and Vite, with a batteries-included TypeScript/tooling setup for shipping production desktop apps.

entity-client-dynamodb - Convenience wrapper for DynamoDB SDK with enhanced batch processing & EntityManager support.

entity-manager Rational indexing & cross-shard querying at scale in your NoSQL database so you can focus on your application logic.

entity-manager-demo - A working demonstration of Entity Manager in action.

entity-tools - Types & low-level functions for entity operations.

get-dotenv - Manage environment variables from dotenv files across multiple environments. Supports async/CLI operations, dynamic variables, custom CLI creation & more!

hook-form-semantic - React Hook Form components with Semantic UI React integration - date pickers, WYSIWYG editor, phone input, JSON editor, and more.

identity-engine - Deterministic identity-resolution engine in TypeScript: Zod-validated handlers, mocked deps, and a CLI that mirrors the future HTTP API.

mock-db - Mock DynamoDB-style query & scan behavior with local JSON data.

npm-package-template-ts - A feature-rich NPM package template for TypeScript projects.

react-component-npm-package-template-ts - A modern, batteries‑included React 18 component library template for TypeScript with ESM‑only bundling, Vite playground, Vitest, ESLint/Prettier, TypeDoc, release‑it, STAN, and optional cloud backup.

rrstack - Manage a stack of RRULEs.

stan-cli & stan-core - The command-line interface for STAN, a tool for managing snapshots, patches, and archives in software development.

smoz - SMOZ: a TypeScript toolkit for AWS Lambda combining Serverless, Middy, OpenAPI 3.1 and Zod for schema‑first apps with robust HTTP middleware and typed validation.

string-utilities - Handy tagged template functions & other string utilities.

License

BSD‑3‑Clause

Built for you with ❤️ on Bali! Find more great tools & templates on my GitHub Profile.