Skip to content

Capability 003: Content Structure

Status: Accepted

Context

A generated repository organizes its specs by capability, not by document type (mission statement; target picture, sections Capability Specification, Manual Test, and Generated Repository). This capability defines which spec and test documents the modules specs, domain-model, bdd, and manual-test generate, where they live, which templates they carry, and where a generated repository refers to the guidelines. It builds on the modules of capability 002.

References

Details

Files per module, relative to the artifact directory, or to the repository root where marked:

File Module Owner Content
specs/index.md specs Developer Entry point: links to the mission statement, capabilities/, functional_design/, technical_design/
specs/mission_statement.md specs Developer Single repository and mono-repository root only: what the system is and for whom, then ## Principles
specs/capabilities/README.md specs Generator Capability Specification template with its guidance; for requirements: external see capability 010
specs/inputs/README.md specs Generator What an Input Document is (capability 010)
specs/functional_design/glossary.md specs Developer Empty term table
specs/technical_design/system_context.md specs Developer Context diagram skeleton
specs/technical_design/ADRs/README.md specs Generator ADR template of the Documentation Mode (capability 010) and when to write an ADR
specs/technical_design/APIs/provided/README.md, .../consumed/README.md specs Generator Where interface descriptions go, including *.path.txt
specs/functional_design/domain_model.md domain-model Developer Domain model skeleton
test/bdd/features/ bdd Developer Feature files; a profile whose sample code has a BDD harness gets the feature that exercises it, e.g. liveness.feature for a service's health endpoint
test/manual/README.md manual-test Generator Manual test template
docs/README.md specs Generator What belongs in docs/ (capability 010)

Repository root of a mono-repository:

File Module Owner Content
specs/index.md specs Developer Entry point: links to the mission statement, the artifacts, and the shared interfaces
specs/mission_statement.md specs Developer As for a single repository
specs/technical_design/ADRs/README.md specs Generator As for an artifact; for cross-artifact decisions
specs/technical_design/APIs/README.md specs Generator Where interfaces shared by several artifacts go, e.g. a DBC file
specs/inputs/README.md specs Generator As for an artifact
docs/README.md specs Generator As for an artifact

Functional Requirements

  1. The modules generate the files listed in Details and those of capability 010. They generate no other file below specs/, docs/, or test/manual/.
  2. No module generates specs/requirements/, specs/functional_design/features/, a Capability Specification, an ADR, or a Derived Document.
  3. With requirements: repo, specs/capabilities/README.md contains the template of the target picture, section Capability Specification: every section in order, the content each section holds, None. for a section without content, and the guidance the template carries.
  4. test/manual/README.md contains the template of the target picture, section Manual Test, and states that test records do not belong in the file.
  5. An artifact of a mono-repository has no specs/mission_statement.md.
  6. The README.md of each APIs/ directory names both ways to provide an interface: the file itself, or a *.path.txt holding the path to a shared interface at the repository root.
  7. Only CLAUDE.md and .github/copilot-instructions.md name where the guidelines are: guidelines/ with module guidelines, otherwise the generator's docs site. No other generated file contains a path to a guideline; code, configuration, and build files do not refer to a guideline at all, and the assistants' skills, agents, and commands name it by its topic only.
  8. The docs site of a mono-repository shows each file below the root specs/ exactly once.
  9. The docs site of a mono-repository builds with mkdocs build --strict although an artifact's specs link files below the root specs/ by their path in the repository.

Non-Functional Requirements

None.

Technical Requirements

None.

Error Handling

None.

Out of Scope

  • Content that a deselected module leaves in the files of other modules, such as links, Makefile targets, and CI jobs
  • The content of CLAUDE.md beyond the guideline reference, and the rules in .claude/
  • The generator's docs site
  • Migrating the specs of a repository generated with the previous approach

Acceptance Criteria

  1. Go service with default modules, repo update: every file of the first table exists, except test/manual/README.md; specs/ holds no other file.
  2. Same repository: no specs/requirements/, business_rules.md, use_cases/, specs/functional_design/features/, and specs/technical_design/ADRs/ holds README.md only.
  3. specs/capabilities/README.md names every section of the target picture in order and contains None..
  4. KiCad electronics with default modules: test/manual/README.md contains the sections Scope, Safety, Equipment, Setup, Preconditions, Procedure; no test/bdd/.
  5. Mono-repository with the artifacts planner and bridge: specs/mission_statement.md exists at the root, bridge/specs/mission_statement.md does not.
  6. Same repository: specs/technical_design/APIs/README.md exists at the root; bridge/specs/technical_design/APIs/provided/README.md contains .path.txt.
  7. Go service with default modules and both assistants: no generated file except CLAUDE.md and .github/copilot-instructions.md contains guidelines/; both name the generator's docs site.
  8. Same with module guidelines: CLAUDE.md names guidelines/.
  9. Mono-repository with the artifacts planner and bridge, bridge/specs/index.md linking ../../specs/mission_statement.md, docs site built with mkdocs build --strict: succeeds, and the mission statement appears once.

Decisions

  1. A template lives as README.md in the directory it applies to. The developer and the assistant find it where they write the next file, and the docs site shows it as the directory's index page. Consequence: repo update overwrites these files; notes of the developer belong in another file.
  2. The repository starts without a sample Capability Specification or ADR, and without a feature file unrelated to its sample code. A sample gets edited instead of written from the template and leaves traces of an unrelated example. Consequence: specs/capabilities/ and specs/technical_design/ADRs/ hold their template only until the developer writes the first document.
  3. One mission statement per repository. In a mono-repository, the artifacts serve one system; a mission statement per artifact would repeat it. Consequence: the Context of an artifact's Capability Specification links a file outside the artifact directory.
  4. Only the assistants' entry files say where the guidelines are. Generated code, configuration, and documents are expected to follow the guidelines; a reference in each of them adds nothing and dangles once a guideline moves. The assistants' skills and agents still need to know which guideline applies, so they name its topic. Consequence: a reader of a generated file does not learn from it which guideline shaped it.
  5. A link from an artifact to the root specs/ follows the repository, not the docs site. Assistants and developers read the repository, where the relative path works; the combined docs site publishes the root specs/ and each artifact under paths of its own. The docs site reports a link target it cannot find as information instead of a warning. Consequence: such a link leads to a missing page in the docs site, whose navigation still reaches the target; a mistyped link inside an artifact no longer fails the strict build either.