@nolrm/contextkit 0.12.17 → 0.12.20

package/README.md

@@ -153,6 +153,7 @@ ContextKit installs reusable slash commands for supported platforms:
 | `/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-doc` | Create companion `.md` files for new/modified code after review passes |
 | `/squad-auto` | Auto-run the full pipeline after kickoff (recommended, 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 |
@@ -177,18 +178,20 @@ The squad workflow turns a single AI session into a structured multi-role pipeli
 | 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 |
+| 6 | Doc Writer | `/squad-doc` | Creates companion `.md` files for every new/modified code file |
 
 ### Single-Task Flow
 
 ```bash
 /squad "add dark mode support"   # PO writes the spec
 
-/squad-auto                      # Auto-runs architect → dev → test → review (recommended)
+/squad-auto                      # Auto-runs architect → dev → test → review → doc (recommended)
 # — or step through manually —
 /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
+/squad-doc                       # Doc Writer creates companion .md files
 ```
 
 ### Batch Flow
@@ -200,7 +203,7 @@ Pass multiple tasks to `/squad` and it automatically runs in batch mode:
 # PO writes specs for all three tasks
 
 /squad-auto
-# Runs Architect → Dev → Test → Review for each task sequentially
+# Runs Architect → Dev → Test → Review → Doc for each task sequentially
 ```
 
 **Parallel mode (Claude Code only):** Use `/squad-auto-parallel` instead of `/squad-auto` to spawn parallel subagents — one per task per phase — so all tasks progress simultaneously rather than one at a time.
@@ -210,7 +213,7 @@ Pass multiple tasks to `/squad` and it automatically runs in batch mode:
 
 /squad-auto-parallel
 # Phase 1: architect agents for all 3 tasks run in parallel
-# Phase 2: dev→test→review pipeline runs in parallel per task
+# Phase 2: dev→test→review pipeline runs in parallel per task; Phase 3: doc runs sequentially
 ```
 
 **Model routing (Claude Code only):** Set `model_routing: true` in `.contextkit/squad/config.md` to have `/squad-auto` automatically use Claude Haiku for Dev and Test phases. Architect and Review always run on your primary model. Saves ~35% tokens with no quality loss — the standards files and Review gate maintain quality.
@@ -318,6 +321,7 @@ ck vscode      # alias for copilot
 # Analysis & Updates
 /analyze       # customize standards to your project (slash command in your AI tool)
 ck update      # pull latest commands/hooks — preserves your analyzed standards
+               # updates are also flagged automatically after each ck command (24h cache)
 ck status      # check install & integrations
 
 # Validation & Compliance
@@ -330,7 +334,7 @@ ck note "AI issue" --category "AI Behavior" --priority HIGH
 
 # Squad — multi-role AI pipeline (slash commands in your AI tool)
 /squad "add dark mode"   # PO writes spec
-/squad-auto              # runs architect → dev → test → review hands-free
+/squad-auto              # runs architect → dev → test → review → doc hands-free
 /squad-reset             # clear stuck or mixed squad state
 
 # Observability

package/bin/contextkit.js

@@ -12,6 +12,9 @@ const publish = require('../lib/commands/publish');
 const pull = require('../lib/commands/pull');
 const dashboard = require('../lib/commands/dashboard');
 const packageJson = require('../package.json');
+const { checkForUpdates } = require('../lib/utils/notifier');
+
+checkForUpdates();
 
 // Set up the CLI
 program

package/lib/commands/install.js

@@ -734,6 +734,14 @@ Any design decisions, trade-offs, or open questions to resolve before coding.
         `${this.repoUrl}/commands/squad-reset.md`,
         '.contextkit/commands/squad-reset.md'
       );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/squad-doc.md`,
+        '.contextkit/commands/squad-doc.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/health-check.md`,
+        '.contextkit/commands/health-check.md'
+      );
 
       // Download hooks (pre-push and commit-msg only, no pre-commit)
       await this.downloadManager.downloadFile(
@@ -792,7 +800,6 @@ Any design decisions, trade-offs, or open questions to resolve before coding.
     await this.createCorrectionsLog();
     await this.createMetaInstructions();
     await this.createPolicyFile();
-    await this.createHealthCheckCommand();
 
     // Install CLI helpers
     await this.installCLIHelpers();
@@ -1592,58 +1599,6 @@ 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: /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, platform = null, projectType = '', packageManager = '') {
     console.log('');
     console.log(chalk.green('🎉 ContextKit v1.0.0 successfully installed!'));

package/lib/commands/update.js

@@ -291,6 +291,14 @@ class UpdateCommand {
         `${this.repoUrl}/commands/squad-reset.md`,
         '.contextkit/commands/squad-reset.md'
       );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/squad-doc.md`,
+        '.contextkit/commands/squad-doc.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/health-check.md`,
+        '.contextkit/commands/health-check.md'
+      );
 
       // Download hooks (pre-push and commit-msg only, no pre-commit)
       await this.downloadManager.downloadFile(

package/lib/integrations/claude-integration.js

@@ -25,6 +25,7 @@ class ClaudeIntegration extends BaseIntegration {
       '.claude/commands/squad-auto.md',
       '.claude/commands/squad-auto-parallel.md',
       '.claude/commands/squad-reset.md',
+      '.claude/commands/squad-doc.md',
       '.claude/commands/spec.md',
       '.claude/commands/ck.md',
     ];
@@ -82,11 +83,16 @@ The following standards are auto-loaded into context via @imports:
   }
 
   async generateFiles() {
+    const { version } = require('../../package.json');
+
     // Bridge file: CLAUDE.md (auto-loaded every session)
     const bridgeContent = `# Project Standards (ContextKit)
 
 This project uses [ContextKit](https://github.com/nolrm/contextkit) for AI development standards.
 
+## ContextKit
+Version: ${version}
+
 ${this.getStandardsBlock()}
 
 ## Corrections Log
@@ -211,7 +217,7 @@ 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.
 
-After kickoff, run \`/squad-auto\` to auto-run the full pipeline hands-free, or step through manually with \`/squad-architect\` → \`/squad-dev\` → \`/squad-test\` → \`/squad-review\`.
+After kickoff, run \`/squad-auto\` to auto-run the full pipeline hands-free, or step through manually with \`/squad-architect\` → \`/squad-dev\` → \`/squad-test\` → \`/squad-review\` → \`/squad-doc\`.
 `);
 
     await this.writeGeneratedFile('.claude/commands/squad-architect.md', `# Squad — Architect (manual step 1/4)
@@ -261,6 +267,13 @@ Spawn one subagent per task per phase using the Task tool, so all tasks progress
 Read \`.contextkit/commands/squad-reset.md\` and execute the reset workflow.
 
 Delete the current squad state (.contextkit/squad/) so you can start fresh. Use when the squad folder is in a mixed or stuck state.
+`);
+
+    await this.writeGeneratedFile('.claude/commands/squad-doc.md', `# Squad — Doc (manual step 5/5)
+
+Read \`.contextkit/commands/squad-doc.md\` and execute the doc workflow.
+
+After review passes, create or update companion .md files for every new/modified code file in this task. Use \`/squad-auto\` instead to run all steps automatically.
 `);
 
     await this.writeGeneratedFile('.claude/commands/ck.md', `# ContextKit Health Check
@@ -293,6 +306,7 @@ Check project setup, standards status, and integrations. Report what needs atten
     console.log(chalk.dim('    /squad-review      — Review and write verdict'));
     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)'));
+    console.log(chalk.dim('    /squad-doc              — Document changes after review passes'));
     console.log(chalk.dim(''));
     console.log(chalk.dim('  Health check:'));
     console.log(chalk.dim('    /ck           — Check project setup and standards status'));

package/lib/utils/notifier.js

@@ -0,0 +1,17 @@
+const updateNotifier = require('update-notifier');
+const pkg = require('../../package.json');
+
+/**
+ * Check for available updates to @nolrm/contextkit on npm.
+ * Results are cached for 24 hours. Notification prints after the command
+ * completes. Suppressed automatically in CI environments.
+ */
+function checkForUpdates() {
+  try {
+    updateNotifier({ pkg }).notify();
+  } catch (err) {
+    // Never crash the CLI due to a notifier failure
+  }
+}
+
+module.exports = { checkForUpdates };

package/lib/utils/notifier.md

@@ -0,0 +1,29 @@
+# notifier.js
+
+Thin wrapper around `update-notifier` for passive npm update notifications in the ContextKit CLI.
+
+## Purpose
+
+Checks npm once every 24 hours for a newer version of `@nolrm/contextkit`. If an update is available, prints a non-blocking one-liner after the command completes. Suppressed automatically in CI environments (`CI=true`).
+
+## Exports
+
+### `checkForUpdates()`
+
+Initialises `update-notifier` with the package metadata from `package.json` and calls `.notify()`. Errors are silently swallowed — a notifier failure must never crash the CLI.
+
+## Usage
+
+Called once in `bin/contextkit.js` before `program.parse()`:
+
+```javascript
+const { checkForUpdates } = require('../lib/utils/notifier');
+checkForUpdates();
+program.parse(process.argv);
+```
+
+## Edge Cases
+
+- `update-notifier` caches the check result for 24 hours — only one npm request per day per machine.
+- Suppressed in CI via `update-notifier`'s built-in CI detection (`CI`, `CONTINUOUS_INTEGRATION`, `BUILD_NUMBER` env vars).
+- Uses `update-notifier@5.1.0` — the last CommonJS-compatible release (v6+ is ESM-only).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nolrm/contextkit",
-  "version": "0.12.17",
+  "version": "0.12.20",
   "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": {
@@ -69,7 +69,8 @@
     "fs-extra": "^11.1.1",
     "inquirer": "^8.2.6",
     "js-yaml": "^4.1.0",
-    "ora": "^5.4.1"
+    "ora": "^5.4.1",
+    "update-notifier": "^5.1.0"
   },
   "files": [
     "bin/",