[Extension]: Update OKF Knowledge Bundle Generator to v0.3.0

[alexcpn]

Extension ID

okf

Extension Name

OKF Knowledge Bundle Generator

Version

0.3.0

Description

Generates and maintains an Open Knowledge Format (OKF v0.1) knowledge bundle from a source-code repository, mining git history for significance and rationale, and resolving open questions with the user.

Author

Alex Punnen

Repository URL

https://github.com/alexcpn/speckit_ofk

Download URL

https://github.com/alexcpn/speckit_ofk/archive/refs/tags/v0.3.0.zip

License

MIT

Homepage (optional)

https://github.com/alexcpn/speckit_ofk

Documentation URL (optional)

https://github.com/alexcpn/speckit_ofk/blob/main/README.md

Changelog URL (optional)

https://github.com/alexcpn/speckit_ofk/blob/main/CHANGELOG.md

Required Spec Kit Version

=0.12.0

Required Tools (optional)

Number of Commands

4

Number of Hooks (optional)

0

Tags

knowledge, okf, documentation, metadata, catalog

Key Features

• Full bundle generation (/speckit.okf.generate) — scans the repo, mines git history (per-file commit churn for significance, per-path history for rationale), plans concepts, writes cross-linked docs, and validates
• Incremental updates (/speckit.okf.update) — diffs git history, updates only stale concepts, preserves human edits and clarified facts
• Clarification (/speckit.okf.clarify) — new in 0.3.0: collects open_questions the agent couldn't resolve from code or history, asks the user in prioritized batches, and folds answers back into concepts as cited, curation-protected knowledge
• Conformance validation (/speckit.okf.validate) — checks OKF §9 conformance plus link/secret/quality spot-check, including unresolved open questions (W8)

Testing Checklist

• Extension installs successfully via download URL
• All commands execute without errors
• Documentation is complete and accurate
• No security vulnerabilities identified
• Tested on at least one real project

Submission Requirements

• Valid extension.yml manifest included
• README.md with installation and usage instructions
• LICENSE file included
• GitHub release created with version tag
• All command files exist and are properly formatted
• Extension ID follows naming conventions (lowercase-with-hyphens)

Testing Details

Tested on

OS: Pop!_OS 22.04 LTS (Linux, kernel 6.9.3-76060903-generic, x86_64)
Spec Kit CLI: 0.12.18.dev0 (Python 3.11.15)
LLM / coding agent: Claude Sonnet 5 (via Claude Code CLI)

• Verified okf-inventory.sh emits the new git.history object (churn + recent_commits) and adr_docs category on both a single-repo project and a synthetic monorepo (multiple service subdirectories under one git history) — churn correctly attributes commits per-file/per-service rather than blurring them together
• Verified the new okf-history.sh script scoped to a subdirectory (git log -- <path>) correctly returns only commits touching that subtree, including revert/hotfix/risk-flagged detection
• Ran ShellCheck (0 findings) on both bash scripts and Bandit (0 findings) on validate_okf.py before tagging the release; both are also checked automatically on every push via CodeQL and ShellCheck GitHub Actions workflows
• Confirmed the release archive URL (https://github.com/alexcpn/speckit_ofk/archive/refs/tags/v0.3.0.zip) is publicly reachable and resolves via GitHub's codeload redirect
• Confirmed extension.yml lists all 4 commands (generate, update, clarify, validate) and validates against the manifest schema

Example Usage

# 1. Installation
specify extension add okf --from https://github.com/alexcpn/speckit_ofk/archive/refs/tags/v0.3.0.zip

# 2. Generate the initial knowledge bundle
/speckit.okf.generate

# 3. Resolve anything the agent couldn't infer from code + git history
/speckit.okf.clarify

# 4. After making code changes, refresh incrementally
/speckit.okf.update

# 5. Validate conformance before committing
/speckit.okf.validate

Output lands in knowledge/ (configurable) as a set of cross-linked markdown concept files ready to commit alongside your code.

Proposed Catalog Entry

{
    "okf": {
      "name": "OKF Knowledge Bundle Generator",
      "id": "okf",
      "description": "Generates and maintains an Open Knowledge Format (OKF v0.1) knowledge bundle from a source-code repository, mining git history for significance and rationale, and resolving open questions with the user.",
      "author": "Alex Punnen <alexcpn@gmail.com>",
      "version": "0.3.0",
      "download_url": "https://github.com/alexcpn/speckit_ofk/archive/refs/tags/v0.3.0.zip",
      "repository": "https://github.com/alexcpn/speckit_ofk",
      "homepage": "https://github.com/alexcpn/speckit_ofk",
      "documentation": "https://github.com/alexcpn/speckit_ofk/blob/main/README.md",
      "changelog": "https://github.com/alexcpn/speckit_ofk/blob/main/CHANGELOG.md",
      "license": "MIT",
      "requires": {
        "speckit_version": ">=0.12.0"
      },
      "provides": {
        "commands": 4,
        "hooks": 0
      },
      "tags": ["knowledge", "okf", "documentation", "metadata", "catalog"],
      "verified": false,
      "downloads": 0,
      "stars": 0,
      "created_at": "2026-07-17T00:00:00Z",
      "updated_at": "2026-07-21T00:00:00Z"
    }
  }

Additional Context

This is an update to the existing okf catalog entry (originally submitted in #3580, merged via #3585 at v0.2.0). v0.3.0 adds git-history mining (okf-history.sh, git.history in the inventory) and the new /speckit.okf.clarify command; see the changelog for full details. created_at above is preserved from the original 2026-07-17 submission.

Release: https://github.com/alexcpn/speckit_ofk/releases/tag/v0.3.0

[xg-gh-25]

The okf-history.sh → git.history pipeline is smart. Mining commit churn per-file for significance and commit messages for rationale is exactly what a knowledge system should do — git history contains why decisions were made, not just what changed.

Three observations from maintaining a living knowledge substrate:

1. Git history as primary source has a coverage gap

Commits capture decisions that shipped, but not the dead ends. We maintain an adjacent "decision log" (ADRs) that records: the problem, options considered, chosen option, and why the rejected options were rejected. Commit messages explain the solution; ADRs explain the choice.

When your /speckit.okf.clarify asks "why did you choose X over Y?", if the answer isn't in git history, you can't fill the gap from code alone. The user must supply it. But once clarified, that knowledge should be curation-protected (as you do) and decay-monitored — if the codebase changes in a way that invalidates the reasoning, the clarification becomes stale.

Example: "We chose SQLite over Postgres because deployment complexity" is true until you containerize, at which point the reasoning is obsolete but the text stays.

2. Incremental updates must handle deleted concepts

Your okf-update diffs git history and updates stale concepts. What happens when a file is deleted? If the concept was "how module X works" and module X is gone, should the concept be deleted, archived, or marked deprecated?

We handle this with a "last-verified" timestamp on each knowledge node. When the backing code disappears, the concept stays (someone might ask "why did we remove X?") but is marked last_verified: <deletion_date> and excluded from the active knowledge graph. Your validation (§9 conformance) could check for orphaned concepts and warn.

3. The clarification loop is your differentiator

Most knowledge-mining tools (including ours) generate docs and stop. Your /speckit.okf.clarify → user answers → fold back as curation-protected knowledge is the key innovation. This creates a living substrate where the system knows what it doesn't know and can ask.

One refinement: batch clarifications by urgency. If concept A is referenced by 5 other concepts and concept B by none, resolve A first. You could track cross-links during generation and prioritize open_questions by downstream fan-out.

Also: when the user answers a clarification, log who answered and when. If that person leaves the team and a conflict arises ("but we decided X because Y"), the timestamp + author are the provenance trail.

The v0.3.0 release looks production-ready. We'd use this alongside (not replacing) our DDD cultivation loop — yours mines history, ours mines agent conversations and failures.

---

Living knowledge substrate — cultivated by SwarmAI. Discussion: DDD Cultivation

[github-actions]

cc @github/spec-kit-maintainers — new catalog submission for review.

[github-actions]

Pull request created: #3608

Generated by Add Community Extension from Issue Submission · 172.9 AIC · ⌖ 15.2 AIC · ⊞ 34.5K

[mnriem]

Thank you!