claude-code-pilot 2.0.0

package/kit/commands/setup.md

@@ -0,0 +1,579 @@
+---
+description: "First-time project setup — scans codebase, generates CLAUDE.md, installs language rules, discovers skills"
+---
+
+# Project Setup Wizard
+
+You are setting up Claude Code for this project. Follow these stages precisely.
+
+## Stage 0 — Source Directory Detection
+
+Verify that all 4 source directories from the Claude Code Pilot are properly installed.
+
+Check the following paths relative to the project root:
+
+1. **Kit commands** — check if `.claude/commands/setup.md` exists (this file is a kit-specific marker)
+2. **GSD commands** — check if `.claude/commands/gsd/` directory exists and is non-empty (contains the 32 GSD commands)
+3. **ECC toolbox** — check if `.claude/ecc-scripts/` directory exists (contains hooks, lib, detection scripts)
+4. **GSD SDLC workflows** — check if `.claude/get-shit-done/` directory exists and contains `workflows/` subdirectory
+
+Use the Bash tool to run existence checks (e.g., `ls` or `test -d`). Count items in each directory.
+
+Present results in this format:
+```
+Source Directory Detection:
+  [PASS] Kit commands     .claude/commands/ (N kit commands)
+  [PASS] GSD commands     .claude/commands/gsd/ (N commands)
+  [PASS] ECC toolbox      .claude/ecc-scripts/ (hooks, lib, detection)
+  [PASS] GSD workflows    .claude/get-shit-done/ (workflows, references, templates)
+
+All 4 source directories detected.
+```
+
+If any directory is missing, show:
+```
+  [FAIL] GSD commands     .claude/commands/gsd/ -- NOT FOUND
+         Fix: Run /kit:update or reinstall with npx claude-code-pilot@latest
+```
+
+Continue to Stage 1 regardless — detection is informational, not blocking.
+
+---
+
+## Stage 1 — Detect
+
+Check if this is an existing codebase or new project:
+
+1. Run `ls -la` and `find . -maxdepth 2 -type f | head -50`
+2. Check for: `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`, `pom.xml`
+
+**Files exist** → Stage 2A (scan).  **Mostly empty** → Stage 2B (interview).
+
+---
+
+## Stage 2A — Scan Existing Codebase
+
+Use subagents to explore (keeps main context clean). Tailor the exploration prompts based on what Stage 1 detected:
+
+**If Next.js detected** (react + next in dependencies, or next.config.* exists):
+```
+Use subagents to investigate:
+1. App Router vs Pages Router -- check for app/ vs pages/ directory
+2. Server vs Client components -- grep for 'use client' directives
+3. Data fetching -- check for fetch(), server actions, tRPC, or API routes
+4. Styling -- check for tailwind.config, CSS modules, styled-components
+5. Testing -- check for jest.config, vitest.config, playwright.config
+6. Database/ORM -- check for prisma/, drizzle.config, or direct DB imports
+```
+
+**If Python/Django detected** (manage.py exists, or django in dependencies):
+```
+Use subagents to investigate:
+1. Django apps -- list directories with models.py
+2. Database -- check for DATABASES in settings.py, migration files
+3. Auth -- check for custom User model, third-party auth (allauth, etc.)
+4. API -- check for rest_framework, graphene, or plain views
+5. Testing -- check for pytest.ini, manage.py test, test directories
+6. Deployment -- check for Dockerfile, gunicorn config, WSGI/ASGI
+```
+
+**If Go project detected** (go.mod exists):
+```
+Use subagents to investigate:
+1. Module structure -- list top-level packages (cmd/, internal/, pkg/)
+2. Web framework -- check for gin, echo, chi, net/http
+3. Database -- check for sqlx, gorm, pgx, migrate files
+4. Testing -- check for _test.go patterns, testify usage
+5. Build -- check for Makefile, Dockerfile, go generate directives
+```
+
+**If generic/unknown project** (none of the above matched clearly):
+```
+Use subagents to investigate:
+1. Language and framework markers -- package.json, go.mod, Cargo.toml, etc.
+2. Directory structure -- key directories and their purposes
+3. Build commands -- from manifest files (package.json scripts, Makefile, etc.)
+4. Test commands -- test runner config and test file locations
+5. Linting/formatting -- .eslintrc, .prettierrc, biome.json, etc.
+```
+
+Present findings:
+```
+Tech Stack: [framework] + [language] + [database]
+Linting: [tool] (config: [file])
+Testing: [framework] (command: [cmd])
+Structure: [key directories]
+Languages detected: [list]
+
+Does this look right?
+```
+
+Wait for confirmation → Stage 3.
+
+---
+
+## Stage 2B — New Project Interview
+
+Use AskUserQuestion:
+1. What are you building?
+2. What tech stack? (or "recommend for me")
+3. Database? Auth?
+4. Preferences? (linter, tests)
+
+Then → Stage 3.
+
+---
+
+## Stage 3 — Install Language Rules
+
+Based on detected languages, activate language-specific rules from `available-rules/`:
+
+```bash
+# For each detected language (e.g., typescript, python, golang):
+cp -r .claude/available-rules/<language>/ .claude/rules/<language>/
+```
+
+Always confirm with the user:
+```
+Detected languages: TypeScript, Python
+I'll activate language-specific rules for: coding-style, patterns, security, testing, hooks
+
+Proceed?
+```
+
+Common rules (`.claude/rules/common/`) are already active for all projects.
+
+---
+
+## Stage 4 — Directory-Scoped CLAUDE.md
+
+Generate CLAUDE.md files for recognized project subdirectories. These provide directory-specific context that Claude Code loads on demand when reading files in those directories.
+
+**Step 1: Scan for recognized directories**
+
+Check the project root for these directories: `src/`, `test/`, `tests/`, `lib/`, `app/`, `api/`, `scripts/`, `docs/`
+
+Skip any directory that does not exist.
+
+**Step 2: Check existing CLAUDE.md files**
+
+For each existing recognized directory:
+- If no `CLAUDE.md` exists in the directory: mark for generation
+- If `CLAUDE.md` exists and its **first line** contains `<!-- Generated by /setup -- customize freely, /setup:refresh will regenerate if this comment is present -->`: mark for regeneration (overwrite)
+- If `CLAUDE.md` exists **without** that marker on line 1: skip (user customized it)
+
+**Step 3: Confirm with user**
+
+Show a summary and ask for confirmation once (not per-file):
+```
+Directory-scoped CLAUDE.md files will be generated for:
+  src/     -- Source code (Next.js conventions)
+  test/    -- Test files (Jest + React Testing Library)
+  docs/    -- Documentation
+
+Proceed? (These can be customized later -- /setup:refresh will skip files you edit)
+```
+
+**Step 4: Generate files**
+
+After confirmation, use the Write tool to create each file. Every generated file MUST start with the marker comment on line 1.
+
+Use these templates based on the detected stack (from Stage 1):
+
+### src/ templates
+
+**Next.js project:**
+```markdown
+<!-- Generated by /setup -- customize freely, /setup:refresh will regenerate if this comment is present -->
+# Source Code (src/)
+
+This directory contains the application source code for a **Next.js** project.
+
+## Conventions
+
+- Use Server Components by default. Add `'use client'` only when the component needs browser APIs or interactivity.
+- App Router conventions: page.tsx for routes, layout.tsx for layouts, loading.tsx for suspense boundaries.
+- Import paths use `@/` alias (maps to `src/`).
+- Keep files under 400 lines. Extract utilities to `lib/` or shared modules.
+- Co-locate component tests as `ComponentName.test.tsx` alongside the component file.
+```
+
+**Express + TypeScript project:**
+```markdown
+<!-- Generated by /setup -- customize freely, /setup:refresh will regenerate if this comment is present -->
+# Source Code (src/)
+
+This directory contains the application source code for an **Express + TypeScript** project.
+
+## Conventions
+
+- Controllers in `controllers/`. Services in `services/`. Type definitions in `types/`.
+- Route handlers receive (req, res, next) and delegate to services.
+- All service functions return typed results, never throw for expected errors.
+- Keep files under 400 lines. Extract shared utilities to `lib/` or `utils/`.
+- Validate request bodies at the controller layer before passing to services.
+```
+
+**Python + Django project:**
+```markdown
+<!-- Generated by /setup -- customize freely, /setup:refresh will regenerate if this comment is present -->
+# Source Code (src/)
+
+This directory contains the application source code for a **Django** project.
+
+## Conventions
+
+- Apps follow Django conventions. Models in `models.py`. Views in `views.py`. URLs in `urls.py`.
+- Use class-based views for CRUD operations, function-based views for custom logic.
+- Keep models focused -- one responsibility per model. Use proxy models for alternative representations.
+- Keep files under 400 lines. Extract complex queries to managers.
+- Use Django's ORM. Raw SQL only when ORM cannot express the query efficiently.
+```
+
+**Go project:**
+```markdown
+<!-- Generated by /setup -- customize freely, /setup:refresh will regenerate if this comment is present -->
+# Source Code (src/)
+
+This directory contains the application source code for a **Go** project.
+
+## Conventions
+
+- Package-per-directory. Exported functions start with uppercase.
+- Interfaces are defined near the consumer, not the implementer.
+- Error handling: return errors, do not panic. Wrap errors with context using fmt.Errorf.
+- Keep files under 400 lines. One primary type per file.
+- Use dependency injection. Accept interfaces, return structs.
+```
+
+**Generic project (unknown framework):**
+```markdown
+<!-- Generated by /setup -- customize freely, /setup:refresh will regenerate if this comment is present -->
+# Source Code (src/)
+
+This directory contains the application source code.
+
+## Conventions
+
+- Follow existing patterns in this directory. Keep files focused and under 400 lines.
+- Organize by feature or domain, not by file type.
+- Export public interfaces through index files where applicable.
+- Separate business logic from I/O and framework code.
+- Keep imports organized: stdlib first, then external, then internal.
+```
+
+### test/ or tests/ templates
+
+**Next.js / React project:**
+```markdown
+<!-- Generated by /setup -- customize freely, /setup:refresh will regenerate if this comment is present -->
+# Tests (test/)
+
+This directory contains automated tests.
+
+## Conventions
+
+- Use Jest with React Testing Library for component tests.
+- Test file naming: `*.test.tsx` or `*.test.ts` matching the source file being tested.
+- Mock Next.js router and navigation using `next/navigation` mocks.
+- Prefer testing user-visible behavior over implementation details.
+- Each test should be independent -- no shared mutable state between tests.
+```
+
+**Python + Django project:**
+```markdown
+<!-- Generated by /setup -- customize freely, /setup:refresh will regenerate if this comment is present -->
+# Tests (tests/)
+
+This directory contains automated tests.
+
+## Conventions
+
+- Use pytest. Fixtures in `conftest.py`.
+- Mark database tests with `@pytest.mark.django_db`.
+- Test file naming: `test_*.py` matching the module being tested.
+- Do not mock what you can test directly. Prefer integration over unit when cost is similar.
+- Each test should be independent -- no shared mutable state between tests.
+```
+
+**Go project:**
+```markdown
+<!-- Generated by /setup -- customize freely, /setup:refresh will regenerate if this comment is present -->
+# Tests (test/)
+
+This directory contains automated tests.
+
+## Conventions
+
+- Test files: `*_test.go` in the same package as the code being tested.
+- Use table-driven tests for multiple input/output scenarios.
+- Use `testify` if present in go.mod, otherwise use stdlib `testing`.
+- Integration tests that need external services use build tags.
+- Each test should be independent -- no shared mutable state between tests.
+```
+
+**Generic project:**
+```markdown
+<!-- Generated by /setup -- customize freely, /setup:refresh will regenerate if this comment is present -->
+# Tests (test/)
+
+This directory contains automated tests.
+
+## Conventions
+
+- Test file naming: `*.test.*` matching the source file being tested.
+- Use the project's configured test runner (see root CLAUDE.md for commands).
+- Integration tests may use real filesystem I/O in temp directories.
+- Do not mock what you can test directly. Prefer integration over unit when cost is similar.
+- Each test should be independent -- no shared mutable state between tests.
+```
+
+### lib/ template (all stacks)
+
+```markdown
+<!-- Generated by /setup -- customize freely, /setup:refresh will regenerate if this comment is present -->
+# Shared Libraries (lib/)
+
+This directory contains shared utility functions and libraries.
+
+## Conventions
+
+- Pure utility functions. Minimize side effects.
+- Export public API through an index file where applicable.
+- Functions should be small, focused, and well-documented.
+- No framework-specific code -- keep lib/ portable across the project.
+- Keep files under 400 lines. Group related utilities in subdirectories.
+```
+
+### app/ templates
+
+**Next.js App Router:**
+```markdown
+<!-- Generated by /setup -- customize freely, /setup:refresh will regenerate if this comment is present -->
+# App Directory (app/)
+
+This directory contains Next.js App Router pages and layouts.
+
+## Conventions
+
+- Server Components by default. Add `'use client'` only when needed for browser APIs or interactivity.
+- Route structure: `page.tsx` for routes, `layout.tsx` for layouts, `loading.tsx` for suspense, `error.tsx` for error boundaries.
+- Route handlers in `route.ts` files for API endpoints.
+- Co-locate page-specific components in the same route directory.
+- Metadata exports for SEO in `page.tsx` and `layout.tsx`.
+```
+
+**Rails project:**
+```markdown
+<!-- Generated by /setup -- customize freely, /setup:refresh will regenerate if this comment is present -->
+# App Directory (app/)
+
+This directory contains the Rails application code.
+
+## Conventions
+
+- Follow Rails conventions: models/, controllers/, views/, helpers/, mailers/.
+- Skinny controllers, fat models. Business logic belongs in models or service objects.
+- Use concerns for shared behavior across models or controllers.
+- Keep views simple -- complex logic goes in helpers or presenters.
+- Follow RESTful routing conventions.
+```
+
+**Generic app/ directory:**
+```markdown
+<!-- Generated by /setup -- customize freely, /setup:refresh will regenerate if this comment is present -->
+# Application (app/)
+
+This directory contains the main application code.
+
+## Conventions
+
+- Follow existing patterns in this directory.
+- Organize by feature or domain, not by file type.
+- Keep entry points clearly identified and minimal.
+- Separate configuration from application logic.
+- Keep files under 400 lines.
+```
+
+### api/ template (all stacks)
+
+```markdown
+<!-- Generated by /setup -- customize freely, /setup:refresh will regenerate if this comment is present -->
+# API Layer (api/)
+
+This directory contains API endpoints and route handlers.
+
+## Conventions
+
+- REST conventions: use standard HTTP methods (GET, POST, PUT, DELETE).
+- Validate all inputs at the handler level before processing.
+- Return consistent error format: `{ "error": "message", "code": "ERROR_CODE" }`.
+- Group related endpoints in subdirectories by resource.
+- Keep handlers thin -- delegate business logic to services or models.
+```
+
+### scripts/ template (all stacks)
+
+```markdown
+<!-- Generated by /setup -- customize freely, /setup:refresh will regenerate if this comment is present -->
+# Scripts (scripts/)
+
+This directory contains build, development, and maintenance scripts.
+
+## Conventions
+
+- Shell scripts must be POSIX-compatible (sh, not bash-specific).
+- Include a usage comment at the top of each script explaining what it does and how to run it.
+- Scripts should be idempotent when possible -- safe to run multiple times.
+- Use `set -euo pipefail` (or POSIX equivalent) for error handling.
+- Keep scripts focused -- one task per script.
+```
+
+### docs/ template (all stacks)
+
+```markdown
+<!-- Generated by /setup -- customize freely, /setup:refresh will regenerate if this comment is present -->
+# Documentation (docs/)
+
+This directory contains project documentation.
+
+## Conventions
+
+- Keep docs current with code changes. Outdated docs are worse than no docs.
+- Use relative links between documents (not absolute URLs).
+- No auto-generated content in manually-written docs.
+- Structure: guides/ for how-tos, reference/ for API docs, architecture/ for system design.
+- Include diagrams as code (Mermaid, PlantUML) rather than binary images when possible.
+```
+
+---
+
+## Stage 5 — Generate CLAUDE.md
+
+Write CLAUDE.md under 100 lines. Sections:
+
+- **Why** (2-3 lines): project purpose
+- **Tech Stack** (8-12 lines): everything detected, with versions
+- **Project Map** (5-8 lines): key directories
+- **Build & Validate** (8-10 lines): exact commands
+- **Universal Rules** (5-7 lines): project-specific patterns
+- **Forbidden** (4-6 lines): things that break this project
+- **Methodology — GSD** (6-8 lines): reference /gsd: commands
+- **Toolbox — ECC** (6-8 lines): reference /verify, /checkpoint, /save-session, /learn
+- **Before ANY work** (2 lines): `npx skills find <keywords>`
+- **Reference Docs & MCP** (3-4 lines): point to docs/, contexts/, registries
+- **Gotchas** (3-5 lines): non-obvious things from scan
+
+Show the user and ask for corrections.
+
+---
+
+## Stage 6 — Generate Architecture Guide
+
+Create `docs/agent-guides/architecture.md`:
+
+**Existing**: system overview, auth flow, data model, request flow, key decisions.
+**New**: skeleton with planned architecture.
+
+---
+
+## Stage 7 — MCP Auto-Configuration
+
+Detect MCP-compatible binaries on PATH and add entries to `.mcp.json`.
+
+**Step 1: Read existing .mcp.json**
+
+Read the project's `.mcp.json` file. If missing or malformed JSON, start with `{ "mcpServers": {} }`.
+
+**Step 2: Check for binaries**
+
+Use the Bash tool to check for each binary:
+
+1. `which codebase-memory-mcp` (or `where codebase-memory-mcp` on Windows)
+2. `which ccc` (or `where ccc` on Windows)
+
+Wrap each in try/catch -- if `which` fails, the binary is not installed.
+
+**Step 3: Add entries for detected binaries**
+
+For each binary found:
+- Get the resolved path from the command output (stdout.trim())
+- Check if the corresponding key already exists in `mcpServers`:
+  - `codebase-memory-mcp` found and key `"codebase-memory-mcp"` missing: add `{ "command": "<resolved_path>", "args": [] }`
+  - `ccc` found and key `"cocoindex-code"` missing: add `{ "command": "<resolved_path>", "args": ["mcp"] }`
+  - Key already exists: skip (never overwrite user config)
+
+**Step 4: Write updated .mcp.json**
+
+Write the file back with `JSON.stringify(config, null, 2)`.
+
+**Step 5: Report status**
+
+```
+MCP Tool Detection:
+  [ADDED]   codebase-memory-mcp  /usr/local/bin/codebase-memory-mcp
+  [SKIP]    cocoindex-code       Already configured in .mcp.json
+  [MISSING] ccc                  Not found -- install with instructions below
+```
+
+For MISSING tools, print install instructions:
+- **codebase-memory-mcp**: `curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/scripts/setup.sh | bash`
+- **cocoindex-code (ccc)**: `pipx install cocoindex-code` or `uv tool install cocoindex-code`
+
+---
+
+## Stage 8 — Discover Skills & MCP
+
+Search for skills:
+```bash
+npx skills find [framework]
+npx skills find [language] [testing]
+npx skills find [database]
+```
+
+Check MCP registries (github.com/mcp, mcp.so) for relevant servers.
+
+---
+
+## Stage 9 — Initialize
+
+- **New project**: Suggest `/gsd:new-project` for roadmap/milestones
+- **Existing project**: Suggest `/gsd:quick "first task"` or `/gsd:discuss-phase 1`
+
+---
+
+## Stage 10 — Commit
+
+```bash
+git add CLAUDE.md */CLAUDE.md .claude/ .mcp.json docs/
+git commit -m "chore: add Claude Code Pilot
+
+- GSD methodology (32 commands, 12 agents)
+- ECC toolbox (sessions, learning, verification, quality gates)
+- Language rules: [detected]
+- Directory-scoped CLAUDE.md files: [list of directories]
+- MCP auto-configured: [list of detected tools]
+- Safety hooks + notifications
+- Architecture documentation"
+```
+
+Summary:
+```
+Setup complete!
+
+Configured:
+- CLAUDE.md — [X]-line project guide
+- [N] directory CLAUDE.md files (src/, test/, ...)
+- GSD — 32 commands, 12 agents, context monitoring, statusline
+- ECC — Sessions, learning, verification, checkpoints, quality gates
+- [N] ECC agents (architect, code-reviewer, security, tdd, ...)
+- [N] language rule sets activated
+- [N] ecosystem skills installed
+- MCP tools: [list of detected/added tools]
+- Safety hooks + desktop notifications
+
+Methodology:  /gsd:discuss → /gsd:plan → /gsd:execute → /gsd:verify
+Quality:      /verify → /checkpoint → /quality-gate
+Persistence:  /save-session → /resume-session → /learn → /evolve
+Update:       /kit:update
+```

package/kit/commands/tool-guide.md

@@ -0,0 +1,44 @@
+---
+description: "MCP tool recommendations per task type -- which tools to use when"
+---
+
+# Tool Guide
+
+MCP tools consume context tokens on every invocation. Selecting the right tools per task type improves response quality and speed. The principle: **use 3-5 focused tools, not every tool available.** Loading irrelevant tools wastes tokens and dilutes attention (Stripe's "15 from 400" insight).
+
+## Tool Inventory
+
+The kit configures or recommends these MCP tools:
+
+| Tool | What It Does |
+|------|-------------|
+| **Context7** | Up-to-date library documentation. Prevents hallucinated APIs. |
+| **codebase-memory-mcp** | Code navigation, call graph tracing, semantic search across your codebase. |
+| **cocoindex-code** | Code indexing and semantic search (alternative to codebase-memory-mcp). |
+| **find-skills** | Discover ecosystem skills, templates, and starter kits. |
+| **WebSearch / WebFetch** | Web research and URL content fetching (built-in or MCP). |
+
+## Recommendations by Task Type
+
+| Task Type | Use These | Why | Defer These |
+|-----------|-----------|-----|-------------|
+| **Coding / Implementation** | Context7 (library docs), codebase-memory-mcp (code nav) | Up-to-date APIs prevent hallucination. Code graph for navigation. | find-skills (only if new framework) |
+| **Research / Planning** | Context7 (docs), WebSearch, WebFetch | Need current information for architecture decisions. | codebase-memory-mcp (not needed for planning) |
+| **Code Review** | codebase-memory-mcp (trace call paths), Context7 (verify API usage) | Review needs code navigation and API correctness. | WebSearch (usually irrelevant) |
+| **Testing** | codebase-memory-mcp (find test patterns), Context7 (test framework docs) | Need existing patterns and framework APIs. | find-skills (only if new test framework) |
+| **Debugging** | codebase-memory-mcp (trace call paths), Context7 (verify APIs) | Debugging needs call graph tracing and API verification. | WebSearch (last resort) |
+| **Documentation** | Context7 (verify API accuracy), WebFetch (reference docs) | Docs must be accurate to current APIs. | codebase-memory-mcp (overkill for docs) |
+
+## Usage Tips
+
+- If a tool is not installed, Claude will skip it automatically -- no errors.
+- Use `/setup` to auto-detect and configure available MCP tools.
+- Context7 is the highest-value tool -- it prevents the #1 cause of agent errors (outdated API usage).
+- codebase-memory-mcp and cocoindex-code serve similar purposes -- you don't need both.
+- For large codebases (100+ files), codebase-memory-mcp significantly reduces context waste from file exploration.
+
+## When to Add New MCP Tools
+
+- Check [mcp.so](https://mcp.so) or [github.com/mcp](https://github.com/mcp) for domain-specific servers.
+- Add to `.mcp.json` only when the tool addresses a recurring need.
+- Prefer stdio servers (local binaries) over remote HTTP servers for speed and privacy.

package/kit/hooks/kit-check-update.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Kit update checker — SessionStart hook
+// Checks npm for newer claude-code-pilot version in background
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn } = require('child_process');
+
+const cwd = process.cwd();
+const homeDir = os.homedir();
+
+function findVersionFile() {
+  const local = path.join(cwd, '.claude', 'kit-version', 'VERSION');
+  if (fs.existsSync(local)) return local;
+  const configDir = process.env.CLAUDE_CONFIG_DIR || path.join(homeDir, '.claude');
+  const global = path.join(configDir, 'kit-version', 'VERSION');
+  if (fs.existsSync(global)) return global;
+  return null;
+}
+
+const versionFile = findVersionFile();
+if (!versionFile) process.exit(0);
+
+const configDir = process.env.CLAUDE_CONFIG_DIR || path.join(homeDir, '.claude');
+const cacheDir = path.join(configDir, 'cache');
+const cacheFile = path.join(cacheDir, 'kit-update-check.json');
+try { fs.mkdirSync(cacheDir, { recursive: true }); } catch {}
+
+// Background check
+const child = spawn(process.execPath, ['-e', `
+  const fs = require('fs');
+  const { execSync } = require('child_process');
+  const vf = ${JSON.stringify(versionFile)};
+  const cf = ${JSON.stringify(cacheFile)};
+  let installed = '0.0.0';
+  try { installed = fs.readFileSync(vf, 'utf8').trim(); } catch {}
+  let latest = null;
+  try { latest = execSync('npm view claude-code-pilot version', { encoding: 'utf8', timeout: 10000, windowsHide: true }).trim(); } catch {}
+  fs.writeFileSync(cf, JSON.stringify({ update_available: latest && installed !== latest, installed, latest: latest || 'unknown', checked: Math.floor(Date.now() / 1000) }));
+`], { stdio: 'ignore', windowsHide: true, detached: true });
+child.unref();
+
+// Show cached result if fresh
+try {
+  if (fs.existsSync(cacheFile)) {
+    const cached = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+    if ((Math.floor(Date.now() / 1000) - (cached.checked || 0)) < 86400 && cached.update_available) {
+      process.stdout.write(JSON.stringify({
+        additionalContext: `⬆️ Pilot update available: ${cached.installed} → ${cached.latest}. Run /kit:update to upgrade.`
+      }));
+    }
+  }
+} catch {}

package/kit/mcp.json

@@ -0,0 +1,10 @@
+{
+  "_comment": "MCP servers. Find more: github.com/mcp | mcp.so",
+  "mcpServers": {
+    "context7": {
+      "_comment": "Up-to-date library docs. Prevents hallucinated APIs.",
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    }
+  }
+}