{
  "markdown": "# okf-kit\n\nThe team's OpenSpec + OKF workflow, packaged so every project gets the same one\nand can be upgraded without hand-copying files.\n\n- **OpenSpec** carries change work: proposal, specs, tasks.\n- **OKF** (`.okf/`) carries durable domain knowledge: terms, business rules with\n  stable `BR-n` ids, actors, permissions, entities, workflows.\n- Two gates: an OKF entry must exist before implementation, and so must a\n  test-plan.\n\nStart with `docs/workflow-at-a-glance.md` for the diagrams: how a change and a\nknowledge entry move together from explore to archive. Then\n`docs/okf-kit-overview.md` for the team-facing picture (what the kit solves vs\nusing OpenSpec + OKF traditionally, plus the implement workflow).\nRead `docs/openspec-okf-workflow.md` for mechanics and what it does *not*\nguarantee. Read `.okf/README.md` for what belongs in a knowledge entry.\n\n## Install into a project\n\nOrder matters: `openspec init` writes its own `openspec/config.yaml`, so it goes\nfirst and `okf init` replaces that file afterwards.\n\n```bash\n# 1. OpenSpec itself, plus the skill files for the tools your team uses\nnpx openspec init --tools claude,codex,cursor\n\n# 2. This kit (pin a tag - the version is what makes upgrades traceable)\nnpm i -D github:amagumolabs/okf-kit#v0.6.0\n\n# 3. Install the schema, templates, and the CLAUDE.md / AGENTS.md addendum\nnpx okf init\n\n# 4. Generate the index and check the result\nnpx okf index && npx okf check\n```\n\n`.okf/` targets **Open Knowledge Format v0.2**. `.okf/profile.md` records every\nplace this kit narrows or extends that specification, and what it deliberately\ndoes not claim.\n\n`openspec update` regenerates the tool skill files from OpenSpec's own templates.\nIt leaves the `okf-kit` block in `CLAUDE.md` / `AGENTS.md` alone - verified, not\nassumed.\n\n## Upgrade\n\n```bash\nnpm i -D github:amagumolabs/okf-kit#v0.6.0\nnpx okf upgrade --dry-run   # see what would change\nnpx okf upgrade\n```\n\nUpgrade replaces kit-owned files, but only the ones your team has not edited. A\nfile you changed is reported and left alone:\n\n```\n  MODIFIED LOCALLY  .okf/templates/feature.md.tmpl  -> skipped\n```\n\nDiff it against the kit, fold in what you want, then re-run with `--force` - or\nkeep your version and accept that it drifts. What upgrade decides from is\n`.okf/.okf-kit.json`, a manifest of content hashes written at install time.\n\n## What belongs to whom\n\n| Kit-owned (upgrade replaces) | Project-owned (never touched) |\n| --- | --- |\n| `openspec/schemas/okf-gated-feature/**` | `.okf/features/**`, `.okf/decisions/**` |\n| `openspec/config.yaml` | `.okf/index.md`, `.okf/log.md` (generated by `okf index`) |\n| `.okf/templates/**`, `.okf/README.md`, `.okf/profile.md` | everything in `CLAUDE.md` / `AGENTS.md` outside the markers |\n| the block between `<!-- okf-kit:start -->` and `<!-- okf-kit:end -->` | your code, tests, and every other file |\n\n## Commands\n\n| Command | Purpose |\n| --- | --- |\n| `okf check` | Entries, pointers, rule ids, evidence, test statuses, index, debt ledger, kit version skew |\n| `okf check` (archive mode) | Also: every decision in `design.md` accounted for in the Decision Promotion table, by a resolving path under `.okf/decisions/` or a stated reason |\n| `okf check --archive <change-id>` | The stricter pre-archive set - run it before archiving |\n| `okf check --json` | Same findings, machine-readable |\n| `okf audit` | Report entries whose declared `code_paths` changed after they were verified. Reports only, never edits knowledge |\n| `okf index` | Regenerate `.okf/index.md` and `.okf/log.md` from entry frontmatter |\n| `okf index --check` | Fail if either is stale (for CI) |\n| `okf migrate` | Move entry frontmatter to the current kit shape. The only command that writes to `.okf/features/` and `.okf/decisions/`, so it is invoked deliberately rather than by `okf upgrade`. Never invents a `verified[]` attestation (`--dry-run`) |\n| `okf init` / `okf upgrade` | Install or update the kit in a project (`--dry-run`, `--force`) |\n\nExit codes: `0` clean, `1` problems found, `2` bad usage.\n\n## CI\n\nCopy `.github/workflows/okf.yml` into the project, or add the three steps to an\nexisting workflow:\n\n```yaml\n- run: npx okf index --check\n- run: npx okf check\n```\n\n`okf audit` belongs on a schedule, not on every commit. Drift accumulates over\nweeks, and a job that fails a pull request for something nobody in it caused is a\njob that gets deleted:\n\n```yaml\non:\n  schedule:\n    - cron: '0 6 * * 1'   # Monday morning\njobs:\n  drift:\n    steps:\n      - run: npx okf audit\n```\n\nCI is the backstop, not the gate: a developer who never runs `okf check` and\nnever opens a PR can still start implementing behind three empty files. What CI\nguarantees is that it does not reach `main`.\n\n## Developing the kit\n\n```bash\nnode test/run.mjs   # 133 fixture tests, no dependencies\nnode bin/okf.mjs check\n```\n\nThe kit develops against its own schema and templates - the payload `okf init`\ncopies is the same set of files this repo uses - so it cannot ship something it\ndoes not itself run. Requires Node 18+ and nothing else.\n",
  "bytes": 5061,
  "sha": "11b4fe2bb08736692b7abfc46144af1a108f081875c22d6f9d82a5ff4c1a774c",
  "repo_slug": "amagumolabs/okf-kit",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_amagumolabs_okf_kit_okf_index_md_bc5e6544/readme"
}