crewkit 0.1.0

package/skill/templates/skills/full-workflow/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: full-workflow
+description: "Execute the complete development workflow: classify size/risk, route to appropriate agents (explorer, architect, coder, tester, reviewer), validate in parallel, fix loop until clean."
+---
+
+Execute the full orchestrator workflow for: $ARGUMENTS
+
+---
+
+# Part 1 — Core Flow
+
+## Step 0 — Classify
+
+> **Stack:** [detect from target files]
+> **Size: SMALL / MEDIUM / LARGE**
+> **Risk: LOW / MEDIUM / HIGH**
+> Reason: [1 sentence for size, 1 sentence for risk]
+
+| Size | Criteria |
+|------|----------|
+| **SMALL** | 1-2 files, localized change, scope is obvious, no cross-module impact |
+| **MEDIUM** | 3-5 files, some cross-module dependencies, domain already known |
+| **LARGE** | 6+ files, architectural impact, unknown codebase area, multi-module, or migration needed |
+
+| Risk | Scope |
+|------|-------|
+| **LOW** | Pure DTO, mapper, UI without business logic, text, local refactor |
+| **MEDIUM** | Application handlers, queries, validation, cache, UI with conditional logic |
+| **HIGH** | Auth, multi-tenant, billing, permissions, deletes, migrations, background jobs, external integrations, public API contracts |
+
+**Plan detection:** if `$ARGUMENTS` points to an existing `.ai/plans/*.md` file → skip explorer + architect, go straight to coder. Update plan status to IN_PROGRESS.
+
+**Classification correction:** if later evidence shows the initial classification was too optimistic, immediately reclassify and switch to the appropriate flow.
+
+## Subagents
+
+| Phase | Subagent | Model |
+|-------|----------|-------|
+| explorer | `explorer` | Sonnet |
+| architect | `architect` | Opus |
+| coder | `coder` | Sonnet |
+| tester | `tester` | Sonnet |
+| reviewer | `reviewer` | Opus |
+
+## Background execution rule
+
+**When launching 2+ agents in parallel, ALWAYS use `run_in_background: true` on ALL of them.**
+
+---
+
+## Flows
+
+### SMALL
+
+```text
+orchestrator → coder → [ tester | reviewer ] → consolidate → fix loop if needed
+```
+
+1. Read the target file(s) directly (no explorer scan)
+2. **coder** — implement smallest possible change
+3. **In parallel** (two Agent calls in the same message):
+   - **tester** — **Normal mode**: build, create tests, run full suite
+   - **reviewer** — review diff
+4. **Consolidate** (see Part 2)
+5. Clean → Summarize. Issues → fix loop.
+
+### MEDIUM
+
+```text
+orchestrator → explorer → coder → [ tester | reviewer ] → consolidate → fix loop if needed
+```
+
+1. **explorer** — map relevant files and dependencies
+2. **coder** — implement based on explorer findings
+3. **In parallel**: tester (Normal mode) + reviewer
+4. Consolidate → Summarize or fix loop
+
+### LARGE — with plan
+
+```text
+orchestrator → coder → [ tester | reviewer ] → consolidate → fix loop if needed
+```
+
+1. Read the plan file
+2. **coder** — implement per plan
+3. **In parallel**: tester (Normal mode) + reviewer
+4. Consolidate → Summarize or fix loop
+
+### LARGE — without plan
+
+```text
+orchestrator → explorer → architect → [USER APPROVAL] → coder → [ tester | reviewer ] → consolidate → fix loop if needed
+```
+
+1. **explorer** — deep map
+2. **architect** — plan, assess risk
+3. **MANDATORY PAUSE** — present to user, wait for approval
+4. **coder** — implement per architect plan
+5. **In parallel**: tester + reviewer
+6. Consolidate → Summarize or fix loop
+
+---
+
+## Summarize (all flows)
+
+Return:
+- **Stack:** [detected]
+- **Size:** SMALL / MEDIUM / LARGE
+- **Risk:** LOW / MEDIUM / HIGH
+- **Summary:** what was done
+- **Files changed:** list
+- **Tests:** X passed, Y failed
+- **Review:** approved / needs changes
+- **Risks / Next steps:** if any
+
+If a plan file was used, update its status to **DONE**.
+
+## Memory Update
+
+If a durable lesson was learned, append to the appropriate `lessons-{domain}.md`.
+
+---
+
+# Part 2 — Operational Policies
+
+## Exit gate
+
+**HARD BLOCK: No task is complete without reviewer APPROVED (clean).**
+
+- Tester PASS alone is **not sufficient**
+- Reviewer APPROVED is **mandatory** before Summarize
+- **APPROVED with IMPORTANT+ findings is NOT clean.** Fix, then re-run tester + reviewer.
+- Both must be clean (PASS + APPROVED without IMPORTANT+ findings) before Summarize.
+
+## Findings consolidation
+
+After tester and reviewer finish:
+
+1. **Collect** results from both
+2. **Classify:** Tester = PASS/FAIL. Reviewer = APPROVED/NEEDS_CHANGES
+3. **Deduplicate** — same file + same concern → keep higher severity
+4. **APPROVED with IMPORTANT+ findings** = treat as NEEDS_CHANGES
+5. **Decision matrix:**
+
+| Tester | Reviewer | Action |
+|--------|----------|--------|
+| PASS | APPROVED (clean) | Done → Summarize |
+| PASS | APPROVED with IMPORTANT+ | Fix loop |
+| PASS | NEEDS_CHANGES | Fix loop (reviewer findings) |
+| FAIL | APPROVED | Fix loop (test failures) |
+| FAIL | NEEDS_CHANGES | Fix loop (merge into ONE list for coder) |
+
+When both fail, call coder **once** with the merged list.
+
+## Fix loop
+
+1. **Fix:**
+   - Risk **HIGH**: all fixes through **coder** — never auto-fix
+   - Risk LOW/MEDIUM: `auto_fixable: yes` → orchestrator applies directly. Else → coder
+   - When fix changes an exception type or interface → instruct coder to grep for all test doubles/fakes
+2. **Revalidate in parallel** (tester fix-loop mode + reviewer)
+3. Consolidate again
+4. Exit when PASS + APPROVED
+5. **Max 5 iterations** — then STOP and report to user.
+
+**MINOR findings** do not trigger fix loop alone.
+
+**Tester time budget:** if the tester reports pre-existing failures unrelated to the current task, the orchestrator must NOT ask the tester to fix them. Note them for a separate task and proceed.
+
+## Test creation rule
+
+**Every behavioral change must be validated by tests.** The tester creates them automatically.
+
+- New feature with logic → unit tests + integration when applicable
+- Bug fix → test that reproduces the bug + verifies the fix
+- Refactor with preserved behavior → existing tests are sufficient
+- Cosmetic/text/DTO change without logic → build + review is sufficient
+
+## HIGH risk rules
+
+- Never auto-fix — all through coder
+- Full test suite on every revalidation
+- Reviewer always mandatory
+- Architect mandatory if any design decision is open
+
+## Stop conditions
+
+STOP and escalate when:
+- Build doesn't stabilize after 2 corrections
+- Reviewer flags an architectural problem
+- Tester finds widespread failures outside task scope
+- Root cause unclear after 1 fix loop
+- Affected files grow beyond plan
+- SMALL/MEDIUM reveals structural impact
+
+---
+
+# Part 3 — Stack Configuration
+
+The orchestrator must tell subagents which build/test commands to use. Read `.ai/memory/commands.md` at the start and use the correct commands for each stack.
+
+When telling the tester subagent what to do, always include:
+- The stack being tested
+- The test framework (from `.ai/memory/testing.md`)
+- Whether this is a cross-stack task (requires testing multiple stacks)
+
+For cross-stack tasks:
+1. Explorer maps both sides
+2. Architect evaluates the contract between stacks
+3. Coder runs once per stack in sequence (dependency direction decides order)
+4. Tester runs tests for all affected stacks
+5. Reviewer runs once across the full diff

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

@@ -0,0 +1,117 @@
+---
+name: hotfix
+description: "Compressed workflow for urgent production fixes: diagnose → coder → [tester | reviewer] → consolidate → document. No refactor. No architecture phase unless the issue is not locally fixable."
+---
+
+Execute hotfix for: $ARGUMENTS
+
+## When to use
+Use only when production is broken and fast restoration matters more than broader improvement.
+
+Skips explorer, architect, and refactor **only if**:
+- the failure is already understood or can be confirmed quickly
+- the fix is local
+- no new architecture decision is required
+
+If root cause is unclear, blast radius grows, or fix requires design trade-offs, **STOP and use `/full-workflow` instead**.
+
+## Never use hotfix for
+
+These always require `/full-workflow`:
+- **Auth or multi-tenant isolation** — wrong fix = data leak
+- **Billing or payment logic** — wrong fix = financial impact
+- **DB migrations** — irreversible in production
+- **Public API contract changes** — breaks consumers
+- **State machine transitions** — adding states affects the full lifecycle
+- **Persistence format/schema changes** — wrong format corrupts state on restart
+- **Retry/idempotency logic** — wrong fix = duplicates or lost events
+
+Hotfix IS valid for:
+- Guards/validations within existing flow
+- Fixing a service call that sends wrong data
+- Fixing a timer/job that isn't cleaned up
+- Fixing an async handler that swallows errors
+- Any localized fix that doesn't change the architecture
+
+---
+
+## Hotfix rules
+
+- Restore service with the **smallest possible fix**
+- No cleanup, no opportunistic refactor, no unrelated improvements
+- Do not widen scope unless required for safety
+- Every behavioral fix must be validated by tests
+
+---
+
+## Flow
+
+```text
+orchestrator → diagnose → coder → [ tester | reviewer ] → consolidate → document
+```
+
+### Step 1 — Diagnose
+
+Before calling coder, confirm the root cause. The orchestrator does this directly.
+
+1. Read the target file(s) and relevant logs/errors
+2. Run diagnostic commands (logs, DB queries, API calls, git blame)
+3. Identify the exact failure path
+4. State root cause in 1-2 sentences
+5. **Escape to `/full-workflow`** if:
+   - Root cause unclear after reading code + logs
+   - Fix requires 3+ files
+   - Fix requires migration, contract change, or infra change
+   - Fix requires architectural decision
+   - Fix touches auth, tenant isolation, or billing
+
+### Step 2 — Fix
+
+Use **coder** with: confirmed root cause, target files, instruction for smallest fix.
+
+### Step 3 — Validate
+
+**In parallel**: tester (Normal mode, full suite) + reviewer
+
+### Step 4 — Consolidate
+
+| Tester | Reviewer | Action |
+|--------|----------|--------|
+| PASS | APPROVED | Done → Step 5 |
+| PASS | NEEDS_CHANGES | Fix loop (1 max) |
+| FAIL | APPROVED | Fix loop (1 max) |
+| FAIL | NEEDS_CHANGES | Merge → fix loop (1 max) |
+
+On fix loop iteration, revalidate **in parallel** (tester **Fix-loop mode** + reviewer), same as Step 3.
+
+**Max 2 iterations.** If not clean → STOP and escalate to user with:
+- Summary of what was attempted and why it failed
+- Recommend: **revert** (if fix introduced worse regressions) or **escalate to `/full-workflow`** (if fix is on right track but needs more work)
+- Never leave broken code uncommitted — either revert to last known good state or commit with `[WIP]` marker and explain what remains
+
+### Step 5 — Document
+
+Append to appropriate `lessons-{domain}.md`:
+
+```markdown
+### [YYYY-MM-DD] Hotfix: <short title>
+- **Root cause:** [1-2 sentences]
+- **Fix:** [what was changed]
+- **Files:** [list]
+- **Lesson:** [what to watch for to prevent recurrence]
+```
+
+**Follow-up assessment:** If root cause reveals systemic issue, suggest `/explore-and-plan` for structural fix.
+
+---
+
+## Return Format
+
+- **Stack:** [detected]
+- **Root cause:** [1-2 sentences]
+- **Summary:** what was fixed
+- **Files changed:** list
+- **Tests:** X passed, Y failed
+- **Review:** approved / needs changes
+- **Lesson documented:** yes/no
+- **Residual risks:** [if any]

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

@@ -0,0 +1,53 @@
+---
+name: review-pr
+description: "Review a pull request using the reviewer agent. Fetches diff + description via gh CLI, returns structured findings."
+---
+
+Review pull request: $ARGUMENTS
+
+## Steps
+
+### 1. Fetch PR data
+
+Run in parallel:
+```bash
+gh pr view $ARGUMENTS --json number,title,body,author,baseRefName,headRefName,additions,deletions,changedFiles
+gh pr diff $ARGUMENTS
+```
+
+If $ARGUMENTS is empty, use `gh pr view` (current branch's PR).
+
+### 2. Load project context
+
+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
+- 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).
+
+### 4. Return
+
+```markdown
+---
+**PR #[number] — [title]**
+**Author:** [author] | **Branch:** [head] → [base]
+**Size:** +[additions] / -[deletions] in [changedFiles] files
+
+**Findings:**
+- CRITICAL: [list or "none"]
+- IMPORTANT: [list or "none"]
+- MINOR: [list or "none"]
+
+**Positives:** [what's good]
+
+**Verdict:** APPROVED / NEEDS_CHANGES
+---
+```
+
+If no PR number provided and no current branch PR exists, ask for the PR number.

package/src/cli.js

@@ -0,0 +1,35 @@
+import { install } from './install.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
+
+Usage:
+  npx crewkit install    # one-time setup
+  /crewkit-setup         # run in your IDE to scan & calibrate a project
+`;
+
+export function run(args) {
+  const command = args[0];
+
+  switch (command) {
+    case 'install':
+    case 'update':
+      install();
+      break;
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+      console.log(HELP);
+      break;
+    default:
+      console.error(`Unknown command: ${command}`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}

package/src/install.js

@@ -0,0 +1,40 @@
+import { cpSync, mkdirSync, existsSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export function install() {
+  const skillSource = join(__dirname, '..', 'skill');
+  const skillDest = join(homedir(), '.claude', 'skills', 'crewkit-setup');
+
+  // Verify source exists
+  if (!existsSync(skillSource)) {
+    console.error('Error: skill/ directory not found. Package may be corrupted.');
+    process.exit(1);
+  }
+
+  // Create destination
+  mkdirSync(skillDest, { recursive: true });
+
+  // Copy skill + templates
+  cpSync(skillSource, skillDest, { recursive: true, force: true });
+
+  // Read version
+  const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+  console.log(`
+  ✓ crewkit v${pkg.version} installed
+
+  Skill copied to: ${skillDest}
+
+  Next: open any project in Claude Code and run:
+
+    /crewkit-setup
+
+  This will scan your codebase and generate a complete
+  context engineering setup (agents, skills, hooks, rules, memory).
+  `);
+}