@paw-workflow/cli 0.0.1

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

@@ -0,0 +1,118 @@
+---
+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"
+---
+
+# PAW Initialization
+
+> **Execution Context**: This skill runs **directly** in the PAW session (not a subagent), as bootstrap requires user input for workflow parameters.
+
+Bootstrap skill that initializes the PAW workflow directory structure. This runs **before** the workflow skill is loaded—WorkflowContext.md must exist for the workflow to function.
+
+## Capabilities
+
+- Generate Work Title from issue URL, branch name, or user description
+- Generate Work ID from Work Title (normalized, unique)
+- Create `.paw/work/<work-id>/` directory structure
+- Generate WorkflowContext.md with all configuration fields
+- Create and checkout git branch (explicit or auto-derived)
+- Commit initial artifacts if tracking is enabled
+- Open WorkflowContext.md for review
+
+## Input Parameters
+
+| Parameter | Required | Default | Values |
+|-----------|----------|---------|--------|
+| `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` |
+| `review_policy` | No | `milestones` | `always`, `milestones`, `planning-only`, `never` |
+| `session_policy` | No | `per-stage` | `per-stage`, `continuous` |
+| `track_artifacts` | No | `true` | boolean |
+| `issue_url` | No | none | URL |
+| `custom_instructions` | Conditional | — | text (required if `workflow_mode` is `custom`) |
+| `work_description` | No | none | text |
+
+### 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
+
+This mirrors the VS Code command flow which prompts sequentially but allows skipping with defaults.
+
+## Desired End States
+
+### Work Title
+- A 2-4 word human-readable name exists
+- Sources (priority order): issue title → branch name → work description
+- Capitalized appropriately (e.g., `User Auth System`)
+
+### Work ID
+- Unique within `.paw/work/`
+- Format: lowercase letters, numbers, hyphens only; 1-100 chars
+- No leading/trailing/consecutive hyphens
+- Not reserved (`.`, `..`, `node_modules`, `.git`, `.paw`)
+- If conflict: append `-2`, `-3`, etc.
+
+### Configuration Validation
+- If `workflow_mode` is `minimal`, `review_strategy` MUST be `local`
+- If `review_policy` is `planning-only` or `never`, `review_strategy` MUST be `local`
+- Invalid combinations: STOP and report error
+
+### Directory Structure
+```
+.paw/work/<work-id>/
+└── WorkflowContext.md
+```
+
+### WorkflowContext.md
+Created at `.paw/work/<work-id>/WorkflowContext.md` with all input parameters:
+
+```markdown
+# WorkflowContext
+
+Work Title: <generated_work_title>
+Work ID: <generated_work_id>
+Target Branch: <target_branch>
+Workflow Mode: <workflow_mode>
+Review Strategy: <review_strategy>
+Review Policy: <review_policy>
+Session Policy: <session_policy>
+Custom Workflow Instructions: <custom_instructions or "none">
+Initial Prompt: <work_description or "none">
+Issue URL: <issue_url or "none">
+Remote: origin
+Artifact Paths: auto-derived
+Additional Inputs: none
+```
+
+### Git Branch
+> Branch creation and checkout follows `paw-git-operations` patterns.
+
+- Target branch exists and is checked out
+- If explicit branch provided: use as-is (prompt if exists)
+- If auto-derive: `feature/<work-id>`
+
+### Artifact Tracking
+- **If tracking enabled**: WorkflowContext.md committed with message `Initialize PAW workflow for <Work Title>`
+- **If tracking disabled**: `.gitignore` with `*` created in work directory
+
+### User Review
+- WorkflowContext.md presented for user review/confirmation
+
+## Completion Response
+
+Report initialization results to PAW agent including: work ID, workflow mode, target branch, and the recommended next step based on workflow mode (full → spec, minimal → code research, custom → per instructions).
+
+## Validation Checklist
+
+- [ ] Work ID is unique and valid format
+- [ ] Review strategy valid for workflow mode
+- [ ] WorkflowContext.md created with all fields
+- [ ] Git branch created and checked out
+- [ ] Artifacts committed (if tracking enabled)
+- [ ] WorkflowContext.md opened for review

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

@@ -0,0 +1,117 @@
+---
+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"
+---
+
+# Plan 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.
+
+Review implementation plans for quality, feasibility, and alignment with specification before implementation proceeds.
+
+> **Reference**: Follow Core Implementation Principles from `paw-workflow` skill.
+
+## Capabilities
+
+- Review ImplementationPlan.md for feasibility, completeness, and spec alignment
+- Validate against quality criteria
+- Identify specific phases or sections needing revision
+- Return structured feedback with pass/fail status
+
+## Desired End State
+
+- Plan reviewed against all quality criteria
+- Specific issues identified with actionable feedback
+- Structured PASS/FAIL response returned to PAW agent
+
+## Quality Criteria
+
+### Spec Coverage
+
+- [ ] All spec requirements mapped to plan phases
+- [ ] User stories have corresponding implementation work
+- [ ] Success criteria from spec reflected in phase success criteria
+- [ ] No spec requirements orphaned (missing from plan)
+
+### Phase Feasibility
+
+- [ ] Each phase has clear, testable success criteria
+- [ ] Phase boundaries are logical (not too large, not too small)
+- [ ] Dependencies between phases are explicit
+- [ ] Phases build incrementally and can be reviewed independently
+
+### Completeness
+
+- [ ] No placeholder content or TBDs
+- [ ] All file paths and components specified
+- [ ] Unit tests specified alongside code they test
+- [ ] "What We're NOT Doing" section exists
+
+### Research Integration
+
+- [ ] Code research findings incorporated (file:line references)
+- [ ] Documentation System section from CodeResearch.md considered
+- [ ] Existing patterns referenced where applicable
+
+### Strategic Focus
+
+- [ ] Changes describe WHAT not HOW (interfaces, responsibilities)
+- [ ] Code blocks limited to architectural concepts (<10 lines)
+- [ ] No implementation algorithms or pseudo-code
+- [ ] Significant decisions include trade-off analysis
+
+### Documentation Planning
+
+- [ ] Documentation phase included (standard for all non-trivial changes)
+- [ ] Docs.md specified for technical reference (always required)
+- [ ] Project docs updates included if user-facing or API changes exist
+- [ ] If project docs omitted: reason provided
+
+## Review Process
+
+1. Read ImplementationPlan.md completely
+2. Cross-reference with Spec.md for coverage
+3. Check CodeResearch.md integration
+4. Evaluate each quality criteria category
+5. Compile specific issues with locations
+6. Determine overall PASS/FAIL status
+
+## Feedback Categories
+
+| Category | Description |
+|----------|-------------|
+| **BLOCKING** | Must fix before implementation (missing requirements, infeasible phases) |
+| **IMPROVE** | Should address but not blocking (clarity, organization) |
+| **NOTE** | Observation for awareness (minor suggestions, alternatives) |
+
+## Completion Response
+
+Return structured feedback to PAW agent:
+
+**PASS**: Plan meets quality criteria, ready for implementation
+- Confirm spec coverage complete
+- Note any non-blocking observations
+
+**FAIL**: Plan needs revision before implementation
+- List blocking issues with specific locations
+- Categorize issues (BLOCKING, IMPROVE)
+- Suggest what needs to change (not how to change it)
+
+### Response Content
+
+Include in completion response:
+- Overall status: PASS or FAIL
+- Spec coverage assessment: which requirements are covered, any gaps
+- Phase feasibility assessment: any phases too large, unclear, or missing dependencies
+- Completeness check: any TBDs, missing tests, incomplete sections
+- Specific issues: categorized with plan section references
+- Recommendation: proceed to implementation or revise plan
+
+## Non-Responsibilities
+
+- Do NOT make orchestration decisions (PAW agent handles next steps)
+- Do NOT modify the plan directly (return feedback for planning skill to address)
+- Do NOT implement changes (review only)
+- Do NOT handle handoffs (return status to PAW agent)

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

@@ -0,0 +1,217 @@
+---
+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"
+---
+
+# Implementation Planning
+
+> **Execution Context**: This skill runs **directly** in the PAW session (not a subagent), preserving user interactivity for phase decisions and blocker handling.
+
+Create detailed implementation plans through interactive refinement. Plans describe WHAT to build (components, interfaces, behaviors) at the architectural level, delegating HOW to implement to the implementer.
+
+> **Reference**: Follow Core Implementation Principles from `paw-workflow` skill.
+
+## Capabilities
+
+- Create implementation plan from spec and research
+- Revise plan based on learnings or feedback
+- Address PR review comments (load `paw-review-response` for mechanics)
+- Plan documentation phases when documentation updates are warranted
+
+## Be Skeptical
+
+- Question vague requirements—ask "why" and "what about"
+- Identify potential issues early
+- Don't assume—verify with code research
+- If user corrects a misunderstanding, verify the correction against code before accepting
+
+## Strategic Planning Guidelines
+
+Operate at the **C4 container/component abstraction level**:
+
+**Do**:
+- Describe component responsibilities and interfaces
+- Reference file paths, module names, existing patterns
+- Present 2-3 options with trade-offs for significant decisions
+- Define success via observable outcomes (tests, SLOs, acceptance criteria)
+- Limit code snippets to 3-10 lines for critical architectural concepts only
+
+**Don't**:
+- Include complete function implementations
+- Provide pseudo-code walkthroughs
+- Specify library choices without trade-off analysis
+- Write tutorial-style code examples
+
+**Example descriptions**:
+- ✅ "Implement `UserRepository` interface with CRUD methods, following pattern in `models/repositories/`"
+- ✅ "Add auth middleware validating JWT tokens, integrating with `services/auth/`"
+- ❌ "Create function that loops through array and filters..."
+
+## Documentation Phase Planning
+
+Include documentation as the **final implementation phase**. The documentation phase is standard for all non-trivial changes.
+
+### What the Documentation Phase Produces
+
+1. **Docs.md** (always): Technical reference capturing implementation details, usage, and verification approach—serves as the "as-built" record even for internal changes
+2. **Project documentation updates** (when warranted): README, CHANGELOG, guides following project conventions
+3. **Documentation build verification**: Command from CodeResearch.md (if framework discovered)
+
+### When to Include Project Docs
+
+- Work creates user-facing features
+- APIs are added or changed
+- Existing behavior is modified in ways users should know about
+
+### When to Omit Project Docs
+
+- Purely internal changes (Docs.md still required)
+- Refactors without behavior changes (Docs.md still required)
+- User explicitly indicates no project docs needed
+
+**Note**: Implementer loads `paw-docs-guidance` utility skill for templates and conventions during documentation phases.
+
+## ImplementationPlan.md Template
+
+Save to: `.paw/work/<work-id>/ImplementationPlan.md`
+
+```markdown
+# [Feature/Task Name] Implementation Plan
+
+## Overview
+[What we're implementing and why]
+
+## Current State Analysis
+[Existing state, gaps, key constraints from research]
+
+## Desired End State
+[Target state specification and verification approach]
+
+## What We're NOT Doing
+[Out-of-scope items]
+
+## Phase Status
+- [ ] **Phase 1: [Name]** - [Objective]
+- [ ] **Phase 2: [Name]** - [Objective]
+- [ ] **Phase N: Documentation** - [If warranted]
+
+---
+
+## Phase 1: [Name]
+
+### Changes Required:
+- **`path/to/file.ext`**: [Component changes, pattern references]
+- **Tests**: [Test file, key scenarios]
+
+### Success Criteria:
+
+#### Automated Verification:
+- [ ] Tests pass: `<command>`
+- [ ] Lint/typecheck: `<command>`
+
+#### Manual Verification:
+- [ ] [User-observable behavior]
+- [ ] [Edge cases requiring human judgment]
+
+---
+
+## Phase N: Documentation (if warranted)
+
+### Changes Required:
+- **`.paw/work/<work-id>/Docs.md`**: Technical reference (load `paw-docs-guidance`)
+- **Project docs**: Per CodeResearch.md findings
+
+### Success Criteria:
+- [ ] Docs build: `<command>`
+- [ ] Content accurate, style consistent
+
+---
+
+## References
+- Issue: [link or 'none']
+- Spec: `.paw/work/<work-id>/Spec.md`
+- Research: `.paw/work/<work-id>/SpecResearch.md`, `.paw/work/<work-id>/CodeResearch.md`
+```
+
+**Phase Status format**: Use checkboxes `- [ ]` for pending, `- [x]` for complete. This provides at-a-glance status without heavy tables.
+
+## Execution Contexts
+
+### Initial Planning
+
+**Desired end state**: Complete ImplementationPlan.md with all phases defined
+
+1. Read all context: Issue, Spec.md, SpecResearch.md, CodeResearch.md
+2. Analyze and verify requirements against actual code
+3. Present understanding and resolve blocking questions
+4. Research patterns and design options (if significant choices exist)
+5. Write plan incrementally (outline, then phase by phase)
+6. Handle branching per Review Strategy (see below)
+
+### PR Review Response
+
+When addressing Planning PR comments, load `paw-review-response` utility for mechanics.
+
+**Desired end state**: All review comments addressed, artifacts consistent
+
+1. Verify on planning branch (`<target>_plan`)
+2. Read all unresolved PR comments
+3. Create TODOs for comments (group related, separate complex)
+4. For each TODO: make changes → commit → push → reply
+5. Verify all comments addressed and artifacts consistent
+
+### Plan Revision
+
+When revising based on paw-plan-review feedback:
+
+**Desired end state**: ImplementationPlan.md updated to address all BLOCKING issues
+
+1. Read paw-plan-review feedback completely
+2. Address BLOCKING issues first (these prevent implementation)
+3. Address IMPROVE issues if scope permits
+4. Acknowledge NOTE items in commit message if applicable
+5. Re-run quality checklist to verify fix didn't introduce new issues
+
+## Branching and Commits
+
+> **Reference**: Load `paw-git-operations` skill for branch naming, commit mechanics, and PR descriptions.
+
+## Quality Checklist
+
+- [ ] All phases contain specific file paths, components, or interfaces
+- [ ] Every phase has measurable automated and manual success criteria
+- [ ] Phases build incrementally and can be reviewed independently
+- [ ] Zero open questions or TBDs remain
+- [ ] All references trace to Spec.md and CodeResearch.md
+- [ ] Unit tests specified alongside code they test within each phase
+- [ ] "What We're NOT Doing" section prevents scope creep
+- [ ] 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
+
+## Completion Response
+
+Report to PAW agent:
+- Artifact path: `.paw/work/<work-id>/ImplementationPlan.md`
+- **Plan summary** for quick review:
+  - Architecture approach (1-2 sentences)
+  - Phase overview (numbered list with one-line objective each)
+  - What's explicitly NOT being done (scope boundaries)
+- Review Strategy used (PR created or committed to target)
+- Any items requiring user decision or observations worth noting
+
+### Blocked on Open Questions
+
+If planning encounters questions that cannot be answered from existing artifacts (Spec.md, CodeResearch.md):
+
+1. **Do NOT write ImplementationPlan.md** — partial artifacts cause confusion on re-invocation
+2. **Return to PAW agent** with:
+   - Status: `blocked`
+   - List of specific open questions
+   - What research or clarification would resolve each question
+3. **PAW agent handles resolution** based on Review Policy:
+   - `never`: PAW agent conducts additional research to resolve questions autonomously
+   - `always`/`milestones`: PAW agent asks user for clarification
+4. **Re-invocation**: PAW agent calls planning again with answers provided in the delegation prompt

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

@@ -0,0 +1,157 @@
+---
+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.
+metadata:
+  version: "0.0.1"
+---
+
+# 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.
+
+> **Reference**: Follow Core Implementation Principles from `paw-workflow` skill.
+
+## Capabilities
+
+- Run pre-flight validation checks
+- Create comprehensive PR description (scaled to complexity)
+- Open final PR from target branch to main
+- Provide merge and deployment guidance
+
+## Pre-flight Validation
+
+Before creating the PR, verify and report status. Block on failures unless user explicitly confirms.
+
+### Required Checks
+
+**Phase Implementation**:
+- All phases in ImplementationPlan.md marked complete
+- All phase PRs merged (prs strategy) or commits pushed (local strategy)
+- Target branch exists with implementation commits
+
+**Artifacts Exist** (check existence per Workflow Mode):
+- CodeResearch.md (required: all modes)
+- ImplementationPlan.md (required: all modes)
+- Spec.md (required: full mode; optional: minimal/custom)
+- SpecResearch.md (optional: all modes)
+- Docs.md (required: full mode; optional: minimal/custom)
+
+**Branch Status**:
+- Target branch up to date with base branch (main)
+- No merge conflicts
+
+**Build/Tests**:
+- Latest build passes on target branch (if applicable)
+- All tests passing
+
+**Open Questions Resolved**:
+- SpecResearch `## Open Unknowns` → resolved in Spec or clarified
+- CodeResearch `## Open Questions` → resolved in Plan or code
+- ImplementationPlan `## Open Questions` → empty
+- Unresolved items → block and report with recommendation
+
+## Workflow Mode Handling
+
+### Full Mode
+- Reference all artifacts: Spec.md, SpecResearch.md, CodeResearch.md, ImplementationPlan.md, Docs.md
+- PRs strategy: Include links to intermediate PRs (Planning, Phase, Docs)
+- Local strategy: Describe work directly from commits
+
+### Minimal Mode
+- Reference only core artifacts: CodeResearch.md, ImplementationPlan.md
+- Check Spec.md and Docs.md existence before including
+- Local strategy only (enforced)
+
+### Custom Mode
+- Dynamically check which artifacts exist
+- Adapt references based on Custom Workflow Instructions
+
+## Artifact Tracking Detection
+
+Check if workflow artifacts are tracked in git:
+1. Check for `.paw/work/<work-id>/.gitignore`
+2. If contains `*` → artifacts **untracked**
+3. If no `.gitignore` → artifacts **tracked**
+
+**Impact on PR Description**:
+- Tracked: Include Artifacts section with links
+- Untracked: Omit Artifacts section; summarize key information in body
+
+## PR Description Formats
+
+**Scale description to change complexity.** Simple fixes need brief summaries; major features need comprehensive sections.
+
+### Simple Changes
+
+For bug fixes, small features: title with `[Work Title]` prefix, close issue, brief summary, changes list, testing status, PAW footer.
+
+### Complex Changes
+
+For large features, architectural changes, multi-phase implementations:
+
+Include these elements as appropriate:
+- Summary: Overview of what PR delivers and key design decisions
+- Changes: Detailed changes with context and rationale
+- Testing: Coverage notes, verification performed
+- Breaking Changes: Migration guidance if applicable
+- Deployment: Feature flags, rollout strategy, dependencies
+- Artifacts: Links to workflow artifacts (if tracked)
+
+Footer: `🐾 Generated with [PAW](https://github.com/lossyrob/phased-agent-workflow)`
+
+### PRs Strategy Sections
+
+When intermediate PRs exist, include:
+- Planning section referencing Planning PR
+- Implementation Phases listing Phase PRs
+- Documentation section referencing Docs PR
+
+### Local Strategy Sections
+
+When no intermediate PRs:
+- Implementation Summary describing work from commit history
+- Focus on what was implemented, not which PRs
+
+## PR Creation
+
+**Final PR context requirements**:
+- Source: `<target_branch>`
+- Target: `main` (or specified base branch)
+- Title format: `[<Work Title>] <description>`
+- Body: Scaled description per formats above
+- Issue linking: Include Issue URL from WorkflowContext.md
+
+## Merge Guidance
+
+After PR creation, provide:
+- Summary of what reviewers should focus on
+- Deployment considerations (if any)
+- Next steps for completion
+
+## Quality Checklist
+
+- [ ] All pre-flight checks pass (or user confirmed proceed)
+- [ ] PR description complete with all relevant sections
+- [ ] All artifact links valid (if tracked)
+- [ ] Intermediate PR links included (if prs strategy)
+- [ ] Breaking changes documented (or stated "None")
+- [ ] Issue URL linked in PR body
+
+## Guardrails
+
+- Do NOT modify code or documentation
+- Do NOT approve or merge PRs
+- Do NOT address review comments (Implementer handles this)
+- Do NOT guess artifact locations—verify existence
+
+## Completion Response
+
+Report back:
+- Final PR URL
+- Pre-flight validation summary
+- Items for reviewer attention
+- Merge readiness assessment
+
+Next steps: Address PR feedback via `address comments`, then merge to complete workflow.