Auto-Status Transitions

Planu specs move through a lifecycle managed by a state machine. Calling update_status with a target status triggers the transition and fires a cascade of autopilot actions automatically — no manual steps required.

The State Machine

         ┌─────────┐
         │  draft  │
         └────┬────┘
              │ update_status(review)
              ▼
         ┌─────────┐
         │ review  │◄──── request_changes
         └────┬────┘
              │ approve_spec / update_status(approved)
              ▼
         ┌──────────┐
         │ approved │
         └────┬─────┘
              │ update_status(implementing)
              ▼
       ┌─────────────┐
       │implementing │
       └──────┬──────┘
              │ update_status(done)
              ▼
          ┌──────┐
          │ done │
          └──────┘

Any stage → blocked (update_status(blocked))
blocked → previous stage (update_status(review) etc.)

Blocked is a meta-state

blocked does not reset progress. When the blocker is resolved, transition back to the appropriate active stage.

What Fires on Each Transition

Transition	Trigger	Autopilot actions
draft → review	update_status(review)	Run challenge/readiness/review gates and write spec-review evidence
review → approved	update_status(approved) or approve_spec	Snapshot spec version, lock spec against edits (lock_spec), verify dedicated reviewer evidence
approved → implementing	update_status(implementing)	Start implementation against the approved contract
implementing → done	validate then update_status(done)	Verify implementation, write validation-review evidence, scan crash risks, finalize sync
any → blocked	update_status(blocked)	Record blocker reason, pause autopilot cascade

Using update_status

Invoke update_status with the spec ID and target status:

# Move a spec to review
update_status("SPEC-659", "review")

# Approve after review is complete
update_status("SPEC-659", "approved")

# Start implementation
update_status("SPEC-659", "implementing")

# Validate first, then mark done
validate("SPEC-659")
update_status("SPEC-659", "done")

The tool returns a summary of which cascade actions ran and their results. If any cascade action encounters a blocker or needs clarification, it returns an InteractiveQuestion[] for the LLM to relay.

Fire-and-forget vs Blocking Actions

Action	Behavior
validate	Blocking for done — must produce fresh reviewer evidence before done can finalize
check_readiness	Blocking — transition to review/approved is gated on a passing readiness check
challenge_spec evidence	Blocking for review — review is gated on recorded challenge resolution
spec-review evidence	Blocking for approved — approval requires a dedicated plan reviewer artifact
lock_spec	Blocking — must succeed before approved is written

Blocking vs. approved

If check_readiness returns 0 passing criteria, update_status(approved) will return an InteractiveQuestion[] asking you to confirm you want to approve an incomplete spec.

---

Cross-links

• Interactive Questions — how blocking transitions request clarification
• Lean Spec Format — the status frontmatter field that drives this machine
• Unified spec.md (SPEC-630) — where the acceptance criteria live that validate checks