crewkit 0.1.0 → 1.1.0

package/skill/templates/skills/retro/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: retro
+description: "Post-mortem of a completed task or plan — analyzes fix loops, reviewer findings, lessons learned, and suggests process improvements."
+---
+
+Post-mortem for: $ARGUMENTS
+
+If $ARGUMENTS is empty, analyze the most recent completed task from git log.
+
+---
+
+## When to use
+
+Use after a task is completed (or after a painful iteration) to extract durable lessons
+and identify process improvements. Not a blame exercise — a signal extraction exercise.
+
+---
+
+## Steps
+
+### 1. Gather signals
+
+Run in parallel:
+
+```bash
+git log --oneline -30
+git diff HEAD~10..HEAD --stat
+```
+
+Also read (if they exist):
+- `.ai/plans/` — any plan file matching $ARGUMENTS
+- `.ai/memory/lessons-*.md` — to avoid duplicating existing lessons
+
+If $ARGUMENTS points to a specific plan file, read it directly.
+
+### 2. Reconstruct the timeline
+
+From git log and plan file, reconstruct:
+
+| Phase | What happened | Agent/actor |
+|-------|--------------|-------------|
+| Initial implementation | ... | coder |
+| First test run | PASS / FAIL | tester |
+| First review | APPROVED / NEEDS_CHANGES | reviewer |
+| Fix loop iterations | count + what was fixed | coder |
+| Final state | PASS + APPROVED | — |
+
+Flag any phase that repeated more than once.
+
+### 3. Analyze fix loops
+
+For each fix loop iteration, identify:
+- **Trigger:** what caused the loop (test failure / reviewer finding / build error)
+- **Root cause category:** one of:
+  - `spec-gap` — requirement was ambiguous or incomplete
+  - `scope-underestimate` — task was classified smaller than it was
+  - `missing-context` — coder lacked critical info (architecture, conventions, existing pattern)
+  - `test-gap` — test didn't cover the scenario before the fix
+  - `review-gap` — reviewer finding could have been caught earlier
+  - `execution-error` — correct spec, wrong implementation (typo, off-by-one, wrong field)
+  - `external-dependency` — blocked by something outside the task
+
+### 4. Classify reviewer findings
+
+If reviewer output is available (from PR diff, plan notes, or conversation context), classify findings:
+
+| Severity | Count | Recurring? | Category |
+|----------|-------|-----------|----------|
+| CRITICAL | ... | yes/no | ... |
+| IMPORTANT | ... | yes/no | ... |
+| MINOR | ... | yes/no | ... |
+
+"Recurring" = same finding appeared in a previous retro or lesson file.
+
+### 5. Identify process improvements
+
+For each fix loop trigger, propose one concrete process change:
+
+| Finding | Proposed change | Target phase |
+|---------|----------------|--------------|
+| e.g. coder missed multi-tenant rule | Add explicit tenant check to coder prompt | Step 0 (classify) |
+| e.g. test missed edge case | Add edge case checklist to tester for this module | tester |
+
+Keep proposals concrete and actionable. Do not propose vague "be more careful" items.
+
+### 6. Extract durable lessons
+
+For each lesson that would prevent future recurrence, format as:
+
+```markdown
+### [YYYY-MM-DD] Retro: <short title>
+- **Task:** [what was being built/fixed]
+- **What happened:** [1-2 sentences]
+- **Root cause:** [category from Step 3]
+- **Lesson:** [actionable guidance for next time]
+- **Applies to:** [domain: .NET / gateway / Blazor / process / all]
+```
+
+Append to the correct `.ai/memory/lessons-{domain}.md`.
+If lesson is process-level, append to `lessons-process.md` (create if missing).
+
+### 7. Update plan status
+
+If a plan file was identified, update its status to **DONE** (if not already).
+
+---
+
+## Return Format
+
+```markdown
+---
+**Retro: [task name or git range]**
+**Period:** [date range from git log]
+**Fix loop count:** [N]
+
+**Timeline summary:**
+[reconstructed table from Step 2]
+
+**Fix loop analysis:**
+[table from Step 3]
+
+**Reviewer findings:**
+[table from Step 4, or "not available"]
+
+**Process improvements:**
+[table from Step 5]
+
+**Lessons documented:** [N lessons → file(s)]
+
+**Top recommendation:** [single most impactful process change]
+---
+```
+
+If no fix loops occurred and review was clean on the first pass, state that explicitly — it is a positive signal worth noting.

package/skill/templates/skills/review-pr/SKILL.md

@@ -9,7 +9,10 @@ Review pull request: $ARGUMENTS
 
 ### 1. Fetch PR data
 
-Run in parallel:
+Try each source in order, stopping at the first that succeeds.
+
+#### 1a. GitHub (gh CLI)
+
 ```bash
 gh pr view $ARGUMENTS --json number,title,body,author,baseRefName,headRefName,additions,deletions,changedFiles
 gh pr diff $ARGUMENTS
@@ -17,6 +20,32 @@ gh pr diff $ARGUMENTS
 
 If $ARGUMENTS is empty, use `gh pr view` (current branch's PR).
 
+If `gh` is not installed or returns an error, proceed to **1b**.
+
+#### 1b. GitLab (glab CLI)
+
+```bash
+glab mr view $ARGUMENTS --output json
+glab mr diff $ARGUMENTS
+```
+
+If $ARGUMENTS is empty, use `glab mr view` (current branch's MR).
+
+If `glab` is not installed or returns an error, proceed to **1c**.
+
+#### 1c. Pure git fallback
+
+```bash
+git log main..HEAD --oneline
+git diff main...HEAD
+```
+
+When using this fallback:
+- PR metadata (title, description, author, reviewer comments) is **not available**.
+- Communicate this clearly to the reviewer agent.
+- Ask the user to provide context about the changes if possible:
+  > "No GitHub/GitLab CLI was found. I'm reviewing based on raw git diff only. PR title, description, and comments are unavailable. If you can share what this change is about, it will improve the review."
+
 ### 2. Load project context
 
 Read `.ai/memory/architecture.md` and `.ai/memory/conventions.md`.
@@ -24,9 +53,10 @@ Read `.ai/memory/architecture.md` and `.ai/memory/conventions.md`.
 ### 3. Run reviewer agent
 
 Pass to **reviewer** subagent:
-- Full PR diff
-- PR title and description
-- File count and change size
+- Full PR/MR diff (or git diff if fallback)
+- PR/MR title and description (if available; otherwise note "unavailable — git fallback")
+- File count and change size (derive from diff if metadata unavailable)
+- Source used: GitHub / GitLab / git fallback
 - Project context from step 2
 
 The reviewer applies all checks from its instructions and `.ai/memory/conventions.md`, including project-specific rules (e.g., multi-tenant enforcement, architecture layer violations, forbidden patterns).
@@ -37,6 +67,7 @@ The reviewer applies all checks from its instructions and `.ai/memory/convention
 ---
 **PR #[number] — [title]**
 **Author:** [author] | **Branch:** [head] → [base]
+**Source:** GitHub / GitLab / git fallback (no PR metadata)
 **Size:** +[additions] / -[deletions] in [changedFiles] files
 
 **Findings:**
@@ -50,4 +81,7 @@ The reviewer applies all checks from its instructions and `.ai/memory/convention
 ---
 ```
 
-If no PR number provided and no current branch PR exists, ask for the PR number.
+If using git fallback, omit fields that are unavailable (number, author, branch names) and add a note:
+> "Review based on git diff only — PR metadata was not available."
+
+If no PR/MR number provided and no current branch PR/MR exists and git fallback also fails, ask the user for a PR number or a base branch to diff against.

package/skill/templates/skills/security-scan/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: security-scan
+description: "Scan for known CRITICAL security issues and OWASP top 10 vulnerabilities specific to this project. Reports status of each known issue."
+---
+
+Run security scan for: $ARGUMENTS
+
+If $ARGUMENTS is empty, scan the full codebase.
+If $ARGUMENTS is a path or module name, scope the scan to that area.
+
+---
+
+## When to use
+
+Use before merging changes that touch auth, tenant isolation, input handling, external integrations,
+or any area that directly processes user-supplied data. Not a replacement for automated SAST —
+a targeted, context-aware review using project conventions.
+
+---
+
+## Steps
+
+### 1. Load project context
+
+Read `.ai/memory/conventions.md` and `.ai/memory/architecture.md`.
+
+Extract:
+- Security rules declared in conventions (e.g., TenantId must come from JWT, not body)
+- Auth mechanism (JWT, sessions, API keys)
+- Data flow: where external input enters the system
+- Stack-specific concerns (e.g., SQL via ORM, HTML rendering, file uploads)
+
+### 2. Map attack surface
+
+Identify entry points within the scan scope:
+
+```bash
+# Find API endpoint definitions
+# (adapt pattern to the project's stack — controllers, routes, handlers, etc.)
+
+# Find places that read from request body, query string, or headers
+# Find places that write to DB or execute queries
+# Find places that render HTML or return user-supplied content
+# Find places that call external services
+# Find files that handle auth or session state
+```
+
+Run searches appropriate to the detected stack. Do not run all commands if the stack is clear
+from `.ai/memory/architecture.md`.
+
+### 3. Check OWASP Top 10
+
+For each category, determine status based on code inspection:
+
+| # | Category | Status | Evidence |
+|---|----------|--------|----------|
+| A01 | Broken Access Control | PASS / FAIL / PARTIAL / SKIP | [file:line or reason for skip] |
+| A02 | Cryptographic Failures | PASS / FAIL / PARTIAL / SKIP | |
+| A03 | Injection (SQL, NoSQL, cmd) | PASS / FAIL / PARTIAL / SKIP | |
+| A04 | Insecure Design | PASS / FAIL / PARTIAL / SKIP | |
+| A05 | Security Misconfiguration | PASS / FAIL / PARTIAL / SKIP | |
+| A06 | Vulnerable Components | PASS / FAIL / PARTIAL / SKIP | |
+| A07 | Auth & Session Management | PASS / FAIL / PARTIAL / SKIP | |
+| A08 | Software & Data Integrity | PASS / FAIL / PARTIAL / SKIP | |
+| A09 | Security Logging & Monitoring | PASS / FAIL / PARTIAL / SKIP | |
+| A10 | Server-Side Request Forgery | PASS / FAIL / PARTIAL / SKIP | |
+
+**Status definitions:**
+- `PASS` — checked, no issue found
+- `FAIL` — issue found, report exact location
+- `PARTIAL` — partially mitigated, describe gap
+- `SKIP` — not applicable to this scope (explain why)
+
+### 4. Check project-specific security rules
+
+From the rules extracted in Step 1, verify each one explicitly.
+
+Common examples (adapt to what conventions.md actually says):
+
+| Rule | Status | Evidence |
+|------|--------|----------|
+| TenantId sourced from JWT only (never from body/query) | PASS / FAIL | |
+| No hardcoded secrets or API keys in source files | PASS / FAIL | |
+| Auth enforced on all non-public endpoints | PASS / FAIL | |
+| User-supplied data never passed to raw SQL or shell | PASS / FAIL | |
+| File uploads validated for type and size | PASS / FAIL / N/A | |
+| External service calls use timeout and error handling | PASS / FAIL / N/A | |
+
+### 5. Check for secrets in code
+
+Search for common secret patterns:
+
+```bash
+# Patterns to search: password=, secret=, apikey=, token=, connectionstring=
+# in non-test, non-example source files
+# Flag any hardcoded value that is not an environment variable reference
+```
+
+Report any findings with file path and line number. Flag `FAIL` in A02 if found.
+
+### 6. Classify findings
+
+| Severity | Criteria |
+|----------|----------|
+| CRITICAL | Exploitable without authentication, or exposes tenant data across boundaries |
+| HIGH | Exploitable by authenticated users, privilege escalation, or data exposure |
+| MEDIUM | Requires specific conditions, indirect exposure, or defense-in-depth gap |
+| LOW | Best practice violation, minor information leakage, or hardening opportunity |
+
+---
+
+## Return Format
+
+```markdown
+---
+**Security Scan Report**
+**Scope:** [full codebase or specific module]
+**Stack:** [detected from architecture.md]
+
+## OWASP Top 10 Status
+[table from Step 3]
+
+## Project-Specific Rules
+[table from Step 4]
+
+## Findings
+
+### CRITICAL
+- [none | list with file:line, description, remediation]
+
+### HIGH
+- [none | list]
+
+### MEDIUM
+- [none | list]
+
+### LOW
+- [none | list]
+
+## Summary
+| Total findings | CRITICAL | HIGH | MEDIUM | LOW |
+|---------------|----------|------|--------|-----|
+| N | N | N | N | N |
+
+**Overall status:** CLEAN / NEEDS_ATTENTION / CRITICAL_ACTION_REQUIRED
+
+## Recommended next steps
+[numbered list, prioritized by severity]
+---
+```
+
+**CLEAN** = zero CRITICAL or HIGH findings.
+**NEEDS_ATTENTION** = one or more MEDIUM findings, zero CRITICAL/HIGH.
+**CRITICAL_ACTION_REQUIRED** = any CRITICAL or HIGH finding present.
+
+Do not suggest generic remediation. Every recommendation must reference the specific file,
+function, or rule from conventions.md.

package/src/add.js

@@ -0,0 +1,45 @@
+import { cpSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const OPTIONAL_SKILLS = ['retro', 'dev-metrics', 'security-scan', 'impact'];
+
+export function add(skillName) {
+  if (!skillName) {
+    console.error('Error: skill name is required.');
+    console.log(`\n  Available optional skills:\n${OPTIONAL_SKILLS.map(s => `    - ${s}`).join('\n')}\n`);
+    process.exit(1);
+  }
+
+  if (!OPTIONAL_SKILLS.includes(skillName)) {
+    console.error(`Error: "${skillName}" is not a known optional skill.`);
+    console.log(`\n  Available optional skills:\n${OPTIONAL_SKILLS.map(s => `    - ${s}`).join('\n')}\n`);
+    process.exit(1);
+  }
+
+  const source = join(homedir(), '.claude', 'skills', 'crewkit-setup', 'templates', 'skills', skillName, 'SKILL.md');
+
+  if (!existsSync(source)) {
+    console.error(`Error: source not found at ${source}`);
+    console.log('  Make sure crewkit is installed first: npx crewkit install');
+    process.exit(1);
+  }
+
+  const targetDir = join(process.cwd(), '.claude', 'skills', skillName);
+  const target = join(targetDir, 'SKILL.md');
+
+  if (existsSync(target)) {
+    console.log(`  Warning: ${target} already exists. Overwriting.`);
+  }
+
+  mkdirSync(targetDir, { recursive: true });
+  cpSync(source, target);
+
+  console.log(`
+  ✓ Skill "${skillName}" installed
+
+  Copied to: ${target}
+
+  Use /${skillName} in Claude Code to run it.
+  `);
+}

package/src/cli.js

@@ -1,16 +1,20 @@
 import { install } from './install.js';
+import { update } from './update.js';
+import { add } from './add.js';
 
 const HELP = `
 crewkit — Context engineering for AI-assisted development
 
 Commands:
-  install    Install crewkit skill globally (~/.claude/skills/)
-  update     Update to latest version (re-run install)
-  help       Show this message
+  install       Install crewkit skill globally (~/.claude/skills/)
+  update        Update to latest version (re-run install)
+  add <skill>   Add an optional skill to the current project
+  help          Show this message
 
 Usage:
-  npx crewkit install    # one-time setup
-  /crewkit-setup         # run in your IDE to scan & calibrate a project
+  npx crewkit install          # one-time setup
+  npx crewkit add retro        # add optional skill to project
+  /crewkit-setup               # run in your IDE to scan & calibrate a project
 `;
 
 export function run(args) {
@@ -18,9 +22,14 @@ export function run(args) {
 
   switch (command) {
     case 'install':
-    case 'update':
       install();
       break;
+    case 'update':
+      update();
+      break;
+    case 'add':
+      add(args[1]);
+      break;
     case 'help':
     case '--help':
     case '-h':

package/src/install.js

@@ -1,4 +1,4 @@
-import { cpSync, mkdirSync, existsSync, readFileSync } from 'node:fs';
+import { cpSync, mkdirSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -25,6 +25,9 @@ export function install() {
   // Read version
   const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
 
+  // Write version marker
+  writeFileSync(join(skillDest, '.version'), pkg.version, 'utf8');
+
   console.log(`
   ✓ crewkit v${pkg.version} installed
 

package/src/update.js

@@ -0,0 +1,28 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { install } from './install.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export function update() {
+  const versionFile = join(homedir(), '.claude', 'skills', 'crewkit-setup', '.version');
+  const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+  const newVersion = pkg.version;
+  const currentVersion = existsSync(versionFile)
+    ? readFileSync(versionFile, 'utf8').trim()
+    : 'unknown';
+
+  if (currentVersion === newVersion) {
+    console.log(`  Already up to date (v${newVersion})`);
+    return;
+  }
+
+  install();
+
+  const fromLabel = currentVersion === 'unknown' ? 'v0.1 (untracked)' : `v${currentVersion}`;
+  console.log(`  Updated: ${fromLabel} → v${newVersion}`);
+}