Skip to content

Derive the agent architecture map from the live workspace #749

Description

@forkwright

Finding

Harmonia's primary agent-orientation surface claims _llm/architecture.toml is the full crate map, but that file currently lists only 8 crates while the Cargo workspace contains 21 members. Surrounding agent/contributor prose independently restates an older count of 19 crates.

The architecture view is explicitly generated = false, so a fast-changing structural fact is maintained by hand in several places and has already drifted in two different directions: README knows there are 21 crates, the instructions say 19, and the supposed full map names 8.

Verified against main 65644113e47814c87eaba14a6f322820974b8780.

Evidence

  • Root Cargo.toml lists 21 workspace members under [workspace].members.
  • AGENTS.md:35-38 says "19 crates under crates/" and directs agents to _llm/architecture.toml "for the full map." AGENTS.md:57 repeats "all 19 crates."
  • _llm/README.md:5-16 describes a 19-crate workspace and says architecture.toml contains "19 crates: layer, purpose, dependency direction."
  • _llm/architecture.toml declares generated = false and contains only 8 [[architecture.crates]] entries: aggelmata, apotheke, paroche, kathodos, ergasia, syntaxis, akouo-core, and archon.
  • CONTRIBUTING.md:57 also carries the 19-crate count, while README's current architecture section reports 21 workspace crates.

No open issue currently owns this architecture-view drift.

Why this matters

These files exist specifically so agents do not need to reconstruct the workspace from scratch. An incomplete map sends work toward the wrong owner or makes whole subsystems—auth, curation, integrations, requests, search, renderer transport, subtitles, mobile, conversion—effectively invisible during cold-start orientation.

Because crate membership is already declared mechanically by Cargo, maintaining a separate numeric count and hand-curated full inventory is unnecessary synchronization work. The view can contain judgment such as roles/layers, but membership and paths should be derived.

Desired correction

Make workspace membership/path inventory derive from Cargo metadata or the root manifest, then attach maintained role/layer annotations to that derived set. Generate or mechanically check _llm/architecture.toml so every workspace member is represented exactly once, and remove volatile numeric crate counts from prose unless they are generated.

If a deliberately partial architecture view is preferable, rename and document it as partial instead of calling it the full map; the current contract is what makes the missing 13 entries a defect.

Done when:

  • every Cargo workspace member is represented exactly once in the agent architecture inventory, or the file explicitly declares a narrower scope;
  • adding/removing/renaming a workspace member without updating the architecture view fails a check or regenerates it;
  • AGENTS, CONTRIBUTING, _llm/README, and README no longer maintain contradictory crate counts; and
  • role/layer annotations remain human-owned judgment while crate identity/path membership is derived.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    refactorCode quality and architecture improvementstech-debtTechnical debt and cleanup

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions