pi-delegation-policy 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.5.0 - 2026-08-28
+
+### Added
+
+- Expanded the optional visual specialist to create assets and complete bounded presentation-layer changes when behavior and data contracts are already defined.
+
+### Changed
+
+- Renamed the user-facing UI Design role to Visual Design while preserving the `uiDesign` configuration key and `ui-design` status token.
+- Clarified routing boundaries for application behavior, accessibility, checks, integration, and final acceptance.
+
 ## 0.4.1 - 2026-08-28
 
 ### Fixed

package/README.md

@@ -1,20 +1,22 @@
 # pi-delegation-policy
 
-A local Pi extension that helps the main agent decide **when delegation is worth it** and which exact models to use for the Small, Medium, Large, and optional UI Design roles. It provides guidance; it is not a subagent runner.
+A local Pi extension that helps the main agent decide **when delegation is worth it** and which exact models to use for the Small, Medium, Large, and optional Visual Design roles. It provides guidance; it is not a subagent runner.
 
-> **Status:** Version **0.4.1** is the latest published package. The package requires Pi `>=0.84.3`; Pi `0.84.3` is the explicitly checked baseline (newer versions are not claimed as tested).
+> **Status:** Version **0.5.0** is the latest published package. The package requires Pi `>=0.84.3`; Pi `0.84.3` is the explicitly checked baseline (newer versions are not claimed as tested). The repository and npm package describe the same published behavior.
 >
 > **Docs:** [Read the documentation site](https://yivas.github.io/pi-delegation-policy/).
 
 ## Value and boundary
 
 - Choose `off`, `normal`, or `aggressive` delegation intensity globally or for the current session branch.
-- Configure exact provider/model references for Small, Medium, Large, and optionally UI Design.
+- Configure exact provider/model references for Small, Medium, Large, and optionally Visual Design.
 - Keep global defaults and session-branch overrides across reload, resume, and tree navigation.
 - Validate active configurations before injecting one policy block through Pi's public `before_agent_start` event.
 
 The extension guides the main agent. It never creates, launches, routes, supervises, or blocks subagents; changes Pi's main model or thinking; stores credentials; intercepts tools; or makes its own network requests. It has no model fallback, telemetry, project configuration, presets, or external skill loading.
 
+Visual Design is an optional specialist for direction, assets, bounded presentation-layer implementation, and visual review. Use it only when behavior and data contracts are already defined and unchanged, the affected surface is bounded, and visual quality or user experience is the primary acceptance criterion. Route business logic, data, APIs, routes, application architecture, tooling, interaction behavior, and cross-system integration to Small, Medium, or Large by task fit. The main agent retains final integration and acceptance.
+
 ## Install and start
 
 Install the published package in Pi's user settings, then reload Pi:
@@ -25,7 +27,7 @@ pi install npm:pi-delegation-policy
 ```
 
 1. Open `/delegate` (or press `Alt+G` in Pi's TUI).
-2. Configure exact, authenticated Small, Medium, and Large provider/model references. UI Design is optional.
+2. Configure exact, authenticated Small, Medium, and Large provider/model references. Visual Design is optional.
 3. Select `normal` or `aggressive`, then choose **Apply changes**.
 4. Run `/delegate status` and inspect the exact role references and their sources. `D:ERR` means an active required role is invalid; no policy is injected.
 5. The applied state affects the **next** agent run. An agent already running is not rewritten.
@@ -47,7 +49,7 @@ The editor is a bounded, keyboard-first panel. It shows model ID first and `[pro
 
 ## Configuration and safety
 
-Global defaults are stored at `~/.pi/agent/delegation-policy.json` (schema version 2). The file stores optional intensity, preference, exact role references, and an optional UI Design reference; it never stores thinking. A valid active mode requires exact, available, in-scope, authenticated Small, Medium, and Large references. Before every delegated launch, the policy requires the selected role's exact `provider/model` base and a thinking level chosen for that task instead of relying on ambient defaults. With `pi-subagents`, the main agent passes both as `model: "provider/model:LEVEL"`; other launchers may expose a separate per-run thinking field. Invalid active configuration fails closed as `D:ERR` with no policy injection; `off` is always `D:OFF`.
+Global defaults are stored at `~/.pi/agent/delegation-policy.json` (schema version 2). The file stores optional intensity, preference, exact role references, and an optional Visual Design reference under the stable `uiDesign` key; it never stores thinking. A valid active mode requires exact, available, in-scope, authenticated Small, Medium, and Large references. Before every delegated launch, the policy requires the selected role's exact `provider/model` base and a thinking level chosen for that task instead of relying on ambient defaults. With `pi-subagents`, the main agent passes both as `model: "provider/model:LEVEL"`; other launchers may expose a separate per-run thinking field. Invalid active configuration fails closed as `D:ERR` with no policy injection; `off` is always `D:OFF`.
 
 The extension stores only policy settings and provider/model identifiers in local defaults and session entries. Review local configuration before sharing diagnostics, and remove credentials, prompts, personal paths, session files, and unredacted logs from reports. See the [limits and privacy reference](https://yivas.github.io/pi-delegation-policy/limits-and-privacy/) and [security policy](https://github.com/Yivas/pi-delegation-policy/blob/main/SECURITY.md).
 

package/SECURITY.md

@@ -14,4 +14,4 @@ Include the affected version or commit, operating system, Pi version, reproducti
 
 ## Supported versions
 
-Only the latest published version is supported. Version 0.4.1 is the current supported release.
+Only the latest published version is supported. Version 0.5.0 is the current supported release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-delegation-policy",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "private": false,
   "description": "A Pi extension for configurable delegation intensity and exact subagent role model references.",
   "type": "module",

package/src/delegate-panel.ts

@@ -73,7 +73,7 @@ const FIELD_LABELS: Record<DelegateField, string> = {
   small: "Small model",
   medium: "Medium model",
   large: "Large model",
-  uiDesign: "UI Design",
+  uiDesign: "Visual Design",
 };
 
 const FIELD_DESCRIPTIONS: Record<DelegateField, string> = {
@@ -82,7 +82,7 @@ const FIELD_DESCRIPTIONS: Record<DelegateField, string> = {
   small: "Bounded, planned, and verifiable execution.",
   medium: "Planning, ambiguity, synthesis, and coordination.",
   large: "Exceptional unblocker for persistent hard problems.",
-  uiDesign: "Visual direction and review only; never implementation.",
+  uiDesign: "Design, assets, and bounded presentation work; no app behavior.",
 };
 
 const ACTION_LABELS: Record<PanelAction, string> = {

package/src/prompt.ts

@@ -23,6 +23,16 @@ Large quantities of repetitive, independent work favor multiple Small delegation
 
 In every intensity, keep global strategy, coordination, integration, final review, and work whose essential context is too costly or risky to transfer with the main agent.`;
 
+const VISUAL_DESIGN_POLICY = `Visual Design is an optional specialist role. Use it only when all four conditions hold:
+1. the primary acceptance criterion is a visual or user-experience result;
+2. product behavior and data contracts are already defined and remain unchanged;
+3. the patch is bounded to an identifiable surface, component, or set of assets;
+4. it requires no business logic, data flow, APIs, routes, application architecture, tooling, or cross-system coordination.
+
+When eligible, Visual Design may design, create, implement, and review scoped presentation code and visual assets, including layout, styles, responsive presentation, typography, images, icons, logos, SVGs, diagrams, and documentation visuals. It may address visual accessibility such as contrast and focus visibility. It must run and report the relevant existing checks for its patch.
+
+Route interaction behavior, state, validation, semantic HTML changes, keyboard mechanics, ARIA behavior, authentication, permissions, persistence, test infrastructure, and behavior-test ownership to Small, Medium, or Large by task fit. If any eligibility condition fails, use an ordinary role or split the visual portion from the broader task. The main agent retains cross-domain integration and final acceptance.`;
+
 function preferenceGuidance(preference: Preference): string {
   if (preference === "efficient") {
     return "Use efficient only as a Small tie-break when Small and Medium are comparably credible. Do not choose Small when Medium is a materially better task fit.";
@@ -81,7 +91,7 @@ export function buildDelegationPolicy(state: RuntimeState): string | undefined {
 
   const intensityPolicy = effective.intensity === "normal" ? NORMAL_POLICY : AGGRESSIVE_POLICY;
   const uiDesign = effective.uiDesign
-    ? `\n- UI Design: ${formatReference(effective.uiDesign)}; exact model base: ${formatLaunchModel(effective.uiDesign)}; pi-subagents form: ${formatThinkingLaunchModel(effective.uiDesign)}. Use this role only for visual design direction, exploration, or review. Never use it to implement an interface, write code, or run tests.`
+    ? `\n- Visual Design: ${formatReference(effective.uiDesign)}; exact model base: ${formatLaunchModel(effective.uiDesign)}; pi-subagents form: ${formatThinkingLaunchModel(effective.uiDesign)}`
     : "";
 
   return `<delegation_policy>
@@ -98,7 +108,7 @@ Roles:
 - Small: ${formatReference(effective.small)}; exact model base: ${formatLaunchModel(effective.small)}; pi-subagents form: ${formatThinkingLaunchModel(effective.small)}
 - Medium: ${formatReference(effective.medium)}; exact model base: ${formatLaunchModel(effective.medium)}; pi-subagents form: ${formatThinkingLaunchModel(effective.medium)}
 - Large: ${formatReference(effective.large)}; exact model base: ${formatLaunchModel(effective.large)}; pi-subagents form: ${formatThinkingLaunchModel(effective.large)}${uiDesign}
-
+${effective.uiDesign ? `\n${VISUAL_DESIGN_POLICY}\n` : ""}
 This is guidance for the main agent. It does not create, execute, route, supervise, or enforce delegated work.
 </delegation_policy>`;
 }

package/src/types.ts

@@ -14,7 +14,7 @@ export const ROLE_LABELS: Record<ModelConfigKey, string> = {
   small: "Small",
   medium: "Medium",
   large: "Large",
-  uiDesign: "UI Design",
+  uiDesign: "Visual Design",
 };
 
 export type ModelRef = {
@@ -39,7 +39,7 @@ export type SessionDelegateState = {
   small?: ModelRef;
   medium?: ModelRef;
   large?: ModelRef;
-  // Null explicitly disables a global UI Design role for this session branch.
+  // Null explicitly disables a global Visual Design role for this session branch.
   uiDesign?: ModelRef | null;
 };