km-spec-driven-development 0.1.0

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "km-spec-driven-development",
+  "version": "0.1.0",
+  "description": "A lightweight Spec Driven Development CLI for AI-assisted software projects",
+  "bin": {
+    "km-spec": "bin/km-spec"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "spec-driven-development",
+    "sdd",
+    "ai-assisted-development",
+    "bash",
+    "cli",
+    "claude-code",
+    "codex",
+    "cursor"
+  ],
+  "license": "MIT"
+}

package/templates/.specs/codebase/CONVENTIONS.md

@@ -0,0 +1,125 @@
+# Codebase Conventions
+
+## 1. Technical Context
+
+Describe the language, framework, runtime, package manager, database, infrastructure, and main tools used by the project.
+
+Suggested fields:
+
+- Language:
+- Framework:
+- Runtime:
+- Package manager:
+- Database:
+- Main libraries:
+- Deployment:
+- CI/CD:
+
+## 2. Architecture
+
+Describe the general architecture, layers, modules, data flow, and important technical decisions.
+
+Include:
+
+- Main modules:
+- Data flow:
+- Architectural patterns:
+- Important decisions:
+
+## 3. Project Structure
+
+Explain the project folder structure and where new files should be created.
+
+Example:
+
+```txt
+src/
+├── ...
+```
+
+Rules:
+
+- [Where API files go]
+- [Where components go]
+- [Where services go]
+- [Where tests go]
+
+## 4. Coding Standards
+
+Define naming conventions, import organization, error handling, logging, environment variables, and coding style.
+
+Include:
+
+- Naming:
+- Imports:
+- Error handling:
+- Logging:
+- Environment variables:
+- Comments:
+- Formatting:
+
+## 5. Testing
+
+Describe how tests should be written, where they should live, which commands should be run, and which validation gates are required.
+
+Include:
+
+- Test framework:
+- Test file pattern:
+- Unit test rules:
+- Integration test rules:
+- E2E test rules:
+- Required commands:
+
+Validation gates:
+
+- [ ] Build
+- [ ] Lint
+- [ ] Typecheck
+- [ ] Tests
+- [ ] Manual check when needed
+
+## 6. Integrations
+
+List external services, APIs, SDKs, webhooks, authentication methods, and integration concerns.
+
+Include:
+
+- Service name:
+- Purpose:
+- Auth method:
+- Environment variables:
+- Risks or limits:
+
+## 7. Concerns
+
+List technical risks, tech debt, fragile areas, limitations, and parts of the codebase that agents should modify carefully.
+
+Include:
+
+- Known risks:
+- Technical debt:
+- Fragile areas:
+- Low test coverage areas:
+- Deprecated patterns:
+
+## 8. AI Rules
+
+- Do not invent files, APIs, functions, or behavior.
+- Read existing code before modifying it.
+- Follow existing project patterns.
+- Do not refactor unrelated code.
+- Keep changes small and reviewable.
+- Validate before marking work as done.
+- Update `.specs/project/STATE.md` at the end of the session.
+
+## 9. Optional Expansion
+
+If one section becomes too large, it may be extracted into a dedicated optional file, such as:
+
+- `.specs/codebase/ARCHITECTURE.md`
+- `.specs/codebase/TESTING.md`
+- `.specs/codebase/INTEGRATIONS.md`
+- `.specs/codebase/CONCERNS.md`
+
+These files are optional and should not be generated by default.

package/templates/.specs/project/PROJECT.md

@@ -0,0 +1,36 @@
+# Project
+
+## Name
+
+[Project name]
+
+## One-Line Description
+
+[Describe the project in one sentence.]
+
+## Problem
+
+[What problem does this project solve?]
+
+## Target Users
+
+- [User type 1]
+- [User type 2]
+
+## Goals
+
+- [Goal 1]
+- [Goal 2]
+- [Goal 3]
+
+## Non-Negotiables
+
+- [Security, performance, compliance, UX, business, or technical constraint]
+
+## Out of Scope
+
+- [What should not be built now]
+
+## Key Terms
+
+- **[Term]:** [Definition]

package/templates/.specs/project/ROADMAP.md

@@ -0,0 +1,26 @@
+# Roadmap
+
+## Current Phase
+
+[Discovery | Setup | MVP | Active Development | Stabilization | Maintenance]
+
+## Milestones
+
+### Milestone 1 — [Name]
+
+**Status:** Planned
+**Goal:** [What this milestone should achieve]
+
+#### Features
+
+- [ ] [Feature 1]
+- [ ] [Feature 2]
+- [ ] [Feature 3]
+
+## Backlog
+
+- [ ] [Backlog item]
+
+## Deferred
+
+- [ ] [Deferred idea or feature]

package/templates/.specs/project/STATE.md

@@ -0,0 +1,37 @@
+# Project State
+
+## Last Updated
+
+[YYYY-MM-DD HH:MM]
+
+## Current Focus
+
+[Describe what is being worked on now.]
+
+## Last Completed Task
+
+None.
+
+## Current Task
+
+None.
+
+## Suggested Next Steps
+
+1. Complete `.specs/project/PROJECT.md`.
+2. Complete `.specs/codebase/CONVENTIONS.md`.
+3. Create the first feature spec under `.specs/features/[feature-name]/`.
+
+## Decisions
+
+No decisions recorded yet.
+
+## Blockers
+
+No blockers.
+
+## Notes for Future Agents
+
+- Always read this file before starting work.
+- Always update this file at the end of a session.
+- Record decisions, blockers, deviations, and next steps here.

package/templates/AGENTS.md

@@ -0,0 +1,42 @@
+# Agent Instructions
+
+This project uses Spec Driven Development.
+
+## Always Read First
+
+Before changing code, always read:
+
+1. `.specs/project/STATE.md`
+2. `.specs/project/PROJECT.md`
+3. `.specs/codebase/CONVENTIONS.md`
+
+For feature work, also read:
+
+- `.specs/features/[feature]/spec.md`
+- `.specs/features/[feature]/tasks.md`
+- `.specs/features/[feature]/validation.md`
+
+## Rules
+
+- Do not invent files, APIs, functions, or behavior.
+- Read existing code before modifying it.
+- Implement only the current task scope.
+- Keep changes small and reviewable.
+- Do not refactor unrelated code.
+- Follow `.specs/codebase/CONVENTIONS.md`.
+- Update task status after implementation.
+- Run validation before marking work as done.
+- Record validation evidence.
+- Update `.specs/project/STATE.md` at the end of the session.
+
+## Done Means
+
+A task is only complete when:
+
+- Build passes.
+- Lint passes, if available.
+- Typecheck passes, if available.
+- Tests pass, if available.
+- Acceptance criteria are verified.
+- Validation result is recorded.
+- Project state is updated.