diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..6d9bd4c --- /dev/null +++ b/.env.example @@ -0,0 +1,18 @@ +# Copy to .env and adjust as needed. All variables are optional; sensible +# defaults are used when unset. + +# Preferred package manager for scripts/lib/package-manager.js detection +# (npm | pnpm | yarn | bun). See README.md#package-manager-detection. +CLAUDE_PACKAGE_MANAGER= + +# Set by Claude Code itself; used by scripts/hooks/session-end.js and +# scripts/hooks/pre-compact.js to locate the session transcript. +CLAUDE_TRANSCRIPT_PATH= + +# Set by Claude Code itself; used by scripts/hooks/*.js to key +# per-session state. Falls back to the parent process id if unset. +CLAUDE_SESSION_ID= + +# Number of turns before scripts/hooks/suggest-compact.js suggests a +# strategic /compact. Defaults to 50. +COMPACT_THRESHOLD=50 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..8fd4cf4 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,23 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version-file: .nvmrc + + - name: Validate agent/command/skill frontmatter + run: node scripts/validate-frontmatter.js + + - name: Run test suite + run: node tests/run-all.js diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 0000000..209e3ef --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +20 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..f793224 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,43 @@ +# CLAUDE.md + +This file is the always-on entry point Claude Code loads when working in +this repository. It gives Claude project context automatically instead of +starting every session with none. + +## What this repo is + +**Everything Claude Code** is a Claude Code **plugin** distributing +production configs: `agents/`, `skills/`, `commands/`, `rules/`, `hooks/`, +`contexts/`, `mcp-configs/`, and cross-platform Node.js `scripts/`. See +[README.md](README.md) for the full directory map and installation options. + +## Conventions when contributing + +- **Agents** (`agents/*.md`) require YAML frontmatter with `name`, + `description`, `tools`, and `model`. See any file in `agents/` for the + pattern. +- **Commands** (`commands/*.md`) require a `description` field in + frontmatter. +- **Skills** (`skills/**/SKILL.md`) require `name` and `description` in + frontmatter — this is what Claude Code uses to discover and route to a + skill. A skill without it is silently invisible. +- Run `node scripts/validate-frontmatter.js` before committing to catch + missing/malformed frontmatter in agents, commands, and skills. +- See [CONTRIBUTING.md](CONTRIBUTING.md) for where to place new + contributions and the PR process. + +## Test command + +```bash +node tests/run-all.js +``` + +Runs the full suite (`tests/lib/*.test.js`, `tests/hooks/*.test.js`). CI runs +this automatically on every push and pull request — see +`.github/workflows/ci.yml`. + +## Scripts + +Cross-platform Node.js utilities live in `scripts/`. See +[scripts/AGENTS.md](scripts/AGENTS.md) for conventions specific to that +directory (package-manager detection, hook implementations). diff --git a/commands/build-fix.md b/commands/build-fix.md index d3a051b..32519dd 100644 --- a/commands/build-fix.md +++ b/commands/build-fix.md @@ -1,3 +1,7 @@ +--- +description: Incrementally fix TypeScript and build errors by parsing build output, grouping by file, and applying fixes one at a time with context. +--- + # Build and Fix Incrementally fix TypeScript and build errors: diff --git a/commands/checkpoint.md b/commands/checkpoint.md index 06293c0..c96a04b 100644 --- a/commands/checkpoint.md +++ b/commands/checkpoint.md @@ -1,3 +1,7 @@ +--- +description: Create, verify, or list workflow checkpoints. Usage: /checkpoint [create|verify|list] [name]. +--- + # Checkpoint Command Create or verify a checkpoint in your workflow. diff --git a/commands/code-review.md b/commands/code-review.md index 4e5ef01..91ece16 100644 --- a/commands/code-review.md +++ b/commands/code-review.md @@ -1,3 +1,7 @@ +--- +description: Comprehensive security and quality review of uncommitted changes, covering credentials, injection, XSS, input validation, and insecure dependencies. +--- + # Code Review Comprehensive security and quality review of uncommitted changes: diff --git a/commands/eval.md b/commands/eval.md index 7ded11d..a705fb2 100644 --- a/commands/eval.md +++ b/commands/eval.md @@ -1,3 +1,7 @@ +--- +description: Manage eval-driven development workflow - define, check, and report on capability/regression evals. Usage: /eval [define|check|report|list] [feature-name]. +--- + # Eval Command Manage eval-driven development workflow. diff --git a/commands/learn.md b/commands/learn.md index 9899af1..3dfd8f6 100644 --- a/commands/learn.md +++ b/commands/learn.md @@ -1,3 +1,7 @@ +--- +description: Analyze the current session and extract reusable patterns worth saving as a new skill. Run after solving a non-trivial problem. +--- + # /learn - Extract Reusable Patterns Analyze the current session and extract any patterns worth saving as skills. diff --git a/commands/orchestrate.md b/commands/orchestrate.md index 30ac2b8..866e21e 100644 --- a/commands/orchestrate.md +++ b/commands/orchestrate.md @@ -1,3 +1,7 @@ +--- +description: Run a sequential multi-agent workflow (e.g. planner -> tdd-guide -> code-reviewer -> security-reviewer) for complex tasks. Usage: /orchestrate [workflow-type] [task-description]. +--- + # Orchestrate Command Sequential agent workflow for complex tasks. diff --git a/commands/refactor-clean.md b/commands/refactor-clean.md index 6f5e250..5e6bf20 100644 --- a/commands/refactor-clean.md +++ b/commands/refactor-clean.md @@ -1,3 +1,7 @@ +--- +description: Safely identify and remove dead code using knip, depcheck, and ts-prune, with a categorized report and test verification before deletion. +--- + # Refactor Clean Safely identify and remove dead code with test verification: diff --git a/commands/test-coverage.md b/commands/test-coverage.md index 754eabf..f07f135 100644 --- a/commands/test-coverage.md +++ b/commands/test-coverage.md @@ -1,3 +1,7 @@ +--- +description: Analyze test coverage, identify files below the 80% threshold, and generate missing unit, integration, and E2E tests. +--- + # Test Coverage Analyze test coverage and generate missing tests: diff --git a/commands/update-codemaps.md b/commands/update-codemaps.md index f363a05..636a321 100644 --- a/commands/update-codemaps.md +++ b/commands/update-codemaps.md @@ -1,3 +1,7 @@ +--- +description: Scan the codebase and regenerate token-lean architecture codemaps (architecture, backend, frontend, data), gated on diff percentage and user approval. +--- + # Update Codemaps Analyze the codebase structure and update architecture documentation: diff --git a/commands/update-docs.md b/commands/update-docs.md index 3dd0f89..e2da747 100644 --- a/commands/update-docs.md +++ b/commands/update-docs.md @@ -1,3 +1,7 @@ +--- +description: Sync generated documentation (script reference, env vars, CONTRIB.md) from source-of-truth files like package.json and .env.example. +--- + # Update Documentation Sync documentation from source-of-truth: diff --git a/commands/verify.md b/commands/verify.md index 5f628b1..4cd4f2e 100644 --- a/commands/verify.md +++ b/commands/verify.md @@ -1,3 +1,7 @@ +--- +description: Run comprehensive verification (build, type check, lint, tests) on the current codebase state before continuing or opening a PR. +--- + # Verification Command Run comprehensive verification on current codebase state. diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md new file mode 100644 index 0000000..ff6beaa --- /dev/null +++ b/scripts/AGENTS.md @@ -0,0 +1,30 @@ +# scripts/ + +Cross-platform Node.js utilities used by hooks and slash commands. Rewritten +from shell scripts so they work identically on Windows, macOS, and Linux. + +## Structure + +- `lib/` — shared utilities (`utils.js` for file/path/system helpers, + `package-manager.js` for package-manager detection). +- `hooks/` — hook implementations invoked from `hooks/hooks.json` + (`session-start.js`, `session-end.js`, `pre-compact.js`, + `suggest-compact.js`, `evaluate-session.js`). +- `setup-package-manager.js` — interactive/CLI package-manager setup, also + exposed as the `/setup-pm` command. +- `validate-frontmatter.js` — checks that `agents/*.md`, `commands/*.md`, + and `skills/**/SKILL.md` have the required frontmatter fields. Run before + committing new agents/commands/skills, and enforced in CI. + +## Conventions + +- Node.js only, no OS-specific shell calls — that's the entire reason these + were rewritten from shell scripts. If you need a system operation, add it + to `lib/utils.js` rather than shelling out to a platform-specific command. +- Every new script under `lib/` or `hooks/` should have a matching + `*.test.js` under `tests/` and be added to the list in + `tests/run-all.js`. +- Package-manager selection always goes through + `lib/package-manager.js` — see the priority order documented in the root + [README.md](../README.md#package-manager-detection). Don't hardcode + `npm`/`pnpm`/`yarn`/`bun` elsewhere. diff --git a/scripts/validate-frontmatter.js b/scripts/validate-frontmatter.js new file mode 100644 index 0000000..cd88df0 --- /dev/null +++ b/scripts/validate-frontmatter.js @@ -0,0 +1,96 @@ +#!/usr/bin/env node +/** + * Validate required YAML frontmatter across agents, commands, and skills. + * + * - agents/*.md -> requires: name, description, tools, model + * - commands/*.md -> requires: description + * - skills/**\/SKILL.md -> requires: name, description + * + * Usage: node scripts/validate-frontmatter.js + * Exits with code 1 if any file is missing a required field. + */ + +const fs = require('fs'); +const path = require('path'); + +const repoRoot = path.join(__dirname, '..'); + +function listMarkdownFiles(dir) { + const results = []; + if (!fs.existsSync(dir)) return results; + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + const full = path.join(dir, entry.name); + if (entry.isDirectory()) { + results.push(...listMarkdownFiles(full)); + } else if (entry.isFile() && entry.name.endsWith('.md')) { + results.push(full); + } + } + return results; +} + +function parseFrontmatter(filePath) { + const content = fs.readFileSync(filePath, 'utf8'); + const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/); + if (!match) return null; + + const fields = {}; + for (const line of match[1].split(/\r?\n/)) { + const fieldMatch = line.match(/^([A-Za-z_-]+):/); + if (fieldMatch) fields[fieldMatch[1]] = true; + } + return fields; +} + +function checkFiles(files, requiredFields, label) { + const errors = []; + for (const file of files) { + const rel = path.relative(repoRoot, file); + const fields = parseFrontmatter(file); + if (!fields) { + errors.push(`${rel}: missing frontmatter block (---\\n...\\n---)`); + continue; + } + for (const field of requiredFields) { + if (!fields[field]) { + errors.push(`${rel}: missing required '${field}' in frontmatter`); + } + } + } + if (errors.length > 0) { + console.error(`\n${label}:`); + for (const e of errors) console.error(` ✗ ${e}`); + } else { + console.log(`✓ ${label}: all files OK (${files.length} checked)`); + } + return errors.length; +} + +let totalErrors = 0; + +totalErrors += checkFiles( + listMarkdownFiles(path.join(repoRoot, 'agents')), + ['name', 'description', 'tools', 'model'], + 'agents/*.md' +); + +totalErrors += checkFiles( + listMarkdownFiles(path.join(repoRoot, 'commands')), + ['description'], + 'commands/*.md' +); + +totalErrors += checkFiles( + listMarkdownFiles(path.join(repoRoot, 'skills')).filter( + (f) => path.basename(f) === 'SKILL.md' + ), + ['name', 'description'], + 'skills/**/SKILL.md' +); + +if (totalErrors > 0) { + console.error(`\n${totalErrors} frontmatter error(s) found.`); + process.exit(1); +} + +console.log('\nAll frontmatter checks passed.'); diff --git a/skills/eval-harness/SKILL.md b/skills/eval-harness/SKILL.md index 522937d..c12f1ca 100644 --- a/skills/eval-harness/SKILL.md +++ b/skills/eval-harness/SKILL.md @@ -1,3 +1,8 @@ +--- +name: eval-harness +description: Use this skill when defining success criteria before implementation, tracking regressions across changes, or measuring reliability with pass@k metrics. Implements eval-driven development (EDD) with capability and regression evals. +--- + # Eval Harness Skill A formal evaluation framework for Claude Code sessions, implementing eval-driven development (EDD) principles. diff --git a/skills/project-guidelines-example/SKILL.md b/skills/project-guidelines-example/SKILL.md index 0135855..1aa9c04 100644 --- a/skills/project-guidelines-example/SKILL.md +++ b/skills/project-guidelines-example/SKILL.md @@ -1,3 +1,8 @@ +--- +name: project-guidelines-example +description: Example project-specific skill template covering architecture overview, file structure, code patterns, testing requirements, and deployment workflow. Copy and adapt this as a starting point for your own project's guidelines skill. +--- + # Project Guidelines Skill (Example) This is an example of a project-specific skill. Use this as a template for your own projects. diff --git a/skills/verification-loop/SKILL.md b/skills/verification-loop/SKILL.md index b56bb7e..9b3b570 100644 --- a/skills/verification-loop/SKILL.md +++ b/skills/verification-loop/SKILL.md @@ -1,3 +1,8 @@ +--- +name: verification-loop +description: Use this skill after completing a feature or significant code change, before creating a PR, or after refactoring. Runs build, type-check, lint, and test verification phases to ensure quality gates pass. +--- + # Verification Loop Skill A comprehensive verification system for Claude Code sessions.