Use Cases

Use Cases

Real-world usage patterns for SAIPEN.

---

Use Case 1: Solo developer across sessions

Context: Developer works evenings on a side project. Each session is 1-2 hours, days apart. Different agents available (Claude Code at home, Gemini at work).

Problem: Every session starts with "what was I doing?" Context windows reset. Chat history is too long to re-read.

Solution: SAIPEN's .saipen/ directory is the persistent memory. Agent reads STATE (phase: BUILD, task: T-14 implement export), BOARD (T-14 in DOING), LOG (last 5 events). Picks up exactly where left off.

Result: 0 minutes of context recovery per session.

---

Use Case 2: Team with mixed agents

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

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

Solution: All three agents read/write the same .saipen/ files. Pure markdown — no vendor lock-in. Agent A creates a ticket in BUILD, Agent B can pick it up in VERIFY next day.

Result: Agents are interchangeable. The project owns its memory, not the vendor.

---

Use Case 3: CI/CD integration

Context: A CI pipeline runs automated code reviews.

Problem: CI runs in isolation — has no context of what the PR is trying to achieve, what phase the project is in, what tickets are open.

Solution: CI checks out the repo including .saipen/. Pre-commit hook (installed via tools/install_hook.py) validates .saipen/ structure on every commit. tools/validate.py runs in CI to catch drift.

Result: Structural corruption never ships. CI knows if the project is in a valid state before any commit.

---

Use Case 4: LLM evaluation sandbox

Context: Researcher wants to test how different LLMs handle multi-step software engineering tasks.

Problem: Each test run needs identical starting conditions. Agent memory and context management differ per platform.

Solution: SAIPEN's .saipen/ STATE.md gives the same initial condition to every agent. phases/scout.md, build.md, verify.md create a reproducible evaluation pipeline. tests/scenarios/ provides executable fixtures with declared pass/fail expectations.

Result: Apples-to-apples comparison across Claude, Gemini, GPT, DeepSeek, and open-source models.

---

Use Case 5: Long-running project maintenance

Context: A library with low activity — one maintainer, 3-4 updates per year.

Problem: With months between sessions, maintainer can't remember the architecture, the phase state, or what depends on what.

Solution: saipen status shows everything: current phase, open tickets, last conformance check, what's waiting on the human. saipen continue resumes precisely.

Result: Zero ramp-up time after months away.

---

Use Case 6: Parallel sub-agent workflows

Context: Main agent building a feature. User wants a translation sweep, a bug hunt, and a documentation audit — all in parallel.

Solution:

1. saihunt — bugs (read-only, writes OUTBOX)
2. saitranslate — translation audit (read-only, writes OUTBOX)
3. saiwiki — wiki content check (read-only, writes OUTBOX)

All three run concurrently. Main agent never interrupted. collect gathers findings.

Result: 3 tasks in parallel, 0 interruption to main workflow.

---

Use Case 7: New developer onboarding

Context: A new team member (human) joins a SAIPEN-managed project.

Problem: Understanding project state, conventions, and current work requires reading documentation, asking senior devs, piecing together context.

Solution: saipen status tells them the current phase and any WAIT items. BOARD.md shows what's pending. LOG.md shows the work history. State fits in a single file read.

Result: 5-minute onboarding to project status vs hours of meetings.

---

Use Case 8: Multi-repository coordination

Context: A microservices project with 5 repos, each SAIPEN-managed.

Problem: Coordinating state across repos — which services need updates, which are blocked, which are shipping.

Solution: Each repo has its own .saipen/. A meta-repo or orchestrator agent reads all 5 STATE.md files to produce a unified status report. Cross-repo dependencies tracked via needs: in tickets.

Result: Cross-repo visibility without a centralized tool.

---

Use Case 9: Disaster recovery

Context: Agent crashes mid-BUILD with unstaged changes and stale state.

Problem: Unsaved work, stale claim_time (>15 min), possibly corrupt STATE.md.

Solution: RFC § 1.5 Recovery:

1. STATE.md corrupt? Copy to .saipen/recovery/, restore from last valid state
2. Claim stale? Reset, reclaim ticket
3. Unstaged changes? git diff, decide what to keep
4. LOG a RECOVERY event

Result: Crash -> resume in <1 minute.

---

Use Case 10: Open source contributor workflow

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

Problem: No access to chat history. No knowledge of project state.

Solution: Fork repo. saipen status shows: "phase: DONE, tickets: T-14 (TODO, bug: export crashes on empty state)". saipen scout T-14 reads the relevant code and reproduces the bug. Contributor fixes it, commits, PRs.

Result: External contributors self-onboard without maintainer intervention.