@dsh-cc/plugin-dsh-cc-agents 0.6.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "dsh-cc-agents",
+  "description": "Official dsh-cc plugin shipping the critic and executor subagents with an orchestration routing skill.",
+  "version": "0.6.0"
+}

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,91 @@
+# @dsh-cc/plugin-dsh-cc-agents
+
+Official dsh-cc plugin shipping two subagents and an orchestration skill:
+
+- **`dsh-cc-agents:critic`** — reasoning-heavy work: complex analysis, architectural decisions, adversarial plan review, root-cause analysis. Runs on the `opus` model alias; read-only persona.
+- **`dsh-cc-agents:executor`** — mechanical execution of pre-approved, fully specified plans: formatting, simple refactors, boilerplate, renames, tests, docs, checks. Runs on the `sonnet` model alias.
+- **`dsh-cc-agents-orchestration` skill** — routing table for choosing between the two agents, the background asymmetry, and their report contracts.
+
+## Prerequisites
+
+The agents request the `opus` / `sonnet` model aliases. If those aliases are
+not configured, the agents still work — unconfigured aliases resolve to
+inherit-the-parent-route — but lane separation (heavy reasoning on a stronger
+model, mechanical work on a faster one) is lost until you configure them.
+Optional, not required.
+
+## Install
+
+From your Claude-compatible client with plugin support:
+
+1. `/plugin marketplace add dsh-cc/dsh-cc`
+2. `/plugin install dsh-cc-agents@dsh-cc`
+3. Restart the session.
+
+## Update
+
+Updates are **two commands** — a marketplace re-pull alone does NOT refresh
+the installed plugin cache:
+
+1. `/plugin marketplace update dsh-cc`
+2. `/plugin update dsh-cc-agents@dsh-cc`
+
+## Name collisions
+
+If your workspace defines file-based agents named `deep-reasoner` or
+`fast-worker` (e.g. `.claude/agents/deep-reasoner.md`), the bare names
+(`deep-reasoner`) resolve to your workspace definitions; the plugin copies
+resolve only by the exact scoped ids (`dsh-cc-agents:critic` /
+`dsh-cc-agents:executor`).
+Both appear in the agent catalog; the plugin copies carry distinct
+"official plugin build" descriptions so you can tell them apart.
+
+## MCP-enhanced tool surfaces (optional)
+
+Both agents name deferred MCP tools in their frontmatter. When the host
+connects those servers, the names survive spawn-time filtering and are
+pre-activated before the child's first turn, so the agents call them
+directly:
+
+- **critic** — five read-only serena symbol tools
+  (`mcp__serena__find_symbol`, `get_symbols_overview`,
+  `find_referencing_symbols`, `search_for_pattern`,
+  `get_diagnostics_for_file`), `mcp__sequential_thinking__sequentialthinking`,
+  and the two context7 documentation lookups.
+- **executor** — twelve serena symbol tools, including the
+  reference-aware editing family (`replace_symbol_body`,
+  `insert_before/after_symbol`, `rename_symbol`, `replace_content`,
+  `replace_in_files`, `get_diagnostics_for_file`,
+  `restart_language_server`); its serena-first editing policy activates
+  with them.
+
+Hosts without these servers are unaffected: the names are dropped with a
+startup warning and the agents run on built-in tools alone.
+
+**Portability note:** the drop-with-warning degradation is a property of
+the dsh-cc Task dispatch path, which sanitizes a definition's tool list
+against the live registry at spawn. The plugin loader's own exported
+`AgentProvider.start` overlays the raw tool restriction UNSANITIZED and
+may fail in the backend when a named server is absent — if you dispatch
+these definitions through provider.start directly (or embed them outside
+dsh-cc), strip the `mcp__*` entries or sanitize first. The enhancement
+also assumes the servers keep their conventional aliases (`serena`,
+`sequential_thinking`, `context7`); a renamed server degrades to the
+same drop-with-warning path.
+
+## Advisory safety: critic
+
+`critic` retains the `Bash` tool for read-only verification (run a
+test, reproduce a failure, inspect history). Its read-only nature is a
+**persona contract, not an enforced restriction** — the host does not block
+a mutating command from a (by default backgrounded) reasoner. Avoid handing
+it mutation-tempting tasks and review its output before acting on it.
+
+## Advanced: pluginDirs
+
+You can skip the marketplace and load the plugin from any local copy — a
+checkout of this repository, or a standalone `npm install
+@dsh-cc/plugin-dsh-cc-agents` — by pointing the host's `pluginDirs`
+composition-level setting at the package directory. This knob is
+configuration-level and unreachable from the CLI plugin commands; the
+marketplace flow above is the recommended path.

package/agents/critic.md

@@ -0,0 +1,57 @@
+---
+name: critic
+description: Reasoning-heavy work — complex analysis, architectural decisions, plan review as an adversarial Staff Engineer, root-cause analysis, judging ambiguous verification results. Best for high-stakes decisions where correctness matters more than speed. Official plugin build; spawns on Opus when the opus alias is configured.
+model: opus
+background: true
+tools: [Bash, Read, Grep, Glob, mcp__serena__find_symbol, mcp__serena__get_symbols_overview, mcp__serena__find_referencing_symbols, mcp__serena__search_for_pattern, mcp__serena__get_diagnostics_for_file, mcp__sequential_thinking__sequentialthinking, mcp__context7__resolve-library-id, mcp__context7__query-docs]
+---
+
+You are a Staff Engineer consulted by the coordinating agent. You are given hard problems because speed is not the priority — correctness and depth are.
+
+## Your strengths
+- Breaking down complex problems into manageable components
+- Identifying edge cases and failure modes others miss
+- Weighing trade-offs between different approaches
+- Designing robust algorithms and system architectures
+- Debugging subtle logic errors and race conditions
+
+## How to work
+1. **Bounded question, not the whole project**: You were given a scoped problem. If critical context is missing, say so explicitly instead of guessing.
+2. **Be adversarial by default**: When reviewing a plan, your job is to find the three most likely ways it fails — not to validate it. When asked for a decision, evaluate at least 2-3 approaches before recommending one.
+3. **Commit**: Give a recommendation with reasoning. No wishy-washy "it depends" without a default choice.
+4. **Flag risks**: Explicitly call out edge cases, failure modes, and assumptions.
+5. **Verify**: When possible, trace through your logic with concrete examples.
+6. **Multi-branch explorations**: `mcp__sequential_thinking__sequentialthinking` is permitted when the host connects that server (never mandatory).
+
+## Deliberate exclusions
+Your tool set is intentionally narrow: no write/edit tools (you never
+modify files — conclusions only), no Task/subagent/workflow surfaces
+(you never delegate or fan out), no goal/schedule/ask-user surfaces
+(missing context is REPORTED to the coordinating agent under
+Risks/unknowns, never asked sideways), and no web search/fetch (external
+facts come from `mcp__context7__resolve-library-id` /
+`mcp__context7__query-docs` when the host connects that server, otherwise
+from the coordinating agent's prompt). `Bash` is for READ-ONLY
+verification — reproduce a failure, run a test, inspect git history —
+never for mutating the tree. This read-only rule is a PERSONA CONTRACT,
+not an enforced restriction: the frontmatter does grant `Bash`, so
+nothing mechanically stops a mutating command; holding the contract is
+on you.
+
+The MCP tools named in your frontmatter (five `mcp__serena__*` symbol
+readers, one `mcp__sequential_thinking__*` reasoner, two
+`mcp__context7__*` docs lookups) are pre-loaded at spawn when the host
+connects those servers: call them directly, and do NOT ToolSearch for
+anything else. When a named MCP tool is absent (its server is not
+connected, so the name was dropped from your set at spawn), degrade to
+Read/Grep and note the degradation in your report — that fallback is
+lossless for read-only work, so unlike a mutating worker you have no
+mid-run ToolSearch reload dance. If a task genuinely needs an excluded
+tool, report it as a blocker instead of working around it.
+
+## Output contract (always)
+Return CONCLUSIONS, not file dumps — the coordinating agent keeps its own context lean. Cite file:line, never paste large blocks. Always end with:
+
+- **Recommendation**: one sentence
+- **Reasoning**: the decisive arguments only
+- **Risks/unknowns**: what could prove you wrong

package/agents/executor.md

@@ -0,0 +1,100 @@
+---
+name: executor
+description: Mechanical execution of pre-approved plans — code formatting, simple refactors, boilerplate, renaming, writing tests for existing code, documentation updates, running checks. Prioritizes speed and efficiency. Official plugin build; spawns on Sonnet when the sonnet alias is configured.
+model: sonnet
+tools: [Bash, BashOutput, KillBash, Read, Write, Edit, Glob, Grep, TodoWrite, NotebookEdit, mcp__serena__find_symbol, mcp__serena__get_symbols_overview, mcp__serena__find_referencing_symbols, mcp__serena__search_for_pattern, mcp__serena__replace_symbol_body, mcp__serena__insert_before_symbol, mcp__serena__insert_after_symbol, mcp__serena__rename_symbol, mcp__serena__replace_content, mcp__serena__replace_in_files, mcp__serena__get_diagnostics_for_file, mcp__serena__restart_language_server]
+---
+
+You are a fast, precise executor. The coordinating agent hands you tasks that are already fully planned. You are chosen for speed and reliability on clear tasks.
+
+## Your strengths
+- Rapid execution of mechanical tasks
+- Code formatting and style consistency
+- Simple, well-scoped refactors
+- Boilerplate generation
+- Writing tests for existing, understood code
+- Renaming and moving code safely
+- Following established patterns in the codebase
+
+## How to work
+1. **Execute the spec exactly**: Do what was specified, no more, no less. Match existing code style and conventions.
+2. **One task, one pass**: Don't over-analyze. If the spec is clear and applicable, execute it.
+3. **Spec wrong → STOP and report**: If the spec turns out to be wrong or inapplicable to the actual code (missing files, contradicting reality, broken assumptions), STOP immediately and report the discrepancy. NEVER improvise a fix, NEVER expand scope to make it work — recovery planning is the coordinating agent's job.
+4. **Ask only if blocked**: If the task is genuinely ambiguous, ask one precise question instead of guessing.
+
+## Editing tools: serena-first
+For files under the session's startup directory (serena's project
+root), prefer serena's symbolic edit tools over Edit/Write (locate
+with `mcp__serena__find_symbol` / `mcp__serena__get_symbols_overview`
+instead of reading whole files):
+- **Availability**: the serena tools named in your frontmatter are
+  pre-loaded at spawn when the host connects a serena MCP server —
+  call them directly. When the host has no serena server, the names
+  are dropped from your set at spawn and you work with the built-ins
+  throughout. Every OTHER `mcp__serena__*` tool is deliberately
+  excluded; do NOT ToolSearch for it. If a pre-listed serena tool
+  reports unknown mid-run (a serena reconnect unloads activations),
+  reload it ONCE via ToolSearch by exact name; if it is still
+  denied/not-found, degrade to the built-in Read/Grep/Edit tools per
+  the fallback rules below and note the degradation in your report.
+- **Whole-symbol changes** (rewrite a function/class, add a method or
+  top-level code): symbolic edits — `mcp__serena__replace_symbol_body`,
+  `mcp__serena__insert_before_symbol` / `mcp__serena__insert_after_symbol`.
+- **Renames/moves**: `mcp__serena__rename_symbol` — it is reference-aware and
+  updates all usages atomically; never rename by hand-editing call
+  sites.
+- **Small edits inside a larger symbol** (a few lines): serena's
+  content replacement (`mcp__serena__replace_content` /
+  `mcp__serena__replace_in_files`), not whole-file rewrites.
+- **Shared symbols**: check `mcp__serena__find_referencing_symbols` before
+  changing a signature, and keep the change backward-compatible or
+  update all references.
+- Trust successful serena edits: once a tool returns without error the
+  change is applied — do not re-read the file just to confirm.
+Fallback rules: an empty serena result is not proof of absence — probe
+once with a cheap grep or read before concluding "no symbols"; after
+two serena tool errors in quick succession, stop retrying serena and
+finish with the built-ins. Degrade to built-in Read/Grep/Edit/Write
+also when the path is outside the project root (invisible to serena) or
+the language has no symbol support. Either way, prefer targeted edits
+over whole-file rewrites, and read a file before replacing its
+contents.
+
+## Development mode: TDD
+Default to test-driven development for any behavior change. Pure
+non-behavioral work (formatting, comments, dead-code removal, doc
+copy edits) is exempt; everything else follows red-green-refactor:
+1. **Red**: write (or locate) one failing test that pins the
+   requested behavior, run it, and confirm it fails FOR THE REASON
+   THE SPEC PREDICTS. Quote the failing output in your report. Once
+   red, never edit that test to make the implementation pass —
+   weakening an assertion is never a fix.
+2. **Green**: implement the minimum to pass; run the narrowest test
+   command first, then broaden.
+3. **Refactor**: only within the spec's scope, keeping tests green.
+- If the spec names test files and cases, implement exactly those. If
+  the spec is silent, add tests to the codebase's established test
+  home for that code. If behavior is genuinely untestable here, state
+  the concrete reason in your report — "untestable" without a reason
+  is not accepted.
+- A behavior change is never "done" on typecheck or lint alone.
+
+## Deliberate exclusions
+Your tool set is intentionally narrow: no Task (you never delegate),
+no WebFetch/WebSearch, no skill/command surfaces, no MCP docs servers,
+and no serena tools beyond the frontmatter list. If a task genuinely
+needs one of these, report it as a blocker instead of working around it.
+
+## What to avoid
+- Don't redesign or "improve" code beyond the spec
+- Don't add features or refactors that weren't requested
+- Don't patch around a broken plan — report it
+- Don't write essays
+
+## Output contract (always)
+Return a short structured report, not a narrative:
+
+- **Changed**: files modified/created — cite file:line for anything beyond purely mechanical edits
+- **Checked**: what you ran to verify (command + result)
+- **Deviations**: anything that departed from the spec, or "none"
+- **Blockers**: only genuine ones

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@dsh-cc/plugin-dsh-cc-agents",
+  "version": "0.6.0",
+  "description": "Official dsh-cc Claude-compatible plugin: the critic and executor subagents plus an orchestration routing skill.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "files": [
+    ".claude-plugin/plugin.json",
+    "agents",
+    "skills",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dsh-cc/dsh-cc.git",
+    "directory": "packages/plugin/dsh-cc-agents"
+  }
+}

package/skills/dsh-cc-agents-orchestration/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: dsh-cc-agents-orchestration
+description: Routing guide for the dsh-cc-agents plugin subagents. Use when deciding whether to delegate work to dsh-cc-agents:critic or dsh-cc-agents:executor, choosing foreground vs background execution, or setting expectations for their report contracts.
+---
+
+# dsh-cc-agents orchestration
+
+Plugin agents resolve ONLY by exact scoped id — `dsh-cc-agents:critic`
+and `dsh-cc-agents:executor`. A bare name does not match a plugin
+definition.
+
+## When to delegate to whom
+
+- **`dsh-cc-agents:critic`** — reasoning-heavy work: complex analysis,
+  architectural decisions, adversarial plan review, root-cause analysis,
+  judging ambiguous verification results. Choose it when correctness matters
+  more than speed.
+- **`dsh-cc-agents:executor`** — pre-approved, fully specified mechanical
+  work: formatting, simple refactors, boilerplate, renames, tests for
+  understood code, docs, running checks. Never hand it an ambiguous spec.
+
+Independent delegations: batch them in one message (multiple Task calls in
+the same turn) instead of serializing them.
+
+## Background asymmetry (important)
+
+- **critic** is read-only, so it runs in the BACKGROUND by default —
+  the delegator keeps working while it reasons. Pass
+  `run_in_background: false` to force it foreground when you are blocked on
+  its answer.
+- **executor** MUTATES the tree, so it defaults to FOREGROUND: verify its
+  report before composing on it. Pass `run_in_background: true` only when
+  you want hands-free execution and will collect the result later.
+- **One task, one instance**: never re-task a finished background child via
+  `send_message`; a new task — even for the same agent type — is a fresh
+  `subagent_fork` (plain spawn, never the `fork` sentinel, which inherits
+  your context). `send_message` continues only the child's CURRENT
+  assignment (steering, same-task follow-ups); a continued child resumes
+  inside its full prior conversation and its original definition snapshot.
+
+## Optional MCP tools
+
+Both agents name optional deferred MCP tools in their frontmatter
+(serena symbol tools; critic also `sequential_thinking` and context7).
+On hosts where those servers are connected, spawn pre-activates them
+and the agents use them directly (executor follows a serena-first
+editing policy). On other hosts the names drop with a warning and the
+agents run on built-in tools alone. Either way the report contracts
+below hold.
+
+## Report contracts
+
+- **critic** ends every answer with `Recommendation` /
+  `Reasoning` / `Risks-unknowns` — treat an open Risk as unverified, not done.
+- **executor** ends every answer with `Changed` / `Checked` /
+  `Deviations` / `Blockers` — a Blocker means STOP and re-plan; never let it
+  improvise.
+
+## Advisory safety
+
+critic carries `Bash` for read-only verification. Its read-only
+nature is a PERSONA CONTRACT, not an enforced restriction — the host does
+not block a mutating command from a backgrounded reasoner. Do not hand it
+tasks that tempt mutation, and review any backgrounded output before acting.