This is an agentic workflow for Fossil RFC drafts. It tells an operator how to run the workflow in OpenCode, OMP, OMP with alternate models, native Codex CLI, and legacy/proprietary Claude Code.
The workflow separates three concerns:
- Public RFC deliverables — clean RFC text and source Kramdown selected for promotion.
- Evidence artifacts — claim ledgers, capability matrices, examples, validation reports, findings, and correction logs retained for audit.
- Execution adapters — OpenCode prompts, OMP task-batch descriptors, Codex prompt fragments, Claude-proprietary stubs, and a reusable skill that help a harness run the staged process.
Do not write public RFC prose from source memory or tool impressions. Public prose comes only after accepted claim-ledger rows exist.
Do not promote evidence artifacts into public RFC text. Evidence explains why the RFC says something but is not RFC content.
Different harnesses consume different file types:
| Surface | Files to use | Auto-executed by that surface? | Notes |
|---|---|---|---|
| OpenCode | opencode/start-prompt.md, runbooks/, workflows/omp-task-batches.json, skills/fossil-rfc-workflow/SKILL.md |
Partly | OpenCode can use subagents for scout/review waves; the OMP JSON is a planning descriptor, not executable OpenCode config. |
| OMP interactive session | 00-controller.md, runbooks/, workflows/omp-task-batches.json, skills/fossil-rfc-workflow/SKILL.md |
Partly | OMP can use task directly; the JSON wave file is a controller-readable descriptor, not a magic script. |
| OMP using a Codex model | Same OMP files | Partly | Prefer OMP task waves; do not fall back to native Codex limitations when OMP subagents are available. |
| OMP using a Claude model | Same OMP files | Partly | Same workflow as OMP/Codex; model choice does not change the evidence gates. |
| Native Codex CLI | codex/AGENTS.fragment.md, codex/start-prompt.md, skills/fossil-rfc-workflow/SKILL.md |
Only after installation/copy | Codex relies on AGENTS.md and skills. It does not consume OMP task-batch JSON as executable config. |
| Legacy/proprietary Claude Code | claude-proprietary/claude-plugin/, claude-proprietary/workflows/ |
Tool-dependent | Preserved for reference or operators using Claude-specific plugin/workflow surfaces. Not the primary OpenCode path. |
OpenCode quick start
From the repo root, start OpenCode and use opencode/start-prompt.md as the controller prompt. It tells OpenCode to read the controller files, use workflows/omp-task-batches.json as a wave map, and substitute direct source exploration for TraceDecay when TraceDecay is unavailable.
Use rfc-workflow-setup/runs/<YYYYMMDD-topic>/ for durable run artifacts when a run needs evidence ledgers, validation reports, or final packets.
The first run artifact is the corpus record. Confirm the Fossil and libfossil source paths with the operator before source-grounded work. Record path, commit/digest, branch, and dirty state for each. When libfossil is out of scope, record that decision and its validation impact.
OMP quick start
From the repo root, start OMP and give it this controller prompt:
Read `rfc-workflow-setup/README.md`, `rfc-workflow-setup/00-controller.md`,
`rfc-workflow-setup/manifest.json`, `rfc-workflow-setup/04-validation-gates.md`,
`rfc-workflow-setup/runbooks/06-prose-onramp-gate.md`, and
`rfc-workflow-setup/workflows/omp-task-batches.json`.
Execute the Fossil RFC workflow for: <artifact-format | delta-format | sync-protocol | repo-state | submanifests | all-public-drafts>.
Use `rfc-workflow-setup/runs/<YYYYMMDD-topic>/` for run artifacts.
Start with corpus preparation and context substrate setup. Ask the operator to confirm Fossil and libfossil source paths before source-grounded work, and record path, commit/digest, branch, and dirty state. Dispatch source scouts from the OMP task-batch descriptor only after the corpus boundary is recorded. Do not draft public RFC prose until the claim ledger and capability matrix have accepted rows. Run the cold-reader on-ramp and prose-tell gates on current public drafts before clean-room proof or packaging.
Then run stages in this order:
1. Prepare the corpus boundary.
2. Build the wiki/source-graph context substrates.
3. Dispatch source scouts using `workflows/omp-task-batches.json` wave `source-scouts`.
4. Consolidate scout output into the claim ledger and capability matrix.
5. Dispatch author waves only for sections with accepted evidence.
6. Validate examples against source-derived expectations.
7. Run the review gauntlet.
8. Run the cold-reader on-ramp gate from `runbooks/06-prose-onramp-gate.md`, keeping each reviewer isolated to one draft.
9. Run prose-tell verification on the public drafts and normalize flagged clusters or justify them as legitimate spec structure.
10. Apply recursive corrections to the earliest faulty artifact.
11. Run clean-room proof.
12. Render public outputs and verify rendered examples with `runbooks/08-render-kramdown-rfc.md`.
13. Package public RFC files separately from evidence with `runbooks/09-package-for-review.md`.
OMP with Codex or Claude models
The workflow does not need different files for Codex-backed or Claude-backed OMP sessions. Use the same setup pack and change only the model selection in OMP.
Recommended model split:
- Use the stronger reasoning model for the controller, claim-ledger consolidation, sync-protocol state machine, and final cross-document review.
- Use smaller/cheaper workers for bounded source scouting and mechanical template filling when their output is easy to verify.
- Keep reviewer agents constrained by role. A clean-room reviewer must not read source notes; a grounding reviewer must read source notes.
Legacy/proprietary Claude Code quick start
Use native Claude Code only when the operator wants to work in that tool rather than OpenCode or OMP. The adapter files are preserved under claude-proprietary/.
Two supported installation styles:
- Plugin-style local install — use
claude-proprietary/claude-plugin/plugin.jsonas the plugin manifest. It declares the workflow command path. - Command-copy install — copy
claude-proprietary/claude-plugin/commands/fossil-rfc-workflow.mdinto the project or user Claude commands directory and run the command from Claude Code.
The command still tells the agent to read this setup pack and execute the same staged gates. It does not bypass the claim ledger, examples ledger, validation report, or clean-room proof.
No Claude hook JSON is required. Hooks would be too blunt for this workflow: the important checks depend on stage state and evidence artifacts, so they belong in review/validation stages rather than pre-edit interception.
Native Codex CLI quick start
Use native Codex when OMP is not the runner. Codex should receive scoped instructions rather than the full monolithic RFC prompt.
Recommended setup:
- Merge or copy
codex/AGENTS.fragment.mdinto an applicableAGENTS.mdif you want persistent project instructions. - Install or copy
skills/fossil-rfc-workflow/SKILL.mdinto the skill location your Codex setup uses. - Start each run with
codex/start-prompt.mdand name the target RFC topic. - Run stages sequentially unless your Codex environment has a separate orchestration layer.
Do not ask native Codex CLI to execute workflows/omp-task-batches.json as config. It can read that file as a planning aid, but OMP's task schema is not Codex workflow metadata.
Directory map
| Path | Role |
|---|---|
00-controller.md |
Minimal controller rules and stage checklist. |
01-source-authority.md |
Source hierarchy and claim-admission rules. |
02-deliverables.md |
Public/evidence split and packaging rules. |
03-style-and-provenance.md |
RFC style and process-leak controls. |
04-validation-gates.md |
Mechanical, review, and correction gates. |
05-context-engineering.md |
Wiki and source-graph context layer. |
runbooks/ |
Ordered stage procedures. |
briefs/ |
Per-role subagent prompts. |
templates/ |
Evidence artifact templates. |
queries/ |
Source-graph and wiki query recipes. |
workflows/ |
Harness adapter descriptors and execution notes. |
opencode/ |
Native OpenCode start prompt and execution notes. |
omp/commands/ |
Optional OMP slash-command source, if copied into .omp/commands/. |
claude-proprietary/ |
Optional native Claude Code plugin/workflow adapters, kept separate from portable workflow material. |
codex/ |
Optional native Codex instruction fragments. |
skills/ |
Portable skill(s) that can be copied into OpenCode/OMP/Claude/Codex skill roots. |
runs/ |
Suggested per-run output location; create on demand. |
Rendering and rendered-byte validation are covered by runbooks/08-render-kramdown-rfc.md. Run it before packaging any public .txt output.
Run artifact layout
For a run targeting all public drafts on 2026-07-01, use a layout like:
rfc-workflow-setup/runs/20260701-all-public-drafts/
00-corpus/
01-context/
02-scouts/
03-ledgers/
04-skeletons/
05-drafts/
06-examples/
07-validation/
08-review/
09-corrections/
10-cleanroom/
11-final-packet/
Cold-reader and prose-tell reports normally live under 08-review/; wording fixes and their dispositions belong in 09-corrections/.
Copy templates into the run as they become active. Do not pre-fill every artifact just to make the tree look complete.
Skill policy for this pack
Create or install skills only when they reduce repeated setup without hiding project-specific evidence.
Already included:
skills/fossil-rfc-workflow/SKILL.md— the reusable workflow skill. This is appropriate because the staging, evidence separation, and review gates are reusable across runs.
Do not create separate permanent skills yet for every sub-role. Keep those as briefs/ until at least one full run proves the role boundary is stable. Candidate future skills:
- source-grounded RFC authoring;
- rendered example round-trip validation;
- clean-room specification review;
- RFC legibility review.
Context-engineering references
These references justify the wiki and graph layers; they do not replace source-code evidence for Fossil protocol claims.
- Andrej Karpathy, “LLM Wiki” — motivates a persistent, compounding markdown wiki between immutable raw sources and repeated LLM queries. This supports the structured Fossil-family wiki layer.
- Microsoft Research, “From Local to Global: A Graph RAG Approach to Query-Focused Summarization” — reports substantial improvements over conventional RAG for global sensemaking questions using graph-indexed community summaries, especially answer comprehensiveness and diversity. This supports a graph retrieval layer for cross-source RFC questions.
- Microsoft GraphRAG documentation — describes extracting entities, relationships, key claims, communities, and local/global query modes from raw text. This supports using graph structure to route source scouts and reviewers.
- Neo4j, “What is agentic RAG?” — frames agentic RAG as useful when queries require planning, multiple retrieval rounds, cross-source validation, and stopping criteria. This supports the workflow's scout/review loops.
The operational rule remains: wiki and graph layers improve orientation and retrieval, but accepted claim-ledger rows still require source code or observed bytes.
Acceptance criteria
A run is not complete until all of these are true:
- Every public claim maps to an accepted claim-ledger row.
- Every required implementer capability appears in the capability matrix.
- Every public example is validated from rendered text or explicitly marked illustrative in the evidence packet.
- Every ABNF production and table entry has matching prose or a documented reason it is excluded.
- Review findings have no open P0/P1 items.
- Clean-room proof reports no blocker for the targeted implementer capability.
- Every target document passes the cold-reader on-ramp gate, or every
SOFT-FAILis explicitly fixed or justified in the correction log. - Prose-tell verification leaves no unresolved high-density tell clusters; accepted flags are recorded as legitimate spec punctuation, explanatory structure, or list shape.
- Public RFC files and evidence artifacts are listed separately in the final packet manifest.
Common failure modes
| Failure | Prevention |
|---|---|
| The worker drafts from source impressions. | Require accepted claim-ledger rows before prose. |
| Every subagent receives the whole monolithic prompt. | Use role briefs and runbook slices. |
| Public RFC text leaks source archaeology. | Keep source paths and process notes in evidence artifacts. |
| Reviewers all check the same thing. | Assign distinct failure modes: grounding, clean-room, readability, RFC process, cross-document, security/IANA. |
| OMP JSON is treated as portable config for other tools. | Use it only as an OMP task-call descriptor. |
| Skills become stale hidden policy. | Keep skills short; keep project evidence in run artifacts. |
Minimum first run
For a conservative first run, target only the delta-format RFC before the full public draft suite. It is smaller than sync, but still exercises source scouting, example validation, claim ledgers, ABNF/prose alignment, and clean-room proof. After the gates work on delta, expand to the remaining public drafts.