# RFC Workflow
`rfc-workflow` is a reusable control pack for source-grounded RFC authoring.
It is designed to be **harness-neutral**. The repository defines the workflow, evidence discipline, review gates, and project-pack boundaries, but it does **not** ship runner-specific commands, plugins, or adapter files. A harness is expected to load the neutral assets and translate them into its own native execution primitives at runtime.
## What this repo is for
This repo packages the workflow pattern that was previously mixed together with one project's execution adapters.
The pattern has three stable ideas:
1. **Public RFC deliverables are separate from internal evidence artifacts.**
2. **Public claims enter the draft only after accepted evidence exists.**
3. **A run advances stage by stage, with gates, review lanes, recursive correction, and clean-room proof before final packaging.**
Those ideas are reusable across projects. The source corpus, references, document suite, and examples are not, so they live in project packs.
## Repository architecture
The repository is split into six surfaces.
### 1. Contract
- `workflow.contract.yaml`
- `schemas/workflow-contract.schema.json`
The contract is the canonical source of truth for:
- stage IDs and order,
- entry criteria,
- outputs,
- role visibility,
- backpressure and correction routing,
- and the public/evidence split.
If a prose file and the contract ever disagree about execution order or required outputs, follow the contract.
### 2. Neutral workflow rules
- `core/`
`core/` explains the reusable workflow semantics:
- controller behavior,
- source-authority rules,
- deliverable boundaries,
- style and provenance controls,
- validation gates,
- and context-engineering expectations.
These files describe **how the workflow works**, independent of any one source corpus.
### 3. Reusable operating materials
- `briefs/`
- `toolchains/`
- `templates/`
These files support execution without redefining the workflow:
- `briefs/` hold reusable role instructions.
- `toolchains/` hold reusable rendering or build mechanics.
- `templates/` hold standard evidence and packaging artifacts.
### 4. Project packs
- `projects/<name>/`
A project pack provides what the neutral workflow cannot:
- the source corpus boundary,
- project-specific references and terminology,
- the document suite or target scope,
- per-document briefs,
- and any source-specific example seeds or metadata.
A project pack answers **what to run the workflow against**. It should not redefine the workflow itself.
### 5. Run-artifact area
- `projects/runs/<run-id>/`
`projects/runs/` is the canonical repo-local default for one run-owned workspace per execution.
- Keep every run in its own `<run-id>` subdirectory.
- Keep generated drafts, evidence packets, gate/status records, and optional logs there.
- Do not treat `projects/runs/` as a reusable project pack or neutral workflow canon.
### 6. Harness-translation prompts
- `prompts/translate-workflow-for-harness.md`
- `prompts/run-selected-project.md`
These prompts replace checked-in adapter files. They tell a harness how to:
- map neutral workflow concepts into native primitives,
- preserve workflow semantics during that mapping,
- and execute one selected project pack.
## Deliberate non-features
This repo intentionally omits:
- harness-specific command stubs,
- plugin manifests,
- runner-specific workflow code,
- pre-populated run histories or sample output trees,
- final RFC artifacts,
- and source-specific rules in `core/`.
If a harness needs workers, tasks, jobs, subagents, staged prompts, or other runtime constructs, it should derive them from the neutral contract and prompts when the run starts.
## Workflow shape
A typical run follows this shape:
1. Define scope and target deliverables.
2. Load context and source-orientation material.
3. Gather and confirm source evidence.
4. Build claim/evidence and capability-coverage artifacts.
5. Draft from accepted evidence only.
6. Validate examples and mechanical consistency.
7. Run review lanes and reader-facing gates.
8. Apply recursive corrections to the earliest faulty artifact.
9. Run clean-room proof.
10. Package public outputs separately from evidence artifacts.
The exact stage IDs, gates, and outputs live in `workflow.contract.yaml`. The list above is the operator's mental model, not a substitute for the contract.
## Recommended start sequence
For a new operator or harness, use this startup path in order:
1. Read `README.md` for the repo model and `AGENTS.md` for the operational load order.
2. Select exactly one reusable project pack under `projects/` (never `projects/runs/`).
3. Choose the target scope before loading prompts:
- `document:<brief-name>`
- `subset:<brief-name>,<brief-name>,...`
- `suite:all`
4. Choose or create one dedicated writable run root for this execution.
- The canonical repo-local default is `projects/runs/<run-id>/`.
- Keep each execution in its own run-owned subdirectory with stable subpaths such as `public/`, `evidence/`, `gates/`, and optional `logs/` beneath that run root.
- Do not use the repo root, the shared `projects/runs/` directory itself, or the project-pack directory as the run root.
5. Verify the selected pack's required render/toolchain prerequisites before translation or execution.
- Reusable mechanics live under `toolchains/`.
- For the Fossil pack, rendered-output runs require `kramdown-rfc` and `xml2rfc`; see `toolchains/kramdown-rfc-mechanics.md`.
6. Load `workflow.contract.yaml`.
7. Load the neutral docs under `core/`.
8. Load any reusable `briefs/`, `toolchains/`, and `templates/` needed for the selected scope.
9. Read the selected pack's `README.md` plus its suite, corpus, `references.md`, draft metadata, document briefs, examples, and any staged support material under `projects/<selected-project>/references/` that the run needs.
10. Give the harness `prompts/translate-workflow-for-harness.md` first. Fill or attach the selected pack, target scope, run-root intent, harness facts, and any pack-local staged references. The required output is a ready-to-run handoff.
11. Without dropping that translation output from context, give the harness `prompts/run-selected-project.md` second with concrete placeholders replaced. If you must start a fresh thread or session, paste the ready-to-run handoff above the run prompt.
Do not skip the translation step or the dedicated run-root setup. This repo is adapter-free by design.
## How to use this repo with any dynamic workflow harness
A compatible harness should be able to do four things well.
### Load files as operating instructions
The harness must be able to read the contract, neutral workflow docs, and one selected project pack.
### Allocate native execution units
The harness may call them tasks, jobs, workers, agents, lanes, or something else. The names can change; the responsibilities cannot.
### Preserve gates and correction behavior
The harness must preserve entry criteria, output requirements, review gates, and recursive correction routing rather than flattening the workflow into a single drafting pass.
### Keep reusable repo assets separate from run-local output
Run artifacts belong in one dedicated run-local workspace—by default `projects/runs/<run-id>/`—chosen by the operator or harness. Keep reusable pack content under `projects/<name>/` and keep per-run output in its own run subdirectory.
## Suggested operator mental model
Think of execution as:
> neutral contract + neutral workflow rules + selected project pack + runtime harness translation
That split makes it straightforward to add a new project later without forking the workflow or blessing one harness as canonical.
## Creating a project pack
Use `projects/fossil/` as the shape reference, but replace every source-specific fact with material for your own corpus. A new pack should be runnable without copying neutral workflow policy into it.
### Canonical starter skeleton
```text
projects/<name>/
├── README.md # required
├── suite-brief.md # required
├── corpus-brief.md # required
├── references.md # required
├── references/ # canonical staging dir for pack-local source-reference support material
├── draft-metadata.md # required
├── briefs/ # required
│ ├── <document-1>.md # required
│ └── <document-N>.md # required; exactly one per public document
└── examples/ # optional
└── <example-note>.md # optional
```
Required files and directories:
- `README.md` — pack overview, suite covered, pack contents, recommended use, and pack-local boundaries.
- `suite-brief.md` — suite charter, deliverable boundaries, cross-document dependencies, and any suite-wide exclusions.
- `corpus-brief.md` — source corpus boundary, source-authority notes, and section-to-source routing for this project.
- `references.md` — the authoritative curated reference pool, terminology ownership, and internal dependency map for the suite.
- `references/` — required directory for pack-local source-reference manifests, path maps, excerpts, or other staged support material used during evidence gathering. It may start empty, but it belongs in the scaffold and complements rather than replaces `references.md`.
- `draft-metadata.md` — shared draft defaults plus per-document title/abstract metadata.
- `briefs/<document>.md` — exactly one brief per public document in the suite. If the suite has four deliverables, `briefs/` must contain four document briefs.
Optional files:
- `examples/*.md` — project-specific anomaly seeds, observed-byte notes, or review probes that execution should revisit.
- Additional pack-local notes only when they are source-specific and linked from the pack `README.md`.
Do **not** put harness commands, runner adapters, reusable neutral workflow rules, generated run output, or another project's source notes in the pack.
### Ordered procedure
1. Create `projects/<name>/` with the skeleton above, including an empty `references/` directory for staged support material.
2. Write `README.md` first so the pack states the suite, the intended deliverables, and the exact files the operator should load.
3. Write `suite-brief.md` with the complete document list, document ordering/dependency notes, and suite-wide scope boundaries.
4. Write `corpus-brief.md` so the source boundary and source-authority rules are explicit before any drafting starts.
5. Write `references.md` and `draft-metadata.md` so terminology ownership, document relationships, and shared front matter are fixed once for the suite. Use `references/` only for staged support material that complements `references.md`.
6. Create `briefs/<document>.md` for every public document named in `suite-brief.md`. The brief count must match the document count; no document should rely on a brief from another pack.
7. Add files under `references/` or `examples/` only when they are project-specific and execution-relevant.
8. Read the pack top to bottom and confirm an operator could select it, choose scope, verify prerequisites, and run translation without opening another project's pack for missing context.
## Pack completeness checklist
- [ ] `projects/<name>/README.md` explains the suite, the pack contents, and the intended load/use order.
- [ ] `suite-brief.md` names every public deliverable in the suite and states cross-document dependency boundaries.
- [ ] `corpus-brief.md` defines the source corpus boundary and project-specific source-authority routing.
- [ ] `references.md` covers reference ownership, terminology ownership, and document-to-document dependency pointers.
- [ ] `references/` exists as the required pack-local staging area for source-reference support material, and it is not being used as a substitute for `references.md`.
- [ ] `draft-metadata.md` supplies shared defaults plus per-document metadata for every deliverable in the suite.
- [ ] `briefs/` contains exactly one document brief for each public document named in `suite-brief.md`.
- [ ] Any `examples/` files are source-specific review/evidence aids, not neutral workflow policy or harness glue.
- [ ] The pack contains no harness-specific command files, runner adapters, generated run directories, or reusable rules that belong in `core/`, `briefs/`, `toolchains/`, or `templates/`.
- [ ] An operator can understand the pack without consulting another project's pack for missing required files or definitions.
## Adding another project pack
When adding another pack to this repo:
1. Scaffold `projects/<new-project>/` from the canonical starter skeleton above, including the empty `references/` staging directory.
2. Fill the required files in this order: `README.md`, `suite-brief.md`, `corpus-brief.md`, `references.md`, `draft-metadata.md`, then one file per document under `briefs/`.
3. Add optional files under `references/` and optional `examples/` material only when they are truly project-specific and execution-relevant.
4. Run the pack completeness checklist before the first translated run.
5. Reuse the neutral contract and `core/` files unchanged unless workflow semantics themselves need to change.
6. If workflow semantics do change, update the neutral contract and neutral docs rather than hiding the difference inside the new pack.
A new pack should plug different source material into the same workflow machine.
## Quick path map
```text
.
├── README.md
├── AGENTS.md
├── workflow.contract.yaml
├── schemas/
├── core/
├── briefs/
├── prompts/
├── toolchains/
├── templates/
└── projects/
├── runs/
│ └── <run-id>/
│ ├── public/
│ ├── evidence/
│ ├── gates/
│ └── logs/ # optional
└── <project>/
```
## Rule of thumb for placing content
- Put it in `core/` when another project could use it unchanged.
- Put it in `briefs/`, `toolchains/`, or `templates/` when it supports execution but does not define project-specific behavior.
- Put it in `projects/<name>/` when it depends on one source corpus, one document suite, or one project's terminology and examples.
- Put it in `projects/runs/<run-id>/` when it is generated, collected, or revised for one specific workflow run.
- Put it in `prompts/` when it helps a harness load or run the neutral workflow without becoming a checked-in harness adapter.