From b2ead84531f9b75c68dcda1e9cddeab2bd27d30c Mon Sep 17 00:00:00 2001 From: Jeff Smith Date: Tue, 7 Apr 2026 13:47:41 -0600 Subject: [PATCH] chore: extract workflow sections to global ~/.claude/CLAUDE.md Move Development Workflow, Branching Discipline, Documentation Workflow, ADHD Session Protocols, and Session Protocols out of the project CLAUDE.md and into the global one so all projects share them. Move docs/externalize.md and docs/wrap-up.md to ~/.claude/protocols/ (lightly generalized). Project CLAUDE.md keeps only luminos-specific state, module map, constraints, naming, test command, and session log. Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 95 ++++----------------------------------------- docs/externalize.md | 36 ----------------- docs/wrap-up.md | 31 --------------- 3 files changed, 7 insertions(+), 155 deletions(-) delete mode 100644 docs/externalize.md delete mode 100644 docs/wrap-up.md diff --git a/CLAUDE.md b/CLAUDE.md index 9c4f541..3a5c86b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -79,42 +79,15 @@ python3 luminos.py --install-extras --- -## Development Workflow +## Project-Specific Test Notes -- **Issue-driven work** — all work must be tied to a Forgejo issue. If the - user names a specific issue, use it. If they describe work without an issue - number, search open issues for a match. If no issue exists, gather enough - context to create one before starting work. Branches and commits should - reference the issue number. -- **Explain then build** — articulate the approach in a few bullets before - writing code. Surface assumptions early. -- **Atomic commits** — each commit is one logical change. -- **Test coverage required** — every change to a testable module must include - or update tests in `tests/`. Run with `python3 -m unittest discover -s tests/`. - All tests must pass before merging. Modules exempt from unit testing: - `ai.py` (requires live API), `ast_parser.py` (requires tree-sitter), - `watch.py` (stateful events), `prompts.py` (string templates only). -- **Shiny object capture** — new ideas go to PLAN.md (Raw Thoughts) or a - Forgejo issue, not into current work. +Run tests with `python3 -m unittest discover -s tests/`. Modules exempt from +unit testing: `ai.py` (requires live API), `ast_parser.py` (requires +tree-sitter), `watch.py` (stateful events), `prompts.py` (string templates +only). ---- - -## Branching Discipline - -- **Always branch** — no direct commits to main, ever -- **Branch before first change** — create the branch before touching any files -- **Naming:** `feat/`, `fix/`, `refactor/`, `chore/` + short description -- **One branch, one concern** — don't mix unrelated changes -- **Two-branch maximum** — never have more than 2 unmerged branches -- **Merge with `--no-ff`** — preserves branch history in the log -- **Delete after merge** — `git branch -d ` immediately after merge -- **Close the underlying issue manually** — after merging, `PATCH` the - referenced issue to `state: closed` via the Forgejo API. Do not rely - on `Closes #N` keyword auto-close — it has not worked reliably in - this Forgejo instance, leaving issues stale while their PRs are - merged. Manual close is one extra API call and is part of the merge - step, not optional. -- **Push after commits** — keep Forgejo in sync after each commit or logical batch +(Development workflow, branching discipline, and session protocols live in +`~/.claude/CLAUDE.md`.) --- @@ -131,60 +104,6 @@ python3 luminos.py --install-extras --- -## Documentation Workflow - -- **Wiki location:** `docs/wiki/` — local git checkout of `luminos.wiki.git` -- **Clone URL:** `ssh://git@forgejo-claude/archeious/luminos.wiki.git` -- **Session startup:** clone if missing, `git -C docs/wiki pull` if present -- **All reads and writes** happen on local files in `docs/wiki/`. Use Read, - Edit, Write, Grep, Glob — never the Forgejo web API for wiki content. -- **Naming:** CamelCase slugs (`Architecture.md`, `DevelopmentGuide.md`). - Display name comes from the H1 heading inside the file. -- **Commits:** direct to main branch. Batch logically — commit when finishing - a round of updates, not after every file. -- **Push:** after each commit batch. - ---- - -## ADHD Session Protocols - -> **MANDATORY — follow literally, every session, no exceptions.** - -1. **Session Start Ritual** — Ensure `docs/wiki/` is cloned and current. - Fetch open issues from Forgejo (`archeious/luminos`) and present them as - suggested tasks. Ask: *"What's the one thing we're shipping?"* Once the - user answers, match to an existing issue or create one before starting - work. Do NOT summarize project state, recap history, or do any other work - before asking this question. - -2. **Dopamine-Friendly Task Sizing** — break work into 5–15 minute tasks with - clear, visible outputs. Each task should have a moment of completion. - -3. **Focus Guard** — classify incoming requests as on-topic / adjacent / - off-topic. Name it out loud before acting. Adjacent work goes to a new - issue; off-topic work gets deferred. - -4. **Shiny Object Capture** — when a new idea surfaces mid-session, write it - to PLAN.md (Raw Thoughts) or open a Forgejo issue, then return to the - current task. Do not context-switch. - -5. **Breadcrumb Protocol** — after each completed task, output: - `Done: . Next: .` - This re-orients after any interruption. - -6. **Session End Protocol** — before closing, state the exact pickup point for - the next session: branch name, file, what was in progress, and the - recommended first action next time. - ---- - -## Session Protocols - -- **"externalize"** → read and follow `docs/externalize.md` -- **"wrap up" / "end session"** → read and follow `docs/wrap-up.md` - ---- - ## Session Log | # | Date | Summary | diff --git a/docs/externalize.md b/docs/externalize.md deleted file mode 100644 index aa870bc..0000000 --- a/docs/externalize.md +++ /dev/null @@ -1,36 +0,0 @@ -# Externalize Protocol - -> Triggered when the user says "externalize" or "externalize your thoughts." -> This is a STANDALONE action. Do NOT wrap up unless separately asked. - -## Steps - -1. **Determine session number** — check the Session Log in CLAUDE.md for the - latest session number, increment by 1 - -2. **Pull wiki** — ensure `docs/wiki/` is current: - ```bash - git -C docs/wiki pull # or clone if missing - ``` - -3. **Create session wiki page** — write `docs/wiki/Session{N}.md` with: - - Date, focus, duration estimate - - What was done (with detail — reference actual files and commits) - - Discoveries and observations - - Decisions made and why - - Raw Thinking — observations, concerns, trade-offs, and loose threads that - came up during the session but weren't part of the main deliverable. - Things you'd mention if pair programming: prerequisites noticed, corners - being painted into, intent mismatches, unresolved questions. - - What's next - -4. **Update SessionRetrospectives.md** — read the current index, add the new - session row, write it back - -5. **Commit and push wiki:** - ```bash - cd docs/wiki - git add -A - git commit -m "retro: Session {N} — " - git push - ``` diff --git a/docs/wrap-up.md b/docs/wrap-up.md deleted file mode 100644 index 02c150d..0000000 --- a/docs/wrap-up.md +++ /dev/null @@ -1,31 +0,0 @@ -# Session Wrap-Up Checklist - -> Triggered when the user says "wrap up", "end session", or similar. -> Always externalize FIRST, then do the steps below. - -## Steps - -1. **Externalize** — run the `docs/externalize.md` protocol if not already - done this session - -2. **Reread CLAUDE.md** — ensure you have the latest context before editing - -3. **Update CLAUDE.md:** - - Update **Current Project State** — phase, last worked on (today's date), - last commit, blocking issues - - Update **Session Log** — add new entry, keep only last 3 sessions, - remove older ones (full history is in the wiki) - -4. **Commit and push main repo:** - ```bash - git add CLAUDE.md - git commit -m "chore: update CLAUDE.md for session {N}" - git push - ``` - -5. **Verify nothing is unpushed** — both the main repo and docs/wiki should - have no pending commits - -6. **Recommend next session** — tell the user what the best next session - should tackle, in priority order based on PLAN.md and any open Forgejo - issues