para-workflow

name	para-workflow
description	Orchestrate the full PARA execution cycle across phases. Triggers on: "run the workflow", "para workflow", "orchestrate phases", "auto mode", "run all phases", "execute the full workflow".

Skill: para-workflow

Orchestrate the full PARA execution cycle across phases: execute -> PR -> review -> summarize -> archive -> next phase. Supports both manual (pause at boundaries) and autonomous (--auto) modes.

Usage

para-workflow                     # Run workflow for active plan (pause at phase boundaries)
para-workflow --auto              # Fully autonomous (no pause between phases)
para-workflow --phase=N           # Start from a specific phase
para-workflow --skip-review       # Skip Staff+ review loops (for speed)

Prerequisites

• context/context.md must exist with an active phased plan
• For simple (non-phased) plans, use para-execute directly -- the workflow command is designed for multi-phase orchestration
• Git repository must be clean (or user confirms proceeding with dirty state)

Process (Per Phase)

For each phase in the plan, the workflow runs these steps in order:

Step 1: Execute

Run para-execute --phase=N.

• Creates a branch for the phase
• Extracts checklist items as todos
• Implements each todo following the TDD cycle (red -> green -> commit)
• Each checklist item text becomes the commit message

Step 2: Create PR

Create a pull request for the phase branch. This step owns PR creation for workflow runs. para-summarize (Step 4) will detect that it's running inside the orchestrator and skip its standalone push/PR guidance.

• PR title: para/{task-name} phase N: {phase title}
• PR body: auto-generated from:
  • Phase objective (from sub-plan)
  • Commit list with descriptions
  • Checklist of implementation steps (checked off)
  • Link to plan file

Step 3: Review

Run para-review --pr (unless --skip-review is specified).

• Staff+ independent agent reviews the PR
• Loop until approved (or user overrides)
• Apply fixes, create additional commits as needed
• Push fixes to the PR branch

Step 4: Summarize

Run para-summarize --phase=N.

• Generate phase summary to context/summaries/
• Record what changed, rationale, key learnings
• Mark phase as "completed" in context/context.md

Step 5: Merge

Merge the PR.

• Default mode: Pause and ask user "Ready to merge Phase N PR? (Y/n)"
• --auto mode: Merge automatically after Staff+ review approval

Step 6: Archive

Run para-archive for mid-workflow cleanup.

• For mid-workflow (more phases remaining): partial archive -- update context/context.md to reflect completed phase, but don't create a full archive snapshot
• For final phase: full archive -- move context to archives, create fresh context

Step 7: Next Phase

If more phases remain:

• Default mode: Pause and ask "Ready to start Phase {N+1}? (Y/n)"
• --auto mode: Proceed immediately
• Pull latest main (with merged phase), update context/context.md to reflect new active phase
• Loop back to Step 1

State Tracking

Track workflow progress in context/context.md metadata. See ../para-init/context-schema.md for the full field reference.

This enables resumability -- if the workflow is interrupted, running para-workflow again picks up from the current step of the current phase.

Error Handling

• Step failure: If any step fails (e.g., tests fail, PR has conflicts, review doesn't converge), pause and present the error to the user with options:

  1. Fix the issue and continue (para-workflow resumes from current step)
  2. Skip the current step (para-workflow --skip-step=review)
  3. Abort the workflow

• Merge conflicts: If the PR cannot be merged, pause and ask the user to resolve conflicts manually. After resolution, resume with para-workflow.

• Review non-convergence: If the Staff+ review hits the 5-round limit, escalate per para-review convergence rules. The workflow pauses until the user decides.

Completion

When all phases are complete:

1. Run full archive (para-archive)
2. Display summary of all phases:
   • Total phases completed
   • Total commits across all phases
   • PRs merged (with links)
   • Staff+ review rounds per phase
3. Suggest next steps (e.g., tag a release, update documentation)

Notes

• The workflow command is an orchestrator -- it delegates to existing skills (para-execute, para-review, para-summarize, para-archive)
• --auto mode still requires Staff+ review approval as a quality gate (unless --skip-review is also specified)
• Each phase creates its own PR, enabling incremental review and merge
• The workflow is resumable -- state is tracked in context/context.md
• For single-phase plans, the workflow still works but is equivalent to running the skills manually