[English] [简体中文]

streamsmith

A complete software workflow inside your coding agent: requirements → design → breakdown → parallel implementation → review → shipping.
Skills make the judgment calls; ordering and checkpoints go to tested scripts; implementation goes to subagents isolated in their own git worktree.

Online docs · Install · Skills · Workflow · Project Status

## What is streamsmith? streamsmith is a set of development-workflow skills: 25 skills that take a change from "an idea" to "shipped code" through standard steps — requirements, design, breakdown, implementation, review, shipping — each owned by one skill. You say what you want; the agent asks the questions, writes the PRD, splits it into Issues with blocking edges, implements in parallel inside isolated worktrees, reviews, opens the PR and merges. **An implementation node is a subagent** in its own git worktree, and its job stops at "implement → prove it against the project's gates → commit on its own branch". Leak check, integration, gates on the integrated tree, review and shipping are one step, done **once per wave**: a single PR closes every Issue the wave satisfies. Ordering, layering, cycle detection and checkpointing are arithmetic, and they live in the Python scripts shipped with the skills (standard library only, with self-tests). The skills themselves carry only judgement: **scripts do the arithmetic, skills do the judgement**. ## Quick Start ### Option 1: Install as a skill directory (recommended) ```bash npx skills add 9Ashwin/streamsmith # installs globally (~/.agents/skills) npx skills update -g # update from source later ``` The skills land in `~/.agents/skills`, and this route changes nothing in any profile's dependencies. `npx skills` scans recursively and flattens `skills//` into `~/.agents/skills/` — a skill root is scanned only one level deep, so the flattening is required. Copying by hand means doing that step yourself: ```bash cp -R /skills/flow/graph ~/.agents/skills/graph # flattened, not the bucket ``` ### Option 2: Install as a bundle (optional) ```bash dsh plugin --profile web add -w github:9Ashwin/streamsmith ``` The package's `dsh.bundle` declaration makes `dsh` append it to the profile's `bundles` layer; the skills are then served by the **provider shipped inside the package**. ```bash dsh --profile web --dump-config | grep -A3 streamsmith # expect a "# == streamsmith-skills" layer ```

More install details (pnpm errors / pinning a version / local checkout)

- If pnpm reports `ERR_PNPM_ADDING_TO_ROOT`, the profile is being treated as a workspace root — re-run with `-w` (pnpm 9 requires it). - Pin the commit in production: `dsh plugin --profile web add -w github:9Ashwin/streamsmith#`. - This is a **config-only package** (no build scripts), so no `allowBuilds` grant is needed. - Working from a local checkout: `dsh plugin --profile demo add -w /path/to/streamsmith`.

**Which route to pick.** On a surface like Web the shipped preset already supplies the skill catalog, and `~/.agents/skills` is one of its roots — so Option 1 is enough if all you want is the skills. Same-named skills de-duplicate by **nearest layer wins**, and the directory copy beats the package copy. What Option 2 adds is a **preset that travels with the package**: which skills an agent mounts, and whether its subagents get a skill catalog (`toolFilter`) and a persona, become deployment configuration. On a surface with no preset at all (some minimal profiles), Option 2 is what makes the skills visible. Installing both never lists a skill twice; on a Web-like surface the bundle copy simply loses. > [!TIP] > Not sure which skill to reach for? Type **`/ask-flow`** — it names the next thing to type and the decisions that are yours to make. > > The full usage guide (installation, how to trigger each step, acceptance criteria, FAQ) lives at ****, which redirects to the Chinese or English version based on your browser language; in the repo it is [docs/index_cn.html](docs/index_cn.html) and [docs/index_en.html](docs/index_en.html). ## How It Runs Three phases with scopes that do not overlap: | Scope | Does | Doesn't | | --- | --- | --- | | **Node** | Implements in its own worktree, proves itself with the project's gates, and **only commits to its own branch** | No push, no PR, no merge, no self-review | | **Wave** | Leak check → merge only the nodes that finished → run gates on the integrated tree → **review once** (one section per node, focused on the seams between nodes) → **ship once** (one PR with a per-item evidence table) | No node-level PRs | | **Batch** | The serial path in `/loop-it` works the same way: implement and commit one Issue at a time inline, then review and ship once at the end of the batch | — | A few deliberate design choices: - **Use `/graph` only when there is real parallelism.** One unit, two units that share a file, or chained work like "schema → API → UI" belongs in `/loop-it` or done inline — all of `/graph`'s value comes from nodes within a wave being genuinely independent. - **A single-node wave skips the wave branch.** There is nothing to integrate, so that node's branch goes straight to review and shipping. - **Failed nodes are retried in place first.** A follow-up message reuses that node's own context instead of paying for a fresh child; if the retry still fails, the node is re-run, and if it fails again it is dropped from the wave branch — its siblings were independent all along, so the rest ship as usual. - **When one PR closes several Issues, list the evidence per item**: the commit, the Issue it closes, the test names that prove it, and the manual acceptance status. After a squash those commits are invisible on `main`, and without this table there is no way to roll back or audit one Issue on its own. ## Why streamsmith - **Cost is counted per wave, not per node.** Every subagent pays for the parent's system prompt, tool schemas, and skill catalog across its entire lifetime, and a `/review-it` + `/ship-it` per node means N PRs, N CI runs, and N chances to get stuck on a merge conflict. So nodes stop at commit, and review and shipping are collected at the wave level. - **The arithmetic lives in scripts.** Dependency ordering, wave layering, scope-conflict serialization, and the checkpoint state machine all sit in `scripts/`, each with self-tests; the skills describe when to use them and where the boundaries are, not how the algorithm works. - **Designed around real constraints, not an idealized model.** Subagents have no cwd of their own, every shell call is a fresh shell, delegation depth is capped, and the skill catalog is billed to every subagent — all of which became hard rules in the skills (absolute-path discipline plus leak checks against the shared checkout, nodes may not spawn further subagents, and an optional [lean-subagent patch](skills/flow/graph/references/lean-subagent.md)). ## Skills **Not sure which one? Type `/ask-flow` first** — it names the next thing to type and does not act for you. | Stage | Skill | What it does | | --- | --- | --- | | Entry | `/ask-flow` | Ask which skill or flow fits your situation (it routes only; it does not run anything) | | Requirements & design | `/prd` · `/prd-to-spec` · `/to-design` · `/design-it` | Requirements doc → technical SPEC → Go-style design proposal → fixed-style HTML design doc | | Breakdown & triage | `/to-issues` · `/triage` | Split your own PRD/SPEC into vertical slices · turn **incoming** raw issues into agent-ready cards | | Implementation | `/implement` · `/test-first` · `/graph` · `/loop-it` | Finish a single unit inline · red-green testing · DAG waves in parallel (one worktree per node) · Issues in dependency order, serial (resumable checkpoints) | | Diagnosis | `/diagnose` · `/conflict` | A debugging loop that demands a red-capable command first · resolve merge/rebase conflicts hunk by hunk by intent | | Review & shipping | `/review-it` · `/ship-it` · `/note-it` | Two-axis review (Spec + 8 standards dimensions) · commit/PR/merge/close Issue · implementation notes for an Issue | | Code quality | `/smell` · `/refactor` · `/modern-go` | Architecture smells and complexity hotspots · Fowler's refactoring catalog · Go 1.0→1.27+ modernization | | Reverse engineering & docs | `/code-to-spec` · `/understand` · `/insight-diagram` | Reverse a SPEC out of code · turn the current change into an interactive review page · UML/architecture diagrams | | Content | `/humanize-it` · `/article-icons` · `/listenhub-tts` | De-AI-ify documents · article icons · text to speech | Five skills carry `disable-model-invocation` (`/ask-flow`, `/insight-diagram`, and the three content tools in the last row) and stay **out of the model catalog**: the model will not reach for them on its own, you type the command — which saves the fixed cost every session **and every subagent** would otherwise pay. Across the current 25 skills the catalog is 4,818 characters, of which the model actually sees **3,651**. Those five also ship an `agents/openai.yaml` (`policy.allow_implicit_invocation: false`). `/goal` is a DSH **command**, not a skill: you type it at the prompt to create a persisted goal with automatic continuation rounds. The model side of that surface is `create_goal` / `update_goal`, but `create_goal` only runs in a **direct top-level human turn** — a subagent or a mid-orchestration step cannot mint a long-horizon goal for itself. ## Repository layout ``` skills/ ├── flow/ # one link in the PRD → ship chain, run in order (9) ├── practice/ # engineering practice you reach for mid-flow (7) ├── meta/ # about the skill set itself: the router (1) └── bonus/ # produces non-code artifacts: design docs, diagrams, specs, content (8) ``` The test is the role a skill plays: `flow` is the pipeline itself; `practice` is what you reach for mid-flight because something broke or because quality is at stake (a testing method, diagnosis, conflicts, incoming triage, quality passes); `meta` describes the set itself (`/ask-flow`, the router); `bonus` produces artifacts that are not code. A DSH skill root is scanned **exactly one level deep** (`//SKILL.md`), so `cordis.patch.yml` lists each of the four buckets as its own root rather than pointing at `skills/`. `npx skills add` scans recursively and flattens on install, so both routes yield exactly the same set. `scripts/check_skills.py` guards the two silent failures: **a skill left at the top level** (the bundle install cannot see it) and **a bucket missing from the patch** (that whole bucket disappears without an error). ## Project Status ![License](https://img.shields.io/github/license/9Ashwin/streamsmith) ![Last Commit](https://img.shields.io/github/last-commit/9Ashwin/streamsmith) ![Commit Activity](https://img.shields.io/github/commit-activity/m/9Ashwin/streamsmith) ![Issues](https://img.shields.io/github/issues/9Ashwin/streamsmith) ![Pull Requests](https://img.shields.io/github/issues-pr/9Ashwin/streamsmith) ## Community & Feedback - 🌐 [**Online docs**](https://9ashwin.github.io/streamsmith/) — usage guides in Chinese and English - 🐛 [**Issues**](https://github.com/9Ashwin/streamsmith/issues) — bugs, feature requests, and skill improvements - 🧩 [**DeepSeek Harness**](https://github.com/deepseek-ai/DeepSeek-Harness) — the host these skills run on ## License MIT — see [LICENSE](./LICENSE).