mirror of
https://github.com/alirezarezvani/ClaudeForge.git
synced 2026-07-03 18:33:16 -04:00
Claude
0a34178e22
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.
86 lines
4.2 KiB
Markdown
86 lines
4.2 KiB
Markdown
> Parent context: see the root [CLAUDE.md](../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
|
||
|
||
1. Edit files in `skill/`.
|
||
2. Run the smoke test (see `docs/CLAUDE.md` → Testing & Validation).
|
||
3. Re-install for live testing: `./install.sh` (project-level scope).
|
||
4. Test slash command: `/enhance-claude-md`.
|
||
5. Validate output against `skill/examples/`.
|
||
6. Update `CHANGELOG.md`.
|
||
|
||
## Adding Reference Templates
|
||
|
||
1. Add a new file under `skill/examples/`.
|
||
2. Follow the native format (project structure, setup, architecture, tech guidelines).
|
||
3. Update `skill/examples/README.md`.
|
||
4. Teach `template_selector.py` how to detect the new template.
|
||
5. 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](https://github.com/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.
|