@nolrm/contextkit 0.18.0 → 0.21.0

package/README.md

@@ -1,24 +1,31 @@
 # ContextKit
 
-> Context Engineering for AI Development
+> Context Engineering + Agentic AI Pipelines
 
-Give your AI assistants (Cursor, Claude, Copilot, Codex, OpenCode, Gemini, Aider, Continue, Windsurf) structured context through markdown files. ContextKit creates a knowledge base that ensures AI generates code matching your exact patterns, style, and architecture—no more hallucinated code or mismatched conventions.
+ContextKit gives your AI assistants (Cursor, Claude, Copilot, Codex, OpenCode, Gemini, Aider, Continue, Windsurf) structured context through markdown files—and gives you a multi-role autonomous pipeline (PO → Architect → Dev → Test → Review → Doc) to execute work with those same agents. The context layer is what keeps the pipeline grounded: agents read your standards, so they never hallucinate your conventions.
 
-ContextKit is a CLI tool that provides **context-engineering** capabilities by creating `.contextkit/` directories with project standards, guidelines, and patterns that AI assistants read automatically.
+ContextKit is a CLI tool with two capabilities: **context engineering** (`.contextkit/standards/` + platform bridge files so every AI tool reads your project conventions automatically) and **squad pipelines** (a six-role agentic workflow grounded by those same standards).
 
 **[Read the full documentation](https://contextkit-docs.vercel.app/)** · **[How context works](https://contextkit-docs.vercel.app/docs/how-context-works)**
 
 ## Why ContextKit?
 
-**The problem:** LLMs are great at syntax, not at _your_ conventions. Generic AI output requires manual fixes for style, structure, and architecture.
+**The problem:** LLMs are good at syntax, not at _your_ conventions — and multi-agent pipelines amplify that. An autonomous dev agent that doesn't know your architecture, naming, or testing patterns will produce code you have to fully rewrite.
 
-**The solution:** ContextKit provides your AI with:
+**The solution — two pillars that reinforce each other:**
 
-- **Glossary** of project terminology and domain-specific terms (e.g., your entity, feature, and module names)
-- **Standards** for code style, testing patterns, and architecture
-- **Templates** with canonical component shapes
+**Pillar 1: Context engineering**
+- **Glossary** — project terminology and domain-specific entity names
+- **Standards** — code style, testing patterns, architecture rules
+- **Templates** — canonical component shapes
+- **Platform bridges** — auto-generated `CLAUDE.md`, `AGENTS.md`, `.windsurfrules`, etc. so every AI tool reads the same context without manual setup
 
-Update `.md` files as your project evolves; the AI follows.
+**Pillar 2: Agentic squad pipeline**
+- A six-role pipeline (PO → Architect → Dev → Tester → Reviewer → Doc Writer) runs in a single AI session
+- Each role reads the context layer before acting — no hallucinated conventions
+- Run `/squad "add dark mode"` then `/squad-auto` and walk away
+
+Update your `.md` standards as your project evolves; every agent that runs after picks up the change automatically.
 
 ## Multi-Platform Support
 
@@ -111,7 +118,6 @@ Each platform generates bridge files that the AI tool auto-reads. If a bridge fi
 ```
 /analyze    # scan codebase and generate standards
 /review     # code review with checklist
-/fix        # diagnose and fix bugs
 ```
 
 **Claude Code** — `CLAUDE.md` uses `@` imports to auto-load all standards into context every session (no manual reads needed, saves tokens). Skills in `.claude/skills/`. Also writes a PostToolUse hook to `.claude/settings.json` that runs format+lint after every file edit — auto-detected for Node.js (npm/pnpm/yarn/bun), Go, and Python.
@@ -150,14 +156,14 @@ ContextKit installs reusable slash commands for supported platforms:
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
 | `/analyze`             | Scan codebase and generate standards content                                                                                    |
 | `/review`              | Code review with checklist                                                                                                      |
-| `/fix`                 | Diagnose and fix bugs                                                                                                           |
 | `/refactor`            | Refactor code with safety checks                                                                                                |
 | `/test`                | Generate comprehensive tests                                                                                                    |
 | `/doc`                 | Add documentation                                                                                                               |
 | `/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 +275,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

@@ -899,10 +899,6 @@ Any design decisions, trade-offs, or open questions to resolve before coding.
         `${this.repoUrl}/commands/dev/review.md`,
         '.contextkit/commands/dev/review.md'
       );
-      await this.downloadManager.downloadFile(
-        `${this.repoUrl}/commands/dev/fix.md`,
-        '.contextkit/commands/dev/fix.md'
-      );
       await this.downloadManager.downloadFile(
         `${this.repoUrl}/commands/dev/refactor.md`,
         '.contextkit/commands/dev/refactor.md'
@@ -928,8 +924,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 +978,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`,
@@ -1112,7 +1146,6 @@ claude "read .contextkit/context.md to see available standards, then create a bu
 ### Commands
 - \`.contextkit/commands/dev/analyze.md\` - Analyze & customize standards
 - \`.contextkit/commands/dev/review.md\` - Code review
-- \`.contextkit/commands/dev/fix.md\` - Diagnose and fix bugs
 - \`.contextkit/commands/dev/refactor.md\` - Refactor code structure
 - \`.contextkit/commands/dev/run-tests.md\` - Generate or run tests
 - \`.contextkit/commands/docs/add-documentation.md\` - Add documentation
@@ -1241,7 +1274,6 @@ esac
       commands: {
         analyze: '@.contextkit/commands/dev/analyze.md',
         review: '@.contextkit/commands/dev/review.md',
-        fix: '@.contextkit/commands/dev/fix.md',
         refactor: '@.contextkit/commands/dev/refactor.md',
         run_tests: '@.contextkit/commands/dev/run-tests.md',
         add_docs: '@.contextkit/commands/docs/add-documentation.md',

package/lib/commands/update.js

@@ -263,10 +263,6 @@ class UpdateCommand {
         `${this.repoUrl}/commands/dev/review.md`,
         '.contextkit/commands/dev/review.md'
       );
-      await this.downloadManager.downloadFile(
-        `${this.repoUrl}/commands/dev/fix.md`,
-        '.contextkit/commands/dev/fix.md'
-      );
       await this.downloadManager.downloadFile(
         `${this.repoUrl}/commands/dev/refactor.md`,
         '.contextkit/commands/dev/refactor.md'
@@ -292,8 +288,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 +342,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`,
@@ -464,7 +498,6 @@ paths:
 commands:
   analyze: "${config.commands?.analyze || '@.contextkit/commands/dev/analyze.md'}"
   review: "${config.commands?.review || '@.contextkit/commands/dev/review.md'}"
-  fix: "${config.commands?.fix || '@.contextkit/commands/dev/fix.md'}"
   refactor: "${config.commands?.refactor || '@.contextkit/commands/dev/refactor.md'}"
   run_tests: "${config.commands?.run_tests || '@.contextkit/commands/dev/run-tests.md'}"
   add_docs: "${config.commands?.add_docs || '@.contextkit/commands/docs/add-documentation.md'}"
@@ -506,6 +539,8 @@ commands:
       '.contextkit/commands/analyze.md',
       '.contextkit/commands/review.md',
       '.contextkit/commands/fix.md',
+      // Removed in 0.20.0 — /fix replaced by /squad for bug workflows
+      '.contextkit/commands/dev/fix.md',
       '.contextkit/commands/refactor.md',
       '.contextkit/commands/run-tests.md',
       '.contextkit/commands/add-documentation.md',

package/lib/integrations/claude-integration.js

@@ -13,7 +13,6 @@ class ClaudeIntegration extends BaseIntegration {
       '.claude/rules/contextkit-code-style.md',
       '.claude/skills/analyze/SKILL.md',
       '.claude/skills/review/SKILL.md',
-      '.claude/skills/fix/SKILL.md',
       '.claude/skills/refactor/SKILL.md',
       '.claude/skills/test/SKILL.md',
       '.claude/skills/doc/SKILL.md',
@@ -28,6 +27,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',
@@ -86,7 +86,6 @@ class ClaudeIntegration extends BaseIntegration {
       // Migrated to .claude/skills/ in 0.15.0
       '.claude/commands/analyze.md',
       '.claude/commands/review.md',
-      '.claude/commands/fix.md',
       '.claude/commands/refactor.md',
       '.claude/commands/test.md',
       '.claude/commands/doc.md',
@@ -251,21 +250,6 @@ Review current changes for correctness, standards compliance, and potential issu
 `
     );
 
-    await this.writeGeneratedFile(
-      '.claude/skills/fix/SKILL.md',
-      `---
-description: Diagnose root cause and implement a minimal bug fix with regression test
-argument-hint: "<description of the bug>"
-allowed-tools: Read, Edit, Write, Glob, Grep, Bash
-effort: normal
----
-
-Read \`.contextkit/commands/dev/fix.md\` and execute the bug fix workflow.
-
-Diagnose the root cause, implement the minimal fix, and add a regression test.
-`
-    );
-
     await this.writeGeneratedFile(
       '.claude/skills/refactor/SKILL.md',
       `---
@@ -312,7 +296,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 +304,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',
       `---
@@ -595,7 +595,6 @@ Load and apply the project's ContextKit standards before taking action in an age
     console.log(chalk.dim('  Slash commands:'));
     console.log(chalk.dim('    /analyze  — Analyze project and generate standards'));
     console.log(chalk.dim('    /review   — Review current changes'));
-    console.log(chalk.dim('    /fix      — Diagnose and fix a bug'));
     console.log(chalk.dim('    /refactor — Refactor code structure'));
     console.log(chalk.dim('    /test     — Generate or run tests'));
     console.log(chalk.dim('    /doc           — Add documentation'));

package/lib/integrations/cursor-integration.js

@@ -14,7 +14,6 @@ class CursorIntegration extends BaseIntegration {
       '.cursor/rules/contextkit-api.mdc',
       '.cursor/prompts/analyze.md',
       '.cursor/prompts/review.md',
-      '.cursor/prompts/fix.md',
       '.cursor/prompts/refactor.md',
       '.cursor/prompts/test.md',
       '.cursor/prompts/doc.md',
@@ -179,16 +178,6 @@ Review current changes for correctness, standards compliance, and potential issu
 `
     );
 
-    await this.writeGeneratedFile(
-      '.cursor/prompts/fix.md',
-      `# Fix Bug
-
-Read \`.contextkit/commands/dev/fix.md\` and execute the bug fix workflow.
-
-Diagnose the root cause, implement the minimal fix, and add a regression test.
-`
-    );
-
     await this.writeGeneratedFile(
       '.cursor/prompts/refactor.md',
       `# Refactor
@@ -309,7 +298,6 @@ Check project setup, standards status, and integrations. Report what needs atten
     console.log(chalk.dim('  Slash commands (in Cursor Chat):'));
     console.log(chalk.dim('    /analyze  — Analyze project and generate standards'));
     console.log(chalk.dim('    /review   — Review current changes'));
-    console.log(chalk.dim('    /fix      — Diagnose and fix a bug'));
     console.log(chalk.dim('    /refactor — Refactor code structure'));
     console.log(chalk.dim('    /test     — Generate or run tests'));
     console.log(chalk.dim('    /doc      — Add documentation'));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nolrm/contextkit",
-  "version": "0.18.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.",
+  "version": "0.21.0",
+  "description": "ContextKit - Context Engineering + Agentic AI Pipelines. Scaffold structured standards for AI assistants and run autonomous multi-role pipelines (PO → Architect → Dev → Test → Review → Doc) grounded by that same context layer. Works with Cursor, Claude Code, Copilot, Codex, Gemini, Aider, and more.",
   "main": "lib/index.js",
   "bin": {
     "contextkit": "bin/contextkit.js",
@@ -45,7 +45,14 @@
     "structured-context",
     "markdown-standards",
     "project-standards",
-    "code-patterns"
+    "code-patterns",
+    "agentic-pipeline",
+    "agentic-ai",
+    "squad-workflow",
+    "ai-agents",
+    "autonomous-agents",
+    "multi-agent",
+    "claude-code"
   ],
   "author": {
     "name": "Marlon Maniti",