feat(spec): add MD-first development pattern with /spec command (0.12.8)

  Introduces a 3-level spec-before-code workflow: Architecture → Page → Component.
  Each component gets a colocated .md spec written before any code is created.

  - Add commands/spec.md — new slash command to scaffold component specs
  - Add templates/component-spec.md — Level 3 spec template
  - Update commands/create-component.md — spec check/creation is now Step 1
  - Register /spec in Claude and Cursor integrations
  - Add docs/md-first page and sidebar entry
  - Add V1-PLAN.md with release roadmap to 1.0.0

Author: nolrm

README.md

@@ -165,6 +165,7 @@ ContextKit installs reusable slash commands for supported platforms:
 | `/refactor` | Refactor code with safety checks |
 | `/test` | Generate comprehensive tests |
 | `/doc` | Add documentation |
+| `/spec` | Write a component spec (MD-first) before any code is created |
 | `/squad` | Kick off a squad task — write the PO spec |
 | `/squad-architect` | Design the technical plan from the PO spec |
 | `/squad-dev` | Implement code following the architect plan |

V1-PLAN.md

@@ -0,0 +1,168 @@
+# ContextKit 1.0.0 — Release Plan
+
+> Honest baseline: **0.12.7 today**. Feature-complete, but test coverage is 27%, core UX has a mismatch, and the project doesn't dogfood itself. One focused sprint gets us there.
+
+---
+
+## Summary
+
+| Area | Status | Blocking 1.0? |
+|------|--------|---------------|
+| Core CLI (install, status, update) | ✅ Tested & stable | No |
+| Platform integrations (9 platforms) | ✅ Working | No |
+| Quality gates (7 languages) | ✅ Tested | No |
+| Squad workflow | ✅ Feature-complete, ❌ untested | Yes |
+| Command test coverage | ❌ 3/11 commands tested (27%) | Yes |
+| Analyze UX clarity | ❌ Behavior mismatch | Yes |
+| Project dogfooding | ❌ Own product files are placeholders | Yes |
+| API stability contract | ❌ Not documented | Yes |
+| Contributing guide | ❌ Missing | Yes |
+| MD-first pattern (3-level spec) | 🚧 Partial (templates + commands done) | Yes |
+
+---
+
+## 1. Test Coverage
+
+> **Goal:** Bring critical commands to tested. Not aiming for 100% — focus on the commands users actually run.
+
+### High Priority (user-facing commands)
+- [ ] `lib/commands/analyze.js` — test scope detection, monorepo detection, context loading, usage output
+- [ ] `lib/commands/pull.js` — test registry pull, version resolution, backup flag, overwrite behavior
+- [ ] `lib/commands/check.js` — test install detection, status reporting
+- [ ] `lib/commands/run.js` — test command routing and execution
+
+### Medium Priority
+- [ ] `lib/commands/ai.js` — test prompt construction, tool routing (aider, claude, gemini)
+- [ ] `lib/commands/dashboard.js` — test status rendering and data aggregation
+- [ ] `lib/commands/publish.js` — test package validation and registry write
+- [ ] `lib/commands/note.js` — test file append and corrections log format
+
+### Squad Workflow (integration-level)
+- [ ] Test manifest creation from `squad-batch` input (fresh start)
+- [ ] Test manifest append mode (existing manifest detected, numbering continues correctly)
+- [ ] Test `squad-run` phase routing based on manifest statuses
+- [ ] Test clarify status detection pauses the correct tasks
+- [ ] Test single handoff file creation from `squad` input
+
+---
+
+## 2. Analyze UX Clarity
+
+> **The mismatch:** Users run `ck analyze` expecting standards files to be generated. The CLI only detects project structure and prints instructions — the AI does the actual work. This surprises users.
+
+- [ ] Update the `ck analyze` terminal output to **explicitly state the handoff**: "Analysis complete. Now paste the above context into your AI tool, or run: `claude .contextkit/commands/analyze.md`"
+- [ ] Add a "Next step" callout box at the end of the analyze output (not buried in instructions)
+- [ ] Update README `ck analyze` section to clearly describe the two-stage process: CLI detects → AI generates
+- [ ] Update docs site quick-start page to reflect the two-stage flow
+- [ ] Consider adding `ck analyze --with-claude` / `--with-aider` flags that auto-invoke the detected AI tool (stretch goal — not blocking)
+
+---
+
+## 3. Project Dogfooding
+
+> **The credibility gap:** ContextKit's own `.contextkit/` is mostly placeholder. The tool that helps teams fill their context hasn't filled its own.
+
+### Product files
+- [ ] Fill `.contextkit/product/mission.md` — write actual ContextKit mission, users, problem, value
+- [ ] Fill `.contextkit/product/mission-lite.md` — condensed 2-3 sentence version for AI context
+- [ ] Fill `.contextkit/product/decisions.md` — document real architectural decisions made so far:
+  - Why markdown over a database
+  - Why AI-delegated analyze (not in-CLI generation)
+  - Why CommonJS over TypeScript
+  - Why platform bridge files vs single universal format
+- [ ] Fill `.contextkit/product/roadmap.md` — use this document as the source
+
+### Standards files (run `ck analyze` on itself)
+- [ ] Generate `.contextkit/standards/code-style.md` — Node.js/CommonJS, chalk, ora, inquirer patterns
+- [ ] Generate `.contextkit/standards/architecture.md` — command pattern, utils structure, integration pattern
+- [ ] Generate `.contextkit/standards/testing.md` — Jest, mock patterns, integration vs unit split
+- [ ] Generate `.contextkit/standards/workflows.md` — git flow, versioning, changelog discipline
+- [ ] Generate `.contextkit/standards/ai-guidelines.md` — ContextKit-specific AI behavior rules
+
+---
+
+## 4. API Stability Contract
+
+> **1.0.0 signals "the interface is locked."** Without documenting what's stable, users can't trust it.
+
+- [ ] Define and document the **stable public API surface** in README:
+  - CLI commands that won't be renamed or removed
+  - File paths that are guaranteed stable (`.contextkit/standards/`, `.contextkit/commands/`, handoff file schema)
+  - Config file schema (`config.yml`, `manifest.md` fields)
+- [ ] Add a **Breaking Changes policy** to README: breaking changes require a major bump, deprecated features get one release cycle warning
+- [ ] Document the **squad handoff file schema** as a stable format (fields: `task`, `status`, sections 1–5)
+- [ ] Document the **manifest.md schema** as stable (fields: `batch`, `total`, `checkpoint`, task list format)
+
+---
+
+## 5. Contributing Guide
+
+- [ ] Create `CONTRIBUTING.md` at the project root with:
+  - [ ] How to set up the dev environment
+  - [ ] How to run tests (`npm test`)
+  - [ ] How to add a new platform integration (the integration pattern)
+  - [ ] How to add a new command
+  - [ ] Commit message format (conventional commits — already enforced by hook)
+  - [ ] PR checklist (tests pass, changelog entry, version bump if needed)
+- [ ] Link `CONTRIBUTING.md` from README
+
+---
+
+## 6. MD-First Development Pattern
+
+> **The idea:** Before any component or feature is coded, a markdown spec must exist. This is the 3-level documentation hierarchy — Architecture → Project → Component — where specs drive implementation, not the other way around.
+
+### The 3 Levels (Option A: Colocated)
+
+| Level | Scope | Location |
+|-------|-------|----------|
+| **1. Architecture** | How projects connect | `.contextkit/standards/architecture.md` |
+| **2. Project** | What this project does, structure | `.contextkit/product/mission.md` + `context.md` |
+| **3. Component** | Individual component logic & responsibilities | `<ComponentName>/<ComponentName>.md` (colocated) |
+
+Level 3 example:
+```
+src/components/Button/
+  Button.md       ← spec (written first)
+  Button.tsx      ← code (written after spec)
+  Button.test.tsx
+```
+
+### Deliverables
+
+- [x] Create `templates/component-spec.md` — Level 3 spec template with Purpose, Responsibilities, Props/API, Logic & Behavior, Dependencies sections
+- [x] Create `commands/spec.md` — Standalone command to write a component spec before coding
+- [x] Update `commands/create-component.md` — Step 1 is now spec check/creation; code only after spec is confirmed
+- [ ] Document the 3-level pattern in `.contextkit/standards/architecture.md`
+- [ ] Add spec scanning to `ck analyze` — report which components have specs vs. missing
+
+---
+
+## 7. Polish & Loose Ends
+
+- [ ] **`ck pull` docs** — it's implemented and registered but not mentioned anywhere in the README CLI commands table. Add it.
+- [ ] **`squad-run-agents` scope** — currently undocumented that it's Claude Code-only. Add a note in the docs site squad page and in the command file itself.
+- [ ] **`vibe-kit` / `vk` aliases** — these legacy aliases are still in `package.json` bin. Decide: keep with deprecation notice or remove before 1.0.
+- [ ] **`nolrm-vibe-kit-0.1.2.tgz`** in the repo root — stale artifact, should be deleted or gitignored.
+- [ ] **`test-project/`** in the repo root — confirm it's gitignored and not shipping in the npm package.
+- [ ] **Node.js engine requirement** — `package.json` says `>=14.0.0` but codebase likely uses features requiring 16+. Verify and update if needed.
+
+---
+
+## 8. Version Milestones
+
+| Version | Focus | Done when |
+|---------|-------|-----------|
+| **0.13** | Test coverage + analyze UX | All high-priority tests written, analyze output updated |
+| **0.14** | Dogfooding + product files | All `.contextkit/product/` and standards filled |
+| **0.15** | API contract + contributing | README stability docs + CONTRIBUTING.md merged |
+| **0.16** | Polish sprint | All loose ends resolved, no known issues |
+| **1.0.0** | Release | All items above checked off |
+
+---
+
+## Done When
+
+1.0.0 ships when every checkbox above is checked. No partial credit.
+
+> Last updated: 2026-03-01 · Baseline: v0.12.7

__tests__/integrations/claude-integration.test.js

@@ -70,9 +70,9 @@ describe('ClaudeIntegration', () => {
     await integration.install();
 
     const commands = [
-      'analyze', 'review', 'fix', 'refactor', 'test', 'doc',
+      'analyze', 'review', 'fix', 'refactor', 'test', 'doc', 'spec',
       'squad', 'squad-architect', 'squad-dev', 'squad-test', 'squad-review',
-      'squad-batch', 'squad-run', 'ck',
+      'squad-batch', 'squad-run', 'squad-run-agents', 'ck',
     ];
     for (const cmd of commands) {
       const filePath = `.claude/commands/${cmd}.md`;

commands/create-component.md

@@ -1,14 +1,25 @@
 # Create Component
 
-Scaffold a new UI component with tests.
+Scaffold a new UI component with tests, following the MD-first pattern.
+
+**MD-first rule:** A spec file must exist (or be created now) before any code is written.
+The spec lives colocated with the component:
+```
+src/components/ComponentName/
+  ComponentName.md    ← spec (Level 3 doc)
+  ComponentName.tsx   ← implementation
+  ComponentName.test.tsx
+```
 
 ## What I'll Do
 
-1. Detect the project's UI framework and conventions
-2. Create the component file in the appropriate location
-3. Add typed props/interfaces
-4. Create a test file with numbered test cases
-5. Update exports if needed
+1. Check if `<ComponentName>/<ComponentName>.md` already exists
+2. If not — create the spec from `.contextkit/templates/component-spec.md` and present it for review
+3. Once spec is confirmed — detect the project's UI framework and conventions
+4. Scaffold the component file using the spec as the source of truth
+5. Add typed props/interfaces matching the spec's Props/API table
+6. Create a test file with numbered test cases covering the spec's Logic & Behavior
+7. Update exports if needed
 
 ## How to Use
 
@@ -20,13 +31,15 @@ Create a Modal component with title and children props
 
 ## Process
 
-1. **Detect patterns** — Scan existing components for conventions
-2. **Scaffold** — Create component matching project structure
-3. **Props** — Define typed interface for all inputs
-4. **Tests** — Add test file covering rendering and interactions
-5. **Exports** — Update barrel files or index if the project uses them
+1. **Spec check** — Look for `<ComponentName>/<ComponentName>.md`. If missing, draft it from template and wait for approval before continuing.
+2. **Detect patterns** — Scan existing components for conventions
+3. **Scaffold** — Create component matching project structure, using spec as source of truth
+4. **Props** — Define typed interface from spec's Props/API table
+5. **Tests** — Add test file covering the Logic & Behavior section of the spec
+6. **Exports** — Update barrel files or index if the project uses them
 
 ## Standards Applied
 
+- `.contextkit/standards/architecture.md` — 3-level MD-first pattern
 - `.contextkit/standards/code-style.md` — Coding conventions
 - `.contextkit/standards/testing.md` — Testing patterns

commands/spec.md

@@ -0,0 +1,41 @@
+# Spec
+
+Write a component spec (Level 3 of the MD-first pattern) before any code is written.
+
+The spec file lives **colocated** with the component it describes:
+```
+src/components/Button/
+  Button.md     ← spec (written first)
+  Button.tsx    ← code (written after spec is approved)
+```
+
+## What I'll Do
+
+1. Ask for the component name and a brief description of its purpose
+2. Scan existing components to understand project patterns and naming conventions
+3. Create `<ComponentName>/<ComponentName>.md` using `.contextkit/templates/component-spec.md`
+4. Fill in Purpose, Responsibilities, Props/API, Logic & Behavior, and Dependencies based on your description
+5. Present the spec for your review before any code is written
+
+## How to Use
+
+```
+Spec a Button component that handles primary and secondary variants with loading state
+Spec an AuthProvider that manages session state and exposes useAuth hook
+Spec a DataTable with sortable columns, pagination, and row selection
+```
+
+## Process
+
+1. **Understand** — Parse the description to identify purpose, props, and behavior
+2. **Scan** — Check existing components for similar patterns or dependencies
+3. **Draft spec** — Create `<ComponentName>/<ComponentName>.md` from template
+4. **Fill** — Populate all sections based on description and codebase context
+5. **Review** — Present the spec. Wait for approval before writing any code.
+
+Once the spec is approved, use `create-component` to scaffold the implementation.
+
+## Standards Applied
+
+- `.contextkit/standards/architecture.md` — 3-level MD-first pattern
+- `.contextkit/standards/code-style.md` — Naming conventions