Skip to content

Capability 007: Artifact List

Status: Accepted

Context

The root of a mono-repository lists its artifacts in developer-owned files: CLAUDE.md for the assistant, specs/index.md for the docs site, and README.md. repo update never overwrites a developer-owned file (capability 002), so a new artifact had to be added to each list by hand. This capability lets the generator maintain the lists in marked sections of these files and removes the list from README.md.

References

Details

A generated section is the text between two marker lines in a developer-owned file:

<!-- BEGIN: <name> -->
<!-- END: <name> -->

Generated sections at the root of a mono-repository:

File Module Section Content per artifact, in the order of artifacts
CLAUDE.md ai, assistant claude artifact-list Bullet: title linked to its directory, description, and its CLAUDE.md
specs/index.md specs artifact-version-table Table row: title linked to its directory, — as version, release date, and commit

The pipeline that builds the docs site fills the version table from the release tags, in its own working copy only.

Functional Requirements

  1. repo update rewrites each generated section on every run and leaves the rest of the file unchanged.
  2. A file that lacks one of the markers of its section stays unchanged.
  3. repo check lists a file whose generated section differs from what repo update would write.
  4. A change confined to generated sections is no reason for a review: line (capability 002, Functional Requirement 11).
  5. The root README.md of a mono-repository names no artifact; it links specs/index.md as the overview of the artifacts.

Non-Functional Requirements

None.

Technical Requirements

None.

Error Handling

  1. A file with a BEGIN marker but no matching END marker after it is left unchanged, and repo update prints a review: line with its path.

Out of Scope

  • Generated sections in an artifact's own files or in a single repository
  • Generated sections other than those in Details
  • Converting a README.md generated before this capability; it keeps its list until the developer removes it

Acceptance Criteria

  1. Mono-repository with the artifacts planner and bridge, generated; CLAUDE.md changed outside its generated section; all committed; artifact tracker added, repo update: CLAUDE.md keeps the change and lists tracker in its generated section; specs/index.md has a row for tracker; standard output contains no review: line.
  2. Same repository, the markers removed from CLAUDE.md and committed, artifact tracker added, repo update: CLAUDE.md is unchanged.
  3. Same repository, the generated section of CLAUDE.md changed and committed, repo check: lists CLAUDE.md and exits non-zero.
  4. Same repository, the END marker removed from CLAUDE.md and committed, repo update: CLAUDE.md is unchanged, and review: CLAUDE.md is printed.
  5. Mono-repository with the artifacts planner and bridge, generated: README.md contains neither planner nor bridge and links specs/index.md.

Decisions

  1. The generator maintains a marked section instead of taking over the whole file. CLAUDE.md and specs/index.md carry project-specific text that the generator cannot know. Consequence: the developer edits the list only through .repo.yaml; a hand edit inside the section is lost on the next run.
  2. README.md links the overview instead of listing the artifacts. One list fewer to keep in step; the docs site shows the artifacts with their versions. Consequence: a reader of README.md needs one more click to see the artifacts.
  3. Missing markers mean the developer opted out. Restoring them would overwrite a deliberate decision, as regenerating a deleted file would (capability 002, Decision 1).