SubSaipen

SubSaipen (Sub-Agents)

SubSaipen are delegatable read-only agent roles for parallel work. Any sai* bare word auto-spawns a sub-agent with full read-only isolation.

How it works

1. Auto-spawn: Type any sai* name (e.g. saihunt, saiwiki). If no subSaipen with that name exists, one is created automatically.
2. Read-only: SubSaipen can read all project files but MUST NOT write to the main tree. Findings go to its own kitchen/OUTBOX.md.
3. Isolation: Each subSaipen has its own STATE.md, BOARD.md, LOG.md, and kitchen/ inside .saipen/extensions/subs/<name>/.
4. Collection: Main agent runs collect to read OUTBOXes and act on findings.
5. Crew mode: 3 subSaipen can run simultaneously in a split-window layout.

Shipped subSaipen

---

saiwiki

Role: Wiki and content maintenance.

Workflow:

• Adopt -> read the top TODO ticket on its board
• Draft wiki pages from the main project (read-only)
• Write page-ready content to kitchen/OUTBOX.md
• Never writes the main tree

Shipped with: WIKI-001 (locale freshness audit), WIKI-002 (badge-drift maintenance mechanism), WIKI-003 (wiki injection)

---

saihunt

Role: Autonomous bug/code-quality sweep runner.

Workflow:

• Adopt -> read the top HUNT ticket on its board
• Run the 6-category HUNT sweep against HEAD
• Write findings to kitchen/OUTBOX.md with severity (critical: true|false)
• Never writes the main tree

6 categories scanned:

1. Failing tests
2. Commits unverified in LOG
3. Stale TODO/FIXME/HACK markers
4. Silent failures (empty catches, ignored returns)
5. Symmetry gaps (missing counterpart features)
6. Dead code and orphan files

Auto-cleanup: Up to 5 "obvious junk" files per sweep can be deleted without a ticket.

---

saitranslate

Role: Translation locale structure validation and maintenance.

Workflow:

• Adopt -> validate the translation kitchen structure
• Check all 32 locales have 5 required files with valid UTF-8
• Verify version badges match current VERSION
• Report drift to kitchen/OUTBOX.md
• Never writes the main tree

Coverage: 32 locales, 5 files per locale (README, SECURITY, CONTRIBUTING, SPEC, CODE_OF_CONDUCT)

---

saipython

Role: Python-specific code analysis and maintenance companion.

Workflow:

• Adopt -> read the top TODO on its board
• Analyze Python code for issues (type hints, imports, patterns)
• Write analysis to kitchen/OUTBOX.md

Shipped with: A pen/ scratch directory in its kitchen for Python-specific scratch work.

---

Creating a new subSaipen

SubSaipen can be spawned via the official mechanism:

saipen sub spawn <name>

Or auto-spawned by simply typing the bare sai* name. The spawned instance gets a TEMPLATE-based STATE.md, empty BOARD/LOG, and kitchen/.

.saipen/extensions/subs/<name>/
    STATE.md     # phase, task, next_action, mode: read-only
    BOARD.md     # ticket tracking
    LOG.md       # event graph
    kitchen/
        OUTBOX.md  # findings container

Shared infrastructure

All subSaipen share:

• _shared/inbox.md — cross-subSaipen message board. A subSaipen can leave notes for other subSaipen or the main agent here.
• MANIFEST.md — registry of all spawned subSaipen with last activity timestamps.
• PROTOCOL.md — the formal subSaipen protocol (rules for read-only mode, adoption, collection).
• crew.md — crew mode protocol for running 3 subSaipen concurrently.
• TEMPLATE/ — blank template files used by saipen sub spawn.

Collection

Main agent collects subSaipen output:

collect

This reads all OUTBOX.md files, acts on findings, and marks each as collected. Findings can range from info-level (structure OK) to critical (security bug found).