@melihmucuk/pi-crew 1.0.15 → 1.0.16

package/prompts/pi-crew-plan.md

@@ -1,166 +1,62 @@
 ---
-description: Run parallel subagents to investigate a codebase and produce an implementation plan for the given task.
+description: Orchestrate scouts and planner to produce an implementation plan.
 ---
 
 # Planning Orchestration
 
-## Input
+Additional instructions: `$ARGUMENTS`
 
-**Additional instructions**: `$ARGUMENTS`
+You are a planning orchestrator, not a scout, planner, or implementer. Resolve the task and scope, gather only minimal orientation context, delegate discovery to scouts when available, pass cleaned findings to the planner, and manage the planner lifecycle. Do not perform deep investigation, write the plan yourself, or modify files.
 
-## Role
+## Task and Context
 
-This is an orchestration prompt.
-Understand the task, gather minimal orientation context, delegate discovery to scout subagents, collect their findings, delegate planning to a planner subagent, and relay the planner's result to the user.
+Use additional instructions when provided; otherwise use the current conversation task. If the task or scope is decision-critical unclear or conflicting, ask the user before proceeding.
 
-Do not perform deep investigation yourself.
-Do not write the plan yourself.
-Do not modify files.
+Build shared context for subagents:
 
-## Task Resolution
+- user task;
+- project root;
+- constraints and additional instructions;
+- user-provided references as paths/URLs and why they matter;
+- scope boundary: in scope, out of scope, assumptions;
+- minimal orientation already gathered;
+- known stack, dependencies, conventions when relevant.
 
-Determine the task from:
+Do not copy full reference contents. Subagents cannot see conversation context unless you include it.
 
-- additional instructions, if provided
-- otherwise the current conversation context
+Gather only enough orientation to assign scout scopes or brief the planner: top-level structure, key config, README/AGENTS when relevant, and targeted searches or entrypoint checks. Do not read full files, trace call chains, or analyze implementations.
 
-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.
+## Scouts
 
-Identify any user-provided references that subagents may need, including file paths, images, documents, screenshots, or URLs.
+Call `crew_list` and check for `scout`. If unavailable, continue to planner with minimal context and note the missing scout coverage.
 
-## Shared Context Contract
+If available, spawn up to 4 scouts for distinct, non-overlapping focus areas. Keep each task narrow and include shared context, explicit investigation scope, requested facts, read-only constraints, and no build/test/install/format/codegen/server-start commands.
 
-Build this shared context once and pass it to every scout and to the planner:
+Wait for scout results without polling or fabrication. If a scout fails or returns no useful findings, retry or reformulate once. If it still fails, record the gap and continue.
 
-- 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
+Before planner handoff, perform only mechanical cleanup: remove duplicates, irrelevant generic notes, and out-of-scope findings; organize by area; preserve facts, paths, interfaces, constraints, conflicts, and discovery gaps. Do not add new inferences, risks, or recommendations.
 
-Do not copy full reference contents into subagent prompts.
-Do not assume subagents can access this conversation context unless you pass it along.
+## Planner
 
-## Orientation Context
+Call `crew_list` and check for `planner`. If unavailable, tell the user and stop; do not write the plan yourself.
 
-Gather only enough context to assign focused scout tasks.
+Spawn the planner with shared context, cleaned scout findings, and gaps. The planner is interactive and may return **Blocking Questions**, **Implementation Plan**, or **No plan needed**.
 
-Start with:
+Do not rewrite planner output that is already visible as a steering message.
 
-- top-level project structure
-- key config files to identify language, framework, and dependencies
-- README or AGENTS.md if present
+Lifecycle:
 
-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, and stop earlier if you already have enough.
-Do not trace call chains, analyze implementations, or read full files.
-
-## Scope Extraction
-
-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. If `scout` is unavailable, tell the user and stop.
-
-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.
-
-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:
-
-- explicit investigation scope
-- the specific information to return
-- 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.
-
-## Scout Waiting and Recovery
-
-Wait for all spawned scouts to return.
-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 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 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. If `planner` is unavailable, tell the user and stop.
-
-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 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 the shared context plus:
-
-- processed scout findings
-- any discovery gaps
-
-The planner is interactive. It may return:
-
-- Blocking Questions
-- Implementation Plan
-- No plan needed
-
-## Relay
-
-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
-- 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:
-- tell the user the plan is ready and ask for approval or feedback
-- relay any feedback with `crew_respond`
-- wait for the updated planner response
-
-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 and stop
-
-## Language
-
-Respond to the user in the same language as the user's request.
+- **Blocking Questions**: ask the user to answer; relay the answer with `crew_respond`. If the answer changes scope significantly, close with `crew_done` and restart with the new scope.
+- **Implementation Plan**: ask for approval or feedback; relay feedback with `crew_respond`; on approval, close with `crew_done` and confirm finalized.
+- **No plan needed**: close with `crew_done` and briefly confirm direct implementation is appropriate.
+- **Cancel**: close with `crew_done` and stop.
 
 ## Rules
 
+- Reply in the user's language.
 - 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.
+- Do not perform independent scouting, planning, or implementation.
+- Never answer planner questions for 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.
+- Do not poll for subagent completion.
+- Do not expand scope beyond the user's task.

package/prompts/pi-crew-review.md

@@ -1,150 +1,70 @@
 ---
-description: Run parallel code and quality reviews by gathering minimal context and orchestrating reviewer subagents.
+description: Orchestrate parallel code and quality reviews with reviewer subagents.
 ---
 
 # Parallel Review
 
-## Input
+Additional instructions: `$ARGUMENTS`
 
-**Additional instructions**: `$ARGUMENTS`
+You are a review orchestrator, not a reviewer. Resolve the review scope, gather only enough context to brief subagents, spawn reviewers, then filter and merge their results. Do not perform an independent review, read full files, or inspect raw diffs except for minimal scope clarification or spot-checking ambiguous findings.
 
-## Role
+## Scope
 
-This is an orchestration prompt.
-Determine review scope with minimal context gathering, prepare a short neutral brief, spawn the reviewer subagents, wait for their results, and merge them into one final report.
+Use the user's scope when provided. Otherwise review uncommitted changes: staged, unstaged, and untracked files. If “latest” or “recent” is requested, review the last 5 commits unless a count is given.
 
-Do not perform the review yourself.
-Do not perform a broad second review or re-investigate the whole repository. Your job is orchestration, filtering, and merging. If a reviewer finding is ambiguous, high-impact, or appears out of scope, you may do a minimal spot-check to clarify whether it is concrete enough to include.
+Gather minimal context: repo root, current branch, git status, relevant diff stats/name-only, untracked files, and any user instructions. Keep the brief neutral and descriptive, not analytical. Stop when scope and changed files are clear.
 
-## Scope Rules
+## Subagents
 
-- If the user specifies a scope (commit, branch, files, PR, or focus area), that scope overrides the default scope.
-- Otherwise, default scope includes:
-  - recent commits
-  - staged changes
-  - unstaged changes
-  - untracked files
+Call `crew_list` first and check for `code-reviewer` and `quality-reviewer`. Spawn available reviewers in parallel. If one is unavailable, fails to start, returns `error`, or is aborted, report that clearly and continue with completed reviewer results.
 
-## Context Gathering
+Send each reviewer a self-contained brief with:
+- repo root and branch;
+- resolved in-scope review target;
+- explicit out-of-scope boundaries;
+- commit range or changed file list;
+- staged/unstaged/untracked status when relevant;
+- short file/group summary;
+- additional user instructions;
+- instruction to ignore the reviewer’s own default scope if it differs from this brief.
 
-Collect only enough context to define scope and prepare a short brief.
+Add agent-specific non-goals:
+- `code-reviewer`: review realistic actionable bugs; do not do maintainability/style review.
+- `quality-reviewer`: review maintainability structure; do not hunt for bugs.
 
-Collect:
+Do not poll. Wait for all successfully spawned reviewers to return terminal results before the final report. Never fabricate subagent output.
 
-- repo root
-- current branch
-- `git status --short`
-- `git log --oneline --decorate -n 5`
-- `git diff --stat --cached`
-- `git diff --stat`
-- untracked file list
+## Acceptance Gate
 
-For recent commits:
+Before forwarding a finding, keep only evidence-backed, actionable findings with realistic trigger or concrete maintenance impact. Keep valid Minor findings. Omit speculative, optional, style-only, unsupported, out-of-scope, or weakly evidenced findings.
 
-- use `HEAD~3..HEAD` if at least 3 commits exist
-- otherwise use the widest reachable history range
-
-Collect for that range:
-
-- `git diff --stat <range>`
-- `git diff --name-only <range>`
-
-Rules:
-
-- Do not read full files before spawning subagents.
-- Do not dump raw diffs into the prompt.
-- Do not inspect every changed file manually.
-- Use full diffs or targeted reads only when file names and diff stats are insufficient to produce a short neutral summary.
-- Keep the brief short and descriptive, not analytical.
-- Watch for diminishing returns: if you have enough to define scope and write the brief, stop gathering context. More git commands or file reads at this stage add noise, not clarity.
-
-## Subagent Preparation
-
-Call `crew_list` first and verify that both are available:
-
-- `code-reviewer`
-- `quality-reviewer`
-
-Prepare one short brief for both reviewers including:
-
-- repo root
-- resolved review scope
-- commit range if any
-- staged / unstaged / untracked status
-- changed files
-- 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 terminal result (`done`, `error`, or `aborted`).
-Do not poll or repeatedly check active subagents while waiting; results will be delivered asynchronously.
-
-## Findings Acceptance Gate
-
-Before including a reviewer finding in the final report, apply these filters:
-
-Include a finding only if:
-- it is actionable now
-- it describes a realistic scenario for this project
-- it includes a concrete trigger or maintenance impact
-- it includes evidence or a clear rationale from the reviewer
-- its severity matches the described likelihood and impact
-
-Exclude findings that are:
-- speculative or theory-driven (no realistic trigger)
-- based on broken invariants or unsupported usage
-- style preferences or optional refactors without concrete bug risk
-- vague suggestions without concrete trigger, impact, or evidence
-
-Do not exclude a legitimate Minor finding that has a concrete trigger and realistic near-term impact. Minor findings with evidence pass the gate; Minor findings without evidence do not.
-
-If a finding clearly fails the gate, omit it rather than forwarding reviewer noise to the user. Prefer omission for weak or optional findings, but do not discard a potentially important finding solely because the reviewer wrote it imperfectly. The merged report should be shorter and more impactful than the raw reviewer outputs, not a concatenation of them.
+You may do a minimal spot-check only when a finding is ambiguous, high-impact, or possibly out of scope. Do not turn the spot-check into a second review.
 
 ## Merge
 
-Write the final response in the same language as the user's request.
+Reply in the user's language. Apply the gate before merging.
 
-Structure:
+Sections:
 
 ### Consensus Findings
-
-Merge only findings that are clearly the same issue reported by both reviewers.
+Issues clearly reported by both reviewers.
 
 ### Code Review Findings
-
-Include findings reported only by `code-reviewer`.
+Accepted findings only from `code-reviewer`.
 
 ### Quality Review Findings
-
-Include findings reported only by `quality-reviewer`.
+Accepted findings only from `quality-reviewer`.
 
 ### Final Summary
-
-Include:
-
-- review scope
-- which reviewers ran
-- consensus findings count
-- code review findings count
-- quality review findings count
-- overall assessment
+- Review scope
+- Reviewers run and any failures
+- Consensus findings count
+- Code review findings count
+- Quality review findings count
+- Overall assessment
 
 Rules:
-
 - Do not repeat overlapping findings.
-- Do not invent reviewer output, evidence, or counts.
 - Do not present a single-reviewer finding as consensus.
-- Apply the Findings Acceptance Gate before merging. Do not forward weak, speculative, or optional findings; if a single-reviewer finding appears important but ambiguous, do a minimal spot-check before deciding.
-- If both reviewers report no issues, say so explicitly.
-- If one reviewer failed or was unavailable, say so explicitly.
-- Review only. Do not make code changes.
-- Do not perform independent review beyond minimal scope and validity checks on reviewer findings. Only orchestrate reviewers and merge their reported results.
-- Never fabricate subagent results. Wait for all successfully spawned reviewers to return.
+- If both reviewers report no accepted findings, say so clearly.
+- Review only; do not change code.

package/skills/pi-crew/REFERENCE.md

@@ -0,0 +1,70 @@
+# Pi Crew Reference
+
+## Delegation Checklist
+
+Before `crew_spawn`, ensure the brief includes:
+
+- User goal and agreed decisions.
+- Relevant files, symbols, entry points, commands, errors, or logs.
+- Scope, constraints, and non-goals.
+- Whether the subagent may edit files or must only report.
+- Whether the task is exploratory, implementation, review, planning, or verification.
+- Expected output format.
+- Acceptance criteria.
+- Verification command, if known.
+
+Do not rely on hidden active-session context. If the subagent needs it, include it.
+
+## Good Brief
+
+```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 / entry points: `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.
+Non-goals: Do not refactor session ownership or delivery routing.
+Acceptance criteria: Identify root cause and minimal fix direction.
+Expected output: Root cause, minimal fix proposal, and verification command. Do not edit files.
+Verification: `npm run typecheck` if implementation is later requested.
+```
+
+## Bad Briefs
+
+```md
+Fix this.
+```
+
+```md
+Investigate the bug we discussed.
+```
+
+```md
+Implement the plan.
+```
+
+These depend on hidden conversation state and produce inconsistent results.
+
+## Parallel Delegation
+
+Use parallel subagents only when tasks are independent:
+
+- Good: one reviewer checks correctness while another checks maintainability.
+- Good: scouts inspect separate modules with non-overlapping files.
+- Bad: two workers edit the same file or feature area simultaneously.
+
+If ownership overlaps, serialize the work.
+
+## Failure and Conflict Handling
+
+- If a subagent errors or aborts, report that status clearly and continue only if remaining results are sufficient.
+- If a result misses acceptance criteria, ask a focused follow-up or spawn a new subagent with a corrected brief.
+- If results conflict, do not average them or pick silently. State the conflict, compare evidence, and resolve only with available facts or a targeted follow-up.
+- If a task becomes obsolete, abort the relevant active subagent.
+
+## Tool Notes
+
+- `crew_list`: discovery before a new spawn decision or requested status snapshot; never completion polling.
+- `crew_spawn`: self-contained delegation; ownership transfers after spawn.
+- `crew_respond`: send a follow-up to a waiting interactive subagent; fire-and-forget.
+- `crew_done`: close a waiting interactive subagent when complete.
+- `crew_abort`: abort active owned subagents only when obsolete, wrong, or cancelled.

package/skills/pi-crew/SKILL.md

@@ -1,129 +1,55 @@
 ---
 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."
+description: "MUST be read before using any pi-crew tool: crew_list, crew_spawn, crew_respond, crew_done, or crew_abort. Use for subagent delegation, async result handling, interactive lifecycle, anti-polling rules, and self-contained crew_spawn 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.
+Use this skill to coordinate subagents safely. Core rule: delegate clearly, do not duplicate delegated work, do not poll, and manage async/interactive lifecycle explicitly.
 
-## Core protocol
+See [REFERENCE.md](REFERENCE.md) for examples and detailed handling patterns.
 
-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.
+## Protocol
 
-## Before spawning
+- Call `crew_list` before each new spawn decision. Choose from discovered names, descriptions, capabilities, and `interactive` flags; do not assume fixed agents exist.
+- Spawn only when delegation adds clear value: independent parallel work, focused investigation, review, planning, implementation, or verification.
+- Do not spawn for tiny tasks, unclear tasks, or work whose required context cannot be summarized safely.
+- Before spawning, gather only the minimum context needed to brief the subagent. Do not complete the delegated investigation, review, plan, implementation, or solution yourself. After spawning, ownership transfers to the subagent.
+- Subagents cannot see your conversation, files read, commands run, decisions, or conclusions unless you include them in the task.
+- Parallel spawns must be independent and non-overlapping. If multiple subagents may touch the same files or ownership area, serialize them.
+- Results arrive asynchronously as steering messages. Do not poll with `crew_list`; call it again only for a new spawn decision or a user-requested status snapshot.
 
-Gather only enough context to write a useful task:
+## Spawn Brief
 
-- 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.
+Send a self-contained task. Include only relevant sections:
 
 ```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.
+Include paths, exact errors/output, edit permissions, task type, and constraints when they matter. Prefer path references over copying large file contents.
 
-## 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
+## Result Handling
 
+- Wait for subagent results before using them. Never invent or predict results.
+- Evaluate each result against the task acceptance criteria.
+- If results conflict, are incomplete, or miss criteria, state that clearly and use a follow-up or new spawn only when needed.
 - 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.
+## Interactive Subagents
 
-## Aborting
+- Use `crew_respond` only for a waiting interactive subagent when another answer is needed.
+- `crew_respond` is fire-and-forget; wait for the next steering result and do not poll.
+- Use `crew_done` only when a waiting interactive subagent is complete.
+- Do not call `crew_done` if you still need another answer.
 
-Use `crew_abort` only for active subagents owned by your active session.
+## Abort
 
-- 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.
+Use `crew_abort` only for active subagents owned by this session when the task is obsolete, wrong, or cancelled.