@paw-workflow/cli 0.0.1

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

@@ -0,0 +1,163 @@
+---
+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"
+---
+
+# Documentation Guidance
+
+## Docs.md Purpose
+
+`Docs.md` is the **authoritative technical reference** for implemented work. It serves as:
+
+- The most comprehensive documentation of what was implemented
+- A standalone technical reference for engineers
+- The source of truth for understanding how the implementation works
+- The basis for generating project-specific documentation
+- Documentation that persists as the go-to reference
+
+**Docs.md is NOT**: A list of documentation changes or a changelog.
+
+## Docs.md Template
+
+```markdown
+# [Work Title]
+
+## Overview
+
+[Comprehensive description of what was implemented, its purpose, and the problem it solves]
+
+## Architecture and Design
+
+### High-Level Architecture
+[Architectural overview, system components, data flow]
+
+### Design Decisions
+[Key design choices made during implementation and rationale]
+
+### Integration Points
+[How this implementation integrates with existing systems]
+
+## User Guide
+
+### Prerequisites
+[What users need before using this implementation]
+
+### Basic Usage
+[Step-by-step guide for common use cases with examples]
+
+### Advanced Usage
+[Complex scenarios, customization options, power-user features]
+
+## API Reference
+
+### Key Components
+[Document reusable components that other code will call]
+
+### Configuration Options
+[Available settings and their effects]
+
+## Testing
+
+### How to Test
+[How to exercise the implementation as a human user]
+
+### Edge Cases
+[Known edge cases and how they're handled]
+
+## Limitations and Future Work
+
+[Known limitations, planned improvements, out-of-scope items]
+```
+
+## What to Include
+
+Focus Docs.md on information not easily discovered from code:
+
+| Include | Why |
+|---------|-----|
+| Design decisions and rationale | Not visible in code |
+| Architecture and integration points | High-level view |
+| User-facing behavior and usage patterns | User perspective |
+| How to test/exercise as a human | Verification guidance |
+| Migration paths and compatibility | Operational knowledge |
+| Reusable components for other code | API surface |
+| Edge cases and limitations | Gotchas users should know |
+
+## What NOT to Include
+
+Avoid duplicating information already in code or other artifacts:
+
+| Exclude | Why |
+|---------|-----|
+| Code reproduction | Already in the code |
+| Every function/class | Internal details |
+| Exhaustive API docs | Over-documentation |
+| Test coverage checklists | In PRs and tests |
+| Acceptance criteria verification | In implementation artifacts |
+| Project doc updates list | In PR description |
+| Unnecessary code examples | Only when essential |
+
+## Project Documentation Updates
+
+When updating README, CHANGELOG, guides, or API docs, follow these principles:
+
+### Style Matching (CRITICAL)
+
+**STUDY FIRST**: Before updating any project documentation:
+1. Read multiple existing entries/sections
+2. Understand the style, length, and detail level
+3. Match it precisely
+
+### CHANGELOG Discipline
+
+- Create **ONE entry** for the work, not multiple sub-entries
+- Follow existing format exactly (bullet style, sentence case, etc.)
+- Group related changes into a single coherent entry
+
+**Example:**
+```markdown
+## [Unreleased]
+
+### Added
+- Skills-based architecture for implementation workflow (#164)
+```
+
+### README Discipline
+
+- Match section length and detail level of surrounding sections
+- Don't expand sections beyond the existing style
+- Keep additions proportional to the significance of the change
+
+### When Uncertain
+
+Err on the side of **LESS detail** in project docs. Docs.md contains the comprehensive detail; users can ask for more if needed.
+
+## Surgical Change Discipline
+
+- ONLY modify documentation files required to describe the completed work
+- DO NOT format or rewrite implementation code sections
+- DO NOT introduce unrelated documentation updates or cleanups
+- DO NOT remove historical context without explicit direction
+- When unsure if a change is purely documentation, pause and ask
+
+## Documentation Depth by Workflow Mode
+
+| Mode | Docs.md Depth | Project Docs |
+|------|---------------|--------------|
+| full | Comprehensive with all sections | Full updates |
+| minimal | Essential information only | Minimal updates |
+| custom | Per Custom Workflow Instructions | As specified |
+
+## Quality Checklist
+
+Before completing documentation:
+
+- [ ] Docs.md covers all sections relevant to the implementation
+- [ ] Design decisions and rationale documented
+- [ ] User-facing behavior explained with examples
+- [ ] No code reproduction or over-documentation
+- [ ] Project docs match existing style
+- [ ] CHANGELOG has single coherent entry
+- [ ] README changes proportional to significance

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

@@ -0,0 +1,196 @@
+---
+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"
+---
+
+# Git Operations
+
+## Branch Naming Conventions
+
+| Branch Type | Pattern | Example |
+|-------------|---------|---------|
+| Phase branch | `<target>_phase[N]` | `feature/auth-system_phase1` |
+| Multi-phase | `<target>_phase[M-N]` | `feature/auth-system_phase1-3` |
+| Planning branch | `<target>_plan` | `feature/auth-system_plan` |
+| Docs branch | `<target>_docs` | `feature/auth-system_docs` |
+
+**Target branch** is the feature branch from WorkflowContext.md (e.g., `feature/auth-system`).
+
+## Strategy-Based Branching Logic
+
+### PRs Strategy
+
+Create intermediate branches for each workflow stage; push and create PRs for review.
+
+**Phase work:**
+1. Check current branch: `git branch --show-current`
+2. If not on correct phase branch:
+   - Checkout target branch: `git checkout <target>`
+   - Set upstream if not set: `git branch --set-upstream-to=<remote>/<target>`
+   - Pull latest: `git pull`
+   - Create phase branch from target: `git checkout -b <target>_phase[N]`
+3. Verify: `git branch --show-current`
+4. Implement on phase branch, commit locally
+5. Push: `git push -u <remote> <target>_phase[N]`
+6. Create PR: `<target>_phase[N]` → `<target>`
+
+**Planning work:**
+1. Checkout target branch: `git checkout <target>`
+2. Set upstream if not set: `git branch --set-upstream-to=<remote>/<target>`
+3. Pull latest: `git pull`
+4. Create planning branch: `git checkout -b <target>_plan`
+5. Commit planning artifacts
+6. Push: `git push -u <remote> <target>_plan`
+7. Create PR: `<target>_plan` → `<target>`
+
+**Docs work:**
+1. Checkout target branch: `git checkout <target>`
+2. Set upstream if not set: `git branch --set-upstream-to=<remote>/<target>`
+3. Pull latest: `git pull`
+4. Create docs branch: `git checkout -b <target>_docs`
+5. Commit documentation
+6. Push: `git push -u <remote> <target>_docs`
+7. Create PR: `<target>_docs` → `<target>`
+
+### Local Strategy
+
+Work directly on target branch; no intermediate branches or PRs between stages.
+
+**All work:**
+1. Check current branch: `git branch --show-current`
+2. If not on target branch:
+   - Checkout target: `git checkout <target>`
+   - Set upstream if not set: `git branch --set-upstream-to=<remote>/<target>`
+   - Pull latest: `git pull`
+3. Verify: `git branch --show-current`
+4. Implement, commit to target branch
+5. Push: `git push <remote> <target>`
+6. Skip intermediate PR creation
+
+## Selective Staging Discipline
+
+**CRITICAL**: Never use `git add .` or `git add -A`. Always stage files explicitly.
+
+### Standard Staging
+
+```bash
+# Stage specific files
+git add <file1> <file2> <file3>
+
+# Verify staged changes before commit
+git diff --cached
+```
+
+### PAW Artifact Staging
+
+Before staging `.paw/` files, check if artifact tracking is disabled:
+
+```bash
+# Check for .gitignore in work directory
+if [ -f ".paw/work/<feature-slug>/.gitignore" ]; then
+  # Tracking disabled - skip .paw/ artifacts
+  git add <non-paw-files-only>
+else
+  # Tracking enabled - stage all changed files
+  git add <all-changed-files>
+fi
+```
+
+**Why**: Users can disable artifact tracking via `.gitignore`. Respect this by checking before staging `.paw/` files.
+
+## Branch Verification
+
+Before every commit, verify you're on the expected branch:
+
+```bash
+# Get current branch
+git branch --show-current
+
+# Expected patterns by work type:
+# - Phase work (prs): *_phase[N] or *_phase[M-N]
+# - Planning (prs): *_plan
+# - Docs (prs): *_docs
+# - Any work (local): <target> (no suffix)
+```
+
+**If on wrong branch**: STOP immediately. Do not commit. Switch to correct branch first.
+
+## Pre-Commit Checklist
+
+1. ✓ Verify current branch matches expected pattern
+2. ✓ Stage only related files (no `git add .`)
+3. ✓ Check `.paw/work/<slug>/.gitignore` before staging `.paw/` artifacts
+4. ✓ Review staged changes: `git diff --cached`
+5. ✓ Commit with descriptive message
+
+## Phase PR Creation
+
+After implementation review passes, create Phase PR (PRs strategy only).
+
+### Push and Create PR
+
+```bash
+# 1. Verify on phase branch
+git branch --show-current  # Should be <target>_phase[N]
+
+# 2. Push branch
+git push -u <remote> <target>_phase[N]
+
+# 3. Create PR via gh CLI
+gh pr create \
+  --base <target> \
+  --head <target>_phase[N] \
+  --title "[<Work Title>] Phase <N>: <description>" \
+  --body "<PR body>"
+```
+
+### PR Title Format
+
+`[<Work Title>] Phase <N>: <one-sentence description>`
+
+Example: `[Auth System] Phase 1: Add JWT token validation`
+
+### PR Body Scaling
+
+**Simple phases**:
+```
+Phase <N>: <one-sentence objective>
+
+🐾 Generated with [PAW](https://github.com/lossyrob/phased-agent-workflow)
+```
+
+**Complex phases**:
+```
+## Summary
+<Key changes and approach>
+
+## Design Decisions
+<Noteworthy decisions made>
+
+## Reviewer Notes
+<Items for reviewer attention>
+
+🐾 Generated with [PAW](https://github.com/lossyrob/phased-agent-workflow)
+```
+
+### Post-PR Actions
+
+1. Capture PR URL from `gh pr create` output
+2. Update ImplementationPlan.md with PR link in phase notes
+3. Report PR URL to user
+
+### PR Update Policy
+
+After a PR is opened, post progress updates as **PR comments**, not modifications to the PR body. PR body modifications require explicit user request.
+
+### Reply Format (PR Comments)
+
+When replying to review comments:
+
+```
+**🐾 PAW 🤖:**
+
+[What was changed and commit hash reference]
+```

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

@@ -0,0 +1,178 @@
+---
+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"
+---
+
+# Implementation Review
+
+> **Execution Context**: This skill runs in a **subagent** session, delegated by the PAW orchestrator. Return structured feedback (pass/fail + issues) to the orchestrator—do not make orchestration decisions or perform git operations.
+
+Review implementation changes for quality and maintainability. Acts as quality gate between implementation and PR creation.
+
+> **Reference**: Follow Core Implementation Principles from `paw-workflow` skill.
+
+## Capabilities
+
+- Review implementation for quality and maintainability
+- Add documentation/docstrings to implementation
+- Verify `paw-implement` addressed PR comments correctly
+- Return structured verdict (pass/fail + issues)
+
+## Role: Maintainability
+
+Focus on ensuring code is well-documented, readable, and maintainable.
+
+**Responsibilities:**
+- Review code for clarity, readability, necessity
+- Question design decisions and identify unnecessary code
+- Generate docstrings and code comments
+- Make small refactors (remove unused parameters, simplify)
+- Return structured verdict for orchestrator
+
+**Not responsibilities** (handled elsewhere):
+- Writing functional code or tests (`paw-implement`)
+- Push branches or create PRs (PAW agent / `paw-git-operations`)
+- Merging PRs (human responsibility)
+
+## Review Philosophy
+
+Act as a critical PR reviewer, not just a documentation pass:
+
+- Question whether code should exist as-is
+- Identify unused parameters, dead code, over-engineering
+- Check for code duplication across changed files
+- Verify tests exist for new functionality
+
+**Small refactors** (do yourself): Remove unused parameters, dead code, extract duplicate utilities
+**Large refactors** (coordinate): Restructuring, major changes → return `blocked` with reason, specific changes needed, and evidence (file:line references, test output)
+
+## Project Instructions Adherence
+
+Discover and enforce project-specific coding conventions from instruction files.
+
+**Discovery**: Search for instruction files at repo root and `.github/`:
+- `AGENTS.md`, `.github/AGENTS.md`
+- `.github/copilot-instructions.md`
+- `*.agent.md` in project root or `agents/` directory
+- `.cursor/rules` or similar convention files
+
+**Extract and verify**:
+- Required commands (lint, build, test) → run them, must pass
+- Coding patterns and conventions → verify in changed code
+- Project-specific standards → check adherence
+
+**Enforcement**: Non-adherence is a **blocking issue**, not a suggestion. If instructions specify a required command, failure = BLOCKED.
+
+## Desired End State
+
+After review, the PAW agent receives:
+- Pass/fail determination
+- For passing reviews: confirmation ready for PR creation (with optional polish suggestions)
+- For failing reviews: specific issues, what needs to change, and whether Implementer rework is required
+
+## Review Process
+
+### Plan Completeness Check (CRITICAL)
+
+**Before reviewing code quality**, verify the implementation covers all plan items:
+
+1. **Read ImplementationPlan.md** for the current phase
+2. **Extract all planned changes**: files to modify, features to add, components to update
+3. **Compare against actual changes**: `git diff` against the plan checklist
+4. **Flag gaps**: If the plan says "update services A, B, C" but only A and B changed → BLOCKED
+
+**This check catches partial implementations** where the agent implements some items but forgets others.
+
+### Initial Phase Review
+
+**Required context**:
+- Implementation changes via `git diff` or `git log`
+- ImplementationPlan.md requirements for comparison
+
+**Review focus**:
+- Code clarity, readability, project conventions
+- Code necessity: unused parameters, dead code, duplication
+- Tests exist and pass (REQUIRED)
+
+**Allowed improvements**:
+- Add docstrings to new functions/classes
+- Add inline comments for complex logic
+- Small refactors (remove unused parameters, simplify)
+- **Do NOT modify core functional logic**
+
+**Constraints**:
+- Commit improvements with clear messages
+- Do NOT push or create PRs (orchestrator handles this)
+
+### Review Comment Verification
+
+When reviewing Implementer's response to PR comments:
+
+**Required context**:
+- Implementer's commits present locally
+- All PR comments and threads
+
+**Verification**:
+- Review Implementer's commits against the comments
+- Run tests (REQUIRED):
+  - If tests fail due to reviewer changes → fix them
+  - If tests fail due to Implementer's code → return `blocked`
+  - If functional code changed but tests not updated → BLOCKER
+
+**Constraints**:
+- Add improvements if needed (documentation, polish)
+- Do NOT push (orchestrator handles this)
+
+## Quality Checklist
+
+- [ ] **Plan completeness verified**: All phase items from ImplementationPlan.md implemented
+- [ ] Project instruction files discovered and reviewed
+- [ ] Required commands from instructions pass (lint, build, test)
+- [ ] Changes follow documented coding conventions
+- [ ] All tests pass
+- [ ] Reviewed for code necessity and duplication
+- [ ] Docstrings added to public functions/classes
+- [ ] No modifications to core functional logic
+- [ ] Changes committed locally (not pushed)
+
+## Completion Response
+
+Return structured feedback to PAW agent:
+
+**PASS**: Implementation meets quality criteria, ready for PR
+- Confirm tests pass
+- Note any non-blocking observations
+- Commits made (documentation, polish)
+
+**BLOCKED**: Implementation needs rework
+- List blocking issues with file:line references
+- Specify what Implementer needs to change
+- Note **incomplete plan items** (e.g., "Phase 2 says update services A, B, C but only A implemented")
+- Note test failures or missing tests
+- Note violations of project instruction conventions
+
+> **After returning PASS**: The PAW orchestrator will handle push/PR creation (via `paw-git-operations`) and then invoke `paw-transition`. This skill does NOT push or create PRs—it only returns the verdict.
+
+### Response Format
+
+```
+## Review Result: [PASS|BLOCKED]
+
+### Summary
+[One-sentence summary of review outcome]
+
+### Tests
+- Status: [PASS|FAIL]
+- [Details if relevant]
+
+### Commits Made
+- [List of commits added during review, if any]
+
+### Issues Found
+[For BLOCKED only: specific issues requiring Implementer attention]
+
+### Notes for Reviewer
+[Optional: items flagged for human PR reviewer attention]
+```

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

@@ -0,0 +1,153 @@
+---
+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"
+---
+
+# Implementation
+
+> **Execution Context**: This skill runs **directly** in the PAW session (not a subagent), preserving user interactivity for course-correction during implementation.
+
+Execute implementation plan phases by making code changes, running verification, and committing locally. Operates one phase per invocation by default.
+
+> **Reference**: Follow Core Implementation Principles from `paw-workflow` skill.
+
+## Critical: Preserve Existing Changes
+
+**DO NOT modify, revert, or stage existing uncommitted changes** in the working directory. The user may have in-progress work they haven't committed yet.
+
+- Before making changes, check `git status` to understand current state
+- Only stage files YOU modified for the current phase
+- Never use `git add .` or `git add -A` (can capture unrelated changes)
+- If existing uncommitted changes conflict with plan work, report as `blocked` and ask user how to proceed
+
+## Capabilities
+
+- Execute one or more plan phases based on delegation instructions
+- Make focused code changes with appropriate verification (tests, lint) per repository norms
+- 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
+
+## Role: Forward Momentum
+
+Focus on making changes work and getting automated verification passing.
+
+**Responsibilities:**
+- Implement plan phases with functional code
+- Run automated verification (tests, linting, type checking)
+- Address PR review comments by making code changes
+- Update ImplementationPlan.md with progress
+- Commit functional changes locally
+
+**Not responsibilities** (handled by `paw-impl-review`):
+- Docstrings or code comments
+- Code formatting or style polish
+- Opening Phase PRs
+- Replying to PR review comments
+
+## Implementation Philosophy
+
+Plans are carefully designed, but reality can be messy:
+
+- Follow the plan's intent while adapting to what you find
+- Implement each phase fully before moving to the next
+- Verify your work makes sense in the broader codebase context
+- Update checkboxes in the plan as you complete sections
+
+When things don't match the plan exactly, think about why and communicate clearly. The plan is your guide, but your judgment matters too.
+
+## Blocking Behavior
+
+When plan conflicts with codebase reality or leaves critical gaps: **STOP immediately**. No TODO comments, placeholders, or speculative code. Return status `blocked` with specific blockers and what would resolve each.
+
+**Exception**: If delegation explicitly allows degraded verification for non-critical checks (e.g., flaky tests, optional linters), report as `⚠️ warning` and proceed.
+
+## Execution Contexts
+
+### Initial Phase Development
+
+**Desired end state**: Phase implemented, tests passing, changes committed locally on correct branch
+
+**Required context**:
+- Current phase requirements from ImplementationPlan.md
+- Codebase conventions and verification commands from CodeResearch.md
+- Branch state per Review Strategy (load `paw-git-operations`)
+
+**Constraints**:
+- All verification commands from CodeResearch.md must pass before committing
+- Update ImplementationPlan.md: mark phase complete in Phase Status (`- [ ]` → `- [x]`)
+- Commit locally with descriptive message
+- **DO NOT push** — `paw-impl-review` handles that
+
+### Documentation Phase Execution
+
+**Desired end state**: Docs.md created/updated, project docs updated (if warranted), docs build passing
+
+**Required context**:
+- Load `paw-docs-guidance` utility skill for templates and conventions
+- Docs build command from CodeResearch.md (if framework discovered)
+
+**Constraints**:
+- Use same branch strategy and review flow as code phases
+- Verify docs build passes before committing
+- **DO NOT push** — `paw-impl-review` handles that
+
+### PR Review Comment Response
+
+**Desired end state**: All review comments addressed with focused commits, ready for verification
+
+**Required context**:
+- PR metadata (URL or number) from delegation—if absent, return `blocked`
+- PR type determined from PR description/metadata (Phase PR vs Final PR)
+- Load `paw-review-response` for commit/reply mechanics
+- Pull latest to include any reviewer commits
+
+**Constraints**:
+- One focused commit per comment group (related comments addressed together)
+- Complete each group fully (changes + commit) before starting next
+- **DO NOT push** — `paw-impl-review` verifies and pushes
+
+## Branching and Commits
+
+> **Reference**: Load `paw-git-operations` skill for branch naming, commit mechanics, and selective staging.
+
+## Resuming Work
+
+If the plan has existing checkmarks:
+- Trust that completed work is done
+- Pick up from the first unchecked item
+- Verify previous work only if something seems off
+
+## Artifact Update Discipline
+
+- Only update checkboxes for work actually completed in current session
+- DO NOT mark phases complete preemptively
+- Preserve prior notes; append new summaries
+- Limit edits to sections affected by current phase
+- Re-running same phase should produce no additional plan changes
+
+## Quality Checklist
+
+### Initial Phase Implementation
+
+- [ ] All automated success criteria green
+- [ ] Phase Status checkbox marked complete in ImplementationPlan.md
+- [ ] Changes committed locally (NOT pushed)
+
+### PR Review Comment Response
+
+- [ ] All automated checks passing
+- [ ] Each comment group addressed with focused commit
+- [ ] ImplementationPlan.md updated with "Addressed Review Comments:" section
+- [ ] All commits local (NOT pushed)
+
+## Completion Response
+
+Report back:
+- Phase(s) completed and brief summary
+- Verification results (tests, lint)
+- Branch name and commit hash(es)
+- Any items requiring user decision or review attention
+- Status: `complete` or `blocked` (with specific blockers)