@paw-workflow/cli 0.0.1 → 0.0.4

package/README.md

@@ -53,8 +53,8 @@ paw uninstall --force  # Skip confirmation prompt
 
 ## What Gets Installed
 
-- **Agents**: PAW workflow orchestrators (`PAW.agent.md`, `PAW-Review.agent.md`)
-- **Skills**: 26 activity skills for specification, planning, implementation, and review workflows
+- **Agents**: PAW workflow orchestrators (`PAW.agent.md`, `PAW Review.agent.md`)
+- **Skills**: Activity and utility skills for specification, planning, implementation, and review workflows
 
 Files are installed to:
 - `~/.copilot/agents/` - Agent files

package/dist/agents/PAW-Review.agent.md

@@ -9,7 +9,7 @@ You execute the PAW Review workflow by loading the workflow skill and following
 
 
 
-Read the `skills/paw-review-workflow/SKILL.md` file to understand orchestration, principles, and artifact structure. If the file cannot be read, report the error and stop.
+Load the `paw-review-workflow` skill to understand orchestration, principles, and artifact structure. If the skill fails to load, report the error and stop.
 
 
 ## Context Detection
@@ -42,9 +42,9 @@ When cross-repository conditions are detected:
 
 
 
-Discover available review skills from `skills/paw-review-*/SKILL.md` directories, then execute each activity by delegating to a separate agent session. Each delegated agent:
-- Receives the skill file path, PR context, and artifact path
-- Reads and executes the specified skill
+Discover available review skills (`paw-review-*`) from the skills catalog, then execute each activity by delegating to a separate agent session. Each delegated agent:
+- Receives the skill name, PR context, and artifact path
+- Loads and executes the specified skill
 - Returns a completion status with artifact confirmation
 
 
@@ -83,4 +83,4 @@ If any stage fails, report the error to the user and seek guidance on how to pro
 - Load skills before executing workflow logic
 - Human authority over all posted feedback
 
-<!-- @paw-workflow/cli v0.0.1 -->
+<!-- @paw-workflow/cli v0.0.4 -->

package/dist/agents/PAW.agent.md

@@ -20,8 +20,11 @@ On first request, identify work context from environment (current branch, `.paw/
 | paw-planning | paw-plan-review | NO |
 | paw-plan-review (passes) | Planning PR (prs strategy) | NO |
 | Planning PR created | paw-transition → paw-implement | NO |
-| paw-impl-review (passes) | Push & Phase PR (prs strategy) | NO |
-| Phase PR created | paw-transition → paw-implement (next) or paw-pr | NO |
+| paw-impl-review (passes, more phases) | Push & Phase PR (prs strategy) | NO |
+| paw-impl-review (passes, last phase, review enabled) | paw-final-review | NO |
+| paw-impl-review (passes, last phase, review disabled) | paw-pr | Per Review Policy |
+| paw-final-review | paw-pr | NO |
+| Phase PR created | paw-transition → paw-implement (next) or paw-final-review or paw-pr | NO |
 
 **Skippable = NO**: Execute immediately without pausing or asking for confirmation.
 
@@ -39,6 +42,8 @@ Stage boundaries:
 - Planning PR created (PRs strategy)
 - Phase PR created (PRs strategy) or push complete (local strategy)
 - All phases complete
+- paw-final-review complete
+- paw-pr complete (Final PR created)
 
 The transition skill returns `pause_at_milestone`. If `true`, STOP and wait for user. This is how milestone pauses happen—without the transition call, you will skip pauses.
 
@@ -76,14 +81,26 @@ Use TODOs to externalize workflow steps.
 **Core rule**: After completing ANY activity, determine if you're at a stage boundary (see Stage Boundary Rule). If yes, delegate to `paw-transition` before doing anything else.
 
 **Transition response handling**:
-- `pause_at_milestone`: If `true`, PAUSE and wait for user confirmation
+- `pause_at_milestone`: If `true`, PAUSE and wait for user confirmation. Applies at every phase boundary, including before entering candidate promotion and after each promoted phase.
 - `artifact_tracking`: Pass to next activity (if `disabled`, don't stage `.paw/` files)
 - `preflight`: Report blocker if not `passed`
+- `promotion_pending`: If `true` **and not paused**, run Candidate Promotion Flow (see below)
 
 
 - `session_action`: Ignored in CLI (single-session mode)
 
 
+### Candidate Promotion Flow
+
+When `paw-transition` returns `promotion_pending = true` with a `candidates` list:
+
+1. Present each candidate to user with options: **Promote**, **Skip**, **Defer**
+2. For each decision:
+   - **Promote**: Update candidate to `- [x] [promoted] <desc>` in ImplementationPlan.md. Run `paw-code-research` + `paw-planning` to elaborate into a full phase, then follow standard mandatory transitions (plan-review → implement → impl-review). If research reveals infeasibility, update to `- [x] [not feasible] <desc>` and continue with remaining candidates. User may request a lightweight promote (skip plan-review) for trivial changes.
+   - **Skip**: Update candidate to `- [x] [skipped] <desc>` in ImplementationPlan.md
+   - **Defer**: Update candidate to `- [x] [deferred] <desc>` in ImplementationPlan.md
+3. After all candidates resolved: proceed to `paw-pr`
+
 ## Before Yielding Control
 
 When **stopping work or pausing the workflow**, verify:
@@ -126,8 +143,8 @@ When pausing at a milestone, provide:
 ## Hybrid Execution Model
 
 **Direct execution** (load skill, execute in this session):
-- `paw-spec`, `paw-planning`, `paw-implement`, `paw-pr`
-- `paw-init`, `paw-status`, `paw-work-shaping`
+- `paw-spec`, `paw-planning`, `paw-implement`, `paw-pr`, `paw-final-review`
+- `paw-init`, `paw-status`, `paw-work-shaping`, `paw-rewind`
 
 **Subagent delegation** (delegate via `runSubagent`):
 - `paw-spec-research`, `paw-code-research`, `paw-spec-review`, `paw-plan-review`, `paw-impl-review`
@@ -138,6 +155,7 @@ When pausing at a milestone, provide:
 - After Planning PR created: **Delegate to `paw-transition`** (this is a stage boundary)
 - After `paw-impl-review` returns PASS: Load `paw-git-operations`, push/create PR
 - After Phase PR created or push complete: **Delegate to `paw-transition`** (this is a stage boundary)
+- After `paw-final-review` completes: **Delegate to `paw-transition`** (this is a stage boundary)
 - After any review subagent: Check result, handle accordingly, then `paw-transition` if at stage boundary
 
 ### Work Shaping Detection
@@ -163,9 +181,10 @@ For each user request:
 - PR comment responses → `paw-review-response`
 - Documentation conventions → `paw-docs-guidance`
 - Status/help → `paw-status`
+- Workflow rollback → `paw-rewind`
 
 ## Error Handling
 
 If any activity fails, report the error to the user and seek guidance.
 
-<!-- @paw-workflow/cli v0.0.1 -->
+<!-- @paw-workflow/cli v0.0.4 -->

package/dist/skills/paw-code-research/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-code-research
 description: Code research activity skill for PAW workflow. Documents implementation details with file:line references, discovers documentation infrastructure, and creates CodeResearch.md artifact.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # Code Research

package/dist/skills/paw-docs-guidance/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-docs-guidance
 description: Documentation conventions for PAW implementation workflow. Provides Docs.md template structure, include/exclude guidelines, and project documentation update patterns.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # Documentation Guidance

package/dist/skills/paw-final-review/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: paw-final-review
+description: Pre-PR review activity skill for PAW workflow. Reviews implementation against spec before Final PR creation with configurable multi-model or single-model execution.
+metadata:
+  version: "0.0.4"
+---
+
+# Final Agent Review
+
+> **Execution Context**: This skill runs **directly** in the PAW session (not a subagent), preserving user interactivity for apply/skip/discuss decisions.
+
+Automated review step that runs after all implementation phases complete, before Final PR creation. Examines the full implementation diff against specification to catch issues before external review.
+
+## Capabilities
+
+- Review implementation against spec for correctness, patterns, and issues
+- Multi-model parallel review with synthesis (CLI only)
+- Single-model review (CLI and VS Code)
+- Interactive or auto-apply resolution modes
+- Generate review artifacts in `.paw/work/<work-id>/reviews/`
+
+## Procedure
+
+### Step 1: Read Configuration
+
+Read WorkflowContext.md for:
+- Work ID and target branch
+- `Final Review Mode`: `single-model` | `multi-model`
+- `Final Review Interactive`: `true` | `false`
+- `Final Review Models`: comma-separated model names (for multi-model)
+
+
+If mode is `multi-model`, parse the models list. Default: `latest GPT, latest Gemini, latest Claude Opus`.
+
+
+
+### Step 2: Gather Review Context
+
+**Required context**:
+- Full diff of implementation changes (target branch vs base branch)
+- Spec.md requirements and success criteria
+- ImplementationPlan.md phases and scope
+- CodeResearch.md patterns and conventions
+
+**Generate diff**:
+```bash
+git diff <base-branch>...<target-branch>
+```
+
+### Step 3: Create Reviews Directory
+
+Create `.paw/work/<work-id>/reviews/` if it doesn't exist.
+Create `.paw/work/<work-id>/reviews/.gitignore` with content `*` (if not already present).
+
+### Review Prompt (shared)
+
+Use this prompt for all review executions (single-model or each multi-model subagent):
+
+```
+Review this implementation against the specification. Be critical and thorough.
+
+## Specification
+[Include Spec.md content]
+
+## Implementation Diff
+[Include full diff]
+
+## Codebase Patterns
+[Include relevant patterns from CodeResearch.md]
+
+## Review Criteria
+1. **Correctness**: Do changes implement all spec requirements? Any gaps?
+2. **Pattern Consistency**: Does implementation follow established codebase patterns?
+3. **Bugs and Issues**: Logic errors, edge cases, race conditions, error handling gaps
+4. **Token Efficiency**: For prompts/skills, opportunities to reduce verbosity
+5. **Documentation**: Missing or outdated documentation
+
+For each finding, provide:
+- Issue description
+- Current code/text
+- Proposed fix
+- Severity: must-fix | should-fix | consider
+
+Write findings in structured markdown.
+```
+
+
+### Step 4: Execute Review (CLI)
+
+**If single-model mode**:
+- Execute review using the prompt above
+- Save to `REVIEW.md`
+
+**If multi-model mode**:
+
+First, resolve model intents to actual model names (e.g., "latest GPT" → current GPT model).
+
+**If Interactive = true**: Present the resolved models for confirmation:
+```
+About to run multi-model review with:
+- [resolved model 1]
+- [resolved model 2]
+- [resolved model 3]
+
+Proceed with these models, or specify different ones?
+```
+Allow user to confirm or provide alternative model list.
+
+Then spawn parallel subagents using `task` tool with `model` parameter for each model. Each subagent receives the review prompt above. Save per-model reviews to `REVIEW-{MODEL}.md`.
+
+**After multi-model reviews complete**, generate synthesis.
+
+**Important**: If any findings involve interface changes, API modifications, or data flow updates, populate the Verification Checklist with specific components that need coordinated updates. This prevents half-fixes where only one side of an interface is updated.
+
+**REVIEW-SYNTHESIS.md structure**:
+```markdown
+# Review Synthesis
+
+**Date**: [date]
+**Reviewers**: [model list]
+**Changes**: [branch/diff reference]
+
+## Consensus Issues (All Models Agree)
+[Highest priority - all models flagged these]
+
+## Partial Agreement (2+ Models)
+[High priority - multiple models flagged]
+
+## Single-Model Insights
+[Unique findings worth considering]
+
+## Verification Checklist
+[Populate with specific touchpoints for interface/data-flow changes]
+- [ ] [Component A] updated
+- [ ] [Component B] updated  
+- [ ] Data flows end-to-end from [source] → [target]
+
+## Priority Actions
+### Must Fix
+[Critical issues]
+
+### Should Fix
+[High-value improvements]
+
+### Consider
+[Nice-to-haves]
+```
+
+
+
+
+### Step 5: Resolution
+
+**If no findings**: Report clean review and proceed.
+
+**If Interactive = true**:
+
+Present each finding to user:
+```
+## Finding #N: [Title]
+
+**Severity**: [must-fix | should-fix | consider]
+**Issue**: [Description]
+
+**Current**:
+[Show current code/text]
+
+**Proposed**:
+[Show proposed change]
+
+**My Opinion**: [Rationale]
+
+---
+
+**Your call**: apply, skip, or discuss?
+```
+
+Track status for each finding:
+- `applied` - Change made to codebase
+- `skipped` - User chose not to apply
+- `discussed` - Modified based on discussion, then applied or skipped
+
+
+For multi-model mode, process synthesis first (consensus → partial → single-model). Track cross-finding duplicates to avoid re-presenting already-addressed issues.
+
+
+**If Interactive = false**:
+
+Auto-apply all findings marked `must-fix` and `should-fix`. Skip `consider` items. Report what was applied.
+
+### Step 6: Completion
+
+**Report back**:
+- Total findings count
+- Applied / skipped / discussed counts
+- Summary of key changes made
+- Review artifacts location
+- Status: `complete` (ready for paw-pr)
+
+**Edge cases**:
+- Empty diff → Report "no implementation changes to review", proceed to paw-pr
+- All findings skipped → Proceed to paw-pr (user's choice respected)
+
+## Review Artifacts
+
+| Mode | Files Created |
+|------|---------------|
+| single-model | `REVIEW.md` |
+| multi-model | `REVIEW-{MODEL}.md` per model, `REVIEW-SYNTHESIS.md` |
+
+Location: `.paw/work/<work-id>/reviews/`
+All files gitignored via `.gitignore` with `*` pattern.

package/dist/skills/paw-git-operations/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-git-operations
 description: Shared git mechanics for PAW activity skills including branch naming conventions, strategy-based branching logic, and selective staging discipline.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # Git Operations

package/dist/skills/paw-impl-review/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-impl-review
 description: Implementation review activity skill for PAW workflow. Reviews implementation for quality, adds documentation, and returns structured verdict.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # Implementation Review

package/dist/skills/paw-implement/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-implement
 description: Implementation activity skill for PAW workflow. Executes plan phases with code changes, documentation phases, and PR review comment handling. One phase per invocation.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # Implementation
@@ -29,6 +29,7 @@ Execute implementation plan phases by making code changes, running verification,
 - Execute documentation phases (create/update Docs.md, update project documentation)
 - Address PR review comments on implementation work (load `paw-review-response` for mechanics)
 - Handle non-linear requests (e.g., "adjust implementation to match updated spec") when delegated by PAW agent
+- Capture phase candidates mid-implementation for later elaboration
 
 ## Role: Forward Momentum
 
@@ -128,6 +129,15 @@ If the plan has existing checkmarks:
 - Limit edits to sections affected by current phase
 - Re-running same phase should produce no additional plan changes
 
+### Capturing Phase Candidates
+
+When related work surfaces during implementation (e.g., "this would be cleaner if we also refactored X"):
+1. If `## Phase Candidates` section missing, create it after `## Phase Status`
+2. Append `- [ ] Brief description of potential work`
+3. Continue current phase immediately—no context-switch
+
+Candidates are elaborated into full phases later via the promotion flow in `paw-transition`.
+
 ## Quality Checklist
 
 ### Initial Phase Implementation

package/dist/skills/paw-init/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-init
 description: Bootstrap skill for PAW workflow initialization. Creates WorkflowContext.md, directory structure, and git branch. Runs before workflow skill is loaded.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # PAW Initialization
@@ -25,6 +25,7 @@ Bootstrap skill that initializes the PAW workflow directory structure. This runs
 
 | Parameter | Required | Default | Values |
 |-----------|----------|---------|--------|
+| `base_branch` | No | `main` | branch name |
 | `target_branch` | No | auto-derive from work ID | branch name |
 | `workflow_mode` | No | `full` | `full`, `minimal`, `custom` |
 | `review_strategy` | No | `prs` (`local` if minimal) | `prs`, `local` |
@@ -34,13 +35,18 @@ Bootstrap skill that initializes the PAW workflow directory structure. This runs
 | `issue_url` | No | none | URL |
 | `custom_instructions` | Conditional | — | text (required if `workflow_mode` is `custom`) |
 | `work_description` | No | none | text |
+| `final_agent_review` | No | `enabled` | `enabled`, `disabled` |
+| `final_review_mode` | No | `multi-model` | `single-model`, `multi-model` |
+| `final_review_interactive` | No | `true` | boolean |
+| `final_review_models` | No | `latest GPT, latest Gemini, latest Claude Opus` | comma-separated model names or intents |
 
 ### Handling Missing Parameters
 
 When parameters are not provided:
 1. Apply defaults from the table above
-2. **Present configuration summary** and ask for confirmation before proceeding
-3. If user requests changes, update values and re-confirm
+2. Check user-level defaults in `copilot-instructions.md` or `AGENTS.md` (these override table defaults)
+3. **Present configuration summary** and ask for confirmation before proceeding
+4. If user requests changes, update values and re-confirm
 
 This mirrors the VS Code command flow which prompts sequentially but allows skipping with defaults.
 
@@ -77,11 +83,16 @@ Created at `.paw/work/<work-id>/WorkflowContext.md` with all input parameters:
 
 Work Title: <generated_work_title>
 Work ID: <generated_work_id>
+Base Branch: <base_branch>
 Target Branch: <target_branch>
 Workflow Mode: <workflow_mode>
 Review Strategy: <review_strategy>
 Review Policy: <review_policy>
 Session Policy: <session_policy>
+Final Agent Review: <final_agent_review>
+Final Review Mode: <final_review_mode>
+Final Review Interactive: <final_review_interactive>
+Final Review Models: <final_review_models>
 Custom Workflow Instructions: <custom_instructions or "none">
 Initial Prompt: <work_description or "none">
 Issue URL: <issue_url or "none">
@@ -93,6 +104,13 @@ Additional Inputs: none
 ### Git Branch
 > Branch creation and checkout follows `paw-git-operations` patterns.
 
+**Branch creation sequence** (REQUIRED):
+1. Checkout base branch: `git checkout <base_branch>`
+2. Update base: `git pull origin <base_branch> --ff-only`
+3. Create feature branch: `git checkout -b <target_branch>`
+
+Never create feature branch from current HEAD without explicit checkout of base.
+
 - Target branch exists and is checked out
 - If explicit branch provided: use as-is (prompt if exists)
 - If auto-derive: `feature/<work-id>`

package/dist/skills/paw-plan-review/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-plan-review
 description: Plan review activity skill for PAW workflow. Reviews implementation plans for feasibility, completeness, and spec alignment before implementation proceeds.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # Plan Review

package/dist/skills/paw-planning/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-planning
 description: Implementation planning activity skill for PAW workflow. Creates phased implementation plans with clear success criteria, documentation phase planning, and strategic architectural descriptions.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # Implementation Planning
@@ -97,6 +97,10 @@ Save to: `.paw/work/<work-id>/ImplementationPlan.md`
 - [ ] **Phase 2: [Name]** - [Objective]
 - [ ] **Phase N: Documentation** - [If warranted]
 
+## Phase Candidates
+<!-- Lightweight capture of potential phases identified during implementation.
+     Add one-liner descriptions here; elaborate into full phases later via promotion. -->
+
 ---
 
 ## Phase 1: [Name]
@@ -190,6 +194,7 @@ When revising based on paw-plan-review feedback:
 - [ ] Code blocks absent or limited to <10 lines for architectural concepts
 - [ ] Documentation phase included (or explicitly omitted with reason)
 - [ ] Phase Status exists with checkbox phases and one-sentence objectives
+- [ ] Phase Candidates section present (may be empty initially)
 
 ## Completion Response
 

package/dist/skills/paw-pr/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: paw-pr
-description: Final PR activity skill for PAW workflow. Creates comprehensive final PR to main with pre-flight validation, scaled descriptions, and merge guidance.
+description: Final PR activity skill for PAW workflow. Creates comprehensive final PR to base branch with pre-flight validation, scaled descriptions, and merge guidance.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # Final PR
 
 > **Execution Context**: This skill runs **directly** in the PAW session (not a subagent), allowing user interaction for PR description and final checks.
 
-Create the final PR merging all implementation work to main branch after pre-flight validation.
+Create the final PR merging all implementation work to the base branch (from WorkflowContext.md) after pre-flight validation.
 
 > **Reference**: Follow Core Implementation Principles from `paw-workflow` skill.
 
@@ -30,6 +30,7 @@ Before creating the PR, verify and report status. Block on failures unless user
 - All phases in ImplementationPlan.md marked complete
 - All phase PRs merged (prs strategy) or commits pushed (local strategy)
 - Target branch exists with implementation commits
+- No unresolved phase candidates (`- [ ]` items in `## Phase Candidates`)
 
 **Artifacts Exist** (check existence per Workflow Mode):
 - CodeResearch.md (required: all modes)
@@ -39,7 +40,7 @@ Before creating the PR, verify and report status. Block on failures unless user
 - Docs.md (required: full mode; optional: minimal/custom)
 
 **Branch Status**:
-- Target branch up to date with base branch (main)
+- Target branch up to date with base branch (from WorkflowContext.md, defaults to `main`)
 - No merge conflicts
 
 **Build/Tests**:
@@ -117,8 +118,8 @@ When no intermediate PRs:
 ## PR Creation
 
 **Final PR context requirements**:
-- Source: `<target_branch>`
-- Target: `main` (or specified base branch)
+- Source: `<target_branch>` (from WorkflowContext.md)
+- Target: `<base_branch>` (from WorkflowContext.md, defaults to `main`)
 - Title format: `[<Work Title>] <description>`
 - Body: Scaled description per formats above
 - Issue linking: Include Issue URL from WorkflowContext.md

package/dist/skills/paw-review-baseline/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-review-baseline
 description: Analyzes the codebase at the PR's base commit to establish baseline understanding for review comparison.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # Baseline Research Activity Skill

package/dist/skills/paw-review-correlation/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-review-correlation
 description: Synthesizes findings across multiple PRs to identify cross-repository dependencies, interface mismatches, and coordination gaps.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # Cross-Repository Correlation Analysis Skill

package/dist/skills/paw-review-critic/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-review-critic
 description: Critically assesses generated review comments for usefulness, accuracy, and appropriateness, adding assessment sections.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # PAW Review Critic Skill

package/dist/skills/paw-review-feedback/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-review-feedback
 description: Transforms gap analysis findings into structured review comments with comprehensive rationale. Handles both initial draft generation and critique response iteration.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # PAW Review Feedback Skill

package/dist/skills/paw-review-gap/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-review-gap
 description: Systematically identifies gaps in correctness, safety, testing, and maintainability, categorizing findings by severity.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # Gap Analysis Activity Skill

package/dist/skills/paw-review-github/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-review-github
 description: Posts finalized review comments to GitHub as a pending review after critique iteration is complete.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
   type: activity
   artifacts: none
   updates: ReviewComments.md

package/dist/skills/paw-review-impact/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-review-impact
 description: Analyzes system-wide impact of PR changes including integration effects, breaking changes, performance, and security implications.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # Impact Analysis Activity Skill

package/dist/skills/paw-review-response/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-review-response
 description: Shared PR review comment response mechanics for PAW activity skills. Provides TODO workflow, commit patterns, and reply format for addressing reviewer feedback.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # Review Response

package/dist/skills/paw-review-understanding/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-review-understanding
 description: Analyzes PR changes to create ReviewContext.md and DerivedSpec.md artifacts. Handles both initial analysis and resumption after baseline research.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # Understanding Activity Skill
@@ -91,9 +91,11 @@ related_prs:
    - **GitHub**: Use GitHub tools to retrieve PR details (number, title, author, state, description, labels, reviewers, CI status, changed files)
    - **Non-GitHub**: Use git to determine commits and changed files between base and head
 
-3. **Resolve Base Commit** (Non-GitHub only):
-   - Prefer the remote tracking branch reference
-   - Record source (remote|local|github-api) in ReviewContext.md
+3. **Resolve Base Commit**:
+   - **GitHub**: Use `base.sha` from PR metadata (GitHub returns the merge-base)
+   - **Non-GitHub**: Run `git merge-base <head-branch> origin/<base-branch>` to find common ancestor
+   - **CRITICAL**: The base commit must be the merge-base (common ancestor), NOT the current tip of the base branch. Using the tip causes files added to main after branching to appear as "deletions."
+   - Record in ReviewContext.md: `Base Commit: <sha>` and `Base Commit Source: github-api | merge-base`
 
 4. **Create ReviewContext.md**:
    - Write to `.paw/reviews/<identifier>/ReviewContext.md`

package/dist/skills/paw-review-workflow/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-review-workflow
 description: Orchestrates the PAW Review workflow, coordinating activity skills to analyze PRs and generate comprehensive review feedback.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # PAW Review Workflow Skill
@@ -71,11 +71,11 @@ Activity skills are executed via delegated agent sessions.
 
 
 
-1. Read the skill file at `skills/paw-review-<skill-name>/SKILL.md`
+1. Load the skill by name (e.g., `paw-review-understanding`)
 2. Read and internalize the skill instructions
 3. Only then begin executing the activity
 
-**Delegation prompt must include**: "First read your skill from `skills/paw-review-<skill-name>/SKILL.md`, then execute the activity."
+**Delegation prompt must include**: "First load the `paw-review-<skill-name>` skill, then execute the activity."
 
 
 ### Response Format

package/dist/skills/paw-rewind/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: paw-rewind
+description: Workflow rewind utility skill for PAW workflow. Rolls back workflow state to a previous stage or phase with safeguards and user confirmation.
+metadata:
+  version: "0.0.4"
+---
+
+# Workflow Rewind
+
+> **Execution Context**: This skill runs **directly** in the PAW session (not a subagent)—requires user interaction for confirmation prompts.
+
+Roll back workflow state to a previous stage or phase. Handles safeguard checks, action preview, and git reset upon user confirmation.
+
+> **Reference**: Follow Core Implementation Principles from `paw-workflow` skill.
+
+## Capabilities
+
+- Parse rewind target from natural language (spec, planning, phase N, start)
+- Detect current workflow state using `paw-status` patterns
+- Identify target commit for rewind point
+- Check safeguards (uncommitted changes, unpushed commits, orphaned PRs)
+- Present itemized action preview grouped by category
+- Execute rewind via git reset on user confirmation
+- Close orphaned PRs (PRs strategy) with explanatory comment
+
+## Rewind Targets
+
+| Target | Description | Resets to |
+|--------|-------------|-----------|
+| `start` | Reset to initialization | After WorkflowContext.md created |
+| `spec` | Reset to post-specification | After Spec.md created (full mode only) |
+| `planning` | Reset to post-research | After CodeResearch.md created |
+| `phase N` | Reset to post-phase N | After Phase N completed |
+
+**Target aliases**: "go back to spec", "rewind to planning", "reset to phase 2", "roll back to start"
+
+## Procedure
+
+### 1. Parse Rewind Target
+
+Map user request to target:
+- "spec", "specification" → `spec`
+- "planning", "plan", "research" → `planning`
+- "phase 1", "phase one", "p1" → `phase 1`
+- "start", "beginning", "init" → `start`
+
+If target unclear, ask user to clarify with available options.
+
+### 2. Validate Target
+
+Check target is reachable from current state:
+- `spec` requires full mode (minimal mode has no spec stage)
+- `phase N` requires ImplementationPlan.md with at least N phases
+- Target must be before current stage (can't rewind forward)
+
+If invalid, report error with available rewind targets.
+
+### 3. Detect Current State
+
+Use `paw-status` patterns to determine:
+- WorkflowContext.md for configuration (mode, strategy)
+- Current stage from artifact existence
+- Phase progress from ImplementationPlan.md
+- Git branch and status
+
+### 4. Identify Target Commit
+
+Find the commit representing the rewind point:
+
+```bash
+# Find commit where artifact was added
+git log --oneline --diff-filter=A -- .paw/work/<work-id>/<artifact> | head -1
+```
+
+| Target | Artifact to search |
+|--------|-------------------|
+| `start` | WorkflowContext.md |
+| `spec` | Spec.md |
+| `planning` | CodeResearch.md |
+| `phase N` | Search for phase completion commit message pattern |
+
+For phase targets, search commit messages:
+```bash
+git log --oneline --grep="Phase N" --grep="phase N" | head -1
+```
+
+If target commit not found, report error with available recovery options.
+
+### 5. Safeguard Checks
+
+Before any destructive action, check and warn about:
+
+**Uncommitted changes**:
+```bash
+git status --porcelain
+```
+If non-empty, list files and require confirmation.
+
+**Unpushed commits**:
+```bash
+git rev-list @{u}..HEAD --count
+```
+If upstream not set, treat as 0 unpushed. If > 0, report count and require confirmation.
+
+**Orphaned PRs** (PRs strategy only):
+Query PRs with head branches matching `<target>_phase*` patterns that would be orphaned by rewind. List PR numbers/URLs.
+
+### 6. Action Preview
+
+Present itemized preview grouped by category:
+
+```
+Rewind to: planning (after CodeResearch.md)
+Target commit: abc1234
+
+Actions to be performed:
+
+📁 Git Reset:
+   - Reset to commit abc1234
+   - Removes: ImplementationPlan.md, all phase changes
+
+🔗 PRs to Close (PRs strategy):
+   - #42: [Feature] Phase 1 implementation
+   - #43: [Feature] Phase 2 implementation
+
+⚠️ Warnings:
+   - 3 uncommitted files will be discarded
+   - 5 unpushed commits will be removed
+
+Continue with rewind? [yes/no]
+```
+
+### 7. Execute Rewind
+
+On user confirmation:
+
+1. **Close orphaned PRs** (PRs strategy):
+   - Close each PR with comment: "Workflow rewound to {target}. This PR is no longer applicable."
+   - If close fails, prompt user to close manually with direct link
+
+2. **Git reset**:
+   ```bash
+   git reset --hard <target-commit>
+   ```
+
+3. **Report completion**:
+   - What was reverted
+   - Current state after rewind
+   - Recommended next step
+
+### 8. Cancellation
+
+If user declines confirmation:
+- Report "Rewind cancelled. No changes made."
+- Workflow continues at current state
+
+## Edge Cases
+
+**Already at target**: Report "Already at {target} stage. No rewind needed." and exit.
+
+**Minimal mode + spec target**: Report error: "Spec stage not available in minimal workflow mode. Available targets: planning, start"
+
+**No commit found**: Report error with manual recovery guidance: "Could not identify target commit. You may need to manually reset using `git log` to find the appropriate commit."
+
+**PR close fails**: Prompt user: "Could not close PR #42 automatically. Please close manually: {url}"
+
+## Guardrails
+
+- Never execute destructive operations without explicit user confirmation
+- Never rewind without showing action preview first
+- Never assume commit exists—always verify
+- Never modify files outside of git reset operation
+- Be idempotent: cancelled rewind leaves state unchanged
+
+## Completion Response
+
+Report:
+- Rewind status (completed/cancelled/error)
+- If completed: target reached, commit hash, files reverted
+- Current workflow stage after rewind
+- Recommended next action
+- Any manual steps required (e.g., PRs to close manually)

package/dist/skills/paw-spec/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-spec
 description: Specification activity skill for PAW workflow. Converts issue/brief into structured feature specification with user stories, requirements, and success criteria.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # Specification

package/dist/skills/paw-spec-research/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-spec-research
 description: Spec research activity skill for PAW workflow. Answers factual questions about existing system behavior to inform specification writing.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # Spec Research

package/dist/skills/paw-spec-review/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-spec-review
 description: Specification review skill for PAW workflow. Validates Spec.md against quality criteria and returns structured feedback for iteration.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # Spec Review

package/dist/skills/paw-status/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-status
 description: Workflow status activity skill for PAW workflow. Diagnoses workflow state, recommends next steps, explains PAW process, and optionally posts updates to Issues/PRs.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # Workflow Status
@@ -35,9 +35,18 @@ Check `.paw/work/<work-id>/` for:
 - CodeResearch.md (research stage)
 - ImplementationPlan.md (planning stage)
 - Docs.md (documentation if separate from implementation)
+- `reviews/` directory (Final Agent Review artifacts)
 
 Note existence vs intentionally skipped (minimal mode skips Spec/Docs).
 
+### Configuration Detection
+
+Read WorkflowContext.md for:
+- Workflow Mode, Review Strategy, Review Policy
+- Final Agent Review: `enabled` | `disabled`
+- Final Review Mode: `single-model` | `multi-model`
+- Final Review Interactive: `true` | `false`
+
 ### Phase Counting
 
 Parse ImplementationPlan.md with regex: `^## Phase \d+:`
@@ -45,6 +54,12 @@ Parse ImplementationPlan.md with regex: `^## Phase \d+:`
 - Report: "Phase N of M" or "Phase N (plan shows M phases total)"
 - Never assume total—always verify
 
+### Phase Candidates
+
+Check `## Phase Candidates` section in ImplementationPlan.md:
+- Count unresolved (`- [ ]`), promoted (`[promoted]`), skipped (`[skipped]`), deferred (`[deferred]`), not feasible (`[not feasible]`)
+- If unresolved exist after last phase: report "N phase candidates pending review"
+
 ### Git Status
 
 Determine:
@@ -80,15 +95,18 @@ Map state to guidance:
 | CodeResearch.md exists, no Plan | "Create plan: `plan`" |
 | Plan exists, no phase work | "Begin Phase 1: `implement`" |
 | Phase N complete, Phase N+1 exists | "Continue Phase N+1: `implement`" |
-| All complete | "Create final PR: `pr`" |
+| All phases complete, review enabled, no reviews/ | "Run final review: `final-review`" |
+| All phases complete, reviews/ exists | "Create final PR: `pr`" |
+| All phases complete, review disabled | "Create final PR: `pr`" |
+| All complete + unresolved candidates | "Review phase candidates before PR" |
 
 ## Workflow Mode Behavior
 
 ### Full Mode
-Expect: Spec → Spec Research (optional) → Code Research → Plan → Implementation (multi-phase) → Docs → Final PR
+Expect: Spec → Spec Research (optional) → Code Research → Plan → Implementation (multi-phase, including Documentation phase) → Final Review (if enabled) → Final PR
 
 ### Minimal Mode
-Expect: Code Research → Plan → Implementation (single phase) → Final PR
+Expect: Code Research → Plan → Implementation (including Documentation phase) → Final Review (if enabled) → Final PR
 Skips: Spec, Spec Research (local strategy enforced)
 
 ### Custom Mode
@@ -139,6 +157,7 @@ For "How do I start?", explain:
 Synthesize findings into sections:
 - **Artifacts**: Existence and status
 - **Phases**: Current progress (N of M)
+- **Phase Candidates**: Pending/resolved candidate counts (if any exist)
 - **Branch & Git**: Current state, divergence
 - **PRs**: Open/merged status, review comments
 - **Next Actions**: Recommended commands

package/dist/skills/paw-transition/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-transition
 description: Workflow transition gate for PAW. Handles stage boundaries, session policy, preflight checks, and next activity determination.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # Workflow Transition
@@ -30,6 +30,8 @@ Read WorkflowContext.md to determine:
 - 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`
+- Final Agent Review (`enabled` | `disabled`)
+  - If missing, default to `enabled`
 
 Identify last completed activity from TODOs or artifacts.
 
@@ -43,27 +45,51 @@ Use the Mandatory Transitions table:
 | paw-implement (any phase) | paw-impl-review | NO |
 | paw-spec | paw-spec-review | NO |
 | paw-planning | paw-plan-review | NO |
-| paw-impl-review (passes) | paw-implement (next phase) or paw-pr | Per Review Policy |
+| paw-impl-review (passes, more phases) | paw-implement (next phase) | NO |
+| paw-impl-review (passes, last phase, review enabled) | paw-final-review | NO |
+| paw-impl-review (passes, last phase, review disabled) | paw-pr | Per Review Policy |
+| paw-final-review | paw-pr | NO |
 
 **Skippable = NO**: Add activity TODO and execute immediately after transition completes.
 
+### Step 2.5: Candidate Promotion Check
+
+When next activity would be `paw-pr` (all planned phases complete), check for phase candidates:
+
+1. Read ImplementationPlan.md `## Phase Candidates` section
+2. Count **unresolved** candidates: `- [ ]` items WITHOUT terminal tags (`[skipped]`, `[deferred]`, `[not feasible]`)
+3. If unresolved candidates exist: set `promotion_pending = true` and extract candidate descriptions
+4. Otherwise: set `promotion_pending = false`
+
+If `promotion_pending = true`, return candidates in structured output. PAW orchestrator handles user interaction.
+
 ### 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
+- all phases complete → paw-final-review (if enabled) or paw-pr (if disabled)
+- paw-final-review complete → paw-pr
+- paw-pr complete → workflow complete
+
+**Stage-to-milestone mapping** (determines which milestone is reached at each boundary):
 
-**Milestones** (require pause check): Spec.md complete, ImplementationPlan.md complete, Phase PR completion, Final PR
+| Stage Boundary | Milestone Reached |
+|----------------|-------------------|
+| spec-review passes | Spec.md complete |
+| plan-review passes | ImplementationPlan.md complete |
+| phase N complete (not last) | Phase completion |
+| all phases complete | Phase completion (last phase) |
+| paw-final-review complete | Final Review complete |
+| paw-pr complete | Final PR |
 
 **Determine pause_at_milestone**:
-- If at a milestone AND Review Policy ∈ {`always`, `milestones`}: set `pause_at_milestone = true`
+- If Review Policy ∈ {`always`, `milestones`}: pause at ALL milestones
 - If Review Policy = `planning-only`:
-  - If milestone is Spec.md, ImplementationPlan.md, or Final PR: set `pause_at_milestone = true`
-  - If milestone is Phase PR/phase completion: set `pause_at_milestone = false`
-- If Review Policy = `never`: set `pause_at_milestone = false`
-- If not at a milestone: set `pause_at_milestone = false`
+  - 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`
@@ -86,8 +112,13 @@ Before the next activity can start, verify:
 **For paw-code-research**:
 - [ ] Spec.md exists (unless minimal mode)
 
+**For paw-final-review**:
+- [ ] All implementation phases complete
+- [ ] On target branch (local strategy) or phase branches merged (prs strategy)
+
 **For paw-pr**:
 - [ ] All phases complete
+- [ ] paw-final-review complete (if enabled) or skipped (if disabled)
 - [ ] On target branch or ready to merge
 
 **Artifact Tracking Check** (for all activities):
@@ -116,6 +147,8 @@ TRANSITION RESULT:
 - preflight: [passed | blocked: <reason>]
 - work_id: [current work ID]
 - inline_instruction: [for new_session only: resume hint]
+- promotion_pending: [true | false] (only when next would be paw-pr)
+- candidates: [list of unresolved candidate descriptions] (only if promotion_pending)
 ```
 
 **If pause_at_milestone = true**: The PAW agent must PAUSE and wait for user confirmation before proceeding.
@@ -126,6 +159,16 @@ TRANSITION RESULT:
 
 Mark the `paw-transition` TODO complete after returning this output.
 
+## Candidate Resolution Markers
+
+Terminal markers used in Step 2.5 to identify resolved candidates:
+- `- [x] [promoted] <desc>` — Elaborated into a full phase
+- `- [x] [skipped] <desc>` — User chose not to pursue
+- `- [x] [deferred] <desc>` — Future work outside current workflow
+- `- [x] [not feasible] <desc>` — Code research revealed infeasibility
+
+Unresolved: `- [ ]` items without terminal tags. Empty section or all-resolved → `promotion_pending = false`.
+
 ## Guardrails
 
 - Do NOT skip the stage boundary check (Step 3)

package/dist/skills/paw-work-shaping/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-work-shaping
 description: Interactive pre-spec ideation utility skill. Agent-led Q&A to progressively clarify vague ideas, research codebase context, and produce structured WorkShaping.md artifact.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # Work Shaping

package/dist/skills/paw-workflow/SKILL.md

@@ -2,7 +2,7 @@
 name: paw-workflow
 description: Reference documentation for PAW multi-phase implementation workflows. Provides activity tables, artifact structure, stage guidance, and PR routing patterns. Workflow enforcement rules are in PAW.agent.md.
 metadata:
-  version: "0.0.1"
+  version: "0.0.4"
 ---
 
 # PAW Implementation Workflow Skill
@@ -66,6 +66,7 @@ Humans have final authority over all workflow decisions:
 | `paw-plan-review` | Review plan for feasibility, spec alignment | Review feedback |
 | `paw-implement` | Execute plan phases, make code changes | Code files, Docs.md |
 | `paw-impl-review` | Review implementation quality, return verdict | Review feedback |
+| `paw-final-review` | Pre-PR review with multi-model or single-model | REVIEW*.md in reviews/ |
 | `paw-pr` | Pre-flight validation, create final PR | Final PR |
 
 **Note**: Phase PR creation is handled by PAW agent (using `paw-git-operations`) after `paw-impl-review` passes.
@@ -85,7 +86,11 @@ All implementation artifacts are stored in a consistent directory structure:
 ├── CodeResearch.md         # Implementation details with file:line refs
 ├── ImplementationPlan.md   # Phased implementation plan
 ├── Docs.md                 # Technical documentation (created during final implementation phase)
-└── prompts/                # Generated prompt files (optional)
+├── prompts/                # Generated prompt files (optional)
+└── reviews/                # Final Agent Review artifacts (gitignored)
+    ├── REVIEW.md           # Single-model review
+    ├── REVIEW-{MODEL}.md   # Per-model reviews (multi-model)
+    └── REVIEW-SYNTHESIS.md # Synthesis (multi-model)
 ```
 
 **Work ID Derivation**: Normalized from Work Title, lowercase with hyphens (e.g., "Auth System" → "auth-system").
@@ -110,8 +115,14 @@ Per phase in ImplementationPlan.md:
 2. `paw-impl-review`: Review changes (returns verdict)
 3. Phase PR created (PRs strategy) or push (local strategy)
 
+**Phase Candidates**: During implementation, new ideas can be captured in the `## Phase Candidates` section of ImplementationPlan.md. When all planned phases complete, `paw-transition` returns `promotion_pending = true` if unresolved candidates exist. The orchestrator presents each candidate to the user with options: Promote (elaborate into a full phase), Skip, or Defer. Terminal markers (`[promoted]`, `[skipped]`, `[deferred]`, `[not feasible]`) resolve candidates.
+
 Final phase typically includes documentation (Docs.md, README, CHANGELOG).
 
+### Final Review Stage (if enabled)
+1. `paw-final-review`: Review full implementation against spec
+2. Interactive: apply/skip/discuss findings; Non-interactive: auto-apply
+
 ### Finalization Stage
 1. `paw-pr`: Pre-flight validation, create final PR
 
@@ -127,7 +138,7 @@ Load `paw-review-response` utility skill for comment mechanics.
 
 ## Execution Model
 
-**Direct execution**: `paw-spec`, `paw-planning`, `paw-implement`, `paw-pr`, `paw-init`, `paw-status`, `paw-work-shaping`
+**Direct execution**: `paw-spec`, `paw-planning`, `paw-implement`, `paw-final-review`, `paw-pr`, `paw-init`, `paw-status`, `paw-work-shaping`
 
 **Subagent delegation**: `paw-spec-research`, `paw-code-research`, `paw-spec-review`, `paw-plan-review`, `paw-impl-review`
 

package/lib/commands/install.js

@@ -98,6 +98,23 @@ export async function installCommand(target, flags = {}) {
   const skillCount = readdirSync(distSkillsDir, { withFileTypes: true })
     .filter(e => e.isDirectory()).length;
   
-  console.log(`\nInstalled ${agentCount} agents and ${skillCount} skills to ~/.copilot/`);
-  console.log('Manifest written to ~/.paw/copilot-cli/manifest.json');
+  console.log(`\n✓ Installed ${agentCount} agents and ${skillCount} skills to ~/.copilot/`);
+
+  if (!hasExistingFiles) {
+    console.log(`
+🚀 Quick Start
+  Start a workflow:    copilot --agent PAW
+  Review a PR:         copilot --agent PAW-Review
+  Or use /agent inside any copilot session to switch agents.
+
+💡 Try saying:
+  "I want to add a feature for..."
+  "Help me refactor the auth module"
+  "Review PR #100" (with PAW-Review agent)
+
+📦 Manage your installation:
+  npx @paw-workflow/cli list       Show installed version
+  npx @paw-workflow/cli upgrade    Check for updates
+  npx @paw-workflow/cli uninstall  Cleanly remove PAW`);
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paw-workflow/cli",
-  "version": "0.0.1",
+  "version": "0.0.4",
   "description": "CLI installer for Phased Agent Workflow (PAW) agents and skills",
   "type": "module",
   "bin": {