@menghuan1918/dsh-apollo 0.3.0 → 0.4.0

package/presets/eng/plugins/mode-instructions/index.js

@@ -1,48 +1,124 @@
 /**
- * `eng-mode-instructions` — preset-scoped prompt section for the eng preset
- * (工程模式). Carries the two eng-only behaviors no other surface states:
- *  - the exit guard contract;
- *  - the delegation/orchestration policy (when to delegate, write scopes,
- *    verification, failure handling), moved out of the user-global
- *    ~/.dsh/AGENTS.md on 2026-09-11.
- * Model tiers stay in ~/.dsh/AGENTS.md: they mirror this host's
- * `subagent-model-selection.allowedModels` route list, which is local config.
- * Everything else — tool mechanics, background-job etiquette, sleep caps —
- * lives in the harness system prompt or the tool descriptions, and is
- * deliberately NOT repeated here. Dedupe first, inject only the delta.
+ * `eng-mode-instructions` — preset-scoped prompt section for 工程模式
+ * (`eng`) and 工程(PTC)模式 (`eng-ptc`).
  *
- * Zero imports on purpose (same constraint as the sibling wait-subagent
- * plugin): this module loads from the preset directory, where Node's upward
- * node_modules walk never reaches the harness install.
+ * Carries what no other surface states: the general engineering discipline
+ * (moved out of the user-global ~/.dsh/AGENTS.md, which keeps only
+ * machine-local conventions), the delegation policy, the subagent model tiers
+ * rendered from Apollo settings (`tiers.*`), and the exit guard contract while
+ * that switch is on. Tool mechanics, background-job etiquette and run_code
+ * syntax live in the harness prompt and tool descriptions and are NOT
+ * repeated here.
+ *
+ * The text is a function re-rendered per request from the live Apollo config,
+ * so settings edits apply without remounting; an edit costs the prefix cache
+ * once, which is acceptable for rarely changed settings. The row config
+ * `ptc: true` (set by eng-ptc) adds a rule for fanning out subagents inside
+ * one run_code program (workflow usage is left to the harness tool guidance); run_code mechanics themselves
+ * come from the harness `tools:sdk` / `tools:ptc-only` sections.
  */
 
+import z from '@deepseek-ai/schemastery'
+import { currentConfig } from '../../../../src/config.js'
+
 export const name = 'eng-mode-instructions'
 
 export const inject = ['systemPrompt']
 
-const TEXT = [
-  '# 工程模式专属',
-  '',
-  '工程模式（eng）面向编码与基础设施任务。',
-  '',
-  '- 退出守卫：回合结束前仍有运行中的子代理或后台命令时，回合不会关闭——系统注入运行清单提醒，先用 wait_subagent / job_output 等待收取、job_kill 停掉不需要的，处理完毕再收尾。',
-  '',
-  '## 委派与编排',
-  '',
-  '- 开局侦察：非琐碎任务在陌生或大型代码库上开始时，情况了解（仓库结构、相关模块定位、约定与测试入口）默认立即并行派发快速档侦察子代理，同批在一条消息里一起派；主线程只保留定义任务必需的指令类文件阅读（AGENTS.md、PRD、任务说明）。不要为「写好委派 prompt」而先单线程探索——侦察 prompt 只需目标、边界、交付物，缺的上下文正是侦察要产出的东西。',
-  '- 默认委派：只读、可并行、无状态的调查一律派出去（含大型/陌生仓库、前端代码、批量排查），同一批独立任务在一条消息里一起派，不在主线程先试一遍。',
-  '- 转委派阈值：实现/调试中途冒出的新未知，主线程深挖 1–2 轮未收敛立即派出去；开局侦察不适用此阈值。',
-  '- 实现分层：写入范围互不重叠的独立实现块派子代理并行推进；线性推进、强耦合改动、需要持续控制活状态的调试（活进程、串行打补丁）留主线程。',
-  '- 扇出用 workflow：同一形状的工作重复多份（审计、迁移、多角度验证、批量修复）即属大型多代理编排，直接写 workflow 脚本一次编排；一两次委派仍用 subagent。',
-  '- 派发写明目标、写入范围、交付物与验证方式；引用的前置产出给实际文件路径——子代理看不到父对话。',
-  '- 并行实现子代理的写入范围不得重叠；最终集成、审查、验证由主代理负责；子代理报告是线索不是证据，亲自核对实际变更状态。',
-  '- 子代理以 error / 空返回收场：先读失败原因，修正路由或重派一次；仍失败且无外部阻塞才主线程接管，并在当轮说明为何接管。',
-].join('\n')
-
-export function apply(ctx) {
+export const Config = z.object({
+  /** Render the PTC variant (eng-ptc). */
+  ptc: z.boolean().default(false),
+})
+
+const PRINCIPLES = `# Engineering mode
+
+For coding and infrastructure work. These are defaults; explicit user instructions take precedence.
+
+## Principles
+- KISS / YAGNI: use the simplest approach that works. Do not add abstractions, indirection, or options the task does not need.
+- Inspect first: read the actual files, run the actual commands, check the actual state, then judge. When evidence and judgment disagree, evidence wins. Look up unfamiliar library/API behavior instead of relying on memory.
+- Fix the root cause: trace a bad value back to the violated assumption; no workarounds that only hide the symptom.
+- One coherent change at a time, each with an observable result and a pass/fail check; do not bundle unrelated edits.
+- Follow existing conventions: match surrounding naming, style, error handling, and patterns; use the project's own build/test/lint commands; read the repo's coding-standards files (if any) before writing code.
+- Think about requirements, approach, and verification; do not draft whole implementations in your reasoning. If your reasoning starts repeating, stop, change angle, or go gather evidence.
+
+## Avoid over-engineering and over-defending
+- Do not add complexity for speculative needs or vanishingly unlikely race/security edge cases. If one seems necessary, first explain the concrete failure mode, its likelihood, and the complexity cost to the user and get agreement; never silently expand scope for theoretical robustness.
+- Validate unknown input once, at the boundary that owns it, and pass settled values inward; do not re-check what a schema, constructor, or type already guarantees.
+- Put try/catch only where the error can actually be handled; never use it to swallow errors or hide failures.
+- Do not extract single-use helpers unless they name a real concept or isolate a genuinely complex boundary.
+- Comment non-obvious constraints and surprising behavior, not what the code already says.
+- Test the real implementation; minimize mocks; do not copy implementation logic into tests.
+
+## Verification and reporting
+- Claim success only with fresh evidence from the changed state. Passing lint does not prove runtime behavior; unit tests do not prove deployment integration.
+- In reports, separate verified, executed-but-unverified, and not executed. Never fake progress.
+
+## Boundaries
+- Changing shared branches such as main or dev needs explicit authorization. Within the task, commits and merges on isolated branches are fine; create worktrees for isolation when useful.
+- Preserve unrelated changes and keep the main worktree clean; recurring local files can go in .git/info/exclude.
+- Commit with the configured global Git identity, never placeholder identities such as bot or agent.
+- Tell the user when you install system packages or download dependencies outside the package manager; ask where to install missing unmanaged dependencies; prefer prebuilt packages over compiling.
+- No filesystem-wide or whole-home-directory searches without asking first.
+- Deviating from these rules needs the user's consent. Before asking, explore the code, tests, and prior decisions yourself; ask only questions whose answers change what you do, each with a recommended answer and why.
+
+## Commands and processes
+- One background job per goal: check job_list first; do not run near-duplicate commands in parallel.
+- Work on data where it already is (including remote mounts) instead of downloading or copying large files.
+- Before killing a process, confirm its full command line and PID with \`pgrep -af <keyword>\`, then \`kill <PID>\`; never pkill / killall.
+- Never sleep longer than 60s at once; for longer waits use stepped probes, sentinel files, or completion notices.
+- Run services that must outlive the turn (dev servers, watchers) under pm2/nohup outside the job registry, and say which ones are still running when you finish.`
+
+const DELEGATION_HEAD = `## Delegation
+- Subagents cannot see this conversation: state the goal, write scope, deliverable, and verification, and give real file paths for prior outputs.
+- Opening reconnaissance: when starting non-trivial work in an unfamiliar or large codebase, immediately dispatch fast-tier scouts in parallel (structure, relevant modules, conventions, test entry points), all in one message; the main agent reads only the instruction files that define the task. A scout prompt needs only goal, boundaries, and deliverable.
+- Delegate read-only, parallelizable, stateless investigation by default instead of trying it in the main thread first; when a new unknown appears mid-task and 1–2 rounds of digging do not converge, delegate it.
+- Implementation chunks with non-overlapping write scopes can run in parallel; keep linear work, tightly coupled changes, and debugging that needs live state in the main thread.`
+
+const FANOUT_PTC = '- For repeated same-shaped work, dispatch all subagents inside one run_code program, then collect them with wait_subagent.'
+
+const DELEGATION_TAIL = `- When you need a subagent's result, wait patiently with wait_subagent. Do not poll or prod it with send_message; send a message only to give it genuinely new information or a correction.
+- The main agent owns integration, review, and final verification. Subagent reports are leads, not evidence: check the actual changes yourself.
+- When a subagent ends in an error or empty result, read why, fix the cause, and re-dispatch once; take over in the main thread only if it fails again without an external blocker, and say why.`
+
+const EXIT_GUARD = `## Exit guard
+- If subagents or background commands are still running when the turn would end, the system injects a reminder and the turn continues. Collect them with wait_subagent / job_output, stop unneeded ones with job_kill, then finish.`
+
+/** One tier as model-facing argument text; an unset tier inherits the parent route. */
+export function renderTier(tier) {
+  if (!tier?.provider || !tier?.model) return 'omit provider / model / reasoning_effort to inherit the parent route'
+  const parts = [`provider: \`${tier.provider}\``, `model: \`${tier.model}\``]
+  if (tier.reasoningEffort) parts.push(`reasoning_effort: \`${tier.reasoningEffort}\``)
+  return parts.join(' · ')
+}
+
+/**
+ * Render the full section text.
+ * @param config - normalized Apollo config (`exitGuard`, `tiers`).
+ * @param options - `{ ptc }` from this row's config.
+ * @returns the section markdown.
+ */
+export function renderInstructions(config, options = {}) {
+  const tiers = `## Subagent model tiers
+- Fast tier (exploration, reconnaissance, mechanical analysis, batch triage): ${renderTier(config.tiers?.fast)}
+- Quality tier (complex implementation, debugging, review, design): ${renderTier(config.tiers?.quality)}
+- Start exploration on the fast tier; when coverage falls short or key questions remain, re-dispatch the unresolved part on the quality tier. Escalating means re-dispatching, not modifying an existing subagent.
+- subagent_fork takes no model choice: it keeps the parent route to reuse the prefix cache.`
+  const blocks = [
+    PRINCIPLES,
+    [DELEGATION_HEAD, ...(options.ptc ? [FANOUT_PTC] : []), DELEGATION_TAIL].join('\n'),
+    tiers,
+  ]
+  if (config.exitGuard) blocks.push(EXIT_GUARD)
+  return blocks.join('\n\n')
+}
+
+export function apply(ctx, config) {
+  const options = { ptc: config?.ptc === true }
   ctx.effect(() => ctx.systemPrompt.section({
     name: 'eng:mode-instructions',
     order: 1,
-    text: TEXT,
+    interpolate: false,
+    text: () => renderInstructions(currentConfig(ctx), options),
   }), 'eng-mode-instructions.section()')
 }

package/presets/eng/plugins/wait-subagent/index.js

@@ -25,6 +25,8 @@
  *
  * `timeout_ms` is ONE shared window over the whole batch (all timers start at
  * the same instant), matching the semantics same-message parallel calls had.
+ * Values below MIN_TIMEOUT_MS (15 minutes) are raised to it: short polling
+ * waits only burned turns, since a finishing child notifies the parent anyway.
  * An id that is not a direct child fails the whole call fast — nobody is
  * waited for — keeping the contract the single-id version had. A child
  * dispatched moments ago may not have started its first turn yet: its status
@@ -48,6 +50,9 @@ export const inject = ['tools', 'subagents', 'agents']
 /** Grace window for a just-dispatched child that has not started running yet. */
 const START_GRACE_MS = 30_000
 
+/** Floor for a caller-supplied timeout_ms (15 minutes). */
+const MIN_TIMEOUT_MS = 15 * 60_000
+
 /** Status polling interval while waiting for a not-yet-started child. */
 const POLL_MS = 250
 
@@ -70,7 +75,7 @@ export function apply(ctx) {
 
   ctx.tools.register({
     name: 'wait_subagent',
-    description: 'Wait for one or more background continuable subagents (spawned by subagent or subagent_fork) to finish their current turn. Pass their durable ids as an array in subagent_id — all are awaited concurrently and the result carries one short line per id (done + stop reason); a child\'s closing message arrives as the framework settlement notice immediately after this result; do not expect it here. Blocks until every listed child settles, the optional timeout_ms elapses (one shared window over all ids), or the user interrupts — without timeout_ms, until completion. A just-dispatched child that has not started yet is awaited through a brief startup grace rather than reported as not running. Use it when your next step depends on those results; with independent work remaining, prefer background plus completion notices. Do not pass bash job ids — those use job_output.',
+    description: 'Wait for direct subagents (from subagent or subagent_fork) to finish their current turn. Pass every id in subagent_id; all are awaited together and each gets one done line, while its closing message arrives as the settlement notice right after. Use it when your next step needs the results, instead of messaging the child to check on it. Not for bash jobs (use job_output).',
     parameters: {
       type: 'object',
       properties: {
@@ -78,11 +83,11 @@ export function apply(ctx) {
           type: 'array',
           items: { type: 'string' },
           minItems: 1,
-          description: 'One or more durable subagent ids returned by the subagent or subagent_fork tool call; every id is awaited concurrently.',
+          description: 'Durable ids returned by subagent or subagent_fork.',
         },
         timeout_ms: {
           type: 'integer',
-          description: 'Optional maximum wait in milliseconds applied as one shared window over all ids; omit to wait until every child settles. On expiry the tool returns while some children are still running.',
+          description: 'Optional shared wait window in ms; values below 900000 (15 minutes) are raised to 900000. Omit to wait until every child settles.',
         },
       },
       required: ['subagent_id'],
@@ -123,7 +128,7 @@ export function apply(ctx) {
       const doneLine = (id, info) => `subagent ${id} done (${info && info.stopReason ? info.stopReason : 'completed'}); its closing message follows as the settlement notice.`
 
       const startedAt = Date.now()
-      const capMs = typeof args.timeout_ms === 'number' && args.timeout_ms > 0 ? args.timeout_ms : undefined
+      const capMs = typeof args.timeout_ms === 'number' && args.timeout_ms > 0 ? Math.max(args.timeout_ms, MIN_TIMEOUT_MS) : undefined
 
       /**
        * Wait for one child. Resolves with {kind:'settled',info} |

package/presets/eng-ptc.patch.yml

@@ -0,0 +1,186 @@
+# dsh-apollo bundle patch: the `eng-ptc` (工程(PTC)模式) agent preset.
+#
+# A copy of the eng plugins block (presets/eng.patch.yml — read that file for
+# the per-row rationale) with exactly the deltas the upstream `ptc` preset
+# applies to `standard`:
+#   - `tool-presentation { mode: ptc }`: every tool is reached through the
+#     run_code TypeScript SDK (needs the host `ptc-runtime` row);
+#   - `workflow-ptc` and `tool-workflow` disabled: PTC fans out by calling
+#     subagent several times inside one run_code program instead;
+# plus `eng-mode-instructions { ptc: true }`, which adds the rule for fanning
+# out subagents inside one run_code program. Preset-local plugins reuse the eng modules.
+# tests/upstream-drift.test.mjs checks this file against both eng and the
+# upstream `ptc` preset; edit eng first, then redo these deltas.
+#
+# `config.id` MUST stay `eng-ptc`: it is the preset identity historical
+# sessions resume by.
+
+- insert:
+    - id: preset-eng-ptc
+      name: '@deepseek-ai/dsh-agent-preset'
+      config:
+        id: eng-ptc
+        name: 工程(PTC)模式
+        description: >-
+          工程模式的 PTC 变体：工具经 run_code 的 TypeScript SDK 调用，一个程序组合多步操作；与官方 PTC 模式一致不提供 workflow 工具。
+        order: 11
+        plugins:
+
+          - id: persona
+            name: '@deepseek-ai/dsh-persona'
+            config:
+              prefix: >-
+                You are a coding agent powered by the {{model}} model.
+
+          - id: agent-instructions
+            name: '@deepseek-ai/dsh-agent-instructions'
+            config:
+              maxBytes: 65536
+
+          - id: time-context
+            name: '@deepseek-ai/dsh-time-context'
+
+          - id: tool-bash
+            name: '@deepseek-ai/dsh-tool-bash'
+            disabled: !!js process.platform === 'win32'
+
+          - id: tool-pwsh
+            name: '@deepseek-ai/dsh-tool-pwsh'
+            disabled: !!js process.platform !== 'win32'
+
+          - id: tool-fs
+            name: '@deepseek-ai/dsh-tool-fs'
+
+          - id: tool-fs-search
+            name: '@deepseek-ai/dsh-tool-fs-search'
+            config:
+              sampleOverCapGlobResults: false
+
+          - id: tool-jobs
+            name: '@deepseek-ai/dsh-tool-jobs'
+            config:
+              maxConsecutiveWakes: 5000
+
+          - id: skill-filesystem
+            name: '@deepseek-ai/dsh-skill-filesystem'
+
+          - id: tool-skill
+            name: '@deepseek-ai/dsh-tool-skill'
+
+          - id: planning
+            name: cordis:group
+            group: true
+            isolate:
+              planMode: true
+            config:
+              - id: plan-mode
+                name: '@deepseek-ai/dsh-plan-mode'
+                config:
+                  section: |
+                        You are in plan mode. Stay in plan mode until the user approves your plan through exit_plan_mode or switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
+
+                        Explore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.
+
+                        The tool catalog stays the same across modes for request-cache stability. These plan-mode rules override any later tool description or guidance that suggests using mutation tools; those tools remain listed to keep the tool catalog unchanged. Do not use todo_write to track this planning phase: it tracks implementation after an approved plan, while the plan itself belongs in exit_plan_mode.
+
+                        Resolve discoverable facts by inspection. Use ask_user_question only for user-owned choices or material ambiguity that inspection cannot answer. Do not ask the user where code lives or how current behavior works when you can find out.
+
+                        Make the plan decision-complete: state the goal and success criteria; group implementation changes by subsystem; identify public API, schema, and data-flow changes; cover edge cases, failure modes, tests, acceptance criteria, and explicit assumptions. Keep it concise enough to review but detailed enough that another engineer can implement it without making design decisions.
+
+                        When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
+
+          - id: compaction
+            name: cordis:group
+            group: true
+            isolate:
+              compaction: true
+              toolResultPruner: true
+            config:
+              - id: compaction-basic
+                name: '@deepseek-ai/dsh-compaction-basic'
+
+              - id: command-compact
+                name: '@deepseek-ai/dsh-command-compact'
+
+              - id: tool-result-pruner
+                name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+                config:
+                  thresholdChars: 16384
+                  headChars: 8192
+                  tailChars: 2048
+
+          - id: delegation
+            name: cordis:group
+            group: true
+            isolate:
+              workflowEngine: true
+            config:
+              - id: tool-subagent-control
+                name: '@deepseek-ai/dsh-tool-subagent-control'
+
+              - id: tool-subagent-list-agents
+                name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+
+              - id: tool-subagent
+                name: '@deepseek-ai/dsh-tool-subagent'
+                config:
+                  provider: spawn
+                  toolName: subagent
+                  modelSelectionSettings: true
+
+              - id: tool-subagent-fork
+                name: '@deepseek-ai/dsh-tool-subagent'
+                config:
+                  provider: fork
+                  toolName: subagent_fork
+
+              - id: workflow-ptc
+                name: '@deepseek-ai/dsh-workflow-ptc'
+                disabled: true
+                config:
+                  provider: spawn
+
+              - id: tool-workflow
+                name: '@deepseek-ai/dsh-tool-workflow'
+                disabled: true
+
+          - id: tool-ask-user
+            name: '@deepseek-ai/dsh-tool-ask-user'
+
+          - id: tool-todo
+            name: '@deepseek-ai/dsh-tool-todo'
+            config:
+              allowParallelInProgress: true
+
+          - id: tool-web
+            name: '@deepseek-ai/dsh-tool-web'
+            config:
+              fetch: true
+              searchTimeoutMs: 60000
+
+          - id: tool-presentation
+            name: '@deepseek-ai/dsh-agent-tool-presentation'
+            config:
+              mode: ptc
+
+          - id: present
+            name: '@deepseek-ai/dsh-tool-present'
+
+          - id: tool-plugin-manager
+            name: '@deepseek-ai/dsh-plugin-manager/tools'
+            disabled: true
+
+          - id: tool-plugin-market
+            name: '@deepseek-ai/dsh-plugin-market/tools'
+            disabled: true
+
+          - id: tool-wait-subagent
+            name: '@menghuan1918/dsh-apollo/presets/eng/plugins/wait-subagent/index.js'
+
+          - id: eng-exit-guard
+            name: '@menghuan1918/dsh-apollo/presets/eng/plugins/exit-guard/index.js'
+
+          - id: eng-mode-instructions
+            name: '@menghuan1918/dsh-apollo/presets/eng/plugins/mode-instructions/index.js'
+            config:
+              ptc: true

package/presets/eng.patch.yml

@@ -46,10 +46,9 @@
           # ── identity ────────────────────────────────────────────────────────────────
 
           # The preset's own persona, shadowing the deployment default for this agent.
-          # One row on purpose: the rich engineering rules live in the user-global
-          # instructions (~/.dsh/AGENTS.md) and the preset's `eng:mode-instructions`
-          # section, not in the persona. `eng:mode-instructions` owns the delegation
-          # policy; the tiers stay global because they track local route config.
+          # One row on purpose: the engineering rules, delegation policy and model
+          # tiers live in the preset's `eng:mode-instructions` section, not in the
+          # persona; ~/.dsh/AGENTS.md only keeps machine-local conventions.
           # 0.2.1's upstream `standard` preset carries `prefix` only: the working-
           # directory `suffix` line it used to set is gone, and eng follows suit.
           - id: persona
@@ -116,9 +115,9 @@
           # idle owner and is restored ONLY by a user-authored message, so a long
           # unattended chain of background jobs parks after its third wake — from the
           # fourth completion on, the notice degrades to injection and waits for the
-          # user's next input. Keep this value identical in the eng-noask patch (the
-          # upstream-drift test compares same-id row configs); upstream `standard`
-          # ships no such key, and the drift test whitelists exactly this delta.
+          # user's next input. Keep this value identical in the eng-ptc patch (the
+          # upstream-drift test compares both presets against upstream with the
+          # same whitelist); upstream ships no such key.
           - id: tool-jobs
             name: '@deepseek-ai/dsh-tool-jobs'
             config:
@@ -327,15 +326,13 @@
 
           # ── mode instructions ────────────────────────────────────────────────────────
 
-          # Preset-local prompt section carrying the two eng-only rules: the exit guard
-          # contract and the delegation/orchestration policy (the latter moved out of the
-          # user-global ~/.dsh/AGENTS.md on 2026-09-11 — the model tiers stay there
-          # because they mirror this host's `subagent-model-selection` route list).
-          # Registered as a system-prompt section (order 1, right after the persona slot)
-          # so it is scoped to sessions mounted on this preset and nothing else; injected
-          # from the first request alongside the other sections.
-          # This plugins block (presets/eng.patch.yml) is the single source of truth;
-          # the 0.2.1 bundle-patch mechanism loads it straight from this file, with no
-          # boot-time copy in between.
+          # Preset-local prompt section carrying the engineering discipline (moved out
+          # of the user-global ~/.dsh/AGENTS.md), the delegation policy, the model
+          # tiers rendered from Apollo settings (`tiers.*`), and the exit guard
+          # contract when that switch is on. Registered as a system-prompt section
+          # (order 1, right after the persona slot) so it is scoped to sessions
+          # mounted on this preset; its text is re-rendered per request from the live
+          # Apollo config. `ptc: true` (set by eng-ptc) adds the rule for fanning
+          # out subagents inside one run_code program.
           - id: eng-mode-instructions
             name: '@menghuan1918/dsh-apollo/presets/eng/plugins/mode-instructions/index.js'

package/skills/brainstorming/SKILL.md

@@ -1,90 +1,90 @@
 ---
 name: brainstorming
-description: "把大型需求设计为多个协同 Spec。仅当用户显式调用 /brainstorming，或要求把大型任务拆分为可执行 Spec 时使用。"
+description: "Design large requirements as multiple cooperating Specs. Use only when the user explicitly invokes /brainstorming, or asks to split a large task into executable Specs."
 ---
 
-# 大型任务头脑风暴
+# Brainstorming Large Tasks
 
-把大型需求整理为一个获批的主 Spec 和至少两个可执行子 Spec。保持 KISS：只沿真实的职责、依赖或验证边界拆分。
+Turn a large requirement into one approved master Spec and at least two executable sub-Specs. Stay KISS: split only along real responsibility, dependency, or verification boundaries.
 
-**终态是交接给 `/exec`。** 不得实现功能、创建 worktree 或调用开发技能。用户批准书面 Spec 后停止。
+**The end state is a handoff to `/exec`.** Do not implement features, create worktrees, or invoke development skills. Stop once the user approves the written Specs.
 
-## 流程
+## Process
 
-1. **探索项目上下文** — 检查文件、文档和当前项目状态。事实自己查，不问用户。
-2. **逐一提问** — 每条消息只问一个决策问题，系统遍历设计树，每个问题以推荐答案开头。区分事实（自行查明）与决策（用户定夺）。详见下文提问规则。
-3. **给出 2-3 个方案** — 含权衡和推荐，以推荐方案开头。
-4. **分段展示设计** — 按复杂度决定每段长度，每段取得用户确认。需拆分时展示拆分方案（主 Spec + 子 Spec、依赖顺序、共享契约、集成验收）。
-5. **写入全部 Spec** — 写盘后自审（占位符、矛盾、歧义、过度细节），内联修复。详见下文自审。
-6. **派 spec-reviewer 审查** — 按 [`spec-document-reviewer-prompt.md`](spec-document-reviewer-prompt.md) 派一个全新只读 `subagent`（质量档 = 本会话最强模型）审查主 Spec 与全部子 Spec；修复阻塞项，必要时复派。
-7. **请用户审阅** — 按反馈修改直至批准。
-8. **交接给 `/exec`** — 告知用户用主 Spec 路径调用 `/exec`。
+1. **Explore project context** — inspect files, docs, and current project state. Look up facts yourself; do not ask the user.
+2. **Ask one question at a time** — one decision question per message, walking the design tree systematically, each question led by a recommended answer. Separate facts (look up yourself) from decisions (the user's call). See the question rules below.
+3. **Offer 2-3 options** — with tradeoffs and a recommendation, leading with the recommended option.
+4. **Present the design in sections** — scale each section's length to its complexity, and get the user's confirmation on each. When a split is needed, present it (master Spec + sub-Specs, dependency order, shared contracts, integration acceptance).
+5. **Write all Specs** — self-review after writing (placeholders, contradictions, ambiguity, over-detail) and fix inline. See self-review below.
+6. **Dispatch a spec-reviewer** — per [`spec-document-reviewer-prompt.md`](spec-document-reviewer-prompt.md), dispatch a fresh read-only `subagent` (quality tier) to review the master Spec and all sub-Specs; fix blockers and re-dispatch if needed.
+7. **Ask the user to review** — revise per feedback until approved.
+8. **Hand off to `/exec`** — tell the user to invoke `/exec` with the master Spec path.
 
-完成标准：主 Spec + 全部子 Spec 已写入磁盘，用户已批准，已给出 `/exec` 调用方式。
+Done when: the master Spec and all sub-Specs are on disk, the user has approved them, and the `/exec` invocation has been given.
 
-## 提问规则
+## Question rules
 
-- **每条消息只问一个问题。** 等用户反馈再继续。一次问多个会导致混乱。
-- **给出推荐答案。** 附推理，用户可接受、拒绝或修改。
-- **事实 vs 决策。** 事实查代码库或文档获得，不问用户；决策展示给用户等待回答。
-- **优先多选题**，开放式问题也可以。
-- **聚焦理解：** 目标、约束、成功标准、架构、错误处理、测试。
+- **One question per message.** Wait for the answer before continuing. Asking several at once causes confusion.
+- **Lead with a recommended answer.** Include the reasoning; the user can accept, reject, or amend it.
+- **Facts vs decisions.** Get facts from the codebase or docs; never ask the user. Present decisions to the user and wait for an answer.
+- **Prefer multiple choice**, though open-ended questions are fine too.
+- **Focus on understanding:** goals, constraints, success criteria, architecture, error handling, testing.
 
-共识达成前不写 Spec。后续答案改变前提时，回头修正既有决定。
+Do not write Specs before consensus. When a later answer changes a premise, go back and fix earlier decisions.
 
-## 设计粒度
+## Design granularity
 
-子 Spec 定义**做什么和为什么**，以及独立实现和验证所需的边界。不是实现食谱。（主 Spec 不在此列——它只是目标 + 索引，见拆分准则。）
+A sub-Spec defines **what and why**, plus the boundaries needed to implement and verify it independently. It is not an implementation recipe. (The master Spec is exempt — it is just goal + index; see the split guidance.)
 
-- 包含目标、范围、关键决策、组件职责、交互、外部可观察行为、错误语义、验收标准、测试范围。
-- 把局部编码选择留给实现。不含代码、伪代码、私有类型设计、逐文件修改清单、分步指令。
-- 精确的公共契约（API 路由、共享 schema、配置键）仅在兼容性或迁移依赖时写入。
+- Include goals, scope, key decisions, component responsibilities, interactions, externally observable behavior, error semantics, acceptance criteria, and test scope.
+- Leave local coding choices to implementation. No code, pseudocode, private type design, per-file change lists, or step-by-step instructions.
+- Write exact public contracts (API routes, shared schemas, config keys) only when compatibility or migration depends on them.
 
-## 拆分准则
+## Split guidance
 
-主 Spec 只承载总目标 + 索引（见下文多 Spec 结构），不承载任何具体执行内容。**鼓励多写子 Spec**——任务有几个独立单元就拆几个，下限两个，但更细的拆分只要每个子 Spec 仍能独立实现、独立验证就值得。每个子 Spec 必须能独立实现、独立测试，适合独立的 Spec → 实现周期。
+The master Spec carries only the overall goal + index (see Multi-Spec structure below), never any concrete execution content. **Lean toward more sub-Specs** — split as many as the task has independent units, with two as the floor; finer splits are worth it as long as each sub-Spec can still be implemented and verified independently. Every sub-Spec must be independently implementable and testable, suited to its own Spec → implementation cycle.
 
-**拆分有价值时：** 任务确实复杂，有多个独立子系统或可并行轨道；每个子 Spec 接口清晰；拆分提升清晰度而非仅为并行。
+**Splitting pays off when:** the task is genuinely complex, with multiple independent subsystems or parallel tracks; each sub-Spec has a clear interface; and the split improves clarity rather than just enabling parallelism.
 
-**过度拆分信号：** 子 Spec 间循环依赖；无法独立验证；共享契约多处不一致；拆出无独立职责的子 Spec。
+**Signals of over-splitting:** circular dependencies between sub-Specs; nothing can be verified independently; shared contracts diverge in several places; sub-Specs carved out with no independent responsibility.
 
-质量优先于并行——为清晰而拆分，不仅为了并行执行。
+Quality over parallelism — split for clarity, not just for parallel execution.
 
-## 多 Spec 结构
+## Multi-Spec structure
 
-### 主 Spec
+### Master Spec
 
-**只做总目标 + 索引，不承载执行。** 内容限于：总目标、范围与非目标、子 Spec 索引（每个子 Spec 一行：职责 + 路径）、依赖 DAG 与并行分组、整体验收的指向。关键决策、共享契约、组件职责、交互、错误语义等具体内容一律下沉到子 Spec；主 Spec 只指明每个契约由哪个子 Spec 定义/拥有。不得在主 Spec 里实现任何东西。
+**Only the overall goal + index, no execution content.** Confined to: overall goal, scope and non-goals, sub-Spec index (one line per sub-Spec: responsibility + path), dependency DAG and parallel groups, and a pointer to overall acceptance. Push all concrete content — key decisions, shared contracts, component responsibilities, interactions, error semantics — down to the sub-Specs; the master Spec only names which sub-Spec defines/owns each contract. Never implement anything in the master Spec.
 
-### 子 Spec
+### Sub-Spec
 
-独立实现、审查、测试和提交所需：边界明确的目标、范围内/外行为、依赖、输入输出和共享契约、错误语义、验收标准、聚焦验证范围、指向主 Spec 的链接。不复制主 Spec，只带入执行所需契约。
+What independent implementation, review, testing, and commit need: a boundary-clear goal, in-scope/out-of-scope behavior, dependencies, inputs/outputs and shared contracts, error semantics, acceptance criteria, a focused verification scope, and a link back to the master Spec. Do not copy the master Spec; carry over only the contracts execution needs.
 
-## 文件布局
+## File layout
 
-落盘位置按工作区实际情况择一，不要两处都写：
+Pick one landing location based on the actual workspace; do not write to both:
 
 ```text
-<工作区>/.workspace-docs/specs/MM-DD-<主题>-主设计/   # 工作区有 .workspace-docs/ 时用它
-<目标仓库>/docs/specs/MM-DD-<主题>-主设计/             # 否则用目标仓库自己的 specs 目录
-├── MM-DD-<主题>-主设计.md
-├── MM-DD-<主题>-<子任务A>-设计.md
-└── MM-DD-<主题>-<子任务B>-设计.md
+<workspace>/.workspace-docs/specs/MM-DD-<topic>-master-design/    # when the workspace has .workspace-docs/
+<target-repo>/docs/specs/MM-DD-<topic>-master-design/             # otherwise the target repo's own specs directory
+├── MM-DD-<topic>-master-design.md
+├── MM-DD-<topic>-<subtask-A>-design.md
+└── MM-DD-<topic>-<subtask-B>-design.md
 ```
 
-- 主 Spec 与子 Spec 双向链接。
-- 目录内已有其它 Spec 时，沿用其文件名与头格式，不引入第二套约定。
-- 写入 `.workspace-docs/` 时每篇带 OKF 头部（`type: Design Spec`、`title`、`description`、`tags`、`status`、`repos`）；提交推送遵循该仓库自己的 `AGENTS.md`。目标仓库无此约定时用仓库现有文档格式，不新造 OKF。
+- Link master Spec and sub-Specs to each other in both directions.
+- When the directory already holds other Specs, follow their file naming and header format; do not introduce a second convention.
+- When writing under `.workspace-docs/`, give every file an OKF header (`type: Design Spec`, `title`, `description`, `tags`, `status`, `repos`); committing and pushing follow that repo's own `AGENTS.md`. Where the target repo has no such convention, use its existing doc format and do not invent OKF.
 
-## 自审
+## Self-review
 
-写入后用新鲜眼光检查：占位符（`TODO`/`TBD`）、内部一致性、范围聚焦、歧义、过度细节。内联修复全部问题。这是自己先过一遍；随后派 spec-reviewer 子代理做独立审查（流程第 6 步）。
+After writing, check with fresh eyes: placeholders (`TODO`/`TBD`), internal consistency, scope focus, ambiguity, over-detail. Fix everything inline. This is your own first pass; a spec-reviewer subagent then does the independent review (process step 6).
 
-## 可视化辅助
+## Visual aids
 
-当展示优于讲述（mockup、布局、架构图、方案对比）时，写一个自包含 HTML 到系统临时目录（`$TMPDIR`，未设置时 `/tmp`），文件名 `brainstorm-<主题>-<序号>.html`：
+When showing beats telling (mockups, layouts, architecture diagrams, option comparisons), write a self-contained HTML file to the system temp directory (`$TMPDIR`, or `/tmp` when unset), named `brainstorm-<topic>-<n>.html`:
 
-- 用 write 工具写完整文档：内联 CSS、无外部依赖、无脚本、无服务；每页 2-4 个选项或变体。
-- 文件名不复用；迭代就写新文件（`-2`、`-3`）。
-- 告知用户文件路径（DSH 界面可直接打开预览），并用一两句话概括页面内容；用户看后回到对话作答，不采集点击。
-- 每个问题独立判断是否需要可视化；概念性选择（A/B/C 方案、取舍清单）留在对话里。
+- Write the complete document with the write tool: inline CSS, no external dependencies, no scripts, no server; 2-4 options or variants per page.
+- Never reuse a file name; for iterations write a new file (`-2`, `-3`).
+- Tell the user the file path (the DSH UI can open it for preview directly) and summarize the page in one or two sentences; the user looks, then answers back in the conversation — clicks are not collected.
+- Decide per question whether a visual helps; keep conceptual choices (A/B/C options, tradeoff lists) in the conversation.