Repository navigation
Description
PRD: https://github.com/eltmon/okf/blob/main/.pan/drafts/okf-v0.2-redesign.md (§6, report id PAN-A)
Depends on: nothing; this can start now
Blocks: OKF-1 (eltmon/okf#1)
Full order: PAN-A #4408 → OKF-1 eltmon/okf#1 → OKF-2 eltmon/okf#2 → (OKF-3 eltmon/okf#3 ‖ OKF-4 eltmon/okf#4 ‖ OKF-5 eltmon/okf#5) → OKF-6 eltmon/okf#6 → (OKF-7 eltmon/okf#7 ‖ OKF-8 eltmon/okf#8) → OKF-9 eltmon/okf#9 (ends with the v0.2.0 tag) → PAN-B #4409 → PAN-C #4410
Transition note (operator decision 2026-09-29). eltmon/okf main now carries .pan/drafts/okf-v0.2-redesign.md (commit 712af54), so its tree no longer matches sync-sources/skills/okf/ and never will again. Work item 0 retires okf-mirror-drift.yml and mirror-okf-skill.sh first, as its own commit, so the drift job cannot fail main on the next push that touches sync-sources/skills/okf/**. Until item 0 lands, do not edit sync-sources/skills/okf/ and do not run the mirror script. The vendor exclude list and the vendor-pin comparison both exclude .pan/.
What OKF-1 needs from this issue: the eltmon/okf items (LICENSE, NOTICE, CI workflow, v0.1.0 tag). The Overdeck-side items (vendor script, pin workflow, sync convergence, doctor warning) can finish in parallel with OKF-1.
Problem
sync-sources/skills/okf/is canonical and is subtree-split to the publiceltmon/okf(scripts/mirror-okf-skill.sh,.github/workflows/okf-mirror-drift.yml), so the public repo cannot take fixes.- Standalone behaviour is untested.
- Five copies of the skill exist: the source, the mirror, the installed Claude Code and Codex skill directories (a divergent 2026-09-01 variant not in git), the
pan syncstaging copy, and per-bundle.okf/scripts. eltmon/okfhas no LICENSE.
Design
eltmon/okfbecomes canonical and is registered as Overdeck projectokfwithissue_prefix: OKF.- Overdeck vendors a tagged tree and CI pins it.
pan syncinstalls the vendored tree everywhere and reports version skew.
Work items
0. First, landable alone: retire the mirror gate. Delete .github/workflows/okf-mirror-drift.yml and scripts/mirror-okf-skill.sh. From the moment this PRD was committed to eltmon/okf (2026-09-29), its tree differs from sync-sources/skills/okf/ permanently, so the drift job would fail the next main push that touches the skill directory, and the mirror script would be rejected as a non-fast-forward. Nobody runs the mirror again. (Workflow-file changes push over SSH; the gh OAuth token lacks workflow scope.)
Operator:Done 2026-09-29.pan project addfor theeltmon/okfcheckout (keyokf, prefixOKF, tracker GitHubeltmon/okf).eltmon/okf:- add
LICENSE(MIT) andNOTICE(Apache-2.0 attribution forreferences/spec.md); - add
.github/workflows/ci.ymlrunningscripts/selftest.shfor now; - tag
v0.1.0atfe73d46(the last pure-skill commit, byte-identical to overdeckd44e4a9fefe), not at the current tip, which also carries.pan/. - This item is work inside
eltmon/okf, done by the Overdeck-side agent: expect a cross-repo push.
- add
- Overdeck:
- new
scripts/vendor-okf-skill.sh <tag>: fetch the tag tarball, replacesync-sources/skills/okf/using an explicit exclude list (.github/,.pan/,tests/,CHANGELOG.md, dev tooling), always includeLICENSEandNOTICEbecause the skill is redistributed, and write.okf-skill-version; - delete
scripts/mirror-okf-skill.sh; - replace
.github/workflows/okf-mirror-drift.ymlwithokf-vendor-pin.yml, which comparesHEAD:sync-sources/skills/okfagainst the pinned tag's tree after applying the same exclude list.
- new
src/lib/sync.ts:- determine why the 2026-09-01 variant in the installed Claude Code and Codex skill directories survived while the staging copy is current, and make sync converge installed copies to the vendored tree;
pan doctorWARNs when an installedokf/.okf-skill-versiondiffers from the vendored one.
- Docs:
sync-sources/skills/okf/README.mdinstall section;configuration/knowledge.mdx"Where the skill lives".
Acceptance criteria
okf-mirror-drift.ymlandmirror-okf-skill.share gone frommain, and no workflow compares againsteltmon/okfmain.scripts/vendor-okf-skill.sh v0.1.0produces a tree identical to the tag's filtered tree, with no.github/,.pan/ortests/and withLICENSEandNOTICEpresent. A Vitest test covers the script's arg parsing and the version file.- CI fails when a file under
sync-sources/skills/okf/is edited without a re-vendor. Proven by a workflow-dispatch run on a branch with a deliberate edit. - After
pan sync,diff -rof each installed harnessokfskill directory againstsync-sources/skills/okfis empty. - A unit test covers the doctor skew warning.
Docs: a CLAUDE.md one-liner stating that the OKF skill is edited in eltmon/okf and vendored here, plus the configuration doc.
Activity
eltmon commentedon Sep 29, 2026
Work item 0 landed directly on main as
abaeeab9647(2026-09-29):.github/workflows/okf-mirror-drift.ymlandscripts/mirror-okf-skill.share deleted, so the drift gate can no longer fail main. Skip item 0; start from item 1. The.husky/pre-pushcomment that mentions the mirror script is now stale; update it as part of this issue.eltmon commentedon Sep 29, 2026
🤖 Agent completed work:
No deviations from plan except: D11's live red/green CI checkpoint for okf-vendor-pin (WI-7/pin-workflow) could not run pre-merge — GitHub requires a workflow file to exist on the default branch before workflow_dispatch will trigger it, and no PR existed yet for the pull_request trigger. Followed the PRD's stated fallback: skipped the live proof, reverted the deliberate SKILL.md drift (commits 7307e38 / db96dbb), and documented it (b506e3a). It will run for real once this PR is open (pull_request trigger, scoped to sync-sources/skills/okf/** changes) — please confirm it's green on the PR head before merging.
All 16 xBRIEF items complete across both repos, with all 49 acceptance criteria individually verified and recorded:
npm run typecheck and npm run lint both pass clean. All touched test files pass.
eltmon commentedon Sep 30, 2026
Closed via close-out ceremony
Definition of Done
Gate: passed