Fix missing frontmatter (3 skills, 11 commands) + add CLAUDE.md, CI, and validation

.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

.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

.nvmrc

@@ -0,0 +1 @@
+20

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).

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:

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.

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:

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.

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.

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.

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:

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:

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:

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:

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.

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.

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.');

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.

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.

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.