@nolrm/contextkit 0.17.0 → 0.19.0

package/README.md

@@ -157,14 +157,16 @@ 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                                                                                     |
 | `/squad-test`          | Classify test levels, write and run tests against acceptance criteria                                                           |
 | `/squad-review`        | Review the full pipeline and give a verdict                                                                                     |
 | `/squad-doc`           | Create companion `.md` files for new/modified code after review passes                                                          |
-| `/squad-auto`          | Auto-run the full pipeline after kickoff (recommended, sequential)                                                              |
+| `/squad-go`            | Extract tasks from the current conversation and run the full pipeline immediately — no second command needed                     |
+| `/squad-auto`          | Auto-run the full pipeline after `/squad` kickoff (sequential)                                                                  |
 | `/squad-auto-parallel`    | Auto-run the pipeline in parallel using Claude Code agents (Claude Code only)                                                   |
 | `/ck`                     | Health check — verify setup, standards, and integrations                                                                        |
 | `/agent-push-checklist`   | Pre-push quality checklist for agents to self-check before `git push`                                                           |
@@ -195,12 +197,22 @@ The squad workflow turns a single AI session into a structured multi-role pipeli
 | 5    | Reviewer      | `/squad-review`    | Reviews everything and gives a PASS or NEEDS-WORK verdict                                                                                                                                                      |
 | 6    | Doc Writer    | `/squad-doc`       | Creates companion `.md` files for every new/modified code file                                                                                                                                                 |
 
+### Express Flow (conversation-first)
+
+After discussing a feature or fix with your AI tool, run a single command to go hands-free:
+
+```bash
+/squad-go
+# Reads tasks from the current conversation, confirms the list, writes specs,
+# and immediately runs architect → dev → test → review → doc — no second command needed
+```
+
 ### Single-Task Flow
 
 ```bash
 /squad "add dark mode support"   # PO writes the spec
 
-/squad-auto                      # Auto-runs architect → dev → test → review → doc (recommended)
+/squad-auto                      # Auto-runs architect → dev → test → review → doc
 # — or step through manually —
 /squad-architect                 # Architect designs the plan
 /squad-dev                       # Dev implements the code
@@ -258,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
@@ -973,11 +973,53 @@ Any design decisions, trade-offs, or open questions to resolve before coding.
         `${this.repoUrl}/commands/squad/squad-ci.md`,
         '.contextkit/commands/squad/squad-ci.md'
       );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/squad/squad-go.md`,
+        '.contextkit/commands/squad/squad-go.md'
+      );
       await this.downloadManager.downloadFile(
         `${this.repoUrl}/commands/dev/health-check.md`,
         '.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
@@ -337,11 +337,53 @@ class UpdateCommand {
         `${this.repoUrl}/commands/squad/squad-ci.md`,
         '.contextkit/commands/squad/squad-ci.md'
       );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/squad/squad-go.md`,
+        '.contextkit/commands/squad/squad-go.md'
+      );
       await this.downloadManager.downloadFile(
         `${this.repoUrl}/commands/dev/health-check.md`,
         '.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

@@ -26,7 +26,9 @@ class ClaudeIntegration extends BaseIntegration {
       '.claude/skills/squad-auto-parallel/SKILL.md',
       '.claude/skills/squad-reset/SKILL.md',
       '.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',
@@ -311,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>"
@@ -319,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',
       `---
@@ -471,6 +489,24 @@ After review passes, create or update companion .md files for every new/modified
 `
     );
 
+    await this.writeGeneratedFile(
+      '.claude/skills/squad-go/SKILL.md',
+      `---
+description: Extract tasks from conversation and run the full pipeline immediately — no checkpoint pause
+argument-hint: '"<optional task override>"'
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash
+effort: high
+context: fork
+---
+
+Read \`.contextkit/commands/squad/squad-go.md\` and execute the express pipeline workflow.
+
+Reads tasks from the current conversation, writes PO specs, and immediately runs architect → dev → test → review → doc. No checkpoint pause — single invocation, hands-free.
+
+Use \`/squad\` instead when you want to review specs before execution starts.
+`
+    );
+
     // Doc family skills
     await this.writeGeneratedFile(
       '.claude/skills/doc-arch/SKILL.md',
@@ -590,6 +626,11 @@ Load and apply the project's ContextKit standards before taking action in an age
     console.log(chalk.dim('    /squad-dev         — Implement the code'));
     console.log(chalk.dim('    /squad-test        — Write and run tests'));
     console.log(chalk.dim('    /squad-review      — Review and write verdict'));
+    console.log(
+      chalk.dim(
+        '    /squad-go               — Extract tasks from conversation and run full pipeline'
+      )
+    );
     console.log(chalk.dim('    /squad-auto             — Auto-run full pipeline (recommended)'));
     console.log(
       chalk.dim('    /squad-auto-parallel    — Auto-run pipeline in parallel (batch, fastest)')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nolrm/contextkit",
-  "version": "0.17.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": {