the-custodian/canon/standards/project-repository-flavor_v0.1.md

---
id: canon-project-repository-flavor
type: standard
title: "Project Repository Flavor (prj-) v0.1"
domain: custodian
status: accepted
version: "0.1"
owner: the-custodian
revision: "accepted-1"
last_reviewed: "2026-08-31"
review_interval: 6m
created: "2026-08-09"
updated: "2026-08-09"
scope: fleet
related_workplans:
  - SHR-WP-0001
  - CUST-WP-0050
related_adrs:
  - ADR-001
  - ADR-005
supersedes: none
closes:
  - "ADR-005 deferred naming convention"
  - "CUST-WP-0050 open question D1a (naming + archival trigger details)"
---

# Project Repository Flavor (`prj-`) v0.1

## Purpose

Define the durable **project repository** flavor used for complex
cross-repository efforts: naming, required files, authority boundary,
lifecycle, residual handoff, and archive procedure.

This standard implements and completes **ADR-005** (*Cross-Repo Workplans Live
in Dedicated Project Repos*). It does **not** replace the Repo Classification
Standard: project repositories still use `category: project` in
`.repo-classification.yaml`.

## When to use a project repository

Create a project repository when **all** of the following hold:

1. The work coordinates change across **two or more** functional repositories.
2. Binding the coordination workplan to any single product/tooling repo would
   misrepresent ownership or pollute that repo's history.
3. The effort has a **bounded outcome** with explicit success and retirement
   conditions (not an open-ended product roadmap).

Do **not** create a project repository for:

- single-repo workplans;
- small cross-cutting fixes that fit one lead repo's workplan plus dependency
  links;
- durable products, libraries, or services (those use `INTENT.md` and ordinary
  product/tooling/research categories);
- long-lived domain charters (those remain under `the-custodian/canon/projects/`).

## Naming

| Element | Convention |
| --- | --- |
| Git / local directory | `prj-<kebab-slug>` |
| Hub `repo` slug | same as directory name |
| Workplan prefix | short uppercase prefix derived from the project, ending in `-WP-` (example: `SHR-WP-` for State Hub Retirement) |
| Classification | `category: project` |

**Canonical prefix is `prj-`.** ADR-005's illustrative `proj-` form is
superseded for new repositories. Do not invent parallel prefixes (`project-`,
`xrepo-`, …).

Slug rules:

- lowercase kebab-case;
- outcome-oriented (`prj-state-hub-retirement`), not a random ticket id;
- stable for the life of the project (rename only with an explicit migration
  note in `history/`).

## Authority boundary

| Concern | Owner |
| --- | --- |
| Project goal, success gates, retirement conditions | project repo (`GOAL.md`) |
| Architecture decisions, sequencing, dependency map, migration ledger, risks, consolidated evidence | project repo |
| Cross-repo workplans that coordinate the effort | project repo (`workplans/`) |
| Production implementation, tests, deployables | **participating functional repositories** |
| Per-repo implementation workplans and local evidence | each functional repository |
| Durable post-project standards and ADRs | permanent homes (`the-custodian` canon, or the owning product/tooling repo) |

**Hard rules:**

1. Project repositories **MUST NOT** host production implementation code for the
   systems being changed.
2. Project workplans **link** child workplans by stable ID; they **MUST NOT**
   copy or replace child task lists.
3. The hub remains a read/index layer; work records originate as files
   (ADR-001).
4. Results of the project live primarily in the modified functional repositories
   and promoted canon. The project repo is coordination + provenance.

## Required files

At registration / first meaningful commit:

| Path | Required | Role |
| --- | --- | --- |
| `GOAL.md` | **yes** | Outcome, invariants, success gates, project retirement conditions. **Replaces `INTENT.md` for this flavor.** |
| `SCOPE.md` | **yes** | Project authority, participating repos, in/out of scope, work-record rule. |
| `README.md` | **yes** | Short entry point linking `GOAL.md`, `SCOPE.md`, genesis/history, active workplans. |
| `AGENTS.md` | **yes** | Agent session protocol for this project (orient → work → close; hub integration). |
| `.repo-classification.yaml` | **yes** | `category: project` plus domain / capability tags for the *effort*. |
| `workplans/` | **yes** | At least one foundation workplan; prefix unique to the project. |
| `history/` | recommended | Genesis and significant milestones (why the project exists). |
| `WORK-RECORDS.md` | generated | Hub index; do not hand-edit. |
| `.custodian-brief.md` | generated | Offline orientation brief. |

### `GOAL.md` (not `INTENT.md`)

Durable product and tooling repositories explain **why they exist** with
`INTENT.md`. Project repositories are temporary and outcome-bounded; they use
**`GOAL.md`** instead.

`GOAL.md` MUST include:

1. **Outcome** — what success looks like in one short section.
2. **Invariants** — rules that must hold during the project.
3. **Success gates** — checkable conditions for “goal achieved”.
4. **Project retirement** — conditions under which *this repository* may be
   archived (usually: gates met + residuals handed off + durable decisions
   promoted).

Recommended frontmatter:

```yaml
---
repo: prj-<slug>
repo_flavor: project
project_status: draft | active | completed | archived
started: "YYYY-MM-DD"
reviewed: "YYYY-MM-DD"
---
```

**Anti-pattern:** shipping both `INTENT.md` and `GOAL.md` in a `prj-` repo.
If a durable intent emerges, promote it into a permanent repository's
`INTENT.md` (or canon) and keep the project goal as the temporary outcome
document.

### Relation to durable `INTENT.md`

| Repository kind | Purpose document |
| --- | --- |
| product / tooling / research / business / experimental | `INTENT.md` |
| **project (`prj-`)** | **`GOAL.md` only** |

Tooling that scaffolds repositories (e.g. `statehub register`) MUST treat
`GOAL.md` + `repo_flavor: project` as sufficient purpose documentation for
`prj-` repos and MUST NOT require inventing an `INTENT.md` that pretends the
project is a permanent product.

## Lifecycle

```
draft → active → completed → archived
```

| Status | Meaning | Repo / hub signals |
| --- | --- | --- |
| `draft` | Convention and foundation still forming; may not yet be registered | `project_status: draft`; workplans often `proposed` / `ready` |
| `active` | Coordination and child implementation in progress | `project_status: active`; at least one workplan `active` or `ready` |
| `completed` | All success gates have accepted evidence; residuals have live owners outside this repo | `project_status: completed`; project workplans `finished` or cancelled with rationale |
| `archived` | Repository is read-only provenance | forge archive flag; hub repo/workplan `archived`; no normal writes |

Promotion rules:

- `draft → active` when `GOAL.md` / `SCOPE.md` are reviewable and the foundation
  workplan is `ready` or `active`.
- `active → completed` only when **every** `GOAL.md` success gate has accepted
  evidence **and** residuals are live work records elsewhere (see below).
- `completed → archived` after the completion record is written, durable
  decisions are promoted, and a final consistency/link check passes.

## Residuals before completion

Actionable leftovers MUST NOT live only in finished workplan prose or
`SCOPE.md`. Before any project workplan is set to `finished`, and again before
`project_status: completed`, each residual becomes a **live work record**
outside the closing narrative:

- intake with `origin: residual` + `origin_ref: <WP-id>`, or
- a next workplan / decision / engagement / register-entry in a permanent repo.

Canon: `work-record-types_v0.1.md` § Residuals. Fleet residual listing is a
State Hub concern, not a project-local queue file.

## Completion record

Before archival, the project repository MUST contain a completion record
(recommended path: `history/YYYY-MM-DD-completion.md`) that lists:

1. deployed or merged revisions that realize the outcome;
2. every participating repository touched, with links to merged PRs/commits or
   child workplan IDs;
3. promoted durable artefacts (canon paths, ADRs, standards);
4. migration and retirement evidence pointers (counts, cutover windows, backups);
5. residual work-record IDs and their owning repos;
6. rollback expiry or remaining operational obligations, if any.

Without this record, do not archive.

## Archive procedure

1. Verify all success gates and retirement conditions in `GOAL.md`.
2. Confirm residuals are live and owned outside this repository.
3. Promote remaining durable decisions/standards to permanent homes; leave
   pointers from the project repo.
4. Finish or cancel project workplans; move finished files to
   `workplans/archived/YYMMDD-<id>-<slug>.md` per workplan convention.
5. Write the completion record.
6. Set `project_status: archived` in `GOAL.md` frontmatter.
7. Run `statehub fix-consistency` (or equivalent) so the hub reflects finished
   workplans and the archived status.
8. Archive the repository in the forge (read-only); do **not** delete it.
9. Optionally mark the hub registration archived / read-only.

**Archive means read-only provenance, never deletion.** Historical evidence and
coordination narrative remain queryable.

## Workplan and agent conventions

- Workplan files: `workplans/<PREFIX>-WP-NNNN-<slug>.md` with fleet status
  vocabulary (`proposed` … `archived`).
- Session start order for agents: `GOAL.md` → `SCOPE.md` → genesis/history →
  active workplans (see project `AGENTS.md`).
- Progress and task status follow ordinary State Hub / fix-consistency rules.
- Ad-hoc low-risk fixes may use `workplans/ADHOC-YYYY-MM-DD.md` with canonical
  id `{PREFIX}-WP-ADHOC-YYYY-MM-DD`; anything multi-step belongs in a normal
  workplan.

## Minimal layout example

```text
prj-example-cutover/
  GOAL.md
  SCOPE.md
  README.md
  AGENTS.md
  .repo-classification.yaml
  history/
    2026-08-09-genesis.md
  workplans/
    EX-WP-0001-foundation.md
```

## Reference instance

The first repository under this standard is
`prj-state-hub-retirement` (State Hub retirement / hub-core consolidation).
Use it as the structural reference when scaffolding later `prj-` repos; do not
copy its domain-specific content.

## Conformance checklist

A repository conforms to the `prj-` flavor when:

- [ ] Named `prj-<slug>` and classified `category: project`.
- [ ] Has `GOAL.md` with outcome, invariants, success gates, and retirement.
- [ ] Has no durable-product `INTENT.md` (or documents an explicit temporary
      exception during migration of a mis-scaffolded repo).
- [ ] Has `SCOPE.md`, `README.md`, `AGENTS.md`, and `.repo-classification.yaml`.
- [ ] Hosts coordination workplans only; implementation lives in child repos.
- [ ] Links child workplans by ID rather than duplicating their tasks.
- [ ] Defines archive/completion discipline consistent with this standard.
- [ ] On completion, writes a completion record and archives read-only.

## Related

- ADR-001 — Workplans and Work Items Are Repository Artefacts
- ADR-005 — Cross-Repo Workplans Live in Dedicated Project Repos
- `repo-classification-standard_v1.0.md` — `category: project`
- `work-record-types_v0.1.md` — residuals and work-record kinds
- `workplan-terminology-fleet_v0.1.md` — workplan vocabulary