mirror of https://github.com/alirezarezvani/ClaudeForge.git synced 2026-07-03 10:23:15 -04:00

Files

T

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

4.2 KiB

Raw Blame History

Parent context: see the root CLAUDE.md for project-wide guidelines and behavioural rules. Chained import: @../CLAUDE.md

Skill Development

Guidelines for the claudeforge-skill Python modules and the karpathy-guidelines skill.

Component Interaction Flow

User Project
    ↓
/enhance-claude-md (Slash Command)  →  Explore subagent (deep scan)
    ↓
[Discovery] → [Analysis] → [Task]
    ↓
claude-md-guardian (Agent) OR Direct Skill Invocation
    ↓
claudeforge-skill (Python Modules)
    ↓
workflow.py → analyzer.py → validator.py → template_selector.py → generator.py
    ↓
CLAUDE.md ≤ 150 lines, chained via `@path` imports

Python Module Architecture

Five modules live under skill/:

workflow.py — InitializationWorkflow: orchestrates interactive setup, detects project type / tech stack / team size / phase / workflows, returns a context dict.
analyzer.py — CLAUDEMDAnalyzer: analyses existing files; quality scoring (0–100) across length, completeness, formatting, specificity, modularity.
validator.py — BestPracticesValidator: checks file length (hard cap 150, warning at 120), required sections, formatting, anti-patterns.
template_selector.py — TemplateSelector: maps project type + team size to a template; all team-size targets are ≤ 150 lines.
generator.py — ContentGenerator: writes root + context files, emits @path chain imports, prepends sub-file back-links, idempotent merge_with_existing. Also exposes generate_rules_file(name, description, paths, body) for path-scoped .claude/rules/*.md files (loaded lazily by Claude when accessed files match the paths: globs) and prepends @AGENTS.md-style imports when project_context['existing_instruction_files'] lists sibling instruction files.

Required Output Sections

Every generated CLAUDE.md must contain:

Project structure (ASCII tree, for projects that need it)
Setup & installation
Architecture (for non-trivial projects)
## Behavioral Guidelines (Karpathy summary — inserted automatically)
Cross-check against reference examples in skill/examples/

Modifying Python Modules

Edit files in skill/.
Run the smoke test (see docs/CLAUDE.md → Testing & Validation).
Re-install for live testing: ./install.sh (project-level scope).
Test slash command: /enhance-claude-md.
Validate output against skill/examples/.
Update CHANGELOG.md.

Adding Reference Templates

Add a new file under skill/examples/.
Follow the native format (project structure, setup, architecture, tech guidelines).
Update skill/examples/README.md.
Teach template_selector.py how to detect the new template.
Add a scenario to skill/sample_input.json.

Quality Scoring (analyzer.py)

calculate_quality_score() breakdown:

length_appropriateness: 25 pts (50–150 lines ideal; the 150-line hard cap is enforced here)
section_completeness: 25 pts (required sections present)
formatting_quality: 20 pts (markdown, heading hierarchy, code blocks)
content_specificity: 15 pts (project-specific, not generic)
modular_organization: 15 pts (chained sub-files when needed)

Tech Stack Detection

skill/workflow.py → _detect_tech_stack() reads these signals:

Frontend — React/Vue/Angular via package.json; Angular via angular.json; TypeScript via tsconfig.json.
Backend — Node (package.json), Python (requirements.txt / pyproject.toml / setup.py), Go (go.mod), Java (pom.xml / build.gradle), Rust (Cargo.toml).
Database — Postgres (pg / psycopg2), MongoDB (mongoose / pymongo), Redis (redis / ioredis).

Add new detectors there, not in the template selector.

Karpathy Guidelines Skill

skill/karpathy-guidelines/SKILL.md is the standalone skill installed at ~/.claude/skills/karpathy-guidelines/. Adapted with attribution from the MIT-licensed forrestchang/andrej-karpathy-skills repo. The four principles are inserted automatically into every generated CLAUDE.md via template_selector._generate_karpathy_guidelines() and generator._generate_karpathy_guidelines(). Do not strip the embedded section during enhancement.

4.2 KiB Raw Blame History Unescape Escape