@nolrm/contextkit 0.14.0 → 0.15.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). 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). Skills in `.claude/skills/`.
 
 ```bash
 /analyze    # scan codebase and generate standards
@@ -171,7 +171,7 @@ ContextKit installs reusable slash commands for supported platforms:
 | `/context-budget`         | Prioritized guide for which standards files to load for a given task                                                            |
 | `/standards-aware`        | Decide whether and how to add a newly discovered pattern to the project's standards files                                       |
 
-**Claude Code** — available as `/analyze`, `/review`, etc. in `.claude/commands/`
+**Claude Code** — available as `/analyze`, `/review`, etc. via `.claude/skills/`
 **Cursor** — available as slash commands in Chat via `.cursor/prompts/`
 
 Both platforms delegate to the universal command files in `.contextkit/commands/`, so you maintain one set of workflows.

package/bin/contextkit.js

@@ -7,7 +7,6 @@ const analyze = require('../lib/commands/analyze');
 const check = require('../lib/commands/check');
 const note = require('../lib/commands/note');
 const run = require('../lib/commands/run');
-const GatesCommand = require('../lib/commands/gates');
 
 const packageJson = require('../package.json');
 const { checkForUpdates } = require('../lib/utils/notifier');
@@ -113,23 +112,6 @@ program
     }
   });
 
-// Gates command
-program
-  .command('gates')
-  .description('Inspect and manage quality gate configuration')
-  .option('--disable <key>', 'Disable a specific gate by key')
-  .option('--enable <key>', 'Enable a specific gate by key')
-  .option('--list', 'List all gates and their status (default)')
-  .action(async (options) => {
-    try {
-      const cmd = new GatesCommand();
-      await cmd.run(options);
-    } catch (error) {
-      console.error(chalk.red('Gates command failed:'), error.message);
-      process.exit(1);
-    }
-  });
-
 // Run command
 program
   .command('run <workflow>')

package/lib/commands/install.js

@@ -69,6 +69,7 @@ class InstallCommand {
       console.log(chalk.blue(`🔧 Adding ${requestedPlatform} integration...`));
       console.log('');
       await this.installPlatformIntegration(requestedPlatform);
+      await this.addContextKitGitignoreEntries();
       return;
     }
 
@@ -153,6 +154,9 @@ class InstallCommand {
       await this.installPlatformIntegration(chosenPlatform);
     }
 
+    // Add ephemeral ContextKit entries to .gitignore
+    await this.addContextKitGitignoreEntries();
+
     // Success message
     this.showSuccessMessage(hookChoices, chosenPlatform, projectType, packageManager);
   }
@@ -184,6 +188,31 @@ class InstallCommand {
     }
   }
 
+  async addContextKitGitignoreEntries() {
+    if (!(await fs.pathExists('.gitignore'))) return;
+
+    const entries = [
+      '.contextkit/status.json',
+      '.contextkit/status.yml',
+      '.contextkit/context.md',
+      '.contextkit/squad/',
+      '.contextkit/squad-done-*/',
+    ];
+
+    try {
+      const content = await fs.readFile('.gitignore', 'utf-8');
+      const missing = entries.filter((e) => !content.includes(e));
+      if (missing.length === 0) return;
+
+      const hasHeader = content.includes('# ContextKit');
+      const header = hasHeader ? '' : '\n# ContextKit\n';
+      const separator = content.endsWith('\n') ? '' : '\n';
+      await fs.appendFile('.gitignore', `${separator}${header}${missing.join('\n')}\n`);
+    } catch (error) {
+      console.log(chalk.yellow('⚠️  Could not update .gitignore:'), error.message);
+    }
+  }
+
   showPlatformUsage(platform) {
     const { getIntegration } = require('../integrations');
     const integration = getIntegration(platform);

package/lib/commands/update.js

@@ -86,7 +86,11 @@ class UpdateCommand {
       await this.refreshIntegrations();
 
       // Update version in config
-      await this.updateConfigVersion(updateInfo.latestVersion || '1.0.0');
+      await this.updateConfigVersion(
+        updateInfo.latestVersion && updateInfo.latestVersion !== 'unknown'
+          ? updateInfo.latestVersion
+          : require('../../package.json').version
+      );
 
       console.log(chalk.green('✅ ContextKit updated successfully!'));
     } catch (error) {
@@ -102,16 +106,15 @@ class UpdateCommand {
   }
 
   async checkForUpdates() {
+    const pkg = require('../../package.json');
     try {
       const axios = require('axios');
       const response = await axios.get(
-        'https://api.github.com/repos/nolrm/contextkit/releases/latest',
-        {
-          timeout: 5000,
-        }
+        `https://registry.npmjs.org/${pkg.name}/latest`,
+        { timeout: 5000 }
       );
 
-      const latestVersion = response.data.tag_name.replace('v', '');
+      const latestVersion = response.data.version;
       const currentVersion = await this.getCurrentVersion();
       const hasUpdate = this.isNewerVersion(latestVersion, currentVersion);
 
@@ -121,10 +124,11 @@ class UpdateCommand {
         latestVersion,
       };
     } catch (error) {
+      // Can't reach npm registry — skip update rather than blindly running
       return {
-        hasUpdate: true, // Assume update available if we can't check
+        hasUpdate: false,
         currentVersion: await this.getCurrentVersion(),
-        latestVersion: 'latest',
+        latestVersion: 'unknown',
         error: error.message,
       };
     }
@@ -133,9 +137,9 @@ class UpdateCommand {
   async getCurrentVersion() {
     try {
       const config = await this.parseConfig();
-      return config.version || '1.0.0';
+      return config.version || require('../../package.json').version;
     } catch {
-      return '1.0.0';
+      return require('../../package.json').version;
     }
   }
 

package/lib/index.js

@@ -1,11 +1,9 @@
 const install = require('./commands/install');
 const update = require('./commands/update');
 const status = require('./commands/status');
-const GatesCommand = require('./commands/gates');
 
 module.exports = {
   install,
   update,
   status,
-  gates: GatesCommand,
 };

package/lib/integrations/claude-integration.js

@@ -11,6 +11,59 @@ class ClaudeIntegration extends BaseIntegration {
       '.claude/rules/contextkit-standards.md',
       '.claude/rules/contextkit-testing.md',
       '.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',
+      '.claude/skills/squad/SKILL.md',
+      '.claude/skills/squad-architect/SKILL.md',
+      '.claude/skills/squad-dev/SKILL.md',
+      '.claude/skills/squad-test/SKILL.md',
+      '.claude/skills/squad-review/SKILL.md',
+      '.claude/skills/squad-auto/SKILL.md',
+      '.claude/skills/squad-auto-parallel/SKILL.md',
+      '.claude/skills/squad-reset/SKILL.md',
+      '.claude/skills/squad-doc/SKILL.md',
+      '.claude/skills/spec/SKILL.md',
+      '.claude/skills/ck/SKILL.md',
+      '.claude/skills/doc-arch/SKILL.md',
+      '.claude/skills/doc-feature/SKILL.md',
+      '.claude/skills/doc-component/SKILL.md',
+      '.claude/skills/agent-push-checklist/SKILL.md',
+      '.claude/skills/context-budget/SKILL.md',
+      '.claude/skills/standards-aware/SKILL.md',
+    ];
+    this.platformDir = '.claude/rules';
+  }
+
+  async install() {
+    await super.install();
+    const fs = require('fs-extra');
+    await fs.ensureDir('.claude/skills');
+    await this.addToGitignore('.claude/settings.local.json');
+    await this.removeLegacyFiles();
+  }
+
+  async addToGitignore(entry) {
+    const fs = require('fs-extra');
+    if (!fs.existsSync('.gitignore')) return;
+    const content = await fs.readFile('.gitignore', 'utf-8');
+    if (content.includes(entry)) return;
+    const separator = content.endsWith('\n') ? '' : '\n';
+    await fs.appendFile('.gitignore', `${separator}${entry}\n`);
+  }
+
+  async removeLegacyFiles() {
+    const fs = require('fs-extra');
+    const legacyFiles = [
+      '.claude/rules/vibe-kit-standards.md',
+      '.claude/rules/vibe-kit-testing.md',
+      '.claude/rules/vibe-kit-code-style.md',
+      '.claude/commands/squad-batch.md',
+      '.claude/commands/squad-peer-review.md',
+      // Migrated to .claude/skills/ in 0.15.0
       '.claude/commands/analyze.md',
       '.claude/commands/review.md',
       '.claude/commands/fix.md',
@@ -31,25 +84,9 @@ class ClaudeIntegration extends BaseIntegration {
       '.claude/commands/doc-arch.md',
       '.claude/commands/doc-feature.md',
       '.claude/commands/doc-component.md',
-    ];
-    this.platformDir = '.claude/rules';
-  }
-
-  async install() {
-    await super.install();
-    const fs = require('fs-extra');
-    await fs.ensureDir('.claude/commands');
-    await this.removeLegacyFiles();
-  }
-
-  async removeLegacyFiles() {
-    const fs = require('fs-extra');
-    const legacyFiles = [
-      '.claude/rules/vibe-kit-standards.md',
-      '.claude/rules/vibe-kit-testing.md',
-      '.claude/rules/vibe-kit-code-style.md',
-      '.claude/commands/squad-batch.md',
-      '.claude/commands/squad-peer-review.md',
+      '.claude/commands/agent-push-checklist.md',
+      '.claude/commands/context-budget.md',
+      '.claude/commands/standards-aware.md',
     ];
     for (const file of legacyFiles) {
       if (await fs.pathExists(file)) {
@@ -78,11 +115,11 @@ The following standards are auto-loaded into context via @imports:
 
 ## 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`;
+- \`.contextkit/commands/dev/analyze.md\` — Analyze and customize standards
+- \`.contextkit/commands/dev/create-component.md\` — Create components
+- \`.contextkit/commands/dev/create-feature.md\` — Create features
+- \`.contextkit/commands/dev/run-tests.md\` — Run tests
+- \`.contextkit/commands/dev/quality-check.md\` — Quality checks`;
   }
 
   async generateFiles() {
@@ -163,83 +200,137 @@ Follow the code style standards auto-loaded via CLAUDE.md (from code-style.md).
 `;
     await this.writeGeneratedFile('.claude/rules/contextkit-code-style.md', codeStyleRule);
 
-    // Slash commands — thin wrappers that delegate to .contextkit/commands/
+    // Skills — delegate to .contextkit/commands/ with rich frontmatter for Claude Code
     await this.writeGeneratedFile(
-      '.claude/commands/analyze.md',
-      `# Analyze Project
+      '.claude/skills/analyze/SKILL.md',
+      `---
+description: Analyze project and generate customized standards
+argument-hint: "[optional: scope or package path]"
+allowed-tools: Read, Glob, Grep, Write, Bash
+effort: high
+---
 
-Read \`.contextkit/commands/analyze.md\` and execute the analysis workflow for this project.
+Read \`.contextkit/commands/dev/analyze.md\` and execute the analysis workflow for this project.
 
 Scan the codebase structure, detect frameworks and patterns, then generate customized standards files in \`.contextkit/standards/\`.
 `
     );
 
     await this.writeGeneratedFile(
-      '.claude/commands/review.md',
-      `# Code Review
+      '.claude/skills/review/SKILL.md',
+      `---
+description: Review current changes for correctness and standards compliance
+argument-hint: "[optional: file or directory]"
+allowed-tools: Read, Glob, Grep, Bash
+effort: normal
+---
 
-Read \`.contextkit/commands/review.md\` and execute the review workflow.
+Read \`.contextkit/commands/dev/review.md\` and execute the review workflow.
 
 Review current changes for correctness, standards compliance, and potential issues.
 `
     );
 
     await this.writeGeneratedFile(
-      '.claude/commands/fix.md',
-      `# Fix Bug
+      '.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/fix.md\` and execute the bug fix workflow.
+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/commands/refactor.md',
-      `# Refactor
+      '.claude/skills/refactor/SKILL.md',
+      `---
+description: Improve code structure without changing behavior
+argument-hint: "[optional: file or scope]"
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash
+effort: normal
+---
 
-Read \`.contextkit/commands/refactor.md\` and execute the refactoring workflow.
+Read \`.contextkit/commands/dev/refactor.md\` and execute the refactoring workflow.
 
 Improve code structure without changing behavior, keeping tests green at every step.
 `
     );
 
     await this.writeGeneratedFile(
-      '.claude/commands/test.md',
-      `# Run Tests
+      '.claude/skills/test/SKILL.md',
+      `---
+description: Generate or run tests covering happy paths, edge cases, and errors
+argument-hint: "[optional: file or function]"
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash
+effort: normal
+---
 
-Read \`.contextkit/commands/run-tests.md\` and execute the testing workflow.
+Read \`.contextkit/commands/dev/run-tests.md\` and execute the testing workflow.
 
 Generate or run tests for the specified code, covering happy paths, edge cases, and errors.
 `
     );
 
     await this.writeGeneratedFile(
-      '.claude/commands/doc.md',
-      `# Add Documentation
+      '.claude/skills/doc/SKILL.md',
+      `---
+description: Add inline docs, README sections, and usage examples
+argument-hint: "[optional: file or module]"
+allowed-tools: Read, Edit, Write, Glob, Grep
+effort: normal
+---
 
-Read \`.contextkit/commands/add-documentation.md\` and execute the documentation workflow.
+Read \`.contextkit/commands/docs/add-documentation.md\` and execute the documentation workflow.
 
 Add inline docs, README sections, and usage examples for the specified code.
 `
     );
 
     await this.writeGeneratedFile(
-      '.claude/commands/spec.md',
-      `# Spec
+      '.claude/skills/spec/SKILL.md',
+      `---
+description: Write a component spec (MD-first) before coding begins
+argument-hint: "<component or feature name>"
+allowed-tools: Read, Write, Glob, Grep
+effort: normal
+---
 
-Read \`.contextkit/commands/spec.md\` and execute the spec workflow.
+Read \`.contextkit/commands/dev/spec.md\` and execute the 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.
 `
     );
 
-    // Squad slash commands
     await this.writeGeneratedFile(
-      '.claude/commands/squad.md',
-      `# Squad — Kickoff (start here)
+      '.claude/skills/ck/SKILL.md',
+      `---
+description: Check project setup, standards status, and integrations
+allowed-tools: Read, Glob, Grep, Bash
+effort: low
+---
+
+Read \`.contextkit/commands/dev/health-check.md\` and execute the health check workflow.
+
+Check project setup, standards status, and integrations. Report what needs attention.
+`
+    );
+
+    // Squad skills
+    await this.writeGeneratedFile(
+      '.claude/skills/squad/SKILL.md',
+      `---
+description: Squad pipeline kickoff — create handoff file and write PO spec
+argument-hint: '"<task description>"'
+allowed-tools: Read, Write, Glob, Grep
+effort: normal
+---
 
-Read \`.contextkit/commands/squad.md\` and execute the squad kickoff workflow.
+Read \`.contextkit/commands/squad/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.
 
@@ -248,101 +339,130 @@ After kickoff, run \`/squad-auto\` to auto-run the full pipeline hands-free, or
     );
 
     await this.writeGeneratedFile(
-      '.claude/commands/squad-architect.md',
-      `# Squad — Architect (manual step 1/4)
+      '.claude/skills/squad-architect/SKILL.md',
+      `---
+description: Write technical implementation plan from PO spec (manual step 1/4)
+allowed-tools: Read, Write, Glob, Grep, Bash
+effort: normal
+---
 
-Read \`.contextkit/commands/squad-architect.md\` and execute the architect workflow.
+Read \`.contextkit/commands/squad/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. Use \`/squad-auto\` instead to run all steps automatically.
 `
     );
 
     await this.writeGeneratedFile(
-      '.claude/commands/squad-dev.md',
-      `# Squad — Dev (manual step 2/4)
+      '.claude/skills/squad-dev/SKILL.md',
+      `---
+description: Implement code changes following architect plan (manual step 2/4)
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash
+effort: normal
+---
 
-Read \`.contextkit/commands/squad-dev.md\` and execute the dev workflow.
+Read \`.contextkit/commands/squad/squad-dev.md\` and execute the dev workflow.
 
 Follow the architect's plan to implement the code changes. Use \`/squad-auto\` instead to run all steps automatically.
 `
     );
 
     await this.writeGeneratedFile(
-      '.claude/commands/squad-test.md',
-      `# Squad — Test (manual step 3/4)
+      '.claude/skills/squad-test/SKILL.md',
+      `---
+description: Write and run tests against acceptance criteria (manual step 3/4)
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash
+effort: normal
+---
 
-Read \`.contextkit/commands/squad-test.md\` and execute the test workflow.
+Read \`.contextkit/commands/squad/squad-test.md\` and execute the test workflow.
 
 Write and run tests against the PO's acceptance criteria. Use \`/squad-auto\` instead to run all steps automatically.
 `
     );
 
     await this.writeGeneratedFile(
-      '.claude/commands/squad-review.md',
-      `# Squad — Review (manual step 4/4)
+      '.claude/skills/squad-review/SKILL.md',
+      `---
+description: Review full handoff and write pass/needs-work verdict (manual step 4/4)
+allowed-tools: Read, Write, Glob, Grep, Bash
+effort: normal
+---
 
-Read \`.contextkit/commands/squad-review.md\` and execute the review workflow.
+Read \`.contextkit/commands/squad/squad-review.md\` and execute the review workflow.
 
 Review the full handoff (spec, plan, implementation, tests) and write the final verdict. Use \`/squad-auto\` instead to run all steps automatically.
 `
     );
 
     await this.writeGeneratedFile(
-      '.claude/commands/squad-auto.md',
-      `# Squad Auto — Full Pipeline (recommended)
+      '.claude/skills/squad-auto/SKILL.md',
+      `---
+description: Auto-run full squad pipeline hands-free (architect → dev → test → review → doc)
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash
+effort: high
+context: fork
+---
 
-Read \`.contextkit/commands/squad-auto.md\` and execute the pipeline runner workflow.
+Read \`.contextkit/commands/squad/squad-auto.md\` and execute the pipeline runner workflow.
 
 Run after \`/squad\` kickoff. Automatically runs architect → dev → test → review for all tasks sequentially, hands-free.
 `
     );
 
     await this.writeGeneratedFile(
-      '.claude/commands/squad-auto-parallel.md',
-      `# Squad Auto — Parallel Agents (batch, fastest)
+      '.claude/skills/squad-auto-parallel/SKILL.md',
+      `---
+description: Auto-run squad pipeline with parallel agents — one per task per phase (fastest)
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash
+effort: high
+context: fork
+---
 
-Read \`.contextkit/commands/squad-auto-parallel.md\` and execute the parallel pipeline workflow.
+Read \`.contextkit/commands/squad/squad-auto-parallel.md\` and execute the parallel pipeline workflow.
 
 Spawn one subagent per task per phase using the Task tool, so all tasks progress simultaneously instead of sequentially. Use this after \`/squad\` batch kickoff for faster execution on multi-task batches.
 `
     );
 
     await this.writeGeneratedFile(
-      '.claude/commands/squad-reset.md',
-      `# Squad — Reset
+      '.claude/skills/squad-reset/SKILL.md',
+      `---
+description: Delete squad state to start fresh
+allowed-tools: Read, Write, Glob
+effort: low
+---
 
-Read \`.contextkit/commands/squad-reset.md\` and execute the reset workflow.
+Read \`.contextkit/commands/squad/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)
+      '.claude/skills/squad-doc/SKILL.md',
+      `---
+description: Document changes after review passes (manual step 5/5)
+allowed-tools: Read, Edit, Write, Glob, Grep
+effort: normal
+---
 
-Read \`.contextkit/commands/squad-doc.md\` and execute the doc workflow.
+Read \`.contextkit/commands/squad/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.
 `
     );
 
+    // Doc family skills
     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.
-`
-    );
-
-    // Doc family slash commands
-    await this.writeGeneratedFile(
-      '.claude/commands/doc-arch.md',
-      `# Doc — Architecture (Level 1)
+      '.claude/skills/doc-arch/SKILL.md',
+      `---
+description: Generate or update architecture documentation (Level 1)
+argument-hint: "[optional: PR number]"
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash
+effort: high
+---
 
-Read \`.contextkit/commands/doc-arch.md\` and execute the architecture documentation workflow.
+Read \`.contextkit/commands/docs/doc-arch.md\` and execute the architecture documentation workflow.
 
 Detect the project stack, then generate or update \`docs/architecture.md\` with system boundaries, key flows, and stack-appropriate artifacts (Mermaid diagrams, component trees, service maps).
 
@@ -351,10 +471,15 @@ Pass an optional PR number to scope to that PR's changes.
     );
 
     await this.writeGeneratedFile(
-      '.claude/commands/doc-feature.md',
-      `# Doc — Feature (Level 2)
+      '.claude/skills/doc-feature/SKILL.md',
+      `---
+description: Generate or update feature documentation (Level 2)
+argument-hint: "[optional: feature name, path, or PR number]"
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash
+effort: high
+---
 
-Read \`.contextkit/commands/doc-feature.md\` and execute the feature documentation workflow.
+Read \`.contextkit/commands/docs/doc-feature.md\` and execute the feature documentation workflow.
 
 Detect the project stack, identify the target feature from the argument or current branch, then generate or update \`docs/features/<name>.md\` with purpose, components/modules, data flow, and user flows.
 
@@ -363,14 +488,62 @@ Pass a feature name, directory path, or PR number to scope the documentation.
     );
 
     await this.writeGeneratedFile(
-      '.claude/commands/doc-component.md',
-      `# Doc — Component (Level 3)
+      '.claude/skills/doc-component/SKILL.md',
+      `---
+description: Generate or update component documentation (Level 3)
+argument-hint: "[optional: file path or directory]"
+allowed-tools: Read, Edit, Write, Glob, Grep
+effort: normal
+---
 
-Read \`.contextkit/commands/doc-component.md\` and execute the component documentation workflow.
+Read \`.contextkit/commands/docs/doc-component.md\` and execute the component documentation workflow.
 
 Detect the project stack, read the target file or directory, then create or update a colocated \`<name>.md\` with API/props, usage examples, behavior, and edge cases.
 
 Pass a file path or directory to target. Omit to infer from current context.
+`
+    );
+
+    // Agent skills
+    await this.writeGeneratedFile(
+      '.claude/skills/agent-push-checklist/SKILL.md',
+      `---
+description: Pre-push quality checklist for agents before git push
+allowed-tools: Read, Glob, Grep, Bash
+effort: low
+---
+
+Read \`.contextkit/commands/agents/agent-push-checklist.md\` and execute the agent push checklist workflow.
+
+Run before pushing from an AI agent. Validates that changes are safe, tests pass, and the push is ready.
+`
+    );
+
+    await this.writeGeneratedFile(
+      '.claude/skills/context-budget/SKILL.md',
+      `---
+description: Check context consumption and advise on compact, summarise, or continue
+allowed-tools: Read, Glob, Grep
+effort: low
+---
+
+Read \`.contextkit/commands/agents/context-budget.md\` and execute the context budget workflow.
+
+Check how much context has been consumed and advise on whether to compact, summarise, or continue.
+`
+    );
+
+    await this.writeGeneratedFile(
+      '.claude/skills/standards-aware/SKILL.md',
+      `---
+description: Load and apply project standards before acting in an agentic context
+allowed-tools: Read, Glob, Grep
+effort: low
+---
+
+Read \`.contextkit/commands/agents/standards-aware.md\` and execute the standards-aware workflow.
+
+Load and apply the project's ContextKit standards before taking action in an agentic context.
 `
     );
   }

package/lib/integrations/cursor-integration.js

@@ -132,8 +132,8 @@ Reference: @.contextkit/standards/code-style.md
 
 ## Commands
 
-- @.contextkit/commands/create-component.md — Create component workflow
-- @.contextkit/commands/spec.md — Write a component spec before coding
+- @.contextkit/commands/dev/create-component.md — Create component workflow
+- @.contextkit/commands/dev/spec.md — Write a component spec before coding
 `;
     await this.writeGeneratedFile('.cursor/rules/contextkit-components.mdc', componentsRule);
 
@@ -154,7 +154,7 @@ Reference: @.contextkit/standards/architecture.md
 
 ## Commands
 
-- @.contextkit/commands/create-feature.md — Create feature workflow
+- @.contextkit/commands/dev/create-feature.md — Create feature workflow
 `;
     await this.writeGeneratedFile('.cursor/rules/contextkit-api.mdc', apiRule);
 
@@ -163,7 +163,7 @@ Reference: @.contextkit/standards/architecture.md
       '.cursor/prompts/analyze.md',
       `# Analyze Project
 
-Read \`.contextkit/commands/analyze.md\` and execute the analysis workflow for this project.
+Read \`.contextkit/commands/dev/analyze.md\` and execute the analysis workflow for this project.
 
 Scan the codebase structure, detect frameworks and patterns, then generate customized standards files in \`.contextkit/standards/\`.
 `
@@ -173,7 +173,7 @@ Scan the codebase structure, detect frameworks and patterns, then generate custo
       '.cursor/prompts/review.md',
       `# Code Review
 
-Read \`.contextkit/commands/review.md\` and execute the review workflow.
+Read \`.contextkit/commands/dev/review.md\` and execute the review workflow.
 
 Review current changes for correctness, standards compliance, and potential issues. Flag bugs, security concerns, and standards violations.
 `
@@ -183,7 +183,7 @@ Review current changes for correctness, standards compliance, and potential issu
       '.cursor/prompts/fix.md',
       `# Fix Bug
 
-Read \`.contextkit/commands/fix.md\` and execute the bug fix workflow.
+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.
 `
@@ -193,7 +193,7 @@ Diagnose the root cause, implement the minimal fix, and add a regression test.
       '.cursor/prompts/refactor.md',
       `# Refactor
 
-Read \`.contextkit/commands/refactor.md\` and execute the refactoring workflow.
+Read \`.contextkit/commands/dev/refactor.md\` and execute the refactoring workflow.
 
 Improve code structure without changing behavior, keeping tests green at every step.
 `
@@ -203,7 +203,7 @@ Improve code structure without changing behavior, keeping tests green at every s
       '.cursor/prompts/test.md',
       `# Run Tests
 
-Read \`.contextkit/commands/run-tests.md\` and execute the testing workflow.
+Read \`.contextkit/commands/dev/run-tests.md\` and execute the testing workflow.
 
 Generate or run tests for the specified code, covering happy paths, edge cases, and errors.
 `
@@ -213,7 +213,7 @@ Generate or run tests for the specified code, covering happy paths, edge cases,
       '.cursor/prompts/doc.md',
       `# Add Documentation
 
-Read \`.contextkit/commands/add-documentation.md\` and execute the documentation workflow.
+Read \`.contextkit/commands/docs/add-documentation.md\` and execute the documentation workflow.
 
 Add inline docs, README sections, and usage examples for the specified code.
 `
@@ -224,7 +224,7 @@ Add inline docs, README sections, and usage examples for the specified code.
       '.cursor/prompts/squad.md',
       `# Squad — Kickoff
 
-Read \`.contextkit/commands/squad.md\` and execute the squad kickoff workflow.
+Read \`.contextkit/commands/squad/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.
 `
@@ -234,7 +234,7 @@ Create the handoff file and write the PO spec for the given task. Pass the user'
       '.cursor/prompts/squad-architect.md',
       `# Squad — Architect
 
-Read \`.contextkit/commands/squad-architect.md\` and execute the architect workflow.
+Read \`.contextkit/commands/squad/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.
 `
@@ -244,7 +244,7 @@ Read the PO spec from the handoff file, design the technical approach, and write
       '.cursor/prompts/squad-dev.md',
       `# Squad — Dev
 
-Read \`.contextkit/commands/squad-dev.md\` and execute the dev workflow.
+Read \`.contextkit/commands/squad/squad-dev.md\` and execute the dev workflow.
 
 Follow the architect's plan to implement the code changes.
 `
@@ -254,7 +254,7 @@ Follow the architect's plan to implement the code changes.
       '.cursor/prompts/squad-test.md',
       `# Squad — Test
 
-Read \`.contextkit/commands/squad-test.md\` and execute the test workflow.
+Read \`.contextkit/commands/squad/squad-test.md\` and execute the test workflow.
 
 Write and run tests against the PO's acceptance criteria.
 `
@@ -264,7 +264,7 @@ Write and run tests against the PO's acceptance criteria.
       '.cursor/prompts/squad-review.md',
       `# Squad — Review
 
-Read \`.contextkit/commands/squad-review.md\` and execute the review workflow.
+Read \`.contextkit/commands/squad/squad-review.md\` and execute the review workflow.
 
 Review the full handoff (spec, plan, implementation, tests) and write the final verdict.
 `
@@ -274,7 +274,7 @@ Review the full handoff (spec, plan, implementation, tests) and write the final
       '.cursor/prompts/squad-auto.md',
       `# Squad Auto — Full Pipeline (recommended)
 
-Read \`.contextkit/commands/squad-auto.md\` and execute the pipeline runner workflow.
+Read \`.contextkit/commands/squad/squad-auto.md\` and execute the pipeline runner workflow.
 
 Run after kickoff. Automatically runs architect → dev → test → review for all tasks sequentially, hands-free.
 `
@@ -284,7 +284,7 @@ Run after kickoff. Automatically runs architect → dev → test → review for
       '.cursor/prompts/spec.md',
       `# Spec
 
-Read \`.contextkit/commands/spec.md\` and execute the spec workflow.
+Read \`.contextkit/commands/dev/spec.md\` and execute the 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.
 `
@@ -294,7 +294,7 @@ Write a component spec (MD-first) before any code is created. Scaffold the spec
       '.cursor/prompts/ck.md',
       `# ContextKit Health Check
 
-Read \`.contextkit/commands/health-check.md\` and execute the health check workflow.
+Read \`.contextkit/commands/dev/health-check.md\` and execute the health check workflow.
 
 Check project setup, standards status, and integrations. Report what needs attention.
 `

package/lib/utils/migrations.js

@@ -11,7 +11,10 @@ class MigrationRunner {
    * @param {string} configPath - path to config.yml
    */
   async run(currentVersion, configPath) {
-    const from = currentVersion === undefined || currentVersion === null ? 0 : currentVersion;
+    const from =
+      currentVersion === undefined || currentVersion === null || Number.isNaN(currentVersion)
+        ? 0
+        : currentVersion;
 
     if (from > CURRENT_FORMAT_VERSION) {
       console.log(

package/package.json

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

package/lib/commands/gates.js

@@ -1,119 +0,0 @@
-const chalk = require('chalk');
-const fs = require('fs-extra');
-const yaml = require('js-yaml');
-
-const KNOWN_GATES = {
-  'Node.js': ['typescript', 'eslint', 'prettier', 'format', 'lint', 'build', 'test', 'e2e'],
-  Python: ['ruff-lint', 'typecheck', 'ruff-format', 'pytest'],
-  Rust: ['cargo-check', 'clippy', 'cargo-test'],
-  Go: ['go-vet', 'golangci-lint', 'go-test'],
-  PHP: ['phpstan', 'phpunit'],
-  Ruby: ['rubocop', 'rspec'],
-  'Java / Kotlin': ['maven-verify', 'gradle-check', 'ktlint', 'kotlin-test'],
-  Swift: ['swiftlint', 'swift-test'],
-  '.NET': ['dotnet-build', 'dotnet-test'],
-};
-
-const ALL_GATE_KEYS = Object.values(KNOWN_GATES).flat();
-const GATES_CONFIG_PATH = '.contextkit/quality-gates.yml';
-
-class GatesCommand {
-  async run(options = {}) {
-    if (!(await fs.pathExists('.contextkit/config.yml'))) {
-      console.log(chalk.red('ContextKit not installed. Run: ck install'));
-      process.exit(1);
-    }
-
-    if (options.disable) {
-      await this.disable(options.disable);
-    } else if (options.enable) {
-      await this.enable(options.enable);
-    } else {
-      await this.list();
-    }
-  }
-
-  async list() {
-    const disabled = await this.readDisabled();
-    console.log(chalk.bold('\nQuality Gates\n'));
-    for (const [stack, keys] of Object.entries(KNOWN_GATES)) {
-      console.log(chalk.cyan(`  ${stack}`));
-      for (const key of keys) {
-        const isDisabled = disabled.includes(key);
-        const status = isDisabled ? chalk.yellow('[disabled]') : chalk.green('[enabled] ');
-        console.log(`    ${status}  ${key}`);
-      }
-    }
-    console.log('');
-    console.log(chalk.yellow('  To disable a gate: ck gates --disable <key>'));
-    console.log(chalk.yellow('  To enable a gate:  ck gates --enable <key>'));
-    console.log('');
-  }
-
-  async disable(key) {
-    if (!ALL_GATE_KEYS.includes(key)) {
-      this.printInvalidKey(key);
-      process.exit(1);
-    }
-    const disabled = await this.readDisabled();
-    if (disabled.includes(key)) {
-      console.log(chalk.yellow(`Gate "${key}" is already disabled.`));
-      return;
-    }
-    disabled.push(key);
-    await this.writeDisabled(disabled);
-    console.log(chalk.green(`✅ Gate "${key}" disabled.`));
-  }
-
-  async enable(key) {
-    if (!ALL_GATE_KEYS.includes(key)) {
-      this.printInvalidKey(key);
-      process.exit(1);
-    }
-    const disabled = await this.readDisabled();
-    const idx = disabled.indexOf(key);
-    if (idx === -1) {
-      console.log(chalk.yellow(`Gate "${key}" is already enabled.`));
-      return;
-    }
-    disabled.splice(idx, 1);
-    await this.writeDisabled(disabled);
-    console.log(chalk.green(`✅ Gate "${key}" enabled.`));
-  }
-
-  async readDisabled() {
-    if (!(await fs.pathExists(GATES_CONFIG_PATH))) return [];
-    try {
-      const content = await fs.readFile(GATES_CONFIG_PATH, 'utf-8');
-      const parsed = yaml.load(content);
-      return Array.isArray(parsed && parsed.disabled) ? parsed.disabled : [];
-    } catch (err) {
-      console.error(chalk.red('Error reading quality-gates.yml:'), err.message);
-      process.exit(1);
-    }
-  }
-
-  async writeDisabled(disabled) {
-    if (!(await fs.pathExists(GATES_CONFIG_PATH))) {
-      await fs.writeFile(GATES_CONFIG_PATH, `# Quality Gates Configuration\n\ndisabled:\n`);
-    }
-    const content = await fs.readFile(GATES_CONFIG_PATH, 'utf-8');
-    // Replace or append the disabled block, preserving comments above it
-    const withoutDisabled = content.replace(/^disabled:[\s\S]*$/m, '').trimEnd();
-    const disabledBlock =
-      disabled.length > 0
-        ? `\ndisabled:\n${disabled.map((k) => `  - ${k}`).join('\n')}\n`
-        : `\ndisabled:\n`;
-    await fs.writeFile(GATES_CONFIG_PATH, withoutDisabled + disabledBlock);
-  }
-
-  printInvalidKey(key) {
-    console.error(chalk.red(`Unknown gate key: "${key}"`));
-    console.log(chalk.yellow('\nValid gate keys:'));
-    for (const [stack, keys] of Object.entries(KNOWN_GATES)) {
-      console.log(chalk.cyan(`  ${stack}: `) + keys.join(', '));
-    }
-  }
-}
-
-module.exports = GatesCommand;