Developer onboarding: deep-dive code tour + reconcile architecture/roadmap docs #53

New issue

Closed

opened 2026-04-07 05:12:10 +00:00 by archeious · 0 comments

archeious commented

2026-04-07 05:12:10 +00:00

Owner

Before Phase 3 starts, do a documentation pass so a new developer (basic Python, no agent-loop background) can orient themselves to the project from the wiki alone.

Deliverables

New page: Internals.md — narrative code tour of how luminos actually works. Sections:

The two layers (base scan vs --ai), strict separation, lazy imports
Base scan walkthrough (luminos.py:scan())
AI pipeline walkthrough: analyze_directory → _run_investigation → _run_survey → dir loop fan-out → _run_synthesis, with file:line refs
The dir loop in depth: message history, tool registry, _execute_tool dispatch, _TokenTracker, early-exit + partial cache flush, submit_report
Tools reference (every tool the agent has, where defined, when filtered)
Cache model (JSONL append, investigation IDs, entry shapes, leaves-first via _get_child_summaries)
Prompts (where each lives, what gets injected at runtime)
Token budget (per-call vs cumulative, the #44 fix)
Where to make common changes (add a tool / add a pass / change a prompt)
Glossary

Fix existing docs in the same pass:

Architecture.md: update the AI pipeline diagram to include the survey pass + signals; complete the tool list; add _TokenTracker to module notes
Roadmap.md: delete and replace with a thin pointer to PLAN.md + open issues. Three sources of truth is the root cause of the staleness; cut to two
PLAN.md File Map: fix the domain.py lie (survey landed in ai.py)
PLAN.md: add status to phases — Phase 1, 2, 2.5 done; Phase 3 next
DevelopmentGuide.md: add a link at the top pointing to Internals.md

Out of scope

Any code changes
Reorganizing PLAN.md beyond status fields and the file-map fix

Acceptance

A developer who has never seen the repo can read Home → DevelopmentGuide → Internals and understand both how to run it and how the AI pipeline actually flows, with file:line references to verify.

Before Phase 3 starts, do a documentation pass so a new developer (basic Python, no agent-loop background) can orient themselves to the project from the wiki alone. ## Deliverables **New page: `Internals.md`** — narrative code tour of how luminos actually works. Sections: - The two layers (base scan vs --ai), strict separation, lazy imports - Base scan walkthrough (`luminos.py:scan()`) - AI pipeline walkthrough: `analyze_directory` → `_run_investigation` → `_run_survey` → dir loop fan-out → `_run_synthesis`, with file:line refs - The dir loop in depth: message history, tool registry, `_execute_tool` dispatch, `_TokenTracker`, early-exit + partial cache flush, `submit_report` - Tools reference (every tool the agent has, where defined, when filtered) - Cache model (JSONL append, investigation IDs, entry shapes, leaves-first via `_get_child_summaries`) - Prompts (where each lives, what gets injected at runtime) - Token budget (per-call vs cumulative, the #44 fix) - Where to make common changes (add a tool / add a pass / change a prompt) - Glossary **Fix existing docs in the same pass:** - `Architecture.md`: update the AI pipeline diagram to include the survey pass + signals; complete the tool list; add `_TokenTracker` to module notes - `Roadmap.md`: **delete and replace** with a thin pointer to PLAN.md + open issues. Three sources of truth is the root cause of the staleness; cut to two - `PLAN.md` File Map: fix the `domain.py` lie (survey landed in `ai.py`) - `PLAN.md`: add status to phases — Phase 1, 2, 2.5 done; Phase 3 next - `DevelopmentGuide.md`: add a link at the top pointing to `Internals.md` ## Out of scope - Any code changes - Reorganizing PLAN.md beyond status fields and the file-map fix ## Acceptance - A developer who has never seen the repo can read `Home → DevelopmentGuide → Internals` and understand both how to run it and how the AI pipeline actually flows, with file:line references to verify.