Add the codebase-wiki starter pack — an agent-authored, navigable…#264
Merged
Conversation
…ur repo) (#1921)
* feat(ok): add codebase-wiki starter pack + wiki workflow (DeepWiki, in your repo)
Adds a repo-owned, agent-authored equivalent of DeepWiki: a coding agent reads
the source and authors a navigable, diagram-rich, source-grounded wiki AS
markdown into the OK knowledge base. Version-controlled, private by default,
human+agent co-editable, renders in live preview, and durable grounding context
for future agent sessions. Implements specs/2026-06-15-codebase-wiki-pack.
What ships:
- `ok seed --pack codebase-wiki` scaffolds `wiki/` with five sections
(architecture / modules / flows / concepts / guides), each carrying
agent-guidance folder frontmatter + a page template, plus an `OVERVIEW.md`
hub stub (frontmatter `profile` + `source_commit` freshness anchors) and an
append-only `log.md`. Installs the pack skill into every set-up editor.
- `workflow({ kind: 'wiki' })` returns a phased, STOP-gated generate/refresh
guide (mirrors `discover`): two natural-language knobs (audience: internal|
public; depth: tour|standard|exhaustive), the source-reference convention
(relative links + code-spans internal; GitHub blob URLs public), and
incremental refresh by diffing `source_commit..HEAD` (DEC-4).
- New pack SKILL.md: genre-detection trigger on the seeded `wiki/` layout,
per-folder rules, knobs, source convention, and freshness + log discipline.
Machinery correctness (DEC-6 — wiki nests under `wiki/` from CLI and desktop
without `--root`):
- The pack is the first to use nested folder paths (`wiki/architecture`) and
folder-prefixed rootFiles keys (`wiki/OVERVIEW.md`). `apply.ts`
`resolveFileContent` previously matched only single-segment folder ids and
bare-filename rootFiles; broadened both so the slashes resolve. The two
id families stay unambiguous (a frontmatter/template id always carries the
literal `/.ok/` segment a rootFile key never does). Guarded by new
plan/apply tests that seed the pack end-to-end.
- Kept the three-way `PackId`/`OkPackId` wire mirror in sync (server / core /
app), enforced by the existing desktop `Eq<>` typecheck guard; added the
picker icon (exhaustive `Record<OkPackId>`).
Tests: starter pinned count 6->7 + per-segment kebab + nested-rootFile safety +
a codebase-wiki structural block; nested-path plan/apply coverage; workflow
`wiki` parity; pack-skill install + build-bundles presence guard.
* chore(ok): address PR review — changeset, rootFiles JSDoc, SKILL.md de-dup
Addresses the claude[bot] review (APPROVE WITH SUGGESTIONS) on #1921:
- Add the missing changeset: a new user-facing starter pack + `wiki` workflow
kind are observable changes to the published `@inkeep/open-knowledge` CLI,
which per RELEASES.md must ship a `.changeset/*.md` (minor bump; body =
release notes). Without it the feature would ship silently in the next beta.
- Document the nested-key `rootFiles` convention on the `StarterPack.rootFiles`
JSDoc: bare filenames vs. slash-prefixed subfolder paths (`wiki/OVERVIEW.md`),
the `/.ok/` disambiguator in `resolveFileContent`, and that
`assertEntryPathInProject` owns path safety — so future pack authors don't
rediscover it.
- De-duplicate the pack SKILL.md against the workflow guide. The verbatim knob
table + source-reference convention now live once, in the
`workflow({ kind: 'wiki' })` guide (the single source of truth for the
procedure); SKILL.md keeps the genre trigger, per-folder rules, and
freshness/log discipline (useful when editing an existing wiki) and carries
tight summaries that point to the workflow guide. Removes the drift risk the
review flagged for the first pack to ship both a SKILL and a paired body.
* chore(ok): address re-review — strip process-citations, harden resolver order
Round-2 claude[bot] re-review (PR #1921) confirmed the prior 3 findings fixed and
raised one comment-discipline violation plus two defensive suggestions:
- Strip process-citation markers from source comments per the repo's
comment-discipline rule ("don't cite the process that produced the code; strip
the citation, keep the substance"). Removed five decision-marker tags and one
spec-path line across starter.ts / apply.ts / wiki-body.ts — all the
load-bearing substance (the wiki-nests-under-`wiki/` constraint, the resolver
disambiguation rationale) stays. Also dropped a stray decision tag from the
agent-facing wiki guide heading (meaningless to the consuming agent) and the
two pre-existing `Per spec` citations in applySeed's JSDoc (same file).
- Harden `resolveFileContent`: run the rootFiles exact-key lookup BEFORE the
folder-id regexes. The lookup cannot false-positive, so ordering it first
makes the frontmatter/template vs. rootFile disambiguation structural rather
than convention-dependent — a rootFile key (even an unusual one containing
`/.ok/`) resolves directly and can never be mis-claimed by a regex. Behavior
unchanged for all shipped packs; covered by the existing nested-path +
unknown-template-id tests.
- Annotate the `wiki` workflow case: note it mirrors discover's no-arg ad-hoc
resolve pattern (bypassing the buildWorkflowHandler factory, which serves the
arg-bearing kinds) so a future contributor knows which path to follow.
* fix(open-knowledge): reconcile codebase-wiki pack with post-merge starter-pack guards
Merging origin/main pulled in new starter-pack conformance guards (#2036
single-block frontmatter, OKF §9 rule 2 typed-doc) and a new pack
(worldbuilding), which the clean textual merge could not reconcile against
the codebase-wiki pack:
- starter.ts: rewrite the 5 codebase-wiki page templates from a stacked
double frontmatter block to a single block with a nested `template:`
identity + a top-level `type` (architecture/module/flow/concept/guide),
satisfying the seed-frontmatter-guard and okf-conformance rule-2 guards.
- starter.test.ts: bump the pinned STARTER_PACK_IDS count 7 → 8 (the
expected-name array already unioned codebase-wiki + worldbuilding in the
merge; only the count + title lagged).
- project SKILL.md: add the `codebase-wiki` awareness bullet so the
skill-pack-list-drift guard (new from main) matches STARTER_PACK_IDS.
All 102 src/seed tests pass.
Claude-Session: https://claude.ai/code/session_01WN4uDxpLLQVN1gQBXv2yw9
* test(open-knowledge): address PR review — 8-pack build guard + strip DEC citations
Resolves the two non-blocking pending recommendations from the PR #1921
re-review:
- build-skill-bundles.test.ts: add `okf` to the shipped-pack SKILL.md guard
and retitle "seven" → "eight". The reconciliation commit bumped
starter.test.ts to 8 but missed this sibling guard, leaving okf's pack
SKILL.md presence unguarded.
- Strip process-citation markers (`DEC-5`/`DEC-6`) from 5 test locations
(3 describe titles + 2 inline comments) per the repo comment-discipline
rule — decision-log references belong in the PR, not source. Substance
(the prose describing the nested-wiki layout) is preserved.
Claude-Session: https://claude.ai/code/session_01WN4uDxpLLQVN1gQBXv2yw9
* Adjust hubs text
---------
GitOrigin-RevId: 2867f693c92b1e7fe3ae22f579ba3632f3398ede
![inkeep-internal-ci[bot]](https://avatars.githubusercontent.com/in/2806322?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Automated approval from agents-private public-mirror-sync (run: https://github.com/inkeep/agents-private/actions/runs/28181975996). Source of truth is the monorepo; direct edits on inkeep/open-knowledge are overwritten on next sync.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add the
codebase-wikistarter pack — an agent-authored, navigable wiki of your codebase.ok seed --pack codebase-wikiscaffolds awiki/knowledge base (architecture, modules, flows, concepts, and guides — each with a page template) plus anOVERVIEWhub and a generation log. The newworkflow({ kind: "wiki" })guide drives an agent to generate — and later incrementally refresh — the wiki from source, with mermaid diagrams, cross-linked pages, and source references, tuned by two natural-language knobs (audience: internal/public,depth: tour/standard/exhaustive). Version-controlled and private by default; the wiki doubles as durable grounding context for future agent sessions.