km-spec-driven-development 0.1.0 → 0.2.0

package/README.md

@@ -11,6 +11,8 @@
                          |_|
 ```
 
+**Version:** 0.2.0
+
 ---
 
 ## What is KM Spec Driven Development?
@@ -69,44 +71,85 @@ km-spec <command> [options]
 
 ```bash
 km-spec init
-km-spec init --force   # overwrite existing files
+km-spec init --force   # overwrite existing scaffold files
 ```
 
-### Fill in project context
+Creates (among other files): `AGENTS.md`, `HARNESS.md`, `SDD.md`, and the `.specs/` tree.
+
+### Create a feature (non-interactive by default)
 
 ```bash
-km-spec project        # configure PROJECT.md
-km-spec roadmap        # configure ROADMAP.md
-km-spec state          # update STATE.md with session notes
+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
 ```
 
-### Document the technical stack
+**Default is non-interactive.** The CLI does not wait for stdin unless `--interactive` is passed.
 
-```bash
-km-spec stack          # language, framework, runtime, database
-km-spec architecture   # modules, data flow, patterns
-km-spec structure      # folder layout and file placement rules
-km-spec testing        # test framework, patterns, validation gates
-km-spec integrations   # external APIs, SDKs, webhooks
-km-spec concerns       # risks, tech debt, fragile areas
+Supported tiers: `standard` (default), `complex`.
+
+Generated layout:
+
+```text
+.specs/features/<slug>/
+├── spec.md
+├── context.md
+├── plan.md
+├── tasks.md
+└── validation.md
 ```
 
-### Create feature specs and quick tasks
+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)
 
 ```bash
-km-spec feature "User Authentication"
-km-spec feature "User Authentication" --force
 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:
+
+```text
+.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:
+
+```bash
+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
 
 ```bash
-km-spec status         # show status of all spec files
-km-spec doctor         # validate the full SDD setup
+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
@@ -115,7 +158,8 @@ Running `km-spec init` creates:
 
 ```txt
 .
-├── AGENTS.md                          — AI agent operating instructions
+├── AGENTS.md                          — Permanent agent rules
+├── HARNESS.md                         — Execution lifecycle for agents
 ├── SDD.md                             — Full methodology reference
 └── .specs/
     ├── project/
@@ -127,81 +171,81 @@ Running `km-spec init` creates:
     ├── 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
+    │       └── validation.md          — Validation evidence ledger
     └── quick/
-        └── [task-name].md             — Quick tasks and bug fixes
+        └── [task-name]/
+            ├── TASK.md                — Quick task definition
+            └── SUMMARY.md             — Post-implementation summary
 ```
 
 ---
 
-## How to use with different stacks
+## How AI agents use the specs
 
-KM SDD generates only Markdown files. It never modifies source code, package managers, frameworks, or runtimes. It works with any stack.
+Read **`AGENTS.md`** first (mandatory reading order), then **`HARNESS.md`** for the lifecycle:
 
-### PHP / Laravel
+`Discover → Read → Plan → Implement → Validate → Review → Report`
 
-```bash
-cd my-laravel-app
-km-spec init
-km-spec stack      # Language: PHP, Framework: Laravel, ...
-km-spec feature "User Registration"
-```
+Typical always-read set:
 
-### Python / Django / FastAPI
+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
 
-```bash
-cd my-python-app
-km-spec init
-km-spec stack      # Language: Python, Framework: FastAPI, ...
-km-spec feature "REST API Endpoints"
+For Claude Code, you can add:
+
+```markdown
+# Development Guide
+This project uses Spec Driven Development. See `AGENTS.md` and `HARNESS.md`.
+Always start a session by reading `.specs/project/STATE.md`.
 ```
 
-### Node.js / Express / NestJS
+---
 
-```bash
-cd my-node-app
-km-spec init
-km-spec stack      # Language: TypeScript, Runtime: Node.js, ...
-km-spec feature "Auth Middleware"
-```
+## Migration notes (0.1.x → 0.2.0)
 
-### Java / Spring
+Breaking / behavior changes for **new** scaffolds:
 
-```bash
-cd my-spring-app
-km-spec init
-km-spec stack      # Language: Java, Framework: Spring Boot, ...
-km-spec feature "Payment Service"
-```
+| 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`** |
 
-### Android / Kotlin
+**Compatibility:**
 
-```bash
-cd my-android-app
-km-spec init
-km-spec stack      # Language: Kotlin, Framework: Android SDK, ...
-km-spec feature "Push Notifications"
-```
+- 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).
 
-### Go
+To adopt 0.2 agent docs in an existing repo without wiping specs:
 
-```bash
-cd my-go-app
-km-spec init
-km-spec stack      # Language: Go, Runtime: Go 1.22, ...
-km-spec feature "gRPC Service"
-```
+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
 
-### .NET / C#
+KM SDD generates only Markdown files. It never modifies source code, package managers, frameworks, or runtimes. It works with any stack.
 
 ```bash
-cd my-dotnet-app
+cd my-app
 km-spec init
-km-spec stack      # Language: C#, Framework: ASP.NET Core, ...
-km-spec feature "Background Job Service"
+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
@@ -230,49 +274,12 @@ If one section becomes too large, it can optionally be extracted to a dedicated
 
 ---
 
-## How AI agents use the specs
-
-The `AGENTS.md` file at the project root instructs AI agents to read three files before doing any work:
-
-1. `.specs/project/STATE.md` — current project state and last session notes
-2. `.specs/project/PROJECT.md` — project goals, users, and constraints
-3. `.specs/codebase/CONVENTIONS.md` — technical rules for every line of code
-
-For Claude Code, add this to your `CLAUDE.md`:
-
-```markdown
-# Development Guide
-This project uses Spec Driven Development. See `SDD.md` for the full methodology.
-
-Always start a session by reading `.specs/project/STATE.md`.
-All work follows the AI Development Harness in `SDD.md` Section 7.
-```
-
----
-
 ## Local test commands
 
 ```bash
 chmod +x bin/km-spec
-npm link
-km-spec
-km-spec help
-km-spec init
-km-spec project
-km-spec stack
-km-spec feature "User Authentication"
-km-spec quick "Fix login validation"
-km-spec status
-km-spec doctor
-```
-
----
-
-## Publish to npm
-
-```bash
-npm login
-npm publish
+npm test
+npm pack --dry-run
 ```
 
 ---