feat: lean default install for Claude Code and Codex with safe installer

Adds a marked global rules block, project AGENTS.md/CLAUDE.md template, an on-demand lean-review skill, a dry-run-first stdlib installer with backups, and tests using temp homes. README quick start no longer moves ~/.claude; legacy library stays opt-in. Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
2026-09-30 13:43:26 -04:00
1 parent 7ec467451b
commit d45d4bec97
@@ -0,0 +1,37 @@
+# Lean setup
+
+Default install is small: a marked rules block in the user-level instruction files, an optional `lean-review` skill for Claude, and a project template. The legacy library (`.claude/`, `.agents/`, `.codex/`) is untouched and stays opt-in.
+
+## Install
+
+```bash
+python3 scripts/lean-install.py global                 # dry-run: shows what would change
+python3 scripts/lean-install.py global --apply         # ~/.claude/CLAUDE.md, $CODEX_HOME/AGENTS.md, lean-review skill
+python3 scripts/lean-install.py project /path/to/repo --apply   # AGENTS.md + CLAUDE.md (@AGENTS.md)
+python3 scripts/lean-install.py uninstall --apply      # remove only the marked block
+```
+
+Options: `--claude-home`, `--codex-home` (defaults `$CLAUDE_CONFIG_DIR`/`~/.claude`, `$CODEX_HOME`/`~/.codex`), `--skip-claude`, `--skip-codex`, `--skip-skill`, `--force`.
+
+Safety: dry-run unless `--apply`; the whole plan is validated before any write; an existing file is changed only by adding or replacing the marked block, after a `*.bak-<timestamp>` copy (never overwriting an earlier backup); symlinked targets, non-UTF-8 files, malformed markers and missing homes are refused; differing skill/project files need `--force`; settings, `config.toml` and `auth.json` are never read or written; no shell rc edits. Restore by copying a backup back over the file.
+
+Codex reads `$CODEX_HOME/AGENTS.override.md` before `AGENTS.md`; an override file makes the installed global block inactive.
+
+## Optional full library
+
+Copy pieces by hand rather than wholesale: pick agents from `.claude/agents/` (or `.codex/agents/`), skills from `.agents/skills/`, and merge hook entries from `.claude/settings.json` into your own settings after backing yours up. Hooks there reference `~/.claude/hooks/`, so only enable them once the scripts are copied there. Never replace `~/.claude` or its credentials.
+
+## Sources and decisions
+
+Official: [Claude Code best practices](https://code.claude.com/docs/en/best-practices), [Codex AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md) (redirects to learn.chatgpt.com/docs/agent-configuration/agents-md).
+Comparison material: Migration Accelerator `CLAUDE.md` (public GitHub sample `J-Bland/migration-accelerator`; the private original on git.kinec.tech was unavailable, so this is a mirror and may differ) and HyperFactory `AGENTS.md` / `diff-reviewer`.
+
+Adopted:
+- Compact always-loaded files; detail on demand via skills and links (official; MA/HF both enforce a size budget).
+- Verification the agent can run, reported with real output (Claude best practices).
+- Explore/plan only for substantive changes (Claude best practices).
+- One shared `AGENTS.md`, with `CLAUDE.md` importing it via `@AGENTS.md`; global Codex file lives in the actual `CODEX_HOME`, project files layer root-down (Codex guide).
+- Evidence rule and one consolidated diff review: a finding needs a concrete failing input and a failed refutation, existing guards are checked first (HyperFactory diff-reviewer).
+- Security review only when the diff warrants it.
+
+Rejected: mandatory refactor agent after every green; stop-hook loops; full role inventories; `xhigh`/1M-context defaults; enabling every MCP or LSP plugin; broad global permissions; hooks pointing at paths that may not exist; multi-model review loops; changing model or provider settings.