Skip to content

Tutorials

Jump to bottom
VAC34 edited this page Jul 27, 2026 · 10 revisions

Tutorials

Step-by-step guides for common SAIPEN operations. Each includes expected commands, outputs, and troubleshooting.

Tutorial 1: Your first SAIPEN session

Goal

Initialize a SAIPEN project, plan work, execute a ticket, and ship it.

Prerequisites

  • Git
  • An AI agent that reads markdown files (Claude Code, Gemini Code Assist, OpenCode, etc.)

Steps

1. Clone and init

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

2. Set up SAIPEN

saipen set

Expected output:

.saipen/ created:
  STATE.md   phase: DONE, ready for first PLAN
  BOARD.md   empty (DOING / TODO / DONE / BLOCKED)
  LOG.md     ready for events
  kitchen/   scratch workspace

Troubleshooting:

  • saipen: command not found -> Install the injector: python bootstrap/inject.ps1 (Windows) or sh bootstrap/inject.sh (macOS/Linux)
  • .saipen/ already exists -> You're continuing an existing project. Run saipen continue
  • Not a git repo -> Run git init first, or use an existing repo

3. Check state

saipen status

Expected output:

phase: DONE
task: none
waiting on you: no
claimed but unproven: none
last conformance: no record — run python tools/validate.py
staleness: fresh (3 min)

4. Plan work

saipen plan

Agent reads the codebase and generates ticket proposals on BOARD.md.

Expected:

PLAN phase: codebase analyzed
3 tickets proposed:
  T-1 [P2] ...
  T-2 [P2] ...
  T-3 [P1] ...
Review BOARD.md to accept or modify.

5. Accept a ticket Say "start T-1" or let the agent auto-pick the first TODO.

6. Follow the phase flow The agent transitions automatically:

  • SCOUT: investigate codebase, read relevant files, note conventions
  • BUILD: implement the change, following existing patterns exactly
  • VERIFY: run tests, check acceptance criteria
  • REVIEW: diff review, no scope creep, docs updated
  • SHIP: bump version, commit, tag, push

7. End session Work checkpoints automatically. Next agent resumes with:

saipen continue

Tutorial 2: Running a bug hunt

Goal

Find and fix bugs using the autonomous HUNT mechanism.

Steps

1. Initiate hunt

saipen hunt

2. Agent runs 6-category scan:

Category What it checks
Failing tests Run python tools/run_scenarios.py — any failures?
Commits unverified Cross-reference LOG events vs git log —oneline
Stale TODOs `rg "TODO
Silent failures except: pass, `
Symmetry gaps install.sh has uninstall.sh counterpart? Export has import?
Dead code Orphan files, functions never called, unreachable branches

3. Review findings

=== HUNT results ===
Tests:        9/9 PASS
Commits:      all verified
TODOs:        clean (no stale markers)
Silent fails: none
Symmetry:     all paired ✓
Dead code:    no orphans
Auto-cleanup: 0 junk files
Result:       clean — no tickets needed

If findings exist:

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

4. Fix P0/P1 findings Agent creates ticket, SCOUTs, BUILDs, VERIFYs, REVIEWs, SHIPs.

5. Re-run hunt to confirm

saipen hunt
hunt -> clean @<hash>  (next run will skip via hash match)

Troubleshooting

  • Hunt takes too long? -> First run is slow, subsequent runs are instant (hash-match optimization)
  • False positive? -> LOG the exception, move on. The hash-match will ignore it next time
  • Found nothing? -> That's fine — a clean hunt means quality is holding

Tutorial 3: Goal mode sprint

Goal

Run a focused multi-ticket sprint with automatic scoping and cap enforcement.

Steps

1. Start a goal

saipen goal add search functionality

2. PLAN phase generates tickets

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

3. Execute wave 1 Agent claims T-1, works SCOUT -> BUILD -> VERIFY -> REVIEW -> SHIP -> DONE.

Then claims T-2, same pipeline. Then T-3, T-4, T-5, T-6.

4. Track progress

saipen status
phase: DONE | goal_waves: 1 | goal_tickets: 6/20
next: T-2 (DONE), T-3 (DONE), T-4 (DONE), T-5 (DONE), T-6 (DONE)

All wave 1 done. Agent checks: more improvements possible? Yes -> enters wave 2.

5. Wave 2 generates refined tickets

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

6. Execute wave 2 Same pipeline for T-7, T-8, T-9.

7. Final check

goal_waves: 2 | goal_tickets: 9/20

Both caps under limit. Product now meets "search functionality" bar. Agent calls mature exit.

8. Report

Goal complete: search functionality shipped
9 tickets across 2 waves
All verify criteria pass:
  - P1 (T-1, T-2, T-3, T-4) — core search works end to end
  - P2 (T-5, T-6, T-7) — polish
  - P3 (T-8, T-9) — nice-to-have

Troubleshooting

  • Hit 20-ticket cap before finishing? -> Report progress, user re-invokes goal to continue
  • Hit 3-wave cap? -> Same — report, user decides
  • Product mature before all tickets done? -> That's success. Goal mode stops, reports, exits
  • Ticket list too long? -> Agent details only current wave. Past waves stay on BOARD as DONE

Tutorial 4: Cross-agent handoff

Goal

Switch between agents mid-project with zero context loss.

Steps

1. Agent A works Agent A (Claude Code) works on T-42, reaches VERIFY phase.

.saipen/STATE.md after Agent A checkpoints:

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

2. Checkpoint (automatic at end of every ticket)

# Agent A writes:
# 1. LOG event: [E-42] VERIFY — pytest green, CSV output valid
# 2. BOARD update: T-42 stays in DOING (not yet SHIP)
# 3. STATE update: phase: VERIFY, next_action as above

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

4. Open Agent B Agent B (Gemini Code Assist) opens the same directory.

5. Resume

saipen continue

Agent B reads:

  1. BOOT.md -> "read STATE, BOARD, LOG, execute next_action"
  2. STATE.md -> phase: VERIFY, task: T-42
  3. BOARD.md -> T-42 in DOING, verify: pytest tests/test_export.py
  4. LOG.md tail -> BUILD done, VERIFY in progress

Agent B executes:

Runs: pytest tests/test_export.py
Result: all 15 tests PASS, CSV output matches expected format
Checkpoints: LOG [E-43] VERIFY -> REVIEW
Reviews diff: 47 lines, no scope creep, tests cover 3 edge cases
Checkpoints: LOG [E-44] REVIEW -> SHIP
Bumps VERSION, commits "v1.2.0: CSV export (T-42)", tags, pushes
Checkpoints: LOG [E-45] SHIP -> DONE

6. Result Agent B shipped in 30 seconds. Didn't need to ask "what were we doing?"

Troubleshooting

  • .saipen/ not found? -> Check if you're in a git worktree (git rev-parse --git-common-dir). The real .saipen/ is in the main worktree
  • claim_time stale (>15 min)? -> RFC 1.5 recovery: reset claim, reclaim ticket, continue
  • STATE.md says BLOCKED? -> Read the WAIT: message. If the blocker is resolved, clear it and continue
  • No STATE.md? -> Run saipen set to initialize

Tutorial 5: SubSaipen delegation

Goal

Delegate a parallel task to a sub-agent without interrupting main work.

Steps

1. Main agent is mid-BUILD on a feature

phase: BUILD
task: T-50 implement payment form

2. Delegate a bug sweep

saihunt

What happens in the background:

  • saihunt subSaipen auto-spawns at .saipen/extensions/subs/saihunt/
  • STATE: phase: HUNT, mode: read-only
  • Reads main project (read-only!), runs 6-category sweep against HEAD
  • Writes findings to .saipen/extensions/subs/saihunt/kitchen/OUTBOX.md

3. Meanwhile, delegate a translation check

saitranslate
  • Another subSaipen spawns, runs translation structure validation
  • Writes its own OUTBOX

4. Main agent continues uninterrupted The BUILD on T-50 proceeds normally. The subSaipen instances are independent read-only processes.

5. Collect findings

collect

Expected:

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

Main agent actions findings: deletes stale files, notes translation status.

6. Resume main work T-50 BUILD continues. Total interruption to main workflow: 0 minutes.

Troubleshooting

  • saihunt not recognized? -> Must start with sai* prefix. That's the auto-spawn trigger
  • SubSaipen trying to write main tree? -> mode: read-only prevents it. If violation detected, it's logged and blocked
  • OUTBOX empty? -> The subSaipen might still be running. Check its LOG.md for progress
  • Can't collect? -> The subSaipen might have nothing in OUTBOX. Check kitchen/OUTBOX.md directly

Tutorial 6: Setting up validation and CI

Goal

Catch structural corruption before every commit and in CI.

Steps

1. Install the pre-commit hook

python tools/install_hook.py

Expected output:

Installed: .git\hooks\pre-commit (validator home: /path/to/saipen)

This creates .git/hooks/pre-commit that runs tools/validate.py before every commit.

Troubleshooting:

  • no .git here -> Run from the project root (where .git/ lives)
  • no .saipen here -> Run saipen set first
  • linked git worktree -> Run from the main checkout, not a worktree
  • Windows permission error? -> The script handles it: try: target.chmod(0o755) except: pass

2. Test the hook

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

Expected if clean:

saipen conformance validation starting...
PASS: STATE.md schema valid
PASS: ...
Validation complete. Agent is conformant.
[main ...] test hook

Expected if corrupt:

FAIL: BOARD.md missing required section heading: ## TODO
saipen: validation failed -- fix .saipen/ or commit with --no-verify

3. Bypass a false positive

git commit --no-verify

Use when you know the failure is expected (e.g., 29 known stale translation badges ticketed as T-186).

4. Set up CI

Add to .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 the CI Push a commit. The CI run:

  • Checks STATE.md structure
  • Checks BOARD.md sections and ticket format
  • Checks LOG.md event graph consistency
  • Checks README badge matches VERSION
  • Checks all 32 locale README badges
  • Fails the build if any check fails

6. Remove the hook (if needed)

python tools/uninstall_hook.py

Tutorial 7: Translation refresh

Goal

Refresh translations after root docs change.

Steps

1. Check current state

python tools/validate.py | grep translation
FAIL: translation README badge drift: 29 locale(s) still show an old version

29 locales need updating. Ticketed as T-186.

2. Run translate

saipen translate

3. Agent detects drift

  • Previous translate run: v7.55.0
  • Current: v7.80.0
  • Root docs changed: README, SECURITY, CONTRIBUTING, SPEC (version bump + content)
  • git diff SHA..HEAD -- README.md SECURITY.md CONTRIBUTING.md SPEC.md quantifies exact changes

4. Core locales updated RU, ET, DED README badges bumped to v7.80.0.

5. Non-Core ticketed

T-186: 29 non-Core locales need v7.64→v7.80 translation update
RUN AS DEDICATED subSaipen INSTANCES per translate.md §2
verify: python tools/validate.py — 0 stale badges

6. Verify

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

Tutorial 8: Recovery from agent crash

Goal

Recover cleanly after an agent crashes mid-task.

Symptoms

  • STATE.md shows old updated timestamp (>15 min ago)
  • BOARD.md has stale claim_time
  • Possibly corrupt STATE.md frontmatter

Steps

1. Open project with any agent

saipen continue

2. Agent detects staleness automatically

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

3. If STATE.md is corrupt

STATE.md: frontmatter parse error
Copying to .saipen/recovery/STATE-corrupt-2026-07-27.md
Restoring from last valid checkpoint...

4. Check git for unsaved work

git diff --stat
# partial work preserved from crashed agent

5. Resume Agent picks up where the crashed agent left off, using preserved git state + LOG history.

Troubleshooting

  • No recovery/ directory? -> First crash since init. Recovery creates it on first use
  • STATE.md completely missing? -> Worst case: run saipen set to re-initialize, then re-plan
  • Lost git changes? -> git reflog shows everything. SAIPEN never touches git without explicit commands

SAIPEN v7.158.0 — One command. Zero dependencies. Zero amnesia. — MIT

Clone this wiki locally