KM Spec Driven Development

A lightweight Spec Driven Development CLI for AI-assisted software projects.

 _  __ __  __      ____
| |/ /|  \/  |    / ___| _ __   ___  ___
| ' / | |\/| |____\___ \| '_ \ / _ \/ __|
| . \ | |  | |_____|__) | |_) |  __/ (__
|_|\_\|_|  |_|    |____/| .__/ \___|\___|
                         |_|

Version: 0.2.0

What is KM Spec Driven Development?

KM Spec Driven Development (KM SDD) is a methodology and CLI tool that creates a structured, persistent layer of Markdown documentation inside any software project. It gives AI agents a stable context they can read at the start of every session — without relying on chat history or inventing details about the codebase.

The .specs/ folder acts as the single source of truth: what the project does, who it is for, how it is built, and what is left to do.

Why it exists

AI agents lose context between sessions. They invent APIs, duplicate work, and make undocumented decisions. KM SDD solves this by establishing a persistent spec layer that any agent — Claude Code, Codex, Cursor, Copilot, or custom CLI agents — can read before starting work.

Supported environments

• Linux
• macOS
• WSL (Windows Subsystem for Linux)
• Git Bash (basic support)

The CLI is implemented in Bash and distributed via npm. Node.js is only used as a distribution mechanism. No Node.js runtime logic is executed.

Installation

Global install via npm

npm install -g km-spec-driven-development

Use without installing (npx)

npx km-spec-driven-development init

Local development

git clone <repo>
cd km-spec-driven-development
chmod +x bin/km-spec
npm link

Usage

km-spec <command> [options]

Initialize a new project

km-spec init
km-spec init --force   # overwrite existing scaffold files

Creates (among other files): AGENTS.md, HARNESS.md, SDD.md, and the .specs/ tree.

Create a feature (non-interactive by default)

km-spec feature "User Authentication"
km-spec feature "User Authentication" --description "Login and session management for the web application"
km-spec feature "User Authentication" --tier standard
km-spec feature "SSO Federation" --tier complex
km-spec feature "User Authentication" --interactive   # optional legacy prompts
km-spec feature "User Authentication" --force         # overwrite this feature dir only

Default is non-interactive. The CLI does not wait for stdin unless --interactive is passed.

Supported tiers: standard (default), complex.

Generated layout:

.specs/features/<slug>/
├── spec.md
├── context.md
├── plan.md
├── tasks.md
└── validation.md

Scaffolded specs use confidence markers ([CONFIRMED], [INFERRED], [NEEDS CLARIFICATION], [DECISION REQUIRED]). A --description value is recorded as [CONFIRMED] overview text. The CLI does not invent product requirements.

Create a quick task (non-interactive by default)

km-spec quick "Fix login validation"
km-spec quick "Fix login validation" --description "Reject expired sessions during login"
km-spec quick "Fix login validation" --interactive
km-spec quick "Fix login validation" --force

Generated layout:

.specs/quick/<slug>/
├── TASK.md
└── SUMMARY.md

Optional interview-style project docs

These commands still use interactive prompts when you want to fill files via the terminal:

km-spec project
km-spec roadmap
km-spec state
km-spec stack
km-spec architecture
km-spec structure
km-spec testing
km-spec integrations
km-spec concerns

Prefer editing the Markdown templates (or asking an agent to fill them) when automating.

Inspect and validate

km-spec status         # show status of spec files and layouts
km-spec doctor         # structural validation + lightweight warnings
km-spec version
km-spec help

doctor treats missing context.md / plan.md on older features as warnings (legacy layout), not hard errors. Legacy single-file quick tasks (.specs/quick/*.md) also produce warnings.

Generated structure

Running km-spec init creates:

.
├── AGENTS.md                          — Permanent agent rules
├── HARNESS.md                         — Execution lifecycle for agents
├── SDD.md                             — Full methodology reference
└── .specs/
    ├── project/
    │   ├── PROJECT.md                 — Vision, goals, users, constraints
    │   ├── ROADMAP.md                 — Milestones and feature priority
    │   └── STATE.md                   — Persistent session memory
    ├── codebase/
    │   └── CONVENTIONS.md             — Stack, architecture, testing, AI rules
    ├── features/
    │   └── [feature-name]/
    │       ├── spec.md                — Requirements and acceptance criteria
    │       ├── context.md             — Codebase context for the feature
    │       ├── plan.md                — Implementation plan (was design.md role)
    │       ├── tasks.md               — Atomic tasks with traceability
    │       └── validation.md          — Validation evidence ledger
    └── quick/
        └── [task-name]/
            ├── TASK.md                — Quick task definition
            └── SUMMARY.md             — Post-implementation summary

How AI agents use the specs

Read AGENTS.md first (mandatory reading order), then HARNESS.md for the lifecycle:

Discover → Read → Plan → Implement → Validate → Review → Report

Typical always-read set:

1. .specs/project/STATE.md
2. .specs/project/PROJECT.md
3. .specs/codebase/CONVENTIONS.md
4. HARNESS.md
5. Current feature or quick-task files only

For Claude Code, you can add:

# Development Guide
This project uses Spec Driven Development. See `AGENTS.md` and `HARNESS.md`.
Always start a session by reading `.specs/project/STATE.md`.

Migration notes (0.1.x → 0.2.0)

Breaking / behavior changes for new scaffolds:

| Area | 0.1.x | 0.2.0 | |------|-------|-------| | Feature create | Interactive prompts by default | Non-interactive by default; rich templates | | Feature files | spec.md, tasks.md, validation.md | + context.md, plan.md | | Quick create | Interactive; single .md file | Non-interactive; quick/<slug>/TASK.md + SUMMARY.md | | Agent docs | AGENTS.md only | + HARNESS.md | | Planning artifact | (docs said design.md) | Canonical plan.md |

Compatibility:

• Existing files are never overwritten without --force.
• init still skips existing files unless --force.
• doctor accepts legacy feature layouts (warns on missing context.md / plan.md).
• Legacy .specs/quick/*.md files produce warnings only.
• No automatic migration is performed. Re-scaffold only with --force (destructive for that feature/quick directory).

To adopt 0.2 agent docs in an existing repo without wiping specs:

1. Copy HARNESS.md from the package templates (or re-run init and keep skips).
2. Replace AGENTS.md manually if you want the new rules (or init --force only if you accept overwriting root agent docs).

How to use with different stacks

KM SDD generates only Markdown files. It never modifies source code, package managers, frameworks, or runtimes. It works with any stack.

cd my-app
km-spec init
km-spec feature "User Registration" --description "Email signup and verification"

Fill CONVENTIONS.md (manually or via optional km-spec stack interview) so agents know language, test commands, and layout.

How CONVENTIONS.md consolidates technical context

Instead of creating separate files like STACK.md, ARCHITECTURE.md, or TESTING.md, KM SDD consolidates everything into a single file:

.specs/codebase/CONVENTIONS.md

This file has 9 sections, each updated by a dedicated CLI command:

| Section | Command | |---------|---------| | 1. Technical Context | km-spec stack | | 2. Architecture | km-spec architecture | | 3. Project Structure | km-spec structure | | 4. Coding Standards | (edit manually) | | 5. Testing | km-spec testing | | 6. Integrations | km-spec integrations | | 7. Concerns | km-spec concerns | | 8. AI Rules | (pre-filled by init) | | 9. Optional Expansion | (reference only) |

If one section becomes too large, it can optionally be extracted to a dedicated file such as .specs/codebase/ARCHITECTURE.md. These expansion files are never generated by default.

Local test commands

chmod +x bin/km-spec
npm test
npm pack --dry-run

License

MIT