diff --git a/CLAUDE.md b/CLAUDE.md index 7d15aca..fe7d56b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,10 @@ # CLAUDE.md -> Before starting any session: what's the one thing we're shipping today? +> **STOP. Before producing ANY output, pull `docs/wiki/`, fetch open Forgejo +> issues for `archeious/luminos`, and present them as suggested tasks. Then +> ask: "What's the one thing we're shipping?" No preamble. No acknowledgment. +> Just the suggested tasks and the question. Everything else comes after the +> user answers.** --- @@ -8,7 +12,7 @@ - **Phase:** Active development — core pipeline stable, planning and domain intelligence work next - **Last worked on:** 2026-04-06 -- **Last commit:** merge: add -x/--exclude flag for directory exclusion +- **Last commit:** chore: ignore docs/wiki/ — separate git repo - **Blocking:** None --- @@ -75,26 +79,31 @@ python3 luminos.py --install-extras --- -## Git Workflow +## Development Workflow -Every change starts on a branch. Nothing goes directly to main. +- **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. +- **Shiny object capture** — new ideas go to PLAN.md (Raw Thoughts) or a + Forgejo issue, not into current work. -```bash -git checkout -b / -# ... work ... -git checkout main -git merge --no-ff -m "merge: " -git branch -d -``` +--- -| Type | Use | -|---|---| -| `feat/` | New feature | -| `fix/` | Bug fix | -| `refactor/` | No behavior change | -| `chore/` | Tooling, docs, config | +## Branching Discipline -Commit format: `: ` +- **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 +- **Push after commits** — keep Forgejo in sync after each commit or logical batch --- @@ -111,31 +120,64 @@ Commit format: `: ` --- -## Documentation +## Documentation Workflow -Wiki lives at `docs/wiki/` (gitignored — separate git repo). +- **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. -```bash -# First time -git clone ssh://git@forgejo-claude/archeious/luminos.wiki.git docs/wiki/ -# Returning -git -C docs/wiki pull -``` +--- -Wiki: https://forgejo.labbity.unbiasedgeek.com/archeious/luminos/wiki +## 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 -See `~/.claude/CLAUDE.md` +- **"externalize"** → read and follow `docs/externalize.md` +- **"wrap up" / "end session"** → read and follow `docs/wrap-up.md` --- ## Session Log -| Date | Summary | -|---|---| -| 2026-04-06 | Session 1: scan progress output, in-place per-file display, --exclude flag, Forgejo repo, PLAN.md, wiki setup, development practices | +| # | Date | Summary | +|---|---|---| +| 1 | 2026-04-06 | Project setup, scan progress output, in-place file display, --exclude flag, Forgejo repo, PLAN.md, wiki, development practices | Full log: wiki — [Session Retrospectives](https://forgejo.labbity.unbiasedgeek.com/archeious/luminos/wiki/SessionRetrospectives) diff --git a/docs/externalize.md b/docs/externalize.md new file mode 100644 index 0000000..aa870bc --- /dev/null +++ b/docs/externalize.md @@ -0,0 +1,36 @@ +# 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 new file mode 100644 index 0000000..02c150d --- /dev/null +++ b/docs/wrap-up.md @@ -0,0 +1,31 @@ +# 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