# Code repository

URL: https://tfw.how/tool-classes/code-repository/
Description: A code repository holds a topic's versioned implementation. Every repository of a topic has a name that starts with the lowercase topic code and a hyphen.

Code repository is the [tool class](/glossary/#tool-class) for versioned implementation: source code, configuration, infrastructure definitions, schemas, tests, and the history of changes to them. An example of a product in this class is GitHub.

## Role in TFW

The code repository is the [source of truth](/glossary/#source-of-truth) for versioned implementation and its change history: source code, configuration, infrastructure definitions, schemas, tests, executable runbooks, technical decision records that are kept next to the code, and instructions for AI agents that work in the repository. A change to one of these is made in the repository, through the review process the repository uses.

The code repository is not the source of truth for business approvals, task status, long explanations of how the topic works, chat transcripts, or credentials. Task status stays in [task management](/tool-classes/task-management/), and a pull request or change links to the task. Broad explanations and procedures for people stay in the [knowledge base](/tool-classes/knowledge-base/). Credentials stay in a dedicated secrets manager and are never committed to a repository.

## One topic's surface

The example topic Example Co Operations (topic code EXOP) has a code repository surface only if the topic has code. A topic can have more than one repository. Together, the repositories whose names start with the topic's prefix are the topic's code repository surface.

- **Container.** One or more repositories in the organization's account, not in a personal account.
- **Name.** Every repository name starts with the repository prefix: the lowercase topic code and a hyphen, `exop-`. The rest of the name states the purpose of the repository, for example `exop-website` or `exop-inventory-sync`.
- **Description.** One sentence that names the topic code and the purpose, for example "EXOP Example Co Operations: the public website."
- **Agent instructions.** A short file at the root of the repository that tells people and AI agents which topic the repository belongs to, how to build and test it, and where the topic's other records are. It links to those records; it does not copy them.
- **Permissions.** Access follows the topic's [access boundary](/glossary/#access-boundary), granted through a team or group where the product supports it.
- **Maintainer.** Each repository has one named [maintainer](/glossary/#maintainer) who keeps its name, description, settings, and permissions correct.

## Rules

- Every repository of the topic has a name that starts with the lowercase topic code and a hyphen.
- Each repository belongs to exactly one topic. A repository that serves several topics belongs to the topic that is accountable for it, and links to the others.
- List each repository in the [topic profile](/glossary/#topic-profile).
- Link each change to the task or decision it implements. Record task status in task management, not only in the repository.
- Store no credentials, keys, or tokens in a repository. Store a reference to the secret instead.
- Keep the instructions for AI agents short and specific to the repository. Link to the topic's records instead of copying them.
- Grant access through a team or group for the topic, not person by person.

## Common mistakes

- **Repositories without the prefix.** A repository named only for its purpose, such as `website`, cannot be matched to a topic. Rename it with the prefix, or record the old name as an [alias](/glossary/#alias) if it cannot change.
- **Repositories in personal accounts.** Code that matters to the topic is lost or locked when that person leaves.
- **The repository as the task tracker.** Issues in the repository and tasks in task management stop matching each other. Use one place for task status and link to it from the other.
- **Credentials in the repository.** A committed secret stays in the change history even after the file is changed.
- **Decisions only in a pull request discussion.** A pull request discussion is [conversation](/glossary/#conversation). Record a decision that must last in a decision record and link to it.

## Tools

This site does not yet have a tool page for this class. Products in this class follow the same rules.