Thread · HN Continuity

Instead of the proposed /src/md convention:

  src&#x2F;
    md&#x2F;
      README.md          # index of all md, entry point for agents
      TODO.md            # a list of general TODOs open for this module
      OVERVIEW.md        # a technical overview of this module
      features&#x2F;FEATURE_1.md       # a set of feature-specific documents
      data&#x2F;DATAMODEL_1.md         # descriptions of data models in the module
      api&#x2F;API_1.md                # descriptions of APIs the module provides
      infrastructure&#x2F;INFRASTRUCTURE_1.md   # descriptions of infrastructure used by the module

What if we standardized on README.md in each subdirectory alongside the code?

  src&#x2F;
    README.md    # entry point for humans and agents
    TODO.md      # list of general TODOs open for this module
    INFRA.md     # descriptions of infrastructure used by the module
    api&#x2F;
      README.md  # descriptions of APIs the module provides
    models&#x2F;
      README.md  # descriptions of data models in this module

README.md in each subdirectory seems to align better with OP’s objective “that Markdown should be checked in to /src, next to the code it produces”. It is also a convention already in use in many code repositories.