mirror of https://github.com/alirezarezvani/ClaudeForge.git synced 2026-07-04 02:43:15 -04:00

Files

T

Claude c374cc28a1 docs(claude-md): dogfood /sync-claude-md on root CLAUDE.md

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.

2026-05-19 02:04:00 +00:00

2.6 KiB

Raw Blame History

Parent context: see the root 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

Edit agent/claude-md-guardian.md.
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].
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).
Re-install for testing: cp agent/claude-md-guardian.md ~/.claude/agents/.

v2.0.0+ Frontmatter Reference

---
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:

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.

2.6 KiB Raw Blame History Unescape Escape