@andrepontesmelo/dsh-suite

Readme

# dsh-suite

[![CI](https://github.com/andrepontesmelo/dsh-suite/actions/workflows/ci.yml/badge.svg)](https://github.com/andrepontesmelo/dsh-suite/actions/workflows/ci.yml)
[![Version](https://img.shields.io/github/package-json/v/andrepontesmelo/dsh-suite/main?label=version)](package.json)
![local gate](https://img.shields.io/badge/local%20gate-9%20skills%20valid-brightgreen)

![dsh-suite banner](docs/images/banner.png)

**The DeepSeek Harness productivity suite**: self-authored plugins + agent skills for [DSH](https://www.npmjs.com/package/@deepseek-ai/dsh), installable in one command.

## What's inside

| Piece | Type | What it does |
|---|---|---|
| [`dsh-model-router`](https://github.com/andrepontesmelo/dsh-model-router) | plugin | Virtual model ids routed over real provider/model candidates — priority failover, round-robin rotation, sleep windows |
| [`deep-horizon`](https://github.com/andrepontesmelo/deep-horizon) | plugin | Injects the project's horizon (open gaps + about line) into every new session — cold-start project context shared across harnesses |
| strong-orchestrator | skill | Sequential implement → review-loop orchestration with a persistent implementer |
| dex / dex-plan | skills | Task hierarchies: epics, subtasks, verification via the dex CLI |
| ponytail (+ audit, debt, gain, help, review) | skills | Lazy-senior-dev output style family: shortest working diff wins |

**What the one install command does** — install, plugin registration, skills wired:

```mermaid
flowchart TD
    install["dsh plugin --profile myprofile add github:andrepontesmelo/dsh-suite"] --> pkg["package installed: cordis.patch.yml, skills/, scripts/"]
    pkg --> deps["plugin dependencies pulled: @andrepontesmelo/dsh-model-router + deep-horizon"]
    deps --> patch["bundle patch inserts three rows into the profile"]
    patch --> r1["model-router row: virtual model ids"]
    patch --> r2["deep-horizon row: cold-start project context"]
    patch --> r3["skill-suite row: dsh-skill-filesystem, customSkillDirs pointing at skills/"]
    r1 --> live["restart the harness: plugins live, 9 skills wired"]
    r2 --> live
    r3 --> live
```

## Install

Requires a DSH profile to install into.

```bash
dsh plugin --profile <profile> add github:andrepontesmelo/dsh-suite
```

That single command installs this package, pulls the plugin dependencies (currently `@andrepontesmelo/dsh-model-router` and `deep-horizon`), and registers the bundle patch — which points DSH skill discovery at the nine bundled skills. Restart the harness and every suite piece is live in that profile.

> [!WARNING]
> Installing this bundle registers nine agent skills into the target profile, and
> every plugin you list is real software your prompts will flow through. Routes
> and provider credentials stay yours — this bundle ships neither — but audit a
> bundle you did not write before installing it, and pin the install (tag)
> rather than floating on a branch.

Verify before installing:

```bash
npm test   # structural check: 9 skills present, valid names/frontmatter, bundle wiring intact — run this pre-install check first
```

That check confirms what the install pulls per the `files` list in
`package.json` (`cordis.patch.yml`, `skills/`, `scripts/`, `README.md`,
`LICENSE`) plus the plugin `dependencies`. Both dependencies are pinned to
release tags (`deep-horizon#v0.2.0`, `@andrepontesmelo/dsh-model-router#v0.2.1`), so what an
install pulls cannot drift between installs — pin your install of this
bundle the same way (tag) rather than floating on a branch.

Useful commands once installed:

```bash
npm test                                    # re-run the structural gate any time
dsh plugin --profile <profile> list         # confirm model-router, deep-horizon, skill-suite rows
```

**What the bundle patch inserts into your profile's composed config**:

```mermaid
flowchart LR
    subgraph bundle["dsh-suite cordis.patch.yml (ships in the bundle)"]
        rows["insert rows:<br/>model-router<br/>deep-horizon<br/>skill-suite"]
    end
    subgraph profile["your profile config"]
        p1["model-router: virtual model ids<br/>(your routes live here, never in the bundle)"]
        p2["deep-horizon: cold-start project context"]
        p3["skill-suite: dsh-skill-filesystem with<br/>customSkillDirs pointing at the<br/>bundle's skills/ directory"]
    end
    rows --> p1
    rows --> p2
    rows --> p3
```

Plugin *configuration* (model-router routes, provider credentials) stays yours: add route rows to your profile's `cordis.patch.yml`.

## Companion pieces

Standalone siblings that don't ride in this bundle:

- [`archloop`](https://github.com/andrepontesmelo/archloop) — overnight architecture-improvement loop driver
- [`hkrc`](https://github.com/andrepontesmelo/hkrc) — Hermes Kanban blocker recovery controller

## Docs

Start at the [docs index](docs/index.md):

- [Architecture](docs/architecture.md) — bundle wiring, patch rows, skill discovery.
- [Development](docs/development.md) — layout, the local gate, how to add a skill.

## Contributing

PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow and the local gate.
Security issues: [SECURITY.md](SECURITY.md) (do not open a public issue).

## Validate

```bash
npm test   # structural check: 9 skills present, valid names/frontmatter, bundle wiring intact
```

## License

MIT — © 2026 André Pontes Melo