mirror of
https://github.com/alirezarezvani/ClaudeForge.git
synced 2026-07-04 10:53:16 -04:00
Claude
c374cc28a1
Splits the 518-line root CLAUDE.md into a 70-line root plus four chained sub-files (skill/, command/, agent/, docs/), all under the 150-line cap, and prunes stale references uncovered by the audit. - CLAUDE.md (518 -> 70): project overview, navigation with @-imports, behavioural guidelines summary, naming reference, license link - skill/CLAUDE.md (85): component flow, Python module architecture, modifying modules, adding templates, tech-stack detection, quality scoring, karpathy skill - command/CLAUDE.md (38): slash command development, top-level .md install layout, skill <-> command integration - agent/CLAUDE.md (70): guardian frontmatter, hook responsibilities, skill <-> agent integration, git triggers - docs/CLAUDE.md (109): install verification, smoke test, manual e2e tests, common operations, release process Stale content removed: - 'Dual Directory Structure' section (claude-md-enhancer/ legacy dir does not exist on disk) - '20-300 lines' / '300-line cap' references rewritten to 150 - '~/.claude/commands/enhance-claude-md/' bundle paths rewritten to top-level '.md' files (matching the new installer layout) - 'Three integrated components' updated to five - 'Current Version: 2.0.0' updated to 2.1.0 - '6 examples' in sample_input.json claim corrected (file has 1 scenario) Each sub-file opens with a markdown back-link and @../CLAUDE.md import; root contains @-imports for all four sub-files. Validator passes (status pass) for every file.
71 lines
2.6 KiB
Markdown
71 lines
2.6 KiB
Markdown
> Parent context: see the root [CLAUDE.md](../CLAUDE.md) for project-wide guidelines and behavioural rules.
|
||
> Chained import: `@../CLAUDE.md`
|
||
|
||
# Guardian Agent Development
|
||
|
||
Guidelines for the `claude-md-guardian` background-maintenance agent.
|
||
|
||
## File
|
||
|
||
`agent/claude-md-guardian.md` — installs to `~/.claude/agents/claude-md-guardian.md`.
|
||
|
||
## Modifying the Agent
|
||
|
||
1. Edit `agent/claude-md-guardian.md`.
|
||
2. YAML frontmatter fields to preserve:
|
||
- `permissions: [Bash, Read, Write, Edit, Grep, Glob, Skill]`
|
||
- `model: haiku` — token efficiency for routine sync runs.
|
||
- `color: purple` — visual indicator in Claude Code UI.
|
||
- `fork_safe: true` — agent runs independently.
|
||
- `hooks: [SessionStart, PreToolUse, PostToolUse]`.
|
||
3. Workflow phases inside the agent:
|
||
- **Assessment** — read `git diff` / `git status` / changed-file counts.
|
||
- **Analysis** — decide if changes are significant enough to update CLAUDE.md.
|
||
- **Update** — invoke the skill for targeted section updates rather than full regeneration (~70–80% token saving vs. rewrite).
|
||
4. Re-install for testing: `cp agent/claude-md-guardian.md ~/.claude/agents/`.
|
||
|
||
## v2.0.0+ Frontmatter Reference
|
||
|
||
```yaml
|
||
---
|
||
name: claude-md-guardian
|
||
permissions: [Bash, Read, Write, Edit, Grep, Glob, Skill]
|
||
model: haiku
|
||
color: purple
|
||
fork_safe: true
|
||
hooks:
|
||
- SessionStart
|
||
- PreToolUse
|
||
- PostToolUse
|
||
---
|
||
```
|
||
|
||
## Skill ↔ Agent Integration
|
||
|
||
The agent uses `claude-md-enhancer` (the skill's frontmatter name; installed as `claudeforge-skill/`) as its core capability. Invoke it with `Skill: claude-md-enhancer` inside the agent workflow.
|
||
|
||
Hook responsibilities:
|
||
|
||
- **SessionStart** — check `git diff`; if significant change is detected, invoke the skill for an incremental update.
|
||
- **PreToolUse** — validate before a CLAUDE.md edit lands.
|
||
- **PostToolUse** — after Edit/Write to any CLAUDE.md, run `BestPracticesValidator`, report the quality score, suggest improvements. Refuse to leave the file over 150 lines.
|
||
|
||
## Agent ↔ Git
|
||
|
||
The agent watches for change signals via:
|
||
|
||
```bash
|
||
git diff --name-status HEAD~10
|
||
git log --since="1 week ago" --oneline --no-merges
|
||
git diff HEAD~10 -- package.json requirements.txt pyproject.toml go.mod Cargo.toml
|
||
```
|
||
|
||
Triggers an update when any of these hold:
|
||
|
||
- 5+ files modified since the last sync.
|
||
- New dependencies added to a manifest file.
|
||
- New top-level directories created (potential new sub-CLAUDE.md candidates).
|
||
- Manual invocation after a milestone or release.
|
||
|
||
When the agent runs sync, it follows `command/sync-claude-md.md`: never commit, leave the diff for the user to review.
|