# Paw Workflow > 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. Use when this capability is needed. - Skill: `tomevault-io/paw-workflow` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/paw-workflow` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/paw-workflow/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/paw-workflow --- # PAW Implementation Workflow Skill **Reference Documentation**: This skill provides guidance on typical patterns, artifact structure, and stage sequences. Workflow enforcement (mandatory transitions, TODO tracking, pause rules) is in the PAW agent, not this skill. Prerequisite: WorkflowContext.md must exist (created by `paw-init`). ## Core Implementation Principles These principles apply to ALL implementation stages. ### 1. Evidence-Based Documentation Code-related claims in any artifact MUST be supported by: - Specific file:line references for code claims - Concrete code patterns or test results - Direct evidence from the codebase For non-code claims (e.g., requirements or planning decisions), cite the source when available (issue/discussion/user input) and clearly label assumptions. Do not present speculation, assumptions, or unverified claims as fact. ### 2. File:Line Reference Requirement All code-related claims require specific file:line citations: - `[src/module.ts:45](src/module.ts#L45)` for single lines - `[src/module.ts:45-52](src/module.ts#L45-L52)` for ranges - Multiple locations listed explicitly ### 3. No Fabrication Guardrail **CRITICAL**: Do not fabricate, invent, or assume information: - If information is unavailable, state "Not found" or "Unable to determine" - Do not hallucinate file contents, function behaviors, or patterns - When uncertain, document the uncertainty explicitly ### 4. Artifact Completeness Each stage produces complete, well-structured artifacts: - No placeholders or "TBD" markers - No unresolved questions blocking downstream stages - Each artifact is self-contained and traceable to sources ### 5. Human Authority Humans have final authority over all workflow decisions: - Review pauses honor human review preferences - Implementation choices can be overridden - Artifacts are advisory until human-approved ## Activities | Skill | Capabilities | Primary Artifacts | |-------|--------------|-------------------| | `paw-spec` | Create spec, revise spec | Spec.md | | `paw-spec-research` | Answer factual questions about existing system | SpecResearch.md | | `paw-spec-review` | Review spec for quality, completeness, clarity | Review feedback | | `paw-code-research` | Document implementation details with file:line refs | CodeResearch.md | | `paw-planning` | Create implementation plan, revise plan (single/multi-model) | ImplementationPlan.md, planning/ | | `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; delegates SoT orchestration to `paw-sot` | REVIEW*.md in reviews/ | | `paw-planning-docs-review` | Holistic review of planning artifacts bundle | REVIEW*.md in reviews/planning/ | | `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. **Utility skills**: `paw-git-operations` (branching, Phase PRs), `paw-review-response` (PR comments), `paw-docs-guidance` (documentation), `paw-sot` (society-of-thought engine, loaded by `paw-final-review`). ## Artifact Directory Structure All implementation artifacts are stored in a consistent directory structure: ``` .paw/work// ├── WorkflowContext.md # Configuration and state ├── WorkShaping.md # Pre-spec ideation output (optional, from paw-work-shaping) ├── Spec.md # Feature specification ├── SpecResearch.md # Research answers (optional) ├── 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) ├── planning/ # Multi-model planning artifacts (gitignored) │ └── PLAN-{MODEL}.md # Per-model plan drafts └── reviews/ # Review artifacts (gitignored) ├── planning/ # Planning Documents Review artifacts │ ├── REVIEW.md │ ├── REVIEW-{MODEL}.md │ └── REVIEW-SYNTHESIS.md ├── REVIEW.md # Final Agent Review: single-model ├── REVIEW-{MODEL}.md # Final Agent Review: per-model (multi-model) └── REVIEW-SYNTHESIS.md # Final Agent Review: synthesis (multi-model) ``` **Work ID Derivation**: Normalized from Work Title, lowercase with hyphens (e.g., "Auth System" → "auth-system"). ## Default Flow Guidance Typical greenfield progression (adapt based on user intent and workflow state): ### Specification Stage 1. `paw-spec`: Create specification from brief/issue 2. `paw-spec-research` (if needed): Answer factual questions 3. `paw-spec-review`: Review spec quality ### Planning Stage 1. `paw-code-research`: Document implementation details with file:line references 2. `paw-planning`: Create phased implementation plan 3. `paw-plan-review`: Review plan feasibility 4. `paw-planning-docs-review` (if enabled): Holistic review of planning bundle ### Implementation Stage Per phase in ImplementationPlan.md: 1. `paw-implement`: Execute phase, make code changes 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 ## PR Comment Response Routing | PR Type | Skill to Load | Notes | |---------|--------------|-------| | Planning PR | `paw-planning` | Comments on ImplementationPlan.md | | Phase PR | `paw-implement` → `paw-impl-review` | Code changes then verify | | Final PR | `paw-implement` → `paw-impl-review` | May require code changes | Load `paw-review-response` utility skill for comment mechanics. ## Execution Model **Direct execution**: `paw-spec`, `paw-planning`, `paw-implement`, `paw-final-review`, `paw-planning-docs-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` **Orchestrator-handled**: Push and Phase PR creation (after `paw-impl-review` passes, using `paw-git-operations`) Activities may return `blocked` status with open questions. Apply Review Policy to determine resolution approach (`final-pr-only`: research autonomously; `every-stage`/`milestones`: ask user). ## Workflow Mode - **Full**: All stages, multiple phases, PRs or local strategy - **Minimal**: May skip spec stage, single phase, forces local strategy - **Custom**: Read Custom Workflow Instructions from WorkflowContext.md --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/lossyrob) — claim your Tome and manage your conversions.