Skip to content

PAW Agents Reference

PAW uses two AI chat modes ("agents") that orchestrate workflow activities through dynamically loaded skills. Each agent is a compact orchestrator that reasons about user intent and delegates to specialized skills. The paw-lite skill can be loaded by any agent for a lightweight workflow.

Agents Overview

Agent Purpose Architecture
PAW Implementation workflow orchestrator Skills-based
PAW-Review PR review workflow orchestrator Skills-based

Both agents follow the same pattern: a compact orchestrator that loads a workflow skill for guidance, then delegates activities to specialized skills via subagents.

Platform runtime note: Copilot CLI runs installed agents/, skills/, and prompt content directly. The VS Code extension uses src/ TypeScript for commands, setup, and handoff, but that code is not executed in CLI sessions.

PAW Lite is available as the paw-lite skill — any agent can load it on demand.

Implementation Workflow

PAW Agent

Purpose: Execute the complete PAW implementation workflow—from specification through final PR—using dynamically loaded skills.

Invocation (VS Code): PAW: New PAW Workflow command or /paw in Copilot Chat

Invocation (Copilot CLI): copilot --agent PAW or use /agent to select PAW inside a session

Architecture: The PAW agent uses a skills-based architecture with a hybrid execution model. Skill loading is platform-specific:

  1. Loads the paw-workflow skill for orchestration guidance
  2. Loads activity skills through the current platform's native skill system (extension-contributed skills in VS Code; installed skill files in Copilot CLI)
  3. Delegates activities to specialized skills
  4. Applies Review Policy and Session Policy for workflow control

Hybrid Execution Model:

Execution Type Skills Why
Direct (in-session) paw-init, paw-spec, paw-planning, paw-implement, paw-pr, paw-final-review, paw-planning-docs-review, paw-status, paw-work-shaping, paw-rewind Interactive activities that benefit from user collaboration
Subagent (isolated) paw-spec-research, paw-code-research, paw-spec-review, paw-plan-review, paw-impl-review, paw-transition Research and review activities that benefit from context isolation

This preserves conversation flow for interactive work while leveraging fresh context for focused research and review.

Activity Skills:

Skill Capabilities Primary Artifacts
paw-init Bootstrap workflow, create WorkflowContext.md WorkflowContext.md
paw-spec Create/revise specifications Spec.md
paw-spec-research Answer factual questions about existing system SpecResearch.md
paw-spec-review Validate spec quality and completeness Structured feedback
paw-code-research Document implementation details with file:line refs CodeResearch.md
paw-planning Create implementation plans with phases (single/multi-model) ImplementationPlan.md, planning/
paw-plan-review Validate plan feasibility and spec alignment Structured feedback
paw-planning-docs-review Holistic review of planning artifacts bundle; delegates SoT orchestration to paw-sot REVIEW*.md in reviews/planning/
paw-implement Execute plan phases, make code changes Code files, Docs.md
paw-impl-review Review implementation, add docs, open PRs Phase PRs
paw-final-review Pre-PR review; delegates SoT orchestration to paw-sot REVIEW*.md in reviews/
paw-pr Pre-flight validation, create final PR Final PR
paw-status Diagnose workflow state, recommend next steps, explain PAW/onboarding Status reports
paw-lite Lightweight workflow: plan → fleet-implement → review → PR Plan.md

Utility Skills:

Skill Purpose
paw-git-operations Branch naming, strategy-based branching, selective staging
paw-review-response PR comment mechanics (read, TODO, commit, reply)
paw-docs-guidance Documentation templates and project doc update patterns
paw-sot Society-of-thought engine (loaded by paw-planning-docs-review, paw-final-review, or paw-review-workflow)

Workflow Stages:

  1. Specification Stage
  2. paw-spec → paw-spec-research (if needed) → paw-spec (resume)

  3. Produces: Spec.md, SpecResearch.md

  4. Planning Stage

  5. paw-code-research → paw-planning → paw-plan-review → paw-planning-docs-review (if enabled)

  6. Produces: CodeResearch.md, ImplementationPlan.md, Planning PR (prs strategy)

  7. Implementation Stage

  8. For each phase: paw-implement → paw-impl-review

  9. Produces: Code changes, Phase PRs (prs strategy)

  10. Final Review Stage (if enabled)

  11. paw-final-review

  12. Produces: Review artifacts in .paw/work/<work-id>/reviews/

  13. Finalization Stage

  14. paw-pr
  15. Produces: Final PR to main

Policy Configuration:

Policy Values Description
Review Policy every-stage / milestones / planning-only / final-pr-only When to pause for human review
Session Policy per-stage / continuous Chat context management (CLI always uses continuous)
Workflow Mode full / minimal / custom Workflow complexity
Review Strategy prs / local PR-based or direct commits

Review Policy Details:

Policy Behavior
every-stage Pause after every artifact is produced
milestones Pause at key artifacts (Spec.md, ImplementationPlan.md, Phase completion, Final PR)
planning-only Pause at Spec.md, ImplementationPlan.md, and Final PR only; auto-proceed at phases (requires local strategy)
final-pr-only Only pause at final PR — auto-proceed through all intermediate stages

Review Workflow

PAW-Review

Purpose: Execute the complete PAW Review workflow using dynamically loaded skills. This heavyweight workflow is intended for significant, thorough reviews. Generic code and PR review requests use the standard review path unless there is evidence of that broader intent.

Invocation (VS Code): /paw-review <PR-number-or-URL>

Invocation (Copilot CLI): copilot --agent PAW-Review then provide the PR number or URL

Architecture: The PAW Review agent uses a skills-based architecture. The shared review logic lives in skills; VS Code-specific automation remains in src/ only.

  1. Loads the paw-review-workflow skill for orchestration
  2. Executes activity skills via subagents for each stage
  3. Produces all review artifacts automatically

Skills Used:

Skill Type Stage Artifacts
paw-review-workflow Workflow — Orchestrates all stages
paw-review-understanding Activity Understanding ReviewContext.md, DerivedSpec.md
paw-review-baseline Activity Understanding CodeResearch.md
paw-review-impact Activity Evaluation ImpactAnalysis.md (single-model mode)
paw-review-gap Activity Evaluation GapAnalysis.md (single-model mode)
paw-sot Engine Evaluation REVIEW-{SPECIALIST}.md, REVIEW-SYNTHESIS.md (SoT mode)
paw-review-correlation Activity Evaluation CrossRepoAnalysis.md (multi-repo)
paw-review-feedback Activity Output ReviewComments.md (draft → finalized)
paw-review-critic Activity Output Assessment sections in ReviewComments.md
paw-review-github Activity Output GitHub pending or authorized submitted review

Workflow Stages:

  1. Understanding Stage
  2. Analyzes PR changes and creates ReviewContext.md
  3. Researches pre-change baseline at base commit

  4. Derives specification from implementation

  5. Evaluation Stage

  6. Single-model mode (default): Identifies system-wide impacts and gaps, categorizes findings as Must/Should/Could
  7. Society-of-thought mode: Specialist personas evaluate in parallel or debate mode, producing synthesized findings via paw-sot

  8. Correlates findings across repositories (multi-repo reviews, single-model only)

  9. Output Stage (4-step feedback-critique iteration)

  10. Initial feedback: Generates draft comments with rationale
  11. Critique: Adds assessment sections with Include/Modify/Skip recommendations
  12. Critique response: Updates comments per recommendations, marks final status
  13. GitHub posting: Creates a pending review by default; explicit submission requires exact target, head, review ID, and event verification

Comment Evolution: ReviewComments.md shows full history for each comment: original → assessment → updated → posted status. Skipped comments remain visible for manual inclusion if reviewer disagrees with critique.

Human Control: Explicit user direction overrides PAW defaults, but not integrity checks or unavailable capabilities. GitHub stays pending unless submission is explicitly authorized; Azure DevOps and local reviews remain artifact-only when executable output is unavailable.

Note: The six PAW-R* agents (R1A, R1B, R2A, R2B, R3A, R3B) have been replaced by this unified skills-based workflow.

Agent Invocation

Starting Workflows

GitHub Copilot CLI:

copilot --agent PAW        # Start implementation workflow
copilot --agent PAW-Review # Start review workflow

Or use /agent inside an existing session to switch to a PAW agent.

VS Code (Copilot Chat):

Workflow Command Prompt
Implementation PAW: New PAW Workflow /paw
Review — /paw-review <PR>

Note: Slash commands like /paw and /paw-review are VS Code-specific prompt templates.

The PAW agent understands natural language requests and routes them to appropriate skills. Common patterns:

  • "Create a spec for..." → paw-spec skill
  • "Research how X works" → paw-spec-research or paw-code-research
  • "Create an implementation plan" → paw-planning skill
  • "Implement phase N" → paw-implement skill
  • "What is PAW?" or "How do I get started?" → paw-status skill
  • "What's the status?" → paw-status skill

Review Policy Modes

PAW supports four review policies that control when the workflow pauses for human review:

Policy Behavior
every-stage Pause after every artifact is produced
milestones Pause at key artifacts (Spec.md, ImplementationPlan.md, Phase completion, Final PR)
planning-only Pause at Spec.md, ImplementationPlan.md, and Final PR only; auto-proceed at phases (requires local strategy)
final-pr-only Only pause at final PR — auto-proceed through all intermediate stages

Legacy Review Policy Mapping: Older WorkflowContext.md files may use never or always. The mapping is: never → final-pr-only, always → every-stage.

Legacy Handoff Mode Mapping: Older WorkflowContext.md files may use Handoff Mode instead of Review Policy. The mapping is: manual → every-stage, semi-auto → milestones, auto → final-pr-only.

Next Steps