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

id	type	title	domain	status	version	owner	revision	last_reviewed	review_interval	created	updated	scope	related_workplans	related_adrs	supersedes	closes
canon-project-repository-flavor	standard	Project Repository Flavor (prj-) v0.1	custodian	accepted	0.1	the-custodian	accepted-1	2026-08-31	6m	2026-08-09	2026-08-09	fleet	SHR-WP-0001 CUST-WP-0050	ADR-001 ADR-005	none	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:

---
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

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