# Implementation Tracker

**Last Updated**: 2026-02-06
**Status**: Phases 0-4 Complete (~85%). Phase 5 (testing + release) remaining.

Track progress across all phases. Mark tasks complete with `[x]` as you finish them.

## Remaining Work

- Phase 2.5: Constants verification not yet wired into pre-commit hook or CI
- Task 3.8: Manual testing of optimize-cc-md (deferred)
- Phase 5.2-5.3: Manual testing execution — Manual testing infrastructure is now ready (archived as MVP complete)
- Phase 5.4-5.5: Version bump and release

**When to resume**: After infrastructure project Phase 6 complete (see below)

**Why deferred**: Original manual testing approach was broken (no project context). Created sub-project to build proper infrastructure first.

**Infrastructure Project**: `docs/projects/manual-testing-infrastructure-refactor/`

- **Status**: MVP complete (Task 2 infrastructure ready)
- **Next**: Phase 6 - Expand to Tasks 1, 3-6
- **Then**: Return here to execute Task 5.2-5.3 using that infrastructure
- **See**: Infrastructure project tracker.md for workflow details

## Phase 0: Research & Planning

**Status**: Complete
**Duration**: 1 day

- [x] Review Claude skills PDF best practices
- [x] Research plugin distribution model
- [x] Document skill naming constraints (no "claude"/"anthropic")
- [x] Create project structure in docs/projects/
- [x] Finalize skill names for CLAUDE.md management
- [x] Review existing skills for namespace compatibility
- [x] Confirmed 14 CLAUDE.md validation rules already exist in src/rules/claude-md/
- [x] Confirmed /init command is closed-source, not in public repo

## Key Findings

### Phase 0-2 Findings

- **CLAUDE.md validation already implemented**: 14 rules exist covering imports, size, sections, etc.
- **/init is closed-source**: Built-in CLI command, not in github.com/anthropics/claude-code repo
- **Package.json bug**: `"files": ["skills"]` should be `".claude"` - npm users get zero skills
- **Skill naming**: Use `-cc-md` suffix (cc = Claude Code configuration)

### Testing Methodology (Phase 3-5)

**Critical insight**: We do NOT need a separate testing framework for our bundled skills.

**Why**: This project IS claudelint - a linter for Claude Code projects that validates skills.

**Approach**:

1. **Automated testing = dogfooding**
   - Use claudelint itself to validate our bundled skills
   - Run: `claudelint validate-skills .claude/skills/`
   - This validates structure, security, frontmatter, etc. (28+ rules)
   - If our tool can't validate our skills, we have a tool problem

2. **Manual testing = UX validation**
   - Test trigger effectiveness (does Claude load the skill?)
   - Test conversational quality (does Claude explain clearly?)
   - Test real-world usage (does the skill help users?)
   - Per Anthropic: "automated benchmarks help, but real-world testing reveals issues"

**Documentation**: See `docs/skill-testing.md` for complete methodology

**No framework needed**: claudelint already has 28 skill validation rules + 72 planned

## Phase 1: Critical Bug Fixes & Plugin Infrastructure

**Status**: COMPLETE (100% - 9/9 tasks done)
**Duration**: Completed
**Dependencies**: Phase 0 complete

**Completed**: All tasks 1.1-1.9 (package.json, plugin.json, skill renames, schema fix, E10 rule, testing, dependency checks, documentation, README trimming)

### Tasks

- [x] **Task 1.1**: Fix package.json files array bug
  - [x] Remove invalid `"skills"` entry (directory doesn't exist)
  - [x] Update to include `".claude"` (skills are part of npm package)
  - [x] npm package includes: CLI + skills for plugin registration
  - [x] **Understanding**: npm package is primary, plugin points to it

  **Distribution Model (FINAL - follows LSP plugin pattern):**

  Similar to LSP plugins (pyright-lsp requires pyright-langserver binary):
  - **claudelint plugin** (skills) requires **claude-code-lint npm package** (CLI binary)

  **Primary flow (recommended):**

  ```bash
  # 1. Install npm package (gets CLI + skills)
  npm install --save-dev claude-code-lint

  # 2. Register plugin with Claude Code (points to npm install)
  /plugin install --source ./node_modules/claude-code-lint

  # 3. Use CLI commands
  npx claudelint check-all

  # 4. Use skills in Claude Code
  /claudelint:validate-all
  ```

  **Alternative: GitHub install (for users who only want skills)**

  ```bash
  # Must have npm package installed FIRST (dependency)
  npm install --save-dev claude-code-lint

  # Then install plugin from GitHub
  /plugin install github:pdugan20/claudelint
  ```

  **Why this works:**
  - Skills are shell scripts that call `npx claude-code-lint` commands
  - npx uses project install if available, falls back to global
  - Skills fail gracefully with install instructions if package missing
  - Matches established LSP plugin pattern

  **Verification Steps:**
  1. Before fix: `npm pack && tar -tzf claude-code-lint-*.tgz | grep "\.claude/"` (should be empty or shouldn't exist)
  2. Make change: Remove `"skills"` and `".claude"` from files array
  3. After fix: Verify only CLI files included:

     ```bash
     npm pack
     tar -tzf claude-code-lint-*.tgz | grep -E "^package/(dist|bin|README|LICENSE)" | head -10
     tar -tzf claude-code-lint-*.tgz | grep "\.claude" # should be empty
     ```

  4. Verify package is smaller (no skills bloat)
  5. Test CLI install: `npm install -g ./claude-code-lint-*.tgz && claudelint --version`
  6. Clean up: `rm claude-code-lint-*.tgz && npm uninstall -g claude-code-lint`

- [x] **Task 1.2**: Create `.claude-plugin/plugin.json` manifest
  - [x] Add required `name` field: "claudelint"
  - [x] Add metadata (version, description, author)
  - [x] No custom paths needed (use defaults)

  **Verification Steps:**
  1. Create `.claude-plugin/plugin.json` with minimal required fields
  2. Validate JSON syntax: `cat .claude-plugin/plugin.json | jq .` (should output formatted JSON)
  3. Verify required field: `jq -r '.name' .claude-plugin/plugin.json` (should output "claudelint")
  4. Verify in npm pack: `npm pack && tar -tzf claude-code-lint-*.tgz | grep "plugin.json"` (should see it)
  5. Clean up: `rm claude-code-lint-*.tgz`

- [x] **Task 1.3**: Rename generic skills to specific names
  - [x] Rename `validate-agents-md` → `validate-cc-md` (validates CLAUDE.md files)
  - [x] Rename `validate` → `validate-all` (validates all project files)
  - [x] Rename `format` → `format-cc` (formats Claude Code files)
  - [x] Update SKILL.md name and description in each
  - [x] Rename shell scripts to match: format-cc.sh, validate-all.sh, validate-cc-md.sh
  - [x] Update plugin.json skill references to use paths
  - [x] Update integration tests with new skill names
  - [x] Remove deprecated .claude-plugin directory

  **Verification Steps (repeat for each skill):**

  For validate-agents-md → validate-cc-md:
  1. Before: `ls .claude/skills/validate-agents-md/SKILL.md` (should exist)
  2. Rename directory: `mv .claude/skills/validate-agents-md .claude/skills/validate-cc-md`
  3. Update frontmatter: Edit SKILL.md, change `name: validate-agents-md` to `name: validate-cc-md`
  4. Update description to mention "CLAUDE.md" not "agents"
  5. After: `ls .claude/skills/validate-agents-md` (should fail), `ls .claude/skills/validate-cc-md/SKILL.md` (should exist)
  6. Verify frontmatter: `grep "^name: validate-cc-md" .claude/skills/validate-cc-md/SKILL.md`

  For validate → validate-all:
  1. Before: `ls .claude/skills/validate/SKILL.md`
  2. Rename: `mv .claude/skills/validate .claude/skills/validate-all`
  3. Update SKILL.md name field
  4. After: Verify old dir gone, new dir exists, frontmatter correct

  For format → format-cc:
  1. Before: `ls .claude/skills/format/SKILL.md`
  2. Rename: `mv .claude/skills/format .claude/skills/format-cc`
  3. Update SKILL.md name field
  4. After: Verify old dir gone, new dir exists, frontmatter correct

  Check for stale references:

  ```bash
  grep -r "validate\"" .claude/skills/  # should find nothing with old name
  grep -r "format\"" .claude/skills/   # should find nothing with old name
  grep -r "validate-agents-md" docs/  # should find nothing
  ```

- [x] **Task 1.4**: Fix plugin.json schema to match official Claude Code spec
  - [x] Update PluginManifestSchema in src/validators/schemas.ts
  - [x] Fix `author` field: string → string|object with {name, email?, url?}
  - [x] Fix `description`: required → optional
  - [x] Add missing fields: homepage, keywords, outputStyles, lspServers
  - [x] Fix path fields: array → string|array (skills, agents, commands)
  - [x] Fix config fields: array → string|object (hooks, mcpServers, lspServers)
  - [x] Remove undocumented `dependencies` field
  - [x] Deprecate plugin-dependency-invalid-version rule (dependencies field doesn't exist in spec)
  - [x] Deprecate plugin-circular-dependency rule (dependencies field doesn't exist in spec)
  - [x] Update plugin-missing-file.ts to handle union types (string|array|object)
  - [x] Update deprecated rule tests to reflect no-op behavior
  - [x] Update rule verification script to skip deprecated rules
  - [x] Create bin/claudelint wrapper for npm binary
  - [x] All 75 plugin tests passing

  **Note**: Rules deprecated (not deleted yet) - see discussion about deletion vs deprecation

  **Verification Steps:**
  1. Compare current schema with official docs: <https://code.claude.com/docs/en/plugins-reference#complete-schema>
  2. Update schema in src/validators/schemas.ts
  3. Validate our plugin.json: `cat .claude-plugin/plugin.json | jq .` (should pass)
  4. Run tests: `npm test -- plugin` (should pass)
  5. Test schema validation catches errors:

     ```bash
     echo '{"name": "test", "author": "string"}' > /tmp/test-plugin.json
     claudelint check-plugin --path /tmp/test-plugin.json  # should warn about author being string
     ```

- [x] **Task 1.6**: Update E10 validation rule
  - [x] Create new rule file: `src/rules/skills/skill-overly-generic-name.ts`
  - [x] Add single-word verb detection: "format", "validate", "test", "build", "deploy", "run", "execute", etc.
  - [x] Add generic keyword detection: "helper", "utils", "tool", "manager", etc.
  - [x] Flag names that are only a verb without specificity
  - [x] Add comprehensive tests (valid and invalid cases)
  - [x] Rule registered as severity 'warn'
  - [x] All 777 tests passing

  **Verification Steps:**
  1. Find the rule: `find src -name "*generic*name*"`
  2. Write test first (should fail initially):

     ```typescript
     it('should flag single-word verb names', () => {
       const result = validateSkill({ name: 'format' });
       expect(result).toContainWarning('overly-generic-name');
     });
     ```

  3. Run test: `npm test -- --testNamePattern="overly-generic-name"` (should fail)
  4. Update rule to detect single-word verbs (format, validate, test, build, deploy)
  5. Run test again: `npm test -- --testNamePattern="overly-generic-name"` (should pass)
  6. Test on BEFORE renaming our skills:

     ```bash
     # Should flag these (before we rename them)
     claudelint validate-skills --path .claude/skills/validate 2>&1 | grep "generic"
     claudelint validate-skills --path .claude/skills/format 2>&1 | grep "generic"
     # Should NOT flag these
     claudelint validate-skills --path .claude/skills/validate-hooks 2>&1 | grep "generic" && echo "FAIL" || echo "PASS"
     ```

  7. Run full test suite: `npm test`

- [x] **Task 1.7**: Test plugin installation locally
  - [x] Verify plugin.json structure and contents
  - [x] Verify all 8 skill directories exist with correct structure
  - [x] Verify SKILL.md frontmatter matches directory names
  - [x] Verify shell scripts are executable and named correctly
  - [x] Verify old skill names (validate, format, validate-agents-md) removed
  - [x] Test CLI integration (claudelint commands work)
  - [x] All automated checks passed

  **Note**: Manual verification in Claude Code session recommended but not blocking.
  Structure is ready for `/plugin install --source .` or GitHub installation.

  **Verification Steps:**
  1. Build package: `npm pack`
  2. Install as plugin: `claude /plugin install --source .`
  3. In Claude Code session, verify skills are listed: `/skills` (should show claudelint:* skills)
  4. Test each renamed skill namespace:

     ```bash
     /claudelint:validate-all
     /claudelint:format-cc
     /claudelint:validate-cc-md
     ```

  5. Verify old names DON'T trigger:

     ```bash
     /claudelint:validate  # should not be found
     /claudelint:format    # should not be found
     /claudelint:validate-agents-md  # should not be found
     ```

  6. Test skill execution: Run `/claudelint:validate-all` and verify it actually executes
  7. Uninstall: `claude /plugin uninstall claudelint`
  8. Reinstall to ensure clean state: `claude /plugin install --source .`
  9. Clean up: `rm claude-code-lint-*.tgz`

- [x] **Task 1.8**: Update README and documentation
  - [x] Add plugin installation section
  - [x] Document skill namespace usage
  - [x] Add comparison: npm CLI vs plugin
  - [x] Add skill naming guidelines with E10 rule
  - [x] Update all install examples to use project install (--save-dev)
  - [x] Update all commands to use npx
  - [x] Trim README from 795 lines → 467 lines (41% reduction, close to 400 target)

  **Current README issues:**
  - Too long: 795 lines vs ESLint's 363 lines vs Prettier's ~100 lines
  - Too much detail should be in separate docs

  **Sections to move:**
  1. Skill Naming Guidelines (63 lines) → `docs/skill-naming.md`
  2. Troubleshooting (160 lines) → `docs/troubleshooting.md`
  3. Formatting Tools details (95 lines) → `docs/formatting-tools.md` (already exists)
  4. Philosophy (67 lines) → `docs/philosophy.md`
  5. Performance details (42 lines) → `docs/performance.md`
  6. Monorepo details (29 lines) → `docs/monorepo.md` (already exists)

  **Keep in README (brief):**
  - Beta notice
  - Quick Start (both install methods)
  - Brief feature list
  - Basic usage examples
  - Links to detailed docs

  **Verification Steps:**
  1. Check main README has plugin installation section: `grep -A5 "plugin install" README.md` ✓
  2. Verify all skill names updated in README: `grep "validate-all\|format-cc\|validate-cc-md" README.md` ✓
  3. Check no old skill names remain: `grep -E "^/validate\"|^/format\"" README.md` ✓
  4. Verify skill docs updated: Check `.claude/skills/*/SKILL.md` files have correct names ✓
  5. Run markdownlint: `npm run lint:md` ✓
  6. Trim README to target length: `wc -l README.md` (target: ~400 lines)

- [x] **Task 1.9**: Add dependency checks to skill scripts AND plugin installation helpers
  - [x] Created shared wrapper script `.claude/skills/lib/run-claudelint.sh`
  - [x] Updated all 8 skill scripts to use shared wrapper (2-3 lines each)
  - [x] Checks for npx availability (Node.js installed)
  - [x] Checks for claude-code-lint package (project or global)
  - [x] Shows helpful error with installation instructions if missing
  - [x] Updated plugin.json description to document npm dependency
  - [x] Matches LSP plugin pattern (pyright-lsp requires pyright-langserver)
  - [x] Added postinstall npm script (shows plugin install instructions)
  - [x] Created `claudelint install-plugin` command (helper to show instructions)
  - [x] Updated `claudelint init` wizard to show plugin install in next steps
  - [x] Updated README to emphasize project install (--save-dev) over global

  **Context:**
  Users discovering plugin via marketplaces (<https://claudemarketplaces.com>, <https://skills.sh>) will install plugin first without seeing README. Skills need to fail gracefully when npm package isn't installed. Also, users installing via npm need clear guidance on how to enable skills.

  **Final Implementation:**

  Shared wrapper (`.claude/skills/lib/run-claudelint.sh`):

  ```bash
  #!/bin/bash
  # Wrapper script for running claudelint commands
  set -e

  # Check dependencies
  if ! command -v npx &> /dev/null; then
      echo "Error: npx not found"
      echo "Install Node.js from: https://nodejs.org"
      exit 1
  fi

  if ! npx --no-install claude-code-lint --version &> /dev/null; then
      echo "Error: claude-code-lint not installed"
      echo "Install: npm install --save-dev claude-code-lint"
      exit 1
  fi

  # Run the command with all arguments
  npx claude-code-lint "$@"
  ```

  Individual skills (example):

  ```bash
  #!/bin/bash
  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
  exec "$SCRIPT_DIR/../lib/run-claudelint.sh" check-all "$@"
  ```

  **Three plugin installation helpers:**
  1. **Postinstall message** - runs after npm install
  2. **`claudelint install-plugin`** - dedicated helper command
  3. **`claudelint init`** - shows plugin setup in "next steps"

  **Verification Steps:**
  1. Test without package installed:

     ```bash
     # Remove package
     rm -rf node_modules/claude-code-lint
     # Test skill
     .claude/skills/validate-all/validate-all.sh
     # Should show: "Error: claude-code-lint not installed"
     ```

  2. Test with package installed:

     ```bash
     npm install --save-dev claude-code-lint
     .claude/skills/validate-all/validate-all.sh
     # Should execute successfully
     ```

  3. Test postinstall message:

     ```bash
     npm install --save-dev claude-code-lint
     # Should show plugin install instructions
     ```

  4. Test helper command:

     ```bash
     npx claudelint install-plugin
     # Should show /plugin install command
     ```

  5. Test init wizard:

     ```bash
     npx claudelint init
     # Should show plugin install in "next steps"
     ```

  6. Verify plugin.json description:

     ```bash
     jq -r '.description' plugin.json | grep "npm install"
     ```

### Acceptance Criteria

- [x] npm package includes CLI + `.claude/` skills directory
- [x] `plugin.json` created at repository root
- [x] All 3 skills renamed with specific names (validate-all, validate-cc-md, format-cc)
- [x] Plugin.json schema fixed to match official spec (deleted 2 invalid rules)
- [x] E10 rule created to flag single-word verbs and generic keywords
- [x] Plugin structure verified and ready for installation (automated checks)
- [x] Skills have dependency checks (inlined in each skill for self-containment)
- [x] Plugin.json description documents npm dependency requirement
- [x] Three plugin installation helpers implemented (postinstall, command, init wizard)
- [x] README updated to emphasize project install (--save-dev)
- [x] Documentation updated with new naming guidance
- [x] README trimmed down from 866 → 467 lines (46% reduction, close to 400-line target)
- [ ] Skills accessible via `/claudelint:` namespace with new names (needs manual testing in Claude Code)

### End-to-End Integration Test

**Run this complete test after all Phase 1 tasks:**

```bash
#!/bin/bash
set -e

echo "=== Phase 1 Integration Test ==="

echo "1. Testing package.json fix..."
npm pack
tar -tzf claude-code-lint-*.tgz | grep ".claude/skills/validate-all" || { echo "FAIL: skills not in package"; exit 1; }

echo "2. Testing plugin.json..."
tar -tzf claude-code-lint-*.tgz | grep "plugin.json" || { echo "FAIL: plugin.json not in package"; exit 1; }
cat .claude-plugin/plugin.json | jq . > /dev/null || { echo "FAIL: invalid JSON"; exit 1; }

echo "3. Testing skill renames..."
[ ! -d .claude/skills/validate ] || { echo "FAIL: old validate dir still exists"; exit 1; }
[ ! -d .claude/skills/format ] || { echo "FAIL: old format dir still exists"; exit 1; }
[ ! -d .claude/skills/validate-agents-md ] || { echo "FAIL: old validate-agents-md dir still exists"; exit 1; }
[ -d .claude/skills/validate-all ] || { echo "FAIL: validate-all dir missing"; exit 1; }
[ -d .claude/skills/format-cc ] || { echo "FAIL: format-cc dir missing"; exit 1; }
[ -d .claude/skills/validate-cc-md ] || { echo "FAIL: validate-cc-md dir missing"; exit 1; }

echo "4. Testing E10 rule..."
npm test -- --testNamePattern="overly-generic-name" || { echo "FAIL: E10 tests failed"; exit 1; }

echo "5. Testing frontmatter updates..."
grep "^name: validate-all" .claude/skills/validate-all/SKILL.md || { echo "FAIL: validate-all frontmatter"; exit 1; }
grep "^name: format-cc" .claude/skills/format-cc/SKILL.md || { echo "FAIL: format-cc frontmatter"; exit 1; }
grep "^name: validate-cc-md" .claude/skills/validate-cc-md/SKILL.md || { echo "FAIL: validate-cc-md frontmatter"; exit 1; }

echo "6. Running full test suite..."
npm test || { echo "FAIL: test suite failed"; exit 1; }

echo "7. Running linters..."
npm run lint || { echo "FAIL: linting failed"; exit 1; }

echo ""
echo "=== All Phase 1 Integration Tests PASSED ==="
echo ""
echo "Manual verification still needed:"
echo "  - Install plugin: claude /plugin install --source ."
echo "  - Test skills: /claudelint:validate-all, /claudelint:format-cc, /claudelint:validate-cc-md"
echo "  - Verify old names don't work: /claudelint:validate, /claudelint:format"

rm claude-code-lint-*.tgz
```

Save this as `scripts/test-phase-1.sh` and run after completing all tasks.

---

## Phase 2: Schema & Constant Verification System

**Status Update (2026-02-02)**: Pivoted to dual-schema verification approach after discovering drift.

### Verification Approach: Dual-Schema System

**Problem**: Official Claude Code specs exist as prose docs, not machine-readable schemas.

**Solution**: Maintain two types of schemas that validate each other:

1. **Manual Reference JSON Schemas** (`schemas/*.schema.json`)
   - Encode "what official docs say" as test fixtures
   - Created by human reading official docs
   - Hosted on GitHub raw URLs
   - Purpose: Reference implementation to detect drift

2. **Implementation Zod Schemas** (`src/schemas/*.ts`)
   - Runtime validation in claudelint
   - Can be stricter than official specs (extra validations OK)
   - Cannot be looser (missing fields BAD)
   - Purpose: Actual validation logic

**Verification Flow**:

```text
Official Docs → Manual JSON Schema → Generate from Zod → Compare → Fix Drift
```

**Drift Found (6/8 schemas had issues = 75%)**:

- PluginManifestSchema: CLEAN - Clean
- SkillFrontmatterSchema: Minor drift - missing 4 fields (FIXED)
- HooksConfigSchema: Minor drift - missing 2 fields (FIXED)
- MCPConfigSchema: **CRITICAL drift** - entire structure wrong (FIXED + 13 rules updated)
- LSPConfigSchema: **CRITICAL drift** - wrong structure + wrong fields + missing 7 fields (FIXED + 8 rules updated + 2 rules deprecated)
- AgentFrontmatterSchema: Minor drift - missing permissionMode + extra events field (FIXED + deleted agent-events rule)
- OutputStyleFrontmatterSchema: **MAJOR drift** - all validations wrong + missing/extra fields (FIXED + deleted 4 invalid rules)
- RulesFrontmatterSchema: CLEAN - Clean (renamed from ClaudeMdFrontmatterSchema for clarity)

**See**: [Schema Verification Workflow](./schema-verification-workflow.md)

## Phase 2: Full Verification System (Future Work)

**Status**: Not Started
**Duration**: 9-14 days
**Dependencies**: Phase 1 complete
**Priority**: CRITICAL (validation correctness depends on this)

### Overview

Systematic verification of all schemas and constants against official Claude Code sources. Implements unified truth registry with automated, hybrid, and manual verification workflows.

**See**: [Truth Registry Proposal](./truth-registry-proposal.md) for full design

### Discovery Summary

**Found Issues**:

- 1 schema out of sync (PluginManifestSchema - CRITICAL)
- 1 schema verified (SettingsSchema)
- 8 schemas need audit
- 9 constants need verification
- No automation for most sources

**Impact**: Users get false positives/negatives, validation doesn't match Claude Code's actual behavior

### Tasks

#### Phase 2.1: Create Manual Reference Schemas (3-4 days)

**Current Work**: Creating manual JSON Schemas from official docs to detect drift.

**Completed**:

- [x] **Task 2.1.1**: Schema inventory (identified 9 schemas needing verification)
- [x] **Task 2.1.2**: PluginManifestSchema reference created
- [x] **Task 2.1.3**: SkillFrontmatterSchema reference created (FOUND DRIFT - 4 missing fields)
- [x] **Task 2.1.4**: Fix SkillFrontmatterSchema drift (added 4 missing fields to Zod)
- [x] **Task 2.1.5**: HooksConfigSchema reference (FOUND DRIFT - 2 missing fields: timeout, async)
- [x] **Task 2.1.6**: MCPConfigSchema reference (CRITICAL DRIFT - wrong structure, required complete restructure + 13 rule fixes)
- [x] **Task 2.1.7**: LSPConfigSchema reference (CRITICAL DRIFT - wrong structure + wrong field names + missing 7 fields + extra configFile field, updated 8 rules + deprecated 2 rules)
- [x] **Task 2.1.8**: AgentFrontmatterSchema reference (Minor drift - missing permissionMode, extra events field, deleted agent-events rule)
- [x] **Task 2.1.9**: OutputStyleFrontmatterSchema reference (MAJOR drift - all validations wrong, missing keep-coding-instructions, extra examples field, deleted 4 invalid rules)
- [x] **Task 2.1.10**: RulesFrontmatterSchema reference (No drift - schema correct, renamed from ClaudeMdFrontmatterSchema for clarity)
- [x] **Task 2.1.11**: Update all schemas to JSON Schema Draft 2020-12 (migrated from Draft-07)
- [x] **Task 2.1.12**: Extract source URLs to custom properties (added `source` and `sourceType` fields to all 8 schemas for machine-readability)
- [x] **Task 2.1.13**: Fix LSP config schema tests (updated tests to match corrected flat structure, added extensionToLanguage requirement, removed deprecated configFile tests)

**In Progress**:
None - Phase 2.1 complete!

**Acceptance Criteria**:

- [x] All 8 manual reference schemas created in `schemas/` directory
- [x] Each schema documented with official source URL
- [x] All drift between Zod and official specs fixed
- [x] Schemas use JSON Schema Draft 2020-12
- [x] Source URLs extracted into custom properties for machine-readability
- [x] All schema tests passing (139 suites, 771 tests)
- [ ] Schemas hosted on GitHub raw URLs (pending git push)

#### Phase 2.2: Build Automated Comparison (2-3 days)

**Status**: COMPLETE (2026-02-03)

**Goal**: Generate JSON Schema from Zod and compare to manual reference schemas.

**Completed**:

- [x] **Task 2.2.1**: Install zod-to-json-schema
  - [x] Add `zod-to-json-schema` dependency
  - [x] Create wrapper script to generate from all Zod schemas (`scripts/generate/json-schemas.ts`)
  - [x] Add `npm run generate:json-schemas` script
  - [x] Extract schemas from zodToJsonSchema wrapper structure
  - [x] Force Draft 2020-12 compatibility

- [x] **Task 2.2.2**: Build schema comparison tool
  - [x] Create `scripts/verify/compare-schemas.ts` (255 lines)
  - [x] Compare manual reference vs generated schemas
  - [x] Report drift (missing fields, wrong types, enum mismatches, missing required)
  - [x] Allow Zod to be stricter (extra validations OK)
  - [x] Reject Zod being looser (missing fields = ERROR)
  - [x] Add `npm run check:schemas` script
  - [x] All 8 schemas match - no drift detected!

- [x] **Task 2.2.3**: Update schema-sync script
  - [x] Completely rewrite `scripts/check/schema-sync.ts` (66% smaller - 185 vs 540 lines)
  - [x] Remove outdated Ajv/Zod comparison code
  - [x] Orchestrate: generate → compare → report workflow
  - [x] Show Phase 2.1 drift history for all 8 schemas
  - [x] Exit non-zero if drift detected
  - [x] Manual references already on GitHub (no fetching needed)

- [x] **Task 2.2.4**: CI/CD integration
  - [x] CI job already configured correctly
  - [x] Updated `.github/workflows/ci.yml` documentation
  - [x] Runs on every PR and push to main
  - [x] Fails CI if drift detected
  - [x] Included in complete-validation job dependencies
  - [x] Node modules cache already configured

**Acceptance Criteria**:

- [x] zod-to-json-schema installed and wrapper created
- [x] Comparison tool detects all types of drift
- [x] Schema-sync script automated (generate + compare)
- [x] CI runs verification on every PR
- [x] All 8 schemas verified with 0 drift

**Deliverables**:

- `scripts/generate/json-schemas.ts` - Generate JSON Schemas from Zod
- `scripts/verify/compare-schemas.ts` - Compare and detect drift
- `scripts/check/schema-sync.ts` - Rewritten orchestration script
- `schemas/generated/` - Generated schemas (gitignored)
- 2 new npm scripts: `generate:json-schemas`, `verify:schemas`

#### Phase 2.3: Hybrid Verification (3-4 days)

**Status**: COMPLETE (verified via Phase 2.1/2.2 work)

**Note**: Phase 2.3 tasks were defined before implementing comprehensive dual-schema verification. All objectives met through Phase 2.1/2.2 work. See `phase-2-3-verification.md` for detailed audit.

**Completed**:

- [x] **Task 2.3.1**: Plugin manifest verification
  - [x] PluginManifestSchema verified against official spec (no drift)
  - [x] All 15 fields verified (name, version, description, author, etc.)
  - [x] Component paths verified (skills, agents, commands)
  - [x] Config paths verified (hooks, mcpServers, lspServers)
  - [x] Union types handled (string | array | object)

- [x] **Task 2.3.2**: Hook events verification
  - [x] HookEvents constant verified (13 events match official spec)
  - [x] hooks-config.schema.json enum verified (13 events)
  - [x] hooks-invalid-event rule uses correct event list
  - [x] No drift detected between constant and schema

- [x] **Task 2.3.3**: MCP config verification
  - [x] MCPConfigSchema verified against official spec (no drift)
  - [x] Transport types verified (stdio, sse, http, websocket)
  - [x] Flat structure verified (no `transport` wrapper)
  - [x] Server names as object keys verified
  - [x] 13 validation rules updated for correct structure

- [x] **Task 2.3.4**: Create hybrid verification framework
  - [x] Manual extraction process (read docs → create JSON Schema)
  - [x] Automated generation (Zod → JSON Schema via zod-to-json-schema)
  - [x] Automated comparison (manual reference vs generated)
  - [x] Orchestration script (generate → compare → report)
  - [x] CI integration (runs on every PR, blocks if drift detected)
  - [x] Dual-schema system = hybrid verification framework

**Acceptance Criteria**:

- [x] All 3 specific verification tasks complete
- [x] Hybrid framework implemented (dual-schema system)
- [x] All 8 schemas verified with 0 drift
- [x] CI runs verification on every PR
- [x] Framework detects all drift types

**Deliverables**:

- Verification audit: `docs/projects/plugin-and-md-management/phase-2-3-verification.md`
- Evidence: All schemas show "No drift detected" in comparison output

#### Phase 2.4: Constants Verification (2-3 days) [COMPLETE]

**Goal**: Programmatically verify ToolNames and ModelNames constants against Claude Code CLI

**Sources of Truth:**

- **Primary**: Claude Code CLI (queries actual installed version)
- **Documentation Reference**:
  - ToolNames: <https://code.claude.com/docs/en/settings#tools-available-to-claude>
  - ModelNames: <https://code.claude.com/docs/en/sub-agents#supported-frontmatter-fields>

**Strategy:**

1. **Query Claude CLI** - Ask Claude to list its tools/models via CLI
2. **Supplemental Lists** - Maintain lists of valid values CLI doesn't return (e.g., `inherit`)
3. **Hybrid Verification** - Compare against CLI + supplemental, not hardcoded lists
4. **Settings.json** - Changed model to `z.string()` for arbitrary model names

**Implementation:**

**Tools Verification**:

- Runs: `claude -p "List all tool names..."`
- Returns: 17 tools from actual Claude Code
- Supplemental: 0 tools (currently empty)
- Compares: Against `VALID_TOOLS` constant
- **Current Status**: [DRIFT DETECTED] (missing TodoWrite, extra 5 tools)

**Models Verification**:

- Runs: `claude -p "What model values for Task tool..."`
- Returns: 3 models (sonnet, opus, haiku)
- Supplemental: 1 model (`inherit` - valid but CLI doesn't mention)
- Compares: Against `VALID_MODELS` constant
- **Current Status**: [VERIFIED] (matches expected 4 models)

**Tasks:**

- [x] **Task 2.4.1**: Create tool names verification script [DONE]
  - Script: `scripts/verify/tool-names.ts`
  - Method: Queries Claude CLI with `execSync`
  - Parses output, filters to PascalCase tool names
  - Supports supplemental tools list (currently 0)
  - Reports drift: missing TodoWrite, extra LSP/TaskCreate/TaskGet/TaskList/TaskUpdate
  - Exit 1 on drift, 0 on match
  - Includes error handling for missing CLI/API key

- [x] **Task 2.4.2**: Create model names verification script [DONE]
  - Script: `scripts/verify/model-names.ts`
  - Method: Queries Claude CLI for Task tool model parameter
  - Returns sonnet/opus/haiku from CLI
  - Supplements with `inherit` (valid in docs but CLI doesn't return)
  - Compares against `VALID_MODELS` constant
  - **Result**: [SUCCESS] - matches expected 4 models
  - Exit 0 (no drift)

- [x] **Task 2.4.3**: Fix settings.json model validation [DONE]
  - Changed `src/validators/schemas.ts` line 143
  - From: `model: ModelNames.optional()`
  - To: `model: z.string().optional()`
  - Reason: settings.json accepts arbitrary model names
  - Removed unused ModelNames import
  - All tests pass (822 passed)
  - ModelNames enum now ONLY for agents/skills

- [x] **Task 2.4.4**: Rewrite constants verification documentation [DONE]
  - Rewrote: `docs/constants-verification.md`
  - Documents CLI-based verification approach
  - Explains supplemental lists and why they exist
  - Includes manual verification fallback
  - Documents limitations and trade-offs
  - Current drift status for both constants

- [x] **Task 2.4.5**: Remove unused dependencies [DONE]
  - Removed jsdom and @types/jsdom
  - Freed 45 packages
  - No longer needed - CLI queries don't parse HTML

- [x] **Task 2.4.6**: Add NPM scripts [DONE]
  - `npm run check:tool-names` - Queries CLI, compares tools
  - `npm run check:model-names` - Queries CLI, compares models
  - `npm run check:constants` - Runs both verifications
  - All scripts tested and working

**Key Learnings:**

- **Don't**: Maintain hardcoded lists that compare against themselves (useless)
- **Do**: Query actual Claude Code installation via CLI
- **Do**: Support supplemental lists for edge cases CLI misses
- **Do**: Document why each supplemental value exists
- **Limitation**: Requires Claude Code installed and API key configured
- **Cost**: ~$0.01 per verification run (2 API calls, ~1000 tokens total)

#### Phase 2.5: Integration & Documentation (1-2 days)

- [ ] **Task 2.5.1**: Pre-commit hook integration
  - Add `npm run check:constants` to pre-commit hook
  - Fails commit if drift detected
  - Forces manual review of constant changes

- [ ] **Task 2.5.2**: Update project documentation
  - Add constants verification to README
  - Document verification workflow
  - Explain source of truth for each constant

- [ ] **Task 2.5.3**: CI integration
  - Add verification to GitHub Actions workflow
  - Run on every PR
  - Fail CI if constants are out of sync

### Acceptance Criteria

- [ ] All 19 sources have verification method defined
- [ ] PluginManifestSchema fixed and verified
- [ ] High-priority constants verified (ToolNames, ModelNames, HookEvents)
- [ ] Automated verification runs in CI
- [ ] Status dashboard auto-generated

### Success Metrics

- 0 critical sources out of sync
- 100% of schemas have verification defined
- CI catches drift within 1 week

---

## Phase 2.6: Rule Deprecation System (2-3 days)

**Status**: Complete
**Duration**: 2-3 days (completed)
**Dependencies**: Phase 2.1-2.5 complete
**Priority**: HIGH (enables safe rule evolution)

### Overview

Design and implement a proper rule deprecation system modeled after ESLint and Prettier. Currently we have no formal way to deprecate rules - we just deleted two rules that validated non-existent fields. Need a systematic approach for future rule changes.

**Context**: We just deleted `plugin-dependency-invalid-version` and `plugin-circular-dependency` because they validated a field (`dependencies`) that never existed in the official plugin.json spec. This was the right call for beta, but we need a proper deprecation system for post-1.0.

### Research Findings

**ESLint's Modern Approach**:

- Evolved from simple boolean `deprecated: true` to rich object format
- Modern format: `deprecated: { reason, replacedBy[], deprecatedSince, availableUntil, url }`
- Supports cross-plugin replacements with detailed metadata
- Backward compatible (boolean still works)
- **Key finding**: ESLint doesn't automatically warn about deprecated rules (GitHub Issue #20294)

**Prettier's Approach**:

- Shows warnings when deprecated options are used
- Keeps deprecated options for 1+ minor versions before removal
- Removes in next major version
- Unique versioning philosophy: formatting output changes aren't "breaking" (only API/CLI changes are)
- Proposed experimental/deprecated flags for transitional periods (RFC #14527)

**Our Design** (fully documented in `docs/architecture/rule-deprecation.md`):

- Backward-compatible metadata: `deprecated?: boolean | DeprecationInfo`
- `DeprecationInfo`: `{ reason, replacedBy?, deprecatedSince?, removeInVersion?, url? }`
- Warning system with CLI flags: `--no-deprecated-warnings`, `--error-on-deprecated`
- `claudelint migrate` command for auto-updating configs
- Lifecycle: Deprecate (minor) → Warn for 2+ minors → Remove (major)

### Tasks

- [x] **Task 2.6.1**: Research ESLint and Prettier deprecation patterns
  - [x] Study ESLint's `meta.deprecated` and `meta.replacedBy` patterns
  - [x] Study Prettier's deprecation warnings and version policy
  - [x] Document findings in `docs/architecture/rule-deprecation.md` (400+ lines)
  - [x] Identify best practices we want to adopt

- [x] **Task 2.6.2**: Design deprecation system
  - [x] Define `DeprecationInfo` interface (reason, replacedBy, deprecatedSince, removeInVersion, url)
  - [x] Design warning format and output
  - [x] Design CLI flags (--no-deprecated-warnings, --error-on-deprecated, check:deprecated)
  - [x] Design config migration tool (`claudelint migrate`)
  - [x] Define deprecation lifecycle (deprecate → warn → remove)
  - [x] Document in `docs/architecture/rule-deprecation.md`

- [x] **Task 2.6.3**: Implement deprecation metadata
  - [x] Added `DeprecationInfo` interface with all fields (reason, replacedBy, deprecatedSince, removeInVersion, url)
  - [x] Updated `Rule.meta.deprecated` to support `boolean | DeprecationInfo` (backward compatible)
  - [x] Added helper functions: `isRuleDeprecated()`, `getDeprecationInfo()`, `getReplacementRuleIds()`
  - [x] Updated `isRule()` type guard to work with optional deprecated field
  - [x] Updated `src/utils/config/types.ts` to use new helpers for config validation
  - [x] Created comprehensive test suite with 22 tests (all passing)

- [x] **Task 2.6.4**: Implement deprecation warnings
  - [x] Add deprecation detection to rule execution pipeline
    - Added tracking in `FileValidator.executeRule()` to detect deprecated rules
    - Track deprecated rules in `deprecatedRulesUsed` Map during validation
    - Convert Map to `DeprecatedRuleUsage[]` in `getResult()`
    - Added `deprecatedRulesUsed` field to `ValidationResult`
  - [x] Created comprehensive test suite for deprecation tracking
    - 10 tests covering boolean/object formats, multiple rules, disabled rules, etc.
    - All tests passing
  - [x] Add warning formatter (show reason, replacement, version info)
    - Added `deprecatedRulesUsed` field to `LintResult` type
    - Updated `buildLintResult()` to pass through deprecation info
    - Updated `mergeLintResults()` to deduplicate deprecated rules across files
    - Updated `StylishFormatter` to display deprecation warnings at end of output
    - Shows: rule ID, reason, replacements, removal version, migration guide URL
    - Created 7 formatter tests - all passing
  - [x] Add CLI flag to control deprecation warnings (--no-deprecated-warnings)
    - Added flag to `check-all` command
    - Updated `ReportingOptions` interface
    - Updated `Reporter` to show/hide deprecation warnings based on flag
    - Created `reportDeprecatedRules()` method in Reporter class
    - Default: true (warnings shown)
  - [x] Add CLI flag to error on deprecated rules (--error-on-deprecated)
    - Added flag to `check-all` command
    - Updated exit code logic to fail when deprecated rules detected
    - Updated `Reporter.getExitCode()` to handle errorOnDeprecated
    - Displays error message when exiting due to deprecated rules
  - [x] Create `claudelint check-deprecated` command to list deprecated rules in config
    - Created new command in `src/cli/commands/check-deprecated.ts`
    - Scans config file for deprecated rules
    - Shows detailed deprecation info for each rule
    - Provides migration guidance
    - Supports --format json output
    - Exits with code 1 if deprecated rules found, 0 otherwise

- [x] **Task 2.6.5**: Create migration tooling
  - [x] Create `src/utils/migrate/update-configs.ts` (migration logic)
  - [x] Create `src/cli/commands/migrate.ts` (CLI command)
  - [x] Scan config files for deprecated rule IDs
  - [x] Auto-replace with replacedBy rule ID (1:1 replacements)
  - [x] Handle multiple replacements (require manual intervention)
  - [x] Handle no replacement (suggest removal)
  - [x] Generate migration report with change summaries
  - [x] Support dry-run mode (--dry-run flag)
  - [x] Support JSON output (--format json)
  - [x] Add `claudelint migrate` CLI command
  - [x] Add 12 comprehensive tests (all passing)

- [x] **Task 2.6.6**: Documentation and examples
  - [x] Document deprecation policy in CONTRIBUTING.md
    - Added "Rule Deprecation Policy" section (180+ lines)
    - When to deprecate rules
    - How to mark rules as deprecated (boolean vs DeprecationInfo)
    - Deprecation lifecycle (deprecate → warn → remove)
    - Replacement scenarios (1:1, 1:many, none, indefinite)
    - User-facing commands
    - Testing deprecated rules
  - [x] Add examples of marking a rule as deprecated
    - Added "Deprecation Field" section to rule-development.md
    - 4 detailed examples: single replacement, multiple replacements, no replacement, retained indefinitely
    - All DeprecationInfo fields documented with usage
  - [x] Document migration tool usage
    - Added "Deprecation Management" section to cli-reference.md
    - Documented `check-deprecated` command (usage, options, examples, exit codes)
    - Documented `migrate` command (usage, options, how it works, examples, exit codes)
    - Example outputs for both commands
  - [x] Update rule creation template with deprecation fields
    - Updated rule structure template in rule-development.md
    - Added comment referencing Deprecation Field section
    - Clarified that deprecated field is optional for new rules
    - Added note in Required Fields section pointing to deprecation docs

### Acceptance Criteria

- [x] Rule interface supports deprecation metadata (reason, replacedBy, removeInVersion)
- [x] Deprecated rule usage triggers clear warnings
- [x] Migration tool can auto-update configs
- [x] Documentation explains deprecation policy
- [x] Tests cover all deprecation scenarios

### Example: How it should work

```typescript
// src/rules/plugin/example-old-rule.ts
export const rule: Rule = {
  meta: {
    id: 'example-old-rule',
    name: 'Example Old Rule',
    description: 'Old validation approach',
    category: 'Plugin',
    severity: 'warn',
    fixable: false,
    deprecated: {
      reason: 'This rule was based on an unofficial field that was removed from the spec',
      replacedBy: 'example-new-rule',
      removeInVersion: '1.0.0',
    },
    since: '0.1.0',
    docUrl: '...',
  },
  validate: () => {
    // Still runs but shows deprecation warning
  },
};
```

**CLI output:**

```text
Warning: Rule 'example-old-rule' is deprecated
  Reason: This rule was based on an unofficial field that was removed from the spec
  Use 'example-new-rule' instead
  This rule will be removed in version 1.0.0
```

**Migration tool:**

```bash
npm run migrate:config
# Scans .claudelintrc.json
# Replaces "example-old-rule" with "example-new-rule"
# Shows summary of changes
```

---

## Phase 2.7: Skill Quality Improvements (Anthropic Best Practices)

**Status**: Complete
**Duration**: 1-2 days (completed in 1 day)
**Dependencies**: Phase 2.6 complete
**Priority**: HIGH (needed before Phase 3 to establish quality standards)

**Goal**: Improve existing 8 skills to follow Anthropic's best practices from "Complete Guide to Building Skills for Claude" (Jan 2026).

**Reference**: See `docs/projects/plugin-and-md-management/skill-improvement-guidelines.md` for detailed patterns and examples.

### Key Improvements

Based on Anthropic guide analysis + schema verification:

1. **Keep current structure** (8 separate skills) - Anthropic emphasizes composability, not consolidation
2. **Improve skill descriptions** - Add trigger phrases users actually say
3. **Add troubleshooting** - Skill-specific (not generic boilerplate) - **Top 3 skills only**
4. **Add scenario examples** - User says → Actions → Result format - **Top 3 skills only**
5. **Add standard fields** - version, tags, dependencies (NOT custom metadata - schema forbids it)
6. **Verify required fields** - Ensure all skills have name + description
7. **Progressive disclosure** - Move detailed content to references/ if needed (check word counts)

### Tasks

#### Task 2.7.0: Audit Existing Skills for Required Fields

**Priority**: CRITICAL - Must do first before adding new fields

**Goal**: Verify all 8 skills have the 2 required fields from the schema.

**Required fields** (per official schema):

- `name` - Must be present (schema doesn't mark as required, but documentation says it's needed)
- `description` - Must be present and min 10 characters

**Check**:

```bash
# Verify all skills have name and description
for skill in .claude/skills/*/SKILL.md; do
  echo "Checking $skill..."

  # Check for name field
  if ! grep -q "^name:" "$skill"; then
    echo "  [MISSING] name field"
  else
    name=$(grep "^name:" "$skill" | head -1)
    echo "  [OK] Has name: $name"
  fi

  # Check for description field
  if ! grep -q "^description:" "$skill"; then
    echo "  [MISSING] description field"
  else
    desc_len=$(grep "^description:" "$skill" | cut -d: -f2- | wc -c)
    if [ "$desc_len" -lt 10 ]; then
      echo "  [WARNING] Description too short: $desc_len chars (min 10)"
    else
      echo "  [OK] Has description: $desc_len chars"
    fi
  fi
done
```

**Expected**: All 8 skills should have both fields (we created them with frontmatter)

**If missing**: Add missing required fields before proceeding to Task 2.7.1

#### Task 2.7.1: Update All Skill Descriptions with Trigger Phrases

**Priority**: HIGH - Descriptions control skill triggering (Anthropic p11)

For all 8 skills, update descriptions following pattern:
`[What it does] + [When to use it] + [Trigger phrases] + [Key capabilities]`

**Example (validate-cc-md)**:

```yaml
# Current (too technical)
description: Validate CLAUDE.md files for size, imports, and structure

# Improved (user-focused with triggers)
description: Validate CLAUDE.md files for size, imports, and structure. Use when you want to "check my CLAUDE.md", "audit my config", "why is my CLAUDE.md too long", or "validate imports". Checks file size limits (30KB warning, 50KB error), @import directives, frontmatter in .claude/rules/, and section organization.
```

**Skills to update**:

- [x] validate-all
- [x] validate-cc-md
- [x] validate-skills
- [x] validate-plugin
- [x] validate-mcp
- [x] validate-settings
- [x] validate-hooks
- [x] format-cc

**Reference**: See skill-improvement-guidelines.md section "Skill-by-Skill Improvement Plan" for each skill's improved description.

**Verification**:

```bash
# Check descriptions stay under 1024 character limit
for skill in .claude/skills/*/SKILL.md; do
  desc=$(grep "^description:" "$skill" | cut -d: -f2-)
  len=$(echo "$desc" | wc -c)
  echo "$skill: $len characters"
done
```

#### Task 2.7.2: Add Troubleshooting to Top 3 Skills

**Priority**: HIGH - Reduce user confusion (Anthropic p13, p26)

Add skill-specific troubleshooting sections to:

- [ ] **validate-all** - Installation issues, when to use specific validators
  - "claudelint command not found"
  - "Multiple validators failed"
  - Exit code meanings

- [ ] **validate-cc-md** - File size, imports, circular dependencies
  - "File exceeds 50KB"
  - "Import not found"
  - "Circular import detected"
  - "File exceeds 30KB" (warning vs error)

- [ ] **validate-skills** - Name mismatches, invalid tools, dangerous commands
  - "Skill name must match directory name"
  - "Unknown tool in allowed-tools"
  - "Dangerous command detected"
  - "Shell script missing shebang"
  - "Skill lacks version field"

**Format** (from Anthropic p13):

```markdown
## Common Issues

### Error: "[error message]"
**Cause**: [why it happens]
**Solution**: [how to fix]
**Example**: [code sample showing fix]
```

**Reference**: See skill-improvement-guidelines.md for full troubleshooting text for each skill.

**Note**: Other 5 skills (validate-plugin, validate-mcp, validate-settings, validate-hooks, format-cc) don't need troubleshooting - errors are self-explanatory. Can add later if users report confusion.

#### Task 2.7.3: Add Scenario-Based Examples to Top 3 Skills

**Priority**: MEDIUM - Helps users understand workflows (Anthropic p12)

Add examples section using Anthropic's pattern to:

- [ ] **validate-all**
- [ ] **validate-cc-md**
- [ ] **validate-skills**

**Format** (from Anthropic p12):

```markdown
## Examples

### Example 1: [scenario name]
**User says**: "[what user might say]"
**What happens**:
1. [step 1]
2. [step 2]
3. [step 3]
**Result**: [outcome]
```

**Reference**: See skill-improvement-guidelines.md for complete examples for each skill.

#### Task 2.7.4: Add Standard Fields to All Skills

**Priority**: MEDIUM - Important for discoverability and dependencies

**IMPORTANT DISCOVERY**: Official skill schema does NOT support custom `metadata` object. It has `"additionalProperties": false`. We must use standard fields only.

Add standard fields to all 8 skills:

```yaml
---
name: skill-name
description: [updated description]
version: 1.0.0  # Add this - semantic versioning
tags: [validation, claude-code, linting]  # Add this - for categorization
dependencies: ["npm:claude-code-lint"]  # Add this - document npm dependency
allowed-tools:  # Already present - verify correct
  - Bash
  - Read
---
```

**Tag Guidelines**:

- validate-* skills: `[validation, claude-code, linting]`
- format-cc: `[formatting, claude-code, quality]`
- optimize-cc-md: `[automation, claude-code, optimization]`

**Dependencies**:

- All skills depend on npm package: `["npm:claude-code-lint"]`
- This documents the dependency we already have in skill scripts

**Verification**:

```bash
# Check all skills have version field
for skill in .claude/skills/*/SKILL.md; do
  if ! grep -q "^version:" "$skill"; then
    echo "Missing version: $skill"
  fi
  if ! grep -q "^tags:" "$skill"; then
    echo "Missing tags: $skill"
  fi
  if ! grep -q "^dependencies:" "$skill"; then
    echo "Missing dependencies: $skill"
  fi
done
```

#### Task 2.7.5: Check Progressive Disclosure Needs

**Priority**: LOW - Only needed if SKILL.md >5000 words

Check word count for all skills:

```bash
for skill in .claude/skills/*/SKILL.md; do
  words=$(wc -w < "$skill")
  echo "$skill: $words words"
  if [ "$words" -gt 5000 ]; then
    echo "  [WARNING] Consider progressive disclosure"
  fi
done
```

If any skill exceeds 5000 words:

- [ ] Move detailed content to `references/` subdirectory
- [ ] Link from SKILL.md
- [ ] Keep core instructions focused

**Current assessment**: All skills appear under 5000 words, likely no changes needed.

### Acceptance Criteria

- [x] All 8 skills have descriptions with trigger phrases (under 1024 chars)
- [x] Top 3 skills have troubleshooting sections with skill-specific errors
- [x] Top 3 skills have scenario-based examples
- [x] All 8 skills have standard fields (version, tags, dependencies)
- [x] No skill exceeds 5000 words without progressive disclosure
- [x] Changes documented in skill-improvement-guidelines.md
- [x] All skills pass schema validation (required fields present)
- [ ] Test that trigger phrases work (manual testing in Claude Code)

### Verification Steps

After completing all tasks:

1. **Description validation**:

   ```bash
   npm run lint:md  # Check markdown format
   # Manually verify trigger phrases in each description
   ```

2. **Troubleshooting validation**:
   - Read each troubleshooting section
   - Verify errors match what that validator actually reports
   - Check examples are accurate

3. **Examples validation**:
   - Run each example scenario manually
   - Verify "User says" triggers the skill
   - Confirm actions/results are accurate

4. **Metadata validation**:

   ```bash
   # Check all skills have required fields
   for skill in .claude/skills/*/SKILL.md; do
     echo "Checking $skill"
     grep -q "^metadata:" "$skill" || echo "  Missing metadata"
     grep -q "category:" "$skill" || echo "  Missing category"
   done
   ```

---

## Phase 3: Create optimize-cc-md Skill

**Status**: Complete (Tasks 3.1-3.7 done, Task 3.8 requires manual testing)
**Duration**: 3-4 days
**Dependencies**: Phase 2.7 complete (establishes quality standards)

**What This Skill Does**: Provides instructions for Claude to **interactively help users fix their CLAUDE.md files**. When user runs `/optimize-cc-md`, Claude reads the skill instructions and:

1. Runs `claudelint check-claude-md` to get violations
2. Reads user's CLAUDE.md file
3. Explains violations conversationally
4. Asks what they want to fix
5. **Actually edits the file** using Edit/Write tools
6. Creates new @import files if needed
7. Shows before/after results

**This is NOT**: A CLI script, automated tool, or non-interactive validator. It's instructions for Claude to work with the user.

**Design Principle**: Use progressive disclosure from the start (Anthropic p5, p13, p27).

### Directory Structure

Based on Anthropic recommendations for managing large context:

```text
optimize-cc-md/
├── SKILL.md (core instructions, <5000 words)
├── references/
│   ├── size-optimization.md (strategies for reducing file size)
│   ├── import-patterns.md (best practices for @import)
│   └── organization-guide.md (section organization tips)
└── examples/ (optional)
    ├── before-optimization.md
    └── after-optimization.md
```

### Tasks

- [x] **Task 3.1**: Design progressive disclosure structure
  - [x] Map out what goes in SKILL.md (core workflow)
  - [x] Map out what goes in references/ (detailed strategies)
  - [x] Ensure SKILL.md stays under 5000 words (targeting <3000)
  - [x] Document design in optimize-cc-md-structure-design.md

- [x] **Task 3.2**: Create skill directory structure
  - [x] `.claude/skills/optimize-cc-md/`
  - [x] `SKILL.md` with frontmatter
  - [x] No README.md (forbidden in skills)
  - [x] Optional: `references/` for best practices examples

- [x] **Task 3.3**: Write SKILL.md frontmatter (following Phase 2.7 standards)
  - [x] Name: `optimize-cc-md`
  - [x] Description with trigger phrases: "Interactively help users optimize their CLAUDE.md files. Use when you want to 'optimize my CLAUDE.md', 'fix my config', 'my CLAUDE.md is too long', 'improve organization', or 'split my CLAUDE.md'. Runs validation, explains issues conversationally, and helps create @import files to reduce size and improve structure."
  - [x] Allowed tools: Bash, Read, Edit, Write, Grep
  - [x] Metadata: author, category (automation), documentation
  - [x] Version: 1.0.0
  - [x] Keep under 1024 characters

- [x] **Task 3.4**: Write core workflow in SKILL.md
  - [x] Core workflow (keep concise):
    - Step 1: Run `claudelint check-claude-md --explain`
    - Step 2: Read user's CLAUDE.md file with Read tool
    - Step 3: Explain violations in conversational language
    - Step 4: Identify specific problems (link to references/ for details)
    - Step 5: Ask user what to fix first
    - Step 6: Use Edit tool to make changes
    - Step 7: Use Write tool to create @import files if splitting
    - Step 8: Show before/after comparison
  - [x] Link to references for detailed strategies
  - [x] Keep SKILL.md under 3,000 words (target for interactive skill)

- [x] **Task 3.5**: Create reference documents
  - [x] `references/size-optimization.md`:
    - Strategies for reducing file size
    - What content to move to @imports
    - How to identify bloat (obvious advice, config duplication)
  - [x] `references/import-patterns.md`:
    - Best practices for organizing @imports
    - Directory structure recommendations
    - Common patterns (git workflow, testing, linting)
  - [x] `references/organization-guide.md`:
    - Section organization tips
    - When to split vs consolidate
    - Naming conventions for .claude/rules/ files

- [x] **Task 3.6**: Add examples to SKILL.md (following Phase 2.7 pattern)
  - [x] Example 1: Fix size violations
    - User says: "My CLAUDE.md is too long"
    - Actions: Validate → Identify bloat → Suggest splits
    - Result: Content moved to @imports
  - [x] Example 2: Create import structure
    - User says: "Help me organize my config"
    - Actions: Analyze sections → Create .claude/rules/ files → Replace with @imports
    - Result: Well-organized, modular config
  - [x] Example 3: Remove obvious content
    - User says: "Is my CLAUDE.md too generic?"
    - Actions: Scan for generic advice → Suggest removals
    - Result: Focused, project-specific config

- [x] **Task 3.7**: Add troubleshooting section
  - [x] Common issues when using the skill
  - [x] Not issues the skill helps fix (those are in examples)
  - [x] Example: "Skill creates @import but file path is wrong"

- [ ] **Task 3.8**: Test optimize-cc-md skill (DEFERRED - manual testing)

**DEFERRED**: Manual testing deferred until end of project (before release)

**Note**: Full testing methodology documented in `docs/skill-testing.md`

**Automated pre-checks** (run first):

- [ ] Validate skill structure: `claudelint validate-skills .claude/skills/optimize-cc-md`
- [ ] Check word count: SKILL.md should be <3,000 words
- [ ] Verify references/ files exist and are readable

**Manual testing** (Anthropic iterative methodology):

- [ ] **Phase 1: Single-task iteration (Anthropic p15 pro tip)**
  - [ ] Pick ONE challenging CLAUDE.md problem (e.g., 52KB file with bloat, circular imports)
  - [ ] Work with Claude to solve it WITHOUT the skill first
  - [ ] Iterate conversation until perfect solution found
  - [ ] Document the winning approach (what worked, what didn't)
  - [ ] Verify skill instructions match the winning approach
  - [ ] If skill doesn't match, update SKILL.md before expanding tests

- [ ] **Phase 2: Expanded functional testing**
  - [ ] Test on bloated CLAUDE.md (>50KB, obvious content)
  - [ ] Test on well-optimized CLAUDE.md (should suggest minimal changes)
  - [ ] Test on CLAUDE.md with circular imports
  - [ ] Test on CLAUDE.md with missing @import files
  - [ ] Test on CLAUDE.md with organization problems (too many sections)
  - [ ] Use test fixtures from `tests/fixtures/claude-md/`

- [ ] **Phase 3: Trigger validation**
  - [ ] "optimize my CLAUDE.md" → should trigger
  - [ ] "my config is too long" → should trigger
  - [ ] "help me fix my CLAUDE.md" → should trigger
  - [ ] "what is CLAUDE.md?" → should NOT trigger (informational)
  - [ ] "validate my CLAUDE.md" → should NOT trigger (different skill)
  - [ ] Test paraphrased: "CLAUDE.md file is huge", "clean up my config"

- [ ] **Phase 4: Quality & UX testing**
  - [ ] Conversational quality: Clear explanations (not just error dump)
  - [ ] Interactive experience: Asks before editing, shows previews
  - [ ] Tool execution: Edit tool creates clean diffs
  - [ ] Tool execution: Write tool creates valid @import files
  - [ ] References usage: Claude reads references/ docs when helpful
  - [ ] Error handling: Graceful when files missing, permission errors

- [ ] **Phase 5: Document results**
  - [ ] Document test results in `docs/testing/optimize-cc-md-test-results.md`
  - [ ] Note any issues found
  - [ ] Update SKILL.md if needed based on findings
  - [ ] Confirm all Phase 3 acceptance criteria met

**Time estimate**: 3-4 hours total

### Acceptance Criteria

- [x] Skill directory follows progressive disclosure structure (SKILL.md + references/)
- [x] SKILL.md under 3,000 words with core workflow
- [x] References contain detailed strategies (size-optimization, import-patterns, organization-guide)
- [x] Description follows Phase 2.7 standards (trigger phrases, under 1024 chars)
- [x] Metadata includes author, category, documentation
- [x] Examples follow scenario format (User says → Actions → Result)
- [ ] Skill loads when user runs `/optimize-cc-md` (manual testing required)
- [ ] Claude follows instructions to run validation (manual testing required)
- [ ] Claude reads CLAUDE.md file (manual testing required)
- [ ] Claude explains violations conversationally (manual testing required)
- [ ] Claude asks for confirmation before edits (manual testing required)
- [ ] Claude actually makes edits using Edit/Write tools (manual testing required)
- [ ] Claude creates @import files when needed (manual testing required)
- [ ] Claude references references/ docs when user needs details (manual testing required)
- [ ] Trigger phrases work without false positives (manual testing required)

---

## Phase 4: Documentation & Polish

**Status**: In Progress
**Duration**: 2-3 days
**Dependencies**: Phase 3 content complete (manual testing deferred)

### Tasks

- [x] **Task 4.1**: Create plugin-specific README
  - [x] NOT the same as npm package README.md
  - [x] Create `.claude-plugin/README.md` for GitHub plugin users
  - [x] Focus on plugin capabilities (skill descriptions)
  - [x] Installation for Claude.ai users (non-npm flow)
  - [x] Positioning: "Focus on outcomes, not features" (Anthropic p20)
  - [x] Clear value proposition for plugin installation
  - [x] Link to npm package README for CLI users

**Example structure**:

```markdown
# claudelint Plugin for Claude Code

Validate and format your Claude Code project files directly in Claude.

## Skills Included

- **validate-all** - Run all validators in one command
- **validate-cc-md** - Check CLAUDE.md size and imports
- **optimize-cc-md** - Interactively improve your CLAUDE.md [NEW]
- [etc.]

## Installation

### For Claude.ai Users
/plugin install github:pdugan20/claudelint

### For npm Users (CLI + Skills)
npm install --save-dev claude-code-lint
/plugin install --source ./node_modules/claude-code-lint

## Usage

Simply ask Claude to validate your files:
- "Check my Claude Code project"
- "Validate my CLAUDE.md"
- "Optimize my config"

## Requirements

Requires `claude-code-lint` npm package for CLI commands.
```

- [x] **Task 4.2**: Update main npm README
  - [x] Add optimize-cc-md to skills list
  - [x] Document skill namespace usage (`/claudelint:optimize-cc-md`)
  - [x] Update feature list (9 skills instead of 8)
  - [x] Add optimize-cc-md usage example (interactive workflow)
  - [x] Link to plugin README for plugin-only users

- [x] **Task 4.3**: Update skill quality standards documentation
  - [x] Create `docs/skill-development.md` or update existing
  - [x] Document trigger phrase requirements (Phase 2.7)
  - [x] Document troubleshooting requirements
  - [x] Document progressive disclosure guidelines
  - [x] Include examples from skill-improvement-guidelines.md
  - [x] Reference for future skill development

- [x] **Task 4.4**: Update CONTRIBUTING.md
  - [x] Add skill quality standards section
  - [x] Link to skill-improvement-guidelines.md
  - [x] Document skill PR requirements
  - [x] Require trigger phrases in descriptions
  - [x] Require troubleshooting for complex skills

- [x] **Task 4.5**: Add skill testing infrastructure
  - [x] Create `scripts/test/skills/` directory
  - [x] Create `scripts/test/skills/validate-self.sh` (dogfood claudelint)
  - [x] Create `scripts/test/skills/test-cli-commands.sh` (CLI verification)
  - [x] Create `scripts/generate-manual-test-protocol.sh` (manual checklist generator)
  - [x] Add npm scripts to package.json:
    - `test:skills:structure` - Validate skill structure
    - `test:skills:cli` - Test CLI commands
    - `test:skills:metadata` - Metadata consistency (Jest)
    - `test:skills:automated` - Run all automated tests
    - `test:skills:manual` - Print reminder about manual tests
  - [x] Reference `docs/skill-testing.md` for implementation details

### Acceptance Criteria

- [x] Plugin README created for GitHub users
- [x] Plugin README focuses on outcomes, not implementation
- [x] npm README updated with optimize-cc-md
- [x] Skill development standards documented
- [x] CONTRIBUTING.md has skill quality requirements
- [x] No broken references to old skill names
- [x] All documentation follows markdown linting rules
- [x] Testing infrastructure created (scripts and npm commands)

---

## Phase 5: Testing & Release

**Status**: Not Started
**Duration**: 2-3 days
**Dependencies**: Phase 4 complete

**Testing Strategy**: Hybrid approach combining automated structure validation with manual UX testing

**Reference**: See `docs/skill-testing.md` for complete testing methodology

**Key Insight**: We use **claudelint itself** to validate our bundled skills (dogfooding), not a separate testing framework.

### Tasks

#### Task 5.1: Automated Testing (Dogfooding & CLI Verification)

**Goal**: Validate skill structure and CLI integration using claudelint itself

**Automated tests we CAN do**:

- - Skill structure validation (use claudelint itself)
- - CLI command verification (commands exist and respond)
- - Metadata consistency (versions match, commands referenced correctly)
- - Test fixtures for functional testing

**Automated tests we CANNOT do** (require manual testing):

- - Trigger effectiveness (does Claude load the skill?)
- - Conversational quality (does Claude explain well?)
- - User experience (does the skill actually help?)

**Subtasks**:

- [x] **5.1.1**: Create self-validation script
  - [x] Script: `scripts/test/skills/validate-self.sh`
  - [x] Runs: `claudelint validate-skills .claude/skills/`
  - [x] Validates all 9 bundled skills meet our own standards
  - [ ] Add to CI/CD workflow (pending 5.1.5)
  - [x] Add npm script: `npm run test:skills:structure`

- [x] **5.1.2**: Create CLI command verification script
  - [x] Script: `scripts/test/skills/test-cli-commands.sh`
  - [x] For each skill, extract referenced claudelint command
  - [x] Verify command exists: `claudelint <command> --help`
  - [x] Test with: `--help`, `--version`, basic invocation
  - [x] Add npm script: `npm run test:skills:cli`

- [x] **5.1.3**: Create metadata consistency tests
  - [x] Test file: `tests/skills/metadata.test.ts`
  - [x] Verify skill versions match package.json
  - [x] Verify skill descriptions in README match SKILL.md frontmatter
  - [x] Verify no obsolete command names referenced
  - [x] Verify all skills documented in README
  - [x] Add npm script: `npm run test:skills:metadata`
  - [x] All 59 tests passing

- [x] **5.1.4**: Create test fixtures
  - [x] Directory: `tests/fixtures/claude-md/`
    - [x] `valid.md` - Should pass validation
    - [x] `oversized.md` - >50KB file
    - [x] `circular-import.md` - Circular @import chain (with .claude/rules/ support files)
    - [x] `missing-import.md` - @import to non-existent file
    - [x] `invalid-frontmatter.md` - Bad frontmatter in imported rule
  - [x] Directory: `tests/fixtures/skills/`
    - [x] `valid/` - Well-formed skill
    - [x] `no-version/` - Missing version field
    - [x] `dangerous-command/` - Contains rm -rf (SKILL.md + .sh script)
  - [ ] Document fixture usage in `docs/skill-testing.md` (deferred - can add later if needed)

- [x] **5.1.5**: Add CI/CD automation
  - [x] Update `.github/workflows/ci.yml`
  - [x] Add job: Validate bundled skills (skill-validation)
  - [x] Run: `npm run test:skills:structure`
  - [x] Run: `npm run test:skills:cli`
  - [x] Run: `npm run test:skills:metadata`
  - [x] Run: `npm run test:skills:automated`
  - [x] Added to complete-validation job dependencies
  - [x] Fail build if any test fails

- [x] **5.1.6**: Add npm scripts
  - [x] `npm run test:skills:structure` - Dogfood claudelint
  - [x] `npm run test:skills:cli` - Verify CLI commands
  - [x] `npm run test:skills:metadata` - Check consistency (placeholder for now)
  - [x] `npm run test:skills:automated` - Run all automated tests
  - [x] `npm run test:skills:manual` - Print manual test protocol reminder

#### Task 5.2: Manual Testing Protocol (UX & Triggering)

**Status**: DEFERRED - Waiting for infrastructure (Phase 6 of manual-testing-infrastructure-refactor)

**Dependencies**:

- Infrastructure project Phase 6 must be complete
- Need realistic test workspaces for all 6 manual test scenarios (Tasks 1-6)
- Task 2 infrastructure ready, Tasks 1, 3-6 need setup

**Goal**: Test skill UX, triggering, and conversational quality (cannot be automated per Anthropic)

**Why manual**: Per Anthropic best practices, "automated benchmarks help, but real-world testing reveals issues that synthetic tests miss"

**Subtasks**:

- [ ] **5.2.1**: Create manual test protocol documents
  - [ ] Script: `scripts/generate-manual-test-protocol.sh`
  - [ ] Generates checklist from SKILL.md frontmatter
  - [ ] Output: `docs/testing/manual-test-protocol.md`
  - [ ] Include for each skill:
    - Trigger phrase tests (should/shouldn't trigger)
    - Functional tests (with test fixtures)
    - Quality tests (explanation clarity, UX)
    - Edge case tests
  - [ ] Reference: `docs/skill-testing.md` for templates

- [ ] **5.2.2**: Execute triggering tests (MANUAL - 30 min per skill)
  - [ ] For each of 9 skills:
    - [ ] Start fresh Claude session
    - [ ] Test 4-5 trigger phrases (should trigger)
    - [ ] Test 3-4 non-triggers (shouldn't trigger)
    - [ ] Test 2-3 paraphrased requests
  - [ ] Document results in `docs/testing/trigger-test-results.md`
  - [ ] Target: 90%+ trigger success rate
  - [ ] Fix descriptions if triggering fails

- [ ] **5.2.3**: Execute functional tests (MANUAL - 20 min per skill)
  - [ ] For each skill, test with fixtures:
    - [ ] Valid input (should pass)
    - [ ] Invalid input (should detect issues)
    - [ ] Edge cases (empty files, huge files, etc.)
  - [ ] Verify Claude explains issues clearly (not just error dump)
  - [ ] Verify correct claudelint command executed
  - [ ] Document results in `docs/testing/functional-test-results.md`

- [ ] **5.2.4**: Execute quality tests (MANUAL - 15 min per skill)
  - [ ] Conversational quality:
    - [ ] Uses plain language (not jargon)
    - [ ] Explains WHY violations matter
    - [ ] Provides actionable next steps
    - [ ] Shows examples when helpful
  - [ ] Interactive experience (optimize-cc-md only):
    - [ ] Asks before making changes
    - [ ] Shows previews/diffs
    - [ ] Handles user saying "no"
  - [ ] Error handling:
    - [ ] Graceful when claudelint missing
    - [ ] Clear error messages
    - [ ] Doesn't crash
  - [ ] Document results in `docs/testing/quality-test-results.md`

- [ ] **5.2.5**: Execute performance comparison (MANUAL - 1 hour)
  - [ ] Pick 2-3 skills: validate-all, optimize-cc-md, validate-cc-md
  - [ ] Test scenario WITHOUT skill loaded:
    - Count user messages needed
    - Count tool calls
    - Measure time to completion
    - Note success rate
  - [ ] Test SAME scenario WITH skill:
    - Count metrics
    - Compare to baseline
  - [ ] Document improvement % for release notes
  - [ ] Goal: Show 50%+ reduction in user effort

**Time estimate**: ~4.5 hours total for all 9 skills (30+20+15 min each)

**Documented in**: `docs/skill-testing.md` Section 2

#### Task 5.3: Integration Testing (MANUAL)

**Status**: DEFERRED - Waiting for Task 5.2 completion

**Dependencies**:

- Task 5.2 must be complete (uses same test workspaces)
- Infrastructure from manual-testing-infrastructure-refactor project

**Goal**: Verify plugin installation and skill loading work correctly

- [ ] **5.3.1**: Test local plugin installation
  - [ ] Build package: `npm pack`
  - [ ] Install locally: `/plugin install --source .`
  - [ ] Verify all 9 skills load: `/skills list`
  - [ ] Test one skill: `/claudelint:validate-all`

- [ ] **5.3.2**: Test GitHub plugin installation (after release)
  - [ ] Install from GitHub: `/plugin install github:pdugan20/claude-code-lint`
  - [ ] Verify skills load
  - [ ] Test namespaced skill: `/claudelint:optimize-cc-md`

- [ ] **5.3.3**: Test dependency detection
  - [ ] Uninstall npm package: `npm uninstall claude-code-lint`
  - [ ] Try using skill: `/claudelint:validate-all`
  - [ ] Verify graceful error: "claudelint not found, install: npm i -D claude-code-lint"
  - [ ] Reinstall package: `npm i -D claude-code-lint`

- [ ] **5.3.4**: Test in both environments
  - [ ] Test in Claude.ai web (plugin from GitHub)
  - [ ] Test in Claude Code CLI (plugin from npm or local)

- [ ] **5.3.5**: Verify npm package contents
  - [ ] Run: `npm pack --dry-run`
  - [ ] Verify `.claude/` directory included
  - [ ] Verify all 9 SKILL.md files included
  - [ ] Verify bin/claudelint included
  - [ ] Check package size (should be reasonable)

**Documented in**: `docs/skill-testing.md` Section 1 (Automation Opportunities)

#### Task 5.4: Version Bump & Release

- [ ] Determine semver bump (likely minor: 0.2.x → 0.3.0)
  - Breaking changes? (No - all additions)
  - New features? (Yes - optimize-cc-md, skill improvements)
  - Bug fixes? (Yes - better descriptions, troubleshooting)
- [ ] Run `npm run release` (auto-generates CHANGELOG)
- [ ] Verify `npm run sync:versions` runs
- [ ] Review generated CHANGELOG
- [ ] Push tags to GitHub

#### Task 5.5: Publish & Announce

- [ ] npm publish
- [ ] Create GitHub release with highlights:
  - NEW: optimize-cc-md skill (interactive CLAUDE.md optimization)
  - IMPROVED: All 8 skills now follow Anthropic best practices
  - IMPROVED: Better trigger phrases for skill activation
  - IMPROVED: Troubleshooting sections for complex skills
  - IMPROVED: Scenario-based examples
- [ ] Update release notes with performance comparison
- [ ] Announce on relevant channels (if applicable)

### Acceptance Criteria

**Automated Testing**:

- [ ] Skill structure validation passes (claudelint validates its own skills)
- [ ] All CLI commands exist and respond to --help
- [ ] Metadata consistency tests pass (versions match, no stale references)
- [ ] Test fixtures created for manual testing
- [ ] CI/CD runs automated tests on every PR
- [ ] npm scripts for automated tests work

**Manual Testing**:

- [ ] Manual test protocol documented in `docs/skill-testing.md`
- [ ] Triggering success rate >90% for all 9 skills
- [ ] No false positives in triggering tests
- [ ] Functional tests pass (skills execute correct commands)
- [ ] Quality tests pass (Claude explains clearly, good UX)
- [ ] Performance comparison documented (shows improvement)
- [ ] All test results documented in `docs/testing/`

**Integration**:

- [ ] Plugin installable from local source
- [ ] Plugin installable from GitHub
- [ ] All skill namespaces work (`/claudelint:skill-name`)
- [ ] Dependency detection works (graceful error when npm package missing)
- [ ] npm pack includes .claude/ directory
- [ ] Works in both Claude.ai and Claude Code CLI

**Release**:

- [ ] npm package published successfully
- [ ] GitHub release created with highlights
- [ ] CHANGELOG auto-generated correctly
- [ ] Release notes include performance improvements

### Success Metrics (from Anthropic p9)

**Quantitative**:

- Skills trigger on 90%+ of relevant queries
- 0 failed API calls per workflow (dependency checks work)
- Reduced token consumption vs baseline

**Qualitative**:

- Users don't need to prompt Claude about next steps
- Workflows complete without user correction
- Consistent results across sessions
- New users can accomplish tasks on first try

## Progress Summary

```text
Phase 0: [██████████] 100% (Complete - research & planning)
Phase 1: [██████████] 100% (Complete - bug fixes & plugin infrastructure)
Phase 2: [██████████] 100% (Complete - schema verification, deprecation system, skill improvements)
  2.6:   [██████████] 100% (Complete - rule deprecation system)
  2.7:   [██████████] 100% (Complete - skill quality improvements)
Phase 3: [█████████░]  90% (7/8 tasks - optimize-cc-md skill complete, manual testing deferred)
Phase 4: [██████████] 100% (5/5 tasks COMPLETE - documentation & testing infrastructure ready)
Phase 5: [██░░░░░░░░]  20% (1/5 tasks - Task 5.1 complete, Tasks 5.2-5.3 deferred, Tasks 5.4-5.5 remaining)

Overall: [████████░░]  85% (5/6 phases complete or mostly complete)
```

## Estimated Timeline

### Completed

- **Phase 0**: Complete (1 day - research & planning)
- **Phase 1**: Complete (1.5 days - bug fixes + plugin setup + skill renames + E10 update)
- **Phase 2.1-2.5**: Complete (9 days - schema verification system)
- **Phase 2.6**: Complete (2.5 days - rule deprecation system)
- **Phase 2.7**: Complete (1 day - skill quality improvements)

### Remaining

- **Phase 3**: 3-4 days (optimize-cc-md skill with progressive disclosure)
  - Task 3.1: Design structure (1 hour)
  - Task 3.2: Create directories (30 min)
  - Task 3.3: Write frontmatter (1 hour)
  - Task 3.4: Write core workflow (4-6 hours)
  - Task 3.5: Create reference docs (6-8 hours)
  - Task 3.6: Add examples (2 hours)
  - Task 3.7: Add troubleshooting (1 hour)
  - Task 3.8: Manual testing (3-4 hours)
- **Phase 4**: 2-3 days (documentation & polish - expanded)
  - Task 4.1: Plugin README (3-4 hours)
  - Task 4.2: Update npm README (2 hours)
  - Task 4.3: Skill development standards (3-4 hours)
  - Task 4.4: Update CONTRIBUTING (1-2 hours)
- **Phase 5**: 2-3 days (testing & release - comprehensive)
  - Task 5.1: Create test suite (6-8 hours)
  - Task 5.2: Execute manual testing (6-8 hours)
  - Task 5.3: Integration testing (2-3 hours)
  - Task 5.4: Version bump (1 hour)
  - Task 5.5: Publish & announce (1-2 hours)

**Total Remaining**: 7-10 days (~1.5-2 weeks)

**Total Project**: 22-25 days (~4-5 weeks)

### Current Status

- **Days completed**: ~16 days
- **Days remaining**: ~3-4 days (for version bump & release)
- **Completion**: 85%
- **Manual testing**: Deferred until end (Tasks 3.8, 5.2, 5.3)

## Risks & Blockers

### Resolved

1. **Good** **Plugin distribution unclear** - Confirmed npm + plugin.json works
2. **Good** **Building redundant validation rules** - Discovered 14 rules already exist
3. **Good** **Building redundant init skill** - Confirmed /init is built-in (closed-source)

### Remaining Risks

1. **optimize-cc-md skill complexity**
   - Risk: Skill instructions might be too complex/long
   - Mitigation: Keep SKILL.md under 5,000 words, use progressive disclosure
   - Status: Design in progress

2. **Skill trigger phrase overtriggering**
   - Risk: Skill triggers on unrelated queries
   - Mitigation: Test trigger phrases carefully, use specific language
   - Status: Testing needed

### Active Blockers

None currently.

## Notes

### Skill Naming (Anthropic Guide p11)

- **Reserved words**: CANNOT use "claude" or "anthropic" in names
- **Avoid generic names**: Single-word verbs cause triggering issues (p11)
- **Be specific**: Use suffixes like `-all`, `-cc`, `-cc-md` to clarify scope
- **Examples of bad names**: `format`, `validate`, `test` (too generic)
- **Examples of good names**: `format-cc`, `validate-all`, `validate-cc-md`

### Skill Structure

- Skill folders MUST NOT contain README.md
- Keep SKILL.md under 5,000 words
- Description field triggers skill - be specific, include trigger phrases
- Use progressive disclosure - move details to references/

### Project-Specific Notes

- /init command is closed-source (not in public repo)
- 14 CLAUDE.md validation rules already exist in src/rules/claude-md/
- Package.json bug: `"skills"` should be `".claude"` - npm users get nothing
