# 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` - `schemas/workflow-contract.schema.json` `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: - 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 such as claim ledgers, capability matrices, validation reports, escalation notes, and final-packet manifests. ### 4. Project packs - `projects//` A project pack provides what the neutral workflow cannot: - the source corpus boundary, - project-specific references and terminology recorded authoritatively and versioned in `references.md`, - sibling `references/` support-only staged material, covered by the `projects/*/references/*` ignore rule; existing tracked `references/README.md` placeholders stay versioned, but a newly scaffolded pack's placeholder must be explicitly added/promoted if you want it tracked, - the document suite or target scope, - per-document briefs, - pack-local run-root guidance in `runs/README.md`, - 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. Pack-local run roots - `projects//runs//` Each selected project pack owns its own repo-local run namespace. - The canonical repo-local default for one execution is `projects//runs//`. - Keep every run in its own `` subdirectory. - Keep generated drafts, evidence packets, gate/status records, and optional logs there. - Keep the tracked `projects//runs/README.md` placeholder, but never treat the `runs/` subtree itself as reusable pack input. - There is no shared repo-wide `projects/runs/` run namespace in this model. 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. Reusable prompts - `prompts/discover-rfc-suite-shape.md` - `projects/PROMPT-GENERATE-PROJECT-PACK.md` - `prompts/translate-workflow-for-harness.md` - `prompts/run-selected-project.md` These prompts cover the repo's two setup phases: - before a pack exists, `prompts/discover-rfc-suite-shape.md` analyzes the source corpus, proposes the smallest clean RFC suite, and returns `Pack scaffold inputs` for `projects/PROMPT-GENERATE-PROJECT-PACK.md` - once a pack exists, the translation and run prompts tell a harness how to load it, preserve workflow semantics, and execute one selected scope ## Deliberate non-features This repo intentionally omits: - harness-specific command stubs, - plugin manifests, - runner-specific workflow code, - pre-populated run histories, sample output trees, or reusable final-artifact snapshots outside pack-local run-owned directories, - 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. If no suitable project pack exists yet and the suite boundaries are not already fixed, run `prompts/discover-rfc-suite-shape.md` against the real source corpus first. Review its final `Pack scaffold inputs` block, then use `projects/PROMPT-GENERATE-PROJECT-PACK.md` to scaffold `projects//` before continuing. If the pack inputs are already concrete, you can go straight to the pack-generation prompt. 3. Select exactly one reusable project pack under `projects/`; never select a pack's `runs/` subtree as the project pack. 4. Choose the target scope before loading execution prompts: - `document:` - `subset:,,...` - `suite:all` 5. Choose or create one dedicated writable run root for this execution. - The canonical repo-local default is `projects//runs//`. - 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//runs/` directory as the run root. 6. 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`. 7. Load `AGENTS.md`, `workflow.contract.yaml`, and `schemas/workflow-contract.schema.json`. 8. Load the neutral docs under `core/`. 9. Load any reusable `briefs/`, `toolchains/`, and `templates/` needed for the selected scope. `templates/` contains the standard evidence and packaging shapes the run will fill. 10. 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//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. 11. 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, the native workflow/config language/schema/DSL when the harness has one (for example, `Ultracode`), any harness-native schema/reference/example/template material needed to emit valid native config text, and any pack-local staged references the run needs. The required output is a ready-to-run handoff plus whatever harness-native workflow/stage representation the harness needs before execution. When the harness expects a native artifact, that output must include the actual native config/workflow text or object; when it does not, an explicit `none`/`not supported` plus a concrete primitive map and handoff is enough. 12. 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 any generated native workflow/configuration available. Do not skip the suite-discovery step when boundaries are unresolved, the translation step, or the dedicated run-root setup. This repo is adapter-free by design. ## How to use this repo with any 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. When the harness uses a named native workflow/config language, schema, or DSL, the translation output should carry the actual runnable native text/object, not merely describe it; if the required schema/reference/examples/templates are missing, translation should escalate rather than invent generic session primitives. When the harness has no separate native artifact layer, an explicit `none`/`not supported` plus a concrete primitive map and ready-to-run handoff is sufficient. ### 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//`—chosen by the operator or harness. Keep reusable pack content under `projects//` and keep per-run output in that pack's own `runs//` 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 When suite boundaries are not already fixed, start with `prompts/discover-rfc-suite-shape.md`. Its final `Pack scaffold inputs` block is the direct input for `projects/PROMPT-GENERATE-PROJECT-PACK.md`. Then use that pack-generation prompt with `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 ```text projects// ├── 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 │ ├── .md # required │ └── .md # required; exactly one per public document ├── runs/ # required pack-local run namespace │ ├── README.md # required tracked placeholder for per-project run roots │ └── / │ ├── public/ │ ├── evidence/ │ ├── gates/ │ └── logs/ # optional └── examples/ # optional └── .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, versioned 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. The default `projects/*/references/*` ignore rule matches `references/README.md` too: existing placeholders stay versioned because they are already tracked, while a new pack's placeholder and any other staged files must be explicitly promoted if you want them checked in. They complement rather than replace the authoritative versioned `references.md`. - `draft-metadata.md` — shared draft defaults plus per-document title/abstract metadata. - `briefs/.md` — exactly one brief per public document in the suite. If the suite has four deliverables, `briefs/` must contain four document briefs. - `runs/README.md` — required tracked placeholder that documents the pack-local run root `projects//runs//` and preserves the standard `public/`, `evidence/`, `gates/`, and optional `logs/` layout. 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//` 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/.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//runs//` 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 - [ ] `projects//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`. - [ ] `runs/README.md` exists and documents the pack-local run root plus the `public/`, `evidence/`, `gates/`, and optional `logs/` layout. - [ ] 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//` 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//runs//`, 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 ```text . ├── README.md ├── AGENTS.md ├── workflow.contract.yaml ├── schemas/ ├── core/ ├── briefs/ ├── prompts/ ├── toolchains/ ├── templates/ └── projects/ └── / ├── README.md ├── suite-brief.md ├── corpus-brief.md ├── references.md ├── draft-metadata.md ├── briefs/ ├── references/ ├── examples/ └── runs/ ├── README.md └── / ├── public/ ├── evidence/ ├── gates/ └── logs/ # optional ``` ## 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//` when it depends on one source corpus, one document suite, or one project's terminology and examples. - Put it in `projects//runs//` 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.