The Knowledge Base

The knowledge base is the accumulated know-how a project draws on when planning: the rules it commits to, the shared vocabulary it speaks, how the system is built, the traps to avoid, what past work taught, and why decisions were made. Spektacular keeps it alongside your code, under .spektacular/knowledge/, so it lives and versions with the project.

It is a planning-time input. When you ask Spektacular to plan a feature, the planning agent reads the relevant knowledge and writes the parts that matter straight into the plan. The implement workflow then works only from the plan documents (it never re-reads the knowledge base), so the plan is the contract.

This is what it solves: without a knowledge base, every plan starts from a blank slate. The agent rediscovers your conventions, walks into gotchas you already mapped, and re-derives decisions you already made. Captured once and reused on every plan, the knowledge base is what lets Spektacular produce plans that fit your project instead of generic ones. It is also why you can trust the output enough to build on it.

Creating. A new entry is written with knowledge write, naming the scope to store it in and the path within that scope. The content comes from a file or standard input:

spektacular knowledge write \
  --data '{"scope": "project", "path": "gotchas/db-timeouts.md"}' \
  --file ./db-timeouts.md

The first segment of the path picks the category (gotchas/db-timeouts.md lands in gotchas) and the entry is stored as raw markdown at <location>/<category>/<name>.md, with any missing parent directories created for you. There is no required frontmatter; an entry’s title is taken from its first heading, falling back to its path.

Searching and retrieving. knowledge search runs a keyword query across every configured source and returns ranked, one-per-document hits, each with a few short excerpts so an agent can scan many results cheaply. Results are scored by how often the query terms appear, with ties broken by source order and then path, so the ordering is stable. knowledge read pulls back a single entry in full.

spektacular knowledge search "database timeout"

The two always-applied categories, conventions and glossary, are deliberately left out of search results. They are already loaded in full on every planning task (via knowledge always-applied), so surfacing them in search too would only repeat the same content.

Keeping it up to date. There is no separate update command: you write the entry again to the same scope and path, and the new content replaces the old. Because entries are identified by the exact bytes of their content, rewriting the same text changes nothing, while genuinely edited text supersedes the previous version.

Knowledge is a planning-time input, not a runtime one. The planning agent reads the knowledge base while producing a plan and writes the relevant parts into the plan itself; the implement workflow then works only from the plan. So the knowledge base shapes what gets planned, and the plan, not a live lookup, is the contract the implementation is held to. This keeps implementation reproducible: the same plan builds the same thing, regardless of how the knowledge base changes afterwards.

One registry is the single source of truth for the category model. The six categories and their tiers are declared once, in code. That single declaration scaffolds a new project’s directories and READMEs, decides each category’s retrieval behaviour, and tells the assistant where a new entry belongs. Adding a category, or moving one between tiers, is a change in exactly one place.

Two tiers, split by how knowledge is retrieved. Always-applied knowledge (conventions, glossary) is the small set every plan must reflect and the vocabulary needed to read everything else, so it is loaded in full each time. Looked-up knowledge (architecture, gotchas, learnings, decisions) is the larger reference body, fetched only when a query matches it. Because tier membership lives in that one registry, re-tiering a category is a single, self-consistent action: the full-load reader starts including it and search stops returning it at the same moment, so the two behaviours cannot drift apart.

De-duplication is exact, not fuzzy. When the same knowledge is written more than once, the mechanical check for “this is already here” matches on exact byte-identity rather than a similarity score. That is deliberate, because lexical similarity does not track meaning: “always retry” and “never retry” are nearly identical text but opposite instructions, while “add jitter to retries” and “randomize backoff intervals” share almost no words yet say the same thing. Exact matching claims the one thing it can prove, that two entries are byte-for-byte the same, and leaves every genuinely semantic judgement to a human or the assistant, which is where that judgement belongs.

Sources are layered, most-specific first. When several scopes hold knowledge about the same thing, the most specific one wins: a project entry overrides a team entry, which overrides a global one. A refinement is resolved in favour of the most-specific source and noted rather than hidden, while a genuine disagreement between sources is surfaced as a conflict instead of being silently resolved.