claude-code-pilot 2.0.0 → 3.1.0

package/src/skills/laravel-verification/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: laravel-verification
+description: Verification loop for Laravel projects: env checks, linting, static analysis, tests with coverage, security scans, and deployment readiness.
+origin: ECC
+---
+
+# Laravel Verification Loop
+
+Run before PRs, after major changes, and pre-deploy.
+
+## When to Use
+
+- Before opening a pull request for a Laravel project
+- After major refactors or dependency upgrades
+- Pre-deployment verification for staging or production
+- Running full lint -> test -> security -> deploy readiness pipeline
+
+## How It Works
+
+- Run phases sequentially from environment checks through deployment readiness so each layer builds on the last.
+- Environment and Composer checks gate everything else; stop immediately if they fail.
+- Linting/static analysis should be clean before running full tests and coverage.
+- Security and migration reviews happen after tests so you verify behavior before data or release steps.
+- Build/deploy readiness and queue/scheduler checks are final gates; any failure blocks release.
+
+## Phase 1: Environment Checks
+
+```bash
+php -v
+composer --version
+php artisan --version
+```
+
+- Verify `.env` is present and required keys exist
+- Confirm `APP_DEBUG=false` for production environments
+- Confirm `APP_ENV` matches the target deployment (`production`, `staging`)
+
+If using Laravel Sail locally:
+
+```bash
+./vendor/bin/sail php -v
+./vendor/bin/sail artisan --version
+```
+
+## Phase 1.5: Composer and Autoload
+
+```bash
+composer validate
+composer dump-autoload -o
+```
+
+## Phase 2: Linting and Static Analysis
+
+```bash
+vendor/bin/pint --test
+vendor/bin/phpstan analyse
+```
+
+If your project uses Psalm instead of PHPStan:
+
+```bash
+vendor/bin/psalm
+```
+
+## Phase 3: Tests and Coverage
+
+```bash
+php artisan test
+```
+
+Coverage (CI):
+
+```bash
+XDEBUG_MODE=coverage php artisan test --coverage
+```
+
+CI example (format -> static analysis -> tests):
+
+```bash
+vendor/bin/pint --test
+vendor/bin/phpstan analyse
+XDEBUG_MODE=coverage php artisan test --coverage
+```
+
+## Phase 4: Security and Dependency Checks
+
+```bash
+composer audit
+```
+
+## Phase 5: Database and Migrations
+
+```bash
+php artisan migrate --pretend
+php artisan migrate:status
+```
+
+- Review destructive migrations carefully
+- Ensure migration filenames follow `Y_m_d_His_*` (e.g., `2025_03_14_154210_create_orders_table.php`) and describe the change clearly
+- Ensure rollbacks are possible
+- Verify `down()` methods and avoid irreversible data loss without explicit backups
+
+## Phase 6: Build and Deployment Readiness
+
+```bash
+php artisan optimize:clear
+php artisan config:cache
+php artisan route:cache
+php artisan view:cache
+```
+
+- Ensure cache warmups succeed in production configuration
+- Verify queue workers and scheduler are configured
+- Confirm `storage/` and `bootstrap/cache/` are writable in the target environment
+
+## Phase 7: Queue and Scheduler Checks
+
+```bash
+php artisan schedule:list
+php artisan queue:failed
+```
+
+If Horizon is used:
+
+```bash
+php artisan horizon:status
+```
+
+If `queue:monitor` is available, use it to check backlog without processing jobs:
+
+```bash
+php artisan queue:monitor default --max=100
+```
+
+Active verification (staging only): dispatch a no-op job to a dedicated queue and run a single worker to process it (ensure a non-`sync` queue connection is configured).
+
+```bash
+php artisan tinker --execute="dispatch((new App\\Jobs\\QueueHealthcheck())->onQueue('healthcheck'))"
+php artisan queue:work --once --queue=healthcheck
+```
+
+Verify the job produced the expected side effect (log entry, healthcheck table row, or metric).
+
+Only run this on non-production environments where processing a test job is safe.
+
+## Examples
+
+Minimal flow:
+
+```bash
+php -v
+composer --version
+php artisan --version
+composer validate
+vendor/bin/pint --test
+vendor/bin/phpstan analyse
+php artisan test
+composer audit
+php artisan migrate --pretend
+php artisan config:cache
+php artisan queue:failed
+```
+
+CI-style pipeline:
+
+```bash
+composer validate
+composer dump-autoload -o
+vendor/bin/pint --test
+vendor/bin/phpstan analyse
+XDEBUG_MODE=coverage php artisan test --coverage
+composer audit
+php artisan migrate --pretend
+php artisan optimize:clear
+php artisan config:cache
+php artisan route:cache
+php artisan view:cache
+php artisan schedule:list
+```

package/src/skills/mcp-server-patterns/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: mcp-server-patterns
+description: Build MCP servers with Node/TypeScript SDK — tools, resources, prompts, Zod validation, stdio vs Streamable HTTP. Use Context7 or official MCP docs for latest API.
+origin: ECC
+---
+
+# MCP Server Patterns
+
+The Model Context Protocol (MCP) lets AI assistants call tools, read resources, and use prompts from your server. Use this skill when building or maintaining MCP servers. The SDK API evolves; check Context7 (query-docs for "MCP") or the official MCP documentation for current method names and signatures.
+
+## When to Use
+
+Use when: implementing a new MCP server, adding tools or resources, choosing stdio vs HTTP, upgrading the SDK, or debugging MCP registration and transport issues.
+
+## How It Works
+
+### Core concepts
+
+- **Tools**: Actions the model can invoke (e.g. search, run a command). Register with `registerTool()` or `tool()` depending on SDK version.
+- **Resources**: Read-only data the model can fetch (e.g. file contents, API responses). Register with `registerResource()` or `resource()`. Handlers typically receive a `uri` argument.
+- **Prompts**: Reusable, parameterised prompt templates the client can surface (e.g. in Claude Desktop). Register with `registerPrompt()` or equivalent.
+- **Transport**: stdio for local clients (e.g. Claude Desktop); Streamable HTTP is preferred for remote (Cursor, cloud). Legacy HTTP/SSE is for backward compatibility.
+
+The Node/TypeScript SDK may expose `tool()` / `resource()` or `registerTool()` / `registerResource()`; the official SDK has changed over time. Always verify against the current [MCP docs](https://modelcontextprotocol.io) or Context7.
+
+### Connecting with stdio
+
+For local clients, create a stdio transport and pass it to your server’s connect method. The exact API varies by SDK version (e.g. constructor vs factory). See the official MCP documentation or query Context7 for "MCP stdio server" for the current pattern.
+
+Keep server logic (tools + resources) independent of transport so you can plug in stdio or HTTP in the entrypoint.
+
+### Remote (Streamable HTTP)
+
+For Cursor, cloud, or other remote clients, use **Streamable HTTP** (single MCP HTTP endpoint per current spec). Support legacy HTTP/SSE only when backward compatibility is required.
+
+## Examples
+
+### Install and server setup
+
+```bash
+npm install @modelcontextprotocol/sdk zod
+```
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+const server = new McpServer({ name: "my-server", version: "1.0.0" });
+```
+
+Register tools and resources using the API your SDK version provides: some versions use `server.tool(name, description, schema, handler)` (positional args), others use `server.tool({ name, description, inputSchema }, handler)` or `registerTool()`. Same for resources — include a `uri` in the handler when the API provides it. Check the official MCP docs or Context7 for the current `@modelcontextprotocol/sdk` signatures to avoid copy-paste errors.
+
+Use **Zod** (or the SDK’s preferred schema format) for input validation.
+
+## Best Practices
+
+- **Schema first**: Define input schemas for every tool; document parameters and return shape.
+- **Errors**: Return structured errors or messages the model can interpret; avoid raw stack traces.
+- **Idempotency**: Prefer idempotent tools where possible so retries are safe.
+- **Rate and cost**: For tools that call external APIs, consider rate limits and cost; document in the tool description.
+- **Versioning**: Pin SDK version in package.json; check release notes when upgrading.
+
+## Official SDKs and Docs
+
+- **JavaScript/TypeScript**: `@modelcontextprotocol/sdk` (npm). Use Context7 with library name "MCP" for current registration and transport patterns.
+- **Go**: Official Go SDK on GitHub (`modelcontextprotocol/go-sdk`).
+- **C#**: Official C# SDK for .NET.

package/src/skills/nextjs-turbopack/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: nextjs-turbopack
+description: Next.js 16+ and Turbopack — incremental bundling, FS caching, dev speed, and when to use Turbopack vs webpack.
+origin: ECC
+---
+
+# Next.js and Turbopack
+
+Next.js 16+ uses Turbopack by default for local development: an incremental bundler written in Rust that significantly speeds up dev startup and hot updates.
+
+## When to Use
+
+- **Turbopack (default dev)**: Use for day-to-day development. Faster cold start and HMR, especially in large apps.
+- **Webpack (legacy dev)**: Use only if you hit a Turbopack bug or rely on a webpack-only plugin in dev. Disable with `--webpack` (or `--no-turbopack` depending on your Next.js version; check the docs for your release).
+- **Production**: Production build behavior (`next build`) may use Turbopack or webpack depending on Next.js version; check the official Next.js docs for your version.
+
+Use when: developing or debugging Next.js 16+ apps, diagnosing slow dev startup or HMR, or optimizing production bundles.
+
+## How It Works
+
+- **Turbopack**: Incremental bundler for Next.js dev. Uses file-system caching so restarts are much faster (e.g. 5–14x on large projects).
+- **Default in dev**: From Next.js 16, `next dev` runs with Turbopack unless disabled.
+- **File-system caching**: Restarts reuse previous work; cache is typically under `.next`; no extra config needed for basic use.
+- **Bundle Analyzer (Next.js 16.1+)**: Experimental Bundle Analyzer to inspect output and find heavy dependencies; enable via config or experimental flag (see Next.js docs for your version).
+
+## Examples
+
+### Commands
+
+```bash
+next dev
+next build
+next start
+```
+
+### Usage
+
+Run `next dev` for local development with Turbopack. Use the Bundle Analyzer (see Next.js docs) to optimize code-splitting and trim large dependencies. Prefer App Router and server components where possible.
+
+## Best Practices
+
+- Stay on a recent Next.js 16.x for stable Turbopack and caching behavior.
+- If dev is slow, ensure you're on Turbopack (default) and that the cache isn't being cleared unnecessarily.
+- For production bundle size issues, use the official Next.js bundle analysis tooling for your version.

package/src/skills/nuxt4-patterns/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: nuxt4-patterns
+description: Nuxt 4 app patterns for hydration safety, performance, route rules, lazy loading, and SSR-safe data fetching with useFetch and useAsyncData.
+origin: ECC
+---
+
+# Nuxt 4 Patterns
+
+Use when building or debugging Nuxt 4 apps with SSR, hybrid rendering, route rules, or page-level data fetching.
+
+## When to Activate
+
+- Hydration mismatches between server HTML and client state
+- Route-level rendering decisions such as prerender, SWR, ISR, or client-only sections
+- Performance work around lazy loading, lazy hydration, or payload size
+- Page or component data fetching with `useFetch`, `useAsyncData`, or `$fetch`
+- Nuxt routing issues tied to route params, middleware, or SSR/client differences
+
+## Hydration Safety
+
+- Keep the first render deterministic. Do not put `Date.now()`, `Math.random()`, browser-only APIs, or storage reads directly into SSR-rendered template state.
+- Move browser-only logic behind `onMounted()`, `import.meta.client`, `ClientOnly`, or a `.client.vue` component when the server cannot produce the same markup.
+- Use Nuxt's `useRoute()` composable, not the one from `vue-router`.
+- Do not use `route.fullPath` to drive SSR-rendered markup. URL fragments are client-only, which can create hydration mismatches.
+- Treat `ssr: false` as an escape hatch for truly browser-only areas, not a default fix for mismatches.
+
+## Data Fetching
+
+- Prefer `await useFetch()` for SSR-safe API reads in pages and components. It forwards server-fetched data into the Nuxt payload and avoids a second fetch on hydration.
+- Use `useAsyncData()` when the fetcher is not a simple `$fetch()` call, when you need a custom key, or when you are composing multiple async sources.
+- Give `useAsyncData()` a stable key for cache reuse and predictable refresh behavior.
+- Keep `useAsyncData()` handlers side-effect free. They can run during SSR and hydration.
+- Use `$fetch()` for user-triggered writes or client-only actions, not top-level page data that should be hydrated from SSR.
+- Use `lazy: true`, `useLazyFetch()`, or `useLazyAsyncData()` for non-critical data that should not block navigation. Handle `status === 'pending'` in the UI.
+- Use `server: false` only for data that is not needed for SEO or the first paint.
+- Trim payload size with `pick` and prefer shallower payloads when deep reactivity is unnecessary.
+
+```ts
+const route = useRoute()
+
+const { data: article, status, error, refresh } = await useAsyncData(
+  () => `article:${route.params.slug}`,
+  () => $fetch(`/api/articles/${route.params.slug}`),
+)
+
+const { data: comments } = await useFetch(`/api/articles/${route.params.slug}/comments`, {
+  lazy: true,
+  server: false,
+})
+```
+
+## Route Rules
+
+Prefer `routeRules` in `nuxt.config.ts` for rendering and caching strategy:
+
+```ts
+export default defineNuxtConfig({
+  routeRules: {
+    '/': { prerender: true },
+    '/products/**': { swr: 3600 },
+    '/blog/**': { isr: true },
+    '/admin/**': { ssr: false },
+    '/api/**': { cache: { maxAge: 60 * 60 } },
+  },
+})
+```
+
+- `prerender`: static HTML at build time
+- `swr`: serve cached content and revalidate in the background
+- `isr`: incremental static regeneration on supported platforms
+- `ssr: false`: client-rendered route
+- `cache` or `redirect`: Nitro-level response behavior
+
+Pick route rules per route group, not globally. Marketing pages, catalogs, dashboards, and APIs usually need different strategies.
+
+## Lazy Loading and Performance
+
+- Nuxt already code-splits pages by route. Keep route boundaries meaningful before micro-optimizing component splits.
+- Use the `Lazy` prefix to dynamically import non-critical components.
+- Conditionally render lazy components with `v-if` so the chunk is not loaded until the UI actually needs it.
+- Use lazy hydration for below-the-fold or non-critical interactive UI.
+
+```vue
+<template>
+  <LazyRecommendations v-if="showRecommendations" />
+  <LazyProductGallery hydrate-on-visible />
+</template>
+```
+
+- For custom strategies, use `defineLazyHydrationComponent()` with a visibility or idle strategy.
+- Nuxt lazy hydration works on single-file components. Passing new props to a lazily hydrated component will trigger hydration immediately.
+- Use `NuxtLink` for internal navigation so Nuxt can prefetch route components and generated payloads.
+
+## Review Checklist
+
+- First SSR render and hydrated client render produce the same markup
+- Page data uses `useFetch` or `useAsyncData`, not top-level `$fetch`
+- Non-critical data is lazy and has explicit loading UI
+- Route rules match the page's SEO and freshness requirements
+- Heavy interactive islands are lazy-loaded or lazily hydrated

package/src/skills/opensource-pipeline/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: opensource-pipeline
+description: "Open-source pipeline: fork, sanitize, and package private projects for safe public release. Chains 3 agents (forker, sanitizer, packager). Triggers: '/opensource', 'open source this', 'make this public', 'prepare for open source'."
+origin: ECC
+---
+
+# Open-Source Pipeline Skill
+
+Safely open-source any project through a 3-stage pipeline: **Fork** (strip secrets) → **Sanitize** (verify clean) → **Package** (CLAUDE.md + setup.sh + README).
+
+## When to Activate
+
+- User says "open source this project" or "make this public"
+- User wants to prepare a private repo for public release
+- User needs to strip secrets before pushing to GitHub
+- User invokes `/opensource fork`, `/opensource verify`, or `/opensource package`
+
+## Commands
+
+| Command | Action |
+|---------|--------|
+| `/opensource fork PROJECT` | Full pipeline: fork + sanitize + package |
+| `/opensource verify PROJECT` | Run sanitizer on existing repo |
+| `/opensource package PROJECT` | Generate CLAUDE.md + setup.sh + README |
+| `/opensource list` | Show all staged projects |
+| `/opensource status PROJECT` | Show reports for a staged project |
+
+## Protocol
+
+### /opensource fork PROJECT
+
+**Full pipeline — the main workflow.**
+
+#### Step 1: Gather Parameters
+
+Resolve the project path. If PROJECT contains `/`, treat as a path (absolute or relative). Otherwise check: current working directory, `$HOME/PROJECT`, then ask the user.
+
+```
+SOURCE_PATH="<resolved absolute path>"
+STAGING_PATH="$HOME/opensource-staging/${PROJECT_NAME}"
+```
+
+Ask the user:
+1. "Which project?" (if not found)
+2. "License? (MIT / Apache-2.0 / GPL-3.0 / BSD-3-Clause)"
+3. "GitHub org or username?" (default: detect via `gh api user -q .login`)
+4. "GitHub repo name?" (default: project name)
+5. "Description for README?" (analyze project for suggestion)
+
+#### Step 2: Create Staging Directory
+
+```bash
+mkdir -p $HOME/opensource-staging/
+```
+
+#### Step 3: Run Forker Agent
+
+Spawn the `opensource-forker` agent:
+
+```
+Agent(
+  description="Fork {PROJECT} for open-source",
+  subagent_type="opensource-forker",
+  prompt="""
+Fork project for open-source release.
+
+Source: {SOURCE_PATH}
+Target: {STAGING_PATH}
+License: {chosen_license}
+
+Follow the full forking protocol:
+1. Copy files (exclude .git, node_modules, __pycache__, .venv)
+2. Strip all secrets and credentials
+3. Replace internal references with placeholders
+4. Generate .env.example
+5. Clean git history
+6. Generate FORK_REPORT.md in {STAGING_PATH}/FORK_REPORT.md
+"""
+)
+```
+
+Wait for completion. Read `{STAGING_PATH}/FORK_REPORT.md`.
+
+#### Step 4: Run Sanitizer Agent
+
+Spawn the `opensource-sanitizer` agent:
+
+```
+Agent(
+  description="Verify {PROJECT} sanitization",
+  subagent_type="opensource-sanitizer",
+  prompt="""
+Verify sanitization of open-source fork.
+
+Project: {STAGING_PATH}
+Source (for reference): {SOURCE_PATH}
+
+Run ALL scan categories:
+1. Secrets scan (CRITICAL)
+2. PII scan (CRITICAL)
+3. Internal references scan (CRITICAL)
+4. Dangerous files check (CRITICAL)
+5. Configuration completeness (WARNING)
+6. Git history audit
+
+Generate SANITIZATION_REPORT.md inside {STAGING_PATH}/ with PASS/FAIL verdict.
+"""
+)
+```
+
+Wait for completion. Read `{STAGING_PATH}/SANITIZATION_REPORT.md`.
+
+**If FAIL:** Show findings to user. Ask: "Fix these and re-scan, or abort?"
+- If fix: Apply fixes, re-run sanitizer (maximum 3 retry attempts — after 3 FAILs, present all findings and ask user to fix manually)
+- If abort: Clean up staging directory
+
+**If PASS or PASS WITH WARNINGS:** Continue to Step 5.
+
+#### Step 5: Run Packager Agent
+
+Spawn the `opensource-packager` agent:
+
+```
+Agent(
+  description="Package {PROJECT} for open-source",
+  subagent_type="opensource-packager",
+  prompt="""
+Generate open-source packaging for project.
+
+Project: {STAGING_PATH}
+License: {chosen_license}
+Project name: {PROJECT_NAME}
+Description: {description}
+GitHub repo: {github_repo}
+
+Generate:
+1. CLAUDE.md (commands, architecture, key files)
+2. setup.sh (one-command bootstrap, make executable)
+3. README.md (or enhance existing)
+4. LICENSE
+5. CONTRIBUTING.md
+6. .github/ISSUE_TEMPLATE/ (bug_report.md, feature_request.md)
+"""
+)
+```
+
+#### Step 6: Final Review
+
+Present to user:
+```
+Open-Source Fork Ready: {PROJECT_NAME}
+
+Location: {STAGING_PATH}
+License: {license}
+Files generated:
+  - CLAUDE.md
+  - setup.sh (executable)
+  - README.md
+  - LICENSE
+  - CONTRIBUTING.md
+  - .env.example ({N} variables)
+
+Sanitization: {sanitization_verdict}
+
+Next steps:
+  1. Review: cd {STAGING_PATH}
+  2. Create repo: gh repo create {github_org}/{github_repo} --public
+  3. Push: git remote add origin ... && git push -u origin main
+
+Proceed with GitHub creation? (yes/no/review first)
+```
+
+#### Step 7: GitHub Publish (on user approval)
+
+```bash
+cd "{STAGING_PATH}"
+gh repo create "{github_org}/{github_repo}" --public --source=. --push --description "{description}"
+```
+
+---
+
+### /opensource verify PROJECT
+
+Run sanitizer independently. Resolve path: if PROJECT contains `/`, treat as a path. Otherwise check `$HOME/opensource-staging/PROJECT`, then `$HOME/PROJECT`, then current directory.
+
+```
+Agent(
+  subagent_type="opensource-sanitizer",
+  prompt="Verify sanitization of: {resolved_path}. Run all 6 scan categories and generate SANITIZATION_REPORT.md."
+)
+```
+
+---
+
+### /opensource package PROJECT
+
+Run packager independently. Ask for "License?" and "Description?", then:
+
+```
+Agent(
+  subagent_type="opensource-packager",
+  prompt="Package: {resolved_path} ..."
+)
+```
+
+---
+
+### /opensource list
+
+```bash
+ls -d $HOME/opensource-staging/*/
+```
+
+Show each project with pipeline progress (FORK_REPORT.md, SANITIZATION_REPORT.md, CLAUDE.md presence).
+
+---
+
+### /opensource status PROJECT
+
+```bash
+cat $HOME/opensource-staging/${PROJECT}/SANITIZATION_REPORT.md
+cat $HOME/opensource-staging/${PROJECT}/FORK_REPORT.md
+```
+
+## Staging Layout
+
+```
+$HOME/opensource-staging/
+  my-project/
+    FORK_REPORT.md           # From forker agent
+    SANITIZATION_REPORT.md   # From sanitizer agent
+    CLAUDE.md                # From packager agent
+    setup.sh                 # From packager agent
+    README.md                # From packager agent
+    .env.example             # From forker agent
+    ...                      # Sanitized project files
+```
+
+## Anti-Patterns
+
+- **Never** push to GitHub without user approval
+- **Never** skip the sanitizer — it is the safety gate
+- **Never** proceed after a sanitizer FAIL without fixing all critical findings
+- **Never** leave `.env`, `*.pem`, or `credentials.json` in the staging directory
+
+## Best Practices
+
+- Always run the full pipeline (fork → sanitize → package) for new releases
+- The staging directory persists until explicitly cleaned up — use it for review
+- Re-run the sanitizer after any manual fixes before publishing
+- Parameterize secrets rather than deleting them — preserve project functionality
+
+## Related Skills
+
+See `security-review` for secret detection patterns used by the sanitizer.