Agent Skills: Phase Transitions

Phase Transitions

This skill guides moving Metis documents through their lifecycle phases.

Phase Sequences

Phases move forward only. You cannot go backward to a previous phase. Terminal phases cannot transition further.

Vision

draft → review → published

• draft → review
• review → published
• published: terminal

Initiative

discovery → design → ready → decompose → active → completed

• discovery → design
• design → ready
• ready → decompose
• decompose → active
• active → completed
• completed: terminal

Task

backlog → todo → active → completed
            ↓       ↓
         blocked ←──┘

• backlog → todo
• todo → active OR blocked
• active → completed OR blocked
• blocked → todo OR active (return from blocked state)
• completed: terminal

ADR

draft → discussion → decided → superseded

• draft → discussion
• discussion → decided
• decided → superseded
• superseded: terminal

WARNING: Auto-advancing from decided moves to superseded. Most ADRs should stay in decided indefinitely. Only manually transition to superseded when explicitly replacing with a new ADR.

Specification

discovery → drafting → review → published

• discovery → drafting
• drafting → review
• review → published
• published: terminal (but content remains editable as a living document)

Default Phases

When documents are created, they start in these phases:

• Vision: draft
• Initiative: discovery
• Task: todo (or backlog for backlog items)
• ADR: draft
• Specification: discovery

Backlog note: Tasks created with backlog_category start in backlog phase and do NOT auto-transition. You must explicitly transition from backlog → todo before the task can be worked.

Critical Rule: No Phase Skipping

Transitions are constrained to adjacent phases only.

Invalid transitions (will error):

• todo → completed (must go todo → active → completed)
• discovery → active (must progress through all intermediate phases)
• draft → published (must go draft → review → published)

To complete a task, call transition_phase twice:

1. transition_phase(short_code) → todo to active
2. transition_phase(short_code) → active to completed

To publish a vision, call transition_phase twice:

1. transition_phase(short_code) → draft to review
2. transition_phase(short_code) → review to published

Using transition_phase

Auto-advance (recommended):

transition_phase(short_code="PROJ-I-0001")

Moves to next valid phase. Validates exit criteria.

Explicit phase (for blocked state):

transition_phase(short_code="PROJ-T-0042", phase="blocked")

Use explicit phase only for moving to/from blocked state (tasks only).

Force (use sparingly):

transition_phase(short_code="PROJ-I-0001", force=true)

Skips exit criteria validation. Use only when accepting the risk.

Exit Criteria

Exit criteria are conditions that must be true before transitioning.

Good Exit Criteria

• Observable: Can be verified
• Specific: Clear what "done" means
• Relevant: Matters for next phase
• Achievable: Realistic for scope

Common Exit Criteria Patterns

discovery → design:

• Problem statement clear and validated
• Key constraints identified
• Stakeholders aligned on scope

design → ready:

• Solution approach documented
• Technical risks identified
• Dependencies mapped

ready → decompose:

• Design reviewed and approved
• Team capacity available
• No blocking dependencies

decompose → active:

• Tasks created with acceptance criteria
• Task backlog sufficient to start
• Team understands the work

active → completed (tasks):

• Acceptance criteria met
• Work verified/tested
• No known defects

Tracking Exit Criteria

Documents have exit_criteria_met frontmatter field:

exit_criteria_met: false  # or true

Set to true when criteria are met. Used by transition_phase with force: false.

Blocked Work

Handle blocked work explicitly:

1. Transition to blocked: transition_phase(short_code, phase="blocked")
2. Update blocked_by field in document to record what's blocking
3. Address the blocker
4. Return from blocked: transition_phase(short_code, phase="active") or phase="todo"

Note: Only tasks can be blocked - visions, initiatives, and ADRs cannot use the blocked phase.

Blocked is a special state that allows returning to todo or active. This is the only case where you can move "backward" - but it's really returning from a paused state, not reversing progress.

Working in Active Phase

CRITICAL: Active tasks and initiatives serve as persistent working memory. While in active phase, regularly update the document with:

• Progress: What's been completed
• Findings: Unexpected discoveries, blockers
• Decisions: Why you chose approach A over B
• Next steps: What remains if work is interrupted

This ensures no work is lost if context is compacted or the session ends.

When to Transition

Pull-Based Transitions

• Move initiative to active when capacity exists
• Move task to active when ready to start
• Move to completed when actually done

Don't Rush Transitions

Common mistakes:

• Initiative in "active" with no tasks isn't really active
• Task marked "completed" that doesn't meet criteria isn't done
• Design marked "ready" without review isn't ready

The phases protect you. They force discipline that prevents rework.

Monitoring Phase Health

Healthy Signs

• Work moves steadily through phases
• Exit criteria met before transitions
• Blocked items rare and resolved quickly
• Completed work stays completed

Unhealthy Signs

• Work stuck in early phases → unclear requirements or analysis paralysis
• Work stuck in decompose → team struggling to understand work
• Work jumping to active → skipping preparation
• "Completed" work reopening → exit criteria not met

Additional Resources

For detailed phase flow:

• references/phase-flow.md - Complete phase documentation with all transition rules