@melihmucuk/pi-crew 1.0.13 → 1.0.15

package/prompts/pi-crew-plan.md

@@ -24,9 +24,27 @@ Determine the task from:
 - additional instructions, if provided
 - otherwise the current conversation context
 
-If the task is still unclear, ask the user to clarify before proceeding.
+If the task is unclear or additional instructions conflict with the current conversation context in a decision-critical way, ask the user to clarify before proceeding.
 
-Identify any user-provided references that subagents may need, including file paths, images, documents, screenshots, or URLs. Include them explicitly in subagent tasks. Do not assume subagents can access this conversation context unless you pass it along.
+Identify any user-provided references that subagents may need, including file paths, images, documents, screenshots, or URLs.
+
+## Shared Context Contract
+
+Build this shared context once and pass it to every scout and to the planner:
+
+- the user's task
+- project root
+- additional instructions or constraints
+- relevant user-provided references as paths or URLs plus why they matter
+- explicit scope boundary:
+  - what the task requires (in scope)
+  - what the task does not require (out of scope)
+  - scope assumptions, if any
+- minimal orientation context already gathered
+- relevant language, framework, dependencies, and conventions when known
+
+Do not copy full reference contents into subagent prompts.
+Do not assume subagents can access this conversation context unless you pass it along.
 
 ## Orientation Context
 
@@ -38,47 +56,38 @@ Start with:
 - key config files to identify language, framework, and dependencies
 - README or AGENTS.md if present
 
-If needed, do lightweight exploration to find the relevant areas:
+If needed, do lightweight exploration to find the relevant areas, limited to at most 3 additional targeted directory browses or searches:
 
 - browse directories
 - read a few lines of entry points or index files
 - run targeted searches for task-related terms
 
-Stop once you can assign specific scout scopes. Watch for diminishing returns: if the last few files or directories you browsed produced no new insight relevant to scoping, you have enough orientation—proceed to assign scouts.
+Stop once you can assign specific scout scopes, and stop earlier if you already have enough.
 Do not trace call chains, analyze implementations, or read full files.
 
-### Scope Extraction
+## Scope Extraction
 
-Before assigning any scout tasks, extract the scope boundary from the user's task:
-
-- **What the task requires** (in scope)
-- **What the task does NOT require** (out of scope)
-- **Scope assumptions** (if any)
+Before assigning any scout tasks, extract the scope boundary from the user's task.
 
 Pass this scope boundary explicitly to every scout and to the planner. This gives subagents an explicit contract to check against, rather than having them infer scope from the task description alone.
 
 ## Scout Execution
 
-Call `crew_list` first and verify `scout` is available.
+Call `crew_list` first and verify `scout` is available. If `scout` is unavailable, tell the user and stop.
 
-Spawn up to 4 scouts in parallel. Each scout must have a distinct, non-overlapping focus.
+Spawn scouts in parallel using this rule: one focused area means 1 scout; 2-4 independent areas means 1 scout per area; more than 4 areas means choose the 4 highest-risk areas. Each scout must have a distinct, non-overlapping focus.
 
-Each scout task should include:
+After spawning scouts, send one brief status message to the user that scouts have been started and you are waiting for results.
+
+Each scout task should include the shared context plus:
 
-- the user's task
-- project root
-- minimal orientation context already gathered
-- **explicit scope boundary** (what's in scope and out of scope for this scout)
 - explicit investigation scope
 - the specific information to return
-- any relevant user-provided references
 - explicit read-only instruction
+- explicit bash restriction: do not run build, test, install, format, codegen, server start, or any command that writes files or mutates state
 
 Keep scout scopes narrow and non-overlapping. A scout that is asked to "investigate the auth system" will explore broadly. A scout that is asked to "find how login tokens are generated and which function validates them" will stay focused. Prefer the latter.
 
-If the task touches one area, one scout may be enough.
-If it spans multiple areas, split scouts by area or question.
-
 ## Scout Waiting and Recovery
 
 Wait for all spawned scouts to return.
@@ -86,33 +95,26 @@ Do not synthesize partial findings.
 Do not fabricate scout results.
 Do not poll repeatedly while waiting; results arrive asynchronously.
 
-If a scout fails or times out, retry once.
+If a scout fails or times out, retry the same task once.
 If a scout returns without useful findings, reformulate the task and spawn a replacement scout.
-If a retried or replacement scout still fails, proceed with the findings you have and note the gap for the planner.
+If a retried or replacement scout still fails or returns without useful findings, proceed with the findings you have and note the gap for the planner.
 
 ## Planner Execution
 
-Call `crew_list` first and verify `planner` is available.
+Call `crew_list` first and verify `planner` is available. If `planner` is unavailable, tell the user and stop.
 
-Before spawning the planner:
+Before spawning the planner, perform only mechanical cleanup. Do not add new inferences, risk analysis, or recommendations.
 
 - remove duplicate scout findings
 - drop irrelevant generic observations
-- drop findings outside the scope boundary (scouts sometimes drift)
+- drop findings outside the scope boundary except short `Out-of-scope risk/constraint` items that may affect the plan
 - organize findings by area
 - preserve specific facts, constraints, paths, interfaces, and conflicts
 - watch for diminishing returns: if later findings repeat or add no new specifics, you have enough—proceed to the planner rather than processing further
 
-Spawn the planner with:
+Spawn the planner with the shared context plus:
 
-- the user's task
-- additional instructions or constraints
-- relevant user-provided references
-- **explicit scope boundary** (in-scope / out-of-scope as extracted from the task)
 - processed scout findings
-- project root
-- language, framework, dependencies
-- relevant conventions
 - any discovery gaps
 
 The planner is interactive. It may return:
@@ -127,7 +129,9 @@ Do not rewrite subagent output that is already visible as a steering message.
 
 If the planner returns blocking questions:
 - ask the user to answer them
-- relay the user's response with `crew_respond`
+- if the user's answer expands scope, close the planner with `crew_done` and restart the workflow with the expanded scope
+- if the user's answer narrows scope, relay the response with `crew_respond`
+- otherwise relay the user's response with `crew_respond`
 - wait for the next planner response
 
 If the planner returns an implementation plan:
@@ -139,9 +143,13 @@ If the planner returns no plan needed:
 - close the planner with `crew_done`
 - briefly tell the user no plan is needed and that the task can be implemented directly
 
+If the user cancels planning:
+- close the planner with `crew_done`
+- stop
+
 If the user approves the plan:
 - close the planner with `crew_done`
-- confirm that the plan is finalized
+- confirm that the plan is finalized and stop
 
 ## Language
 
@@ -149,9 +157,10 @@ Respond to the user in the same language as the user's request.
 
 ## Rules
 
+- Do not modify files.
 - Do not investigate deeply yourself; delegate to scouts.
 - Do not write, modify, or finalize the plan yourself; use the planner.
 - Never answer planner questions on behalf of the user.
 - Never fabricate subagent results.
 - Always wait for explicit user approval before finalizing the plan.
-- Do not expand scope beyond what the user asked. If scouts return findings outside the task scope, drop them before passing to the planner.
+- Do not expand scope beyond what the user asked.

package/prompts/pi-crew-review.md

@@ -75,14 +75,16 @@ Prepare one short brief for both reviewers including:
 - short summary per file or file group
 - additional user instructions
 - **explicit scope boundary**: what is being reviewed (in scope) and what is not being reviewed (out of scope). For example: "Only the auth module changes are in scope. The unrelated CSS refactor in the same PR is out of scope for this review."
+- **explicit default override**: reviewers must review only the resolved scope in the brief and ignore their own default scope rules if they differ.
 
 ## Execution
 
 Spawn `code-reviewer` and `quality-reviewer` in parallel.
 
 If one reviewer is unavailable or fails to start, report that clearly and continue with the reviewer that is available.
+If a successfully spawned reviewer later returns `error` or `aborted`, report that clearly in the final summary and complete the report using only the reviewer results that completed successfully.
 
-Do not produce a final report until all successfully spawned reviewers have returned a result.
+Do not produce a final report until all successfully spawned reviewers have returned a terminal result (`done`, `error`, or `aborted`).
 Do not poll or repeatedly check active subagents while waiting; results will be delivered asynchronously.
 
 ## Findings Acceptance Gate

package/skills/pi-crew/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: pi-crew
+description: "MUST be read before using any pi-crew tool: crew_list, crew_spawn, crew_respond, crew_done, or crew_abort. Use for all subagent delegation, async result handling, interactive subagent lifecycle, anti-polling rules, and writing self-contained crew_spawn task briefs."
+---
+
+# Pi Crew
+
+Use this skill whenever you coordinate work with `pi-crew` tools. Its primary purpose is to standardize orchestrator behavior while teaching safe use of `crew_*` tools.
+
+## Core protocol
+
+1. Use `crew_list` to discover available subagents before each new spawn decision.
+2. Choose from the discovered subagents by their current names, descriptions, capabilities, and `interactive` flag. Do not assume any fixed subagent names exist.
+3. Spawn only when delegation creates clear value: parallel independent work, focused investigation, review, planning, or implementation that can be handled independently by a subagent.
+4. Do not spawn for tiny tasks, unclear tasks, or work whose required context cannot be summarized safely.
+5. Do not do the delegated work yourself before spawning or after spawning. Before spawning, gather only the minimum context needed to delegate; you may read enough files or output to create a self-contained task, but do not complete the investigation, review, implementation, or solution yourself. After spawning, ownership transfers to the subagent.
+6. Results arrive asynchronously as steering messages at any time. As the orchestrator, do not keep calling `crew_list` to check completion, and do not invent or predict subagent results.
+
+## Before spawning
+
+Gather only enough context to write a useful task:
+
+- user goal and agreed decisions
+- relevant files, symbols, commands, errors, or entry points
+- constraints and non-goals
+- expected output format
+- acceptance criteria
+- verification command, if known
+
+Do not fully investigate, implement, review, or solve the delegated task before spawning. That duplicates the subagent's work and creates conflicting conclusions.
+
+The subagent cannot access your active session. It cannot see user messages, decisions already made, files you discovered, commands you ran, or conclusions you reached unless you include the necessary information in the task.
+
+## `crew_spawn` task template
+
+Write the task as a self-contained brief. The subagent cannot see your current conversation or active session state unless you include the needed context.
+
+```md
+Goal:
+
+Context:
+
+Relevant files / entry points:
+
+Constraints:
+
+Non-goals:
+
+Acceptance criteria:
+
+Expected output:
+
+Verification:
+```
+
+Omit sections only when they are genuinely irrelevant.
+
+## Good delegation rules
+
+- Include absolute or repo-relative file paths when known.
+- If the finding is a file, reference it by path instead of copying the file contents into the task.
+- Include exact error messages or command output when they matter.
+- State whether the subagent may edit files or should only report findings.
+- State whether the task is exploratory, implementation, review, or verification.
+- For parallel spawns, make tasks independent and non-overlapping.
+- If multiple subagents may touch the same files, serialize the work instead of spawning in parallel.
+
+## Bad patterns
+
+Avoid tasks like:
+
+```md
+Fix this.
+```
+
+```md
+Investigate the bug we discussed.
+```
+
+```md
+Implement the plan.
+```
+
+These rely on hidden active-session context and produce inconsistent results.
+
+Prefer:
+
+```md
+Goal: Investigate why `crew_done` emits duplicate result messages.
+Context: Closing an interactive subagent should dispose the session without sending another result.
+Relevant files: `extension/runtime/crew-runtime.ts`, `extension/integration/tools/crew-done.ts`, `AGENTS.md`.
+Constraints: Do not change tool schemas. Do not edit unrelated lifecycle behavior.
+Expected output: Root cause, minimal fix proposal, and verification command. Do not edit files.
+```
+
+## Async result handling
+
+- After spawning, continue only with unrelated work or end the turn.
+- The subagent runs asynchronously and may answer at any time via a `crew-result` steering message.
+- Wait for the `crew-result` steering message before using the result.
+- If more subagents are still running, wait for each relevant result before combining conclusions.
+- Evaluate results against the task acceptance criteria before using them.
+- If results conflict, are incomplete, or miss acceptance criteria, state that explicitly and use a follow-up or new spawn only when needed.
+- Do not repeatedly call `crew_list` as an orchestrator. Call it again only for a user-requested status snapshot or to discover subagents for a new spawn decision.
+
+## Interactive subagents
+
+Interactive subagents stay alive after responding.
+
+- Use `crew_respond` to send a follow-up to a waiting interactive subagent.
+- `crew_respond` is fire-and-forget: the next response arrives asynchronously as a steering message.
+- Do not poll after `crew_respond`.
+- Use `crew_done` when the interaction is complete.
+- Do not call `crew_done` if you still need another answer from that subagent.
+
+## Tool safety quick rules
+
+- `crew_list`: do use for discovery before a new spawn decision or for a user-requested status snapshot; do not use it for polling completion.
+- `crew_spawn`: do send a self-contained task with constraints, non-goals, expected output, and acceptance criteria; do not rely on hidden active-session context.
+- `crew_respond`: do use only for a waiting interactive subagent when another answer is needed; do not poll afterward.
+- `crew_done`: do use only when a waiting interactive subagent interaction is complete; do not call it if another answer is needed.
+- `crew_abort`: do use only for active subagents owned by your active session when the task is obsolete, wrong, or cancelled; do not abort unrelated work.
+
+## Aborting
+
+Use `crew_abort` only for active subagents owned by your active session.
+
+- Abort a specific subagent when its task is obsolete or wrong.
+- Abort all owned subagents only when the user requests cancellation or your plan has changed so all delegated work is invalid.

package/dist/agent-discovery.d.ts

@@ -1,29 +0,0 @@
-import type { ThinkingLevel } from "@mariozechner/pi-agent-core";
-import { type SupportedToolName } from "./tool-registry.js";
-interface ParsedModel {
-    provider: string;
-    modelId: string;
-}
-export interface AgentConfig {
-    name: string;
-    description: string;
-    model?: string;
-    parsedModel?: ParsedModel;
-    thinking?: ThinkingLevel;
-    tools?: SupportedToolName[];
-    skills?: string[];
-    compaction?: boolean;
-    interactive?: boolean;
-    systemPrompt: string;
-    filePath: string;
-}
-export interface AgentDiscoveryWarning {
-    filePath: string;
-    message: string;
-}
-interface AgentDiscoveryResult {
-    agents: AgentConfig[];
-    warnings: AgentDiscoveryWarning[];
-}
-export declare function discoverAgents(cwd?: string): AgentDiscoveryResult;
-export {};