@nolrm/contextkit 0.13.2 → 0.13.4

package/README.md

@@ -142,6 +142,9 @@ ContextKit installs reusable slash commands for supported platforms:
 | `/refactor` | Refactor code with safety checks |
 | `/test` | Generate comprehensive tests |
 | `/doc` | Add documentation |
+| `/doc-arch` | Generate architecture docs (`docs/architecture.md`) — stack-aware (Level 1) |
+| `/doc-feature` | Generate feature-level docs (`docs/features/<name>.md`) — stack-aware (Level 2) |
+| `/doc-component` | Generate component-level docs colocated with the target file — stack-aware (Level 3) |
 | `/spec` | Write a component spec (MD-first) before any code is created |
 | `/squad` | Kick off a squad task — one task or many (auto-detects batch mode). Pushes back with clarifying questions if the task is vague. |
 | `/squad-architect` | Design the technical plan from the PO spec |
@@ -284,6 +287,36 @@ Hooks are optional and can be skipped with `ck install --no-hooks`.
 
 ---
 
+## CI Squad — GitHub Issues → PR
+
+ContextKit can automatically turn GitHub issues into pull requests — no local development required.
+
+**How it works:**
+
+1. Label any issue `squad-ready`
+2. GitHub Actions runs the full squad pipeline (architect → dev → test → review) using Claude
+3. A draft PR is opened, linked to the issue
+
+**Setup:**
+
+```bash
+ck install   # answer "yes" to the CI squad prompt
+```
+
+Then add your Anthropic API key as a repository secret:
+
+> **Settings → Secrets and variables → Actions → New repository secret**
+> Name: `ANTHROPIC_API_KEY`
+
+**Tips:**
+
+- Write issues with clear acceptance criteria for the best results
+- If the issue is too vague, the workflow posts a comment asking for clarification instead of generating a bad PR
+- PRs always open as **draft** — you review and merge manually
+- Re-apply the `squad-ready` label after answering a clarification comment to re-trigger the pipeline
+
+---
+
 ## Key Features
 
 - 🧠 **Context Engineering** - Structured MD files your AI reads automatically

package/lib/commands/install.js

@@ -114,11 +114,20 @@ class InstallCommand {
       await this.gitHooksManager.installHooks(packageManager, hookChoices);
     }
 
+    // Ask about GitHub Actions CI squad workflow
+    let squadCi = false;
+    if (!options.nonInteractive) {
+      squadCi = await this.promptGitHubActionsWorkflow();
+    }
+    if (squadCi) {
+      await this.installGitHubActionsWorkflow();
+    }
+
     // Create configuration
-    await this.createConfiguration(projectType, hookChoices);
+    await this.createConfiguration(projectType, hookChoices, squadCi);
 
     // Create status tracking
-    await this.createStatusFile(projectType, packageManager, hookChoices);
+    await this.createStatusFile(projectType, packageManager, hookChoices, squadCi);
 
     // Determine which platform to install
     let chosenPlatform = requestedPlatform || null;
@@ -204,6 +213,56 @@ class InstallCommand {
     return platform;
   }
 
+  async promptGitHubActionsWorkflow() {
+    if (process.env.CI === 'true' || process.env.NON_INTERACTIVE === 'true') {
+      return false;
+    }
+
+    console.log('');
+    console.log('──────────────────────────────────────────────');
+    console.log(chalk.blue('🤖  CI Squad — GitHub Issues → PR'));
+    console.log('──────────────────────────────────────────────');
+    console.log('');
+    console.log(chalk.dim('Label any GitHub issue `squad-ready` and ContextKit will'));
+    console.log(chalk.dim('automatically create a branch, run the full squad pipeline'));
+    console.log(chalk.dim('(architect → dev → test → review), and open a draft PR.'));
+    console.log('');
+    console.log(chalk.dim('Requires: ANTHROPIC_API_KEY secret in your repo settings.'));
+    console.log('');
+
+    const { squadCi } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'squadCi',
+        message: 'Install GitHub Actions workflow for issue-triggered squad automation?',
+        default: false,
+      },
+    ]);
+
+    if (squadCi) {
+      console.log(chalk.green('  ✅ CI squad workflow will be installed'));
+      console.log(chalk.blue('  💡 Add ANTHROPIC_API_KEY to: Settings → Secrets → Actions'));
+    } else {
+      console.log(chalk.yellow('  ⏭️  Skipping CI squad workflow'));
+    }
+    console.log('');
+
+    return squadCi;
+  }
+
+  async installGitHubActionsWorkflow() {
+    try {
+      await fs.ensureDir('.github/workflows');
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/templates/github-actions/squad-issue.yml`,
+        '.github/workflows/squad-issue.yml'
+      );
+      console.log(chalk.green('✅ CI squad workflow installed → .github/workflows/squad-issue.yml'));
+    } catch (error) {
+      console.log(chalk.yellow('⚠️  Could not install CI squad workflow:'), error.message);
+    }
+  }
+
   async promptGitHooks() {
     // Check for non-interactive mode
     if (process.env.CI === 'true' || process.env.NON_INTERACTIVE === 'true') {
@@ -738,11 +797,29 @@ Any design decisions, trade-offs, or open questions to resolve before coding.
         `${this.repoUrl}/commands/squad-doc.md`,
         '.contextkit/commands/squad-doc.md'
       );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/squad-ci.md`,
+        '.contextkit/commands/squad-ci.md'
+      );
       await this.downloadManager.downloadFile(
         `${this.repoUrl}/commands/health-check.md`,
         '.contextkit/commands/health-check.md'
       );
 
+      // Download doc family commands
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/doc-arch.md`,
+        '.contextkit/commands/doc-arch.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/doc-feature.md`,
+        '.contextkit/commands/doc-feature.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/doc-component.md`,
+        '.contextkit/commands/doc-component.md'
+      );
+
       // Download hooks (pre-push and commit-msg only, no pre-commit)
       await this.downloadManager.downloadFile(
         `${this.repoUrl}/hooks/pre-push`,
@@ -948,7 +1025,7 @@ esac
     console.log(chalk.green('✅ CLI helpers installed'));
   }
 
-  async createConfiguration(projectType, hookChoices) {
+  async createConfiguration(projectType, hookChoices, squadCi = false) {
     const projectName = path.basename(process.cwd());
 
     const config = {
@@ -962,7 +1039,8 @@ esac
         linting: true,
         type_safety: true,
         pre_push_hook: hookChoices.prePush,
-        commit_msg_hook: hookChoices.commitMsg
+        commit_msg_hook: hookChoices.commitMsg,
+        squad_ci_workflow: squadCi,
       },
       paths: {
         components: 'src/components',
@@ -1038,6 +1116,7 @@ features:
   type_safety: ${config.features.type_safety}
   pre_push_hook: ${config.features.pre_push_hook}
   commit_msg_hook: ${config.features.commit_msg_hook}
+  squad_ci_workflow: ${config.features.squad_ci_workflow}
 
 # Paths (customize for your project)
 paths:
@@ -1078,13 +1157,14 @@ https://www.npmjs.com/package/@nolrm/contextkit
     await fs.writeFile('.contextkit/README.md', content);
   }
 
-  async createStatusFile(projectType, packageManager, hookChoices) {
+  async createStatusFile(projectType, packageManager, hookChoices, squadCi = false) {
     try {
       const status = this.statusManager.getDefaultStatus();
       status.project_type = projectType;
       status.package_manager = packageManager;
       status.features.pre_push_hook = hookChoices.prePush;
       status.features.commit_msg_hook = hookChoices.commitMsg;
+      status.features.squad_ci_workflow = squadCi;
       
       await this.statusManager.saveStatus(status);
       console.log(chalk.green('✅ Status tracking initialized'));

package/lib/commands/update.js

@@ -64,7 +64,7 @@ class UpdateCommand {
       }
 
       // Download latest files
-      await this.downloadFiles(projectType);
+      await this.downloadFiles(projectType, config);
 
       // Remove files that were removed from CK
       await this.removeLegacyFiles();
@@ -205,13 +205,16 @@ class UpdateCommand {
       } else if (trimmed.startsWith('commit_msg_hook:')) {
         config.features = config.features || {};
         config.features.commit_msg_hook = trimmed.split('commit_msg_hook:')[1].trim() === 'true';
+      } else if (trimmed.startsWith('squad_ci_workflow:')) {
+        config.features = config.features || {};
+        config.features.squad_ci_workflow = trimmed.split('squad_ci_workflow:')[1].trim() === 'true';
       }
     }
 
     return config;
   }
 
-  async downloadFiles(projectType) {
+  async downloadFiles(projectType, config = {}) {
     const spinner = ora('Downloading latest files...').start();
 
     try {
@@ -306,11 +309,38 @@ class UpdateCommand {
         `${this.repoUrl}/commands/squad-doc.md`,
         '.contextkit/commands/squad-doc.md'
       );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/squad-ci.md`,
+        '.contextkit/commands/squad-ci.md'
+      );
       await this.downloadManager.downloadFile(
         `${this.repoUrl}/commands/health-check.md`,
         '.contextkit/commands/health-check.md'
       );
 
+      // Download doc family commands
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/doc-arch.md`,
+        '.contextkit/commands/doc-arch.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/doc-feature.md`,
+        '.contextkit/commands/doc-feature.md'
+      );
+      await this.downloadManager.downloadFile(
+        `${this.repoUrl}/commands/doc-component.md`,
+        '.contextkit/commands/doc-component.md'
+      );
+
+      // Update CI squad workflow if the user opted in
+      if (config.features?.squad_ci_workflow) {
+        await fs.ensureDir('.github/workflows');
+        await this.downloadManager.downloadFile(
+          `${this.repoUrl}/templates/github-actions/squad-issue.yml`,
+          '.github/workflows/squad-issue.yml'
+        );
+      }
+
       // 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

@@ -28,6 +28,9 @@ class ClaudeIntegration extends BaseIntegration {
       '.claude/commands/squad-doc.md',
       '.claude/commands/spec.md',
       '.claude/commands/ck.md',
+      '.claude/commands/doc-arch.md',
+      '.claude/commands/doc-feature.md',
+      '.claude/commands/doc-component.md',
     ];
     this.platformDir = '.claude/rules';
   }
@@ -281,6 +284,34 @@ After review passes, create or update companion .md files for every new/modified
 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)
+
+Read \`.contextkit/commands/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).
+
+Pass an optional PR number to scope to that PR's changes.
+`);
+
+    await this.writeGeneratedFile('.claude/commands/doc-feature.md', `# Doc — Feature (Level 2)
+
+Read \`.contextkit/commands/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.
+
+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)
+
+Read \`.contextkit/commands/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.
 `);
   }
 
@@ -296,7 +327,10 @@ Check project setup, standards status, and integrations. Report what needs atten
     console.log(chalk.dim('    /fix      — Diagnose and fix a bug'));
     console.log(chalk.dim('    /refactor — Refactor code structure'));
     console.log(chalk.dim('    /test     — Generate or run tests'));
-    console.log(chalk.dim('    /doc      — Add documentation'));
+    console.log(chalk.dim('    /doc           — Add documentation'));
+    console.log(chalk.dim('    /doc-arch      — Architecture docs (Level 1)'));
+    console.log(chalk.dim('    /doc-feature   — Feature docs (Level 2)'));
+    console.log(chalk.dim('    /doc-component — Component docs (Level 3)'));
     console.log(chalk.dim(''));
     console.log(chalk.dim('  Squad (multi-agent workflow):'));
     console.log(chalk.dim('    /squad "task"      — Kickoff: create handoff + PO spec'));

package/package.json

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