Skip to content

Use Cases

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

Use Cases

Real-world usage patterns for SAIPEN. Each includes context, problem, solution, and measured results.

Use Case 1: Solo developer across sessions

Context: Developer works evenings on a side project. Each session is 1-2 hours, days apart. Uses Claude Code at home, Gemini Code Assist at work.

Problem: Every session starts with 5-10 minutes of memory recovery:

  • "What was I working on?"
  • "What files did I change?"
  • "What was the next step?"
  • Chat history from last session is 40+ messages — too long to re-read

Solution:

Session 1 (Monday 9 PM): saipen goal fix login bug
  -> PLAN generates T-1 (validate input), T-2 (error messages), T-3 (test edge cases)
  -> Works T-1, reaches VERIFY
  -> Checkpoints: LOG [E-5] VERIFY, BOARD T-1 in DOING
  -> Closes laptop

Session 2 (Wednesday 7 PM): saipen continue
  -> Agent reads STATE (phase: VERIFY, task: T-1), BOARD (T-1 in DOING), LOG tail
  -> Runs pytest, all green -> REVIEW -> SHIP -> DONE
  -> Claims T-2, BUILDs, VERIFYs, SHIPs, DONE
  -> Claims T-3...
  -> Checkpoints

Session 3 (Friday 10 PM): saipen continue
  -> T-3 already in REVIEW from session 2
  -> Reviews, ships, tags v1.1.0
  -> Goal complete: login bug fixed

Measured result: 0 minutes context recovery per session. 3 sessions across 3 agents, shipped in ~4 hours total working time. No "what was I doing?" ever asked.

Without SAIPEN: ~7 minutes recovery per session + risk of wrong-context mistakes = ~20 minutes wasted + potential regression bugs.

Use Case 2: Team with mixed agents

Context: 3-person team uses different AI coding agents. Alice (Claude Code), Bob (Gemini Code Assist), Charlie (Aider).

Problem: Each agent has different memory formats, context handling, and command syntax. Sharing work mid-task:

  1. Alice codes for 2 hours, reaches VERIFY on T-8
  2. She'd need to dump context to Slack for Bob or Charlie to continue
  3. Bob opens the project — his agent has no memory of what Alice did
  4. Charlie picks up a different ticket — but his agent might conflict with Bob's work

Solution:

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

Bob (next morning): saipen continue
  -> Reads STATE (phase: VERIFY, task: T-8), BOARD, LOG
  -> Reviews T-8 diff: 120 lines, clean, tests pass
  -> SHIPs T-8: commits "v2.1.0: extract auth middleware (T-8)"
  -> Claims T-9: BUILD rate limiting
  -> Checkpoints

Charlie (afternoon): saipen status
  -> Sees T-9 in BUILD, T-10 in TODO
  -> Cannot claim T-9 (Bob owns it, claim_time fresh)
  -> Picks T-10 instead: SCOUTs, finds auth middleware tests already scoped in KNOWLEDGE/
  -> BUILDs unit tests in parallel with Bob's T-9
  -> When Bob checkpoints, sees T-10 done, ships his T-9, done

Measured result: 3 agents, 1 shared .saipen/, zero conflicts, zero cross-briefing. All 3 tickets shipped same day.

Without SAIPEN: Alice finishes T-8, Slack "can someone review my T-8?" Bob reviews in different context, needs re-explanation. Charlie blocks on T-10 not knowing knowledge exists. ~2 hours coordination overhead.

Use Case 3: CI/CD integration

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

Problem: CI runs in isolation — no context of what the PR achieves, what phase the project is in, what tickets are open. A commit that corrupts .saipen/ structure ships silently and breaks the next agent that touches the project.

Solution:

.github/workflows/validate.yml:

name: validate
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate saipen state
        run: python tools/validate.py
      - name: Run scenario tests
        run: python tools/run_scenarios.py

CI checks every commit:

  • STATE.md schema valid
  • BOARD.md all 4 sections present, no duplicate tickets, no cycles
  • LOG.md event graph consistent (E-### unique + monotonic, parents resolve)
  • README badge matches VERSION
  • All 32 locale README badges match VERSION
  • Injector distributes every required file
  • Runtime manifest complete (15+ files)
  • All 9 executable scenario fixtures pass

Pre-commit hook (local): Same checks run before every commit. Catches issues before they reach CI.

Real example (from v7.72.0): A brand-new "shipped template must not carry concrete saipen_home" check false-positived on legacy consuming projects. CI caught it, the fix was shipped in v7.72.1 within an hour. Without the check, it would have blocked every commit on every consuming project until someone noticed.

Measured result: Structural corruption caught before it ships. Average CI run: 8 seconds.

Use Case 4: LLM evaluation sandbox

Context: Researcher wants to compare how different LLMs handle multi-step software engineering tasks. Must evaluate Claude, Gemini, GPT-4o, DeepSeek, and Qwen on identical tasks with identical starting conditions.

Problem:

  • Each LLM has different context management
  • Agent memory formats differ per platform
  • Need reproducible starting conditions
  • Need objective pass/fail criteria per task
  • Manual evaluation doesn't scale

Solution:

SAIPEN provides:

  1. Identical starting state: .saipen/STATE.md gives every agent the same initial condition
  2. Structured phases: phases/scout.md, build.md, verify.md create a reproducible pipeline
  3. Executable test fixtures: tests/scenarios/ has 34 fixtures with declared PASS/FAIL outcomes
  4. Phase docs: Each agent reads the same saipen/phases/ rule files — no ambiguity

Evaluation protocol:

For each LLM under test:
  1. Clone repo (same SHA every time)
  2. Set up .saipen/ with standardized STATE (phase: PLAN, next_action: "PLAN T-1")
  3. Run: "saipen plan — implement CSV export"
  4. Measure:
     a. Time to first PLAN output
     b. Did the agent CLAIM a ticket or just talk about it?
     c. Did BUILD produce working code? (verify against tests/scenarios/)
     d. Did the agent SHIP? (commit + tag)
     e. State fidelity: does STATE.md contain valid frontmatter after each transition?
     f. Did the agent follow phase protocol or skip steps?
  5. Reset .saipen/ to initial state for next LLM

tools/run_scenarios.py automates the pass/fail judgment:

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

Measured result: Apples-to-apples comparison across 5 LLMs, 34 behavioral dimensions per LLM, fully automated evaluation pipeline. Results show which models respect phase protocol vs. which skip steps, which produce valid STATE.md vs. which corrupt it.

Use Case 5: Long-running project maintenance

Context: A CLI library. One maintainer. 3-4 releases per year. 6-12 months between active development sessions.

Problem: After 8 months away:

  • Don't remember the architecture
  • Don't remember what phase the project was in
  • Don't remember what tickets were open
  • Don't remember what conventions were used
  • README and code still work, but the mental model is gone

Solution:

# 8 months later:
cd project
saipen continue

Agent reads:

STATE.md:       phase: DONE
                next_action: "Wait for user command"
BOARD.md:       T-14 (TODO, bug: export crashes on empty state)
                T-8  (TODO, enhancement: add --format flag)
LOG.md tail:    [E-21] SHIP v2.3.0
                [E-22] MARKHUNT — 2 findings, T-13 (P0, fixed), T-14 (P1, backlog)
                [E-23] HUNT — clean @abc1234

Immediate understanding:

  • Project is in steady state (phase: DONE)
  • 2 known issues: T-14 (crash bug), T-8 (feature request)
  • Last release: v2.3.0
  • T-14 was found by MARKHUNT 8 months ago, marked P1, never fixed
saipen scout T-14

Agent reads the export code, reproduces the crash, fixes it. 5 minutes.

Measured result: From cd project to fix shipped: 7 minutes. Without SAIPEN: ~30 minutes re-reading code + re-learning architecture + finding the bug.

Use Case 6: Parallel sub-agent workflows

Context: Main agent is mid-BUILD on a critical feature. User also wants:

  1. A bug sweep (check for regressions)
  2. A translation audit (are locale badges up to date?)
  3. A doc audit (are wiki docs current?)

All without interrupting the main build.

Solution:

saihunt        # spawns bug sweep subSaipen — starts immediately
saitranslate   # spawns translation audit subSaipen — starts immediately
saiwiki        # spawns wiki audit subSaipen — starts immediately

What runs in parallel:

SubSaipen Task Mode Output
Main agent BUILD T-50 payment form read-write shipping feature
saihunt 6-category HUNT sweep read-only OUTBOX with findings
saitranslate Validate 32 locales read-only OUTBOX with stale list
saiwiki Check wiki pages vs source read-only OUTBOX with drift

Lifecycle:

T+0:     Main agent in BUILD. User delegates 3 subSaipen.
T+0:     saihunt spawns, starts scanning
T+1min:  saitranslate spawns, starts validation
T+2min:  saiwiki spawns, starts doc audit
T+5min:  saitranslate finishes: "32/32 OK, 29 stale badges"
T+6min:  saiwiki finishes: "Wiki up to date"
T+8min:  saihunt finishes: "Clean — no issues found"
T+15min: Main agent checkpoints BUILD, user says "collect"
         -> Reads 3 OUTBOXes
         -> Nothing actionable (stale badges already ticketed as T-186)
         -> Continues BUILD

Measured result: 3 parallel tasks completed in 8 minutes. Zero interruption to main build. Total user time spent: 1 word ("collect").

Use Case 7: New developer onboarding

Context: New team member joins a SAIPEN-managed project.

Problem: Understanding project state requires:

  • Reading wiki/docs (30 min)
  • Reading recent git log (10 min)
  • Asking senior devs what's happening (15 min)
  • Reading open issues (15 min)
  • Total: ~70 minutes before first contribution

Solution:

# New dev opens the project
saipen status

Output:

phase: DONE
task: none
board: 3 TODO, 0 DOING, 5 DONE
last conformance: PASS (2 hours ago)
waiting on you: T-14 needs P1 fix (export crashes on empty state)
staleness: fresh

Then reads BOARD.md for ticket details and LOG.md tail for recent work. Total: 5 minutes to full context.

First contribution path:

saipen scout T-14     # Agent reproduces the crash, finds the fix
# Fix it, commit, PR
# No senior dev needed for context handoff

Measured result: 5 minutes to project status awareness vs 70 minutes traditional.

Use Case 8: Multi-repository coordination

Context: 5 microservice repos, each SAIPEN-managed:

  • api-gateway/, auth-service/, payment-service/, notification-service/, frontend/

Problem: Coordinating across repos:

  • Which services have pending work?
  • Which are blocked waiting on another service?
  • Which are shipping this week?
  • Need to check 5 different boards in 5 different tools

Solution:

# Orchestrator script reads all 5 STATE.md files
for repo in api-gateway auth-service payment-service notification-service frontend; do
  echo "=== $repo ==="
  cat $repo/.saipen/STATE.md
  echo
done

Output:

=== api-gateway ===
phase: DONE
next_action: "Wait for user command"

=== auth-service ===
phase: BUILD
task: T-8 add rate limiting
blocker: waiting on api-gateway v2 API contract
next_action: "WAIT: api-gateway — is the v2 contract finalized?"

=== payment-service ===
phase: DONE
next_action: "Wait for user command"

=== notification-service ===
phase: BLOCKED
blocker: payment-service not shipping webhook endpoint
next_action: "WAIT: payment-service — ETA on webhook endpoint?"

=== frontend ===
phase: SHIP
task: T-12 integrate auth v2
next_action: "SHIP T-12: v2.1.0"

Instant picture:

  • 2 services ready (api-gateway, payment-service)
  • 1 building but blocked (auth-service — waiting on contract)
  • 1 blocked on another team (notification-service — waiting on payment)
  • 1 shipping (frontend)

Cross-repo dependencies tracked via needs: in tickets:

- [ ] T-8 auth-service rate limiting | needs: api-gateway-v2-contract
- [ ] T-3 notification webhook | needs: payment-service-webhook

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

Use Case 9: Disaster recovery

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

Problem:

  • STATE.md says BUILD but agent is gone
  • claim_time is 45 minutes stale
  • Uncommitted code changes — were they good or experimental?
  • No memory of what the agent was doing

Solution (RFC 1.5 Recovery):

1. New agent opens project:

saipen continue

2. Automatic stale detection:

RECOVERY: T-18 claim by dead-agent is stale (elapsed: 45 min, limit: 15 min)
  -> claim_time: 2026-07-26T11:45:00Z (agent: dead-agent)
  -> now: 2026-07-26T12:30:00Z
  -> Resetting claim, preserving BOARD line

3. STATE.md was corrupt (bad YAML):

RECOVERY: STATE.md frontmatter parse error at line 4
  -> Copying to .saipen/recovery/STATE-corrupt-2026-07-26T12-30-00Z.md (verbatim, not edited)
  -> Restoring from .saipen/recovery/STATE-valid-2026-07-26T11-45-00Z.md
  -> Recovery copy logged, no data lost

4. LOG a recovery event:

- 26.07.26 12:30 [E-92] RECOVERY: [T-18] — stale claim (45 min), STATE.md
  frontmatter repaired from recovery snapshot, T-18 claimed by new-agent

5. Check git for unsaved work:

git diff --stat
src/search.jsx | 47 ++++++++++++++++++++++++++++
1 file changed, 47 insertions(+)

The crashed agent's work is preserved in the working tree. New agent picks it up.

6. Resume:

$ git diff HEAD -- src/search.jsx | head -5
+function performSearch(query) {
+  const results = searchIndex.find(query);
+  if (!results.length) return { empty: true };
+  return { results, total: results.length };
+}

Agent sees partial implementation, reads LOG tail for context, finishes the function.

Measured result: Crash -> resume in <1 minute. Zero lost work (git preserved everything). Previous known STATE restored from recovery.

Use Case 10: Open source contributor workflow

Context: External contributor wants to fix a bug in a SAIPEN-managed open source project (saipen itself).

Problem:

  • No access to internal chat history
  • No knowledge of project architecture
  • No knowledge of current state
  • Maintainer is busy — can't handhold

Solution:

1. Fork and clone

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

2. Read project state instantly

saipen status
phase: DONE
board: T-14 (TODO, P1, bug: export crashes on empty state), T-8 (TODO, P2, feature)
last conformance: PASS (2h ago)
staleness: fresh

3. Investigate the bug

saipen scout T-14

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

4. Fix and verify

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

5. Commit and PR

git add -A
git commit -m "fix: export crash on empty data (T-14)"
git push origin fix/export-crash

PR message:

Fixes T-14: export([]) now returns headers-only CSV instead of crashing

verify: pytest tests/test_export.py — all 15 tests pass including the new empty-data case

6. Maintainer reviews:

# Reads PR diff — 3 lines
# Runs: python tools/validate.py — PASS
# Runs: python tools/run_scenarios.py — 9/9 PASS
# Merges

Measured result: External contributor self-onboards and ships a fix in ~10 minutes. Maintainer reviews in ~2 minutes. No back-and-forth questions needed.

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

Clone this wiki locally