The additional architecture skill adds one strict lens: do not create more files
unless the new module becomes deeper. A deep module gives callers more leverage
through a smaller interface and gives maintainers better locality.
Use these words consistently:
- Module: a thing with an interface and implementation.
- Interface: everything callers must know to use the module correctly.
- Implementation: the code hidden behind the interface.
- Depth: leverage at the interface.
- Seam: where behavior can change without editing the caller.
- Adapter: a concrete implementation plugged into a seam.
- Leverage: capability gained per unit of interface learned.
- Locality: change and verification concentrated in one place.
This matters because the current extension refactor created many shallow
modules:
vyasa/extensions_builtin/mermaid/__init__.py is shallow because its
interface is metadata plus direct runtime mutation, while the implementation
still lives in Markdown.
vyasa/extensions_builtin/default_layout.py is shallow because its
configure() returns nothing and core still assigns the layout renderer.
vyasa/theme_extensions/*.py is shallow because each module repeats a
two-line adapter with no real extension seam.
vyasa/extensions_builtin/tasks/__init__.py is shallow because it imports
_render_tasks_block and does not own parsing, storage, JavaScript, CSS, or
page behavior.
vyasa/extensions.py is useful but not yet deep because callers still need to
know runtime field names and mutate them directly.