workflow

Files (1)

• SKILL.md

SKILL.md (first lines)

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 worktree and 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+ subagent 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
- Use `gh pr merge --merge --delete-branch`

### 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 via the `workflow` object. See `../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 commands (`/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 commands manually

From brian-lai/para-programming-plugin, MIT.

More from brian-lai/para-programming-plugin