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

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

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:

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

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

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