# Development

## Layout

```
cordis.patch.yml   bundle patch: plugin rows + skill-suite discovery row
skills/<name>/    nine bundled skills, each with SKILL.md (name: == folder)
  dex, dex-plan, ponytail, ponytail-audit, ponytail-debt,
  ponytail-gain, ponytail-help, ponytail-review, strong-orchestrator
scripts/validate.mjs  structural check: bundle wiring + skill frontmatter
package.json       dsh.bundle.patch pointer, files list, plugin dependencies
docs/              index.md (start here) + architecture.md + development.md
```

## The local gate

Everything must pass before a commit is considered done:

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

The validator uses only `node:fs` — no install step, no dependencies. CI
(`.github/workflows/ci.yml`) runs exactly this gate on Node 22 for pushes to
`main` and every pull request.

## Adding a skill

1. Create `skills/<name>/SKILL.md` with frontmatter: `name:` exactly matching
   the folder (lowercase alphanumerics and hyphens only) plus a `description:`
   trigger line.
2. If the skill is part of the bundle's promise, add the folder to the
   `expected` list in [scripts/validate.mjs](../scripts/validate.mjs) — the
   gate fails on any skill it does not know.
3. Mention it in the [README](../README.md) What's-inside table and in the
   skill counts (`README.md`, `docs/`).

## Conventions

- ESM only (`"type": "module"`), Node ≥ 22 — no transpile step.
- No runtime surface in this repo: it is a bundle (patch + skills + a
  structural check), not a service. No build step, no credentials anywhere.
- Skill counts are stated in several places (README install + validate
  sections, `cordis.patch.yml` comment, docs). Keep them in sync — the
  validator's `expected` list is the source of truth.
- `SKILL.md` frontmatter uses `name:` + `description:` — keep both accurate;
  the description is the agent trigger line.

## Before you push

- [ ] `npm test` green
- [ ] New/changed skill covered by the validator (in `expected`)
- [ ] Skill counts in sync across README, patch comment, docs
- [ ] Docs updated if the bundle wiring or the skill set changed