archeious/luminos
1
0
Fork 0
Code Issues 41 Pull requests Projects 1 Releases Packages Wiki Activity Actions
luminos/CLAUDE.md
Jeff Smith 159ab5207a chore: update CLAUDE.md for session 5
2026-04-06 23:23:23 -06:00

8.1 KiB
Raw Blame History

CLAUDE.md

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.

Current Project State

  • Phase: Active development — Phase 2 + 2.5 complete; documentation deep dive complete (#53); Phase 3 (investigation planning) ready to start
  • Last worked on: 2026-04-06
  • Last commit: merge: docs/issue-53-onboarding-internals (#53)
  • Blocking: None

Project Overview

Luminos is a file system intelligence tool — a zero-dependency Python CLI that scans a directory and produces a reconnaissance report. With --ai it runs a multi-pass agentic investigation via the Claude API.

Module Map

Module Purpose
luminos.py Entry point — arg parsing, scan(), main()
luminos_lib/ai.py Multi-pass agentic analysis via Claude API
luminos_lib/ast_parser.py tree-sitter code structure parsing
luminos_lib/cache.py Investigation cache management
luminos_lib/capabilities.py Optional dep detection, cache cleanup
luminos_lib/code.py Language detection, LOC counting
luminos_lib/disk.py Per-directory disk usage
luminos_lib/filetypes.py File classification (7 categories)
luminos_lib/prompts.py AI system prompt templates
luminos_lib/recency.py Recently modified files
luminos_lib/report.py Terminal report formatter
luminos_lib/tree.py Directory tree visualization
luminos_lib/watch.py Watch mode with snapshot diffing

Details: wiki — Architecture | Development Guide

Key Constraints

  • Base tool: no pip dependencies. tree, filetypes, code, disk, recency, report, watch use only stdlib and GNU coreutils. Must always work on bare Python 3.
  • AI deps are lazy. anthropic, tree-sitter, python-magic imported only when --ai is used. Missing packages produce a clear install error.
  • Subprocess for OS tools. LOC counting, file detection, disk usage, and recency shell out to GNU coreutils. Do not reimplement in pure Python.
  • Graceful degradation everywhere. Permission denied, subprocess timeouts, missing API key — all handled without crashing.

Running Luminos

# Base scan
python3 luminos.py <target>

# With AI analysis (requires ANTHROPIC_API_KEY)
source ~/luminos-env/bin/activate
python3 luminos.py --ai <target>

# Common flags
python3 luminos.py -d 8 -a -x .git -x node_modules <target>
python3 luminos.py --json -o report.json <target>
python3 luminos.py --watch <target>
python3 luminos.py --install-extras

Development Workflow

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

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 <branch> 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

Naming Conventions

Context Convention Example
Functions / variables snake_case classify_files, dir_path
Classes PascalCase _TokenTracker, _CacheManager
Constants UPPER_SNAKE_CASE MAX_CONTEXT, CACHE_ROOT
Module files snake_case ast_parser.py
CLI flags kebab-case --clear-cache, --install-extras
Private functions leading underscore _run_synthesis

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: <what was completed>. Next: <what comes 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
3 2026-04-06 Phase 1 complete (#1–#3), MCP backend architecture design (Part 10, Phase 3.5), issues #38–#40 opened
4 2026-04-06 Phase 2 + 2.5 complete (#4–#7, #42, #44), filetype classifier rebuild, context budget metric fix, 8 PRs merged, issues #46/#48/#49/#51 opened
5 2026-04-06 Documentation deep dive (#53): new Internals.md code tour, Architecture cache fix, Roadmap replaced with pointer, PLAN.md status snapshot

Full log: wiki — Session Retrospectives