@menghuan1918/dsh-apollo 0.0.0-stage → 0.4.0

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

@@ -0,0 +1,338 @@
+# dsh-apollo bundle patch: the `eng` (工程模式) agent preset, declared as
+# one `@deepseek-ai/dsh-agent-preset` insert row — the DSH 0.2.1 preset
+# mechanism (the `<dshHome>/.agent-presets` scan root is gone; third-party
+# presets ship as bundle-patch insert rows). Loaded after ./cordis.patch.yml
+# per the `dsh.bundle.patch` array in package.json.
+#
+# The `config.plugins` block below is the single source of truth for the
+# preset's row list; it supersedes the former presets/eng/agent.cordis.yml +
+# preset.yml pair (metadata folded into `config`). `config.id` MUST stay
+# `eng`: it is the preset identity historical sessions resume by.
+#
+# Preset-local plugin modules are referenced by bare package subpaths
+# (`@menghuan1918/dsh-apollo/presets/eng/plugins/...`): names inside `config.plugins`
+# resolve from the profile directory's node_modules (where this package is
+# installed or linked; `exports["./presets/*"]` maps the subpath), not from
+# the preset directory.
+
+- insert:
+    - id: preset-eng
+      name: '@deepseek-ai/dsh-agent-preset'
+      config:
+        id: eng
+        name: 工程模式
+        description: >-
+          面向编码与基础设施任务的工程 Agent：内置工程纪律、后台任务与子代理约定、由独立 goal 插件提供的长期目标续跑。
+        order: 10
+        plugins:
+          #
+          # This plugins block is an AGENT-PLANE composition. The roster mounts it ONCE under a
+          # standing scope; every session naming it joins by scope parentage, so the
+          # tools and prompt sections registered here cover each joined agent while a
+          # session's own state stays keyed per Session/Agent inside the plugins. The
+          # host composition (`base.cordis.yml` + `web.cordis.yml`) keeps everything a
+          # preset must not own: the registries themselves, the sandbox and approval
+          # stack, persistence, and the model route.
+          #
+          # A service row here MUST sit inside a group carrying an `isolate` realm.
+          # Without one it publishes into the root realm, where it is process-global —
+          # another preset publishing the same name collides, and a host reader would
+          # resolve one preset's instance for every session; `dsh-agent-preset` rejects
+          # that at mount. `true` means an entry-local realm: this standing mount's own
+          # private instance, apart from every other preset's. (A shared label does NOT
+          # pool instances — `provide()` throws on the second registration under the
+          # same realm symbol; labels join REALMS, and are not what this file needs.)
+
+          # ── identity ────────────────────────────────────────────────────────────────
+
+          # The preset's own persona, shadowing the deployment default for this agent.
+          # 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
+            name: '@deepseek-ai/dsh-persona'
+            config:
+              prefix: >-
+                You are a coding agent powered by the {{model}} model.
+
+          # Workspace instructions (repository AGENTS.md files) are injected from the
+          # first request, capped at 64 KiB.
+          - id: agent-instructions
+            name: '@deepseek-ai/dsh-agent-instructions'
+            config:
+              maxBytes: 65536
+
+          # 0.2.1 standard adds the per-step time context (sampled current time,
+          # browser time zone and elapsed time) so date/time reasoning does not depend
+          # on the model's own clock. It consumes host services and provides nothing,
+          # so it needs no realm.
+          - id: time-context
+            name: '@deepseek-ai/dsh-time-context'
+
+          # ── shell ───────────────────────────────────────────────────────────────────
+
+          # `shell-env` stays in the HOST composition: `apps/cli/src/web.ts` injects it to
+          # publish `DSH_WEB_URL`/`DSH_WEB_MODE`, and a host row that injects a service is
+          # the criterion for host-plane ownership — injection resolves before any session
+          # exists, so there is no agent to key by. Behind a preset realm those variables
+          # never reached the model's shell at all. Both shell tools consume the host
+          # registry from here; their executors (`bash-sandbox`/`pwsh-sandbox`) are
+          # host-plane too.
+          - 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'
+
+          # ── filesystem ──────────────────────────────────────────────────────────────
+
+          # Both register into the host `tools` registry and provide nothing, so
+          # they need no realm. The `fs` service and its policy stay in the host.
+          - id: tool-fs
+            name: '@deepseek-ai/dsh-tool-fs'
+
+          - id: tool-fs-search
+            name: '@deepseek-ai/dsh-tool-fs-search'
+            config:
+              sampleOverCapGlobResults: false
+
+          # ── background jobs ────────────────────────────────────────────────────────
+
+          # Only the model-facing controls. The task REGISTRY stays on the host plane:
+          # its producers sit outside any realm this file could put it in — `tool-bash`
+          # above resolves it with `ctx.get`, and an entry-local realm here is invisible
+          # to every sibling row, so `run_in_background` would answer "background jobs
+          # unavailable" while these controls sat in the catalog. The registry is keyed by
+          # owning agent anyway, so one host instance serves every session. What a preset
+          # chooses is whether its agent can collect and stop background work at all.
+          #
+          # LOCAL OVERRIDE (2026-09-22): `maxConsecutiveWakes` is 5000 instead of the
+          # bundled 3. The budget is spent by every completion that opens a turn on an
+          # 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-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:
+              maxConsecutiveWakes: 5000
+
+          # The automation-task tools (schedule_create/list/update/delete) are
+          # deliberately omitted from engineering mode: coding/infrastructure work
+          # does not need scheduled reminders. The host `schedule` service and the
+          # sidebar Automation page stay available to other presets.
+
+          # ── skills ──────────────────────────────────────────────────────────────────
+
+          # The skill REGISTRY lives in the host composition and is layered per scope:
+          # these rows register into THIS preset's layer of it, so they need no realm.
+          # `skill-filesystem` contributes local-root discovery for agents on this preset, and
+          # `tool-skill` gives them the catalog and loader; the merged catalog also
+          # carries whatever the deployment registered globally (repository plugins).
+          - id: skill-filesystem
+            name: '@deepseek-ai/dsh-skill-filesystem'
+
+          - id: tool-skill
+            name: '@deepseek-ai/dsh-tool-skill'
+
+          # ── goals ───────────────────────────────────────────────────────────────────
+
+          # Native command-goal/tool-goal rows are deliberately omitted. The goal
+          # domain is owned by the independent dsh-better-goal plugin row in the
+          # top-level patch: it registers one `goal` tool and one `/goal` command
+          # per Agent, hides any legacy goal tools a preset still carries, and has
+          # its own Plugins row for round limits and question timeouts. The two
+          # removed rows remain deliberate removals in tests/upstream-drift.test.mjs,
+          # which asserts they still exist upstream before filtering them out.
+
+          # ── plan mode ───────────────────────────────────────────────────────────────
+
+          # Plan state is per-agent by nature, so an entry-local realm is not a
+          # workaround here — it is the correct lifetime.
+          - 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.
+
+          # ── compaction ──────────────────────────────────────────────────────────────
+
+          # `compaction-basic` reads `toolResultPrune` through `ctx.get`, so the pruner must
+          # share this realm rather than sit outside it.
+          #
+          # `tokenMeter` is deliberately NOT in this realm: the meter stays on the HOST
+          # plane, and the rows here resolve that one instance. It takes no configuration,
+          # keys every fold by Session, and owns the context-meter projection units the
+          # browser reads for every session — behind a realm those units would come and go
+          # with whichever presets happen to be mounted. What a preset chooses is whether
+          # its agent compacts at all, which is `compaction-basic` below.
+          - 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:
+                  # Deliberately 2x the upstream `standard` preset (8192/4096/1024): eng
+                  # sessions emit large build/test/log tool results, and the extra
+                  # head/tail retention preserves the failure context the agent acts on.
+                  thresholdChars: 16384
+                  headChars: 8192
+                  tailChars: 2048
+
+          # ── delegation and workflows ────────────────────────────────────────────────
+
+          # The `subagents` registry and its spawn/fork backends live in the HOST
+          # composition: the registry is a process singleton whose cross-session queries
+          # the api-proxy serves to the browser, and a provider name may only be
+          # registered once. This preset contributes the delegation TOOLS, which resolve
+          # that host registry.
+          #
+          # `workflows` is different — nothing outside an agent reads it — so every row
+          # that reaches it shares one entry-local realm here, and a consumer left
+          # outside would resolve a host registry this preset does not populate.
+          #
+          # 0.1.2-alpha.4 note: the one-way child `report` tool is gone — parent/child
+          # messaging now rides the globally named `send_message` registered by
+          # `tool-subagent-control` below (children inherit it too), so this preset
+          # mounts no messaging row of its own.
+          - 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
+
+              # Fork omits model selection so provider/model stay equal to the parent and
+              # the inherited history remains eligible for KV Cache reuse.
+              - id: tool-subagent-fork
+                name: '@deepseek-ai/dsh-tool-subagent'
+                config:
+                  provider: fork
+                  toolName: subagent_fork
+
+              # 0.1.6-alpha.2 renamed `dsh-workflow-worker-thread` to `dsh-workflow-ptc`
+              # (workflow orchestration in the shared sandboxed Node PTC runtime).
+              - id: workflow-ptc
+                name: '@deepseek-ai/dsh-workflow-ptc'
+                config:
+                  provider: spawn
+
+              - id: tool-workflow
+                name: '@deepseek-ai/dsh-tool-workflow'
+
+          # ── remaining model-facing rows ─────────────────────────────────────────────
+
+          - id: tool-ask-user
+            name: '@deepseek-ai/dsh-tool-ask-user'
+
+          - id: tool-todo
+            name: '@deepseek-ai/dsh-tool-todo'
+            config:
+              allowParallelInProgress: true
+
+          # The `web` service and its search/fetch providers stay in the host
+          # composition; only the model-facing tool is per-session. `fetch` reads the
+          # host-mounted SSRF-guarded `web-fetch-http` provider.
+          - id: tool-web
+            name: '@deepseek-ai/dsh-tool-web'
+            config:
+              fetch: true
+              searchTimeoutMs: 60000
+
+          # Declares deliverable files to the user (file-card surface). Upstream
+          # `standard` mounts it; eng is a fork-copy of that block, so this row has to be
+          # carried by hand — `tests/upstream-drift.test.mjs` fails when a shipped
+          # preset gains rows that eng never picked up.
+          - id: present
+            name: '@deepseek-ai/dsh-tool-present'
+
+          # 0.2.1 ships both plugin surfaces disabled by default; enable either only in a
+          # copy of this plugins block (edits saved from the Web editor override
+          # config.plugins by row id from the profile patch).
+          - 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
+
+          # ── subagent waiting ─────────────────────────────────────────────────────────
+
+          # Preset-local plugin: explicit wait for one continuable child to settle, so
+          # the agent can block on a specific subagent (pi-style await_task semantics)
+          # without giving up send_message continuations. The module specifier is a
+          # bare subpath of this package (@menghuan1918/dsh-apollo/presets/eng/plugins/...):
+          # config.plugins names resolve from the profile directory's node_modules,
+          # where this package is installed or linked; it has zero bare imports on
+          # purpose.
+          - id: tool-wait-subagent
+            name: '@menghuan1918/dsh-apollo/presets/eng/plugins/wait-subagent/index.js'
+
+          # ── exit guard ───────────────────────────────────────────────────────────────
+          #
+          # Preset-local plugin: pi-atlas 式退出守卫。回合结束（agent/turn-stopping）
+          # 时若有运行中的直接子代理或后台任务，注入 next-step 提醒（agent.steer）
+          # 强制回合继续，直到 wait_subagent / job_output / job_kill 处理完毕或用户
+          # 中断（被中断回合不触发）。开关为正式 Config.exitGuard，默认关闭，
+          # 每次事件读取当前值，设置保存后即时生效。监听器注册型
+          # 插件，无服务发布，无需 realm。
+          - id: eng-exit-guard
+            name: '@menghuan1918/dsh-apollo/presets/eng/plugins/exit-guard/index.js'
+
+          # ── mode instructions ────────────────────────────────────────────────────────
+
+          # 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

@@ -0,0 +1,90 @@
+---
+name: brainstorming
+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
+
+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.
+
+**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. **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.
+
+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
+
+- **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.
+
+Do not write Specs before consensus. When a later answer changes a premise, go back and fix earlier decisions.
+
+## Design granularity
+
+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.)
+
+- 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
+
+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.
+
+**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.
+
+**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.
+
+## Multi-Spec structure
+
+### Master 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.
+
+### Sub-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>/.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
+```
+
+- 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
+
+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
+
+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 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.