Skip to content

Capability 005: Generator Documentation

Status: Accepted

Context

A generated repository starts with an empty ADR directory for the developer's own decisions. Why its structure, build, and pipeline look the way they do, and, without module guidelines, the guidelines it follows, are documented once for all repositories on the generator's docs site (mission statement; target picture, sections Rules, Guidelines, and Tools, and Generator Docs Site). This capability defines what that site holds, so that every link from a generated repository finds its target, and applies the generated layout to the generator's own repository.

References

Details

Pages of the docs site:

Page Content Source
Usage Commands and every field of .repo.yaml, with the modules and their defaults specs/usage.md, linking cli.yaml and repo-config.schema.json
Workflow The development workflow from specification to implementation specs/functional_design/workflow.md
Templates The Capability Specification, ADR, and manual test templates specs/document_templates/, which includes the generator's template files unchanged
Profiles One page per profile: structure, build, pipeline, and the rationale for each specs/technical_design/profiles/<language>-<type>.md, which includes the parts shared by its language and by its project type
Assistant support What Claude Code and GitHub Copilot each receive, and Copilot's limits specs/technical_design/assistants.md
Guidelines An overview of which guideline applies to which profile and which files its rule loads for, linking every guideline of every profile specs/guidelines/index.md, generated from the generator's registry; the guidelines from guidelines/ at the generator's repository root

The site always holds every guideline. A generated repository holds a copy of its profile's guidelines only with module guidelines; otherwise its CLAUDE.md and Copilot instructions link to the site's guidelines overview, /guidelines/ on the generator's GitLab Pages site. The address is set at build time from the Makefile variable DOCS_SITE_URL, in GitLab CI from CI_PAGES_URL. The rules in .claude/rules/ and .github/instructions/ are generated either way.

The generator's own repository follows the layout of a generated Go tool with modules scaffold, ci, specs, bdd, ai, and guidelines, with one exception: its guidelines/ holds every guideline of every profile, since the docs site publishes it.

Functional Requirements

  1. The docs site holds the pages of Details; a link from a generated repository to the generator's guidelines reaches the guideline it names.
  2. The site's guidelines are every guideline the generator generates for any profile, each once.
  3. A guideline reads the same for every profile and repository type; content that holds for one language or project type only belongs to that language's or project type's guideline.
  4. The templates page shows the generator's current templates, not copies that can drift from them.
  5. The generator's own .claude/rules/ and CLAUDE.md are what the generator generates for its own profile; no other rule file exists. Its guidelines/ holds every guideline of every profile, as the generator generates it.

Non-Functional Requirements

  1. The generator's own CLAUDE.md stays within the word budget of capability 004.

Technical Requirements

None.

Error Handling

None.

Out of Scope

  • The content of the workflow page; the developer writes it
  • Publishing a site per release; the site shows the latest release only
  • Comments in the generator's Go code

Acceptance Criteria

  1. Docs site built with mkdocs build --strict: succeeds; it holds the pages of Details.
  2. The guidelines of the generator's docs site include cpp_coding.md, java_coding.md, typescript_coding.md, schematic_design.md, and go_coding.md, and as many files as the generator has guideline templates.
  3. Every guideline, generated for every profile in a single repository and as a mono-repository artifact: identical content for every profile.
  4. make selfcheck: no drift for guidelines/, .claude/rules/, and .github/instructions/, and no file in the generator's .claude/rules/ that the generator does not generate.
  5. The generator's CLAUDE.md: at most 400 words.
  6. The templates page contains the section headings of specs/capabilities/README.md as the generator generates it.

Decisions

  1. One site for all profiles, showing the latest release. A generated repository links to one address; versioned sites would need a link per version. Consequence: a repository generated by an older release reads newer guidelines than its rules were extracted from, until its next repo update (target picture, Decision 7).
  2. Guidelines have no profile-specific variants. A site that shows each guideline once cannot show variants; profile-specific content belongs to the guideline of the language or project type. Consequence: testing.md, ci_cd.md, cli_tool.md, and library_design.md lose their conditional sections; their content moves to the guideline it concerns or is phrased for all profiles.
  3. The site includes templates instead of copying them. The template files are the source of what a generated repository receives; a copy drifts. Consequence: the site's build reads files below internal/templating/, and a template that uses template syntax shows it.
  4. The generator's guidelines move to guidelines/ at the repository root. The generator applies the generated layout to itself (target picture, Decision 11), and module guidelines puts them there (capability 002, Decision 6). Consequence: the site takes them in like a generated single repository does, and the address of the site's guidelines stays /guidelines/.