2 Commits

Author	SHA1	Message	Date
Claude	e33fa8326b	feat(plugin): command metadata, scoped skills, local-tier support, layered hooks, Stop audit ... Wave 3 - adoption hardening. Patterns adapted (in original prose, with attribution) from MIT-licensed shanraisshan/claude-code-best-practice. Commands (command/enhance-claude-md.md, command/sync-claude-md.md): - Add allowed-tools / disallowedTools / argument-hint / when_to_use so the commands auto-suggest in the slash menu and avoid permission prompts. - disallowedTools blocks WebFetch + WebSearch on both commands. - Drop the previous broken hooks block (array-of-{matcher, commands} shape did not match canonical schema; was never firing). Skills: - skill/karpathy-guidelines/SKILL.md: paths: glob over 23 code-file extensions, so the guardrails auto-load only when editing source, not markdown or data. - skill/SKILL.md: model: haiku, effort: medium, paths: scoped to CLAUDE.md + AGENTS.md + .claude/rules/*.md so validator/generator passes run cheaply without changing the user-facing model. CLAUDE.local.md personal tier: - skill/validator.py BestPracticesValidator now accepts filename=; any *.local.md basename waives the 150-line cap. - hooks/validate-claude-md.py reads the exempt suffix from hooks-config. - .gitignore covers CLAUDE.local.md, **/CLAUDE.local.md, .claude/settings.local.json, hooks/hooks-config.local.json. Layered hook config: - hooks/hooks-config.json: committed defaults (validateClaudeMd.enabled/maxLines/exemptFilenameSuffix/exitCodeOnViolation, stopAuditLine.enabled). - hooks/validate-claude-md.py merges hooks-config.json + hooks-config.local.json key-by-key; honours enabled=false (silent exit 0), configurable cap, configurable exit code. Stop audit hook: - hooks/audit-claude-md.py walks the project tree, prints one stderr line: total tracked / OVER cap / near cap (>=80%). Respects stopAuditLine.enabled from config. - hooks/hooks.json registers Stop event with matcher "". Guardian fail-closed contract: - agent/claude-md-guardian.md Safety & Validation section now explicitly requires Skill-tool invocation (no inline paraphrase of SKILL.md), abort on missing validated output, never auto-commit, and respect local hook config. Verified (8/8 smoke tests): - Both commands parse with new fields and no broken hooks block. - karpathy paths: 23 globs, includes .py/.ts/.go/.rs. - skill model=haiku effort=medium with CLAUDE.md path scope. - Validator: *.local.md (300 lines) -> pass; CLAUDE.md (300) -> fail; legacy ctor without filename -> default behavior preserved. - hooks-config.json valid; validateClaudeMd.enabled=true, maxLines=150. - Hook validator: default rc=2 on bloated, rc=0 when local override disables it, rc=0 on *.local.md (exempt). - Stop hook entry present; audit script: rc=0 with "5 CLAUDE.md tracked". - Regression: large-fullstack root still 52 lines with chain imports.	2026-05-19 02:04:00 +00:00
Claude	0a34178e22	feat(plugin): fix guardian hooks, add InstructionsLoaded enforcement, .claude/rules emitter, AGENTS.md interop ... Closes the gap between ClaudeForge and the Anthropic docs at code.claude.com/docs/en/memory (and its linked hooks / skills / plugins pages). Five tightly-scoped changes, each verified by smoke test. A. Fix guardian hook frontmatter shape (agent/claude-md-guardian.md) The previous array-of-{event, commands} shape did not match the documented schema (hooks: { EventName: [{ matcher, hooks: [{ type, command }] }] }), so the guardian's hooks silently did not fire. Rewritten to the canonical keyed-object shape with PostToolUse, PreToolUse, SessionStart, and the new InstructionsLoaded event. B+C. Plugin-level hooks/hooks.json + hooks/validate-claude-md.py New deterministic enforcement of the 150-line cap. The validator script reads the hook payload from stdin, extracts any referenced CLAUDE.md path (supports both PostToolUse tool_input.file_path and InstructionsLoaded path / file shapes), and exits 2 with stderr feedback when the file is over 150 lines. Wired to both PostToolUse on Write|Edit and InstructionsLoaded on every load_reason (session_start, nested_traversal, path_glob_match, include, compact). The cap is now enforced at every load *and* write, not only when the guardian decides to run sync. D. ContentGenerator.generate_rules_file() (skill/generator.py) Emits path-scoped .claude/rules/*.md instruction files with name, description, and paths: glob frontmatter. Claude loads these lazily — only when accessing files matching the globs — so file-type-specific guidance no longer has to live in the root CLAUDE.md. Validates that paths is non-empty (ValueError otherwise). E. AGENTS.md / .cursorrules / .windsurfrules interop command/enhance-claude-md.md Phase 1 now lists which sibling instruction files exist. ContentGenerator.generate_root_file() reads project_context['existing_instruction_files'] and prepends an ## External Instructions section with @AGENTS.md (etc.) imports, so repos already using other agent tooling can adopt ClaudeForge without losing their existing instructions. Smoke tests (all pass): - Guardian hooks frontmatter parses as a dict with 4 events, each carrying matcher + nested hooks array of {type, command} entries. - hooks.json is valid JSON; PostToolUse matcher = Write|Edit; InstructionsLoaded matcher covers all five load_reason values. - validate-claude-md.py: small file -> rc 0, bloated file (200 lines) -> rc 2 with stderr referencing the 150 cap, InstructionsLoaded payload shape also handled, non-CLAUDE.md paths ignored, no stdin -> rc 0. - generate_rules_file emits valid frontmatter with paths glob and raises ValueError when paths is empty. - generate_root_file inserts @AGENTS.md and @.cursorrules imports when existing_instruction_files lists them; omits the section otherwise. - Regression: large-fullstack root still 52 lines with chain imports intact; all five sub-CLAUDE.md files in this repo still pass validator (status = pass). Docs: - agent/CLAUDE.md updated to show the canonical hook shape and the hook-driven validator wiring. - skill/CLAUDE.md notes generate_rules_file and AGENTS.md interop. - CHANGELOG.md documents all five changes under Unreleased.	2026-05-19 02:04:00 +00:00