@nolrm/contextkit 0.16.4 → 0.18.0

package/README.md

@@ -114,7 +114,7 @@ Each platform generates bridge files that the AI tool auto-reads. If a bridge fi
 /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/`.
+**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.
 
 ```bash
 /analyze    # scan codebase and generate standards
@@ -164,7 +164,8 @@ ContextKit installs reusable slash commands for supported platforms:
 | `/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 +196,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,7 +269,9 @@ If you have a screenshot, mockup, or design image relevant to the task, paste or
 
 ---
 
-## Git Hooks & Quality Gates
+## 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.
 
 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

@@ -973,6 +973,10 @@ 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'

package/lib/commands/update.js

@@ -337,6 +337,10 @@ 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'

package/lib/integrations/claude-integration.js

@@ -26,6 +26,7 @@ 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/ck/SKILL.md',
       '.claude/skills/doc-arch/SKILL.md',
@@ -44,6 +45,25 @@ class ClaudeIntegration extends BaseIntegration {
     await fs.ensureDir('.claude/skills');
     await this.addToGitignore('.claude/settings.local.json');
     await this.removeLegacyFiles();
+    await this._installHook();
+  }
+
+  async _installHook() {
+    try {
+      const HookDetector = require('../utils/hook-detector');
+      const ClaudeSettings = require('../utils/claude-settings');
+      const command = await new HookDetector().detect();
+      if (command) {
+        await new ClaudeSettings().addPostToolUseHook(command);
+        console.log(chalk.green(`  ✓ PostToolUse hook: ${command}`));
+      } else {
+        console.log(
+          chalk.dim(chalk.yellow('  ⚠  No format/lint tooling detected — PostToolUse hook skipped'))
+        );
+      }
+    } catch (err) {
+      console.log(chalk.yellow(`  ⚠  Could not install PostToolUse hook: ${err.message}`));
+    }
   }
 
   async addToGitignore(entry) {
@@ -452,6 +472,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',
@@ -571,6 +609,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/lib/integrations/claude-integration.md

@@ -0,0 +1,39 @@
+# claude-integration.js
+
+The Claude Code platform integration. Installs `CLAUDE.md`, `.claude/rules/`, `.claude/skills/`, and a PostToolUse hook in `.claude/settings.json`.
+
+## Extends
+
+`BaseIntegration`
+
+## install(force = false)
+
+Runs the full Claude Code setup:
+1. Writes bridge file (`CLAUDE.md`) and generated files (rules, skills) via `super.install()`
+2. Ensures `.claude/skills/` directory exists
+3. Adds `.claude/settings.local.json` to `.gitignore`
+4. Removes legacy `.claude/commands/` files
+5. Detects project tooling and installs a PostToolUse hook in `.claude/settings.json`
+
+### Hook Installation (step 5)
+
+Uses `HookDetector` to detect the right format+lint command for the project (Node.js, Go, or Python). If a command is found, `ClaudeSettings.addPostToolUseHook()` writes it to `.claude/settings.json` with a `_contextkit: true` marker.
+
+- On success: logs `✓ PostToolUse hook: <command>`
+- No tooling detected: logs a dim yellow skip message
+- Any error: logs a yellow warning and continues (graceful degradation)
+
+Re-running `install()` (e.g. via `ck update → refreshIntegrations()`) replaces the existing ContextKit hook rather than duplicating it.
+
+## generatedFiles
+
+Listed in the constructor. Does **not** include `.claude/settings.json` — that file is a merge target, not overwritten.
+
+## Key Files Written
+
+| File | Type | Purpose |
+|---|---|---|
+| `CLAUDE.md` | Bridge (merged) | Auto-loaded every Claude Code session |
+| `.claude/rules/contextkit-*.md` | Generated | Scoped rules for standards, testing, code style |
+| `.claude/skills/*/SKILL.md` | Generated | All slash commands |
+| `.claude/settings.json` | Merged | PostToolUse hook entry (`_contextkit: true`) |

package/lib/utils/claude-settings.js

@@ -0,0 +1,67 @@
+const fs = require('fs-extra');
+const chalk = require('chalk');
+
+const SETTINGS_PATH = '.claude/settings.json';
+
+class ClaudeSettings {
+  async read() {
+    if (!(await fs.pathExists(SETTINGS_PATH))) return {};
+    try {
+      const raw = await fs.readFile(SETTINGS_PATH, 'utf8');
+      return JSON.parse(raw);
+    } catch {
+      console.warn(
+        chalk.yellow(`  ⚠  .claude/settings.json contains invalid JSON — skipping hook merge`)
+      );
+      return {};
+    }
+  }
+
+  async write(settings) {
+    await fs.ensureDir('.claude');
+    await fs.writeFile(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n');
+  }
+
+  async addPostToolUseHook(command) {
+    if (!command) throw new Error('hook command is required');
+
+    const settings = await this.read();
+    settings.hooks = settings.hooks || {};
+
+    if (!Array.isArray(settings.hooks.PostToolUse)) {
+      if (settings.hooks.PostToolUse !== undefined) {
+        settings.hooks._contextkit_original_invalid = settings.hooks.PostToolUse;
+      }
+      settings.hooks.PostToolUse = [];
+    }
+
+    settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter((entry) => !entry._contextkit);
+
+    settings.hooks.PostToolUse.push({
+      matcher: 'Edit|Write',
+      hooks: [{ type: 'command', command }],
+      _contextkit: true,
+    });
+
+    await this.write(settings);
+  }
+
+  async removeContextKitHooks() {
+    const settings = await this.read();
+    if (!Array.isArray(settings.hooks?.PostToolUse)) return;
+
+    settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter((entry) => !entry._contextkit);
+
+    if (settings.hooks.PostToolUse.length === 0) {
+      delete settings.hooks.PostToolUse;
+    }
+
+    if (Object.keys(settings.hooks).length === 0) {
+      delete settings.hooks;
+    }
+
+    await this.write(settings);
+  }
+}
+
+module.exports = ClaudeSettings;

package/lib/utils/claude-settings.md

@@ -0,0 +1,52 @@
+# claude-settings.js
+
+Reads, merges, and writes `.claude/settings.json` safely — adding or removing ContextKit-owned entries without clobbering user content.
+
+## Exports
+
+`ClaudeSettings` — class
+
+## Public API
+
+### `read() → Promise<object>`
+
+Returns the parsed contents of `.claude/settings.json`, or `{}` if the file does not exist. On invalid JSON, logs a yellow warning and returns `{}` (does not throw).
+
+### `write(settings) → Promise<void>`
+
+Writes the settings object to `.claude/settings.json` with 2-space indentation and a trailing newline. Creates `.claude/` if it does not exist.
+
+### `addPostToolUseHook(command) → Promise<void>`
+
+Adds a ContextKit-owned PostToolUse hook entry. Replaces any existing `_contextkit: true` entry rather than duplicating. Merges into existing file content — other keys (permissions, other hooks) are preserved.
+
+Throws `Error('hook command is required')` if `command` is falsy.
+
+Hook entry written:
+```json
+{
+  "matcher": "Edit|Write",
+  "hooks": [{ "type": "command", "command": "<command>" }],
+  "_contextkit": true
+}
+```
+
+### `removeContextKitHooks() → Promise<void>`
+
+Removes all `PostToolUse` entries where `_contextkit: true`. If the array becomes empty, deletes the `PostToolUse` key. If `hooks` becomes empty, deletes the `hooks` key. No-op if the file is absent.
+
+## Usage Example
+
+```javascript
+const ClaudeSettings = require('./claude-settings');
+
+const cs = new ClaudeSettings();
+await cs.addPostToolUseHook('pnpm run format && pnpm run lint --fix 2>&1 | tail -20');
+// → writes .claude/settings.json, merging into existing content
+```
+
+## Edge Cases & Notes
+
+- `PostToolUse` that is not an array: the original value is preserved under `_contextkit_original_invalid`, and a fresh array is started for ContextKit's entry
+- Invalid JSON in existing file: returns `{}` with a warning — the file is NOT overwritten (protects corrupted user files)
+- Thread safety: no file locking; not a concern for a CLI tool

package/lib/utils/hook-detector.js

@@ -0,0 +1,138 @@
+const fs = require('fs-extra');
+const path = require('path');
+const { execSync } = require('child_process');
+
+class HookDetector {
+  _commandExists(name) {
+    try {
+      execSync(`which ${name}`, { stdio: 'ignore' });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  _pmPrefix(pm) {
+    switch (pm) {
+      case 'pnpm':
+        return 'pnpm run';
+      case 'yarn':
+        return 'yarn';
+      case 'bun':
+        return 'bun run';
+      default:
+        return 'npm run';
+    }
+  }
+
+  _lintFixCmd(pm, hasLintFix, hasLint) {
+    if (hasLintFix) {
+      switch (pm) {
+        case 'yarn':
+          return 'yarn lint:fix';
+        default:
+          return `${this._pmPrefix(pm)} lint:fix`;
+      }
+    }
+    if (hasLint) {
+      switch (pm) {
+        case 'pnpm':
+          return 'pnpm run lint --fix';
+        case 'yarn':
+          return 'yarn lint --fix';
+        case 'bun':
+          return 'bun run lint --fix';
+        default:
+          return 'npm run lint -- --fix';
+      }
+    }
+    return null;
+  }
+
+  async _detectNode(projectDir) {
+    const pkgPath = path.join(projectDir, 'package.json');
+    if (!(await fs.pathExists(pkgPath))) return null;
+
+    let packageJson;
+    try {
+      const raw = await fs.readFile(pkgPath, 'utf8');
+      packageJson = JSON.parse(raw);
+    } catch {
+      return null;
+    }
+
+    const scripts = packageJson.scripts || {};
+
+    let pm = 'npm';
+    if (await fs.pathExists(path.join(projectDir, 'bun.lockb'))) {
+      pm = 'bun';
+    } else if (await fs.pathExists(path.join(projectDir, 'pnpm-lock.yaml'))) {
+      pm = 'pnpm';
+    } else if (await fs.pathExists(path.join(projectDir, 'yarn.lock'))) {
+      pm = 'yarn';
+    }
+
+    const hasFormat = Boolean(scripts.format);
+    const hasLintFix = Boolean(scripts['lint:fix']);
+    const hasLint = Boolean(scripts.lint);
+
+    const parts = [];
+
+    if (hasFormat) {
+      const prefix = this._pmPrefix(pm);
+      parts.push(pm === 'yarn' ? `yarn format` : `${prefix} format`);
+    }
+
+    const lintCmd = this._lintFixCmd(pm, hasLintFix, hasLint);
+    if (lintCmd) {
+      parts.push(lintCmd);
+    }
+
+    if (parts.length === 0) return null;
+
+    return parts.join(' && ') + ' 2>&1 | tail -20';
+  }
+
+  async _detectGo(projectDir) {
+    if (!(await fs.pathExists(path.join(projectDir, 'go.mod')))) return null;
+
+    const parts = [];
+    if (this._commandExists('gofmt')) parts.push('gofmt -w .');
+    if (this._commandExists('golangci-lint')) parts.push('golangci-lint run 2>&1 | tail -20');
+
+    if (parts.length === 0) return null;
+
+    const cmd = parts.join(' && ');
+    // If only gofmt, add tail ourselves; if golangci-lint is present, it already has tail
+    return parts.length === 1 && parts[0] === 'gofmt -w .' ? cmd : cmd;
+  }
+
+  async _detectPython(projectDir) {
+    const hasPyproject = await fs.pathExists(path.join(projectDir, 'pyproject.toml'));
+    const hasRequirements = await fs.pathExists(path.join(projectDir, 'requirements.txt'));
+    if (!hasPyproject && !hasRequirements) return null;
+
+    const parts = [];
+    if (this._commandExists('black')) parts.push('black .');
+    if (this._commandExists('ruff')) parts.push('ruff check --fix . 2>&1 | tail -20');
+
+    if (parts.length === 0) return null;
+
+    return parts.join(' && ');
+  }
+
+  async detect(projectDir = process.cwd()) {
+    const node = await this._detectNode(projectDir);
+    if (node) return node;
+
+    const go = await this._detectGo(projectDir);
+    if (go) return go;
+
+    const python = await this._detectPython(projectDir);
+    if (python) return python;
+
+    return null;
+  }
+}
+
+module.exports = HookDetector;

package/lib/utils/hook-detector.md

@@ -0,0 +1,42 @@
+# hook-detector.js
+
+Detects the right PostToolUse hook command for a project based on its language, package manager, and available scripts.
+
+## Exports
+
+`HookDetector` — class
+
+## Public API
+
+### `detect(projectDir = process.cwd()) → Promise<string | null>`
+
+Returns a shell command string suitable for use as a Claude Code PostToolUse hook, or `null` if no format/lint tooling is detected.
+
+Tries three detectors in order: Node.js → Go → Python.
+
+## Usage Example
+
+```javascript
+const HookDetector = require('./hook-detector');
+
+const command = await new HookDetector().detect('/path/to/project');
+// → "pnpm run format && pnpm run lint --fix 2>&1 | tail -20"
+// → null (if no tooling found)
+```
+
+## Detection Logic
+
+| Stack | Trigger | PM detection | Command built from |
+|---|---|---|---|
+| Node.js | `package.json` exists | lockfile (`bun.lockb` > `pnpm-lock.yaml` > `yarn.lock` > `npm`) | `scripts.format`, `scripts['lint:fix']`, `scripts.lint` |
+| Go | `go.mod` exists | n/a | `gofmt` and/or `golangci-lint` (via `which`) |
+| Python | `pyproject.toml` or `requirements.txt` | n/a | `black` and/or `ruff` (via `which`) |
+
+For Node.js: `lint:fix` takes priority over `lint`. If only `lint` is present, `--fix` is appended (npm uses `-- --fix` separator; pnpm/yarn/bun pass args directly).
+
+## Edge Cases & Notes
+
+- Malformed `package.json` → returns `null`, does not throw
+- No scripts in `package.json` → returns `null`
+- Go/Python tools not on PATH → returns `null`
+- Node.js takes priority when multiple stack markers coexist

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nolrm/contextkit",
-  "version": "0.16.4",
+  "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.",
   "main": "lib/index.js",
   "bin": {