@paw-workflow/cli 0.0.1

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

@@ -0,0 +1,134 @@
+---
+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"
+---
+
+# Workflow Transition
+
+> **Execution Context**: This skill runs in a **subagent** session, delegated by the PAW orchestrator when processing a `paw-transition` TODO. Return structured output—do not make orchestration decisions beyond the transition.
+
+## Purpose
+
+Gate between workflow activities. Ensures:
+- Session policy is respected at stage boundaries
+- Correct branch state before implementation
+- Required artifacts exist before proceeding
+- Next activity is correctly identified and queued
+
+## Procedure
+
+Execute these steps in order. Do not skip steps.
+
+### Step 1: Identify Current State
+
+Read WorkflowContext.md to determine:
+- Work ID and target branch
+- Session Policy (`per-stage` | `continuous`)
+- Review Strategy (`prs` | `local`)
+- 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`
+
+Identify last completed activity from TODOs or artifacts.
+
+### Step 2: Determine Next Activity
+
+Use the Mandatory Transitions table:
+
+| After Activity | Required Next | Skippable? |
+|----------------|---------------|------------|
+| paw-init | paw-spec or paw-work-shaping | Per user intent |
+| 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 |
+
+**Skippable = NO**: Add activity TODO and execute immediately after transition completes.
+
+### 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
+
+**Milestones** (require pause check): Spec.md complete, ImplementationPlan.md complete, Phase PR completion, Final PR
+
+**Determine pause_at_milestone**:
+- If at a milestone AND Review Policy ∈ {`always`, `milestones`}: set `pause_at_milestone = true`
+- 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`
+
+**Determine session_action**:
+- If crossing a stage boundary AND Session Policy = `per-stage`: set `session_action = new_session`
+- Otherwise: set `session_action = continue`
+
+If `session_action = new_session`, set inline_instruction to: next activity and phase (e.g., "Phase 2: Tool Enhancement")
+
+Continue to Step 4 (preflight still needed for inline_instruction context).
+
+### Step 4: Preflight Checks
+
+Before the next activity can start, verify:
+
+**For paw-implement**:
+- [ ] On correct branch per Review Strategy
+  - `prs`: phase branch (e.g., `<target>_phase1`)
+  - `local`: target branch
+- [ ] ImplementationPlan.md exists and has the target phase
+
+**For paw-code-research**:
+- [ ] Spec.md exists (unless minimal mode)
+
+**For paw-pr**:
+- [ ] All phases complete
+- [ ] On target branch or ready to merge
+
+**Artifact Tracking Check** (for all activities):
+- Check if `.paw/work/<work-id>/.gitignore` exists
+- If exists with `*` pattern: artifact_tracking = `disabled`
+- Otherwise: artifact_tracking = `enabled`
+
+If any check fails, report blocker and stop.
+
+### Step 5: Queue Next Activity
+
+Add TODO for next activity:
+- `[ ] <activity-name> (<context>)`
+- `[ ] paw-transition`
+
+## Completion
+
+After completing all steps, return structured output:
+
+```
+TRANSITION RESULT:
+- session_action: [continue | new_session]
+- pause_at_milestone: [true | false]
+- next_activity: [activity name and context]
+- artifact_tracking: [enabled | disabled]
+- preflight: [passed | blocked: <reason>]
+- work_id: [current work ID]
+- inline_instruction: [for new_session only: resume hint]
+```
+
+**If pause_at_milestone = true**: The PAW agent must PAUSE and wait for user confirmation before proceeding.
+
+**If session_action = new_session**: The PAW agent must call `paw_new_session` with the provided work_id and inline_instruction.
+
+**If preflight = blocked**: The PAW agent must report the blocker to the user.
+
+Mark the `paw-transition` TODO complete after returning this output.
+
+## Guardrails
+
+- Do NOT skip the stage boundary check (Step 3)
+- Do NOT return session_action = continue if boundary + per-stage policy
+- Do NOT return preflight = passed if checks actually failed
+- Do NOT call paw_new_session directly—return the decision for PAW agent to act on

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

@@ -0,0 +1,99 @@
+---
+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"
+---
+
+# Work Shaping
+
+> **Execution Context**: This skill runs **directly** in the PAW session (not a subagent)—interactive Q&A by design.
+
+Interactive ideation session to transform vague ideas into structured, spec-ready work items.
+
+## When to Use
+
+- User explicitly asks to explore, shape, or flesh out an idea
+- Request has exploratory language ("what if", "maybe we could", "I'm thinking about")
+- User expresses uncertainty ("I'm not sure if...", "not sure how to approach")
+- Idea is too vague for direct specification
+
+## Session Flow
+
+### 1. Opening
+
+Acknowledge the idea and set expectations:
+- This is an exploratory conversation to clarify the work
+- You'll ask questions to understand intent, constraints, and scope
+- User can end anytime; you'll signal when "complete enough"
+
+### 2. Progressive Clarification
+
+Agent-led Q&A to build understanding:
+
+**Question strategy**:
+- One question at a time
+- Start broad (intent, value proposition), then narrow (boundaries, constraints)
+- Offer recommendations when you have informed opinions
+- Prefer multiple choice when options are enumerable
+
+**Topics to explore** (adapt based on idea):
+- Core value: What problem does this solve? Who benefits?
+- Scope boundaries: What's definitely in? What's explicitly out?
+- User interactions: How will users engage with this?
+- Edge cases: What happens when X fails/is empty/conflicts?
+- Success definition: How will we know it works?
+- Constraints: Performance, security, compatibility requirements?
+
+**Codebase research**: When questions arise about existing system behavior, patterns, or integration points, delegate to `paw-code-research` skill via subagent with specific questions. Request findings returned in chat summary rather than full artifact generation. Integrate findings into the conversation.
+
+### 3. Completion Detection
+
+Signal "complete enough" when:
+- Core value proposition is clear
+- Scope boundaries are defined
+- Major edge cases identified
+- No critical unknowns remain
+
+Offer to:
+- Continue exploring specific areas
+- Generate the WorkShaping.md artifact
+- Hand off to specification stage
+
+User can also end anytime with "that's enough", "let's write it up", etc.
+
+### 4. Artifact Generation
+
+Synthesize the conversation into WorkShaping.md.
+
+## Artifact Content
+
+WorkShaping.md should capture:
+- Problem statement (who benefits, what problem is solved)
+- Work breakdown (core functionality vs supporting features)
+- Edge cases with expected handling
+- Rough architecture (component interactions, data flow)
+- Critical analysis (value assessment, build vs modify tradeoffs)
+- Codebase fit (similar features, reuse opportunities)
+- Risk assessment (potential negative impacts, gotchas)
+- Open questions for downstream stages
+- Session notes: key decisions and insights from the Q&A (e.g., scope decisions, rejected alternatives, surprising discoveries)
+
+Use clear section headers. Omit sections that don't apply.
+
+## Artifact Location
+
+**Primary**: `.paw/work/<work-id>/WorkShaping.md` (if work directory exists)
+
+**Fallback**: Workspace root. Prompt user for alternate location if needed.
+
+## Quality Checklist
+
+- [ ] Problem statement is clear and user-focused
+- [ ] Work breakdown covers core and supporting functionality
+- [ ] Edge cases enumerated with expected handling
+- [ ] Architecture sketch shows component relationships
+- [ ] Critical analysis includes value assessment and tradeoffs
+- [ ] Codebase fit identifies reuse opportunities
+- [ ] Risks and gotchas documented
+- [ ] Open questions captured for downstream stages

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

@@ -0,0 +1,142 @@
+---
+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"
+---
+
+# 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 | ImplementationPlan.md |
+| `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-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).
+
+## Artifact Directory Structure
+
+All implementation artifacts are stored in a consistent directory structure:
+
+```
+.paw/work/<work-id>/
+├── 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)
+```
+
+**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
+
+### 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)
+
+Final phase typically includes documentation (Docs.md, README, CHANGELOG).
+
+### 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-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 (`never`: research autonomously; `always`/`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

package/lib/commands/install.js

@@ -0,0 +1,103 @@
+import { existsSync, mkdirSync, readdirSync, copyFileSync } from 'fs';
+import { join } from 'path';
+import { createInterface } from 'readline';
+import {
+  getCopilotAgentsDir,
+  getCopilotSkillsDir,
+  getDistAgentsDir,
+  getDistSkillsDir,
+} from '../paths.js';
+import { readManifest, writeManifest, createManifest } from '../manifest.js';
+
+const VERSION = '0.0.1';
+
+const SUPPORTED_TARGETS = ['copilot'];
+
+async function confirm(message) {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  
+  return new Promise((resolve) => {
+    rl.question(`${message} (y/N) `, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+    });
+  });
+}
+
+function copyDirectory(srcDir, destDir, fileList) {
+  if (!existsSync(destDir)) {
+    mkdirSync(destDir, { recursive: true });
+  }
+  
+  const entries = readdirSync(srcDir, { withFileTypes: true });
+  
+  for (const entry of entries) {
+    const srcPath = join(srcDir, entry.name);
+    const destPath = join(destDir, entry.name);
+    
+    if (entry.isDirectory()) {
+      copyDirectory(srcPath, destPath, fileList);
+    } else if (entry.isFile()) {
+      copyFileSync(srcPath, destPath);
+      fileList.push(destPath);
+    }
+  }
+}
+
+export async function installCommand(target, flags = {}) {
+  if (!SUPPORTED_TARGETS.includes(target)) {
+    throw new Error(`Unsupported target: ${target}. Supported: ${SUPPORTED_TARGETS.join(', ')}`);
+  }
+  
+  const distAgentsDir = getDistAgentsDir();
+  const distSkillsDir = getDistSkillsDir();
+  
+  if (!existsSync(distAgentsDir) || !existsSync(distSkillsDir)) {
+    throw new Error('Distribution files not found. Package may be corrupted.');
+  }
+  
+  const existingManifest = readManifest();
+  const copilotAgentsDir = getCopilotAgentsDir();
+  const copilotSkillsDir = getCopilotSkillsDir();
+  
+  // Check for existing installation
+  const hasExistingFiles = existingManifest || 
+    existsSync(copilotAgentsDir) && readdirSync(copilotAgentsDir).some(f => f.includes('PAW'));
+  
+  if (hasExistingFiles && !flags.force) {
+    const proceed = await confirm('PAW files already exist. Overwrite?');
+    if (!proceed) {
+      console.log('Installation cancelled.');
+      return;
+    }
+  }
+  
+  console.log(`Installing PAW to ${target}...`);
+  
+  const installedFiles = {
+    agents: [],
+    skills: [],
+  };
+  
+  // Copy agents
+  console.log('  Copying agents...');
+  copyDirectory(distAgentsDir, copilotAgentsDir, installedFiles.agents);
+  
+  // Copy skills
+  console.log('  Copying skills...');
+  copyDirectory(distSkillsDir, copilotSkillsDir, installedFiles.skills);
+  
+  // Write manifest
+  const manifest = createManifest(VERSION, target, installedFiles);
+  writeManifest(manifest);
+  
+  const agentCount = readdirSync(distAgentsDir).filter(f => f.endsWith('.md')).length;
+  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');
+}

package/lib/commands/list.js

@@ -0,0 +1,18 @@
+import { readManifest } from '../manifest.js';
+
+export async function listCommand() {
+  const manifest = readManifest();
+  
+  if (!manifest) {
+    console.log('PAW is not installed.');
+    console.log('Run "paw install copilot" to install.');
+    return;
+  }
+  
+  console.log(`PAW v${manifest.version}`);
+  console.log(`Target: ${manifest.target}`);
+  console.log(`Installed: ${new Date(manifest.installedAt).toLocaleString()}`);
+  console.log('');
+  console.log(`Agents: ${manifest.files.agents.length}`);
+  console.log(`Skills: ${manifest.files.skills.length}`);
+}

package/lib/commands/uninstall.js

@@ -0,0 +1,95 @@
+import { existsSync, unlinkSync, rmdirSync, readdirSync } from 'fs';
+import { dirname } from 'path';
+import { createInterface } from 'readline';
+import { readManifest } from '../manifest.js';
+import { getCopilotAgentsDir, getCopilotSkillsDir, getManifestPath } from '../paths.js';
+
+async function confirm(message) {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  
+  return new Promise((resolve) => {
+    rl.question(`${message} (y/N) `, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+    });
+  });
+}
+
+function removeEmptyDirs(dir) {
+  if (!existsSync(dir)) return;
+  
+  try {
+    const entries = readdirSync(dir);
+    if (entries.length === 0) {
+      rmdirSync(dir);
+      removeEmptyDirs(dirname(dir));
+    }
+  } catch {
+    // Ignore errors when cleaning up
+  }
+}
+
+export async function uninstallCommand(flags = {}) {
+  const manifest = readManifest();
+  
+  if (!manifest) {
+    // Check for orphaned files
+    const agentsDir = getCopilotAgentsDir();
+    const skillsDir = getCopilotSkillsDir();
+    const hasPawAgents = existsSync(agentsDir) && 
+      readdirSync(agentsDir).some(f => f.includes('PAW'));
+    const hasPawSkills = existsSync(skillsDir) &&
+      readdirSync(skillsDir).some(f => f.startsWith('paw-'));
+    
+    if (!hasPawAgents && !hasPawSkills) {
+      console.log('PAW is not installed.');
+      return;
+    }
+    
+    console.log('Warning: PAW files found but no manifest. Cannot determine exact files to remove.');
+    console.log('Please manually remove PAW files from ~/.copilot/agents/ and ~/.copilot/skills/');
+    return;
+  }
+  
+  if (!flags.force) {
+    const proceed = await confirm('Remove all PAW agents and skills?');
+    if (!proceed) {
+      console.log('Uninstall cancelled.');
+      return;
+    }
+  }
+  
+  console.log('Uninstalling PAW...');
+  
+  let removedAgents = 0;
+  let removedSkills = 0;
+  
+  // Remove agents
+  for (const filePath of manifest.files.agents) {
+    if (existsSync(filePath)) {
+      unlinkSync(filePath);
+      removedAgents++;
+    }
+  }
+  
+  // Remove skills
+  for (const filePath of manifest.files.skills) {
+    if (existsSync(filePath)) {
+      unlinkSync(filePath);
+      removedSkills++;
+      removeEmptyDirs(dirname(filePath));
+    }
+  }
+  
+  // Remove manifest
+  const manifestPath = getManifestPath();
+  if (existsSync(manifestPath)) {
+    unlinkSync(manifestPath);
+  }
+  
+  console.log(`Removed ${removedAgents} agent files and ${removedSkills} skill files.`);
+  console.log('PAW has been uninstalled.');
+}