Reference
The project overlay directory
Everything under {repo}/.paintedwolf/ that you author is committed with your code:
| Path | Purpose |
|---|---|
extensions.yaml | Pack desired state (format: 1) |
extensions.lock.yaml | Exact pack resolution (lock_format: 1) |
workflows/<id>/workflow.yaml | Custom workflows |
AGENTS.md | Human-authored guidance per the agents.md standard — see agents-md-standard.md |
mcp.yaml | MCP overlay — loopback HTTP only |
scanners.yaml | Scanner enables (id + enabled only) |
detection-packs.yaml | Detection-pack enables (id + enabled only) |
postures.yaml | Session posture retuning — the four shipped ids only |
prompt_files/ | Prompt template overrides |
approvals.yaml, limits.yaml, verify.yaml | Settings overlays — see Configuration |
blueprints/ | Workflow-governed planning documents |
Host-managed evidence, caches, checkpoints, and worktrees live under ~/.config/paintedwolf/, outside the project overlay. Credentials never belong in a repo.
CLI
Put the bundled pw binary on your PATH first — see Command-line tool. Everyday project commands (pw ., ls, logs, completion) live there.
pw extensions install <url|file://…|path:…> [--version RANGE|--ref REF] [--project DIR|--device]
pw extensions install-meta <url|file://…|path:…> [--version RANGE|--ref REF] [--project DIR|--device]
pw extensions remove <pack-id> [--project DIR|--device]
pw extensions remove-meta <meta-pack-id> [--project DIR|--device]
pw extensions update <pack-id>
pw extensions reload <pack-id>
pw extensions lock [--project DIR|--device] [--json]
pw extensions validate [--project DIR|--device] [--json]
pw extensions apply-profile <pack-id> <profile-name> [--project DIR|--device]
pw extensions disable|enable <unit-id> [--project DIR|--device]
pw extensions own <unit-id> <pack-id> [--project DIR|--device]
pw extensions enable-suite|disable-suite <meta-pack-id> [--project DIR|--device]
pw workflow validate [--bundled] [--json] [--project DIR] [PATH…]
pw rules test [--project DIR] [--json] [PATH…]
pw prompts render <template-ref> [--project DIR] [--var k=v]… [--json]
pw prompts render --agent <id> [--project DIR] [--check] [--json]
pw scan engines list|check|validate [--project DIR]
Default scope is the current project; pass --device for machine-wide desired state. validate exits 1 on conflicts or binding errors, so it slots into CI.
rules test and prompts render are the verify half of the author loop. Both are read-only and both exit 1 when something is wrong:
| Verb | Exits 1 when |
|---|---|
rules test | A rule fails schema validation, its when: does not compile, or a fixture disagrees. --json emits a stable code |
prompts render --check | A rendered persona is missing a required heading or exceeds its byte budget |
Workflow diagnostics
workflow validate emits stable codes — branch on code, never on message text. Generated from the engine registry:
Show all workflow diagnostic codes
| Code | Meaning | Fix |
|---|---|---|
ambient_unresolved | default_ambient_workflow {{workflow_id}}@{{version}} is not in the registry. | Fix registry.yaml to point at a shipped ambient workflow. |
boolexpr_parse | Boolean expression parse error: {{detail}}. | Fix the complete_when / entry_when / when expression syntax. |
catalog_only_predicate | Catalog-only condition {{leaf}} cannot gate bundled workflows. | Use a shipped host predicate, or keep this leaf for catalog-only compose stubs. |
decision_gate_phase_mismatch | Decision gate {{leaf}} does not match phase {{phase}}. | Align decision gate and intake key. |
decision_gate_phase_missing | user_decision_received gate references missing phase {{phase}}. | Align the gate with a phase that declares intake decisions. |
depth_param_missing | Phase {{phase}} depth_param {{param}} is not a depth-typed parameter. | Declare parameters.{{param}} with type: depth. |
domain_leaf_on_overlay | Domain leaf {{leaf}} is bundled-only and cannot appear in custom overlays. | Use a generic gate-kit leaf such as evidence_passed:verify, hitl_consulted:<phase>, or human_approval. See docs/workflows.md#custom-workflows. |
extends_cycle | extends cycle detected. | Remove the cycle in the extends chain. |
extends_depth_exceeded | extends depth exceeded. | Shorten the extends chain (max depth 3). |
extends_error | extends error: {{detail}}. | Fix the extends chain. |
extends_not_allowed | extends parent {{extends}} is not in the compose policy allowlist. | Extend an allowed parent (see compose-policy.yaml). |
extends_required | Session compose requires extends when require_extends is enabled. | Set extends: to an allowed parent. |
feedback_gate_phase_mismatch | Feedback gate {{leaf}} does not match phase {{phase}} feedback key. | Align gate leaf and on_enter.request_user_feedback. |
feedback_gate_phase_missing | user_feedback_received gate references missing phase {{phase}}. | Align the gate suffix with a phase that declares request_user_feedback. |
feedback_options_required | Phase {{phase}}: choice feedback requires at least two options. | Add options: with two or more entries. |
forbidden_predicate | Forbidden predicate {{leaf}}. | {{replacement_hint}} |
intake_catalog_error | Intake catalog error on phase {{phase}}: {{detail}}. | Fix the intake: block. |
intake_gate_missing | Phase {{phase}} declares intake but lacks the matching decision/consulted gate. | Add user_decision_received or hitl_consulted for the intake key. |
intake_gate_phase_mismatch | Intake gate {{leaf}} does not match phase {{phase}}. | Align hitl_consulted / intake keys with the phase id. |
intake_key_unknown | Intake key {{key}} on phase {{phase}} is unknown. | Use a declared intake key. |
invalid_execution_mode | Invalid execution mode {{mode}}. | Use a valid execution mode. |
invalid_icon | Unknown icon slot {{icon}}. | Name a host icon slot. An unknown name falls back to the generic workflow mark. |
invalid_posture | Unknown posture {{posture}}. | Use a valid session posture id. |
invoke_child_has_invoke | Child workflow {{workflow_id}}@{{version}} declares invoke_workflow (nesting depth 1 only). | Remove invoke_workflow from the child manifest. |
invoke_unresolved | invoke_workflow target {{workflow_id}}@{{version}} is not in the registry. | Point invoke_workflow at a known id@version. |
load_error | Failed to load workflow catalog: {{detail}}. | Fix YAML syntax or path errors and re-run validate. |
merchandising_incomplete | Catalog workflow is missing merchandising field {{field}}. | Set name, description, and trigger for drawer listing. |
missing_gate_feedback | Gate leaf {{leaf}} has no gate-feedback YAML. | Add config/packs/painted-wolf/platform/guidance/gate-feedback for this leaf. |
missing_hitl_tools | Phase {{phase}} implies HITL tools but surface {{surface}} is missing {{tool}}. | Add {{tool}} to the resolved surface tools (ask_user and wait are required when gates/on_enter imply tool-ask or intake). |
missing_kick | Template id {{kick}} does not resolve to a guidance template in any enabled pack, or in this manifest's own pack. | Add guidance/{{kick}}.md to the pack that ships this manifest, or point render / inject_kick at a template that exists. |
missing_mode_ref | Mode ref {{mode_ref}} does not resolve to a prompt file ({{path}}). | Add the coordinator-mode partial under config/packs/painted-wolf/platform/agents/prompts/. |
missing_review_verdict_tool | review_loop phase {{phase}} requires {{tool}} on surface {{surface}} — a terminal verdict is the only leave. | Add {{tool}} to the surface tools for phase {{phase}}. |
missing_surface_template | Surface template {{path}} does not exist. | Point surface_template at an existing agents/… prompt under config/packs/painted-wolf/platform/agents/prompts/. |
missing_tool_for_advance_policy | Coordinator-owned advance on phase {{phase}} requires {{tool}} on surface {{surface}}. | Add {{tool}} to the surface tools, or set advance.when_gate_met: auto. |
overlay_requires_explicit_surface | Custom overlay phase {{phase}} must set coordinator_surface, surface_template, and mode_refs. | Declare all three fields on the phase; do not rely on shipped surface_profile alone. |
phase_cycle | Phase graph cycles at {{phase}}. | Break the next-link cycle. |
phase_dangling_next | Phase {{phase}} next {{next}} is not a declared phase. | Fix next to a declared phase id or leave it empty for terminal. |
phase_unreachable | Phase {{phase}} is never reachable from the start phase. | Wire next links so every phase is reachable, or remove the orphan phase. |
prompt_required | Phase {{phase}}: request_user_feedback.prompt is required. | Set on_enter.request_user_feedback.prompt. |
required_gate_missing | Posture {{posture}} requires gate {{gate}}. | Add the required gate to the closeout or terminal phase. |
required_phase_missing | extends {{extends}} requires phase {{phase}} in the effective manifest. | Add the required phase id. |
review_loop_evidence_unreferenced | Phase {{phase}} review_loop evidence_key {{key}} is not in gates as evidence_passed:{{key}}. | Add evidence_passed:{{key}} to the phase gates. |
review_loop_incomplete | review_loop evidence_key {{key}} is missing gate-feedback or verdict fixture closure. | Add gate-feedback YAML and a verdict fixture for this evidence key. |
rules_path_missing | Rules path {{path}} was not found under bundled or project config. | Fix the rules: entry to a real relative path. |
spawn_not_subset | Spawn allowlist agent {{agent}} is not in implement allowed_agents. | Add the agent to implement/workflow.yaml allowed_agents or remove it from implement-default-spawn.yaml. |
surface_missing_update_progress | Surface {{surface}} lists progress-gated tools but omits update_progress. | Add update_progress to the surface tools list in coordinator-surfaces.yaml. |
terminal_requires_orchestration_complete | Terminal phase {{phase}} must use complete_when: orchestration_complete. | Set complete_when: orchestration_complete on every terminal: true phase. |
topology_bind_unknown | Phase {{phase}} binds topology stage {{stage}} which is not in topology {{topology}}. | Set bind_topology_stage to a pipeline.stages[].name from the topology YAML. |
topology_missing | Topology {{topology}} is missing or failed to load. | Add a YAML file under config/packs/painted-wolf/platform/workflows/_topologies/ for this topology id. |
topology_stage_complete_unbound | Phase {{phase}} uses topology_stage_complete without bind_topology_stage. | Set bind_topology_stage to a topology stage name. |
unknown_agent | Unknown agent {{agent}}. | Use an agent id from config/catalog/agents. |
unknown_evidence_key | Unknown evidence_passed key {{key}}. | Use a typed evidence key (verify, test, security, or a known review-family key). |
unknown_extends_parent | Unknown extends parent {{extends}}. | Point extends at a known id@version. |
unknown_predicate | Unknown or unregistered condition {{leaf}}. | Use a registered gate or complete_when leaf from the condition registry. |
unknown_readiness | human_approval.readiness leaf {{leaf}} is not registered. | Use a registered condition leaf for readiness. |
Extension resolve codes are on the packs page.
Stock packs
The shipped baseline your desired state starts from — all enabled by default:
| Pack | Units | Requires | What it provides |
|---|---|---|---|
painted-wolf/browser | 49 | painted-wolf/platform | Browser tooling capability for agents that drive a real page. |
painted-wolf/bugbash | 1 | painted-wolf/platform | The /bugbash workflow — hunt bugs in parallel, choose what to fix, verify. |
painted-wolf/hitl | 18 | painted-wolf/platform | Human-in-the-loop consult surfaces — ask, wait, and approval plumbing. |
painted-wolf/implement | 27 | painted-wolf/platform | The ambient implement workflow that attaches to every session. |
painted-wolf/options | 1 | painted-wolf/platform | The /options workflow — explore alternatives before committing to one. |
painted-wolf/plan | 38 | painted-wolf/platform | The /plan workflow — research, blueprint, and approval phases. |
painted-wolf/platform | 1311 | — | The mandatory base — coordinator, core agents, native tool policy, anchors, and surfaces. It cannot be disabled or removed. |
painted-wolf/recon-pack | 7 | painted-wolf/platform | The /recon workflow — read-only fan-out reconnaissance. |
painted-wolf/refactor | 1 | painted-wolf/platform | The /refactor workflow — staged, verified restructuring. |
painted-wolf/scan-guidance | 19 | painted-wolf/platform | Policy, bindings, and guidance around security scanners. Contains no engines — scanners are enabled in Settings. |
painted-wolf/security | 478 | painted-wolf/platform | Guardrail policy and review behavior. Default on; may be disabled. |
painted-wolf/security-survey | 11 | painted-wolf/platform | The /security-survey workflow — parallel security review of a codebase. |
painted-wolf/themes | 9 | — | Ports of widely used cross-editor palettes. Themes only — it contributes no commands or behavior, so enabling it can change nothing but how the window looks. |
painted-wolf/web-research | 20 | painted-wolf/platform | Web research capability — agents, tools, and guidance for sourced external research. |
Schemas
You do not need these to author — extensions validate, workflow validate, and rules test check your files against them. Reach for a schema when you’re building tooling of your own. The Open Agent Rules schema is published on the standard’s own site; the rest are host schemas, mirrored in the product repo:
| Schema | Validates |
|---|---|
oar.schema.json | Open Agent Rules documents |
anchor-binding.schema.json | Guidance bindings (and workflow injects:) — anchor ids are catalogued here |
selector.schema.json | The shared selector vocabulary |
workflow_vocabulary.json | The full gate/condition leaf catalog |
fixtures/ | Reference documents for each of the above |
Host API
The app’s client talks to the local engine over REST + SSE on 127.0.0.1. Sessions, prompts, streams, extensions, MCP, and scanners are documented in the API reference. The API evolves additively where possible and is versioned with the app. Build against it for local tooling and pin the app version you test with.
Wire shapes, editor leases, and workflow revision conflicts are in host-contract.md.
Stability contract
| Surface | Promise |
|---|---|
Code: ids, native tool names, reject shape | Stable — a retired code is never reused |
| Pack host contract | Declared as compatibility.extension_api on extension.yaml — see packs |
| Prompt and guidance wording | Ships with the app; not a separate version stream |
{repo}/.paintedwolf/** formats | Additive-preferred; extensions.yaml is format: 1 |
| OAR documents | Portable spec, oar: '1.0' |
| Gate kit, unit kinds, diagnostic codes | Published with the v1 documentation from the engine catalogs |
| Local HTTP API | Versions with the app — see API reference |