archeious/luminos
1
0
Fork 0
Code Issues 41 Pull requests Projects 1 Releases Packages Wiki Activity Actions
Page: Session6
Pages
Architecture DevelopmentGuide Home Internals Roadmap Session1 Session2 Session3 Session4 Session5 Session6 Session7 Session8 SessionRetrospectives
1 Session6
Jeff Smith edited this page 2026-04-07 13:48:27 -06:00
Table of Contents

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 <repo>.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.