docs: ARCHITECTURE tree, README/USAGE /onboard split, CHANGELOG path rules + InstructionsLoaded logger — ship-feature claude-md split
This commit is contained in:
1 parent
336e7a7e4e
commit
dc6580a6e5
4 files changed
+11
-6
No files matched your search
+4
-3
@@ -20,16 +20,17 @@ claude-config/
|
||||
├── update-all.sh # One-command update for all components
|
||||
├── Makefile # Unified entry point: make install / doctor / update / test (make help)
|
||||
├── plugins.lock.json # Version pinning for non-marketplace dependencies and vendored skills
|
||||
├── hooks/ # Claude Code hooks: session start, statusline, RTK rewrite, ctx7 + design-toolchain reminders, attention notify, unpushed-work guard, manual-mode push guard
|
||||
├── hooks/ # Claude Code hooks: session start, statusline, RTK rewrite, ctx7 + design-toolchain reminders, attention notify, unpushed-work guard, manual-mode push guard, instruction-load log
|
||||
├── githooks/ # Generated git hooks (pre-commit, post-commit, post-merge, reference-transaction), git's global core.hooksPath
|
||||
├── .githooks/ # This repo's own copy of the same hooks
|
||||
├── .claude/rules/ # This repo's project path rules (paths: frontmatter), loaded on Read of a matching file
|
||||
├── rules/ # Rule files deployed to ~/.claude/rules (path-scoped or always-on)
|
||||
├── agents/ # Execution units called by skills (never invoked directly)
|
||||
├── skills/ # Entry points invoked via /skill-name
|
||||
├── mods/ # Claude Code mods (function-hooks plugins), loaded through the skills/<name> symlink
|
||||
├── skills-external/ # Vendored skill packs: gstack submodule, design skills, superpowers, agent-skills, MengTo scroll skills, 21st and Higgsfield packs (machine-owned copies gitignored)
|
||||
├── templates/ # Per-project templates (CLAUDE.md, settings, memory registries, deploy runbook, gitignore)
|
||||
└── lib/ # Shared libs: gitflow, profiles, vendoring, route doctrine, gates, archetypes, tests
|
||||
├── templates/ # Per-project templates (CLAUDE.md, settings, memory registries, path-rule skeletons, deploy runbook, gitignore)
|
||||
└── lib/ # Shared libs: gitflow, profiles, vendoring, route doctrine, gates, archetypes, project-rule oracle, tests
|
||||
```
|
||||
|
||||
## Architecture principles
|
||||
|
||||
@@ -17,6 +17,8 @@ Format follows [Keep a Changelog](https://keepachangelog.com/) and this project
|
||||
- **model-router prompt classifier**: a plain prompt typed in the composer (12 characters or more, not a slash command, not mid-turn, never under `-p` or in a sub-agent) that no keyword rule, skill, run slot, `/route` or floor covers is labelled by one call to the engine's small model (`design`, `analysis`, `coding`, `bookkeeping`, `chat`), bounded to 3 s. The label maps to plan, reflect, implement or apply and the turn takes that phase's route: its effort, and its model under the switch and the downgrade cap, never above the session model (an `ultrathink` floor raises the effort only, the guess's model holds); no dialog, no file write, gone at the end of the turn, replaced by any route call or typed skill, and dropped for that turn by a `/effort` typed between turns. Three failures in a row pause it for `cooldownMinutes` (one toast, `classifier: paused` in the status line). `"classify": false` in `~/.claude/model-router.json` and `/route classify on|off` turn it off; `/route show` prints `classify:`. The status line reads `route: classifier <phase>` and `/route verbose on` adds `(<phase>: classifier)`.
|
||||
- **model-router cold-read caps**: both main-loop caps measure the cold read a switch costs, from a per-model record of main's last step, warm within the engine's prompt-cache TTL (`cache_ttl` 5m or 1h from main's model-switch events, 1 h before the first, kept across `/clear`; records cleared by `/clear` and `/route reload`), plus the submitted prompt the engine's usage may not count yet (code points / 3 of its text, context entries and a typed skill's body, added at the turn's first main step unless usage already grew by half of it; a `document` attachment blocks the switch for that step); `downgradeMaxTokens` (default 120000) joins `upgradeMaxTokens` (200000). A model-loaded helper skill inside a best-tier run moves effort only; main routed onto a model whose window the context outgrew returns to the session model. `/route show` prints `switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`, the status line shows ` · switch off` only when the switch is off, the skip line is logged once per cap crossing and the change toast names a cap hold. A built-in `general-purpose` agent that main spawns with no model while main sits below the session model starts on the session model instead of inheriting the lower one.
|
||||
- **/explain-diff skill**: turns a change (commit, range, branch, merge, PR, staged or uncommitted work) into one self-contained HTML page saved outside the repo, under `~/Documents/explanations/<project>/YYYY-MM-DD-<slug>.html`. The page has a background, an intuition built on toy data with HTML diagrams, a code walkthrough grouped by concern and a 5-question interactive quiz. Adapted from Geoffrey Litt's explain-diff gist. A bundled template (light and dark, works offline) and a checker (`scripts/check_explanation.py`: file name, location, sections, quiz, code escaping, no ASCII art, no em-dash) hold every page to the same floor. Routing row `reflect`; profiles full, max and dev.
|
||||
- **Project path rules (CLAUDE.md split)**: `lib/project-rules.sh` (`check`, `matches`, `sections`, `extract`, `emit`, optional `-C <dir>`) is the glob oracle for `.claude/rules/<name>.md` rules, one-line `paths:` frontmatter, loaded on Read of a matching file; suite `lib/tests/project-rules.test.sh`. `/onboard split` classifies an existing project CLAUDE.md section by section behind a gate and moves the path-bound ones into rules on a `chore/claude-md-split` branch. `/onboard` and `/init-project` emit `docker`, `testing` and `ci` rules from `templates/project-rules/` when their globs match. This repo's CLAUDE.md now keeps its header, Health Stack and a pointer; four sections load as path rules.
|
||||
- **InstructionsLoaded logger**: `hooks/instructions-loaded.sh`, wired in `settings.json`, appends one JSON line per instruction file loaded to `~/.claude/logs/instructions-loaded.jsonl` (rotated above 5 MB), the proof that a path rule loaded.
|
||||
|
||||
### Changed
|
||||
- impeccable is the Build path for all UI: it replaces `frontend-design` on the design gate's `# GATE-BLOCK:` list and leads the Build line of the design doctrine. `frontend-design` stays installed as the light path for a one-off visual. Detector rule count corrected 45 to 61 (BDR-119).
|
||||
@@ -33,6 +35,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/) and this project
|
||||
- `/release-candidate` STEP 6: in manual push mode, with an invalid mode value, or when main or develop is not on origin, Claude pushes nothing and prints one command for the user, `! git push --atomic origin main develop v<X.Y.Z>`. The tag-push question remains for auto-push mode with both branches on origin. The version must match `^[0-9]+\.[0-9]+\.[0-9]+$` before it enters a command or tag; `release-executor` checks it too and blocks on anything else.
|
||||
- `/tour`: each summary row says `on origin` or `local only` with the `! git -C "<project>" push -u origin <branch>` to run. The tour never pushes or retries.
|
||||
- model-router keyword prompt rules (`plan|design|architecture…`, `why|review|audit…`), the `ultrathink` floor and the derived `orchestrate` route of a main Agent dispatch set the turn's effort only, never a model: they no longer lift main above the session model, and a held best-tier run keeps its model. Fable on main comes only from a skill row, the `route` tool, a typed `/route` or a `/model` hand pick (BDR-123). Tests: `mods/model-router/hooks/register.test.ts`.
|
||||
- `.gitignore` and `templates/gitignore/standard.gitignore` un-ignore `.claude/rules/` (`!.claude/rules/` after `.claude/*`); `lib/gitflow-test.sh` asserts the socle line.
|
||||
|
||||
### Removed
|
||||
- The five `effort-low` … `effort-max` skills, `lib/effort-pins.txt`, `lib/effort-pins.sh` and `lib/model-check.sh`, with their tests and the effort-pin re-apply steps of `install-plugins.sh` and `update-all.sh`. The model-router rows replace them. A typed `/effort-<level>` no longer exists: use `ultrathink` or `/route effort=max`. Breaking: the next release is 3.0.0.
|
||||
|
||||
@@ -208,7 +208,7 @@ a different package, ships its own conflicting `graphify` bin) — see
|
||||
|---|---|
|
||||
| `/init-project` | Initialize a complete project from scratch (full orchestrator, 12+ steps) |
|
||||
| `/ship-feature` | Ship a feature end-to-end with validation gates (full orchestrator) |
|
||||
| `/onboard` | Onboard an existing project: CLAUDE.md, settings, .claudeignore, archetype audits, report and a sequenced TODO backlog |
|
||||
| `/onboard` | Onboard an existing project: CLAUDE.md, settings, .claudeignore, path rules, archetype audits, report and a sequenced TODO backlog. `/onboard split` moves the path-bound sections of an existing CLAUDE.md into `.claude/rules/` (loaded on Read of a matching file) |
|
||||
| `/feat` | Small feature implementation (1-5 files, lightweight) |
|
||||
| `/bugfix` | Structured bug fix with root cause investigation |
|
||||
| `/hotfix` | Quick fix for superficial bugs (typos, CSS, config — max 2 files) |
|
||||
|
||||
@@ -139,7 +139,7 @@ Tu veux...
|
||||
| `/feat` | Petite feature (1-5 fichiers) | Léger, pas d'orchestration lourde |
|
||||
| `/bugfix` | Bug avec investigation root cause | Hypothèses, diagnostic, fix minimal |
|
||||
| `/hotfix` | Bug superficiel (typo, CSS, config) | Max 2 fichiers, cause évidente |
|
||||
| `/onboard` | Projet existant non géré par ce config | Génère CLAUDE.md + settings |
|
||||
| `/onboard` | Projet existant non géré par ce config | Génère CLAUDE.md + settings ; `/onboard split` découpe un CLAUDE.md existant en règles `.claude/rules/` |
|
||||
| `/plugin-check` | Avant de démarrer tout travail | Aussi embarqué en STEP 0 des orchestrateurs |
|
||||
| `/analyze` | Comprendre du code avant de le modifier | Read-only, aucune solution proposée |
|
||||
| `/analyze` + erreur | Diagnostiquer un test/build qui échoue | Mode DEBUG : hypothèses ordonnées |
|
||||
@@ -286,7 +286,7 @@ cd mon-projet-existant/
|
||||
| 0 | plugin-advisor — détection signaux + activation plugins | recommandations plugins |
|
||||
| 1 | Archetype detection (scan ~/.claude/lib/project-archetypes/*.md) | archétype SELECTED + implications auto |
|
||||
| 1b | Gate monorepo (A/B/C si détecté) | mode choisi |
|
||||
| 2 | Config baseline (onboarder agent) | CLAUDE.md, settings.json, .claudeignore, .claude/tasks/ + .claude/memory/ + .claude/audits/ |
|
||||
| 2 | Config baseline (onboarder agent) | CLAUDE.md, settings.json, .claudeignore, .claude/tasks/ + .claude/memory/ + .claude/audits/ + .claude/rules/ (docker, testing, ci si un glob matche) |
|
||||
| 2.5| Lib d'animation (`motion`), proposée, opt-in | dépendance si acceptée |
|
||||
| 2.6| Gitflow init (main + develop, hooks) | branches + .githooks/ |
|
||||
| 3 | Interview deep = business minimum (users, deadlines, équipe, légal, perfs) + adaptative par archétype | brief enrichi |
|
||||
@@ -311,6 +311,7 @@ cd mon-projet-existant/
|
||||
```
|
||||
/onboard "Python FastAPI" # hint stack
|
||||
/onboard force-archetype:wordpress # override detection
|
||||
/onboard split # CLAUDE.md existant → règles .claude/rules/ (sections liées à un chemin)
|
||||
```
|
||||
|
||||
**Après /onboard :**
|
||||
|
||||
Reference in new issue
Block a user