Workflow Transition

Execution Context: This skill runs in a subagent session, delegated by the PAW orchestrator when processing a paw-transition TODO. Return structured output—do not make orchestration decisions beyond the transition.

Purpose

Gate between workflow activities. Ensures:

• •Session policy is respected at stage boundaries
• •Correct branch state before implementation
• •Required artifacts exist before proceeding
• •Next activity is correctly identified and queued

Procedure

Execute these steps in order. Do not skip steps.

Step 1: Identify Current State

Read WorkflowContext.md to determine:

• •Work ID and target branch
• •Session Policy (per-stage | continuous)
• •Review Strategy (prs | local)
• •Review Policy (always | milestones | planning-only | never)
  • •If missing, check for legacy Handoff Mode: field and map: manual→always, semi-auto→milestones, auto→never
  • •If neither present, default to milestones

Identify last completed activity from TODOs or artifacts.

Step 2: Determine Next Activity

Use the Mandatory Transitions table:

Skippable = NO: Add activity TODO and execute immediately after transition completes.

Step 3: Check Stage Boundary and Milestone Pause

Stage boundaries occur when moving between these stages:

• •spec-review passes → code-research
• •plan-review passes → implement (Phase 1)
• •phase N complete → phase N+1
• •all phases complete → final-pr
• •paw-pr complete → workflow complete

Stage-to-milestone mapping (determines which milestone is reached at each boundary):

Determine pause_at_milestone:

• •If Review Policy ∈ {always, milestones}: pause at ALL milestones
• •If Review Policy = planning-only:
  • •Spec.md, ImplementationPlan.md, Final PR: pause_at_milestone = true
  • •Phase completion (including last phase): pause_at_milestone = false
• •If Review Policy = never: pause_at_milestone = false

Determine session_action:

• •If crossing a stage boundary AND Session Policy = per-stage: set session_action = new_session
• •Otherwise: set session_action = continue

If session_action = new_session, set inline_instruction to: next activity and phase (e.g., "Phase 2: Tool Enhancement")

Continue to Step 4 (preflight still needed for inline_instruction context).

Step 4: Preflight Checks

Before the next activity can start, verify:

For paw-implement:

• • On correct branch per Review Strategy
  • •prs: phase branch (e.g., <target>_phase1)
  • •local: target branch
• • ImplementationPlan.md exists and has the target phase

For paw-code-research:

• • Spec.md exists (unless minimal mode)

For paw-pr:

• • All phases complete
• • On target branch or ready to merge

Artifact Tracking Check (for all activities):

• •Check if .paw/work/<work-id>/.gitignore exists
• •If exists with * pattern: artifact_tracking = disabled
• •Otherwise: artifact_tracking = enabled

If any check fails, report blocker and stop.

Step 5: Queue Next Activity

Add TODO for next activity:

• •[ ] <activity-name> (<context>)
• •[ ] paw-transition

Completion

After completing all steps, return structured output:

TRANSITION RESULT:
- session_action: [continue | new_session]
- pause_at_milestone: [true | false]
- next_activity: [activity name and context]
- artifact_tracking: [enabled | disabled]
- preflight: [passed | blocked: <reason>]
- work_id: [current work ID]
- inline_instruction: [for new_session only: resume hint]

If pause_at_milestone = true: The PAW agent must PAUSE and wait for user confirmation before proceeding.

If session_action = new_session: The PAW agent must call paw_new_session with the provided work_id and inline_instruction.

If preflight = blocked: The PAW agent must report the blocker to the user.

Mark the paw-transition TODO complete after returning this output.

Guardrails

• •Do NOT skip the stage boundary check (Step 3)
• •Do NOT return session_action = continue if boundary + per-stage policy
• •Do NOT return preflight = passed if checks actually failed
• •Do NOT call paw_new_session directly—return the decision for PAW agent to act on