Contributing

August 21, 2026 ยท View on GitHub

Contributions should make routing more accurate without turning the Skill into a second DSH manual.

Change rules

  1. Start from a named DSH tag or commit and preserve any existing user worktree. Use a fresh temporary checkout for upstream comparison.
  2. Put current product and runtime facts in upstream DSH. In this repository, link or route to those facts; do not copy manifest tables, API signatures, CLI flag inventories, or test command catalogs into SKILL.md.
  3. Keep the installed directory limited to skills/dsh-plugin-development/SKILL.md and agents/openai.yaml. A new bundled script, hook, tool dependency, network call, or permission requires an explicit security and necessity review.
  4. Test observable routing behavior. Update evals/cases.json only when the delivery modes or their pass/fail invariants change, not to pin preferred wording.
  5. Never describe this project as official or endorsed. Name the exact source and evidence behind any alignment or compatibility statement.

Upstream review

When the compatibility workflow reports drift:

  1. Inspect the changed tracked authorities and the new release diff.
  2. Confirm whether the four delivery modes, Host/Client distinction, authority paths, and acceptance tiers still hold.
  3. Run all four eval prompts in fresh agent contexts. Give each agent only the Skill, the target DSH checkout, and the user prompt; do not reveal the expected invariants.
  4. Record failures before editing. Make the smallest routing change, then rerun the failed case and one unaffected case.
  5. Run the local validation commands from both READMEs.
  6. Update compatibility/dsh.json only after the review passes. Set the verified tag to an actual upstream tag; a branch head may be recorded as reviewed but never promoted to a release promise.
  7. Include the DSH tag/commit, eval outcomes, commands run, and remaining uncertainty in the pull request and release notes.

Pull requests

Keep unrelated changes separate. A pull request should explain the user task that previously routed poorly, the official source that resolves it, the observable eval delta, and any increase in Skill lines or bytes.