---
description: Use when configuring, installing, or reasoning about the Orual Polytoken workflow pack; includes workflow-specific project_vars, global/project install paths, and requires the Polytoken config reference for schema details.
polytoken:
  tags: [configuration]
---
# Orual Workflow Config Reference

Use this skill when configuring or debugging the Orual Polytoken workflow pack: facets, hooks, skills, subagents, `project_vars`, and global-vs-project installation.

Before changing Polytoken config, facets, hooks, subagents, or permission behavior, load `polytoken:config_reference` and treat it as authoritative for current Polytoken schema and validation rules. This skill only documents the workflow pack's conventions.

## Validate after changes

Run:

```sh
polytoken config validate
```

If templates, hooks, skills, or facets were changed in a live session, reload or restart Polytoken as needed before testing behavior.

## Project variables contract

Project-specific workflow instructions live in:

```text
.polytoken/project_vars.yaml
```

`project_vars.yaml` is raw project data, not config. It is not merged with global config. Do not put secrets in it.

Recommended minimal fields:

```yaml
design_workflow_instructions: |
  Where durable design artifacts should be written.
  Where the human source of truth lives.
  How to use project trackers, docs, or vaults.

plan_handoff_instructions: |
  What implementation handoff plans must cite or preserve.
  How to refer to design artifacts, tracker issues, and validation expectations.
```

Optional structured fields for hooks or future plugins:

```yaml
orual_workflow:
  agent_truth:
    kind: markdown
    root: agent_docs
  human_truth:
    kind: conversation
    reference: null
  review:
    gate_severities: [Critical, High]
    panel_required_for_large_handoffs: true
    allow_operator_risk_acceptance: true
```

Facets should prefer the string instruction fields for prompt rendering. Hook scripts may use structured fields later, but should tolerate missing keys.

## Global install layout

Until plugin packaging exists, install reusable workflow components in the normal Polytoken global locations.

Facets and hooks:

```text
${XDG_CONFIG_HOME:-~/.config}/polytoken/
  facets/
    design.md
    plan.md              # optional thin wrapper around shipped plan
  hooks.json
  hooks/
    workflow-context.sh
```

Skills:

```text
${XDG_DATA_HOME:-~/.local/share}/polytoken/skills/
  refining-human-documents/SKILL.md
  reviewing-code-for-shipping-quality/SKILL.md
  orual-workflow-config-reference/SKILL.md
```

Project-local overrides live under:

```text
<project>/.polytoken/
  config.yaml
  project_vars.yaml
  facets/
  hooks.json
  hooks/
  skills/
  subagents/
```

Project files override global files with the same facet/subagent names. Hooks append after global hooks unless disabled with `!hook-name`.

## Facet conventions

### `design`

Writable durable design mode. It should:

- use `project_vars.design_workflow_instructions` when present;
- ask before inventing durable storage when absent;
- write only to configured design/documentation spaces unless explicitly approved;
- use `write_plan`/`handoff_plan` for small immediate handoffs;
- switch to `plan` for larger implementation planning.

### `plan`

Thin wrapper around the shipped `polytoken://facets/plan.md` when globally overridden. It may add:

- `project_vars.plan_handoff_instructions`;
- a review gate before `handoff_plan`;
- small workflow-specific constraints not already present in shipped plan.

Keep this wrapper compact. The shipped plan facet should carry the main planning behavior.

## Review gate convention

Before `handoff_plan`, run independent review:

- small/simple handoff: at least one `code_reviewer` subagent;
- larger handoff: panel using pinned models when available:
  - `codex/gpt-5.5(medium)`
  - `codex/gpt-5.4-mini(high)`
  - `zai/glm-5.2(max)`

If a pinned model does not resolve, stop and ask the operator. Do not silently substitute a weaker model.

Fix or rebut every Critical/High finding with evidence. Re-run reviewers until Critical/High are zero, or until the operator explicitly accepts the risk.

## Hooks convention

Start conservative:

- `session_start`: inject workflow frame.
- `pre_model_turn`: inject active workflow/gate context only when useful.
- `post_compaction`: reattach workflow frame after compaction.

Use daemon state when needed:

```sh
session_dir="${XDG_DATA_HOME:-$HOME/.local/share}/polytoken/sessions/${POLYTOKEN_SESSION_ID}"
port="$(jq -r '.port' "$session_dir/startup.json")"
curl -fsS "http://127.0.0.1:${port}/state"
```

Defer strict hooks until the durable gate file format is explicit. Do not implement universal `post_tool_use` logging by default.

## Local file inclusion

Use local `transclude("path.md")` when a prompt fragment needs template rendering with current context. Paths resolve relative to the calling facet/subagent file and cannot escape that directory subtree.

Use `@file` only for static text. It is expanded at load time before Jinja runs, so template variables inside the included file are not rendered.
