@nolrm/contextkit 0.9.4 → 0.9.7

package/README.md

@@ -23,7 +23,7 @@ Update `.md` files as your project evolves; the AI follows.
 
 Works with: **Cursor** • **Claude Code** • **GitHub Copilot** • **Codex CLI** • **Gemini CLI** • **Aider** • **Continue** • **Windsurf**
 
-Each platform gets auto-loaded bridge files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.windsurfrules`, etc.) so your AI tools read project standards automatically.
+Each platform gets auto-loaded bridge files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.windsurfrules`, etc.) so your AI tools read project standards automatically. Claude Code uses `@` imports in CLAUDE.md to load standards content directly into context — no extra token cost from manual file reads.
 
 ---
 
@@ -118,7 +118,7 @@ Each platform generates bridge files that the AI tool auto-reads. If a bridge fi
 /fix        # diagnose and fix bugs
 ```
 
-**Claude Code** — reads `CLAUDE.md` + `.claude/rules/`, slash commands in `.claude/commands/`
+**Claude Code** — `CLAUDE.md` uses `@` imports to auto-load all standards into context every session (no manual reads needed, saves tokens). Slash commands in `.claude/commands/`.
 ```bash
 /analyze    # scan codebase and generate standards
 /review     # code review with checklist
@@ -154,6 +154,14 @@ ContextKit installs reusable slash commands for supported platforms:
 | `/refactor` | Refactor code with safety checks |
 | `/test` | Generate comprehensive tests |
 | `/doc` | Add documentation |
+| `/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 |
+| `/squad-test` | Write and run tests against acceptance criteria |
+| `/squad-review` | Review the full pipeline and give a verdict |
+| `/squad-batch` | Kick off multiple tasks at once (batch PO specs) |
+| `/squad-run` | Auto-run the remaining pipeline for batch tasks |
+| `/ck` | Health check — verify setup, standards, and integrations |
 
 **Claude Code** — available as `/analyze`, `/review`, etc. in `.claude/commands/`
 **Cursor** — available as slash commands in Chat via `.cursor/prompts/`
@@ -162,6 +170,56 @@ Both platforms delegate to the universal command files in `.contextkit/commands/
 
 ---
 
+## Squad Workflow
+
+The squad workflow turns a single AI session into a structured multi-role pipeline. Each role has its own slash command that reads and writes to a shared handoff file (`.contextkit/squad/handoff.md`), simulating a team of specialists.
+
+### Pipeline Roles
+
+| Step | Role | Command | What it does |
+|------|------|---------|-------------|
+| 1 | Product Owner | `/squad` | Writes a user story, acceptance criteria, edge cases, and scope |
+| 2 | Architect | `/squad-architect` | Designs the technical approach, files to change, and implementation steps |
+| 3 | Developer | `/squad-dev` | Implements the code following the architect's plan |
+| 4 | Tester | `/squad-test` | Writes and runs tests against the PO's acceptance criteria |
+| 5 | Reviewer | `/squad-review` | Reviews everything and gives a PASS or NEEDS-WORK verdict |
+
+### Single-Task Flow
+
+```bash
+/squad "add dark mode support"        # PO writes the spec
+/squad-architect                       # Architect designs the plan
+/squad-dev                             # Dev implements the code
+/squad-test                            # Tester writes and runs tests
+/squad-review                          # Reviewer gives the verdict
+```
+
+### Batch Flow
+
+For multiple tasks, use batch mode to spec them all up front, then run the full pipeline automatically:
+
+```bash
+/squad-batch "add dark mode" "fix login bug" "refactor checkout"
+# PO writes specs for all three tasks
+
+/squad-run
+# Runs Architect → Dev → Test → Review for each task sequentially
+```
+
+### Feedback Loop
+
+Any downstream role can raise questions for an upstream role. When this happens, the pipeline pauses and directs you to the right command:
+
+```
+Reviewer has questions for Dev → run /squad-dev to clarify
+Tester has questions for Architect → run /squad-architect to clarify
+Architect has questions for PO → run /squad to clarify
+```
+
+After clarifications are added, re-run the asking role's command to continue. This prevents misunderstandings from compounding through the pipeline.
+
+---
+
 ## Git Hooks & Quality Gates
 
 ContextKit can optionally install Git hooks during `ck install`. Uses `git config core.hooksPath` to point Git at `.contextkit/hooks/` — no external dependencies like Husky required. Works in any git repo, not just Node.js projects.

package/lib/commands/install.js

@@ -551,6 +551,36 @@ Run \`ck analyze\` to generate this content, or manually add your API pattern be
         '.contextkit/commands/create-component.md'
       );
 
+      // Download squad commands
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/squad.md`,
+        '.contextkit/commands/squad.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/squad-architect.md`,
+        '.contextkit/commands/squad-architect.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/squad-dev.md`,
+        '.contextkit/commands/squad-dev.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/squad-test.md`,
+        '.contextkit/commands/squad-test.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/squad-review.md`,
+        '.contextkit/commands/squad-review.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/squad-batch.md`,
+        '.contextkit/commands/squad-batch.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/squad-run.md`,
+        '.contextkit/commands/squad-run.md'
+      );
+
       // Download hooks (pre-push and commit-msg only, no pre-commit)
       await this.downloadManager.downloadFile(
         `${this.repoUrl}/hooks/pre-push`,
@@ -608,6 +638,7 @@ Run \`ck analyze\` to generate this content, or manually add your API pattern be
     await this.createCorrectionsLog();
     await this.createMetaInstructions();
     await this.createPolicyFile();
+    await this.createHealthCheckCommand();
 
     // Install platform integrations
     await this.installPlatformIntegrations(detectedTools);
@@ -1431,6 +1462,58 @@ enforcement:
     console.log(chalk.green('✅ Policy file created'));
   }
 
+  async createHealthCheckCommand() {
+    const healthCheckContent = `# ContextKit Health Check
+
+Check this project's ContextKit setup and report status.
+
+## Steps
+
+1. Check if \`.contextkit/\` directory exists. If not → STOP and tell user: "Run \`ck install\` to set up ContextKit."
+
+2. Read \`.contextkit/config.yml\` and check the \`last_analyzed\` field.
+
+3. Check each standards file for skeleton markers. Read these files and check if they contain \`<!-- Content will be generated by running: ck analyze -->\`:
+   - \`.contextkit/standards/code-style.md\`
+   - \`.contextkit/standards/testing.md\`
+   - \`.contextkit/standards/architecture.md\`
+   - \`.contextkit/standards/ai-guidelines.md\`
+   - \`.contextkit/standards/workflows.md\`
+   - \`.contextkit/standards/glossary.md\`
+
+4. Check product files for placeholder content (e.g., \`[ELEVATOR_PITCH_FROM_MISSION_MD]\`):
+   - \`.contextkit/product/mission-lite.md\`
+   - \`.contextkit/product/decisions.md\`
+   - \`.contextkit/product/roadmap.md\`
+
+5. Check which platform integrations exist:
+   - \`CLAUDE.md\` → Claude Code
+   - \`.cursor/rules/\` → Cursor
+   - \`AGENTS.md\` → Codex
+   - \`GEMINI.md\` → Gemini
+   - \`CONVENTIONS.md\` → Aider
+   - \`.windsurfrules\` → Windsurf
+   - \`.github/copilot-instructions.md\` → Copilot
+
+6. Report findings as a status summary table and list recommended next steps.
+
+## Output Format
+
+| Area | Status | Action |
+|------|--------|--------|
+| Installation | OK/Missing | \`ck install\` |
+| Standards | Populated/Skeleton | \`ck analyze\` or \`/analyze\` |
+| Product context | Populated/Placeholder | Edit \`.contextkit/product/\` files |
+| Integrations | List active | \`ck <platform>\` to add more |
+
+## Token Note
+
+If standards are still skeletons, warn that @imports in CLAUDE.md are loading empty files — wasting context tokens. Run \`/analyze\` to populate them.
+`;
+
+    await fs.writeFile('.contextkit/commands/health-check.md', healthCheckContent);
+  }
+
   showSuccessMessage(hookChoices, detectedTools = {}, projectType = '', packageManager = '') {
     console.log('');
     console.log(chalk.green('🎉 ContextKit v1.0.0 successfully installed!'));

package/lib/commands/update.js

@@ -249,6 +249,36 @@ class UpdateCommand {
         '.contextkit/commands/create-component.md'
       );
 
+      // Download squad commands
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/squad.md`,
+        '.contextkit/commands/squad.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/squad-architect.md`,
+        '.contextkit/commands/squad-architect.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/squad-dev.md`,
+        '.contextkit/commands/squad-dev.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/squad-test.md`,
+        '.contextkit/commands/squad-test.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/squad-review.md`,
+        '.contextkit/commands/squad-review.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/squad-batch.md`,
+        '.contextkit/commands/squad-batch.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/squad-run.md`,
+        '.contextkit/commands/squad-run.md'
+      );
+
       // Download hooks (pre-push and commit-msg only, no pre-commit)
       await this.downloadManager.downloadFile(
         `${this.repoUrl}/hooks/pre-push`,

package/lib/integrations/claude-integration.js

@@ -17,6 +17,14 @@ class ClaudeIntegration extends BaseIntegration {
       '.claude/commands/refactor.md',
       '.claude/commands/test.md',
       '.claude/commands/doc.md',
+      '.claude/commands/squad.md',
+      '.claude/commands/squad-architect.md',
+      '.claude/commands/squad-dev.md',
+      '.claude/commands/squad-test.md',
+      '.claude/commands/squad-review.md',
+      '.claude/commands/squad-batch.md',
+      '.claude/commands/squad-run.md',
+      '.claude/commands/ck.md',
     ];
     this.platformDir = '.claude/rules';
   }
@@ -42,6 +50,33 @@ class ClaudeIntegration extends BaseIntegration {
     }
   }
 
+  getStandardsBlock() {
+    return `## Project Standards
+
+The following standards are auto-loaded into context via @imports:
+
+- @.contextkit/standards/code-style.md — Coding conventions and style rules
+- @.contextkit/standards/testing.md — Testing patterns and requirements
+- @.contextkit/standards/architecture.md — Architecture decisions and patterns
+- @.contextkit/standards/ai-guidelines.md — AI behavior and usage guidelines
+- @.contextkit/standards/workflows.md — Development workflows and processes
+- @.contextkit/standards/glossary.md — Project terminology and shortcuts
+
+## Product Context
+
+- @.contextkit/product/mission-lite.md — Product mission (condensed)
+- @.contextkit/product/decisions.md — Architecture Decision Records
+- @.contextkit/product/roadmap.md — Development roadmap
+
+## Commands
+
+- \`.contextkit/commands/analyze.md\` — Analyze and customize standards
+- \`.contextkit/commands/create-component.md\` — Create components
+- \`.contextkit/commands/create-feature.md\` — Create features
+- \`.contextkit/commands/run-tests.md\` — Run tests
+- \`.contextkit/commands/quality-check.md\` — Quality checks`;
+  }
+
   async generateFiles() {
     // Bridge file: CLAUDE.md (auto-loaded every session)
     const bridgeContent = `# Project Standards (ContextKit)
@@ -52,7 +87,7 @@ ${this.getStandardsBlock()}
 
 ## Corrections Log
 
-- \`.contextkit/corrections.md\` — Track AI performance improvements
+- @.contextkit/corrections.md — Track AI performance improvements
 
 ## Quick Reference
 
@@ -68,14 +103,14 @@ alwaysApply: true
 
 # ContextKit Standards
 
-This project uses ContextKit for structured development standards.
+This project uses ContextKit. Project standards are auto-loaded via CLAUDE.md imports.
 
-Always reference the following before generating code:
-- \`.contextkit/standards/code-style.md\` for coding conventions
-- \`.contextkit/standards/architecture.md\` for architecture patterns
-- \`.contextkit/standards/ai-guidelines.md\` for AI behavior rules
-- \`.contextkit/standards/glossary.md\` for project terminology
-- \`.contextkit/product/mission-lite.md\` for product context
+Key areas to follow:
+- Code style conventions (from code-style.md)
+- Architecture patterns (from architecture.md)
+- AI behavior rules (from ai-guidelines.md)
+- Project terminology (from glossary.md)
+- Product context (from mission-lite.md)
 `;
     await this.writeGeneratedFile('.claude/rules/contextkit-standards.md', standardsRule);
 
@@ -90,8 +125,7 @@ globs:
 
 # Testing Standards
 
-When writing or modifying tests, follow:
-- \`.contextkit/standards/testing.md\` for test patterns and requirements
+Follow the testing standards auto-loaded via CLAUDE.md (from testing.md).
 - All test cases MUST use numbered descriptions (e.g., \`it("1. renders correctly")\`)
 - Reference \`.contextkit/templates/test.md\` for test template patterns
 `;
@@ -109,11 +143,10 @@ globs:
 
 # Code Style
 
-When writing or modifying source code, follow:
-- \`.contextkit/standards/code-style.md\` for coding conventions
-- \`.contextkit/templates/component.md\` for component patterns
-- \`.contextkit/templates/hook.md\` for custom hook patterns
-- \`.contextkit/templates/api.md\` for API service patterns
+Follow the code style standards auto-loaded via CLAUDE.md (from code-style.md).
+- Reference \`.contextkit/templates/component.md\` for component patterns
+- Reference \`.contextkit/templates/hook.md\` for custom hook patterns
+- Reference \`.contextkit/templates/api.md\` for API service patterns
 `;
     await this.writeGeneratedFile('.claude/rules/contextkit-code-style.md', codeStyleRule);
 
@@ -158,6 +191,63 @@ Generate or run tests for the specified code, covering happy paths, edge cases,
 Read \`.contextkit/commands/add-documentation.md\` and execute the documentation workflow.
 
 Add inline docs, README sections, and usage examples for the specified code.
+`);
+
+    // Squad slash commands
+    await this.writeGeneratedFile('.claude/commands/squad.md', `# Squad — Kickoff
+
+Read \`.contextkit/commands/squad.md\` and execute the squad kickoff workflow.
+
+Create the handoff file and write the PO spec for the given task. Pass the user's task description as the input.
+`);
+
+    await this.writeGeneratedFile('.claude/commands/squad-architect.md', `# Squad — Architect
+
+Read \`.contextkit/commands/squad-architect.md\` and execute the architect workflow.
+
+Read the PO spec from the handoff file, design the technical approach, and write the implementation plan.
+`);
+
+    await this.writeGeneratedFile('.claude/commands/squad-dev.md', `# Squad — Dev
+
+Read \`.contextkit/commands/squad-dev.md\` and execute the dev workflow.
+
+Follow the architect's plan to implement the code changes.
+`);
+
+    await this.writeGeneratedFile('.claude/commands/squad-test.md', `# Squad — Test
+
+Read \`.contextkit/commands/squad-test.md\` and execute the test workflow.
+
+Write and run tests against the PO's acceptance criteria.
+`);
+
+    await this.writeGeneratedFile('.claude/commands/squad-review.md', `# Squad — Review
+
+Read \`.contextkit/commands/squad-review.md\` and execute the review workflow.
+
+Review the full handoff (spec, plan, implementation, tests) and write the final verdict.
+`);
+
+    await this.writeGeneratedFile('.claude/commands/squad-batch.md', `# Squad Batch — Multi-Task Kickoff
+
+Read \`.contextkit/commands/squad-batch.md\` and execute the batch kickoff workflow.
+
+Create handoff files for multiple tasks and write PO specs for each one. Pass all task descriptions as the input.
+`);
+
+    await this.writeGeneratedFile('.claude/commands/squad-run.md', `# Squad Run — Auto-Run Pipeline
+
+Read \`.contextkit/commands/squad-run.md\` and execute the pipeline runner workflow.
+
+Process all batch tasks through the remaining pipeline steps (Architect, Dev, Test, Review) sequentially.
+`);
+
+    await this.writeGeneratedFile('.claude/commands/ck.md', `# ContextKit Health Check
+
+Read \`.contextkit/commands/health-check.md\` and execute the health check workflow.
+
+Check project setup, standards status, and integrations. Report what needs attention.
 `);
   }
 
@@ -174,6 +264,18 @@ Add inline docs, README sections, and usage examples for the specified code.
     console.log(chalk.dim('    /refactor — Refactor code structure'));
     console.log(chalk.dim('    /test     — Generate or run tests'));
     console.log(chalk.dim('    /doc      — Add documentation'));
+    console.log(chalk.dim(''));
+    console.log(chalk.dim('  Squad (multi-agent workflow):'));
+    console.log(chalk.dim('    /squad "task"      — Kickoff: create handoff + PO spec'));
+    console.log(chalk.dim('    /squad-architect   — Design the implementation plan'));
+    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-batch       — Batch kickoff: PO specs for multiple tasks'));
+    console.log(chalk.dim('    /squad-run         — Auto-run pipeline for batch tasks'));
+    console.log(chalk.dim(''));
+    console.log(chalk.dim('  Health check:'));
+    console.log(chalk.dim('    /ck           — Check project setup and standards status'));
   }
 }
 

package/lib/integrations/cursor-integration.js

@@ -18,6 +18,14 @@ class CursorIntegration extends BaseIntegration {
       '.cursor/prompts/refactor.md',
       '.cursor/prompts/test.md',
       '.cursor/prompts/doc.md',
+      '.cursor/prompts/squad.md',
+      '.cursor/prompts/squad-architect.md',
+      '.cursor/prompts/squad-dev.md',
+      '.cursor/prompts/squad-test.md',
+      '.cursor/prompts/squad-review.md',
+      '.cursor/prompts/squad-batch.md',
+      '.cursor/prompts/squad-run.md',
+      '.cursor/prompts/ck.md',
     ];
     this.bridgeFiles = [];
     this.platformDir = '.cursor/rules';
@@ -191,6 +199,63 @@ Generate or run tests for the specified code, covering happy paths, edge cases,
 Read \`.contextkit/commands/add-documentation.md\` and execute the documentation workflow.
 
 Add inline docs, README sections, and usage examples for the specified code.
+`);
+
+    // Squad prompts
+    await this.writeGeneratedFile('.cursor/prompts/squad.md', `# Squad — Kickoff
+
+Read \`.contextkit/commands/squad.md\` and execute the squad kickoff workflow.
+
+Create the handoff file and write the PO spec for the given task. Pass the user's task description as the input.
+`);
+
+    await this.writeGeneratedFile('.cursor/prompts/squad-architect.md', `# Squad — Architect
+
+Read \`.contextkit/commands/squad-architect.md\` and execute the architect workflow.
+
+Read the PO spec from the handoff file, design the technical approach, and write the implementation plan.
+`);
+
+    await this.writeGeneratedFile('.cursor/prompts/squad-dev.md', `# Squad — Dev
+
+Read \`.contextkit/commands/squad-dev.md\` and execute the dev workflow.
+
+Follow the architect's plan to implement the code changes.
+`);
+
+    await this.writeGeneratedFile('.cursor/prompts/squad-test.md', `# Squad — Test
+
+Read \`.contextkit/commands/squad-test.md\` and execute the test workflow.
+
+Write and run tests against the PO's acceptance criteria.
+`);
+
+    await this.writeGeneratedFile('.cursor/prompts/squad-review.md', `# Squad — Review
+
+Read \`.contextkit/commands/squad-review.md\` and execute the review workflow.
+
+Review the full handoff (spec, plan, implementation, tests) and write the final verdict.
+`);
+
+    await this.writeGeneratedFile('.cursor/prompts/squad-batch.md', `# Squad Batch — Multi-Task Kickoff
+
+Read \`.contextkit/commands/squad-batch.md\` and execute the batch kickoff workflow.
+
+Create handoff files for multiple tasks and write PO specs for each one. Pass all task descriptions as the input.
+`);
+
+    await this.writeGeneratedFile('.cursor/prompts/squad-run.md', `# Squad Run — Auto-Run Pipeline
+
+Read \`.contextkit/commands/squad-run.md\` and execute the pipeline runner workflow.
+
+Process all batch tasks through the remaining pipeline steps (Architect, Dev, Test, Review) sequentially.
+`);
+
+    await this.writeGeneratedFile('.cursor/prompts/ck.md', `# ContextKit Health Check
+
+Read \`.contextkit/commands/health-check.md\` and execute the health check workflow.
+
+Check project setup, standards status, and integrations. Report what needs attention.
 `);
   }
 
@@ -206,6 +271,18 @@ Add inline docs, README sections, and usage examples for the specified code.
     console.log(chalk.dim('    /refactor — Refactor code structure'));
     console.log(chalk.dim('    /test     — Generate or run tests'));
     console.log(chalk.dim('    /doc      — Add documentation'));
+    console.log(chalk.dim(''));
+    console.log(chalk.dim('  Squad (multi-agent workflow):'));
+    console.log(chalk.dim('    /squad "task"      — Kickoff: create handoff + PO spec'));
+    console.log(chalk.dim('    /squad-architect   — Design the implementation plan'));
+    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-batch       — Batch kickoff: PO specs for multiple tasks'));
+    console.log(chalk.dim('    /squad-run         — Auto-run pipeline for batch tasks'));
+    console.log(chalk.dim(''));
+    console.log(chalk.dim('  Health check:'));
+    console.log(chalk.dim('    /ck           — Check project setup and standards status'));
   }
 }
 

package/package.json

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