km-spec-driven-development 0.1.0

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+<<<<<<< HEAD
+Copyright (c) 2026 Dionatan Melo
+=======
+Copyright (c) 2026 KM Spec Driven Development
+>>>>>>> 727b0ce (Refactor code structure for improved readability and maintainability)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,282 @@
+# KM Spec Driven Development
+
+> A lightweight Spec Driven Development CLI for AI-assisted software projects.
+
+```
+ _  __ __  __      ____
+| |/ /|  \/  |    / ___| _ __   ___  ___
+| ' / | |\/| |____\___ \| '_ \ / _ \/ __|
+| . \ | |  | |_____|__) | |_) |  __/ (__
+|_|\_\|_|  |_|    |____/| .__/ \___|\___|
+                         |_|
+```
+
+---
+
+## 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
+
+```bash
+npm install -g km-spec-driven-development
+```
+
+### Use without installing (npx)
+
+```bash
+npx km-spec-driven-development init
+```
+
+### Local development
+
+```bash
+git clone <repo>
+cd km-spec-driven-development
+chmod +x bin/km-spec
+npm link
+```
+
+---
+
+## Usage
+
+```bash
+km-spec <command> [options]
+```
+
+### Initialize a new project
+
+```bash
+km-spec init
+km-spec init --force   # overwrite existing files
+```
+
+### Fill in project context
+
+```bash
+km-spec project        # configure PROJECT.md
+km-spec roadmap        # configure ROADMAP.md
+km-spec state          # update STATE.md with session notes
+```
+
+### Document the technical stack
+
+```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
+```
+
+### Create feature specs and quick tasks
+
+```bash
+km-spec feature "User Authentication"
+km-spec feature "User Authentication" --force
+km-spec quick "Fix login validation"
+km-spec quick "Fix login validation" --force
+```
+
+### Inspect and validate
+
+```bash
+km-spec status         # show status of all spec files
+km-spec doctor         # validate the full SDD setup
+```
+
+---
+
+## Generated structure
+
+Running `km-spec init` creates:
+
+```txt
+.
+├── AGENTS.md                          — AI agent operating instructions
+├── 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
+    │       ├── tasks.md               — Atomic tasks with traceability
+    │       └── validation.md          — Validation evidence
+    └── quick/
+        └── [task-name].md             — Quick tasks and bug fixes
+```
+
+---
+
+## 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.
+
+### PHP / Laravel
+
+```bash
+cd my-laravel-app
+km-spec init
+km-spec stack      # Language: PHP, Framework: Laravel, ...
+km-spec feature "User Registration"
+```
+
+### Python / Django / FastAPI
+
+```bash
+cd my-python-app
+km-spec init
+km-spec stack      # Language: Python, Framework: FastAPI, ...
+km-spec feature "REST API Endpoints"
+```
+
+### 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"
+```
+
+### Java / Spring
+
+```bash
+cd my-spring-app
+km-spec init
+km-spec stack      # Language: Java, Framework: Spring Boot, ...
+km-spec feature "Payment Service"
+```
+
+### Android / Kotlin
+
+```bash
+cd my-android-app
+km-spec init
+km-spec stack      # Language: Kotlin, Framework: Android SDK, ...
+km-spec feature "Push Notifications"
+```
+
+### Go
+
+```bash
+cd my-go-app
+km-spec init
+km-spec stack      # Language: Go, Runtime: Go 1.22, ...
+km-spec feature "gRPC Service"
+```
+
+### .NET / C#
+
+```bash
+cd my-dotnet-app
+km-spec init
+km-spec stack      # Language: C#, Framework: ASP.NET Core, ...
+km-spec feature "Background Job Service"
+```
+
+---
+
+## 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:
+
+```txt
+.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.
+
+---
+
+## 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
+```
+
+---
+
+## License
+
+MIT