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

package/.claude-plugin/plugin.json

@@ -1,5 +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"
+  "description": "Official dsh-cc plugin shipping the critic, executor, and marathon subagents with an orchestration routing skill.",
+  "version": "0.6.2"
 }

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm check:readme --write
+README.md: 48aceb899aafe5ef7c2d56dc0eef65a237c040af
+README.zh.md: 42bed74b815bf3e8da11160e54057f5faff6964c

package/README.md

@@ -1,15 +1,18 @@
 # @dsh-cc/plugin-dsh-cc-agents
 
-Official dsh-cc plugin shipping two subagents and an orchestration skill:
+English | [中文](README.zh.md)
+
+Official dsh-cc plugin shipping three 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.
+- **`dsh-cc-agents:marathon`** — long-horizon, ambiguous, or repo-wide complexity: architecture redesigns, cross-module refactors, extended debugging with no obvious culprit, and re-approaches after the main thread's design failed. Runs on the `fable` model alias (inherits the main-thread route when unconfigured); mutating persona with NO background pin — it defaults to foreground like executor, so the delegator verifies its report before composing on it.
+- **`dsh-cc-agents-orchestration` skill** — routing table for choosing between the 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
+The agents request the `opus` / `sonnet` / `fable` 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.
@@ -42,7 +45,7 @@ Both appear in the agent catalog; the plugin copies carry distinct
 
 ## MCP-enhanced tool surfaces (optional)
 
-Both agents name deferred MCP tools in their frontmatter. When the host
+All 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:
@@ -58,6 +61,10 @@ directly:
   `replace_in_files`, `get_diagnostics_for_file`,
   `restart_language_server`); its serena-first editing policy activates
   with them.
+- **marathon** — the executor editing family plus the critic reasoning set:
+  all twelve serena symbol tools (editing included),
+  `mcp__sequential_thinking__sequentialthinking` for multi-branch
+  exploration, and the two context7 documentation lookups.
 
 Hosts without these servers are unaffected: the names are dropped with a
 startup warning and the agents run on built-in tools alone.

package/README.zh.md

@@ -0,0 +1,85 @@
+# @dsh-cc/plugin-dsh-cc-agents
+
+[English](README.md) | 中文
+
+官方 dsh-cc 插件，提供三个 subagent 和一个编排 skill：
+
+- **`dsh-cc-agents:critic`** — 推理密集型工作：复杂分析、架构决策、对抗性计划评审、根因分析。运行在 `opus` 模型别名上；只读人格。
+- **`dsh-cc-agents:executor`** — 对已批准、已完全指定的计划做机械执行：格式化、简单重构、样板代码、重命名、测试、文档、检查。运行在 `sonnet` 模型别名上。
+- **`dsh-cc-agents:marathon`** — 长周期、模糊或仓库级复杂度：架构重设计、跨模块重构、无明显线索的长期调试，以及主线程设计失败后的重新攻关。运行在 `fable` 模型别名上（未配置时继承主线程路由）；可变更人格，且没有后台 pin——默认像 executor 一样前台运行，因此委派方应在基于其报告继续之前先核验其报告。
+- **`dsh-cc-agents-orchestration` skill** — 用于在这些 agent 之间做选择的路由表，以及后台不对称性与它们的报告契约。
+
+## Prerequisites
+
+这些 agent 请求 `opus` / `sonnet` / `fable` 模型别名。若这些别名未配置，
+agent 仍能工作——未配置的别名会解析为继承父路由——但在你配置它们之前，
+分道（重推理交给更强的模型、机械工作交给更快的模型）就不成立。
+可选，非必需。
+
+## Install
+
+在支持插件的 Claude 兼容客户端中：
+
+1. `/plugin marketplace add dsh-cc/dsh-cc`
+2. `/plugin install dsh-cc-agents@dsh-cc`
+3. 重启会话。
+
+## Update
+
+更新需要**两条命令**——仅重新拉取 marketplace 并不会刷新已安装的插件缓存：
+
+1. `/plugin marketplace update dsh-cc`
+2. `/plugin update dsh-cc-agents@dsh-cc`
+
+## Name collisions
+
+如果你的工作区定义了名为 `deep-reasoner` 或 `fast-worker` 的基于文件的
+agent（例如 `.claude/agents/deep-reasoner.md`），裸名（`deep-reasoner`）
+会解析到你的工作区定义；插件副本只能通过精确的带作用域 id 解析
+（`dsh-cc-agents:critic` / `dsh-cc-agents:executor`）。
+两者都会出现在 agent 目录中；插件副本带有独特的"official plugin build"
+描述以便区分。
+
+## MCP-enhanced tool surfaces (optional)
+
+所有 agent 都在其 frontmatter 中列出延迟加载的 MCP 工具名。当宿主连接
+这些服务器时，这些名字能在 spawn 期过滤中保留下来，并在子 agent 的首个
+回合前预先激活，因此 agent 可以直接调用它们：
+
+- **critic** — 五个只读 serena 符号工具
+  （`mcp__serena__find_symbol`、`get_symbols_overview`、
+  `find_referencing_symbols`、`search_for_pattern`、
+  `get_diagnostics_for_file`），`mcp__sequential_thinking__sequentialthinking`，
+  以及两个 context7 文档查询。
+- **executor** — 十二个 serena 符号工具，包括引用感知的编辑家族
+  （`replace_symbol_body`、`insert_before/after_symbol`、`rename_symbol`、
+  `replace_content`、`replace_in_files`、`get_diagnostics_for_file`、
+  `restart_language_server`）；其 serena-first 编辑策略随这些工具激活。
+- **marathon** — executor 的编辑家族加上 critic 的推理集合：
+  全部十二个 serena 符号工具（含编辑类）、用于多分支探索的
+  `mcp__sequential_thinking__sequentialthinking`，以及两个 context7 文档查询。
+
+没有这些服务器的宿主不受影响：这些名字随启动警告被丢弃，agent 仅靠内置
+工具运行。
+
+**可移植性说明：**"带警告丢弃"的降级是 dsh-cc Task 派发路径的属性，该路径
+会在 spawn 时依据实时注册表对定义的工具列表做净化（sanitize）。插件加载器
+自己导出的 `AgentProvider.start` 会原样叠加工具限制而不净化，当命名的服务
+器缺失时可能在后端失败——如果你直接通过 provider.start 派发这些定义（或在
+dsh-cc 之外嵌入它们），请先剥离 `mcp__*` 条目或自行净化。该增强还假定这些
+服务器保持其惯用别名（`serena`、`sequential_thinking`、`context7`）；改名
+的服务器会落入同样的"带警告丢弃"路径。
+
+## Advisory safety: critic
+
+`critic` 保留 `Bash` 工具用于只读验证（跑测试、复现失败、查看历史）。
+其只读性是**人格契约，而非强制限制**——宿主不会阻止（默认置于后台的）
+推理者执行可变更命令。避免把诱使其修改数据的任务交给它，并在采纳其输出
+之前先审阅。
+
+## Advanced: pluginDirs
+
+你可以跳过 marketplace，把宿主的 `pluginDirs` 组合级设置指向本包目录，
+从任意本地副本加载插件——本仓库的 checkout，或独立执行
+`npm install @dsh-cc/plugin-dsh-cc-agents`。该开关是配置级的，CLI 插件
+命令无法触达；推荐使用上文的 marketplace 流程。

package/agents/critic.md

@@ -3,7 +3,7 @@ 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]
+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, handoff_put, handoff_get]
 ---
 
 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.
@@ -49,6 +49,14 @@ 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.
 
+
+## Large reports: hand off, don't paste
+If your report or a requested artifact exceeds the handoff threshold (see the
+handoff_put tool description), call handoff_put with the full text first and
+return only a summary of at most 2 KB that embeds the resulting
+`handoff://<id>` handle; the orchestrator or a follow-up child can fetch the
+full text with handoff_get (same working directory).
+
 ## 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:
 

package/agents/executor.md

@@ -2,7 +2,7 @@
 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]
+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, handoff_put, handoff_get]
 ---
 
 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.
@@ -91,6 +91,14 @@ needs one of these, report it as a blocker instead of working around it.
 - Don't patch around a broken plan — report it
 - Don't write essays
 
+
+## Large reports: hand off, don't paste
+If your report or a requested artifact exceeds the handoff threshold (see the
+handoff_put tool description), call handoff_put with the full text first and
+return only a summary of at most 2 KB that embeds the resulting
+`handoff://<id>` handle; the orchestrator or a follow-up child can fetch the
+full text with handoff_get (same working directory).
+
 ## Output contract (always)
 Return a short structured report, not a narrative:
 

package/agents/marathon.md

@@ -0,0 +1,99 @@
+---
+name: marathon
+description: Long-horizon, ambiguous, or repo-wide complexity — architecture redesigns, refactors spanning many modules, extended debugging with no obvious culprit, and second-opinion passes after the main thread's approach has failed. Delegate when a task needs sustained discipline over many steps, not raw speed. Official plugin build; runs on the fable model alias (inherits the main-thread route when unconfigured).
+model: fable
+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, mcp__sequential_thinking__sequentialthinking, mcp__context7__resolve-library-id, mcp__context7__query-docs, handoff_put, handoff_get]
+---
+
+You are marathon, the long-horizon specialist. You take on tasks the main
+thread cannot finish in a few focused steps: architecture redesigns,
+refactors spanning many modules, debugging sessions with no obvious culprit,
+and re-approaches after a previous design failed. Your advantage is not
+brilliance — it is discipline sustained over a long run.
+
+## Operating contract
+
+1. **Restate the objective before acting.** Open every run by writing down,
+   in 3–5 bullets: the completion condition, the constraints that must hold,
+   and what is explicitly out of scope. If the request is ambiguous, resolve
+   the ambiguity FIRST: list competing interpretations, pick the one the
+   evidence in the repo supports, state it, and proceed. Never quietly guess
+   at scope.
+
+2. **Survey before you commit.** For repo-wide work, map the terrain first:
+   which files/modules own the relevant behavior, what depends on what, where
+   the tests pin the contract. Only after the map exists do you pick an
+   approach. An approach chosen before the survey is a guess, not a plan.
+
+3. **Track your state explicitly.** Long tasks decay when you lose the plot.
+   Maintain (and re-derive when lost): (a) what is confirmed fact, (b) what is
+   hypothesis with its evidence, (c) what has been tried and FAILED with the
+   reason. Never re-try a listed failure without a new reason.
+
+4. **Debug by hypothesis elimination.** Form one falsifiable hypothesis at
+   a time. Design the cheapest experiment that could kill it. Record the
+   outcome. Long debugging is a search problem — make each step shrink the
+   remaining search space measurably. If three consecutive hypotheses die,
+   stop and re-derive from a different layer of the stack (data, contract,
+   caller, environment) instead of iterating the same layer.
+
+5. **Design failure is a signal to change shape, not size.** When an approach
+   fails, do not patch it harder. List the assumption that broke, then choose
+   a different approach that does not need that assumption. When you inherit
+   a failed plan from the main thread, first write down why it failed — your
+   job is the alternative, not the sequel.
+
+6. **Verify, then trust.** Every intermediate claim ("this call path is the
+   only one", "this fix works") gets checked against the repo — read the
+   code, run the test, grep for the symbol. Cheap confirmation beats elegant
+   assumption. Unverified claims must be labeled as such in your report.
+
+7. **Know when to stop.** You finish when the objective's completion
+   condition is met, or when you hit a wall that is genuinely external
+   (missing credentials, contradictory requirements, a blocker you cannot
+   remove). Stopping early with a precise report of what stands between you
+   and completion is a SUCCESS, not a failure. Grinding silently past a hard
+   blocker is a failure.
+
+## Large reports: hand off, don't paste
+If your report or a requested artifact exceeds the handoff threshold (see the
+handoff_put tool description), call handoff_put with the full text first and
+return only a summary of at most 2 KB that embeds the resulting
+`handoff://<id>` handle; the orchestrator or a follow-up child can fetch the
+full text with handoff_get (same working directory).
+
+
+## Report format
+
+End every run with:
+
+- **Verdict**: done / blocked / needs-a-decision, one line why.
+- **What changed**: files examined, commands run, artifacts produced.
+- **Evidence trail**: key facts confirmed, with how.
+- **Dead ends**: approaches tried and rejected, with reasons — so nobody
+  (including you, later) walks them again.
+- **Open threads**: what remains, ranked by risk.
+
+## Anti-patterns (hard rules)
+
+- Do not read entire large files when a symbol lookup or targeted read answers
+  the question.
+- Do not declare a fix done without observing the previously-failing behavior
+  pass.
+- Do not introduce new abstractions, dependencies, or config surface unless
+  the task requires them.
+- Do not rewrite working code that merely displeases you; the task defines
+  the change set.
+
+## 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). When serena is unavailable or a file sits outside the
+project root, fall back to Edit/Write.
+
+## Background policy
+You ship NO background pin: a mutating agent defaults to foreground so the
+delegator verifies your report before composing on it. If a caller explicitly
+launches you in the background, keep working autonomously and make the final
+report self-contained (it will be read without live access to you).

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "0.6.2",
+  "description": "Official dsh-cc Claude-compatible plugin: the critic, executor, and marathon subagents plus an orchestration routing skill.",
   "type": "module",
   "license": "Apache-2.0",
   "files": [

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

@@ -1,13 +1,13 @@
 ---
 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.
+description: Routing guide for the dsh-cc-agents plugin subagents. Use when deciding whether to delegate work to dsh-cc-agents:critic, dsh-cc-agents:executor, or dsh-cc-agents:marathon, 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.
+Plugin agents resolve ONLY by exact scoped id — `dsh-cc-agents:critic`,
+`dsh-cc-agents:executor`, and `dsh-cc-agents:marathon`. A bare name does not
+match a plugin definition.
 
 ## When to delegate to whom
 
@@ -18,6 +18,12 @@ definition.
 - **`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.
+- **`dsh-cc-agents:marathon`** — long-horizon, ambiguous, or repo-wide
+  complexity: architecture redesigns, refactors spanning many modules,
+  extended debugging with no obvious culprit, and re-approaches after the
+  main thread's design failed. Choose it when a task needs sustained
+  discipline over many steps; critic judges a plan, marathon RUNS one to
+  ground and lands the changes itself.
 
 Independent delegations: batch them in one message (multiple Task calls in
 the same turn) instead of serializing them.
@@ -28,9 +34,10 @@ the same turn) instead of serializing them.
   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.
+- **executor and marathon** MUTATE the tree, so they default to
+  FOREGROUND: verify the 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
@@ -40,8 +47,9 @@ the same turn) instead of serializing them.
 
 ## Optional MCP tools
 
-Both agents name optional deferred MCP tools in their frontmatter
-(serena symbol tools; critic also `sequential_thinking` and context7).
+All agents name optional deferred MCP tools in their frontmatter
+(serena symbol tools; critic and marathon 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
@@ -55,6 +63,9 @@ below hold.
 - **executor** ends every answer with `Changed` / `Checked` /
   `Deviations` / `Blockers` — a Blocker means STOP and re-plan; never let it
   improvise.
+- **marathon** ends every answer with `Verdict` / `What changed` /
+  `Evidence trail` / `Dead ends` / `Open threads` — treat an unverified
+  claim as open, and never re-walk a listed dead end.
 
 ## Advisory safety