Use Cases

Use-Cases

1. Cold agent resumes project

Scenario: Return to project after 2 weeks. Agent has no chat history.

saipen continue

Agent reads STATE.md (phase: BUILD, task: T-7), BOARD.md (T-7 in DOING), LOG tail (last events). Executes next_action: PHASE BUILD T-7. Resumes coding without asking "what was I doing?"

2. Overnight autonomous evolution

Scenario: Leave agent running with goal mode.

saipen goal 'make the UI responsive'

Agent: PLAN -> 5 tickets. Builds each. Verifies. Reviews. Ships. Then HUNT -> clean -> ADD -> finds symmetry gaps -> tickets -> builds -> ships. Hits wave 3 cap. Writes WAIT: safety valve. Stops. Morning: 3 releases, 15 tickets, zero questions asked.

3. Parallel subSaipen research

Scenario: Need to audit codebase while building a feature.

saipen sub spawn saihunt saipen sub spawn saipython

saihunt scans 6 HUNT categories (failing tests, dead code, etc.). saipython finds Python-specific issues (untyped defs, bare excepts). Both write OUTBOXes. Main agent collects after finishing current BUILD. Creates tickets from real findings.

4. Safety valve prevents runaway

Scenario: Agent has been running autonomously for hours. Goal caps protect against infinite loops.

After 3 waves or 20 tickets: agent stops, writes WAIT: safety valve -- X waves completed, re-invoke saipen goal to authorize more. User reviews progress. Re-authorizes or stops. Never burns through unlimited compute.

5. Multi-vendor handoff

Scenario: Start with Claude, continue with Gemini, ship with Codex.

Claude: saipen goal 'build auth' -> builds, verifies, ships v0.5.0. Next day, Gemini: saipen continue -> reads STATE, sees v0.5.0 shipped, HUNTs for bugs, finds none, ADDs next feature. Codex: saipen ship -> bumps to v0.6.0, tags, pushes.

All three agents work from the same STATE.md. No context loss between vendors.

6. Blocked project recovery

Scenario: T-14 depends on T-12 which is stuck.

Agent at DONE: empty board? No, T-14 blocked.
BLOCKED: T-14 needs T-12, T-12 needs human decision.
WAIT: blocked -- T-12 needs UX mockup approval before build can start

Human sees WAIT: blocked, provides mockup. Next saipen continue: T-12 unblocked, builds, ships, T-14 builds on top. Project unblocked.

7. First-publish gate

Scenario: First release of a new project.

SHIP detects no origin, writes: WAIT: first-publish -- confirm repo name 'my-project' and public/private before I push

Human confirms. Agent pushes, tags, creates first release. One-way door protected.

8. Portable floor validation

Scenario: CI server without Python.

GitHub Actions runs ubuntu-latest (has Python) -> runs tools/validate.py. Minimal Docker container without Python -> runs tests/validate.sh or tests/validate.ps1.

Both probe all 9 STATE fields. Both catch read-only bans. Both check WAIT categories. Never a false PASS from the portable floor.

9. Translation pipeline

Scenario: Need locale packs for 32 languages.

saipen translate

Agent quarantines in .saipen/saitranslate/. Builds translation bundles for 32 locales. Validates each has 4/4 required files (README, SECURITY, CONTRIBUTING, SPEC). Writes OUTBOX with bundle. Main agent collects and integrates. Never touches main tree during translation.

10. Crash recovery

Scenario: Agent crashes mid-BUILD. STATE.md says phase: BUILD but work incomplete.

Next agent: RECOVER. Reads STATE. Checks BOARD: T-17 in DOING with old claim_time (stale). Checks LOG: last entry is RUN: BUILD T-17 with no VERIFY. Adopts T-17 (new claim_time). Continues BUILD. No data loss, no duplicate work.