Tutorials

Tutorials

1. First project setup

git clone https://github.com/vacterro/saipen
cd my-project
saipen set

Creates .saipen/ with STATE.md (INIT), BOARD.md (empty), LOG.md (skeleton). Agent reads BOOT.md -> RFC.md -> STYLE.md -> executes INIT.

2. Running with goal mode

> saipen goal 'add CSV export'
Agent: PLAN -> creates T-1 (CSV export)
       SCOUT -> claims T-1
       BUILD -> implements
       VERIFY-> tests pass
       REVIEW-> self-review clean
       SHIP  -> v0.2.0 tagged
       DONE  -> HUNT -> clean -> ADD -> ... (autonomous)

Goal mode: auto-pilot until mature or cap (3 waves / 20 tickets).

3. Manual workflow (one ticket at a time)

> saipen plan 'add dark mode'
Agent: creates T-2 (theme toggle), T-3 (dark CSS)
> (agent auto-claims T-2 and builds it)
> saipen stop
Agent: checkpoints, writes digest, halts
> (next day) saipen continue
Agent: reads STATE -> T-2 in DOING -> resumes BUILD

4. Handling a blocker

T-4 has needs: T-2. T-2 not done -> agent leaves T-4 in TODO, works T-2 first. All tickets blocked -> BLOCKED.

5. SubSaipen parallel research

> saipen sub spawn saihunt
Agent: dispatches saihunt (read-only)
       saihunt scans 6 HUNT categories
       writes findings to OUTBOX
       main agent collects OUTBOX
       creates tickets for real findings

Collect discipline: main agent runs git status against whole tree before folding findings. A confused sub that wrote outside its folder gets caught (boundary check, v7.98.0+).

6. MARKHUNT dry audit

> saipen markhunt
Agent: exhaustive audit (no cap)
       finds everything: bugs, dead code, symmetry gaps
       records to BOARD as [MARKHUNT] tickets
       NEVER fixes anything
       Human triages: move to TODO or dismiss

7. Translation workflow

> saipen translate
Agent: quarantined env in .saipen/saitranslate/
       builds locale packs for all 32 languages
       never touches main tree
       OUTBOX with translation bundle

8. Validating conformance

> saipen validate
Agent: runs tools/validate.py
       checks STATE/BOARD/LOG/RFC agreement
       fixes structural shape only (never content)
       reports PASS or lists FAILs

9. Validator linting (v7.99.0+)

The validator itself (1418 lines) had never been linted before v7.99.0. First run found 9 cp1251-mangled section signs inside its own FAIL messages — valid UTF-8, invisible to its own U+FFFD check. CI now runs ruff.

10. Push-claim verification (v7.99.0+)

A next_action claiming "shipped, committed, pushed" while commits sit local-only now FAILs. The repository itself holds the answer. Caught v7.98.0 shipping with three uncommitted CI changes.

11. Fixture-based validation (v7.100.0+)

5 key failure modes have standing fixtures with pinned failure reasons. tools/validate.py has 93 failure paths — a fixture proves each one still fires.

The portable floor is also fixtured: tools/audit_floor.py breaks a scratch project 20 different ways and asserts both validate.sh and validate.ps1 report each specific failure. Both halves proven red. First run exposed a wording divergence — aligned. On Windows the floor adds Git's usr/bin to the child PATH only — a directly launched Git Bash otherwise inherits a PATH without grep/sed/sort (v7.127.0).

12. SHIP preflight repair (v7.128.0+)

SHIP requires 100% green, but a fixable failure found before commit used to have no legal way back to BUILD.

> saipen ship
Agent: preflight -> validator FAIL (injector bug, fix known)
       SHIP -> BUILD (narrow edge, current ticket only)
       BUILD -> VERIFY -> REVIEW -> SHIP (repeat all gates)
       commit, push branch, push exact refs/tags/vVERSION

Publish failures and already-pushed work never return to BUILD. Release order is explicit: prepare VERSION/README/CHANGELOG → rerun validators against that metadata → commit → push.

13. Shortcut shorthand (v7.148.0+)

Each key has one exact assignment; repetition is not an effort level:

cc   -> saipen goal       (pivot / re-authorize Goal Mode)
sss  -> saipen status     (reports without touching code)
ss   -> saipen stop       (checkpoint, then halt)
ccc  -> continue + shipping chain (the one that pushes)
ee   -> prepare the complete translation package; never integrate or push
eee  -> collect a ready translation package + gates + push; otherwise run ee
qq   -> prepare the complete wiki package; never integrate or push
qqq  -> collect a ready wiki package + gates + push; otherwise run qq

Length has no global cost or routing meaning; only the declared row counts, so ppp is not inferred. Cyrillic twins work too — сс, ссс, аа, ее, еее, рр normalize through the confusable set before matching. The full 13-key table lives in RFC § 1.10.

WAIT category cheat sheet

next_action	Means	What agent does
WAIT: manual-verify -- test the export feature	Human must test	Reports to human, waits
WAIT: blocked -- T-4 needs T-2 which is not done	Dependency stuck	Skips, works other tickets
WAIT: user brake -- check if this design is right	Human paused	Stops, writes digest
WAIT: safety valve -- 3 waves completed, re-invoke saipen goal	Caps hit	Stops, requires re-auth
WAIT: first-publish -- confirm repo name and visibility	First push	Asks human, one-way door

ДED Voice

"Tutorial? Одна команда — и работает. Не надо ничего настраивать. Не надо ничего объяснять. Просто saipen set — и всё. Потом saipen goal — и агент сам делает. Хочешь остановиться? saipen stop. Хочешь продолжить? saipen continue. Четыре команды — и ты управляешь проектом. Остальное агент делает сам."