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) unless work_id is provided explicitly
• 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 lifecycle mode allows it
• Open WorkflowContext.md for review

Input Parameters

{{#vscode}} | sessionpolicy | No | per-stage | per-stage, continuous | {{/vscode}} {{#cli}} | sessionpolicy | No | continuous | continuous | {{/cli}} | artifactlifecycle | No | commit-and-clean | commit-and-clean, commit-and-persist, never-commit | | issueurl | No | none | URL | | custominstructions | Conditional | — | text (required if workflowmode is custom) | | workdescription | No | none | text | | finalagentreview | No | enabled | enabled, disabled | | finalreviewmode | No | multi-model | single-model, multi-model, society-of-thought | | finalreviewinteractive | No | smart | true, false, smart | | finalreviewmodels | No | latest GPT, latest Gemini, latest Claude Opus | comma-separated model names or intents | | finalreviewspecialists | No | all | all, comma-separated names, or adaptive:<N> (e.g., adaptive:3) | | finalreviewinteractionmode | No | parallel | parallel, debate | | finalreviewspecialistmodels | No | none | none, model pool, pinned pairs, or mixed (see below) | | finalreviewperspectives | No | auto | none, auto, comma-separated perspective names | | finalreviewperspectivecap | No | 2 | positive integer | | implementationmodel | No | none | none (session default), or model name/intent (e.g., gpt-5.4, claude-opus-4.6-1m, latest Claude Opus) | | plangenerationmode | No | single-model | single-model, multi-model | | plangenerationmodels | No | latest GPT, latest Gemini, latest Claude Opus | comma-separated model names or intents | | planningdocsreview | No | enabled (disabled if minimal) | enabled, disabled | | planningreviewmode | No | multi-model | single-model, multi-model, society-of-thought | | planningreviewinteractive | No | smart | true, false, smart | | planningreviewmodels | No | latest GPT, latest Gemini, latest Claude Opus | comma-separated model names or intents | | planningreviewspecialists | No | all | all, comma-separated names, or adaptive:<N> (e.g., adaptive:3) | | planningreviewinteractionmode | No | parallel | parallel, debate | | planningreviewspecialistmodels | No | none | none, model pool, pinned pairs, or mixed (see below) | | planningreviewperspectives | No | auto | none, auto, comma-separated perspective names | | planningreviewperspectivecap | No | 2 | positive integer |

Handling Missing Parameters

When parameters are not provided:

1. Apply defaults from the table above
2. Check user-level defaults in copilot-instructions.md or AGENTS.md (these override table defaults)
3. If a preset was specified, apply preset configuration (overrides steps 1-2 for fields the preset defines)
4. Apply any explicit user overrides from the current request (override everything)
5. Present configuration summary showing the source of each non-default field (preset, user-default, or explicit override) and ask for confirmation
6. If user requests changes, update values and re-confirm

Precedence (lowest → highest): table defaults → user-level defaults → preset → explicit overrides.

Ask in this order and allow defaults where permitted.

Preset System

Presets are named bundles of configuration fields that simplify workflow initialization. Users reference a preset by name (e.g., "paw this with quick") instead of specifying individual fields.

Preset File Schema

name: my-preset
description: Short description for listing
default: false          # optional; if true, applied when no preset specified
extends: base-preset    # optional; inherit from another preset
initial_activity: spec  # optional; spec (default), work-shaping, code-research
config:
  workflow_mode: full
  review_strategy: local
  # ... only fields to override

Presetable fields: All configuration fields from the Input Parameters table above. Not presetable (per-workflow, ignored with warning if present in config:): basebranch, targetbranch, preset, issueurl, custominstructions, workdescription. Fields not in the Input Parameters table (e.g., worktitle, work_id, remote) are always non-presetable.

Built-in Presets

Canonical definitions live in references/presets/<name>.yaml. Load the specific preset file when resolving.

User Presets

User presets are YAML files at ~/.paw/presets/<name>.yaml. The filename (minus extension) is the preset name.

Preset Resolution

When a preset is specified (explicitly or via default):

1. Lookup: Check ~/.paw/presets/ first, then references/presets/ for built-in. User presets override built-in presets of the same name.
2. Inheritance: If preset has extends, resolve the base preset recursively (max depth 5). Detect circular chains and report error.
3. Merge: Apply fields from base → child (most-specific-wins for each field).
4. Validate: Run Configuration Validation on the merged result.
5. Initial activity: If the resolved preset has initial_activity, use it for the completion response recommendation instead of the workflow-mode default.

Default preset: If no preset specified, scan user presets for one with default: true. If found, apply it. If multiple defaults found, report conflict and ask user. If none found, use standard PAW defaults. The precedence chain ensures explicit overrides still win over default preset values.

Error Handling

• Unknown preset: Report not found, list available (built-in + user)
• Invalid YAML / circular extends / multiple defaults: Report error, ask user to resolve
• Unknown fields in config:: Warn but don't fail (forward compatibility)
• Empty preset / missing ~/.paw/presets/: Skip gracefully (no-op / no user presets)

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 work_id is provided explicitly, validate and use it instead of regenerating it from the Work Title
• If conflict: append -2, -3, etc.

Configuration Validation

• If workflowmode is minimal, reviewstrategy MUST be local
• If reviewpolicy is planning-only or final-pr-only, reviewstrategy MUST be local
• If finalreviewmode is society-of-thought, finalagentreview MUST be enabled
• If planningreviewmode is society-of-thought, planningdocsreview MUST be enabled
• Invalid combinations: STOP and report error

Model Resolution

Resolve model intents to concrete model names wherever they appear (e.g., "latest GPT" → gpt-5.2, "latest Gemini" → gemini-3-pro-preview, "latest Claude Opus" → claude-opus-4.6). This applies to finalreviewmodels, plangenerationmodels, implementation_model, and all specialist model fields. Present resolved models for user confirmation and store resolved concrete model names in WorkflowContext.md (not the intent strings).

This ensures model selection is a one-time upfront decision during init, not a per-stage interruption.

Society-of-Thought Configuration (society-of-thought only)

When finalreviewmode is society-of-thought:

• finalreviewspecialists and finalreviewinteraction_mode become relevant
• Validate specialist values: all, comma-separated specialist names, or adaptive:<N> where N is a positive integer
• Validate interaction mode: parallel or debate
• finalreviewspecialist_models becomes relevant — validate format:

- none (default): all specialists use session default model - Pool: comma-separated model names (e.g., gpt-5.3-codex, claude-opus-4.6) — distributed round-robin across specialists - Pinning: specialist:model pairs (e.g., security:claude-opus-4.6, architecture:gpt-5.3-codex) — explicit assignment - Mixed: combination of pinned pairs and pool models (e.g., security:claude-opus-4.6, gpt-5.3-codex, gemini-3-pro-preview) — pinned specialists get their model, unpinned draw from pool round-robin - Resolve model intents (e.g., latest GPT) using existing model intent resolution

• finalreviewmodels is ignored (use finalreviewspecialist_models for model diversity with society-of-thought)
• finalreviewperspectives becomes relevant — validate: none, auto, or comma-separated perspective names
• finalreviewperspective_cap becomes relevant — validate: positive integer
• Present society-of-thought config as part of the configuration summary

Planning Review Society-of-Thought Configuration (society-of-thought only)

When planningreviewmode is society-of-thought:

• planningreviewspecialists and planningreviewinteraction_mode become relevant — validate using the same rules as final review (specialist values, interaction mode)
• planningreviewspecialistmodels becomes relevant — validate format using the same rules as finalreviewspecialistmodels (none, pool, pinning, mixed)
• planningreviewmodels is ignored (use planningreviewspecialist_models for model diversity with society-of-thought)
• planningreviewperspectives becomes relevant — validate: none, auto, or comma-separated perspective names
• planningreviewperspective_cap becomes relevant — validate: positive integer
• Present planning review society-of-thought config as part of the configuration summary

Directory Structure

.paw/work/<work-id>/
└── WorkflowContext.md

WorkflowContext.md

Created at .paw/work/<work-id>/WorkflowContext.md with all input parameters:

# WorkflowContext

Work Title: <generated_work_title>
Work ID: <work_id or generated_work_id>
Base Branch: <base_branch>
Target Branch: <target_branch>
Execution Mode: <execution_mode>
Repository Identity: <repository_identity or "none">
Execution Binding: <execution_binding or "none">
Workflow Mode: <workflow_mode>
Review Strategy: <review_strategy>
Review Policy: <review_policy>
Session Policy: <session_policy>
Final Agent Review: <final_agent_review>
Final Review Mode: <final_review_mode>
Final Review Interactive: <final_review_interactive>
Final Review Models: <final_review_models>
Final Review Specialists: <final_review_specialists>
Final Review Interaction Mode: <final_review_interaction_mode>
Final Review Specialist Models: <final_review_specialist_models>
Final Review Perspectives: <final_review_perspectives>
Final Review Perspective Cap: <final_review_perspective_cap>
Implementation Model: <implementation_model or "none">
Plan Generation Mode: <plan_generation_mode>
Plan Generation Models: <plan_generation_models>
Planning Docs Review: <planning_docs_review>
Planning Review Mode: <planning_review_mode>
Planning Review Interactive: <planning_review_interactive>
Planning Review Models: <planning_review_models>
Planning Review Specialists: <planning_review_specialists>
Planning Review Interaction Mode: <planning_review_interaction_mode>
Planning Review Specialist Models: <planning_review_specialist_models>
Planning Review Perspectives: <planning_review_perspectives>
Planning Review Perspective Cap: <planning_review_perspective_cap>
Custom Workflow Instructions: <custom_instructions or "none">
Initial Prompt: <work_description or "none">
Issue URL: <issue_url or "none">
Remote: origin
Artifact Lifecycle: <artifact_lifecycle>
Artifact Paths: auto-derived
Additional Inputs: none

Execution Contract

• If Execution Mode is absent in an older context, treat it as current-checkout.
• Repository Identity and Execution Binding are portable proof only. Never write machine-local execution paths into WorkflowContext.md.
• Repository Identity format: <normalized-origin-slug>@<root-commit-sha>. Normalize origin to lowercase host/path form and strip any trailing .git before appending the root commit SHA.
• Execution Binding format: worktree:<workid>:<targetbranch> in worktree mode; otherwise write none.
• Write these strings exactly in WorkflowContext.md and compare them literally.

{{#vscode}}

• Use the local execution registry to map Repository Identity + Execution Binding to the canonical execution checkout path for reuse and recovery.
• In worktree mode, create, reuse, or validate the execution checkout before continuing. If validation fails, STOP and give recovery guidance: git worktree list, reopen the execution checkout, or re-initialize.

{{/vscode}} {{#cli}}

• Do not assume a registry or automatic handoff into another checkout.
• In worktree mode, prove the intended execution checkout path with WorkflowContext.md, git worktree list, and the repo/branch/worktree state for that candidate checkout before continuing. The session cwd may differ from the execution checkout when that path is already known or can be derived safely.
• When the session cwd differs, run git commands against that candidate/proven execution checkout path (for example, git -C <execution-checkout-path> ... or switch cwd there) and keep artifact writes there. Do not treat the caller checkout's branch/status as authoritative proof, fallback, or a mutation target.
• If proof fails (execution checkout unknown, branch mismatch, missing metadata), STOP and give recovery guidance: git worktree list, identify or reopen the execution checkout, or re-initialize in current-checkout mode.

{{/cli}}

• After the execution checkout is identified and proven, later workflow stages stay scoped to that checkout; they do not try to rediscover or auto-repair execution state from the caller checkout.
• Classify failures clearly:

- missing dedicated-worktree metadata → half-initialized worktree {{#vscode}} - missing or stale registry path → orphaned binding {{/vscode}} {{#cli}} - execution checkout cannot be proven from this session → unknown checkout; stop and recover before continuing {{/cli}} - repository, binding, or branch mismatch → invalid reuse; do not guess or auto-repair

Git Branch

Branch creation and checkout follows paw-git-operations patterns.

Branch creation sequence (REQUIRED):

1. Checkout base branch: git checkout <base_branch>
2. Update base: git pull origin <base_branch> --ff-only
3. Create feature branch: git checkout -b <target_branch>

Never create feature branch from current HEAD without explicit checkout of base.

• Target branch exists and is checked out
• If explicit branch provided: use as-is (prompt if exists)
• If auto-derive: feature/<work-id>

Artifact Lifecycle

• commit-and-clean or commit-and-persist: WorkflowContext.md committed with message Initialize PAW workflow for <Work Title>
• never-commit: .gitignore with * created in work directory as a local-only lifecycle marker; WorkflowContext.md is NOT committed and the marker itself remains untracked

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. Next step defaults by workflow mode (full → spec, minimal → code research, custom → per instructions) but is overridden by the preset's initial_activity if set (e.g., work-shaping).

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 lifecycle is commit-and-clean or commit-and-persist)
• WorkflowContext.md opened for review