Skip to content

Phases

Jump to bottom
VAC34 edited this page Jul 26, 2026 · 13 revisions

Phases Reference

SAIPEN runs a structured phase workflow. Each phase has a dedicated doc in saipen/phases/. Below is a comprehensive summary of every phase.

PLAN

File: phases/plan.md

Amplify user intent into actionable tickets. Agent evaluates codebase, KNOWLEDGE/, and git log to produce a structured ticket board.

Key behaviors:

  • Bare saipen plan (no prompt) generates autonomous proposal
  • Ticket shape: one goal, independently verifiable, needs: for deps
  • Every ticket SHOULD carry | verify: <command or criterion>
  • Board order = execution order. >10 tickets: waves, detail current only
  • Size gate: <=2 files + obvious change -> skip PLAN, go straight to BUILD. LOG the size-gate decision.
  • Goal mode: goal_mode: true -> proceed to SCOUT directly, increment goal_waves by 1. Caps: 3 waves / 20 tickets.

SCOUT

File: phases/scout.md

Investigate a ticket before building. Mandatory before BUILD.

Key behaviors:

  • Claim the ticket: move from TODO to DOING, set owner:, claim_time:
  • Check KNOWLEDGE/ first — already known? Skip re-reading
  • Read ticket's files + ONE similar neighbor
  • Note: naming, error style, imports, utils, harness, build commands
  • Find the repo's architecture — never invent a parallel one
  • Durable finding -> KNOWLEDGE/. Grep before read

After SCOUT: STATE -> BUILD.

BUILD

File: phases/build.md

Implement a scouted ticket.

Key behaviors:

  • Implement the claimed ticket per SCOUT findings
  • Follow existing code conventions exactly
  • Mimic code style, use existing libraries and utilities
  • NEVER assume a library is available without checking
  • Never add comments unless the code itself needs explanation
  • Minimal, working implementation

After BUILD: STATE -> VERIFY. Iterate BUILD-VERIFY until passing.

VERIFY

File: phases/verify.md

Verify a built ticket passes its acceptance criteria.

Key behaviors:

  • Check the ticket's verify: criterion first
  • Run relevant tests
  • Verify against the acceptance bar, not just against "it runs"
  • Safety net: if verify reveals a design flaw -> RETURN SCOUT or PLAN
  • Debug cap: multiple failed attempts -> ## BLOCKED with facts + dead ends listed

After VERIFY: STATE -> REVIEW.

REVIEW

File: phases/review.md

Review the implementation before shipping.

Key behaviors:

  • Diff review: check for scope creep, dead code, incomplete error handling
  • Verify backwards compatibility
  • Check that tests exist and pass
  • Check documentation was updated
  • One-pass review — if too many issues, return to SCOUT/BUILD

After REVIEW: STATE -> SHIP.

SHIP

File: phases/ship.md

Ship the completed work. Commit, tag, release.

Key behaviors:

  • Bump VERSION file
  • Update CHANGELOG.md
  • Commit with conventional commit message
  • Tag the release
  • Update README badge version
  • Push to origin

After SHIP: STATE -> DONE.

DONE

File: phases/done.md

Final completion state.

Key behaviors:

  • Verify nothing was left dangling (uncommitted work, unpushed branches)
  • Set next_action to a neutral "wait for user command"
  • Complete checkpoint: write LOG -> update BOARD -> update STATE

ADD (Evolutionary Completer)

File: phases/add.md

Systematically expand capabilities. SAIPEN is evolutionary, not creative — it completes software, not reinvents it.

Priority ladder:

  1. Bugfix
  2. Complementary feature (Bold -> Italic)
  3. Workflow step (Open -> Save_As)
  4. UX consistency
  5. Platform convention

Implementation paths:

  • Direct: minimal delta + existing design language -> ticket, claim, BUILD directly
  • Planned: non-minimal or new design -> ticket, RETURN PLAN or SCOUT
  • Bugfixes always go through SCOUT (no inline fixes)

Industrial Completion Rule: When user requests one step of a workflow, implement the minimal coherent set (e.g., Cancel + Save when asked for Apply).

Goal mode: HUNT->ADD cycle increments goal_waves by 1. Mature product -> set goal_mode: false, write final report, STATE -> DONE.

CLEAN

File: phases/clean.md

Deep repository scrub. Triggered by saipen clean.

Safety floor: CLEAN MUST NOT delete user data without explicit confirmation.

Ordered steps:

  1. Board Scrub — remove [x] DONE tickets older than current work, prune stale TODOs, re-check BLOCKED tickets. Structural repair: deduplicate tickets, merge duplicate section headings.
  2. Orphan Hunt — delete unconnected files, ticket ambiguous orphans for human review
  3. Link & Path Audit — fix broken internal links/dead references
  4. Trash Removal — delete temp files, caches, empty dirs. Delete stale kitchen/ files (owning ticket DONE, content superseded). Seal oversized LOG.md (~300 lines / ~64 KB cap)
  5. Freshness Check — ensure repo paths and dependencies are current

HUNT

File: phases/hunt.md

Autonomous bug/code-quality sweep. Runs in background without disrupting workflow.

Hash-match optimization: If LOG.md tail contains hunt -> clean @<CURRENT_HASH>, skip entirely — no re-scan for unchanged code.

6 categories scanned:

  1. Failing tests — run test suite, report regressions
  2. Commits unverified — commits in LOG that lack a matching git log entry
  3. Stale TODO/FIXME/HACK — code markers that outlived their context
  4. Silent failures — empty catch blocks, ignored return values, missing IO error paths, except: without handling
  5. Symmetry gaps — features whose counterpart doesn't exist (import/export, save/load, add/remove)
  6. Dead code, orphan files — unused functions, unreachable branches, dangling assets

Automatic cleanup (free, no ticket): up to 5 files per sweep classified as "obvious junk" (temp files, empty dirs, clearly orphaned caches). All other findings get ticketed.

MARKHUNT

File: phases/markhunt.md

Full manual-hunt process with triage. Runs every 6 releases or when significant architectural drift is detected.

5 vectors:

  1. Logical (spec contradictions, edge cases, missing failure modes)
  2. Manual (concurrency, error handling, silent data loss)
  3. Structural (dependency graph, state machine, resource lifecycle)
  4. Human (setup friction, error message quality, footguns)
  5. Business (license compliance, stale dependencies, security practices)

Outcome: each finding ticketed with severity, fixed within same session if P0/P1, triaged for backlog otherwise.

TRANSLATE

File: phases/translate.md

Deep, isolated translation preparation. Quarantined environment — never touches main project files.

Isolation:

  • Work happens exclusively inside .saipen/saitranslate/kitchen/
  • Own STATE.md if running as parallel dedicated agent
  • MUST NOT modify main project files during translation

Surface:

  • Docs: README, SECURITY, CONTRIBUTING, SPEC and other top-level user-facing docs
  • UI strings: only if the software actually has real UI strings (grep before inventing)

Core vs SubSaipen split:

  • Core handles: English, Russian, Estonian, Дед voice
  • SubSaipen instances handle all other languages (29 languages)
  • 32 languages total, 5 files per locale

Maintenance:

  • Every saipen translate run re-scans drift since last run
  • Version badge drift is machine-detectable via tools/validate.py

BLOCKED

File: phases/blocked.md

Handles session-level blocks that prevent any work from continuing.

Key behaviors:

  • Set STATE.blocker to the blocking condition
  • Set STATE.next_action to WAIT: <specific question or decision needed>
  • The WAIT must name the concrete decision, never "what should I do?"
  • Re-check periodically: block still active? Yes -> stay, No -> resume
  • Switch to independent work if possible (kitchen tasks, doc cleanup)

INIT

File: phases/init.md

Initialize a new SAIPEN project. Called by saipen set.

Key behaviors:

  • Create .saipen/ directory structure
  • Write default STATE.md, BOARD.md, LOG.md
  • Set initial phase to DONE (ready for first PLAN)
  • Register project in SAIPEN home if applicable

PREPARE

File: phases/prepare.md

Pre-flight checks before any phase transition.

Key behaviors:

  • Verify .saipen/ exists and is readable
  • Check STATE.md is valid frontmatter
  • Verify BOARD.md sections are well-formed
  • Check git status for conflicts or dirty state
  • Report blockers before starting work

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

Clone this wiki locally