ClaudeForge/docs/CLAUDE.md

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

Installation, Testing & Release

Operational guidance for installers, smoke tests, and release management.

Test Installation Scripts

# macOS/Linux
./install.sh
# Choose option 1 (user-level) or 2 (project-level)

# Windows
.\install.ps1
# Same options as above

# Verify after install:
ls -la ~/.claude/skills/claudeforge-skill/
ls -la ~/.claude/skills/karpathy-guidelines/
ls -la ~/.claude/commands/enhance-claude-md.md
ls -la ~/.claude/commands/sync-claude-md.md
ls -la ~/.claude/agents/claude-md-guardian.md

Directory Layout After Install

~/.claude/                                  # user-level (project-level mirrors under ./.claude)
├── skills/
│   ├── claudeforge-skill/                  # from skill/
│   │   ├── SKILL.md
│   │   ├── analyzer.py
│   │   ├── validator.py
│   │   ├── generator.py
│   │   ├── template_selector.py
│   │   ├── workflow.py
│   │   └── examples/
│   └── karpathy-guidelines/                # from skill/karpathy-guidelines/
│       └── SKILL.md
├── commands/
│   ├── enhance-claude-md.md
│   └── sync-claude-md.md
└── agents/
    └── claude-md-guardian.md

Smoke Test (run from repo root)

python3 - <<'PY'
import sys; sys.path.insert(0, 'skill')
from validator import BestPracticesValidator
from template_selector import TemplateSelector
from generator import ContentGenerator

assert BestPracticesValidator.MAX_RECOMMENDED_LINES == 150
for cfg in TemplateSelector.TEAM_SIZE_TEMPLATES.values():
    assert cfg['target_lines'] <= 150

ctx = {'type':'fullstack','tech_stack':['typescript','python'],
       'team_size':'medium','phase':'production','workflows':['cicd']}
out = ContentGenerator(ctx).generate_root_file()
assert len(out.splitlines()) <= 150
assert '## Behavioral Guidelines' in out
print('smoke ok')
PY

Run after any change to skill/, command/, or agent/.

Manual End-to-End Tests

Fresh project init:

1. mkdir test-project && cd test-project && git init && npm init -y
2. Run /enhance-claude-md.
3. Confirm generated CLAUDE.md ≤ 150 lines, contains ## Behavioral Guidelines, has tech detection right.

Existing project enhance:

1. Seed CLAUDE.md with one short section.
2. Run /enhance-claude-md; confirm quality score reported, missing sections proposed, ## Behavioral Guidelines appended if absent.

Guardian agent sync:

1. Add a new dependency and create a new directory.
2. Open a new Claude Code session — SessionStart fires.
3. Confirm the agent updates Tech Stack / Project Structure and quality re-validates.

Sync command:

1. In a repo with stale CLAUDE.md references, run /sync-claude-md.
2. Confirm stale lines flagged, 150-cap enforced via split, root ↔ sub chain repaired, diff left staged for the user.

Common Operations

Update a reference template: edit skill/examples/<name>-CLAUDE.md, then add a matching scenario to skill/sample_input.json.

Update quality scoring: edit skill/analyzer.py → calculate_quality_score(). Re-run the smoke test.

Update installer: edit install.sh / install.ps1 (paths, copy logic, backup logic, hooks). Test both user-level and project-level on a throwaway directory.

Release Process

1. Update CHANGELOG.md under a new version header.
2. Bump the version in README.md, skill/SKILL.md, and .claude-plugin/plugin.json.
3. git tag -a vX.Y.Z -m "Release vX.Y.Z".
4. git push origin vX.Y.Z.
5. Create the GitHub release with a CHANGELOG excerpt.

Versioning is semver. See docs/MIGRATION_V2.md for the v1 → v2 upgrade path.