@paw-workflow/cli 0.0.1

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

@@ -0,0 +1,257 @@
+---
+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"
+---
+
+# Specification
+
+> **Execution Context**: This skill runs **directly** in the PAW session (not a subagent), preserving user interactivity for requirement clarification.
+
+Convert a rough Issue / feature brief into a **structured feature specification**. Emphasizes prioritized user stories, enumerated requirements, measurable success criteria, explicit assumptions, and traceability.
+
+> **Reference**: Follow Core Implementation Principles from `paw-workflow` skill.
+
+## Capabilities
+
+- Create new specification from issue/brief or WorkShaping.md output
+- Clarify ambiguous requirements through interactive Q&A
+- Generate research prompt for factual questions about existing system
+- Integrate research findings into specification
+- Revise spec based on downstream learnings (e.g., align with implementation plan)
+- Address PR review comments on specification
+
+## Core Principles
+
+1. **User value focus**: Describe WHAT & WHY, not implementation details 
+2. **Independently testable stories**: Prioritize user stories (P1 highest) with acceptance scenarios and "Independent Test" statement
+3. **Resolve before drafting**: Clarification questions answered before drafting—no unresolved critical questions or placeholder markers
+4. **Enumerated traceability**: Use IDs (FR-001, SC-001) linking stories ↔ FRs ↔ SCs; cite research sources
+5. **Research vs design**: Research documents existing behavior; design decisions belong in spec based on requirements
+6. **Explicit assumptions**: Replace low-impact unknowns with documented assumptions
+7. **Measurable & tech-agnostic**: Success criteria measurable without referencing specific technologies
+8. **Scope & risk**: Maintain explicit In/Out boundaries; enumerate risks with mitigations
+9. **No speculation**: Every feature maps to a defined story—no "future maybe" items
+
+## Clarification Phase
+
+Before drafting the specification, identify and resolve gaps that only the user can answer. This phase always runs during initial spec creation regardless of Review Policy—it's the most important step to get right.
+
+### When to Clarify
+
+After reading the issue/brief, scan for high-impact gaps:
+- **Scope boundaries**: What's explicitly in vs out?
+- **User roles**: Who are the distinct users/personas?
+- **Success criteria**: How will we know it works? (measurable)
+- **Edge cases**: What happens when X fails/is empty/conflicts?
+- **Non-functional requirements**: Performance, security, scale constraints?
+- **Ambiguous terminology**: Terms that could mean multiple things?
+
+**Skip clarification if**: The issue/brief is comprehensive and gaps are low-impact or can be handled as documented assumptions.
+
+### Clarification Process
+
+Ask questions **one at a time**:
+1. Identify the single highest-impact unclear item
+2. Formulate a focused question (prefer multiple choice when options are finite)
+3. Include AI recommendation with reasoning when applicable
+4. Wait for user response
+5. Integrate answer into working understanding
+6. Repeat until gaps resolved or user signals done
+
+### Question Guidelines
+
+- Ask only what the user can answer (intent, priorities, business constraints)
+- Prefer multiple choice over freeform when options are enumerable
+- One question per turn—never batch multiple questions
+- High-impact only: skip stylistic or low-stakes gaps
+- Include recommendation when you have one: "Recommended: X (because...)"
+
+**Example questions**:
+- "Should admin users have different permissions than regular users? (Recommended: Yes, admins need audit capabilities)"
+- "What happens if the external API is unavailable? Options: (a) Show cached data, (b) Show error, (c) Retry with backoff"
+- "Is there a maximum number of items a user can create? (This affects data model and UI)"
+
+### Exit Conditions
+
+Stop clarification when:
+- All high-impact gaps are resolved
+- User signals: "done", "skip", "proceed", "that's enough"
+- ~5-10 questions reached (avoid fatigue—remaining gaps become assumptions)
+
+## Execution Based on Context
+
+### New Specification (No SpecResearch.md)
+
+**Desired end state**: Research prompt generated OR specification complete
+
+**Input source precedence**: WorkShaping.md (if exists) → issue/brief → user description
+
+- Check for WorkShaping.md in work directory; if present, use its structured content as primary input
+- Run Clarification Phase to resolve remaining user-intent gaps before drafting
+- Classify unknowns: assumptions (document in spec) vs research questions (generate prompt)
+- If research needed: generate ResearchQuestions at `.paw/work/<work-id>/ResearchQuestions.md` and STOP
+- If no research needed: proceed to complete specification
+
+### Resume After Research (SpecResearch.md exists)
+
+**Desired end state**: Complete specification integrating research findings
+
+- Map research answers to requirements
+- Resolve any new clarifications surfaced by research
+- Assemble complete specification
+
+### Revise Specification
+
+**Desired end state**: Spec aligned with downstream artifacts, traceability maintained
+
+- Identify specific sections needing updates based on alignment requirements
+- Make targeted revisions while maintaining ID traceability
+- Update version/date in spec header
+
+### Address PR Review Comments
+
+Load `paw-review-response` utility skill for mechanics. Focus on what spec sections to update and how to maintain traceability.
+
+## Research Question Guidelines
+
+Research answers "how does the system work today?" NOT "what should we build?"
+
+**Appropriate:**
+- "How does the authentication system validate sessions?" → Learn pattern → Decide approach
+- "What error format do existing APIs use?" → Learn structure → Decide format
+
+**Inappropriate:**
+- "Should we use JWT or sessions?" → Design decision, not research
+- "What status codes for new endpoint?" → Design decision, not research
+
+## ResearchQuestions Format
+
+Generate ResearchQuestions at `.paw/work/<work-id>/ResearchQuestions.md` containing:
+- Target branch and issue URL (for context)
+- Agent notes from intake that help researcher understand constraints
+- Numbered list of internal system behavior questions
+- Optional section for external/context questions
+
+## Specification Template
+
+```markdown
+# Feature Specification: <FEATURE NAME>
+
+**Branch**: <branch>  |  **Created**: <YYYY-MM-DD>  |  **Status**: Draft
+**Input Brief**: <one-line intent>
+
+## Overview
+<2-4 paragraphs describing WHAT and WHY from user perspective.
+Flowing narrative prose—user journey and value. No implementation details.>
+
+## Objectives
+<Bulleted behavioral goals. Observable outcomes, technology-agnostic.
+Optional rationale: "Enable X (Rationale: this allows users to...)">
+
+## User Scenarios & Testing
+### User Story P1 – <Title>
+Narrative: <short user journey>
+Independent Test: <single action verifying value>
+Acceptance Scenarios:
+1. Given <context>, When <action>, Then <outcome>
+
+### User Story P2 – <Title>
+...
+
+### Edge Cases
+- <edge condition & expected behavior>
+
+## Requirements
+### Functional Requirements
+- FR-001: <testable capability> (Stories: P1)
+- FR-002: <testable capability> (Stories: P1,P2)
+
+### Key Entities (omit if none)
+- <Entity>: <description>
+
+### Cross-Cutting / Non-Functional (omit if in Success Criteria)
+- <constraint with measurable aspect>
+
+## Success Criteria
+- SC-001: <measurable outcome, tech-agnostic> (FR-001)
+- SC-002: <measurable outcome> (FR-002, FR-003)
+
+## Assumptions
+- <Assumed default & rationale>
+
+## Scope
+In Scope:
+- <included boundary>
+Out of Scope:
+- <explicit exclusion>
+
+## Dependencies
+- <system/service/feature flag>
+
+## Risks & Mitigations
+- <risk>: <impact>. Mitigation: <approach>
+
+## References
+- Issue: <link>
+- Research: .paw/work/<work-id>/SpecResearch.md
+```
+
+## Quality Checklist
+
+### Content Quality
+- [ ] Focuses on WHAT & WHY (no implementation details)
+- [ ] No code snippets, file paths, API signatures
+- [ ] Story priorities clear (P1 highest)
+- [ ] Each story independently testable with ≥1 acceptance scenario
+- [ ] Edge cases enumerated
+
+### Narrative Quality
+- [ ] Overview: 2-4 paragraphs of flowing prose
+- [ ] Objectives: bulleted behavioral goals
+- [ ] User perspective throughout—no implementation details
+
+### Requirement Completeness
+- [ ] All FRs testable & observable
+- [ ] FRs mapped to user stories
+- [ ] Success Criteria measurable & tech-agnostic
+- [ ] Success Criteria linked to FRs
+- [ ] Assumptions documented
+- [ ] Dependencies listed
+
+### Ambiguity Control
+- [ ] No unresolved clarification questions
+- [ ] No vague adjectives without metrics
+
+### Scope & Risk
+- [ ] Clear In/Out boundaries
+- [ ] Risks & mitigations captured
+
+### Research Integration
+- [ ] System research questions answered or converted to assumptions
+- [ ] Optional external questions listed for manual completion
+
+## Workflow Mode Adaptation
+
+**Full mode**: Standard spec with comprehensive coverage
+
+**Minimal mode**: Spec stage typically skipped. If invoked, create lightweight spec focusing on core FRs and acceptance criteria.
+
+**Custom mode**: Check Custom Workflow Instructions. Adapt depth per instructions.
+
+## Completion Response
+
+Report to PAW agent based on outcome:
+
+**Research needed**: Include ResearchQuestions path, question count, documented assumptions count, and indicate waiting for research.
+
+**Specification complete**: Include:
+- Artifact path
+- **Spec summary** for quick review:
+  - Overview (1-2 sentences capturing the core value)
+  - Key objectives (bulleted)
+  - Scope highlights (what's in, what's explicitly out)
+- Counts (user stories, FRs, success criteria)
+- Any observations worth noting (e.g., "stakeholder alignment may be needed on X")
+- Confirmation that quality checklist passes

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

@@ -0,0 +1,138 @@
+---
+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"
+---
+
+# Spec Research
+
+> **Execution Context**: This skill runs in a **subagent** session, delegated by the PAW orchestrator. Return structured results to the orchestrator upon completion.
+
+**Describe how the system works today** to answer questions from the spec research prompt. Document existing behavior—no design, no improvements.
+
+> **Reference**: Follow Core Implementation Principles from `paw-workflow` skill.
+
+## Capabilities
+
+- Answer factual questions about existing system behavior
+- Document behavioral descriptions (what system does from user/component perspective)
+- Identify unanswered questions as Open Unknowns
+
+## Scope: Behavioral Documentation Only
+
+> **Note**: The file:line citation requirement from `paw-workflow` Core Principles applies to *implementation claims* in CodeResearch.md, not behavioral documentation here. SpecResearch.md documents *what* the system does, not *how* it's implemented.
+
+**What to document:**
+- Behavioral descriptions (what system does from user/component perspective)
+- Conceptual data flows (entities and their purposes)
+- API behaviors (inputs/outputs, not implementation)
+- User-facing workflows and business rules
+- Configuration effects (what happens when changed)
+
+**What NOT to document:**
+- Implementation details or code structure (Code Research handles this)
+- Technical architecture or design patterns (Code Research handles this)
+- Code snippets or function signatures (Code Research handles this)
+
+**Evidence references**: Use documentation-level citations (e.g., "README section X", "API docs", "config file behavior") rather than code file:line references.
+
+**Key difference from CodeResearch.md:**
+- SpecResearch.md: "The auth system requires email and password, returns session token" (behavioral)
+- CodeResearch.md: "Auth implemented in auth/handlers.go:45 using bcrypt" (implementation)
+
+## Desired End State
+
+SpecResearch.md artifact created at `.paw/work/<work-id>/SpecResearch.md` containing:
+- Summary of key findings about existing system behavior
+- Each question answered with evidence source and spec implications
+- Unanswerable questions listed as Open Unknowns with rationale
+- External questions preserved for manual completion
+
+## Research Process
+
+Read `.paw/work/<work-id>/ResearchQuestions.md` for questions and context. For each question, search the codebase for relevant behavior, ensure sufficient context before stating behavior confidently, and document answers factually with evidence sources.
+
+## SpecResearch.md Template
+
+```markdown
+---
+date: <YYYY-MM-DD HH:MM:SS TZ>
+git_commit: <current commit hash>
+branch: <target branch>
+repository: <repo name>
+topic: "<feature name> Spec Research"
+tags: [research, specification]
+status: complete
+---
+
+# Spec Research: <Feature Name>
+
+## Summary
+<1-2 paragraphs: Key findings overview. What the research revealed about existing system behavior.>
+
+## Agent Notes
+<Preserve notes from Spec Agent verbatim. Omit section if no notes in prompt.>
+
+## Research Findings
+
+### Question 1: <question text>
+**Answer**: <factual behavior description>
+**Evidence**: <source of information - e.g., "API documentation", "observed config behavior">
+**Implications**: <how this impacts spec requirements or scope>
+
+### Question 2: <question text>
+**Answer**: <factual behavior description>
+**Evidence**: <source>
+**Implications**: <impact on spec>
+
+## Open Unknowns
+<List internal questions that couldn't be answered with rationale.>
+
+- <question>: <why it couldn't be answered>
+
+Note: The Spec Agent will review these with you. You may provide answers if possible.
+
+## User-Provided External Knowledge (Manual Fill)
+<Unchecked list of optional external/context questions for manual completion.>
+
+- [ ] <external question 1>
+- [ ] <external question 2>
+```
+
+## Quality Guidelines
+
+### Anti-Evaluation Directives (CRITICAL)
+
+**YOUR JOB IS TO DESCRIBE THE SYSTEM AS IT EXISTS TODAY**
+- DO NOT suggest improvements or alternative implementations
+- DO NOT critique current behavior or identify problems
+- DO NOT recommend optimizations, refactors, or fixes
+- DO NOT evaluate whether the current approach is good or bad
+- ONLY document observable behavior and facts supported by the codebase
+
+### Keep Answers Concise
+
+- Answer questions directly with essential facts only
+- Avoid exhaustive lists, lengthy examples, or unnecessary detail
+- Goal: Give Spec Agent enough info to write clear requirements, not document every edge case
+
+### Idempotent Updates
+
+- Build SpecResearch.md incrementally
+- Re-running with same inputs should reproduce same document
+- Preserve existing accurate sections; avoid rewriting unrelated portions
+
+## Quality Checklist
+
+Before completion:
+- [ ] All internal questions answered or listed as Open Unknowns with rationale
+- [ ] Answers are factual and evidence-based (no speculation)
+- [ ] Responses are concise and directly address questions
+- [ ] Behavioral focus maintained (no implementation details)
+- [ ] Optional external questions copied to manual section
+- [ ] SpecResearch.md saved to `.paw/work/<work-id>/SpecResearch.md`
+
+## Completion Response
+
+Report to PAW agent: artifact path, counts (questions answered, open unknowns, external questions for manual completion), and readiness for spec integration.

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

@@ -0,0 +1,101 @@
+---
+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"
+---
+
+# Spec 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 specifications for quality, completeness, and clarity before planning proceeds. Return structured feedback—do not make orchestration decisions.
+
+> **Reference**: Follow Core Implementation Principles from `paw-workflow` skill.
+
+## Capabilities
+
+- Review Spec.md for quality, completeness, and clarity
+- Validate against specification quality criteria
+- Identify specific sections needing revision
+- Return structured feedback with pass/fail status
+
+## Desired End State
+
+After review, the PAW agent receives:
+- Pass/fail determination
+- For passing specs: confirmation of readiness for planning (with optional polish suggestions)
+- For failing specs: specific issues by criterion, affected sections, and suggestions for fixing
+
+## Review Process
+
+Evaluate the specification at `.paw/work/<work-id>/Spec.md` against the Quality Criteria Checklist below. For failing items, note the specific issue, identify affected section(s), and suggest what needs to change without prescribing exact wording.
+
+## Quality Criteria Checklist
+
+### Content Quality
+- [ ] **User value focus**: Describes WHAT & WHY, no implementation details
+- [ ] **No code artifacts**: No code snippets, file paths, API signatures, class names
+- [ ] **Story priorities**: Clear priority order (P1 highest, descending)
+- [ ] **Testable stories**: Each user story is independently testable
+- [ ] **Acceptance scenarios**: Each story has ≥1 acceptance scenario (Given/When/Then)
+- [ ] **Edge cases**: Edge conditions and error modes enumerated
+
+### Narrative Quality
+- [ ] **Overview present**: 2-4 paragraphs of flowing prose (not bullets)
+- [ ] **Objectives present**: Bulleted behavioral goals (not implementation)
+- [ ] **User perspective**: Overview and Objectives focus on WHAT/WHY from user viewpoint
+- [ ] **Specific content**: Uses measurable language, not vague terms
+- [ ] **No duplication**: Overview doesn't duplicate User Stories/FRs/SCs verbatim
+
+### Requirement Completeness
+- [ ] **FRs testable**: All functional requirements are observable and testable
+- [ ] **FRs mapped**: Each FR linked to supporting user stories
+- [ ] **SCs measurable**: Success criteria are measurable and technology-agnostic
+- [ ] **SCs linked**: Success criteria reference relevant FR IDs
+- [ ] **Assumptions documented**: No silently implied assumptions
+- [ ] **Dependencies listed**: External dependencies and constraints captured
+
+### Ambiguity Control
+- [ ] **No unresolved questions**: No clarification markers or TBDs in spec body
+- [ ] **Precise language**: No vague adjectives without metrics (e.g., "fast", "easy")
+
+### Scope & Risk
+- [ ] **Boundaries defined**: Clear In Scope and Out of Scope sections
+- [ ] **Risks captured**: Known risks with impact and mitigation noted
+
+### Research Integration (if SpecResearch.md exists)
+- [ ] **Research incorporated**: System research questions answered or converted to assumptions
+- [ ] **External questions listed**: Optional external questions preserved for manual completion
+
+## Feedback Guidance
+
+**For passing specs**: Indicate readiness for planning. Include minor polish suggestions if any.
+
+**For failing specs**: List each failing criterion with the specific issue, affected section(s), and a suggestion for what to fix. Include count of passing vs total criteria.
+
+## Review Guidelines
+
+### Be Specific
+
+Instead of: "FRs are incomplete"
+Say: "FR-003 lacks story mapping. Add (Stories: P2) reference."
+
+### Focus on Criteria
+
+Only flag issues that violate a checklist item. Personal preferences don't count unless they affect testability or clarity.
+
+### Don't Rewrite
+
+Identify what's wrong and suggest direction. Don't prescribe exact wording—the Spec Agent makes those decisions.
+
+### Context Matters
+
+Consider workflow mode when reviewing:
+- **Full mode**: Expect comprehensive coverage
+- **Minimal mode**: Accept lighter spec with core FRs only
+- **Custom mode**: Reference Custom Workflow Instructions for expected depth
+
+## Completion Response
+
+Report to PAW agent: pass/fail result, criteria passing count, issues found count, and detailed feedback per Feedback Guidance above. Do NOT make orchestration decisions—return status only.

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

@@ -0,0 +1,160 @@
+---
+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"
+---
+
+# Workflow Status
+
+> **Execution Context**: This skill runs **directly** in the PAW session (not a subagent)—simple diagnostic with no context isolation benefit.
+
+Serve as the workflow navigator and historian. Diagnose current workflow state, recommend next actions, and optionally post updates to Issues/PRs.
+
+> **Reference**: Follow Core Implementation Principles from `paw-workflow` skill.
+
+## Capabilities
+
+- Diagnose current workflow state from artifacts and git
+- Recommend appropriate next steps
+- Explain PAW process and stages
+- List active work items across workspace
+- Post status updates to Issues/PRs (on explicit request)
+
+## Default Behavior
+
+**Report status in chat**—do NOT post to GitHub unless explicitly asked ("post status to issue", "update the PR summary").
+
+## State Detection
+
+### Artifact Discovery
+
+Check `.paw/work/<work-id>/` for:
+- WorkflowContext.md (required for workflow context)
+- Spec.md, SpecResearch.md (specification stage)
+- CodeResearch.md (research stage)
+- ImplementationPlan.md (planning stage)
+- Docs.md (documentation if separate from implementation)
+
+Note existence vs intentionally skipped (minimal mode skips Spec/Docs).
+
+### Phase Counting
+
+Parse ImplementationPlan.md with regex: `^## Phase \d+:`
+- Count distinct phase numbers
+- Report: "Phase N of M" or "Phase N (plan shows M phases total)"
+- Never assume total—always verify
+
+### Git Status
+
+Determine:
+- Current branch: `git branch --show-current`
+- Staged/unstaged changes: `git status --porcelain`
+- Upstream divergence: commits ahead/behind remote
+
+### PR Discovery
+
+For **prs strategy**:
+- Find branches: `<target>_plan`, `<target>_phase*`, `<target>_docs`
+- Query PRs by head branch
+- Capture: URL, state (open/merged/closed), CI status
+
+For **local strategy**:
+- Focus on target branch and Final PR only
+
+### PR Review Comments
+
+When PRs exist:
+- Fetch inline review comments and general discussion
+- Compare comment timestamps vs commit history
+- Summarize: "X comments (Y addressed, Z outstanding)"
+
+## Workflow Stage Progression
+
+Map state to guidance:
+
+| State | Recommendation |
+|-------|----------------|
+| Missing Spec.md + full mode | "Start specification: `spec`" |
+| Spec.md exists, no CodeResearch.md | "Run code research: `research`" |
+| 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`" |
+
+## Workflow Mode Behavior
+
+### Full Mode
+Expect: Spec → Spec Research (optional) → Code Research → Plan → Implementation (multi-phase) → Docs → Final PR
+
+### Minimal Mode
+Expect: Code Research → Plan → Implementation (single phase) → Final PR
+Skips: Spec, Spec Research (local strategy enforced)
+
+### Custom Mode
+Inspect disk to discover actual stages per Custom Workflow Instructions.
+
+## Multi-Work Management
+
+When asked "What PAW work items do I have?":
+- Enumerate `.paw/work/` directories with WorkflowContext.md
+- Report: Work Title, Work ID, target branch, last modified, current stage
+- Sort by most recently modified
+
+## Issue/PR Updates (Opt-in Only)
+
+Only post externally when explicitly asked.
+
+**Issue comments**:
+- Prefix: `**🐾 Status Update 🤖:**`
+- Include: Artifacts, PRs, phase checklist
+
+**PR body updates**:
+- Only modify content inside `<!-- BEGIN:AGENT-SUMMARY -->` / `<!-- END:AGENT-SUMMARY -->` block
+- Preserve all other text
+
+**Never**:
+- Modify issue descriptions
+- Assign reviewers
+- Change labels
+
+## Help Mode
+
+When asked "What does <stage> do?", provide:
+1. Purpose of the stage
+2. Required inputs/artifacts
+3. Expected outputs
+4. Typical duration
+5. Command to run
+
+For implementation details (e.g., two-agent pattern, delegation mechanics), reference `paw-workflow` skill.
+
+For "How do I start?", explain:
+- `PAW: New PAW Workflow` command
+- Parameters (branch, mode, strategy, issue URL)
+- That prompt files generate on demand
+
+## Status Dashboard Format
+
+Synthesize findings into sections:
+- **Artifacts**: Existence and status
+- **Phases**: Current progress (N of M)
+- **Branch & Git**: Current state, divergence
+- **PRs**: Open/merged status, review comments
+- **Next Actions**: Recommended commands
+
+## Guardrails
+
+- Verify phase count from ImplementationPlan.md—never assume
+- Never mutate issue descriptions or PR content outside summary blocks
+- Never push, merge, or rewrite git history
+- Be idempotent: same state → same summary
+- If required info missing, state blocker and resolution
+
+## Completion Response
+
+Report:
+- Current workflow state
+- Recommended next action with command
+- Any blockers or warnings
+- PR/branch status summary