The STAN Loop

STAN Loop

STAN establishes a grounded, "AI-first" development cycle.

Instead of "magic," the AI works from the Ground Truth generated by your tools. You commit every step—broken or fixed—so you can rewind instantly.

1. Run (Validate & Commit)

This is the Reality Check. The AI cannot know if code works just by reading it. It needs evidence.

Execute: Run stan run.
- This executes all configured validation scripts (test, lint, build, knip, docs, smoke, etc.).
- It generates deterministic text outputs (.stan/output/*.txt) representing the comprehensive state of your project.
Commit: Run git commit -am "...".
- The Save Point: Commit the state immediately, whether the scripts passed or failed.
- This allows you to "rewind" the loop instantly if the next patch makes things worse.

Decision Point:

Green & Complete? → Release.
Red or New Requirements? → Snap.

2. Snap (Sync)

This is the Context Bridge. You prepare the artifacts the AI needs to understand the current state.

Baseline: Run stan snap.
- This updates the internal snapshot so archive.diff.tar will contain only changes made after this point.
Upload: Attach artifacts to the chat.
- New Thread: archive.tar (The full repo).
- Same Thread: archive.diff.tar (The delta—keeps context usage low).
- Always: Script outputs (.stan/output/*.txt)—the Ground Truth.

3. Patch (The Intelligence)

This is the Center of Gravity. Here, the assistant acts as architect and engineer.

Discuss: You review the "Ground Truth" (errors, lint warnings) together.
Plan: The assistant updates requirements (stan.requirements.md) and the dev plan (stan.todo.md).
Implement: The assistant generates code patches (Unified Diffs).
Draft: The assistant drafts the Commit Message for the work it just did.
Apply: Copy each code patch & run stan patch to apply the changes locally.

Transition: Go immediately to Run to generate new truth and save the game.

Managing Context (Handoffs)

Long context windows eventually degrade. To switch threads without losing momentum:

Ask for Handoff: In the old chat, say handoff.
Copy: STAN generates a single, self-identifying code block containing the project signature, current state, and immediate tasks.
Paste: Start a new chat, paste the handoff, and attach the full archive.tar.

STAN verifies the signature and resumes work instantly.

Why this works

Ground Truth > Memory: The assistant doesn't guess what the code does; it reads the test.txt output you just generated.
Safety Net: Committing at the Run step means you never lose a working state, and you can always revert a hallucinated patch.
Focus: The Patch phase is purely for intelligence; the Run phase is purely for verification.

Pro Tips

Scripts are everything: Add knip, tsc, docs, or smoke tests to your stan.config.yml. If a script produces text output, STAN can use it to verify integrity.
Context economy: Use archive.diff.tar for most turns. It’s tiny and keeps the assistant focused on recent changes.
Patch safely: Use stan patch --check if you're unsure about a complex refactor.