# Paw Init > Bootstrap skill for PAW workflow initialization. Creates WorkflowContext.md, directory structure, and git branch. Runs before workflow skill is loaded. Use when this capability is needed. - Skill: `tomevault-io/paw-init` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/paw-init` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/paw-init/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-init --- # 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//` 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` | `@` | | `execution_binding` | No | `none` | `worktree::` | | `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:` (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:` (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: 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 ```yaml 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:`): `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/.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/.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 `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:` 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 names - `final_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 names - `planning_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// └── WorkflowContext.md ``` ### WorkflowContext.md Created at `.paw/work//WorkflowContext.md` with all input parameters: ```markdown # WorkflowContext Work Title: Work ID: Base Branch: Target Branch: Execution Mode: Repository Identity: Execution Binding: Workflow Mode: Review Strategy: Review Policy: Session Policy: Final Agent Review: Final Review Mode: Final Review Interactive: Final Review Models: Final Review Specialists: Final Review Interaction Mode: Final Review Specialist Models: Final Review Perspectives: Final Review Perspective Cap: Implementation Model: Plan Generation Mode: Plan Generation Models: Planning Docs Review: Planning Review Mode: Planning Review Interactive: Planning Review Models: Planning Review Specialists: Planning Review Interaction Mode: Planning Review Specialist Models: Planning Review Perspectives: Planning Review Perspective Cap: Custom Workflow Instructions: Initial Prompt: Issue URL: Remote: origin 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: `@`. Normalize `origin` to lowercase `host/path` form and strip any trailing `.git` before appending the root commit SHA. - `Execution Binding` format: `worktree::` 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 ...` 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 ` 2. Update base: `git pull origin --ff-only` 3. Create feature branch: `git checkout -b ` 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/` ### Artifact Lifecycle - **`commit-and-clean` or `commit-and-persist`**: WorkflowContext.md committed with message `Initialize PAW workflow for ` - **`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 --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/lossyrob) — claim your Tome and manage your conversions.