@nolrm/contextkit 0.18.0 → 0.19.0

package/README.md

@@ -157,7 +157,8 @@ ContextKit installs reusable slash commands for supported platforms:
 | `/doc-arch`            | Generate architecture docs — stack-aware (Level 1). Output: `docs/<topic>.md`, or `docs/architecture.md` if no topic given. Pass a topic name, PR number, or leave blank to infer from branch. |
 | `/doc-feature`         | Generate feature-level docs (`docs/features/<name>.md`) — stack-aware (Level 2)                                                 |
 | `/doc-component`       | Generate component-level docs colocated with the target file — stack-aware (Level 3)                                            |
-| `/spec`                | Write a component spec (MD-first) before any code is created                                                                    |
+| `/spec`                | Turn a product overview into an implementation-ready spec — UX flows, DB schema, API contracts, and phased build plan           |
+| `/spec-component`      | Write a component spec (MD-first) before any code is created                                                                    |
 | `/squad`               | Kick off a squad task — one task or many (auto-detects batch mode). Pushes back with clarifying questions if the task is vague. |
 | `/squad-architect`     | Design the technical plan from the PO spec                                                                                      |
 | `/squad-dev`           | Implement code following the architect plan                                                                                     |
@@ -269,6 +270,57 @@ If you have a screenshot, mockup, or design image relevant to the task, paste or
 
 ---
 
+## Spec Pipeline
+
+The spec pipeline turns a high-level product overview into an implementation-ready spec. It runs before the squad — producing the UX flows, DB schema, API contracts, and phased build plan that make stories possible.
+
+```bash
+/spec          # Start or continue — picks up the next unchecked scope automatically
+/spec 02-jobs  # Run a specific scope by name
+/spec --redo 01-identity-auth  # Re-run a completed scope from scratch
+```
+
+### How It Works
+
+`/spec` reads a product overview file (`PROJECT_OVERVIEW.md`, `OVERVIEW.md`, `BRIEF.md`, or any `.md` file you point it to) and runs a multi-round pipeline for each scope:
+
+| Round | Who runs | What happens |
+|-------|----------|-------------|
+| 0 — Brief | CTO | Reads the overview, defines scope boundaries, writes a brief all agents share |
+| 1 — Domain experts | UX, Data, Systems, Planner (parallel) | Each produces their section independently from the brief |
+| 2 — Challenges | CTO | Reads all four sections, writes challenges — gaps, contradictions, missing decisions |
+| 3 — Revisions | UX, Data, Systems, Planner (parallel) | Each addresses the CTO's challenges, flags unresolvable items as OPEN DECISIONs |
+| Final — Author | CTO | Resolves open decisions, writes the unified `SPEC.md` |
+
+### Output Structure
+
+Each scope produces a folder with all working artifacts and a final `SPEC.md`:
+
+```
+spec/
+  PROGRESS.md              ← scope checklist, updated after each run
+  INDEX.md                 ← master TOC linking all SPEC.md files
+
+  01-identity-auth/
+    00-brief.md            ← CTO's scoping brief
+    01-ux.md               ← UX flows and screens
+    02-data.md             ← DB schema and relationships
+    03-systems.md          ← API contracts and services
+    04-plan.md             ← build phases and stories
+    05-challenges.md       ← CTO's Round 2 challenges
+    SPEC.md                ← final unified spec for this scope
+```
+
+Run `/spec` once per scope. Each run appends to `spec/INDEX.md`. When all scopes are done, feed individual `SPEC.md` files into `/squad` as implementation tasks.
+
+### First Run
+
+On the first run, the CTO reads the entire overview and identifies all logical scopes — ordering them by dependency (identity before marketplace, invoicing before tax). This produces `spec/PROGRESS.md` which acts as the checklist for all subsequent runs.
+
+If no standard overview file is found, `/spec` lists all `.md` files in the directory and asks you to pick.
+
+---
+
 ## Hooks & Quality Gates
 
 ContextKit installs two kinds of hooks. **Git hooks** (pre-push, commit-msg) enforce quality at push time for the whole team. For **Claude Code** installs, a **PostToolUse hook** is also written to `.claude/settings.json` — it runs format+lint after every file edit in a Claude Code session, catching failures immediately rather than at push time.

package/lib/commands/install.js

@@ -928,8 +928,8 @@ Any design decisions, trade-offs, or open questions to resolve before coding.
         '.contextkit/commands/dev/create-component.md'
       );
       await this.downloadManager.downloadFile(
-        `${this.repoUrl}/commands/dev/spec.md`,
-        '.contextkit/commands/dev/spec.md'
+        `${this.repoUrl}/commands/dev/spec-component.md`,
+        '.contextkit/commands/dev/spec-component.md'
       );
 
       // Download squad commands
@@ -982,6 +982,44 @@ Any design decisions, trade-offs, or open questions to resolve before coding.
         '.contextkit/commands/dev/health-check.md'
       );
 
+      // Download spec pipeline commands
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/spec/spec.md`,
+        '.contextkit/commands/spec/spec.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/spec/spec-init.md`,
+        '.contextkit/commands/spec/spec-init.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/spec/spec-brief.md`,
+        '.contextkit/commands/spec/spec-brief.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/spec/spec-ux.md`,
+        '.contextkit/commands/spec/spec-ux.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/spec/spec-data.md`,
+        '.contextkit/commands/spec/spec-data.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/spec/spec-systems.md`,
+        '.contextkit/commands/spec/spec-systems.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/spec/spec-planner.md`,
+        '.contextkit/commands/spec/spec-planner.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/spec/spec-challenge.md`,
+        '.contextkit/commands/spec/spec-challenge.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/spec/spec-author.md`,
+        '.contextkit/commands/spec/spec-author.md'
+      );
+
       // Download doc family commands
       await this.downloadManager.downloadFile(
         `${this.repoUrl}/commands/docs/doc-arch.md`,

package/lib/commands/update.js

@@ -292,8 +292,8 @@ class UpdateCommand {
         '.contextkit/commands/dev/create-component.md'
       );
       await this.downloadManager.downloadFile(
-        `${this.repoUrl}/commands/dev/spec.md`,
-        '.contextkit/commands/dev/spec.md'
+        `${this.repoUrl}/commands/dev/spec-component.md`,
+        '.contextkit/commands/dev/spec-component.md'
       );
 
       // Download squad commands
@@ -346,6 +346,44 @@ class UpdateCommand {
         '.contextkit/commands/dev/health-check.md'
       );
 
+      // Download spec pipeline commands
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/spec/spec.md`,
+        '.contextkit/commands/spec/spec.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/spec/spec-init.md`,
+        '.contextkit/commands/spec/spec-init.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/spec/spec-brief.md`,
+        '.contextkit/commands/spec/spec-brief.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/spec/spec-ux.md`,
+        '.contextkit/commands/spec/spec-ux.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/spec/spec-data.md`,
+        '.contextkit/commands/spec/spec-data.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/spec/spec-systems.md`,
+        '.contextkit/commands/spec/spec-systems.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/spec/spec-planner.md`,
+        '.contextkit/commands/spec/spec-planner.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/spec/spec-challenge.md`,
+        '.contextkit/commands/spec/spec-challenge.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/spec/spec-author.md`,
+        '.contextkit/commands/spec/spec-author.md'
+      );
+
       // Download doc family commands
       await this.downloadManager.downloadFile(
         `${this.repoUrl}/commands/docs/doc-arch.md`,

package/lib/integrations/claude-integration.js

@@ -28,6 +28,7 @@ class ClaudeIntegration extends BaseIntegration {
       '.claude/skills/squad-doc/SKILL.md',
       '.claude/skills/squad-go/SKILL.md',
       '.claude/skills/spec/SKILL.md',
+      '.claude/skills/spec-component/SKILL.md',
       '.claude/skills/ck/SKILL.md',
       '.claude/skills/doc-arch/SKILL.md',
       '.claude/skills/doc-feature/SKILL.md',
@@ -312,7 +313,7 @@ Add inline docs, README sections, and usage examples for the specified code.
     );
 
     await this.writeGeneratedFile(
-      '.claude/skills/spec/SKILL.md',
+      '.claude/skills/spec-component/SKILL.md',
       `---
 description: Write a component spec (MD-first) before coding begins
 argument-hint: "<component or feature name>"
@@ -320,12 +321,28 @@ allowed-tools: Read, Write, Glob, Grep
 effort: normal
 ---
 
-Read \`.contextkit/commands/dev/spec.md\` and execute the spec workflow.
+Read \`.contextkit/commands/dev/spec-component.md\` and execute the component spec workflow.
 
 Write a component spec (MD-first) before any code is created. Scaffold the spec file colocated with the component and wait for review before coding begins.
 `
     );
 
+    await this.writeGeneratedFile(
+      '.claude/skills/spec/SKILL.md',
+      `---
+description: Turn a product overview into an implementation-ready spec — UX flows, DB schema, API contracts, and build plan
+argument-hint: "[scope-name] | --redo <scope> | --reset"
+allowed-tools: Read, Write, Glob, Grep, Task
+effort: high
+context: fork
+---
+
+Read \`.contextkit/commands/spec/spec.md\` and execute the spec pipeline workflow.
+
+Reads a product overview file, breaks it into logical scopes, and runs a multi-round pipeline for each scope: CTO briefs → 4 domain experts in parallel → CTO challenges → domain revisions → CTO authors final SPEC.md. Produces a structured \`spec/\` folder. Run once per scope — \`/spec\` picks up where you left off.
+`
+    );
+
     await this.writeGeneratedFile(
       '.claude/skills/ck/SKILL.md',
       `---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nolrm/contextkit",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "ContextKit - Context Engineering for AI Development. Provide rich context to AI through structured MD files with standards, code guides, and documentation. Works with Cursor, Claude, Aider, VS Code Copilot, and more.",
   "main": "lib/index.js",
   "bin": {