Skip to content

feat(ai-autopilot): scale mode — self-maintaining CODE-OVERVIEW.md (#114)#129

Merged
suleimansh merged 1 commit into
mainfrom
feat/code-overview
Jul 2, 2026
Merged

feat(ai-autopilot): scale mode — self-maintaining CODE-OVERVIEW.md (#114)#129
suleimansh merged 1 commit into
mainfrom
feat/code-overview

Conversation

@suleimansh

Copy link
Copy Markdown
Member

Child of #110. Help the agent navigate a large codebase fast.

Maintains a compact CODE-OVERVIEW.md — a map of the repo (structure, key modules, entry points, conventions) the agent reads first, before working, so it stays oriented without re-scanning the whole tree and blowing the context budget.

The hard part is not generating it once but keeping it current: a stale overview is worse than none. So the trigger is a material-change detector wired into the loop (#113), not on-demand-only and not on every edit.

  • detectMaterialChange(event) — deterministic, path-driven: build/config change (package.json, *.config.ts, turbo.json, ...), test-framework migration (vitest/jest/playwright config), a directory restructure (summary keywords), or a large change spread across many areas. Cheap enough to run on every loop event.
  • CodeOverviewMaintainer — owns the policy: refresh + persist on a material change, skip otherwise, seed the previous overview into regeneration so it revises rather than rewrites.
  • agentOverview(agent) — the default regeneration, an ai-sdk agent that reads the tree (via its tools) and returns a structured { summary, sections }.
  • overviewLoopPrompt(maintainer) — bridges the maintainer into a LoopPrompt, so adding its id to a rule (e.g. on major-change) makes the overview self-maintain.
  • CODE-OVERVIEW.md round-trips via parseOverview / serializeOverview; loadOverview / saveOverview persist over an OverviewFs (a runner session's fs satisfies it, same as the decisions store).

Matches the landscape note on the issue (Cloudflare's "instructions rot fast" reviewer): auto-maintenance is the whole point, and the regen trigger is a material-change detector, not on-demand.

Regeneration is injected, so the whole policy is tested offline against a stub. Tests: markdown round-trip, the detector (build/test/restructure/many-files/threshold/extra-patterns + routine-edit skip), the maintainer (material refresh + persist, immaterial skip, previous seeding, on-demand generate, load, observer isolation), and agentOverview + overviewLoopPrompt against a real Loop. Full suite 189 green.

Closes #114.

@suleimansh suleimansh added the enhancement New feature or request label Jul 2, 2026
@suleimansh suleimansh self-assigned this Jul 2, 2026
@suleimansh suleimansh added the priority: low Nice to have / latent label Jul 2, 2026
@suleimansh suleimansh merged commit aa1925f into main Jul 2, 2026
2 checks passed
@suleimansh suleimansh deleted the feat/code-overview branch July 2, 2026 17:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request priority: low Nice to have / latent

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Scale mode — maintain CODE-OVERVIEW.md for large-codebase navigation

1 participant