Tutorials

Tutorials

1. First project setup

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

This creates .saipen/ with STATE.md (phase: 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 is not done yet. Agent leaves T-4 in TODO, works T-2 first. If 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

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

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. Четыре команды — и ты управляешь проектом. Остальное агент делает сам."