| name | paw-init |
| description | Bootstrap skill for PAW workflow initialization. Creates WorkflowContext.md, directory structure, and git branch. Runs before workflow skill is loaded. |
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
| Parameter | Required | Default | Values |
|---|
base_branch | No | main | branch name |
work_id | No | auto-derived from Work Title | lowercase slug |
target_branch | No | auto-derive from work ID | branch name |
execution_mode | No | current-checkout | current-checkout, worktree |
repository_identity | No | none | <normalized-origin-slug>@<root-commit-sha> |
execution_binding | No | none | worktree:<work_id>:<target_branch> |
preset | No | none | preset name (built-in or user-defined) |
workflow_mode | No | full | full, minimal, custom |
review_strategy | No | prs (local if minimal) | prs, local |
review_policy | No | milestones | every-stage, milestones, planning-only, final-pr-only |
| {{#vscode}} | | | |
session_policy | No | per-stage | per-stage, continuous |
| {{/vscode}} | | | |
| {{#cli}} | | | |
session_policy | No | continuous | continuous |
| {{/cli}} | | | |
artifact_lifecycle | No | commit-and-clean | commit-and-clean, commit-and-persist, never-commit |
issue_url | No | none | URL |
custom_instructions | Conditional | — | text (required if workflow_mode is custom) |
work_description | No | none | text |
final_agent_review | No | enabled | enabled, disabled |
final_review_mode | No | multi-model | single-model, multi-model, society-of-thought |
final_review_interactive | No | smart | true, false, smart |
final_review_models | No | latest GPT, latest Gemini, latest Claude Opus | comma-separated model names or intents |
final_review_specialists | No | all | all, comma-separated names, or adaptive:<N> (e.g., adaptive:3) |
final_review_interaction_mode | No | parallel | parallel, debate |
final_review_specialist_models | No | none | none, model pool, pinned pairs, or mixed (see below) |
final_review_perspectives | No | auto | none, auto, comma-separated perspective names |
final_review_perspective_cap | No | 2 | positive integer |
implementation_model | No | none | none (session default), or model name/intent (e.g., gpt-5.4, claude-opus-4.6-1m, latest Claude Opus) |
plan_generation_mode | No | single-model | single-model, multi-model |
plan_generation_models | No | latest GPT, latest Gemini, latest Claude Opus | comma-separated model names or intents |
planning_docs_review | No | enabled (disabled if minimal) | enabled, disabled |
planning_review_mode | No | multi-model | single-model, multi-model, society-of-thought |
planning_review_interactive | No | smart | true, false, smart |
planning_review_models | No | latest GPT, latest Gemini, latest Claude Opus | comma-separated model names or intents |
planning_review_specialists | No | all | all, comma-separated names, or adaptive:<N> (e.g., adaptive:3) |
planning_review_interaction_mode | No | parallel | parallel, debate |
planning_review_specialist_models | No | none | none, model pool, pinned pairs, or mixed (see below) |
planning_review_perspectives | No | auto | none, auto, comma-separated perspective names |
planning_review_perspective_cap | No | 2 | positive integer |
Handling Missing Parameters
When parameters are not provided:
- Apply defaults from the table above
- Check user-level defaults in
copilot-instructions.md or AGENTS.md (these override table defaults)
- If a
preset was specified, apply preset configuration (overrides steps 1-2 for fields the preset defines)
- Apply any explicit user overrides from the current request (override everything)
- Present configuration summary showing the source of each non-default field (preset, user-default, or explicit override) and ask for confirmation
- 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
extends: base-preset
initial_activity: spec
config:
workflow_mode: full
review_strategy: local
Presetable fields: All configuration fields from the Input Parameters table above. Not presetable (per-workflow, ignored with warning if present in config:): base_branch, target_branch, preset, issue_url, custom_instructions, work_description. Fields not in the Input Parameters table (e.g., work_title, 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.
| Preset | Description |
|---|
quick | Minimal ceremony — burns through with no reviews |
standard | Balanced local workflow with milestone review gates |
thorough | Maximum rigor — multi-model planning, SoT debate final |
team | PR-based collaboration with every-stage review |
auto | Autonomous full workflow, only pauses at final PR |
auto-full | Auto + multi-model planning with perspectives + SoT debate final |
shaping-full | Work shaping then auto-full (interactive shaping, auto everything else) |
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):
- Lookup: Check
~/.paw/presets/ first, then references/presets/ for built-in. User presets override built-in presets of the same name.
- Inheritance: If preset has
extends, resolve the base preset recursively (max depth 5). Detect circular chains and report error.
- Merge: Apply fields from base → child (most-specific-wins for each field).
- Validate: Run Configuration Validation on the merged result.
- 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
workflow_mode is minimal, review_strategy MUST be local
- If
review_policy is planning-only or final-pr-only, review_strategy MUST be local
- If
final_review_mode is society-of-thought, final_agent_review MUST be enabled
- If
planning_review_mode is society-of-thought, planning_docs_review 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 final_review_models, plan_generation_models, 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 final_review_mode is society-of-thought:
final_review_specialists and final_review_interaction_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
final_review_specialist_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
final_review_models is ignored (use final_review_specialist_models for model diversity with society-of-thought)final_review_perspectives becomes relevant — validate: none, auto, or comma-separated perspective namesfinal_review_perspective_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 planning_review_mode is society-of-thought:
planning_review_specialists and planning_review_interaction_mode become relevant — validate using the same rules as final review (specialist values, interaction mode)planning_review_specialist_models becomes relevant — validate format using the same rules as final_review_specialist_models (none, pool, pinning, mixed)planning_review_models is ignored (use planning_review_specialist_models for model diversity with society-of-thought)planning_review_perspectives becomes relevant — validate: none, auto, or comma-separated perspective namesplanning_review_perspective_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:<work_id>:<target_branch> 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):
- Checkout base branch:
git checkout <base_branch>
- Update base:
git pull origin <base_branch> --ff-only
- 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
