DEPRECATION NOTICE

This repository is deprecated in favor of @karmaniverous/stan-cli. If you are a stan user, please migrate to the new package.

Migration is simple:

# Global installation recommended.
npm uninstall -g @karmaniverous/stan-cli
npm install -g @karmaniverous/stan-cli

# In repos using stan:
stan init

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.

---

Quick start

1. Install

npm i -g @karmaniverous/stan
# or
pnpm add -g @karmaniverous/stan
# or
yarn global add @karmaniverous/stan

2. Initialize in your repo

stan init

• Creates stan.config.yml and scaffolds STAN docs under (default .stan).
• Adds sensible .gitignore entries for subfolders.

3. Run the loop

• Build & Snapshot

  Make any changes you like to your code. Then snapshot your code base and outputs from test, build & diagnostic scripts with:

  stan run
  

• Share & Baseline

  Commit your changes.

  Attach .stan/output/archive.tar and your script outputs to your chat along with your requirements or comments. Or nothing: STAN will just advance your current dev plan. Use the smaller archive.diff.tar in subsequent turns to make the most your context window.

  Then baseline your next differential archive with:

  stan snap
  

• Discuss & Patch

  Iterate in chat until you have a set of patches that advance your dev plan in the direction you want to go. These will include updates to your requirements and your dev plan, as well as a detailed commit message!

  If you exhaust your context window, say handoff, copy the resulting document, and paste it into a new chat thread along with your latest artifacts.

  Apply each patch with:

  stan patch
  

• Repeat

  When all your tests are passing and all your requirements are met, you're done!

---

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 -c -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 — Install the CLI, initialize a repo, attach archives in chat, and use the bootloader with TypingMind (GPT‑5, High reasoning, 128k tokens).
  • 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.
  • 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:

• 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?

• Tutorial: Quickstart (End‑to‑End)

• 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.

---

License

BSD‑3‑Clause