Preface¶

When running coding tasks with “everything is a plugin” harnesses like dsh (DeepSeek Harness), the common problem is not that the model cannot write code, but that it starts writing immediately upon receiving the requirements: when requirements are vague, the implementation direction drifts, leading to the highest rework costs; assumptions are treated as facts, and the plan stands on shifting sands; too much work is done during implementation, or the scope drifts further away. Writing specifications into the system prompt is a common approach, but constraints remain at the level of “self-discipline,” lacking a hard gate.

The philosophy behind keel (the keel) is: write specifications first and verify assumptions first; do not start implementation until the specifications pass the gate. During implementation, use rules to prevent over-engineering and use change requests to prevent scope creep; audit and verify acceptance criteria item-by-item before delivery. Discipline is enforced by skills constraining agent behavior and by tools performing deterministic checks, not relying on human self-discipline.

Below, I will introduce the composition, installation, and usage of this plugin.

What is this?¶

keel is a spec-driven development (spec-driven) discipline skill-pack, maintained by GitHub user JohnXu22786, under the MIT license, version 1.0.0. It constrains agent coding behavior in the form of skills + tools + templates, providing self-contained integration for plugin-based harnesses like dsh, and can also be used independently with a bare CLI. Repository keywords: dsh-plugin, spec-driven, spec-first, skill-pack, keel.

The Five-Step Discipline Cycle¶

The core of keel is a five-step cycle, where each step is constrained by a skill and comes with its own gate:

The same discipline applies to post-mortems: write the failure cause specification first, verify assumptions, then fix.

Three Tools and Six Templates¶

After loading, the model gains three tools:

• keel_catalog: Lists skills and templates, serving as the routing entry.
• keel_spec: Generates spec class files from templates; parameters are template/path/fields; the entire call is rejected if any field is missing.
• keel_review: Reviews SPEC/ASSUMPTIONS/AUDIT files, outputting a report with rule IDs and line numbers.

There are six templates in total (including variants), selected based on task size:

• spec.minimal: Micro tasks.
• spec: Standard tasks.
• spec.feature: Large tasks.
• assumptions: Assumption registration, including risk levels and verification conclusions.
• audit: Acceptance audit table, including results, evidence, deviations, and retrospectives.
• change-request: The only entry point for scope changes after the specification is frozen.

Installation and Enablement¶

keel comes with a dsh.bundle manifest (cordis.patch.yml, referenced by the dsh.bundle.patch field in package.json). It can be installed and activated with a single command:

dsh plugin --profile demo add github:JohnXu22786/spec-driven

The bundler inserts the plugin line (name: keel) into the profile. dsh parses the package entry src/index.ts, loading and registering the three tools and five skills upon load.

You can also bypass the bundle and load it manually via a cordis.yml patch locally: place the plugin directory in your project or copy it to any location, and create a patch pointing to the plugin entry (you can copy cordis.example.yml from the repository root and modify it):

- insert:
    - id: keel
      name: '/absolute/path/spec-driven/src/index.ts'

Then start the harness and load the patch:

dsh web --patch ./cordis.yml

For more integration details (loading, registration interfaces, three ways to load skills, unloading and reloading), see docs/INTEGRATION.md in the repository.

Configuration¶

Configuration is passed in via the config field of the host patch line; default values are used when there is no harness. There are three configuration items:

• strictness: relaxed | strict; strict upgrades warnings to errors.
• requireAssumptions: requires the existence of ASSUMPTIONS*.md in the same directory when reviewing a spec.
• maxFindings: The upper limit of findings per review report; values range from 1 to 1000.

Invalid configuration fails during loading, with error messages containing fix hints. Default values for each configuration item are not listed in the documentation; refer to the repository documentation before integration.

Bare CLI: Using without a Harness¶

You can use it without a harness by running it directly with Node:

node src/cli.ts catalog
node src/cli.ts scaffold spec SPEC.md "--title=Example" "--goal=Goal" "--in_scope=- behavior" "--out_of_scope=- not doing" "--requirements=- R-01" "--acceptance=- AC-01" "--verification=command"
node src/cli.ts review SPEC.md

The three subcommands are: catalog lists skills and templates, scaffold spec generates a spec file from a template, and review reviews a spec file. Values containing spaces must be quoted (as shown above).

When review has no errors, the exit code is 0; when there are errors, the exit code is 1, making it suitable to be used directly as a CI gate.

Development and Self-Check¶

npm test          # node --test all tests (zero runtime dependencies)
npm run typecheck # tsc --noEmit
npm run cli       # bare CLI

keel has zero runtime dependencies; npm install only installs development-time type packages (typescript, @types/node). Running tests and type checking requires Node ≥ 22.18 (the engines field in package.json requires node >=22.18.0).

Documentation and Examples¶

• docs/METHODOLOGY.md: Methodology, the ten anti-over-engineering rules, scope creep guardrails, KEEL-* review rule checklist.
• docs/INTEGRATION.md: dsh integration details.
• docs/PLANNING_BRIDGE.md: Bridge to planning/task breakdown skills.
• examples/: Positive and negative examples, demonstrating the audit engine’s findings.

Use Cases and Notes¶

Who is it for:

• Running coding tasks in plugin-based harnesses like dsh, wanting the agent to establish specifications and verify assumptions before writing directly.
• Wanting to constrain agent over-engineering and scope creep, and not satisfied with relying solely on prompt constraints.
• Needing to integrate specification review into CI (the review exit code can serve as a gate).
• Tasks ranging from micro to large, with corresponding templates available.

Notes:

1. The runtime environment requires Node ≥ 22.18.
2. The plugin runs with the permissions of the current dsh process; you should check the source code and license before installing (MIT, see the repository LICENSE file).
3. Replace --profile demo in the install command with your actual profile.
4. keel constrains the process and specification quality; the written code still undergoes regular reviews.

Conclusion¶

keel turns the slogan “write specifications first, then code” into skills, tools, and gates: the five-step cycle constrains agent behavior, keel_review provides deterministic review with rule IDs and line numbers, and changes after the specification is frozen are routed through change-request. If you are running coding tasks in dsh and struggle with direction drift and scope creep, you can try integrating it using the commands above.

• Directory Page: https://www.skillhub.cn/plugins/JohnXu22786/spec-driven
• GitHub: https://github.com/JohnXu22786/spec-driven