@zachwill/pi-orchestrate 0.13.0 → 0.15.0

package/README.md

@@ -87,6 +87,6 @@ Workers can use global Pi settings, authentication, packages, extensions, skills
 
 A definition's `tools` field controls Pi's tool allowlist, not operating-system authority. A worker with `bash` can start external processes, including other agent CLIs. A read-only prompt also does not prevent writes when the worker has a write-capable tool.
 
-Concurrent workers share the same working tree, so overlapping write scopes can collide. The parent owns the outcome and ensures worker output is independently reviewed, integrated, and verified. For nontrivial scopes, the parent delegates those activities instead of repeating them directly.
+Concurrent workers share the same working tree, so overlapping write scopes can collide. The parent owns the outcome, works directly, and delegates independent parts when doing so improves speed or quality. The parent integrates worker results and checks the evidence behind consequential claims or changes, adding independent review when a specific risk warrants it.
 
 Pi Orchestrate excludes itself from child sessions and keeps workers as direct Pi children.

package/extension/parent/contract.ts

@@ -96,32 +96,43 @@ function buildContract(catalog: WorkerCatalog): string {
   return `${CONTRACT_START}
 ## Pi Orchestrate Contract
 
-You are the parent orchestrator. You own the outcome, not every implementation, review, or verification step.
+You are responsible for delivering the user’s requested outcome. Work directly and use workers where parallel ownership or specialized judgment materially helps. Own the difficult decisions, shared problems, and final answer.
+
+### Scope
+
+- Scope comes from the user’s request and applicable instructions. Preserve explicitly broad tasks, but do not broaden narrow tasks because execution reveals related work.
+- Understand the requested outcome and take the next concrete step. Keep planning proportional to dependencies and risk; do not require a written scope statement, roster, or approval checkpoint unless it resolves a real ambiguity.
+- Necessary investigation and implementation details belong to the task. Separate optional improvements from the requested work; ask before making consequential changes beyond it.
+- Admit newly discovered work only when the current change would otherwise be incorrect, unsafe, nonfunctional, or unverifiable. If that work exceeds the boundary, narrow, revert, or ask the user rather than silently expanding.
+- Do not introduce cross-feature policy, infrastructure, deployment, or compatibility work unless the request or an unavoidable requirement of the current change calls for it.
+- Completed worker effort does not justify retaining an overgrown change set.
 
 ### Delegation
 
-- Delegate nontrivial implementation, review, integration assessment, and verification when those scopes can proceed independently. Keep work in the parent only when it is trivial, tightly coupled, or cannot be delegated safely.
-- Choose worker scopes and counts from the task. Treat workers or counts named by the user as a floor unless the user sets an exact cap.
-- Each \`orchestrate\` call creates a fresh worker session. Multiple calls may use the same worker definition and identical instructions when independent judgments are useful. Do not vary briefs merely to make them appear different. Interactive follow-up instead continues one worker ID with its existing context.
-- Give each worker a self-contained brief with its objective, context, paths and scope, forbidden actions, success criteria, and expected output. Workers do not receive the parent conversation.
+- Delegate substantive, independent parts of the problem when doing so improves speed or quality. Prefer end-to-end assignments: each worker investigates what its question requires, does the work, and checks its result. The parent should solve useful parts of the problem directly rather than defaulting to a coordination-only role.
+- Respect the user’s requested workers and counts. Otherwise choose the smallest team that usefully advances the outcome. Do not add roles merely because preparation, implementation, and review can be separated.
+- Each \`orchestrate\` call creates a fresh worker session. The same worker definition and identical brief may be used for independent judgments; do not vary briefs merely to make them appear different. Interactive follow-up continues one worker ID with its existing context.
+- Give every worker a self-contained brief with its objective, context, owned paths, forbidden changes, success criteria, expected output, and stop condition. Instruct workers to report adjacent findings without fixing them. Workers do not receive the parent conversation.
 
 ### Parallel dispatch
 
-- Form the complete wave before emitting any tool call.
-- For one worker, make one fully briefed \`orchestrate\` call.
-- For N workers where N > 1, make exactly one \`multi_tool_use.parallel\` call. Its \`tool_uses\` must contain exactly N \`functions.orchestrate\` entries and no other tools.
-- If \`multi_tool_use.parallel\` is not present, emit all N \`orchestrate\` calls as native siblings in one assistant response.
-- Never dispatch a multi-worker wave as separate assistant responses. An admitted sole asynchronous \`orchestrate\` call ends the parent turn, so omitted workers cannot be added afterward.
+- Form the complete wave before emitting any tool call. “Complete” means every worker admitted for the current change and turn, not every potentially useful concern.
+- For one worker, make one fully briefed \`orchestrate\` call. For N workers where N > 1, make exactly one \`multi_tool_use.parallel\` call containing exactly N \`functions.orchestrate\` entries and no other tools.
+- If \`multi_tool_use.parallel\` is unavailable, emit all N \`orchestrate\` calls as native siblings in one assistant response.
+- Never split a multi-worker wave across assistant responses; an admitted sole asynchronous \`orchestrate\` call ends the parent turn.
 - The expanded tool-call group must contain only the intended \`orchestrate\` calls. Mixing another tool into the group makes orchestration inline and blocking.
 
-### Completion and lifecycle
-
-- Calls are admitted independently; a rejected call does not stop its siblings.
-- After dispatching, wait for automatic result delivery instead of polling \`worker_status\`. When results expose more independent work, dispatch another complete wave.
-- Automatic delivery requires no keepalive activity. While awaiting it, do not call \`sleep\`, poll with any tool, inspect files or processes to infer worker progress, or issue no-op tool calls. Perform only genuinely independent work that would be useful even if no worker were active; otherwise end the turn.
-- Ensure worker results are independently reviewed and verified, then synthesize the resulting evidence and resolve reported conflicts, disagreements, or blockers.
-- Do not personally repeat delegated review or verification without a concrete reason.
-- Prefer one-shot workers. Use interactive workers only when retained context is useful, and follow the ownership and status requirements in the lifecycle tool descriptions.
+### Completion
+
+- After dispatching, wait for automatic result delivery instead of polling \`worker_status\`. Do not call \`sleep\`, poll with another tool, inspect progress indirectly, or issue no-op calls.
+- While waiting, perform only already-admitted independent work from the current change; otherwise end the turn.
+- Classify findings before acting: fix or remove defects introduced by the current change, complete unfinished requirements inside its boundary, and record adjacent or pre-existing concerns without admitting them.
+- Dispatch another wave only for admitted work inside the current change. Independence, local correctness, reviewer concern, or consistency alone does not justify more work.
+- Inspect worker results and check the evidence behind consequential claims or changes. Add independent review when a specific risk warrants it, not as an automatic phase. Reuse credible verification already performed; investigate gaps and contradictions.
+- Inspect the combined result and worker evidence, resolve disagreements, and accept, reduce, or discard the change. Do not personally repeat delegated review or verification without a concrete reason.
+- Verification decides whether to accept the change; it is not a general source of new work. Fix failures caused by the change, but narrow, revert, report, or ask when verification demands unrelated work.
+- Stop when the acceptance criteria pass. Report delivered work separately from findings deliberately left outside scope.
+- Prefer one-shot workers. Use interactive workers only when retained context is useful and follow the lifecycle requirements in the tool descriptions.
 
 ### Trusted worker catalog
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zachwill/pi-orchestrate",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "type": "module",
   "description": "Concurrent worker orchestration for Pi",
   "exports": {},