# Project Packs
A project pack is the reusable project-specific layer of this RFC workflow.
The repo-wide workflow defines neutral mechanics in `core/`, repo-level prompts, reviewer roles, and toolchain behavior. A pack under `projects/<name>/` adds the subject-matter context those neutral mechanics need for one concrete RFC suite or document family: source corpus boundaries, authoritative references, terminology ownership, draft defaults, and per-document drafting briefs.
Within `projects/`, keep two surfaces distinct:
- `projects/<name>/` holds reusable project-pack inputs that define what the workflow should run against.
- `projects/runs/<run-id>/` holds per-run artifacts: generated drafts, evidence packets, gate/status records, and optional logs for one execution.
In short:
- `core/` and the top-level workflow say **how** the workflow runs.
- `projects/<name>/` says **what this project is about** and **which source material governs it**.
- `projects/runs/<run-id>/` says **what happened during one concrete run**.
## How `projects/<name>/` fits into the workflow
A harness or human operator should be able to load a project pack before drafting and get the minimum project context needed to work correctly:
1. `suite-brief.md` sets the suite charter, document list, scope boundaries, and cross-document rules.
2. `corpus-brief.md` defines the authoritative source corpus, informative material, observed-byte or runtime evidence surfaces, and section-to-source routing.
3. `references.md` records the curated reference pool plus terminology and dependency ownership.
4. `draft-metadata.md` provides shared draft/front-matter defaults.
5. `briefs/*.md` add document-specific scope, required sections, exclusions, and edge cases.
6. `examples/` seeds example capture or anomaly checks when the suite benefits from them.
7. `references/` can hold local staged support material for the people doing the work, but that staged material stays support-only.
That layering lets the workflow stay reusable while each pack remains small, explicit, and project-authored.
## Reserved `projects/runs/` area
`projects/runs/` is reserved for run-owned artifact trees. It is not a project pack and must not be selected as `projects/<selected-project>/`.
Use one dedicated subdirectory per run:
```text
projects/runs/<run-id>/
├── public/
├── evidence/
├── gates/
└── logs/ # optional
```
Keep reusable inputs in `projects/<name>/` and keep generated or intermediate run output in the matching `projects/runs/<run-id>/` tree.
## Recommended pack layout
A complete pack will usually look like this:
```text
projects/
├── runs/
│ └── <run-id>/
│ ├── public/
│ ├── evidence/
│ ├── gates/
│ └── logs/ # optional
└── <name>/
├── README.md
├── suite-brief.md
├── corpus-brief.md
├── references.md
├── draft-metadata.md
├── briefs/
│ ├── <doc-a>.md
│ └── <doc-b>.md
├── examples/
│ └── <seed-or-example-file>.md
└── references/
├── README.md
└── <ignored staged support files>
```
Not every pack needs the same number of briefs or example files, but the top-level documents should exist so the workflow has a stable place to find each kind of project context.
## What each pack file does
### `README.md`
Pack-local orientation. Explain the suite or document family, summarize the pack contents, and state any pack-specific boundaries that a new contributor should know before loading the detailed briefs.
### `corpus-brief.md`
The source-corpus contract.
Use it to answer:
- What implementation, specification, repository, archive, observed-byte corpus, or runtime surface is authoritative?
- What material is only informative?
- When sources disagree, which surface wins?
- Which source areas govern which draft sections?
- What evidence shapes are acceptable for normative claims?
This file should make it hard for a drafter to confuse orientation material with source authority.
### `references.md`
The curated authoritative reference, terminology, and dependency map for the pack.
Use it to record:
- the normative reference pool,
- the informative reference pool,
- internal document dependencies,
- terminology ownership,
- citation hygiene notes.
This file is canonical for the pack's references and vocabulary relationships. If a local staged note or copied excerpt disagrees with `references.md`, the staged file loses.
### `references/` staged support material
A local workbench for support-only material such as copied source excerpts, manifests, API snapshots, reference bundles, scrape output, or temporary comparison notes.
Important distinction:
- `references.md` is the **authoritative curated pack document**.
- `references/` is **staged support material for local work**.
Staged files can help a run, but they are not the canonical statement of project references, terminology, or scope. Keep them ignored rather than canonical whenever they are copied from elsewhere, bulky, transient, or only useful as local evidence-gathering aids.
### `suite-brief.md`
The suite charter.
Use it to define:
- intended RFC documents,
- implementability or interoperability goals,
- cross-document structure,
- suite-wide constraints,
- deliverable boundaries,
- editorial bias that applies across the suite.
If the pack covers one document instead of a suite, this file can still state the charter and non-goals for that single deliverable.
### `draft-metadata.md`
Shared front-matter and draft defaults.
Use it for items such as:
- title defaults,
- intended status or category,
- deliverable forms,
- abstract anchors,
- authorship/provenance boundaries,
- document-specific front-matter defaults.
Keep workflow-neutral mechanics out of this file. It should say what the project wants in draft metadata, not how a harness should build or render drafts.
### `briefs/*.md`
Document-specific drafting briefs.
Each file under `briefs/` should cover one target RFC or related deliverable and state:
- exact scope,
- required sections and capabilities,
- exclusions,
- cross-references it depends on,
- tricky edge cases or review traps,
- anything that must be preserved for clean-room implementability.
These briefs are where project context becomes concrete for one document.
### `examples/`
Optional example seeds, anomaly probes, observed-byte notes, or example-capture checklists.
Use this directory when the project benefits from explicit reminders about:
- examples that must come from implementation output,
- rendered-example traps,
- anomalies that require confirmation before promotion into public text,
- scenarios that reviewers should re-check.
Treat these files as review aids. They are not a substitute for the normative source corpus.
## Building project-specific reference and context material
A good pack does not merely list files. It explains which materials matter and why. The easiest way to get there is to build the pack in the following order.
### 1. Identify the authoritative source corpus
Decide what the workflow is actually specifying.
Examples:
- implementation source files,
- a reference repository or dataset,
- protocol traces or observed bytes,
- standards documents that define the canonical behavior,
- runtime inspection surfaces or official exported artifacts.
Name the authoritative corpus in `corpus-brief.md`, and be explicit about any boundary such as "implementation wins over lagging prose" or "spec text wins over convenience tooling output."
### 2. Collect normative and informative references separately
Do not blur references with equal weight.
- **Normative references** are required for a correct reading or interoperable implementation.
- **Informative references** help orientation, history, background, examples, or non-binding explanation.
Record both pools in `references.md`. Keep the list curated: include what the suite actually needs, not every adjacent document you found.
### 3. Map terminology ownership and document dependencies
If the pack covers multiple RFCs, decide which document owns each important concept.
Record in `references.md`:
- which document defines each core term,
- which documents depend on other documents,
- where cross-references should replace duplicated explanations.
This prevents three common failures: duplicated vocabulary, inconsistent definitions, and documents that quietly smuggle in dependencies they never name.
### 4. Stage support-only material under `references/`
When a project needs local working material beyond the canonical pack docs, place it under `references/`.
Typical staged items:
- copied source excerpts,
- manifests or sample payloads,
- reference snapshots,
- scrape/export results,
- temporary manifests of where evidence lives,
- local notes that help source scouting.
These files support the workflow; they do not define it. If a staged file becomes stable, reusable, and authoritative, promote its conclusions into `corpus-brief.md`, `references.md`, or another pack document rather than treating the staged file itself as the lasting source of truth.
### 5. Keep staged source files ignored rather than canonical
Copied source files, bulky exports, and local support bundles should normally be ignored from version control rather than checked in as the authoritative pack content.
Recommended practice:
- keep `references/README.md` checked in so the directory has a documented purpose,
- keep transient staged material under `references/`,
- ignore those staged files via a repo-level or pack-level ignore rule,
- promote only the stable conclusions into the canonical pack docs.
That keeps the repository small and the pack legible while still giving local authors a place to collect working evidence.
## Authoring guidance
- Keep pack docs source-agnostic enough to be reusable, but concrete enough that a drafter knows exactly where authority lives.
- Prefer explicit boundaries over implicit culture. Write down what is out of scope.
- Use the pack to document project knowledge, not harness behavior.
- If the pack covers multiple documents, centralize shared facts in the top-level pack docs and keep `briefs/*.md` focused on per-document differences.
- If a fact matters to more than one brief, put it in `suite-brief.md`, `corpus-brief.md`, `references.md`, or `draft-metadata.md` instead of duplicating it.
- Put generated drafts, evidence packets, gate/status files, and optional logs under `projects/runs/<run-id>/`, not inside the reusable pack.
## Using the scaffold prompt
`PROMPT-GENERATE-PROJECT-PACK.md` is the reusable harness prompt template for creating a new `projects/<name>/` skeleton. Fill in the project-specific inputs, ask your harness to scaffold the pack, then review the generated pack against this README:
- Is authority clearly separated from support-only staging?
- Do the top-level docs say what governs the project?
- Do the document briefs express scope and edge cases concretely?
- Does the pack leave `core/` and repo-wide workflow semantics alone?
If the answer is yes, the pack is ready to support drafting work.