# Architecture

How dsh-suite wires into [DSH](https://www.npmjs.com/package/@deepseek-ai/dsh):
one install command delivers plugin packages plus a bundle patch that points
skill discovery at the nine skills shipped inside this package.

## One diagram

```
 dsh plugin --profile <profile> add github:andrepontesmelo/dsh-suite
        │
        ▼
 ┌──────────────────────┐
 │ dsh-suite package    │  files: cordis.patch.yml, skills/,
 │  dependencies        │         scripts/, README.md, LICENSE
 │   ├─ dsh-model-router│  pulled as plugin packages
 │   └─ deep-horizon    │
 └──────────┬───────────┘
            │ bundle patch (dsh.bundle.patch -> ./cordis.patch.yml)
            ▼
 ┌──────────────────────┐
 │ cordis.patch.yml     │  insert rows:
 │  ├─ model-router     │  virtual model ids (configure in YOUR profile)
 │  ├─ deep-horizon     │  cold-start project context
 │  └─ skill-suite      │  @deepseek-ai/dsh-skill-filesystem
 └──────────┬───────────┘  customSkillDirs -> skills/ of THIS package
            │
            ▼
 agents see 9 skills: dex, dex-plan, ponytail (+ audit, debt,
             gain, help, review), strong-orchestrator
```

## Pieces

- **`cordis.patch.yml` — the bundle patch.** Three insert rows. `model-router`
  and `deep-horizon` activate the plugin dependencies (their configuration —
  routes, credentials — stays in your profile's own patch, never here).
  `skill-suite` registers `@deepseek-ai/dsh-skill-filesystem` with
  `customSkillDirs` pointed at this package's `skills/` directory via the
  self-referential `fileURLToPath(new URL('skills/', baseUrl))` pattern from
  the shipped cordis preset.
- **`skills/` — the nine bundled skills.** Two coordinators (`dex`,
  `dex-plan`: task hierarchies via the dex CLI), one output-style family
  (`ponytail` plus `ponytail-audit`, `ponytail-debt`, `ponytail-gain`,
  `ponytail-help`, `ponytail-review`: laziest working solution wins), one
  orchestrator (`strong-orchestrator`: sequential implement → review loop with
  a persistent implementer). Each ships a `SKILL.md` with `name:` matching its
  folder and a `description:` trigger line.
- **`scripts/validate.mjs` — the structural gate.** Verifies the
  `dsh.bundle.patch` pointer exists and inserts a skill-filesystem row aimed at
  `skills/`, then checks every skill folder for a matching `name:`,
  a `description:`, and a valid skill-name shape. Expects exactly the nine
  known skills — a missing or extra skill fails the gate.
- **`package.json` — the wiring contract.** `dsh.bundle.patch` points at
  `./cordis.patch.yml`; `files` lists what the install pulls; `dependencies`
  pulls the plugin packages. `npm test` runs the validator.

## Install sequence

1. `dsh plugin --profile <profile> add github:andrepontesmelo/dsh-suite`
   installs this package and pulls the plugin dependencies.
2. The bundle patch inserts the three rows into the profile's composed config.
3. Restart the harness: the two plugins activate and skill discovery picks up
   the nine skills from this package's `skills/` directory.
4. Add your own route rows and credentials to your profile's `cordis.patch.yml`
   — that configuration is yours and never ships in this bundle.