Getting Started

Getting Started

Install (once per machine)

git clone https://github.com/vacterro/saipen
cd saipen
powershell -ExecutionPolicy Bypass -File .\bootstrap\inject.ps1     # Windows
bash bootstrap/inject.sh                                            # macOS / Linux

Teaches Claude Code, Codex, Gemini, OpenCode, Aider, Antigravity, FreeBuff. Appends marked block to agent instruction files, copies protocol to skill folders. Backs up originals to .bak.

Installs are complete (v7.126.0+): injectors now ship VERSION alongside the protocol — a fresh skill can prove which release it runs. Refreshes replace managed directories instead of overlaying, so deleted source files no longer survive forever in installed copies. The runtime manifest makes forgetting either a validation failure.

Windows users (v7.100.0+): inject.sh now converts paths via cygpath -w under git bash / MSYS / Cygwin. Previously, pwd returned /v/proj/saipen — a path only that shell can resolve. Windows agents couldn't open it, leaving CLAUDE.md full of dead paths with no error at all.

Uninstall: powershell ... uninstall.ps1 or bash uninstall.sh — strips exactly the marked block, saves .uninstalled.bak.

Full list of what every file change touches (nothing outside agent instruction files and skill folders): GitHub README.

Start a project

Open agent in your folder, type:

saipen set

No install? Paste one line to any agent:

Read <clone>/saipen/BOOT.md first, then <clone>/saipen/RFC.md + <clone>/saipen/STYLE.md

Core workflow

saipen set        -> INIT  -> creates .saipen/
saipen goal X     -> PLAN  -> tickets for objective
                     SCOUT -> claim first ticket
                     BUILD -> implement
                     VERIFY-> test
                     REVIEW-> human or manual-verify
                     SHIP  -> tag + push
                     DONE  -> HUNT -> ADD -> ...

Commands

Command	When	What
saipen / saipen continue	Any time	Resume: read STATE, execute next_action
saipen goal <text>	DONE	New objective, auto-run to caps
saipen plan	DONE/IDLE	Generate tickets from analysis
saipen clean	Any	Deep scrub: board, orphans, links, trash
saipen translate	Any	Isolated locale translation build
saipen markhunt	Any	Dry exhaustive audit (records only)
saipen prepare	Any	Package work for next agent
saipen ship	REVIEW	Version bump, changelog, tag, push
saipen validate	Any	Run conformance checker
saipen status	Any	Read-only report (read BOARD+STATE)
saipen stop	Any	Checkpoint + halt

WAIT categories (v7.93.0+)

next_action must carry one of 7 tokens:

Category	Meaning
manual-verify	Human must test this
destructive-op	Ask before deleting/overwriting
first-publish	Confirm name + public/private
user brake	Intentional pause by user
blocked	Stuck, needs human decision
safety valve	Goal caps hit, re-authorize
init	First-time setup question

Portable floor (v7.94.0+)

No Python? tests/validate.sh and tests/validate.ps1 probe all 9 STATE fields. Never more permissive than tools/validate.py. Both check read-only bans, WAIT categories, required fields.

Audited (v7.100.0): tools/audit_floor.py breaks a scratch project 20 ways, then asserts both halves of the floor still go red. First run exposed a wording divergence between .sh and .ps1 on the same defect — aligned.

Known gap: the portable floor checks that next_action: is present, never that it's executable. tools/validate.py covers executability on any host with Python.

Pre-commit hook (v7.113.0+)

The hook carries a generation stamp compared against the installer's current version. A hook installed twenty releases ago runs the logic it was born with — the stamp catches silent staleness.

When neither tools/validate.py nor the portable floor is found (moved saipen_home), the hook still exits 0 (fail-open) but now prints what it could not find and the repair command. An unvalidated commit that looks validated was the problem; silence was the enabler.

Audit tools (v7.109.0+)

Tool	What it checks
tools/audit_floor.py	Portable floor still goes red on all 27 checks × 2 halves. Windows: adds Git usr/bin to child PATH only, rejects System32 WSL stub (v7.100.0, v7.127.0)
tools/audit_tags.py	Every git tag matches VERSION (v7.109.0)
tools/audit_order.py	No top-level name read before its definition (v7.112.0)
tools/audit_checks.py	51 mutations proving validator checks still catch their named failure; LOG mutations resolve sealed segments, no-op mutations rejected — a skipped case is fatal, never a shrunken denominator (v7.119.0, v7.133.0, v7.155.0)
tools/audit_parity.py	Floor baseline never drops; observes one real release-ledger process via Git Trace2 (v7.120.0, v7.129.0)
tools/run_scenarios.py	Executes both injectors in isolated homes, installed validators, floor behavioral cases — guards run the script, not its spelling (v7.126.0, v7.131.0)

Project root (v7.132.0+)

Checkpoints bind to one dynamically resolved project root per session — never ambient cwd. Git projects use the worktree/common-dir pair; linked worktrees use the main worktree's gitignored memory; non-Git projects use the nearest ancestor carrying .saipen/. saipen continue --project-root <path> deliberately overrides cwd from elsewhere. An unowned cwd fails instead of guessing or creating a second memory tree.

ДED Voice

"Ставишь один раз — и забыл. Потом в любой папке: saipen set — и работаешь. Не надо каждый раз объяснять агенту кто ты и что ты хочешь. Просто continue — и он уже читает твой STATE. Ленивый? Да. Работает? Ещё как."