Skip to content
rfc-workflow RFC Workflow
Login

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, examples, and run histories are not, so they live in project packs and in pack-local run roots.

Repository architecture

The repository is split into six surfaces.

1. Contract

workflow.contract.yaml is the human-checked contract; schemas/workflow-contract.schema.json is the machine-checkable shape for validators, generators, or harness-native workflow configuration.

The contract is the canonical source of truth for:

If a prose file and the contract ever disagree about execution order or required outputs, follow the contract.

2. Neutral workflow rules

core/ explains the reusable workflow semantics:

These files describe how the workflow works, independent of any one source corpus.

3. Reusable operating materials

These files support execution without redefining the workflow:

4. Project packs

A project pack provides what the neutral workflow cannot:

A project pack answers what to run the workflow against. It should not redefine the workflow itself.

5. Pack-local run roots

Each selected project pack owns its own repo-local run namespace.

The versioned Fossil ignore policy lives in .fossil-settings/ignore-glob. It follows the repo's project-pack conventions by ignoring projects/*/runs/* run-owned output trees and projects/*/references/* support-only staged material. That second glob also matches references/README.md: existing placeholders remain versioned only because they are already tracked, so a newly created pack's placeholder must be explicitly added/promoted if you want it checked in as the versioned boundary note.

6. Harness-translation prompts

These prompts replace checked-in adapter files. They tell a harness how to:

Deliberate non-features

This repo intentionally omits:

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.

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 select a pack's runs/ subtree as the project pack.
  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/<selected-project>/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 selected pack root, or the bare projects/<selected-project>/runs/ 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 AGENTS.md, workflow.contract.yaml, and schemas/workflow-contract.schema.json.
  7. Load the neutral docs under core/.
  8. Load any reusable briefs/, toolchains/, and templates/ needed for the selected scope. templates/ contains the standard evidence and packaging shapes the run will fill.
  9. Read the selected pack's README.md, suite brief, corpus-brief.md, references.md, draft metadata, document briefs, and examples. Treat references.md as the authoritative versioned reference surface. Treat projects/<selected-project>/references/ as support-only staged material that Fossil ignores by default; read references/README.md for the boundary, consult any local staged support files the run needs, and promote stable conclusions into references.md or another canonical pack doc.
  10. Give the harness prompts/translate-workflow-for-harness.md first. Fill or attach AGENTS.md, the selected pack, target scope, run-root intent, harness facts, and any pack-local staged references the run needs. The required output is a ready-to-run handoff plus any harness-native workflow/stage representation the harness needs before execution.
  11. Without dropping that translation output or generated configuration 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 and keep the generated configuration available.

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 AGENTS.md, the contract, neutral workflow docs, reusable materials, and one selected project pack, then generate or configure whatever native workflow/stage representation it needs from that neutral input before execution.

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/<selected-project>/runs/<run-id>/—chosen by the operator or harness. Keep reusable pack content under projects/<name>/ and keep per-run output in that pack's own runs/<run-id>/ 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/PROMPT-GENERATE-PROJECT-PACK.md when you want a harness to scaffold a new pack, and use projects/template-ietf/ as the checked-in shape reference and reusable IETF starter. The template and every newly scaffolded pack should carry a tracked runs/README.md placeholder so cloned packs inherit the per-project run-root shape. A new pack should be runnable without copying neutral workflow policy into it.

Canonical starter skeleton

projects/<name>/
├── README.md                  # required
├── suite-brief.md             # required
├── corpus-brief.md            # required
├── references.md              # required
├── references/                # support-only staged material; the default glob matches README.md too, so explicitly add/promote a new placeholder if you want it tracked
├── draft-metadata.md          # required
├── briefs/                    # required
│   ├── <document-1>.md        # required
│   └── <document-N>.md        # required; exactly one per public document
├── runs/                      # required pack-local run namespace
│   ├── README.md              # required tracked placeholder for per-project run roots
│   └── <run-id>/
│       ├── public/
│       ├── evidence/
│       ├── gates/
│       └── logs/              # optional
└── examples/                  # optional
    └── <example-note>.md      # optional

Required files and directories:

Optional files:

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 references/README.md as the placeholder for the staged support directory and runs/README.md as the tracked placeholder for pack-local run roots. Because the default projects/*/references/* glob also matches references/README.md, explicitly add/promote a new pack's placeholder if you want it versioned.
  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 support-only staged material that complements references.md; keep new files there ignored by default and explicitly promote only the placeholder or staged files you truly want versioned.
  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. Create runs/README.md so repo-local execution under projects/<name>/runs/<run-id>/ stays documented even before the first run exists.
  8. Add files under references/ or examples/ only when they are project-specific and execution-relevant. Treat references/ contents as support-only staged material covered by the default ignore rule, and deliberately promote only stable files you truly want versioned.
  9. 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

Adding another project pack

When adding another pack to this repo:

  1. Scaffold projects/<new-project>/ from the canonical starter skeleton above, including the references/README.md placeholder in the ignored-by-default staging directory and the tracked runs/README.md placeholder. Because the default projects/*/references/* glob matches that new placeholder too, explicitly add/promote it if you want it versioned.
  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; references/ is for support-only staged material, so keep new files ignored by default and promote only stable files or conclusions deliberately.
  4. Keep generated run output under projects/<new-project>/runs/<run-id>/, not in a shared repo-level runs area.
  5. Run the pack completeness checklist before the first translated run.
  6. Reuse the neutral contract and core/ files unchanged unless workflow semantics themselves need to change.
  7. 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

.
├── README.md
├── AGENTS.md
├── workflow.contract.yaml
├── schemas/
├── core/
├── briefs/
├── prompts/
├── toolchains/
├── templates/
└── projects/
    └── <project>/
        ├── README.md
        ├── suite-brief.md
        ├── corpus-brief.md
        ├── references.md
        ├── draft-metadata.md
        ├── briefs/
        ├── references/
        ├── examples/
        └── runs/
            ├── README.md
            └── <run-id>/
                ├── public/
                ├── evidence/
                ├── gates/
                └── logs/            # optional

Rule of thumb for placing content