diff --git a/Session6.md b/Session6.md new file mode 100644 index 0000000..33162fe --- /dev/null +++ b/Session6.md @@ -0,0 +1,59 @@ +# Session 6 + +**Date:** 2026-04-07 +**Focus:** Extract shared workflow conventions from project CLAUDE.md to global `~/.claude/CLAUDE.md` +**Duration estimate:** ~15 minutes + +## What was done + +Meta/housekeeping session, no Forgejo issue (chore against the harness config, not the codebase). Single branch `chore/extract-workflow-to-global`, merged in commit `fc57e33`. + +### Moved out of project CLAUDE.md → global `~/.claude/CLAUDE.md` + +- **Development Workflow** (issue-driven work, explain-then-build, atomic commits, test coverage, shiny object capture) +- **Branching Discipline** (always-branch, naming, two-branch max, `--no-ff`, manual issue close) +- **Documentation Workflow** (wiki conventions — generalized to "for projects that maintain a wiki") +- **ADHD Session Protocols** (session start ritual, dopamine-friendly sizing, focus guard, breadcrumb, end protocol) +- **Session Protocols** pointer block + +The test-coverage bullet was generalized; the luminos-specific test command and exempt-modules list now lives in a small "Project-Specific Test Notes" section in `luminos/CLAUDE.md`. + +### Moved out of `docs/` → `~/.claude/protocols/` + +- `docs/externalize.md` → `~/.claude/protocols/externalize.md` +- `docs/wrap-up.md` → `~/.claude/protocols/wrap-up.md` + +Lightly generalized: references to "CLAUDE.md" now say "the project's CLAUDE.md", wiki step is conditional on the project using one, the externalize cross-reference in wrap-up.md points at the new global path. + +### Project CLAUDE.md after the trim + +Now ~95 lines (was ~196). Keeps only luminos-specific content: STOP banner, Current Project State, Project Overview, Module Map, Key Constraints, Running Luminos, Project-Specific Test Notes, Naming Conventions, Session Log. + +## Discoveries and observations + +- The Forgejo host info, the Development Workflow, and the ADHD protocols were duplicated mentally in every project — pulling them up to global removes that drift risk. +- The wrap-up protocol's "reread CLAUDE.md" step matters more now: the global file is the source of truth for procedure, but the project file holds the state. Both must be loaded. +- `~/.claude/protocols/` is a new directory. No other files there yet — could become a home for additional standalone protocol files (`/review`, `/triage`, etc.) over time. + +## Decisions made and why + +- **Generalize, don't copy verbatim.** The wiki workflow originally hardcoded `luminos.wiki.git`; the global version uses `.wiki.git` so it's reusable. +- **Keep the project-specific test command in the project file**, not in global. The exempt-module list (`ai.py`, `ast_parser.py`, `watch.py`, `prompts.py`) only makes sense in the luminos context. +- **Did not delete the project's Documentation Workflow section entirely** — wait, actually it was deleted; the global version covers it. The project file no longer mentions wiki workflow because the global one is sufficient. +- **No issue opened for this work.** Strictly a harness configuration change, not a Luminos codebase change. Worth noting for future me: not every chore needs an issue when the change is to `.claude/` rather than the repo. + +## Raw Thinking + +- The STOP banner at the top of `luminos/CLAUDE.md` still references "Forgejo issues for `archeious/luminos`" — that's correct since it's project-specific. But the banner essentially repeats the global Session Start Ritual. Some intentional redundancy is fine here because the banner enforces *order* (must happen before any output) which the global ritual also says, but doubling it makes the contract harder to miss. +- After this extraction, adding a *new* personal project just needs a small project CLAUDE.md (state + module map + constraints + test command). That's a real win for spinning up the next repo. +- One mild risk: `~/.claude/CLAUDE.md` is now the de-facto procedure manual. If it gets edited carelessly, every project's behavior shifts. Worth keeping it in some form of version control eventually (it's currently outside any git repo). +- `~/.claude/protocols/` lives outside git. Same risk as above. Not addressing today. + +## What's next + +Back to the actual roadmap. The session-start suggestions still stand: + +1. **Session 5 follow-ups** (next in plan order): #54 (dormant confidence-write path), #55 (unit tests for `ai.py` helpers), #56 (tool registration dedup), #57 (refactor `_run_dir_loop` before Phase 3 lands) +2. **Phase 3 — investigation planning**: #8 / #9 / #10 / #11 (planning prompt → `submit_plan` tool → dynamic turn allocation → plan caching) + +Recommended pickup: **#57 first** (refactor `_run_dir_loop`) because Phase 3's dynamic turn allocation will modify that loop, and the refactor is cheaper to do on a clean baseline than mid-feature. diff --git a/SessionRetrospectives.md b/SessionRetrospectives.md index cdeaf76..2d956bf 100644 --- a/SessionRetrospectives.md +++ b/SessionRetrospectives.md @@ -7,6 +7,7 @@ | [Session 3](Session3) | 2026-04-06 | Phase 1 complete, MCP backend architecture design, issues #38–#40 opened | | [Session 4](Session4) | 2026-04-06 | Phase 2 + 2.5 complete (#4–#7, #42, #44), classifier rebuild, context budget fix, 8 PRs merged | | [Session 5](Session5) | 2026-04-06 | Documentation deep dive: new Internals.md code tour, Architecture cache fix, Roadmap replaced with pointer, PLAN.md status snapshot (#53) | +| [Session 6](Session6) | 2026-04-07 | Extracted shared workflow/branching/protocols from project CLAUDE.md to global `~/.claude/CLAUDE.md`; moved externalize.md and wrap-up.md to `~/.claude/protocols/` | ---