Project Packs

A project pack is the 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.

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.

Do not use a pack to fork the workflow itself. A pack should supply project facts, not alternate controller semantics, alternate review stages, or harness-specific runner logic.

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.

Recommended pack layout

A complete pack will usually look like this:

projects/<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.

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.