spec-driven

简体中文

keel — Spec-Driven Development Discipline Skill Pack

Write the spec first, then the code. Turn "don't ship it broken" from a slogan into skills, tooling, and gates.

keel is a self-contained pluginized skill pack: five skills (Anchor → Spec → Probe → Build → Audit) constrain the agent's coding behavior, three tools provide spec generation and discipline review, and template variants adapt to task size. It works with plugin-everything harnesses such as dsh (DeepSeek Harness), and can also be used standalone without a harness.

Why you need it

The three main causes of coding failure:

1. Missing spec — you start with vague requirements, and wrong implementation direction costs the most rework;
2. Unverified assumptions — treating "I assumed" as "it's a fact" builds the plan on quicksand;
3. Engineering out of control — doing too much (over-engineering) or drifting (scope creep).

keel's response: write the spec and verify assumptions first; no implementation until the spec passes the gates. During implementation, use the rules to prevent over-engineering and change requests to prevent scope creep. Before delivery, audit each acceptance criterion one by one. Discipline is enforced through skills/prompts that constrain agent behavior and through tools that provide deterministic checks — it does not rely on human self-discipline.

Five-step discipline loop

Step	Skill	Action	Artifact	Gate
1 Anchor	keel-anchor	Three boundary questions: what to do, what not to do, what success looks like	Three sentences	All three sentences verifiable
2 Spec	keel-spec	Pick a template by size and generate the spec	SPEC.md	keel_review zero errors
3 Probe	keel-probe	Register assumptions, flag risks, verify high-risk ones first	ASSUMPTIONS.md	All [High] assumptions resolved (enforced by KEEL-0303)
4 Build	keel-build	Implement per the spec, follow the ten rules and the scope guardrails	Code	Spec frozen, changes go through change requests
5 Audit	keel-audit	Check acceptance criteria one by one, record deviations and retro	AUDIT.md	No unaddressed ❌ (enforced by KEEL-0403)

Failure post-mortems follow the same discipline: write a failure-cause spec first, verify assumptions, then fix.

Quick start

Option 1: Plug into dsh (pluginized harness)

1. Put this directory into your project, or copy it anywhere;
2. Create a cordis.yml patch (you can copy cordis.example.yml from the repo root) pointing to this plugin's entry:

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

3. Start the harness and load the patch:

dsh web --patch ./cordis.yml

Once loaded, the model gains three tools (keel_catalog, keel_spec, keel_review) and five skills (keel-anchor, keel-spec, keel-probe, keel-build, keel-audit). See docs/INTEGRATION.md for details.

Option 2: Bare-metal CLI (no harness)

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

Values containing spaces must be quoted (as above). review exits with code 0 when there are no errors (usable as a CI gate) and 1 when errors exist. Zero dependencies; runs directly on Node ≥ 22.18.

Installing in DSH

keel ships a dsh.bundle manifest (cordis.patch.yml, referenced from package.json),
so it installs and activates in one command:

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

The bundler inserts a plugin row (name: keel) into the profile and dsh resolves the
package entry (src/index.ts), registering the three tools and five skills on load.
Manual local loading via a cordis.yml patch still works (see
docs/INTEGRATION.md).

Tool interface

Tool	Purpose
keel_catalog	List the skills and templates (routing entry)
keel_spec	Generate spec-class files from a template (template/path/fields args; rejects the whole call if any field is missing)
keel_review	Review SPEC/ASSUMPTIONS/AUDIT files; outputs a report with rule IDs and line numbers

Spec templates (with variants)

Template	Size	Use
spec.minimal	Micro task	Single file, single behavior, done in under half an hour
spec	Standard	Regular feature tasks
spec.feature	Large task	Involves interfaces, data, and error paths
assumptions	—	Assumption register (risk levels + verification conclusions)
audit	—	Acceptance audit table (result + evidence + deviation + retro)
change-request	—	Change request (the only entry for scope changes after the spec is frozen)

Configuration

Passed via the config field of the host patch line (defaults are used without a harness):

{
  "strictness": "relaxed",        // relaxed | strict (strict upgrades warnings to errors)
  "requireAssumptions": true,     // require an ASSUMPTIONS*.md file in the same directory when reviewing a spec
  "maxFindings": 100              // cap on findings per review report (1–1000)
}

Invalid configuration fails at load time with a message containing fix guidance.

Documentation index

• docs/METHODOLOGY.md — methodology overview: five-step discipline loop, the ten rules against over-engineering, scope-creep guardrails, review rule list (KEEL-*)
• docs/INTEGRATION.md — dsh integration: loading, registration interface, the three ways to load skills, unload and reload
• docs/PLANNING_BRIDGE.md — bridging to planning/task-breakdown skills: how spec artifacts feed into planning
• examples/ — good examples (spec/assumptions/audit) and counter-examples (demonstrating the review engine's findings)

Development

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

Running tests and type checks requires Node ≥ 22.18; npm install only installs dev-time type packages (typescript, @types/node); zero runtime dependencies.

License

MIT, see LICENSE.