SDK

Workflows, agents, prompts, rules, and themes ship as extension packs: plain YAML and Markdown loaded by the app. These pages are the authoring guides. Engine contracts — Resolve algebra, prompt assembly, the host threat model — live in the product repository.

A pack is a directory in a git repo; a project override is a file committed under {repo}/.paintedwolf/.

What you can build

Put pw on your PATH before the tutorial — see Projects.

The three layers

The app combines bundled and device-installed packs with reviewed project customization:

Packs install on the device. A project can suggest packs and disable eligible shared units; it cannot replace device ownership or strip device enforcement. The property table is on Extension packs → Unit kind properties.

Vocabulary tables on these pages are generated from the v1 engine. Packs declare host compatibility with compatibility.extension_api. See Reference for schemas and the stability contract.

This tutorial builds Triage Lite: a slash command that investigates, reports, and waits for a human before changing anything. It combines a workflow, an Open Agent Rule, and a prompt inject. Every example below is tested by the engine.

You need the app installed and the pw CLI on your path (setup).

1. The manifest

Make a directory called triage-lite and put this in it. The manifest is what turns a directory into a pack:

manifest_version: 1
id: acme/triage-lite
name: Triage Lite
version: 1.0.0
description: A minimal pack — one workflow, one rule, one inject template.
compatibility:
  extension_api: "^1.0.0"
dependencies:
  painted-wolf/platform:
    version: "^1.0.0"

compatibility.extension_api is the host-contract gate — a SemVer range the host must satisfy. A mismatched range leaves the pack installed but non-contributing (extension_api_incompatible). dependencies names packs that must be contributing (with their own version ranges); every pack depends on painted-wolf/platform. Prompt wording in stock packs updates with the app and is not a separate version field — see Extension packs.

2. The workflow

A workflow is an ordered list of phases, each declaring what has to be true before the run moves on. Ours has two: investigate, then done.

id: triage-lite
version: 1.0.0
name: Triage Lite
description: Look at the problem, write up what you found, and stop for a human.
trigger: /triage-lite
request:
  question: What problem should this triage investigate?
initial_posture: spec
blueprint:
  id: triage
  file: triage-lite.md
injects:
  - on: phase.entered
    selector:
      workflow: triage-lite
      phase: investigate
    effect: inform
    render: triage-lite-plan
    tier: workflow
phases:
  - id: investigate
    activity_label: Investigating the problem
    blueprint_write: true
    coordinator_surface: plan_research
    surface_template: agents/coordinator-surface-orchestrate.md
    mode_refs: [plan-research]
    complete_when: gates_satisfied
    gates: [human_approval]
    advance:
      when_gate_met: auto
    human_approval:
      blueprint: triage-lite.md
    next: done
  - id: done
    activity_label: Done
    coordinator_surface: await_user
    surface_template: agents/coordinator-surface-plan.md
    mode_refs: [await-user-input]
    terminal: true
    complete_when: orchestration_complete

Three declarations do the work:

• Every phase names its surface. coordinator_surface, surface_template, and mode_refs are required, including on the terminal phase. The surface is the tool ceiling.
• The gate is a human. gates: [human_approval] renders an Approve button. Chat never approves. advance.when_gate_met: auto advances as soon as the gate is met.
• The inject is the pack’s own guidance. The injects: entry fires when the phase is entered and renders a template from this pack’s guidance/ directory.

Every field the loader understands is in the manifest reference.

3. The rule

A workflow says what the run does. A rule says what it may never do. This one blocks writes for as long as the run holds the spec posture:

oar: '1.0'
id: TRIAGE_LITE_WRITE_FORBIDDEN
kind: policy
anchor: tool.pre_invoke
selector:
  tool:
    - write
    - edit
requires:
  profiles:
    - session
    - tool
when: session_posture == "spec"
effect: block
enforcement: enforce
on_error: fail_closed
copy:
  title: Triage Lite is read-only
  what: A write tool was called during triage.
  cause: The triage-lite workflow reports findings; it does not change files.
  why: Triage runs in the spec posture, where the project tree stays untouched.
  fix: Record the finding in your write-up, then leave triage before editing.
  instead: Branch on Code TRIAGE_LITE_WRITE_FORBIDDEN and report instead of writing
x-paintedwolf-emit: rule:triage_lite
x-paintedwolf-message: Triage Lite is a read-only workflow.
x-paintedwolf-scenarios:
  - id: default
    vars:
      tool: write
      path: src/main.go
      profile: coordinator
    expect_contains:
      - 'Rejected:'
      - 'Code: TRIAGE_LITE_WRITE_FORBIDDEN'
      - leave triage

The filename is the rule id and the Code: an agent receives when it fires. when: uses the typed OAR condition language over the closed fact catalogue; unknown facts fail at load. copy: supplies the rejection guidance, and x-paintedwolf-scenarios: tests it.

4. Prove the rule both ways

A rule that only fires is half-tested. Put conformance fixtures in a conformance/ directory beside policy/ — given these facts, expect this decision:

{
  "name": "triage-lite-write-blocked",
  "rule": {
    "oar": "1.0",
    "id": "TRIAGE_LITE_WRITE_FORBIDDEN",
    "kind": "policy",
    "anchor": "tool.pre_invoke",
    "selector": { "tool": ["write", "edit"] },
    "requires": { "profiles": ["session", "tool"] },
    "when": "session_posture == \"spec\"",
    "effect": "block",
    "enforcement": "enforce",
    "on_error": "fail_closed",
    "x-paintedwolf-emit": "rule:triage_lite"
  },
  "input": {
    "anchor": "tool.pre_invoke",
    "facts": { "tool": "write", "session_posture": "spec" }
  },
  "expected": { "decision": "block", "code": "TRIAGE_LITE_WRITE_FORBIDDEN" }
}

{
  "name": "triage-lite-write-allowed-outside-spec",
  "rule": {
    "oar": "1.0",
    "id": "TRIAGE_LITE_WRITE_FORBIDDEN",
    "kind": "policy",
    "anchor": "tool.pre_invoke",
    "selector": { "tool": ["write", "edit"] },
    "requires": { "profiles": ["session", "tool"] },
    "when": "session_posture == \"spec\"",
    "effect": "block",
    "enforcement": "enforce",
    "on_error": "fail_closed",
    "x-paintedwolf-emit": "rule:triage_lite"
  },
  "input": {
    "anchor": "tool.pre_invoke",
    "facts": { "tool": "write", "session_posture": "build" }
  },
  "expected": { "decision": "allow" }
}

Same rule, same tool, different posture — one blocks, one doesn’t. The rule document itself is a portable Open Agent Rules document; the fixture format is the engine’s own runner format.

5. The inject template

Finally, the guidance the coordinator sees when the investigate phase opens. Templates use the bounded pongo2 syntax with a Markdown body:

Triage Lite is running. Report what you find; do not change files.

{% if workflow_phase %}Phase: {{ workflow_phase }}.{% endif %}
Finish with a short write-up, then ask for the human's sign-off.

The render: triage-lite-plan in the manifest resolves to this file: the host adds the directory and the .md for you.

6. Validate and install

From the directory that contains triage-lite/:

pw extensions install path:./triage-lite
pw extensions validate
pw workflow validate triage-lite/workflows/triage-lite/workflow.yaml
pw rules test triage-lite/policy

Expect a contributing pack, zero workflow errors, and one rule with two passing scenarios.

install path: links the folder on this device, so the pack you keep editing is the pack the app loads. Repositories can suggest the pack to teammates through their extension settings.

If a fixture disagrees, rules test exits 1 with scenario_mismatch. The author loop is write, validate, read the code, and fix.

7. See it in the app

Open Settings → Extensions. acme/triage-lite is listed with its three units. Type /triage-lite in a session and the workflow starts; the investigate phase opens with your inject in the coordinator’s context, and the run stops at the approval button.

Iterating: edit the folder, hit Reload from disk, start a new turn. Installed-from-folder packs re-read their source on Reload, so there is no reinstall step while you work.

8. Read the prompt you shipped

A template that fails to parse is an error. A template with a typo’d variable is not — it renders empty and reports nothing, so rendering it is the only way to catch that:

pw prompts render --agent implementer --project . --check

That renders a full persona through the same layers a live session uses, and --check adds the heading contract and the byte budget on top. Drop --agent and pass a template ref instead to render one file, with --var k=v for context.

Where to go next

A pack is a directory of units—commands, workflows, rules, guidance, agents, and tool policy—plus extension.yaml. Installed packs compose with the stock catalog under one deterministic rule. The engine contract is extend.md in the product repository.

Resolve: provide − disabled ⊕ own

Every enabled pack contributes every unit id it ships (provide). Your desired state can subtract single units or whole packs (disabled), and when two packs provide the same unit id, it names the winner (own). Everything else fails closed:

disabled and own work per unit, while pack enablement covers the whole set. A referenced unit that is disabled or unresolved fails the load by name.

Pack layout

my-pack/
  extension.yaml        # manifest (required)
  policy/               # Open Agent Rules, one file per rule
  guidance/             # kick + inject + tool-feedback templates
  workflows/            # <id>/workflow.yaml manifests
  agents/               # persona YAML + prompts/ (incl. _persona-contract.yaml)
  tools/                # catalogs, profiles/, schemas/<name>.yaml
  approvals/            # **/explain.yaml copy + rules/<id>.yaml policy
  playbooks/            # worker leg checklists
  skills/               # <name>/SKILL.md task procedures (device-only units)
  host/bindings/        # anchor bindings (units)
  host/user-notices/    # notice copy, one file per code (units)
  host/detection-packs/ # Sigma packs (units) — device-only, never ownable
  host/credential-slots/ # credential-slot recognition (units) — device-only, never ownable
  shared/               # archetypes/, partials/ — include-target trees; units/ — per-turn prompt units
  mcp_bindings/         # typed MCP result projections (device scope)
  contributions/        # device-scoped commands, menus, keybindings, editor-actions,
                        #   search-sources, operations, themes, configuration,
                        #   mcp-requirements
  profiles/             # named enable/disable/own sets (not units)

Unit kind properties

Packs install on the device. A project’s extensions.yaml may suggest an install and disable eligible units from that catalog:

own: chooses between colliding unit ids in device settings. Contribution and detection-pack ids include the providing pack, so own: never applies to them. Project skills live separately under .paintedwolf/skills/ or .agents/skills/.

The generated table is authoritative for ids, class, and whether own: is allowed:

Contributions

contributions/ adds to the interface: one YAML document per file. Every vocabulary is closed — an unknown action, slot, or token id is a build error — and pw extensions validate compiles the same graph the app does.

One command owns its title, relevance, enablement, typed input or interaction, action, and result. Crossbar, menus, keybindings, and editor placements are invocation routes for that command; commands appear in Crossbar unless they set palette: false.

contributions/search-sources/ adds an explicit provider-backed source. It runs only after the user selects that source or types its prefix, and selecting a result invokes a command from the same pack.

Direct contribution references stay inside the declaring pack. Cross-pack behavior goes through a typed operation under contributions/operations/ and a direct manifest dependency.

Packs never ship processes. MCP provider bodies, scanner engines, and binaries are forbidden. A pack may refer to them with requires_mcp / requires_scanners, which blocks the pack from contributing until the operator enables the dependency.

The manifest

# extension.yaml
manifest_version: 1
id: acme/triage
name: Acme Triage
version: 1.0.0
compatibility:
  extension_api: "^1.0.0"   # SemVer range over the host extension contract
dependencies:
  painted-wolf/platform:
    version: "^1.0.0"

manifest_version is the YAML document shape. compatibility.extension_api is the host contract — currently 1.0.0. A range that does not include the host leaves the pack installed but non-contributing (extension_api_incompatible).

What compatibility covers

Prefer new unit ids. Use own when you need to replace one colliding id.

Approval explanations

When a tool call needs consent, approvals/**/explain.yaml is the copy in that dialog — what is about to change, who it touches, and what happens if it was the wrong call. Required fields: what_changes, who_affected, if_wrong, allow_line, plus at least one scenarios render sample. Copy fields are pongo2 templates.

Approval rules

Packs may ship additive policy under approvals/rules/<rule-id>.yaml. Each file is one document with exactly category (tool, command, mcp, path, host, write_root, host_resource), pattern, and effect (ask or deny only) — any other key fails the load. A write_root pattern must be an absolute directory. Any deny outranks ask. Packs never grant durable reuse — see Approvals.

Detection packs (Sigma)

Detection packs are device-only and never ownable. Import them under Settings → Approvals → Detections, or ship them under host/detection-packs/ in a pack installed on the device. A repository cannot define a rule; it may only turn a pack the device already has on or off ({repo}/.paintedwolf/detection-packs.yaml — id + enabled only).

Authoring — supported Sigma subset, fixtures, and field sets — is in the product repository: detection-packs.md and the rule schema. See Approvals for the user-facing behavior.

Playbook units

A playbooks/ unit is the numbered checklist a delegated worker follows for one kind of leg. Matching and merge rules are in prompt-assembly.md.

Skills

A skills/ unit is one folder holding a SKILL.md. Pack skills are device-only; project skills live under .paintedwolf/skills/ — see Unit kind properties. Which agents may read a skill is a persona field — see Agents.

skills: selects what an agent may read: an exact name list or all. The local decision model ranks available skills against the request and preloads the best fit when it clears the relevance threshold. The agent can also call skills_read with a plain-language need; the host selects one matching skill and returns its instructions. The catalog stays out of the prompt, so a pack can ship many skills without each one costing prompt bytes on every turn.

To open a referenced file, call skills_read again with the resolved skill identifier as need and the relative path as resource. An exact skill identifier also works when local ranking is unavailable. Reading a skill adds guidance, not tools or permissions.

The description is all the model reads, so it does the work. Write one clear sentence naming the work the skill serves and when it applies. Pack bodies use isolated pongo2 templates with no includes; project skill bodies are never templated. Skills use the open Agent Skills format.

Host content

host/bindings/, host/user-notices/, host/detection-packs/, and host/credential-slots/ are resolve units (device-only). Other host/ paths are fixed parts of the stock configuration, not arbitrary files a third-party pack can contribute. Prefer a workflow or rule for customization. The full path map is in extend.md.

Shared trees

shared/archetypes/ and shared/partials/ hold reusable include targets. See Prompts. shared/units/ holds instruction text that renders only on the turns that need it. See Prompt units.

Desired state

Device desired state and its exact lock control installation. Missing device desired state enables the stock packs.

A repository can recommend a pack without installing it:

format: 1
suggest:
  - id: acme/triage
    source: https://example.com/acme-triage.git
    version: "^1.0.0"
disabled: []

The user reviews the suggestion and installs it on the device. A suggestion may select a version range or exact ref; project disabled entries add to device disables without changing package identity or ownership.

Profiles

A pack can ship named desired-state recipes under profiles/*.yaml. Applying a profile writes desired state only; installing a pack never auto-applies one.

Installing

pw extensions install https://example.com/acme-triage.git --version 1.0.0
pw extensions validate

Sources: git URLs, file:///abs/dir, or path:relative/dir. Release installs resolve into ~/.config/paintedwolf/extensions/<id>/revisions/…; path: installs link the folder. Their contents may contain directories and regular files only; filesystem links and special files are refused. Stock packs are never cloned. Install only packs you trust — pack YAML is the same trust class as your own configuration.

Settings → Extensions manages the device scope. Context → Extensions inspects the catalog and disables eligible units for the project. The local API is /v1/extensions* — see the Host API. The full CLI is in the Reference.

Changes apply immediately. API mutation requests require the current revision as expected_revision; a stale write returns extension_state_changed (409), and desired state plus lock publish atomically.

Resolve diagnostics

Validation and the Extensions UI report stable codes — branch on the code, never the message. error means something you asked for is not in effect, and those are the codes that fail pw extensions validate:

Recipes

1. Additive — ship new unit ids only; install, enable, validate. Stock stays fully effective.
2. Swap — fork one thin pack plus a profile that disables the stock leaf; every other stock pack still updates with the app.
3. Surgical own — own a single unit id to your fork; the rest of the stock pack stays effective.

A workflow is a manifest: an ordered list of phases, each declaring what must be true (gates) before the run advances. Project workflows live at {repo}/.paintedwolf/workflows/<id>/workflow.yaml and surface in the app exactly like the bundled ones. The engine contract is workflows.md in the product repository.

A complete manifest

# {repo}/.paintedwolf/workflows/triage/workflow.yaml
id: triage
version: 1.0.0
name: Triage
description: Fan out read-only scouts, then report — no code changes.
trigger: /triage
request:
  question: What should the scouts look into?
phases:
  - id: investigate
    activity_label: Investigating
    coordinator_surface: orchestrate_plan
    surface_template: agents/coordinator-surface-orchestrate.md
    mode_refs: [plan-research]
    complete_when: gates_satisfied
    gates: [human_approval]
    next: done
  - id: done
    activity_label: Done
    coordinator_surface: await_user
    surface_template: agents/coordinator-surface-plan.md
    mode_refs: [await-user-input]
    terminal: true
    complete_when: orchestration_complete

Every phase in a project workflow — the terminal one included — sets all three surface fields and an activity_label. Overlays are stricter here than the shipped manifests, and this is the most common first validation failure. The top-level request: block is required too: it is the question the app asks when someone starts the workflow without saying what it is for.

A run keeps the id and version it started with. To change what a shipped workflow does, add a new version beside the old one and mark the old one retired: true: new runs take the new version, runs already under way finish on theirs, and the retired manifest stays exactly as it shipped.

Build your first pack walks one manifest end to end.

Phase anatomy

Terminal phases must complete with orchestration_complete. A phase that declares evidence_passed:verify requires a passing host check: the project’s test command when one is set, otherwise a successful check on the current files; see Editing.

Coordinator surfaces

coordinator_surface must name one of the shipped surfaces. The surface names the phase’s tools and its exit — how a deliverable leaves turns on it. The tools are a floor offered on every model call plus the tools a turn loads when the request needs them; the table lists both. Naming a surface that isn’t in this list is a load error, a phase that sets coordinator_surface must also set surface_template, and a phase gated on topology_report_delivered must bind a surface whose exit is report — that is what gives the final report its citation grounding.

Coordinator task() calls use a structured brief: goal and done_when are required, while known_facts, constraints, and context_refs carry only what a cold-start worker needs. Workers do not receive the parent chat transcript, and an omitted max_tool_loops takes the default for the leg’s scope — 12 rounds for a read survey, 20 for a write overlay.

Posture

Every run carries a session posture: a coordinator approval bucket that decides which tool profile and rule set the coordinator gets. This is a different axis from the approval posture in Settings — see Approvals.

The shipped set is closed — overlays may retune these, but cannot add a fifth:

initial_posture: spec
phases:
  - id: draft
    next: implement
  - id: implement
    on_enter:
      set_posture: build

A run records the session’s posture before it begins and restores it when it ends. To retune one for a project, add {repo}/.paintedwolf/postures.yaml. Each of the four ids accepts tool_profile, rules, description, and label.

The gate kit

Project workflows compose from the public gate kit. This vocabulary is generated from the engine — it is the exact set the host evaluates:

Choice transitions

A phase may offer named exits off the next: spine. Transitions render as buttons in the app and as a tool on the coordinator surface.

transitions:
  - id: critique
    to: review
    actors: [human, coordinator]
    label: Run critique

Planned fan-out

fanout_plan records a bounded set of worker legs; it does not start them. Dispatch the recorded legs from a following phase with parallel_task and a worker_cycle_ready gate. Both that gate and fanout_planned are bundled-only leaves, so a project overlay cannot gate on them.

Reports

A workflow can end in a downloadable PDF of its own closeout:

controls:
  report:
    enabled: true

Download report appears once the run finishes. The PDF carries the closeout prose, the evidence behind it, any scan findings with the counts they came from, and the verdict a review_loop phase recorded. Verdict members render as your verdict_schema names them, and a claims-typed member renders as a list of statements with the evidence backing each one.

It is assembled from the run’s stored records, so it needs the grounded closeout a topology_report_delivered phase produces — which is why that phase must bind a report-exit surface. That leaf is bundled-only too: a report is something a pack’s workflow ships, not something a project overlay adds.

Manifest reference

Generated from the loader — every field it parses, and nothing it doesn’t:

Shapes

The full block shapes — blueprint, human_approval, review_loop, invoke_workflow, parallel_task, and run variables — are in the product repository’s workflows.md. The shape the tutorial uses is the human checkpoint:

- id: approve
  coordinator_surface: plan_approve
  surface_template: agents/coordinator-surface-plan.md
  mode_refs: [plan-stub]
  complete_when: gates_satisfied
  gates: [human_approval]
  advance:
    when_gate_met: auto
  human_approval:
    blueprint: plan
    readiness: plan_stub_valid
  next: build

Chat never approves — Approve is a host action. advance.when_gate_met: auto is required on a surface that has no workflow_advance tool.

Validate before you run

pw workflow validate              # project overlays + bundled base
pw workflow validate --json       # machine-readable diagnostics

Green means the manifest loads, every phase is leaveable with the tools and gates the host evaluates, and every catalog reference resolves. It cannot prove model behavior. Diagnostics carry stable codes — the generated table is in the Reference.

What overlays can’t do

• Bundled-only gates — domain leaves are rejected with domain_leaf_on_overlay.
• Implicit surfaces — overlays must set coordinator_surface, surface_template, and mode_refs per phase.
• Routing on prose — triggers are explicit slash commands; Approve is a host action button, never a chat phrase.

Phase-entry guidance is an injects: entry — see Prompts.

OAR is an open standard; this page describes Painted Wolf Code’s implementation. The specification, schemas, and conformance corpus live at openagentrules.org. How this host evaluates rules is open-agent-rules.md in the product repository.

Open Agent Rules (OAR) is a portable standard for agent guardrails: a rule is one YAML document — a lifecycle anchor, a selector, a typed condition over observed facts, and a declared effect. Painted Wolf Code accepts oar: '1.0' and fails closed on other versions. Host-specific binding and selector schemas live in the product repository.

A complete rule

Rules ship in a pack’s policy/ directory (unit id policy/<CODE>), one file per rule:

oar: '1.0'
id: TRIAGE_LITE_WRITE_FORBIDDEN        # SCREAMING_SNAKE, equals the file stem
kind: policy                           # schema | policy | invariant | detector
anchor: tool.pre_invoke                # a lifecycle anchor id
selector:                              # clauses AND; each names a declared fact
  tool: [write, edit]
requires:
  profiles: [session, tool]
when: session_posture == "spec"
effect: block                          # block | warn | nudge | allow | transform
enforcement: enforce
on_error: fail_closed
copy:
  title: Triage Lite is read-only
  what: A write tool was called during triage.
  cause: The triage-lite workflow reports findings; it does not change files.
  fix: Record the finding in your write-up, then leave triage before editing.
  instead: Branch on Code TRIAGE_LITE_WRITE_FORBIDDEN and report instead of writing

Unknown fields are rejected by name. Human copy lives in copy: (title / what / cause / why / fix / instead).

A tool your fix: or instead: names in backticks must be one every agent the rule can reach actually holds, or the pack is held out — a blocked agent needs an exit it can execute. The anchor and selector.tool decide that audience; x-paintedwolf-audience: [<tool profile>] narrows it when your when: is stricter than they express.

Write instead: as the one call to make next. When an agent keeps hitting the same rule, the host escalates and carries that line verbatim in place of your fix:, so an instead: that only forbids something leaves the agent with no move.

Four kinds

kind fixes evaluation order—schema → policy → invariant → detector, then id. anchor: decides when the rule runs. The first block short-circuits; warnings and nudges accumulate.

Where rules fire

anchor: names a lifecycle moment. Guardrails and prompt injects select on the same catalog. Scope a rule with the selector, not by minting new anchors: tool.pre_invoke + selector.tool: [read, grep].

The full catalog — every legal anchor: value — is generated from the host:

Effects

The app lists effective rules read-only under Settings → Approvals. Branch on Code: — never on message text.

Conditions are typed expressions over facts

when: uses the closed, typed OAR condition language. Identifiers are registered facts — a typo’d fact name fails at load:

when: 'session_posture == "spec" && paintedwolf.tool_is_state'
when: mcp_schema_matched && mcp_field_bool("is_ready")

Standard-profile facts are bare names; host-specific facts are namespaced paintedwolf.*. The host produces facts; the rule composes them; the engine renders effects.

The fact catalogue

This is the full closed set, generated from the same engine table that declares the live condition environment: