Getting Started

Getting Started

Prerequisites

• Git
• A filesystem (local or remote)
• An AI coding agent (Claude, Gemini, Codex, Aider, etc.)

Setup

1. Clone the repo:

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

2. Initialize your project:

   saipen set

   Creates .saipen/ directory with STATE, BOARD, LOG.

3. Read saipen/BOOT.md — the cold-start kernel.

Quick commands

Command	What it does
saipen set	Initialize .saipen/ in current project
saipen plan	Generate proposal tickets
saipen goal <text>	Run multi-wave goal mode
saipen status	Project state, blockers, staleness
saipen scout	Investigate a ticket before building
saipen build	Implement a scouted ticket
saipen verify	Verify a built ticket passes its criteria
saipen clean	Deep repo scrub (orphans, stale board items)
saipen continue	Resume where last session stopped
saipen markhunt	Full 6-category bug/quality scan

Phases

SAIPEN runs in phases. Each phase has its own rules in saipen/phases/<phase>.md:

PLAN → SCOUT → BUILD → VERIFY → REVIEW → SHIP → DONE

Plus auxiliary phases: ADD, CLEAN, HUNT, TRANSLATE, MARKHUNT.

SubSaipen (sub-agents)

Delegatable read-only agent roles for parallel work:

• saiwiki — wiki/content maintenance
• saihunt — autonomous bug sweep runner
• saitranslate — locale translation worker

Spawning is automatic: any sai* bare word auto-creates the sub-agent with full read-only isolation.