Tutorials

Tutorials

Step-by-step guides for common SAIPEN operations.

---

Tutorial 1: Your first SAIPEN session

Goal

Initialize a project and get a feel for the phase flow.

Steps

1. Clone and init

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

2. Set up SAIPEN

saipen set

This creates .saipen/ with STATE.md, BOARD.md, LOG.md.

3. Check state

saipen status

Shows current phase, any active tickets, blockers, staleness.

4. Plan work

saipen plan

Agent reads the codebase and proposes tickets on the board.

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

6. Follow the phase flow The agent automatically transitions: SCOUT -> BUILD -> VERIFY -> REVIEW -> SHIP -> DONE.

7. End session Work is checkpointed automatically. Next agent resumes via saipen continue.

---

Tutorial 2: Running a bug hunt

Goal

Find and fix bugs using the autonomous HUNT mechanism.

Steps

1. Initiate hunt

saipen hunt

Agent runs the 6-category sweep:

Category	What it checks
Failing tests	Run test suite
Commits unverified	Cross-reference LOG vs git log
Stale TODOs	grep for TODO/FIXME/HACK in code
Silent failures	bare excepts, ignored returns
Symmetry gaps	missing feature counterparts
Dead code	orphan files, unused functions

2. Review findings Agent reports findings. Obvious junk is auto-deleted (<5 files). Remaining findings become tickets.

3. Triage and fix Each finding gets a priority:

• P0/P1 -> fix immediately
• P2/P3 -> ticket for backlog

4. Verify fixes Re-run hunt to confirm clean.

---

Tutorial 3: Goal mode sprint

Goal

Run a focused multi-ticket sprint with automatic scoping.

Steps

1. Start a goal

saipen goal add search functionality

2. Plan phase Agent generates tickets:

• T-1: search input UI
• T-2: search backend query
• T-3: result display
• T-4: empty state handling

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

4. Progress tracking

saipen status

Shows: goal_waves=1, goal_tickets=4/20

5. Cap limits At 20 tickets or 3 waves, agent stops and reports. User decides: re-invoke goal or stop.

---

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.

2. Checkpoint Agent A completes phase checkpoint: LOG -> BOARD -> STATE.

3. Close Agent A Session ends. Everything needed to resume is in .saipen/.

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

5. Resume

saipen continue

BOOT.md -> STATE.md -> BOARD.md -> LOG.md tail -> execute next_action.

Agent B sees: "T-42 in VERIFY, next_action: 'verify T-42 passes criteria, then REVIEW'"

6. No briefing needed Zero context transferred via chat. The filesystem IS the memory.

---

Tutorial 5: SubSaipen delegation

Goal

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

Steps

1. Start main work Agent is mid-BUILD on a feature.

2. Delegate a sweep

saihunt

This auto-spawns a read-only subSaipen. saihunt cannot modify any files — only reads, analyzes, and writes findings to its own OUTBOX.

3. Sub-agent works independently saihunt runs full HUNT sweep against HEAD. Writes OUTBOX.md in its kitchen/.

4. Collect findings

collect

Main agent reads the OUTBOX, tickets any real findings.

5. Continue main work Main work was never interrupted. The subSaipen instance stays dormant until collected or garbage-collected.

---

Tutorial 6: Installing the pre-commit hook

Goal

Catch structural corruption before every commit.

Steps

1. Install the hook

python tools/install_hook.py

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

2. Test it

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

If .saipen/ is corrupt, commit is blocked with a clear message.

3. Bypass a false positive

git commit --no-verify

Use when you know the failure is expected (e.g., known stale translation badges).

4. Remove

python tools/uninstall_hook.py

---

Tutorial 7: Translation refresh

Goal

Update translations after root docs changed.

Steps

1. Run translate

saipen translate

2. Detection Agent detects what changed since last translate run — version badge drift, content changes, new files.

3. Core execution Core locales (RU, ET, DED) are updated by the main agent.

4. Non-Core ticketing 29 non-Core locales are ticketed for subSaipen instances. Each subSaipen handles its own language pack.

5. Verification

python tools/validate.py

The badge-drift check now PASSes for all updated locales, FAILs for stale ones.