[architecture] No feature-based directory structure or README.md files per AGENTS.md #673

New issue

Closed

opened 2026-06-02 23:40:24 +02:00 by sleepy · 1 comment

sleepy commented

2026-06-02 23:40:24 +02:00

Owner

Missing README.md in feature directories

AGENTS.md rule: "Every feature directory MUST contain a README.md with: what it owns, what it does NOT own, key entry points, external dependencies, test locations."

The entire src/ directory is flat — all 90+ Python files live in src/ with no feature-based organization and no README.md anywhere. Specifically:

src/ has no README.md
No sub-directories exist for feature grouping
The tool system (agent_tools.py, tool_*.py, agent_loop.py, agent_runs.py) has no README.md

Impact

New developers (or AI agents) cannot understand the module ownership boundary
No documented entry points or dependency graph
Unclear which files form a coherent feature vs. standalone utilities

Suggested fix

At minimum, add a src/README.md that documents:

The tool system feature (which files own it, entry points, internal data flow)
The agent loop feature
How they relate to other features (database, routes, etc.)

Then, when the files are refactored into feature directories per the split issues (#664-#669), each directory gets its own README.md.

## Missing README.md in feature directories AGENTS.md rule: _"Every feature directory MUST contain a `README.md` with: what it owns, what it does NOT own, key entry points, external dependencies, test locations."_ The entire `src/` directory is flat — all 90+ Python files live in `src/` with no feature-based organization and **no README.md anywhere**. Specifically: - `src/` has no README.md - No sub-directories exist for feature grouping - The tool system (agent_tools.py, tool_*.py, agent_loop.py, agent_runs.py) has no README.md ### Impact - New developers (or AI agents) cannot understand the module ownership boundary - No documented entry points or dependency graph - Unclear which files form a coherent feature vs. standalone utilities ### Suggested fix At minimum, add a `src/README.md` that documents: - The tool system feature (which files own it, entry points, internal data flow) - The agent loop feature - How they relate to other features (database, routes, etc.) Then, when the files are refactored into feature directories per the split issues (#664-#669), each directory gets its own README.md.

sleepy added the

enhancement

label

2026-06-02 23:40:24 +02:00

sleepy referenced this issue

2026-06-03 00:29:47 +02:00

[search/research/infrastructure] Missing README.md in services/search/, src/search/, services/research/ — violates AGENTS.md feature directory requirement #782

sleepy referenced this issue from a commit

2026-06-04 04:37:44 +02:00

[docs] Add README.md to feature directories (closes #673)

sleepy closed this issue

2026-06-04 04:39:48 +02:00