Use Cases

Use Cases

Real-world patterns. Context, problem, solution, measured results.

---

Use Case 1: Solo developer across sessions

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

Problem: Every session starts with 5-10 min memory recovery — "what was I doing?" Chat history 40+ messages.

Solution:

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

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

Session 3 (Fri 10PM): saipen continue
  → T-3 in REVIEW. Reviews, ships, tags v1.1.0. Goal complete.

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

Without SAIPEN: ~7 min recovery/session + regression risk = ~20 min wasted.

---

Use Case 2: Team with mixed agents

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

Problem: Each agent has different memory formats. Sharing mid-task means Slack dumps + re-explanation. Conflicts possible.

Solution:

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

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

Charlie (afternoon): saipen status
  → Sees T-9 BUILD (Bob owns, claim_time fresh), T-10 TODO
  → Picks T-10: SCOUTs (KNOWLEDGE/ has auth middleware tests scoped)
  → BUILDs tests in parallel with Bob's T-9

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

Without SAIPEN: ~2h coordination overhead. Slack "can someone review?" + re-explanation.

---

Use Case 3: CI/CD integration

Context: Automated CI must validate project state on every push.

Problem: CI runs in isolation — no context of PR's phase, tickets, structure. 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 a "template must not carry concrete saipen_home" check that false-positived on legacy projects. CI caught. Fixed in v7.72.1 within an hour.

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

---

Use Case 4: LLM evaluation 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, scalable eval.

Solution:

SAIPEN provides:

1. Identical start: .saipen/STATE.md same initial condition for every agent
2. Structured phases: scout.md, build.md, verify.md create reproducible pipeline
3. 34 test fixtures with declared PASS/FAIL outcomes
4. Same phase rule files — 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, did CLAIM? BUILD produce working code? SHIP? valid STATE?
  5. Reset .saipen/ for next LLM

tools/run_scenarios.py automates pass/fail:

9 executable fixture(s) checked, 26 behavioral fixture(s) skipped
All fixtures match declared outcome.

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

---

Use Case 5: Long-running project maintenance

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

Problem: After 8 months — 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. T-14 found 8 months ago, never fixed.

saipen scout T-14

Agent reads export code, reproduces crash, fixes. 5 min.

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

---

Use Case 6: Parallel sub-agent workflows

Context: Main agent mid-BUILD critical feature. User also 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	Check wiki vs source	read-only	OUTBOX drift

Timeline:

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

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

---

Use Case 7: New developer onboarding

Context: New team member joins SAIPEN-managed project.

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

Solution:

# New dev:
saipen status

Output:

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.

---

Use Case 8: Multi-repository coordination

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

Problem: Need to check 5 boards across 5 tools. Which blocked? Which shipping? Which waiting?

Solution:

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

Output:

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

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

Deps tracked via needs::

- [ ] T-8 auth rate limiting | needs: api-gateway-v2-contract

Result: 3-second status read for 5 repos. Without SAIPEN: check 5 CI dashboards, Jira boards, Slack channels.

---

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.

---

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.