dsh-super-code 0.3.10 → 0.4.0

package/builtin/skills/pstack/dsh/DSH.md

@@ -0,0 +1,59 @@
+# PStack on DeepSeek Harness
+
+Read this once when using a PStack workflow. Follow the user's request and host permissions. This file translates the workflow's host operations; the selected Skill and playbook still define its steps and completion criteria.
+
+## Delegation
+
+Use the `subagent` tool exposed in this conversation, with its actual schema. The portable call is `{ "description": "short role and task", "prompt": "self-contained brief with scope, exact resource paths, evidence and report contract" }`. Give writers separate files or worktrees and pass `cwd` only when the schema supports it. Include the current task's exact write/read fence, allowed scratch path, read-only requirements and external-action restrictions in every child brief; children do not automatically inherit the root user message. Roles such as poteto-agent and comment-sicko are prompt templates in `agents/`, not registered agent types. Include the required template and this installation's absolute paths in the brief.
+
+Children use the host's model selection. Omit model fields by default. If the current tool exposes model selection and model discovery, use only confirmed provider/model IDs and supported effort values under the user's authorization. Read capabilities from the conversation's advertised tool metadata or exposed discovery tools; missing metadata means inherit, not scan host source, profiles, configuration, environments or credentials. A project preference cannot enable a hidden field or change the user's model settings. Use a different family for cross-model review only when an actual allowed route exists; otherwise keep independent reviewers on the inherited model and report that the review was not cross-model.
+
+DSH Super Code normally limits delegation to one level. The root coordinates all phases; a child returns a request for another role instead of starting grandchildren. Run the dependent phase from the root after its inputs exist. With delegation unavailable or disallowed, execute the same phases sequentially and report the loss of independent review; don't claim a second agent ran. Capacity limits require a bounded queue, not extra DSH processes.
+
+Inspect the returned result kind. A synchronous `foreground` result already contains the completed output and needs no follow-up. A managed activation returns a subagent ID: use `list_agents`, `send_message`, and `interrupt_agent` only when present, with their published fields. Follow the host's completion-notification contract. Continue useful independent work; when only waiting remains, end the turn so a result can resume it. A background-job result instead uses its `job_output` contract. A run ID or job ID is not a subagent ID. Never guess an ID or poll/sleep in a tight loop.
+
+Read a completed delegate's final text/image blocks rather than serializing the entire result, which may also contain reasoning and metadata. For a content-array `output`, select its `type: "text"` blocks and consume them in the same tool call. Ask for a concise reply when output is limited, or print meaningful bounded excerpts with their citations. Do not start the same delegate again or create a capture file merely to print its reply.
+
+## Tools and resources
+
+Use the current tool catalog: `read`, `write`, `edit`, `glob`, `grep`, `bash`, web tools, and MCP tools only when exposed. A role marked read-only has a no-write brief; do not change the host's permission mode to give it MCP access. For a user decision, use the host's question tool when exposed, otherwise one concise chat question. Keep todos in the existing host tool when available, otherwise the task's PLAN.md. Do not create a second task ledger for a trivial request.
+
+Read-only roles may inspect source, Git history and available MCP sources, including through commands that only read. They must not write files or change external state. A probe that writes files or has other side effects belongs to a separately authorized verification task, not a read-only investigation.
+
+For command evidence, invoke each command directly through the native shell tool and retain its stdout, stderr and exit-code fields. This avoids temporary capture files and their cleanup. Create a file only when the requested artifact needs it, in the task's scratch directory; recoverable cleanup or retaining the evidence replaces shell deletion.
+
+When a workflow needs evidence files for later review, run `node "<PSTACK_ROOT>/scripts/capture.mjs" <program> <argument> ...` from the task workspace. The [capture helper](scripts/capture.mjs) executes argv once without a shell and returns its exit/signal plus a unique `scratch/pstack-evidence-*` directory containing command.json, stdout.txt, stderr.txt and result.json. Read those files and cite that returned path; each invocation keeps its own evidence instead of overwriting earlier output. Child temporary-directory variables point into that run. Verify retained bytes with `node "<PSTACK_ROOT>/scripts/capture.mjs" --verify "<returned-directory>"`. Supply shell syntax only through an explicit shell argv when needed; stdin is EOF. Keep credentials out of argv and captured output. Hash verification establishes unchanged evidence, not command success or a true audit claim.
+
+Keep temporary files, logs, evidence and npm caches in the task-owned workspace or its explicit scratch directory. Prefer a project-relative scratch path; an absolute `/tmp` path or the user's HOME is not the task workspace. Read PStack preferences only from the current project's `.dsh/pstack.md`. The original upstream tree beside this DSH distribution is upgrade reference material, not a fallback workflow or a place to discover settings.
+
+For routed PStack Skills, read the sibling `skills/<name>/SKILL.md` as workflow reference after the user explicitly selects this package's workflow. User-only Skills remain user-only in the native catalog; do not attempt a model `skill` call that the host rejects. Resolve references and scripts relative to the returned resource directory, not a guessed cache or home path. `<PSTACK_ROOT>` means this installed directory containing DSH.md and skills/. Substitute its actual absolute path and quote it in commands. Bundled resources are installed files, not paths in the user's Git branch. If a required resource is no longer accessible, report it rather than searching private host directories.
+
+For UI/CLI verification, use a project's own harness, available browser/terminal/MCP tools, or generate a project verification Skill with `skills/create-verification-skill/SKILL.md`. Keep launch, drive, evidence and cleanup. For authoring, use `authoring.md`. Before committing, review the diff for unnecessary changes and run the project's relevant checks. These replace external authoring, control and cleanup Skills; no external Skill plugin is required.
+
+## Images
+
+Use DSH's native composer to select, paste or drop user images. For screenshots, rendered slides and other project images, use the exposed `read_image` tool: its image content reaches the selected model through the host's attachment pipeline. A filename, a text `read` result or your own caption does not perform visual review. For a video, decode a frame from every slide and inspect those actual frames before declaring the visual stage complete.
+
+Image input follows the selected model's capability declaration in DSH model settings. With the pi-ai provider this is `models[].input: ["text", "image"]`, or the provider's inherited `defaultInput`. An error saying the model “does not declare image input” establishes a missing declaration for that route, not that the underlying model cannot see images. Ask the user to verify that setting or choose an authorized image-capable route; keep the exact blocked stage visible until it is retried. Do not enable images for all models or modify private host configuration from a workflow. DSH owns image validation, resizing, durable references and provider encoding; no second upload service is needed.
+
+## Conversation history
+
+Use the current conversation and explicit handoffs first. When available, use workspace-scoped `session_search` to locate prior work, then `session_event_search`, `session_event_read` or trace tools using their actual schemas. For an MCP-owned task, the caller can use `dsh_read` with that task's returned ID and cursors. These are distinct interfaces; don't feed an MCP task ID to session tools.
+
+Older hosts or a preset may expose neither history interface. Then use a user-provided export/handoff, the task's PLAN.md or decision log, Git history and project-local artifacts. State which history was unavailable and ask for the specific export only if essential. Never infer a private profile path or decode internal journals. Scope history to the current workspace and requested time range; missing history is not an empty result.
+
+Durable lessons require the user's consent. Put approved project Skill overrides under `.dsh/skills/<name>/SKILL.md` (also recognized by old supported hosts); edit an existing user/project override in place. Bundled resources are read-only distribution files. Do not edit plugin caches, global rules or unrelated project conversations. Existing sourced memory tools may be used under their own schema; don't invent sources or write preferences merely because a workflow found a pattern.
+
+## Setup, autonomy and long runs
+
+`/setup-pstack` writes an optional project `.dsh/pstack.md` only after the user chooses its preferences. At workflow and dependent phase start, read this project file if it exists; it is not a system rule or a host settings file. Match its role labels to the workflow's named roles. Reasoning budget, panel size and scheduling parallelism are separate choices; the complete role map and budget semantics live in [setup-pstack](skills/setup-pstack/SKILL.md). Preserve configured panel counts while queuing within host capacity. Missing preferences mean inherit the host model and choose bounded parallelism from current capacity. Unsupported routes/efforts must be reported, not silently applied or replaced with extra agents. The package switch does not execute setup, install dependencies or alter the global prompt.
+
+A workflow never grants permission to publish, create/merge a PR, message others, delete data, install tools or expose a service. Use authorization already given for that effect; ask only for a missing decision. Use recoverable deletion and follow the plugin's deletion-protection setting, including in scripts. Preserve unrelated changes and commits. Keep the finish condition and resume point in the task's own plan; no fabricated loop command, scheduler or daemon is needed. If a long run needs a facility the host lacks, checkpoint what remains rather than claiming it keeps running after the turn ends.
+
+Keep cleanup scoped to paths created by this task. Retain process handles or PIDs when launching a renderer, encoder or backend, and stop those owned processes through their handles; a shared executable name does not establish ownership. When recoverable deletion is unavailable, retain the scratch paths and report them rather than adding a permanent-deletion fallback. Finish once the requested artifact, required reviews and relevant checks meet the stated completion criteria. Treat an unavailable source or an inconclusive measurement as a precise evidence limit; expanding the project or repeating a completed review does not remove that limit.
+
+## Optional dependencies
+
+The Git/GitHub workflows require Git and authenticated `gh` (or a user-configured forge tool). Direct forge queries remain usable without the optional Bun watcher. Before using that watcher, copy the entire `skills/poteto-mode/scripts/` directory to a task-owned tools directory, represented as `<PSTACK_TOOLS>` in commands. Quote the actual path. Obtain authorization for its frozen dependency installation before the first invocation: its bootstrap can run `bun install --frozen-lockfile`. Run only the staged copy so installation never writes into bundled resources.
+
+Statechart's opt-in helper requires its documented Java/TLC/mise dependencies; check availability before invoking it because it can install missing tools. Use the real model checker and renderer when requested, never substitute a mock proof. Browser/media workflows require a corresponding browser, capture or rendering tool. Report any unmet capability precisely.

package/builtin/skills/pstack/dsh/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lauren Tan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/builtin/skills/pstack/dsh/README.md

@@ -0,0 +1,9 @@
+# PStack on DSH
+
+This is the DSH edition of PStack 0.15.36, for DeepSeek Harness 0.2.1-alpha.1 and later. Enable the PStack package under Super Code settings → Preset Skills, then choose a workflow from the native `/` menu. Enabling the package runs no setup or scripts.
+
+Read [DSH host operations](DSH.md) when running a workflow. All 58 Skills and 23 poteto-mode playbooks are retained. [poteto-help](skills/poteto-help/SKILL.md) provides the entrypoint guide. [setup-pstack](skills/setup-pstack/SKILL.md) optionally records project-local workflow preferences; it does not configure global rules or host models.
+
+The upstream source is preserved beside this generated edition. `adaptation.json` records each source hash and generated hash. The build-time adapter translates delegation, models, history, project Skill paths, long-running checkpoints and bot UI connections. Git/GitHub, browser/media and model-checking workflows still need their real external tools and the user's authorization. A missing capability is reported explicitly; no second host or simulated proof is substituted.
+
+The docs/ directory retains upstream background material, with a DSH notice. Use the adapted Skills and DSH.md for executable procedures. Cursor/Claude installation, custom modes and automation instructions in those upstream guides do not apply to DSH.