Tutorials

Tutorials

Watch. Follow. No skipping.

---

Tutorial 1: First SAIPEN session

Goal: Init project, plan, execute ticket, ship.

Prerequisites: Git, AI agent that reads markdown.

Steps:

1. Clone + init

git clone https://github.com/vacterro/saipen.git
cd saipen

2. Set up

saipen set

Output:

.saipen/ created:
  STATE.md   phase: DONE
  BOARD.md   empty
  LOG.md     ready
  kitchen/   scratch

Trouble:

• saipen: command not found → Install: python bootstrap/inject.ps1 (Win) or sh bootstrap/inject.sh (macOS/Linux)
• .saipen/ already exists → saipen continue
• Not a git repo → git init

3. Check state:

saipen status

Output:

phase: DONE, task: none
staleness: fresh (3 min)

4. Plan:

saipen plan

Agent reads codebase, generates tickets on BOARD.md.

Output:

PLAN: 3 tickets proposed: T-1, T-2, T-3

5. Accept ticket: Say "start T-1". Agent auto-transitions.

6. Phase flow: SCOUT → BUILD → VERIFY → REVIEW → SHIP → DONE (automatic)

7. End session: Next agent resumes with saipen continue.

7 steps. First time. After that? One command: saipen continue. Learn once. Remember always.

---

Tutorial 2: Bug hunt

Goal: Find + fix bugs via autonomous HUNT.

Steps:

1. Initiate:

saipen hunt

2. 6-category scan:

Category	Check
Failing tests	python tools/run_scenarios.py
Commits unverified	cross-ref LOG vs git log --oneline
Stale TODOs	`rg "TODO
Silent failures	except: pass, `
Symmetry gaps	install ↔ uninstall, export ↔ import
Dead code	orphans, unreachable branches

3. Review:

=== HUNT results ===
Tests:        9/9 PASS
Commits:      all verified
TODOs:        clean
Silent fails: none
Symmetry:     all paired ✓
Dead code:    no orphans
Result:       clean

If findings:

FINDING: silent failure in src/worker.py:42 — except: pass swallows TimeoutError
P0 — fix same session

4. Fix P0/P1: Agent creates ticket, SCOUT→BUILD→VERIFY→REVIEW→SHIP.

5. Re-run:

saipen hunt
hunt → clean @<hash>

Trouble:

• First run slow, subsequent instant (hash-match)
• False positive? LOG exception, move on
• Found nothing? Quality holding

Manual bug hunt = click around, miss half. HUNT = 6 categories, no mercy. Bugs found before they bite.

---

Tutorial 3: Goal mode sprint

Goal: Multi-ticket sprint with auto-scoping + cap enforcement.

Steps:

1. Start:

saipen goal add search functionality

2. PLAN generates tickets:

T-1: search input UI
T-2: search API integration
T-3: results display
T-4: empty state
T-5: debounce 300ms
T-6: keyboard nav (Escape clears, Enter submits)

3. Execute wave 1: T-1→T-6, each through SCOUT→BUILD→VERIFY→REVIEW→SHIP→DONE.

4. Track:

saipen status

phase: DONE | goal_waves: 1 | goal_tickets: 6/20

Wave 1 done. More improvements? Yes → wave 2.

5. Wave 2:

T-7: pagination (20+ results)
T-8: search history (last 5)
T-9: highlight terms

6. Execute wave 2. Same pipeline.

7. Final:

goal_waves: 2 | goal_tickets: 9/20

Product meets "search" bar. Mature exit.

8. Report:

Goal complete: search functionality shipped
9 tickets across 2 waves

Trouble:

• Hit 20-ticket cap? Report, user re-invokes
• Hit 3-wave cap? Same.
• Product mature before tickets done? Success. Stop, report.
• List too long? Agent details only current wave.

"Add search". 9 tickets. 2 waves. Done. Remember when "search" was Ctrl+F? Better now.

---

Tutorial 4: Cross-agent handoff

Goal: Switch agents mid-project, zero context loss.

Steps:

1. Agent A works. Reaches VERIFY on T-42.

STATE.md:

phase: VERIFY
task: T-42 implement CSV export
next_action: "VERIFY T-42: pytest tests/test_export.py"
agent: claude-code
updated: 2026-07-27T14:30:00Z

2. Checkpoint (automatic):

• LOG: [E-42] VERIFY — pytest green, CSV valid
• BOARD: T-42 stays DOING
• STATE: phase VERIFY

3. Close Agent A. Everything in .saipen/.

4. Open Agent B. Same dir.

5. Resume:

saipen continue

Agent B reads: BOOT → STATE (VERIFY) → BOARD (T-42) → LOG tail.

Executes:

pytest tests/test_export.py — 15 PASS
LOG → REVIEW → REVIEW approved → SHIP
Bump, commit "v1.2.0: CSV export (T-42)", tag, push

6. Result: Shipped in 30 seconds. No briefing.

Trouble:

• .saipen/ not found? git rev-parse --git-common-dir — real .saipen/ in main worktree
• claim_time stale? RFC 1.5 recovery
• STATE says BLOCKED? Read WAIT:. Resolved? Clear, continue.
• No STATE? saipen set

Claude builds. Gemini ships. No "wait who are you". SAIPEN brain shared. Switch agents like socks.

---

Tutorial 5: SubSaipen delegation

Goal: Delegate parallel task without interrupting main work.

Steps:

1. Main agent mid-BUILD:

phase: BUILD, task: T-50 payment form

2. Delegate bug sweep:

saihunt

Auto-spawns at .saipen/extensions/subs/saihunt/. mode: read-only. Runs 6-category sweep. Writes to kitchen/OUTBOX.md.

3. Delegate translation check:

saitranslate

Another subSaipen spawns. Runs locale validation. Writes OUTBOX.

4. Main agent continues BUILD. SubSaipen are independent read-only processes.

5. Collect:

collect

Output:

saihunt: 1 finding — 2 stale temp files deleted
saitranslate: 32/32 locales OK, 29 stale (ticketed T-186)

6. Resume main work. Zero interruption.

Trouble:

• saihunt not recognized? Must start with sai* prefix
• SubSaipen writing main tree? mode: read-only prevents. Violation logged + blocked.
• OUTBOX empty? Check subSaipen LOG.md for progress

Main builds feature. Sub hunts bugs. Sub translates. All parallel. You supervise. No fighting.

---

Tutorial 6: Validation and CI

Goal: Catch structural corruption before every commit + in CI.

Steps:

1. Install pre-commit hook:

python tools/install_hook.py

Output: Installed: .git\hooks\pre-commit

Runs tools/validate.py before every commit.

Trouble:

• no .git here — Run from project root
• no .saipen here — saipen set first
• Linked worktree — Run from main checkout, not worktree

2. Test hook:

git commit --allow-empty -m "test hook"

Clean:

PASS: STATE.md schema valid
Validation complete.

Corrupt:

FAIL: BOARD.md missing ## TODO
saipen: validation failed — fix or --no-verify

3. Bypass false positive:

git commit --no-verify

4. Set up CI:

.github/workflows/validate.yml:

name: validate
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: python tools/validate.py

5. Test CI: Push. Checks STATE, BOARD, LOG, README badge, 32 locale badges, all 9 scenarios.

6. Remove hook:

python tools/uninstall_hook.py

Corrupt STATE ships. Next agent confused. Everyone confused. VALIDATE catches before commit. Stay calm.

---

Tutorial 7: Translation refresh

Goal: Refresh translations after root docs change.

Steps:

1. Check:

python tools/validate.py | grep translation
FAIL: 29 locale(s) show old version

2. Run:

saipen translate

3. Agent detects drift:

• Previous: v7.55.0
• Current: v7.80.0
• Root docs changed (version bump + content)

4. Core updated: RU, ET, DED badges bumped.

5. Non-Core ticketed:

T-186: 29 locales need v7.64→v7.80 update
RUN AS DEDICATED subSaipen INSTANCES per translate.md §2

6. Verify:

python tools/validate.py | grep translation
PASS: all 32 locale README badges match VERSION (7.80.0)

"Add French translation". Agent: "oui oui bonjour". 29 other locales? "Not my job". SAIPEN tickets them. Sub-agents handle. You don't do 29 languages either.

---

Tutorial 8: Recovery from agent crash

Goal: Recover cleanly after crash mid-task.

Symptoms:

• STATE.md updated >15 min ago
• BOARD.md stale claim_time
• Possibly corrupt STATE frontmatter

Steps:

1. Open with any agent:

saipen continue

2. Agent auto-detects staleness:

RECOVERY: T-18 claim stale (35 min), resetting
RECOVERY: previous agent dead-agent, reclaiming T-18

3. If STATE.md corrupt:

STATE.md: frontmatter parse error
Copying to .saipen/recovery/STATE-corrupt-<ts>.md
Restoring from last valid checkpoint

4. Check git:

git diff --stat
# partial work preserved

5. Resume. Agent picks up using preserved git state + LOG history.

Trouble:

• No recovery/ dir? First crash. Created on use.
• STATE missing entirely? Worst case: saipen set re-init, re-plan
• Lost git changes? git reflog — SAIPEN never touches git without explicit commands

Agent dies. You cry. New agent: "saipen continue". Reads STATE. Recovers. 30 seconds. Stops crying. SAIPEN remembers what dead agent forgot.