pi-crew 0.10.5 → 0.11.0

package/package.json

@@ -1,171 +1,172 @@
 {
-  "name": "pi-crew",
-  "version": "0.10.5",
-  "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
-  "author": "baphuongna",
-  "license": "MIT",
-  "engines": {
-    "node": ">=22.0.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/baphuongna/pi-crew.git"
-  },
-  "homepage": "https://github.com/baphuongna/pi-crew#readme",
-  "bugs": {
-    "url": "https://github.com/baphuongna/pi-crew/issues"
-  },
-  "type": "module",
-  "bin": {
-    "pi-crew": "install.mjs"
-  },
-  "keywords": [
-    "pi-package",
-    "pi",
-    "pi-coding-agent",
-    "teams",
-    "agents",
-    "multi-agent",
-    "orchestration"
-  ],
-  "files": [
-    "src/",
-    "!src/benchmark",
-    "dist/index.mjs",
-    "index.ts",
-    "install.mjs",
-    "agents/",
-    "teams/",
-    "workflows/",
-    "skills/**",
-    "themes/",
-    "assets/crew-vibes.ttf",
-    "scripts/clean-strip-types.mjs",
-    "scripts/postinstall.mjs",
-    "scripts/install-crew-vibes-font.mjs",
-    "scripts/build-crew-vibes-font.py",
-    "scripts/pty_probe.py",
-    "README.md",
-    "AGENTS.md",
-    "docs/actions-reference.md",
-    "docs/commands-reference.md",
-    "docs/troubleshooting.md",
-    "docs/usage.md",
-    "docs/architecture.md",
-    "docs/dynamic-workflows.md",
-    "docs/runtime-flow.md",
-    "docs/resource-formats.md",
-    "docs/publishing.md",
-    "docs/migration-v0.4-v0.5.md",
-    "tsconfig.json",
-    "schema.json",
-    "types/",
-    "CHANGELOG.md",
-    "LICENSE",
-    "NOTICE.md",
-    "scripts/resource-sampler.mjs",
-    "scripts/analyze-run.mjs"
-  ],
-  "scripts": {
-    "check": "npm run ci",
-    "ci": "npm run check:lockfile-sync && npm run typecheck && npm run lint && npm run format:check && npm run check:conflict-markers && npm run check:decision-drift && npm run check:env-vars && npm run check:event-types && npm run check:lazy-imports && npm run check:wc-gate && npm run check:bundle-staleness && npm run build:bundle && npm run check:bundle-size && npm run test:bundle && npm test && npm pack --dry-run",
-    "ci:fast": "npm run check:lockfile-sync && npm run typecheck && npm run lint && npm run format:check && npm run check:conflict-markers && npm run check:decision-drift && npm run check:env-vars && npm run check:event-types && npm run check:lazy-imports && npm run check:wc-gate && npm run check:bundle-staleness && npm run build:bundle && npm run check:bundle-size && npm run test:bundle && npm run test:critical && npm pack --dry-run",
-    "check:lockfile-sync": "node scripts/check-lockfile-sync.mjs",
-    "check:lazy-imports": "node scripts/check-lazy-imports.mjs",
-    "check:bundle-staleness": "node scripts/check-bundle-staleness.mjs",
-    "check:bundle-size": "node scripts/check-bundle-size.mjs",
-    "check:conflict-markers": "node scripts/check-conflict-markers.mjs",
-    "check:decision-drift": "node scripts/check-decision-drift.mjs",
-    "check:env-vars": "node scripts/check-env-vars.mjs",
-    "check:event-types": "node scripts/check-event-types-registry.mjs",
-    "typecheck": "tsc --noEmit && node --experimental-strip-types -e \"await import('./index.ts'); console.log('strip-types import ok')\"",
-    "lint": "biome check --linter-enabled=true --formatter-enabled=false --max-diagnostics=50 .",
-    "format:check": "biome format .",
-    "test": "npm run test:unit && npm run test:integration",
-    "test:full": "npm run test:unit && npm run test:integration && npm run test:integration:slow",
-    "test:unit": "node scripts/test-runner.mjs --test-concurrency=4 --test-timeout=180000 --test-force-exit 'test/unit/**/*.test.ts'",
-    "test:critical": "node scripts/test-runner.mjs --test-concurrency=4 --test-timeout=30000 --test-force-exit test/unit/runtime/broker/crew-broker-handshake.test.ts test/unit/runtime/broker/crew-broker-stale-socket.test.ts test/unit/runtime/broker/crew-broker-feature-flag.test.ts test/unit/runtime/broker/crew-broker-server-gate.test.ts test/unit/runtime/broker/crew-broker-client-fallback.test.ts test/unit/runtime/broker/crew-broker-mailbox-observer.test.ts test/unit/runtime/broker/crew-broker-close-during-reconnect.test.ts test/unit/runtime/broker/crew-broker-steer-dedup.test.ts test/unit/runtime/broker/crew-broker-symlink-steering.test.ts test/unit/ui/keybinding-map.parity.test.ts test/unit/ui/pi-tui-dispatch-probe.test.ts test/unit/utils/session-utils-extract.test.ts test/unit/config/config-schema-sync.test.ts test/unit/runtime/child-pi/child-pi-env-spread.test.ts",
-    "test:watch": "node scripts/test-runner.mjs --watch --test-concurrency=4 --test-timeout=30000 'test/unit/**/*.test.ts'",
-    "test:integration": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=300000 test/integration/*.test.ts",
-    "test:integration:slow": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=600000 test/integration/slow/*.test.ts",
-    "test:system": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=180000 --test-force-exit test/system/*.e2e.test.ts",
-    "test:smoke": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=180000 test/smoke/*.smoke.ts",
-    "test:spike": "node scripts/test-runner.mjs --test-concurrency=2 --test-timeout=120000 --test-force-exit test/runtime/scratchpad/*.test.ts",
-    "test:functional": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=120000 test/functional/pi-crew-functional.test.ts",
-    "test:platform": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=60000 test/platform/*.test.ts",
-    "build:bundle": "node scripts/build-bundle.mjs",
-    "test:bundle": "node --experimental-strip-types --test --test-force-exit test/unit/bundle-load.test.ts",
-    "watch:bundle": "node scripts/watch-bundle.mjs",
-    "build:bundle:once": "node scripts/watch-bundle.mjs --once",
-    "dev": "node scripts/dev-runner.mjs",
-    "postinstall": "node scripts/postinstall.mjs",
-    "install:crew-font": "node scripts/install-crew-vibes-font.mjs",
-    "build:crew-font": "python scripts/build-crew-vibes-font.py",
-    "bench": "node scripts/run-bench.mjs",
-    "bench:check": "node scripts/bench-check.mjs",
-    "test:new": "node scripts/test-runner.mjs --test-concurrency=4 --test-timeout=30000 'test/unit/**/*.test.ts'",
-    "test:changed": "node scripts/test-changed.mjs",
-    "bench:capture": "node scripts/run-bench.mjs && node -e \"require('node:fs').copyFileSync('test/bench/results.json','test/bench/baseline.json')\"",
-    "profile:startup": "node scripts/profile-startup.mjs",
-    "smoke:pi": "pi install .",
-    "smoke:release": "node scripts/release-smoke.mjs",
-    "prepack": "node scripts/clean-strip-types.mjs",
-    "test:fast": "npm run test:critical && npm run test:bundle",
-    "check:wc-gate": "node scripts/wc-gate.mjs"
-  },
-  "exports": {
-    "./schema.json": "./schema.json",
-    "./workflow": {
-      "types": "./types/dwf.d.ts"
-    }
-  },
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ],
-    "skills": [
-      "./skills"
-    ]
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
-  },
-  "dependencies": {
-    "@sinclair/typebox": "^0.34.50",
-    "acorn": "^8.17.0",
-    "ajv": "^8.20.0",
-    "cli-highlight": "^2.1.11",
-    "diff": "^5.2.0",
-    "esbuild": "^0.28.1",
-    "jiti": "^2.7.0",
-    "yaml": "^2.9.0"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.5.3",
-    "@earendil-works/pi-agent-core": "^0.84.0",
-    "@earendil-works/pi-ai": "^0.84.0",
-    "@earendil-works/pi-coding-agent": "^0.84.0",
-    "@earendil-works/pi-tui": "^0.84.0",
-    "@types/node": "^25.9.5",
-    "tsx": "^4.23.0",
-    "typescript": "^7.0.2"
-  },
-  "peerDependenciesMeta": {
-    "@earendil-works/pi-agent-core": {
-      "optional": true
-    },
-    "@earendil-works/pi-ai": {
-      "optional": true
-    },
-    "@earendil-works/pi-coding-agent": {
-      "optional": true
-    },
-    "@earendil-works/pi-tui": {
-      "optional": true
-    }
-  },
-  "readmeFilename": "README.md"
+	"name": "pi-crew",
+	"version": "0.11.0",
+	"description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
+	"author": "baphuongna",
+	"license": "MIT",
+	"engines": {
+		"node": ">=22.0.0"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/baphuongna/pi-crew.git"
+	},
+	"homepage": "https://github.com/baphuongna/pi-crew#readme",
+	"bugs": {
+		"url": "https://github.com/baphuongna/pi-crew/issues"
+	},
+	"type": "module",
+	"bin": {
+		"pi-crew": "install.mjs"
+	},
+	"keywords": [
+		"pi-package",
+		"pi",
+		"pi-coding-agent",
+		"teams",
+		"agents",
+		"multi-agent",
+		"orchestration"
+	],
+	"files": [
+		"src/",
+		"!src/benchmark",
+		"dist/index.mjs",
+		"index.ts",
+		"install.mjs",
+		"agents/",
+		"teams/",
+		"workflows/",
+		"skills/**",
+		"themes/",
+		"assets/crew-vibes.ttf",
+		"scripts/clean-strip-types.mjs",
+		"scripts/postinstall.mjs",
+		"scripts/install-crew-vibes-font.mjs",
+		"scripts/build-crew-vibes-font.py",
+		"scripts/pty_probe.py",
+		"README.md",
+		"AGENTS.md",
+		"docs/actions-reference.md",
+		"docs/commands-reference.md",
+		"docs/troubleshooting.md",
+		"docs/usage.md",
+		"docs/architecture.md",
+		"docs/dynamic-workflows.md",
+		"docs/runtime-flow.md",
+		"docs/resource-formats.md",
+		"docs/publishing.md",
+		"docs/migration-v0.4-v0.5.md",
+		"tsconfig.json",
+		"schema.json",
+		"types/",
+		"CHANGELOG.md",
+		"LICENSE",
+		"NOTICE.md",
+		"scripts/resource-sampler.mjs",
+		"scripts/analyze-run.mjs",
+		"scripts/watch-agent-transcript.mjs"
+	],
+	"scripts": {
+		"check": "npm run ci",
+		"ci": "npm run check:lockfile-sync && npm run typecheck && npm run lint && npm run format:check && npm run check:conflict-markers && npm run check:decision-drift && npm run check:env-vars && npm run check:event-types && npm run check:lazy-imports && npm run check:wc-gate && npm run check:bundle-staleness && npm run build:bundle && npm run check:bundle-size && npm run test:bundle && npm test && npm pack --dry-run",
+		"ci:fast": "npm run check:lockfile-sync && npm run typecheck && npm run lint && npm run format:check && npm run check:conflict-markers && npm run check:decision-drift && npm run check:env-vars && npm run check:event-types && npm run check:lazy-imports && npm run check:wc-gate && npm run check:bundle-staleness && npm run build:bundle && npm run check:bundle-size && npm run test:bundle && npm run test:critical && npm pack --dry-run",
+		"check:lockfile-sync": "node scripts/check-lockfile-sync.mjs",
+		"check:lazy-imports": "node scripts/check-lazy-imports.mjs",
+		"check:bundle-staleness": "node scripts/check-bundle-staleness.mjs",
+		"check:bundle-size": "node scripts/check-bundle-size.mjs",
+		"check:conflict-markers": "node scripts/check-conflict-markers.mjs",
+		"check:decision-drift": "node scripts/check-decision-drift.mjs",
+		"check:env-vars": "node scripts/check-env-vars.mjs",
+		"check:event-types": "node scripts/check-event-types-registry.mjs",
+		"typecheck": "tsc --noEmit && node --experimental-strip-types -e \"await import('./index.ts'); console.log('strip-types import ok')\"",
+		"lint": "biome check --linter-enabled=true --formatter-enabled=false --max-diagnostics=50 .",
+		"format:check": "biome format .",
+		"test": "npm run test:unit && npm run test:integration",
+		"test:full": "npm run test:unit && npm run test:integration && npm run test:integration:slow",
+		"test:unit": "node scripts/test-runner.mjs --test-concurrency=4 --test-timeout=180000 --test-force-exit 'test/unit/**/*.test.ts'",
+		"test:critical": "node scripts/test-runner.mjs --test-concurrency=4 --test-timeout=30000 --test-force-exit test/unit/runtime/broker/crew-broker-handshake.test.ts test/unit/runtime/broker/crew-broker-stale-socket.test.ts test/unit/runtime/broker/crew-broker-feature-flag.test.ts test/unit/runtime/broker/crew-broker-server-gate.test.ts test/unit/runtime/broker/crew-broker-client-fallback.test.ts test/unit/runtime/broker/crew-broker-mailbox-observer.test.ts test/unit/runtime/broker/crew-broker-close-during-reconnect.test.ts test/unit/runtime/broker/crew-broker-steer-dedup.test.ts test/unit/runtime/broker/crew-broker-symlink-steering.test.ts test/unit/ui/keybinding-map.parity.test.ts test/unit/ui/pi-tui-dispatch-probe.test.ts test/unit/utils/session-utils-extract.test.ts test/unit/config/config-schema-sync.test.ts test/unit/runtime/child-pi/child-pi-env-spread.test.ts",
+		"test:watch": "node scripts/test-runner.mjs --watch --test-concurrency=4 --test-timeout=30000 'test/unit/**/*.test.ts'",
+		"test:integration": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=300000 test/integration/*.test.ts",
+		"test:integration:slow": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=600000 test/integration/slow/*.test.ts",
+		"test:system": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=180000 --test-force-exit test/system/*.e2e.test.ts",
+		"test:smoke": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=180000 test/smoke/*.smoke.ts",
+		"test:spike": "node scripts/test-runner.mjs --test-concurrency=2 --test-timeout=120000 --test-force-exit test/runtime/scratchpad/*.test.ts",
+		"test:functional": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=120000 test/functional/pi-crew-functional.test.ts",
+		"test:platform": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=60000 test/platform/*.test.ts",
+		"build:bundle": "node scripts/build-bundle.mjs",
+		"test:bundle": "node --experimental-strip-types --test --test-force-exit test/unit/bundle-load.test.ts",
+		"watch:bundle": "node scripts/watch-bundle.mjs",
+		"build:bundle:once": "node scripts/watch-bundle.mjs --once",
+		"dev": "node scripts/dev-runner.mjs",
+		"postinstall": "node scripts/postinstall.mjs",
+		"install:crew-font": "node scripts/install-crew-vibes-font.mjs",
+		"build:crew-font": "python scripts/build-crew-vibes-font.py",
+		"bench": "node scripts/run-bench.mjs",
+		"bench:check": "node scripts/bench-check.mjs",
+		"test:new": "node scripts/test-runner.mjs --test-concurrency=4 --test-timeout=30000 'test/unit/**/*.test.ts'",
+		"test:changed": "node scripts/test-changed.mjs",
+		"bench:capture": "node scripts/run-bench.mjs && node -e \"require('node:fs').copyFileSync('test/bench/results.json','test/bench/baseline.json')\"",
+		"profile:startup": "node scripts/profile-startup.mjs",
+		"smoke:pi": "pi install .",
+		"smoke:release": "node scripts/release-smoke.mjs",
+		"prepack": "node scripts/clean-strip-types.mjs",
+		"test:fast": "npm run test:critical && npm run test:bundle",
+		"check:wc-gate": "node scripts/wc-gate.mjs"
+	},
+	"exports": {
+		"./schema.json": "./schema.json",
+		"./workflow": {
+			"types": "./types/dwf.d.ts"
+		}
+	},
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		],
+		"skills": [
+			"./skills"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-agent-core": "*",
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	},
+	"dependencies": {
+		"@sinclair/typebox": "^0.34.50",
+		"acorn": "^8.17.0",
+		"ajv": "^8.20.0",
+		"cli-highlight": "^2.1.11",
+		"diff": "^5.2.0",
+		"esbuild": "^0.28.1",
+		"jiti": "^2.7.0",
+		"yaml": "^2.9.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.3",
+		"@earendil-works/pi-agent-core": "^0.84.0",
+		"@earendil-works/pi-ai": "^0.84.0",
+		"@earendil-works/pi-coding-agent": "^0.84.0",
+		"@earendil-works/pi-tui": "^0.84.0",
+		"@types/node": "^25.9.5",
+		"tsx": "^4.23.0",
+		"typescript": "^7.0.2"
+	},
+	"peerDependenciesMeta": {
+		"@earendil-works/pi-agent-core": {
+			"optional": true
+		},
+		"@earendil-works/pi-ai": {
+			"optional": true
+		},
+		"@earendil-works/pi-coding-agent": {
+			"optional": true
+		},
+		"@earendil-works/pi-tui": {
+			"optional": true
+		}
+	},
+	"readmeFilename": "README.md"
 }

package/scripts/watch-agent-transcript.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// Watch a pi session transcript (JSONL stream events) and print one readable
+// line per message — the "session subagent" pane companion for the Agents &
+// Jobs browser (`p` key). Unlike `tail -F` on the raw file, every line here is
+// a formatted summary (role badge + preview), so a tmux/herdr pane shows WHAT
+// the agent is doing, not walls of JSON.
+//
+// Usage: node watch-agent-transcript.mjs <transcript.jsonl>
+import { open as openFile } from "node:fs/promises";
+import { basename } from "node:path";
+
+const path = process.argv[2];
+if (!path) {
+	console.error("usage: node watch-agent-transcript.mjs <transcript.jsonl>");
+	process.exit(1);
+}
+
+const WIDTH = Math.min(200, Number(process.env.COLUMNS || 160) || 160);
+
+function oneLine(text) {
+	return String(text ?? "")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+function clip(text, max = WIDTH - 10) {
+	const s = oneLine(text);
+	return s.length > max ? `${s.slice(0, max - 1)}…` : s;
+}
+
+function stamp(iso) {
+	const m = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2})/.exec(iso ?? "");
+	return m ? `${m[2]}` : "";
+}
+
+function renderEvent(evt) {
+	if (evt.type === "session") return "── session start ──";
+	if (evt.type === "agent_start") return "── agent start ──";
+	if (evt.type !== "message_end" || !evt.message) return null;
+	const msg = evt.message;
+	const who =
+		msg.role === "assistant" ? "🤖" : msg.role === "user" ? "👤" : msg.role === "toolResult" ? "📤" : (msg.role ?? "?");
+	const parts = Array.isArray(msg.content) ? msg.content : [{ type: "text", text: String(msg.content ?? "") }];
+	const out = [];
+	for (const part of parts) {
+		if (part.type === "thinking") out.push(`💭 ${clip(part.thinking, 120)}`);
+		else if (part.type === "text") out.push(`💬 ${clip(part.text)}`);
+		else if (part.type === "tool_use") {
+			const input = typeof part.input === "object" ? JSON.stringify(part.input) : String(part.input ?? "");
+			out.push(`🔧 ${part.name ?? "tool"} ${clip(input, 100)}`);
+		} else if (part.type === "tool_result") {
+			const content = typeof part.content === "string" ? part.content : JSON.stringify(part.content ?? "");
+			out.push(`📤 ${clip(content, 120)}`);
+		}
+	}
+	if (out.length === 0) return null;
+	return `${stamp(evt.timestamp ?? msg.timestamp) || "        "} ${who} ${out.join(" │ ")}`;
+}
+
+// Clear the pane first — herdr/tmux panes boot via the shell, so the echoed
+// prompt + full node command would otherwise sit above the watcher output.
+process.stdout.write("\x1b[2J\x1b[H");
+console.log(`── watching ${basename(path)} ──`);
+
+let offset = 0;
+let buffer = "";
+const POLL_MS = 400;
+let waitingSince = 0;
+let lastWaitingLog = 0;
+
+function logWaiting(now) {
+	if (!waitingSince) waitingSince = now;
+	if (now - lastWaitingLog >= 2500) {
+		const waitedS = Math.round((now - waitingSince) / 1000);
+		console.log(`… waiting for ${basename(path)} to appear (${waitedS}s)`);
+		lastWaitingLog = now;
+	}
+}
+
+async function pump() {
+	try {
+		const fh = await openFile(path, "r");
+		try {
+			const stat = await fh.stat();
+			if (waitingSince) {
+				console.log(`✓ transcript appeared (waited ${Math.round((Date.now() - waitingSince) / 1000)}s)`);
+				waitingSince = 0;
+			}
+			if (stat.size < offset) offset = 0; // truncated/rotated
+			if (stat.size > offset) {
+				const len = stat.size - offset;
+				const buf = Buffer.alloc(len);
+				await fh.read(buf, 0, len, offset);
+				offset += len;
+				buffer += buf.toString("utf8");
+				const lines = buffer.split("\n");
+				buffer = lines.pop() ?? "";
+				for (const line of lines) {
+					const trimmed = line.trim();
+					if (!trimmed) continue;
+					try {
+						const rendered = renderEvent(JSON.parse(trimmed));
+						if (rendered) console.log(rendered);
+					} catch {
+						console.log(`· ${clip(trimmed)}`);
+					}
+				}
+			}
+		} finally {
+			await fh.close();
+		}
+	} catch {
+		// File not there yet (cold-start window): visible waiting state so the
+		// pane explains itself instead of looking dead.
+		logWaiting(Date.now());
+	}
+}
+
+setInterval(pump, POLL_MS);
+await pump();

package/skills/async-worker-recovery/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: async-worker-recovery
-description: Background worker, heartbeat, stale-run, crash-recovery, and deadletter workflow. Use when debugging stuck/dead workers or changing async run reliability.
+description: >
+  Background worker, heartbeat, stale-run, crash-recovery, and deadletter workflow. Use when debugging stuck/dead workers or changing async run reliability.
+  When NOT to use: pure investigation without async context (use read-only-explorer); one-shot fixes that don't need recovery infrastructure.
+
 origin: pi-crew
 triggers:
   - "worker crashed"

package/skills/child-pi-spawning/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: child-pi-spawning
-description: "Child Pi worker spawning, lifecycle callbacks, and failure modes."
+description: >
+  Child Pi worker spawning, lifecycle callbacks, and failure modes.
+  When NOT to use: non-Pi subprocess execution (use safe-bash); for general async reliability (use async-worker-recovery).
+
 origin: pi-crew
 triggers:
   - "worker crashed"

package/skills/context-artifact-hygiene/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: context-artifact-hygiene
-description: "Use when constructing worker prompts, reading artifacts/logs, summarizing runs, compacting context, or handing work between agents."
+description: >
+  Use when constructing worker prompts, reading artifacts/logs, summarizing runs, compacting context, or handing work between agents.
+  When NOT to use: tasks without artifact/context concerns; pure code questions (use read-only-explorer).
+
 origin: pi-crew
 triggers:
   - "construct prompt"

package/skills/council/SKILL.md

@@ -5,7 +5,7 @@ description: >
   architecture choice, or plan. Anti-anchoring: each role receives ONLY the question,
   not conversation history. Aggregates votes into consensus recommendation with dissent tracking.
   Use when facing critical decisions, architecture choices, security tradeoffs, or plan reviews
-  where single-perspective analysis is insufficient.
+  where single-perspective analysis is insufficient. When NOT to use: trivial choices where consensus adds no value; time-critical decisions that can't afford 3 parallel reviews.
 origin: ECC/skills/council
 ---
 
@@ -46,58 +46,23 @@ DO NOT bias the question toward any particular answer.
 
 ### Step 2: Spawn 3 Council Members
 
-Launch 3 parallel subagents with these EXACT roles:
+Launch 3 parallel subagents, one per seat, using the councillor agents:
 
-**Skeptic** (Goal: Find flaws):
-```
-You are the Skeptic on a council evaluating: [QUESTION]
-
-Your role: Find every possible flaw, risk, and failure mode.
-- Challenge assumptions
-- Identify edge cases that break the proposed approach
-- Focus on what could go WRONG
-- Rate your confidence (0.0-1.0) and give a PRO/CON/ABSTAIN position
-- Provide your top 3 risks
-
-Output format:
-Position: PRO | CON | ABSTAIN
-Confidence: 0.0-1.0
-Reasoning: [your analysis]
-Top 3 Risks: [list]
-```
+- **Skeptic** (finds flaws) → `subagent_type='councillor-skeptic'`
+- **Pragmatist** (weighs tradeoffs) → `subagent_type='councillor-pragmatist'`
+- **Critic** (stress-tests reasoning) → `subagent_type='councillor-critic'`
 
-**Pragmatist** (Goal: Evaluate tradeoffs):
-```
-You are the Pragmatist on a council evaluating: [QUESTION]
+Each subagent's prompt is EXACTLY the question text from Step 1 — nothing else, no context preamble, no your-opinion-matters framing.
 
-Your role: Weigh practical tradeoffs objectively.
-- Consider implementation cost, maintenance burden, team impact
-- Evaluate time-to-value and opportunity cost
-- Compare against realistic alternatives
-- Rate your confidence (0.0-1.0) and give a PRO/CON/ABSTAIN position
+The seat perspective, output contract (Position/Confidence/Reasoning + seat-specific field), and anti-anchoring are baked into the agent files. The councillor agents carry `inheritProjectContext: false`, so isolation is STRUCTURAL (enforced at spawn), not merely instructed — do not wrap the question with your own framing or history.
 
-Output format:
-Position: PRO | CON | ABSTAIN
-Confidence: 0.0-1.0
-Reasoning: [your analysis]
-Alternatives Considered: [list]
-```
+All three seats return the shared vote block:
 
-**Critic** (Goal: Stress-test reasoning):
 ```
-You are the Critic on a council evaluating: [QUESTION]
-
-Your role: Stress-test the logical foundations of each possible answer.
-- Identify logical fallacies in common arguments for/against
-- Check if the question itself contains hidden assumptions
-- Evaluate whether the stated constraints are real or assumed
-- Rate your confidence (0.0-1.0) and give a PRO/CON/ABSTAIN position
-
-Output format:
 Position: PRO | CON | ABSTAIN
 Confidence: 0.0-1.0
-Reasoning: [your analysis]
-Hidden Assumptions: [list]
+Reasoning: <analysis>
+<Seat-specific field: Top 3 Risks | Alternatives Considered | Hidden Assumptions>
 ```
 
 ### Step 3: Aggregate Votes
@@ -161,3 +126,17 @@ Before finalizing a council result, verify:
 - [ ] Consensus level computed from vote pattern
 - [ ] Dissent explicitly documented (not hidden)
 - [ ] Recommendation includes actionable next steps
+
+## Budget
+
+This skill applies a 3-attempt budget: 1 initial + max 2 re-attempts.
+
+Stamp every invocation:
+
+```
+attempt X of 3 (Y attempts remaining)
+```
+
+An attempt is one full council round (3 adversarial agents → aggregate → consensus). Re-attempt when votes deadlock or dissent reveals information the first round missed.
+
+Re-attempts only when the previous attempt materially changes the decision or risk. Do NOT spend a re-attempt on mechanical changes or already-resolved findings. When exhausted, escalate to the user with options (accept risk / change scope / exceptional budget).

package/skills/delegation-patterns/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: delegation-patterns
-description: "Subagent/team delegation workflow."
+description: >
+  Subagent/team delegation workflow.
+  When NOT to use: pure read-only investigation (use read-only-explorer); pre-planning analysis (use scrutinize).
+
 origin: pi-crew
 triggers:
   - "delegate this"
@@ -118,3 +121,17 @@ npx tsc --noEmit
 node --experimental-strip-types --test test/unit/team-recommendation.test.ts test/unit/task-output-context-security.test.ts test/integration/phase3-runtime.test.ts
 npm test
 ```
+
+## Budget
+
+This skill applies a 3-attempt budget: 1 initial + max 2 re-attempts.
+
+Stamp every invocation:
+
+```
+attempt X of 3 (Y attempts remaining)
+```
+
+An attempt is one delegation decision (choose agent/team → dispatch → collect). Re-attempt when the delegation target fails or returns unusable output.
+
+Re-attempts only when the previous attempt materially changes the decision or risk. Do NOT spend a re-attempt on mechanical changes or already-resolved findings. When exhausted, escalate to the user with options (accept risk / change scope / exceptional budget).