Okf Parallel Build

Use this skill when the target OKF bundle is large enough that a single agent context cannot hold the whole concept graph — the failure mode where concepts get silently dropped. It orchestrates Codex subagents in parallel and uses the deterministic okf tools as the coordination substrate.

Why single-pass authoring fails on large bundles

The ordinary authoring flow keeps the concept inventory, drafts, citations, and validator output in one conversation. On a large bundle that overflows the window and concepts are lost. The fix is not "try harder" — it is to move coordination onto disk and fan out:

1. A plan is the ledger. Every concept to author is one row in .okf/plan.csv, with a shard column assigning disjoint file ownership.
2. Workers fan out in parallel. Codex spawns one authoring subagent per row (spawn_agents_on_csv), each owning a single path, so writes never collide.
3. Coverage is audited deterministically. okf coverage diffs the plan against files on disk. This — not any single agent's diligence — is what makes the bundle provably exhaustive.

scouts (∥) → mapper → .okf/plan.csv ──spawn_agents_on_csv──▶ workers (∥, one per row)
                                                                     │
   reconcile (tools):  okf coverage → okf index → okf lint --strict │
                                                                     ▼
              review (∥):  citation-auditor · graph-reviewer · skeptical-reviewer
                              └────────── repair loop until coverage is COMPLETE ──────────┘

One-time setup

Codex spawns only the subagents that exist in .codex/agents/. Install the bundled role definitions once, and raise the parallelism ceiling.

1. Install the subagents:
   • MCP: okf_install_agents, or
   • CLI: python tools/okf_tool.py install-agents This copies okf-source-scout, okf-concept-mapper, okf-authoring-worker, okf-citation-auditor, okf-graph-reviewer, and okf-skeptical-reviewer into .codex/agents/.
2. Raise concurrency in ~/.codex/config.toml (default max_threads is 6):

   [agents]
   max_threads = 10
   max_depth = 1
   

Orchestration workflow

Run this from the orchestrator (the main Codex thread). Keep the orchestrator context thin: it holds the plan and coverage summaries, not concept bodies.

1. Scope. Infer purpose, target consumer, freshness, and source boundaries. Define a source policy before writing.
2. Scout sources in parallel. Split the topic into subtopics and spawn one okf-source-scout per subtopic, giving each a unique short id prefix derived from its subtopic (e.g. auth, pay): "Spawn one source scout per subtopic, wait for all, and merge their source tables." Deduplicate the merged rows, then write the result to <bundle>/.okf/sources.csv with columns source_id,title,url,publisher,date,source_type,reliability,used_for. This file is the citation database every authoring worker resolves source_ids against - a worker cannot cite what is not in it. (.okf/ is skipped by scan_bundle, so it never becomes bundle content.)
3. Map concepts. Hand the merged source table and goal to okf-concept-mapper and get back one exhaustive concept inventory (JSON array). Over-enumerate; coverage will catch extras, but it cannot invent a concept nobody planned.
4. Build the plan. Turn the inventory into a sharded ledger:
   • MCP: okf_plan_bundle with bundle_path, inventory, and shards (match max_threads).
   • CLI: python tools/okf_tool.py plan <bundle> --inventory inventory.json --shards 10 This writes <bundle>/.okf/plan.csv and plan.md.
5. Fan out authoring. Spawn authoring workers over the plan CSV:

   spawn_agents_on_csv(
     csv_path = "<bundle>/.okf/plan.csv",
     agent = "okf-authoring-worker",
     id_column = "path",
     instruction = "Author the OKF concept at {path}. type={type}, title={title}. "
                   "description: {description}. Cite sources {source_ids}. "
                   "Write only {path}; then mark it done and report the result.",
     max_concurrency = 10,
   )
   

   Each worker writes exactly one file and calls report_agent_job_result once. For inventories larger than max_threads, spawn_agents_on_csv queues the rows into waves automatically — you do not need to batch by hand.
6. Reconcile deterministically (tools, not model context):
   • okf coverage <bundle> — the gate; exits non-zero until every planned concept exists and is complete. For rows with source_ids, coverage also checks that the authored file has a # Citations section.
   • okf index <bundle> — regenerate root and directory indexes centrally.
   • okf lint <bundle> --strict — conformance + quality.
7. Repair loop. Run coverage with retry output, then re-spawn authoring workers over <bundle>/.okf/retry.csv:

   python tools/okf_tool.py coverage <bundle> --retry-csv
   spawn_agents_on_csv(csv_path = "<bundle>/.okf/retry.csv", ...)
   

   Re-run coverage and repeat until status is COMPLETE. When coverage is complete, the retry CSV is removed.
8. Review in parallel. Over disjoint directories, spawn okf-citation-auditor, okf-graph-reviewer, and okf-skeptical-reviewer. Feed their findings back into a repair wave, then re-run coverage and lint --strict.
9. Finalize. Add a log.md entry, create/refresh bundle-local AGENTS.md (okf_generate_chatgpt_usage), and package.

Coordination invariants

• Disjoint ownership. One concept path per plan row; a worker writes only its path. Duplicate paths are rejected at plan time — that is the anti-collision guarantee, so git worktrees are not required for authoring.
• Central indexes. Never let workers write index.md; generate indexes once at reconcile time so they stay coherent.
• Truth is on disk. okf coverage derives completeness from files, not from the status column. A worker that marks a row done without a complete file is reported as a status mismatch.
• Sources are on disk. .okf/sources.csv is the single citation database. Workers resolve source_ids against it; never route source tables through agent-to-agent messages.
• Thin orchestrator. Pass concept bodies through the filesystem and pass only tables/summaries between agents. This is what keeps a large bundle inside budget.

Completion criteria

Before the final response, report:

• bundle path and packaging format;
• planned vs. authored concept counts and the number of shards/workers used;
• final okf coverage status (must be COMPLETE) and lint --strict result;
• review findings addressed and any accepted residual warnings;
• most important source/citation constraints and freshness assumptions.