Use Cases

Use Cases

Real people. Real pain. SAIPEN fixes.

---

Use Case 1: Solo dev after midnight

Context: Evening side project. 1-2h sessions, days apart. Claude at home, Gemini at work.

Problem: Every session: "what was I doing?" 5-10 min scrollback. 40+ messages. Context dead.

Solution:

Session 1 (Mon 9PM): saipen goal fix login bug
  → PLAN: T-1 validate input, T-2 error msg, T-3 edge cases
  → Works T-1, reaches VERIFY. Checkpoints. Closes laptop.

Session 2 (Wed 7PM): saipen continue
  → Reads STATE (VERIFY, T-1), BOARD, LOG. pytest → green → REVIEW→SHIP→DONE
  → Claims T-2, BUILD, VERIFY, SHIP. Claims T-3...

Session 3 (Fri 10PM): saipen continue
  → T-3 REVIEW. Ships. Tags v1.1.0. Goal done.

Result: 0 min context recovery. 3 sessions, 3 agents, ~4h. No "what was I doing?"

Without SAIPEN: ~7 min recovery/session = ~20 min lost to amnesia.

Code at 2 AM. Morning: "What did I do?" STATE.md knows. You don't remember. Agent does.

---

Use Case 2: Team with mixed agents

Context: 3-person team. Alice (Claude), Bob (Gemini), Charlie (Aider).

Problem: Different agents, different memory. Slack dump + re-explain. Conflicts.

Solution:

Alice: saipen goal refactor auth module
  → PLAN: T-8 extract middleware, T-9 rate limiting, T-10 unit tests
  → Works T-8 SCOUT→BUILD→VERIFY

Bob (next morning): saipen continue
  → STATE (VERIFY, T-8), BOARD, LOG
  → Reviews diff (120 lines, clean, tests pass) → SHIPs T-8
  → Claims T-9: BUILD rate limiting

Charlie (afternoon): saipen status
  → T-9 BUILD (Bob, claim fresh), T-10 TODO
  → Picks T-10: SCOUTs (KNOWLEDGE/ has test scope)
  → BUILDs tests parallel with Bob's T-9

Result: 3 agents, 1 .saipen/, zero conflicts. 3 tickets shipped same day.

Alice builds. Bob reviews. Charlie tests. No "who did what". SAIPEN tracks. Fire project manager.

---

Use Case 3: CI/CD integration

Context: CI must validate project state on every push.

Problem: CI runs isolated. Corrupted .saipen/ ships silently. Breaks next agent.

Solution:

# .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
      - run: python tools/run_scenarios.py

Checks every commit: STATE schema, BOARD sections, LOG event graph, README badge, 32 locale badges, injector completeness, manifest, 9 scenarios.

Real example: v7.72.0 shipped false-positive check. CI caught. Fixed v7.72.1 within an hour.

Result: Structural corruption caught before ship. Avg CI 8 seconds.

Rogue commit corrupts STATE. Without CI? Ships. Next agent confused. Prod broken. Furious. CI catches. Calm.

---

Use Case 4: LLM eval sandbox

Context: Researcher comparing Claude, Gemini, GPT-4o, DeepSeek, Qwen on identical SE tasks.

Problem: Each LLM has different context management. Need reproducible start, objective pass/fail.

Solution:

SAIPEN provides:

1. Identical start: same .saipen/ for every agent
2. Structured phases: scout.md, build.md, verify.md = reproducible pipeline
3. 34 test fixtures with declared PASS/FAIL
4. Same phase rules — no ambiguity

Eval protocol:

FOR each LLM:
  1. Clone repo (same SHA)
  2. Standardized STATE (phase: PLAN)
  3. Run: "saipen plan — implement CSV export"
  4. Measure: time to PLAN, CLAIM? BUILD? SHIP? valid STATE?
  5. Reset .saipen/ for next LLM

tools/run_scenarios.py automates pass/fail:

9 executable fixtures, 26 behavioral skipped
All match declared outcome.

Result: Apples-to-apples across 5 LLMs, 34 dimensions. Fully automated.

"My LLM better". Prove it. SAIPEN makes eval same start, same rules, same bar. Trust claims with data or not at all.

---

Use Case 5: Long-running project maintenance

Context: CLI library. One maintainer. 3-4 releases/year. 6-12 months between sessions.

Problem: 8 months later — forgot architecture, phase, tickets, conventions.

Solution:

# 8 months later:
cd project
saipen continue

Agent reads:

STATE: phase: DONE, next: "Wait for user"
BOARD: T-14 (TODO, bug: export crashes), T-8 (TODO, feature: --format flag)
LOG: [E-21] SHIP v2.3.0, [E-22] MARKHUNT — T-14 P1 backlog

Immediate understanding: Project steady. 2 known issues. Last release v2.3.0.

saipen scout T-14

Agent exports code, reproduces crash, fixes. 5 min.

Result: cd project to fix shipped: 7 min. Without SAIPEN: ~30 min re-learning.

8 months. You forgot own repo. SAIPEN didn't. Ticket still there. Architecture still documented.

---

Use Case 6: Parallel sub-agent workflows

Context: Main agent mid-BUILD critical feature. User wants bug sweep + translation audit + wiki audit. No interruption.

Solution:

saihunt        # bug sweep
saitranslate   # locale validation
saiwiki        # wiki audit

Parallel:

Process	Task	Mode	Output
Main	BUILD T-50 payment form	read-write	shipping feature
saihunt	6-category HUNT	read-only	OUTBOX findings
saitranslate	Validate 32 locales	read-only	OUTBOX stale list
saiwiki	Wiki vs source check	read-only	OUTBOX drift

Timeline:

T+0:    Main BUILD. User delegates 3 subs.
T+5min: saitranslate done: 32/32 OK, 29 stale
T+6min: saiwiki done: wiki up to date
T+8min: saihunt done: clean
T+15min: Main checkpoints. "collect" → 3 OUTBOXes empty. Continue.

Result: 3 parallel tasks, 8 min. Zero interruption. User time: 1 word ("collect").

Feature building. Bugs hunted. Locales checking. Wiki syncing. ALL PARALLEL. Sip tea. Let agents work.

---

Use Case 7: New developer onboarding

Context: New team member joins SAIPEN-managed project.

Problem: Traditional onboarding: wiki (30 min), git log (10 min), ask seniors (15 min), read issues (15 min) = ~70 min.

Solution:

# New dev:
saipen status

phase: DONE, board: 3 TODO, 0 DOING, 5 DONE
last conformance: PASS (2h ago)
waiting on you: T-14 (P1, export crash)

Then reads BOARD.md + LOG.md tail. Total: 5 min to full context.

First contribution:

saipen scout T-14     # Agent reproduces crash, finds fix
# Fix, commit, PR. No senior dev needed.

Result: 5 min vs 70 min traditional.

New guy. No idea. saipen status — "ah T-14 export crash". saipen scout — "found fix". Commits. PR. Day 1 contribution.

---

Use Case 8: Multi-repo coordination

Context: 5 microservice repos, each SAIPEN-managed: api-gateway, auth, payment, notification, frontend.

Problem: Check 5 boards across 5 tools. Which blocked? Which shipping?

Solution:

for repo in api-gateway auth payment notification frontend; do
  echo "=== $repo ==="
  cat $repo/.saipen/STATE.md
done

Output:

=== api-gateway ===
phase: DONE
=== auth ===
phase: BUILD, task: T-8 rate limiting
blocker: waiting api-gateway v2 contract
=== payment ===
phase: DONE
=== notification ===
phase: BLOCKED, blocker: payment webhook endpoint
=== frontend ===
phase: SHIP, task: T-12 integrate auth v2

Instant picture: 2 ready, 1 building (blocked on contract), 1 blocked, 1 shipping.

Result: 3-second status for 5 repos. No dashboards.

5 repos. Check one file each. 10 seconds. Knows everything. Without SAIPEN? 5 CI dashboards, 3 Slack channels, 2 Jira boards. Tired.

---

Use Case 9: Disaster recovery

Context: Agent crashes mid-BUILD. Uncommitted changes. Stale state.

Problem: STATE says BUILD but agent gone. claim_time 45 min stale. Uncommitted code — good or experimental?

Solution (RFC 1.5):

1. New agent:

saipen continue

2. Auto-detection:

RECOVERY: T-18 claim stale (45 min, limit: 15 min)
  → Resetting claim, preserving BOARD line

3. If STATE corrupt:

RECOVERY: STATE.md frontmatter parse error
  → Copy to recovery/STATE-corrupt-<ts>.md
  → Restore from recovery/STATE-valid-<ts>.md

4. LOG recovery event:

[E-92] RECOVERY: T-18 stale, STATE repaired from snapshot, reclaimed

5. Check git:

git diff --stat
src/search.jsx | 47 +++++++++

Crashed agent's work preserved in working tree.

6. Resume. Agent sees partial impl, reads LOG tail, finishes.

Result: Crash→resume <1 min. Zero lost work.

Agent committed suicide mid-task. Cry. New agent: "saipen continue". Reads stale state. Recovers. 30 seconds. Work preserved. SAIPEN: "told you".

---

Use Case 10: Open source contributor workflow

Context: External contributor wants to fix bug in SAIPEN-managed OSS project.

Problem: No chat history. No architecture knowledge. No maintainer handholding.

Solution:

1. Fork + clone:

git clone https://github.com/contributor/saipen.git

2. Read state instantly:

saipen status

phase: DONE, board: T-14 (P1, bug: export crash)

3. Investigate:

saipen scout T-14

Agent reads src/export.py, finds crash path, understands fix.

4. Fix + verify:

# Edit src/export.py: add guard for empty data
pytest tests/test_export.py — all green

5. PR:

git commit -m "fix: export crash on empty data (T-14)"

PR message:

Fixes T-14: export([]) returns headers-only CSV
verify: pytest tests/test_export.py — 15 tests pass

6. Maintainer reviews:

# Reads 3-line diff
python tools/validate.py — PASS
python tools/run_scenarios.py — 9/9 PASS
# Merges

Result: External contributor self-onboards + ships fix in ~10 min. Maintainer reviews in ~2 min. Zero back-and-forth.