Phase transitions and gates

What you need: A scaffolded project-state/ with a phase preset selected.

A phase is a named stage in the project lifecycle. Each phase has a gate-in (what must be true to enter) and a gate-out (what must be true to leave). The phase-gate skill enforces these gates. It refuses transitions when gate artifacts are missing — no overrides, no soft warnings.

Five presets

Phase definitions come from presets in templates/phase-presets/. The preset is selected during scaffolding and recorded in manifest.yaml:

phases:
  preset: "agile-default"
  current_phase: "04-release"

grant-default

For grant-funded projects (PIC, NSERC, NIH, EU Horizon).

Gates are document-driven: MPA signed, ethics approval obtained, IP agreements filed. The PIC compliance pack adds PIC-specific criteria on top of these base gates (e.g., "PCAIS contribution agreement signed by all consortium members" as a planning gate-out).

agile-default

For engineering teams running Scrum/Kanban.

graph LR
  A[Discovery] --> B[Development]
  B --> C[Release]
  C --> D[Maintenance]

Lightweight gates. Discovery exits when scope and milestones are defined. Development exits when the release candidate passes hardening. Release exits when deployment is confirmed. Maintenance is the terminal phase.

waterfall-default

For traditional sequential projects.

Formal sign-off at each gate. Requirements gate-out requires a signed requirements document. Design gate-out requires approved architecture specs. Each phase produces a defined artifact that the next phase consumes.

client-engagement-default

For consulting and client-services work.

Client approval gates. Scoping exits when the statement of work is signed. Delivery exits when deliverables are accepted. Review is the feedback loop. Handoff is the terminal phase with knowledge transfer artifacts.

open-source-default

For community-governed projects.

Community readiness checks. Incubation exits when docs, CI, and a contributor guide exist. Active exits when the project reaches a stable API. Maintained is the long-term phase. Archived is the terminal phase.

The gate checklist

Ask for the gate status at any time:

What's blocking the gate?

The phase-gate skill reads the current phase's gate-out criteria and checks each one:

# Gate Status — 04-release (agile-default)

Gate-out criteria for "Release":

  [x] All milestones at 100% or deferred
  [x] No critical risks open
  [ ] Release notes published            ← BLOCKING
  [x] Changelog updated
  [ ] Version tag created                 ← BLOCKING

2 of 5 criteria unmet. Cannot transition to 05-maintenance.

Each criterion maps to a verifiable condition: a file exists, a milestone status is complete, a risk status is mitigated, a document is in documents/published/.

Transitioning

Request a transition:

Transition to maintenance phase

If gates are met, the transition happens:

Phase transition: 04-release → 05-maintenance

  [x] All milestones at 100% or deferred
  [x] No critical risks open
  [x] Release notes published
  [x] Changelog updated
  [x] Version tag created

Transition complete. state.json updated.
Activity logged: phase.transitioned 04-release → 05-maintenance

If gates are not met, the transition is refused:

Cannot transition from 04-release to 05-maintenance.

Unmet gate-out criteria:
  [ ] Release notes published
      → Publish release notes via /project-blog-publisher
  [ ] Version tag created
      → Create tag via /project-git

Resolve these items and try again.

The refusal names the blocking criteria and suggests which skill can resolve each one. This is not a warning you can override — the transition will not happen until the criteria are met.

Pack overrides

A compliance pack can add or modify gate criteria for any preset. The pack ships a profiles/phase-gate.yaml that augments the base preset:

# packs/pic-pcais/profiles/phase-gate.yaml
overrides:
  planning:
    gate_out:
      - id: mpa_signed
        label: "MPA signed by all consortium members"
        check: "documents/published/mpa-*.pdf exists"
      - id: ethics_approved
        label: "Ethics approval obtained"
        check: "decisions/*-ethics-approval.yaml exists with status: final"

Loading the PIC pack adds these criteria to the grant-default preset's planning phase. Without the pack, the base preset's gate criteria apply. Multiple packs compose — each pack's overrides are merged, not replaced.

Custom presets

You can write your own phase preset. Create a YAML file following the preset schema:

# templates/phase-presets/my-custom.yaml
id: my-custom
name: "Custom Lifecycle"
phases:
  - id: "01-research"
    name: "Research"
    gate_in: []
    gate_out:
      - id: lit_review_complete
        label: "Literature review document published"
        check: "documents/published/lit-review-*.md exists"
  - id: "02-prototype"
    name: "Prototype"
    gate_in:
      - id: research_complete
        label: "Research phase complete"
    gate_out:
      - id: prototype_demo
        label: "Prototype demonstrated to stakeholders"
  - id: "03-production"
    name: "Production"
    gate_in:
      - id: prototype_accepted
        label: "Prototype accepted"
    gate_out: []

Reference it from your manifest:

phases:
  preset: "my-custom"
  current_phase: "01-research"

The phase-gate skill reads your custom preset and enforces its gates identically to the built-in presets. See Customization for more on writing custom presets and packs.

Next step

Phase presets, gate criteria, and pack overrides are all forms of customization. Customization covers the full picture: what a pack contains, how to edit the reporting matrix, how to write custom presets, and how to author a new pack from scratch.