--- id: canon-project-repository-flavor type: standard title: "Project Repository Flavor (prj-) v0.1" domain: custodian status: active version: "0.1" 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-` | | 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- 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: `, 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--.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/-WP-NNNN-.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-` 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