How to
Install once. Invoke. Review before you merge.
The knowledge base is plain-text Markdown — edit it by hand or drive it with a skill, both are first-class. Whatever you touch, the same gate runs before every merge.
How it works
Two ways to shape the knowledge base.
Everything a skill produces is plain-text Markdown under inspire_kb/. You can write it by hand or drive it through a skill — both are first-class.
By hand
Edit the KB directly
Open any file in inspire_kb/ and write. The layout is designed to be human-editable — follow the conventions in each folder's README and your change passes review. You never need an agent for a small edit.
With an agent
Drive it with a skill
Invoke an /inspire-* skill and it interviews you, generates the artifact in the correct location, and propagates the change across every dependent layer — features, screens, specs, prototype and ADRs.
Reviews are read-only. A skill's review surfaces findings and recommends the next command — it never applies changes. Landing the fix is always the author's call.
The loop
The four moves.
Skills ship as a Claude Code plugin; install it once, then materialize it into your project with one command.
Install the runtime
Add the marketplace, install, reload — /plugin marketplace add Genomcore/inspire, /plugin install inspire@inspire, /reload-plugins — then, in the target repo, /inspire:init.
Invoke a skill
In a Claude Code session, type /inspire-<skill> <subcommand> — for example /inspire-feature create billing/INV-01. The skill does the rest, interviewing you wherever judgment is needed.
Codify it
When the spec is ready, /inspire-code tdd {feature-id} implements it test-first against its acceptance criteria — re-anchoring to the ADRs and descriptors that specify it. For a whole scope rather than one feature, /inspire-emanate run does the same work unattended, in dependency waves.
Review before the PR
Run /inspire-module review {module} for single-module changes, or /inspire-workspace review for cross-cutting ones. This is the required gate before any PR that touches inspire_kb/.
Enforceable
Coherence is protected by design.
The skills are the judgment half. The mechanical half runs at git-time, so drift is caught even when no one remembers to look.
Validators
Bash + yq + jq checks in .inspire/bin/ — no Node toolchain. They enforce the structural rules: acyclic dependencies, stable-blocker invariants, entity lifecycle and cross-field coherence. A sibling tool, trust.sh, lives there too — it stamps and reports provenance but never gates a review.
Git hooks
pre-commit surfaces findings inside the modules you staged; pre-pr re-runs the review across the whole tree as defense-in-depth. Both refuse the call while hard errors remain.
No --no-verify
If a hook fails, investigate the root cause. Bypassing the gate is never the answer.
How prose is written
A knowledge base is read twice.
Once by a person deciding what to build, once by an agent deciding what to generate. The writing contract makes the prose regular enough that both reach the same conclusion from the same sentence — and it binds the artifacts, the review reports and the session's own replies alike.
| Active voice | A passive sentence can omit its actor, and in a specification the actor is usually the thing being specified. |
|---|---|
| One sentence, one claim | A sentence carrying two claims cannot be half-accepted. Length is only where to look for the second one: a forty-word sentence stating one thing is fine. |
| No noun clusters | Stacked nouns compress a relationship into adjacency. A preposition costs a word and removes the ambiguity. |
| One concept, one word | The approved term is the team's own, recorded in 00_bootstrap/glossary.md. Two words for one concept split the graph. |
| One paragraph, one idea | Past that it is two ideas sharing a block, and the second is the one nobody remembers. |
| State what is | Not what an artifact was, not what it will be, not what it is not or will never be. A present-tense prohibition is a rule, not negative space, and it stays. |
| Name the thing | No metaphor, no verbs of mind for a mechanism, no intensifiers. A script returns, refuses and emits; nothing knows or wants. |
| Say it once | No paragraph restating the table above it, no conclusion repeated as a note and again as a finding, no caveat repeated per item. |
The skills carry the whole contract
Every skill that writes a KB artifact applies it while writing, in whatever language the project declares. A rule the writer follows never becomes a finding. session-start injects the same rules into every session, so a reply is held to them too.
prose-style.sh checks the greppable part
Sentence and paragraph length, the closed historical-language tokens, the closed intensifier list, passive voice and noun clusters. The judgment half — metaphor, restatement, the future and the negative space — no script can see. English only: a project declaring another language gets one note and no findings.
Nothing gates a commit on style
Every style check is a warning at every lifecycle state, with one exception: a synonym the glossary rejects becomes an error once the artifact reaches accepted. That check reads a declaration the team wrote down, rather than judging how a sentence reads.
Common scenarios
Where do I start?
The usual path: edit directly for small changes, reach for a skill for new artifacts or cross-cutting work, codify with /inspire-code — and always review before merge.
I have an existing codebase to bring in
/inspire-extract scan {path} — four parallel scanners (stack, screens, logic·API·DB, styles) inventory your code, then consolidate into cross-linked candidate features, screens and domain objects. Read-only; nothing enters the KB without your review.
I want to add a feature to a module
/inspire-feature create {module}/{id} — interviews you for the use case, gates the acceptance criteria before writing it, then points you to screens, the domain descriptor, or the prototype next.
I want to propose an architectural change
/inspire-adr create {slug}, then promote {id} {maturity} as the decision moves design → prototyped → implemented.
I need to design or review a screen
/inspire-screens create {module}/{screen} to author one from a pattern, or validate to check an existing screen for drift.
I need to specify a behavior contract
/inspire-domain define {id} — a socratic interview, not a fill-in-the-blanks form; nothing is written until you approve the shape.
I'm ready to write the code
/inspire-code tdd {feature-id} implements it test-first; /inspire-code review checks a diff against the KB before you merge.
I want a working model of the whole product
/inspire-prototype — scaffold the horizontal mockup from the specs; its insights co-evolve the vault live (features, screens, ADRs).
I'm working without an agent
Edit the Markdown directly following each folder's conventions; run /inspire-workspace review when Claude is back to catch anything the templates don't enforce.
Skills don't write your product.
They keep it coherent while the agents do.