Specification
Capture what the product is and why — decisions, modules, features, domain, processes, screens, prototypes and spikes — in inspire_kb/.
/inspire-adr
inspire_kb/01_spec/_adr/ (and a module's or face's _adr/)
Owns the lifecycle of Architecture Decision Records at three scopes, set by where the files sit: global (a decision across two or more modules or faces, or system-wide), one module, or one face. Every ADR is a pair of files, the decision and its rationale. Status is a maturity ladder (design → prototyped → implemented) that declares how far the decision's consequences must have propagated.
create
Record a new architectural decision at maturity design
/inspire-adr create <slug>
Asks for a short title, the scope (global, a module or a face), the modules affected, context, decision, consequences and alternatives considered. For a global ADR it also asks for the blast radius, the faces: and bundles: fields. It writes two files side by side in the scope's _adr/: {slug}.adr.md, the decision, with Status: design, and {slug}.adr.rationale.md, the context, consequences, alternatives and related ADRs. Reasons stay out of ## Decision. Every link target that does not exist yet is created as a draft, then the skill proposes the feature files that should link to the ADR and waits for approval before editing them.
- Reads
- the operator's answers · existing faces, bundles and modules · feature files that should reference the ADR
- Writes
- inspire_kb/01_spec/_adr/{slug}.adr.md and {slug}.adr.rationale.md (global) · inspire_kb/01_spec/_modules/{module}/_adr/ (module scope) · inspire_kb/01_spec/_faces/{face}/_adr/ (face scope) · draft link targets · ADR links in feature files (on approval)
Filenames are slug-only: no number and no adr- prefix. The slug is unique across the project whatever the scope, and the id is adr-{slug}. The project's action verbs are recorded in one ADR with the fixed id adr-action-verbs. Every write is checked with review.sh and trust-stamped (trust.sh stamp --skill adr).
update
Edit an ADR in place; only an implemented ADR forces a supersede
/inspire-adr update <id>
Modifies an existing ADR. At design or prototyped maturity either file, including ## Decision, may be edited freely, recording new evidence such as a Prototype: pointer when it drove the change. At implemented maturity both files are frozen: a change to either triggers a warning and an offer to switch to supersede. An ADR still in the single-file shape is offered migrate first.
- Reads
- the target ADR and its rationale
- Writes
- the target ADR and its rationale
Rewriting an ADR that carries an endorsed: block is disclosed to the operator first.
promote
Advance maturity (design → prototyped → implemented) and check propagation
/inspire-adr promote <id> <maturity>
Verifies the transition is a single forward step, then sets Status in the decision file. prototyped requires a Prototype: pointer to the external repo that validated the decision; implemented records where the decision lives in the codebase. It runs /inspire-module review on every affected module to find where the consequences are not reflected yet, and lists the gaps as follow-up actions. It then asks whether to endorse the decision, and separately the rationale.
- Reads
- the ADR · the affected modules' design workspace (features, screens, prototype, specs)
- Writes
- the decision file's Status line and evidence pointer
Skips and downgrades are rejected; refine with update instead. Each endorsement (trust.sh endorse) is written only on an explicit yes.
supersede
Retire an ADR in favour of a new one and wire both links
/inspire-adr supersede <id> <new-id>
Checks both ADRs exist; the new one must already have been created with create. Sets the old decision to Status: superseded by a link to the new decision file and adds Supersedes: with a link to the old one to the new decision's header. The old rationale stays as it is. Then it searches inspire_kb/ for links to the old ADR's file and proposes updating each path.
- Reads
- both ADRs · every inspire_kb/ link to the old ADR
- Writes
- both decision headers · links across the KB (proposed)
Works at any non-terminal maturity. It is the required path for changing either file of an implemented ADR.
migrate
Split single-file ADRs into a decision and a rationale
/inspire-adr migrate [<id>...]
Takes the ids given, or every *.adr.md under inspire_kb/01_spec/ with no rationale beside it. It lists them with adr-split.sh --list, discloses any that carry endorsed:, then runs adr-split.sh, which moves every line verbatim: the frontmatter, the header and ## Decision stay in {slug}.adr.md and every other section moves to {slug}.adr.rationale.md. A file with no ## Decision is skipped and written with the operator. For each split ADR it shows the sentences in ## Decision that are reasons and offers to move them to the end of the rationale's ## Context. Both files are stamped.
- Reads
- single-file ADRs · the ADR's endorsed: block
- Writes
- {slug}.adr.md and {slug}.adr.rationale.md for each ADR
Allowed at implemented maturity because it changes no word. It proposes no endorsement. /inspire:update offers it and counts the single-file ADRs; it never runs it.
/inspire-module
inspire_kb/01_spec/_modules/{module}/
Owns a module's directory and its hub ({module}.module.md), and keeps the hub in sync with the module's features, entities and actions, ADRs and processes, and with the screens that use it. The module is the product's organizing unit, and keeping the hub and what it links in agreement is this skill's core invariant. A module holds no screens: they live in the faces.
create
Scaffold a new module hub
/inspire-module create <module>
Takes a module name, an ID prefix and a description. It first applies a name gate: names broad enough to cover the whole product, such as platform or core, are flagged with a suggested alternative, and a module id never starts with _. It writes the hub from the template; writing the hub is what registers the module, since the set of modules is the set of *.module.md files. It then points to /inspire-feature create, /inspire-face for the bundle that exposes the module, and /inspire-prototype as next steps.
- Reads
- the operator's inputs · existing module hubs
- Writes
- inspire_kb/01_spec/_modules/{module}/{module}.module.md
The subdirectories (_features/, _domain/, _adr/, _processes/) are created by the skill that writes the first file in each. Screens are not created here: /inspire-screens writes them in the face that shows them. Exposure is not created here either: it belongs to the bundle files, owned by /inspire-face.
review
Read-only consistency review of a module across all layers
/inspire-module review <module>
The required gate before any PR that touches the module's hub or features. It checks that the hub's links match what the module holds (every *.feature.md, *.entity.md, *.action.md and *.adr.md in its directory, and every screen in any face that declares the module or binds one of its actions), the structure of those screens, the writing contract and links, and cross-layer coverage: features against screens, prototype, actions and current ADRs at every scope. It runs .inspire/bin/review.sh on the module's directory, consolidates prototype drift and flags overengineering. Every finding names the skill to run for the fix.
- Reads
- the hub · the module's directory · screens in the faces that use it · global, module and face ADRs · prototype · task tracker
- Writes
- nothing (read-only)
Pending prototype drift is informational and only blocks when it contradicts a current ADR.
update
Add or remove use cases, rename or restructure, propagating across layers
/inspire-module update <module>
Reads the hub, everything under the module's directory and the screens that use its actions, presents a diff proposal and applies it on approval, creating every missing link target as a draft. A module rename is atomic across the KB and the source: the directory and hub, the ID prefix and every feature id, entity and action ids and the links that carry them, the module: field of every screen in every face (which changes its route), every bundle that lists the module, tracker epics, ADR references, the source module directory and the @covers test annotations, moved with git mv. Finishes by running review.
- Reads
- the hub · the module's directory · screens in every face · bundles · source (on rename)
- Writes
- the hub and the affected files (on approval)
Writes only after the operator approves the plan. Entity and action file names do not carry the module, so they stay as they are on a rename.
scan
Find features without realizing actions and hand off to /inspire-domain
/inspire-module scan [<module>]
Entry point for domain work. It checks the git worktree and branch (feat/sdd-{module}) and offers to create a worktree if needed. It reads the actions declared in the hub and the module's *.feature.md files, canonicalizes their ids to singular form and marks those with no *.action.md descriptor as candidates. It narrows the set through dialogue and, once the operator says start, creates one task per chosen action and runs /inspire-domain define on the first. It ends with an audit of features without realizing actions, orphan actions and coherence conflicts.
- Reads
- the hub · the module's features · the module's _domain/
- Writes
- nothing in _domain/ (read-only); session tasks when authoring starts
Valid as pure exploration. Without an argument it scans every *.module.md.
delete
Remove a module and clean every cross-reference
/inspire-module delete <module>
Lists every file and feature that will be removed and asks for confirmation. Then deletes the module's directory, which takes its hub, features, domain, ADRs and processes together, and every *.screen.md in any face that declares module: {module}. Screens of other modules that bind its actions, bundles that list it, and global or face ADRs and processes that reference it are flagged for the skill that owns them. It removes the module's screens and routes from every face's prototype shell and notes spikes that referenced it, then searches the KB for references and offers fixes.
- Reads
- the whole inspire_kb/ · prototype
- Writes
- deletes _modules/{module}/ and the module's screens in every face · prototype routes
Requires explicit confirmation before deleting anything.
/inspire-feature
inspire_kb/01_spec/_modules/{module}/_features/
Owns feature (use case) files, one per use case at _modules/{module}/_features/{use-case}.feature.md, and their propagation to screens, prototype, domain and ADRs. The id is the file name without the extension. The use-case file is the source of truth that everything downstream realizes, and it describes what the user experiences, not how it is built.
create
Write a new use-case file after the acceptance-criteria gate
/inspire-feature create <module>/<feature-id>
Verifies the module exists, then asks for name, description, actors, dependencies, priority, state (Planned by default), referenced ADRs and blast radius (the faces: and bundles: fields). It runs the acceptance-criteria quality gate, giving each criterion the next free AC-n id, and writes the file from the use-case template. Every link target that does not exist yet is created as a draft. Then it suggests next steps: /inspire-screens if the feature has UI, /inspire-domain define if it has behavior, /inspire-prototype when ready.
- Reads
- the module hub · existing feature ids · referenced ADRs
- Writes
- inspire_kb/01_spec/_modules/{module}/_features/{feature-id}.feature.md
Preconditions, main flow and postconditions carry keyed entries (P{n}, B{n}, Q{n}) beside AC-{n}. Keys are write-once and never renumbered. The gate checks that each criterion is complete, testable and verifiable and covers every error the feature's actions declare; tests claim criteria with @covers {feature}/AC-n. The file is checked with review.sh and trust-stamped (--skill feature).
review
Coverage review of one feature, or all features of a module in parallel
/inspire-feature review <feature-id|module>
Single mode locates the use case and checks it layer by layer: screen coverage in each face of its blast radius, prototype coverage under that face's shell and any drift, realizing action descriptors in the module's _domain/, and whether referenced ADRs are current. Output is a coverage matrix plus issues. Batch mode lists all features of the module, asks for confirmation, runs one agent per feature in parallel and combines the results into a single report with a correction plan.
- Reads
- the use-case file(s) · screens in the faces · prototype · the module's _domain/ · ADRs
- Writes
- nothing (read-only)
Features with no UI are marked N/A rather than flagged. A feature can be covered in one face and uncovered in another.
update
Change description, dependencies, priority, state or name
/inspire-feature update <feature-id>
Reads the use case and presents a diff proposal. If the acceptance criteria change, it runs them through the quality gate first: existing AC ids are kept, new ones take the next free id and deleted ids are never reused. Applies the change on approval. On a rename it renames the file to {new-id}.feature.md, searches the KB and the code for the old id (@covers citations included) and offers fixes, then runs review.
- Reads
- the use-case file · references to its id
- Writes
- the use-case file (on approval)
State moves (Planned → In progress → Implemented) are written here.
scan
Infer the actions a feature needs and hand off to /inspire-domain
/inspire-feature scan <feature-id|module>
Runs the same phases as /inspire-module scan (worktree check, candidate narrowing dialogue, chained /inspire-domain define), scoped to one feature or to every feature in a module. It infers the actions that would realize the feature from the feature text and ends with an audit of features with no realizing action, partial realization and lifecycle mismatches.
- Reads
- the feature file(s) · the module's _domain/
- Writes
- nothing in _domain/ (read-only)
Authoring happens only through /inspire-domain.
delete
Remove a use case and check for orphans in other layers
/inspire-feature delete <feature-id>
Removes the use-case file after the operator approves the plan, then checks screens, prototype, actions and ADRs for references the deletion leaves orphaned.
- Reads
- the use-case file · references across layers
- Writes
- deletes the use-case file; reference fixes on approval
Deleting without cleaning up references counts as drift.
/inspire-domain
inspire_kb/01_spec/_modules/{module}/_domain/
Owns the domain layer: action descriptors ({entity}.{action}.action.md, behavioral contracts) and entity documents ({entity}.entity.md, why the entity exists and what shapes its fields), both in a module's _domain/{entity}/, with a draft → accepted → stable lifecycle. Authoring is an interview run one question at a time, and the entity's Fields and Touched by tables are rebuilt after every change.
define
Author a new action or entity through a guided interview
/inspire-domain define <module::entity[::action]>
Requires a full id; a partial id is redirected to /inspire-module scan. It first decides the authoring context (fresh, field addition or targeted revision), loads the interview prompt catalogue and reads the source feature and ADRs. It then walks the sections one question at a time: Purpose, Inputs, Outputs, Entities, Behavior, requires and Errors for an action, or Purpose, Rationale, Invariants and Fields for an entity. When stack.md declares two or more datastores, it asks which one an entity's rows live in and writes datastore: only when it is not the default; it never infers it. Each section is written to disk as soon as it is settled, and the touched entity document is updated in the same flow.
- Reads
- the source feature · referenced ADRs · adr-action-verbs, when it exists · the interview prompt catalogues · existing entity documents
- Writes
- inspire_kb/01_spec/_modules/{module}/_domain/{entity}/{entity}.{action}.action.md and/or {entity}.entity.md
Refuses a descriptor whose Purpose has no link to a feature; if the feature does not exist, run /inspire-feature create first. Every link to an object that does not exist yet creates it as a draft. The new action's verb is checked against the project's action-verbs ADR. Commits stay with the operator.
show
Render a descriptor with every link resolved inline
/inspire-domain show <id>
Reads the descriptor, opens the target of each link and expands it into the target's title and first paragraph, quoting the feature passage a link with an anchor points to. It shows the expanded view in the conversation.
- Reads
- the descriptor · linked targets
- Writes
- nothing (read-only)
update
Patch an existing descriptor; refuses stable objects
/inspire-domain update <id> [change] [--full]
Shows the descriptor and applies the requested change, which may be written in plain language after the id; otherwise it asks what to change. Every new claim needs a link to its source feature. It shows a unified diff, writes on approval, then rebuilds the affected entity document. New content for a section goes through the matching part of the interview, and --full walks every field.
- Reads
- the descriptor · feature sources
- Writes
- the descriptor · the entity document's derived tables
A stable object cannot be updated: demote it, update it, then promote it back.
refactor
Rename, split or merge actions, confirming each consumer
/inspire-domain refactor <id> [args]
Asks whether this is a rename, split or merge. It lists every descriptor that requires or links to the action and shows each consumer's proposed diff for individual confirmation. Once all are confirmed, it applies the change, renames or deletes source files and rebuilds the entity documents.
- Reads
- the action · all consumer descriptors
- Writes
- renamed/split/merged descriptors · confirmed consumers · entity documents
No batch update and no --cascade flag.
delete
Remove an action; refuses while other actions require it
/inspire-domain delete <id>
Checks the module tree for actions that list the target in requires:. If any exist, it lists them and stops, suggesting their requires entries be changed first or that the action be promoted to superseded. Otherwise it asks for confirmation, deletes the file and removes the action's rows from the entity document.
- Reads
- the domain tree
- Writes
- deletes the descriptor; updates the entity document
No --cascade flag.
promote
Move an object forward in its lifecycle through the quality gates
/inspire-domain promote <id> <accepted|stable|superseded>
Reads the current lifecycle and refuses a no-op, or a move to superseded without a superseded_by pointer. It runs .inspire/bin/review.sh for the target state: error findings block the move, warnings need an explicit yes. It writes the new lifecycle and rebuilds the entity document when moving to stable or superseded.
- Reads
- the object · review.sh findings
- Writes
- the object's lifecycle field · the entity document (on stable/superseded)
A target earlier than the current state is redirected to demote. It may offer to endorse the object (trust.sh endorse) and does so only on an explicit yes.
demote
Move an object back one lifecycle step; refuses with a list of dependents
/inspire-domain demote <id>
Moves stable → accepted or accepted → draft. Before changing anything it finds consumers that would break: stable consumers when demoting from stable, accepted or stable consumers when demoting from accepted. If there are any, it lists them and stops. Otherwise it asks for confirmation, writes the change and rebuilds the entity document when leaving stable.
- Reads
- the object · all requiring descriptors
- Writes
- the object's lifecycle field
Refuses objects already at draft or superseded. Only the operator can start it; no --cascade flag.
review
Run the quality rules over a scope and report findings
/inspire-domain review [<scope>]
Runs .inspire/bin/review.sh on the scope and shows each finding by severity, rule and target, with a suggested follow-up. Rules come in three tiers: mechanical blockers (lifecycle-valid, requires-resolves, acyclic-deps, and others), coherence blockers (sections-present, no-todos, entity-coherence, entity-datastore, stable-blockers, and others), and checks that tighten as the lifecycle advances. A summary with pass/fail comes first.
- Reads
- descriptors in scope
- Writes
- nothing (read-only)
Never fixes anything itself.
source
Show the source behind every claim in a descriptor
/inspire-domain source <id>
Collects every link in the descriptor body, resolves each one and quotes the linked passage claim by claim. Sentences with no link are flagged as possible gaps that update can fill.
- Reads
- the descriptor · linked features, ADRs and actions
- Writes
- nothing (read-only)
graph
Print the action-to-action requires graph with supersession edges
/inspire-domain graph [<scope>]
Prints the requires graph for the scope as a tree, with each target's lifecycle, superseded_by edges and any cycles marked CYCLE. It also lists a ready queue: accepted actions whose requires targets are all stable, so they can be promoted next.
- Reads
- descriptors in scope
- Writes
- nothing (read-only)
/inspire-process
inspire_kb/01_spec/_processes/ (and _modules/{module}/_processes/, _faces/{face}/_processes/)
Owns processes: system behaviour that no actor invokes directly, started by a schedule, an event, start-up or another process. A process calls actions in order and changes the domain only through them. It is one {process}.process.md with the id {scope}.{process}, where the scope is global, a module or a face. If a person starts it, it is a feature, not a process.
create
Write a new process file at global, module or face scope
/inspire-process create <scope>/<process>
Asks what starts it; if the answer is a person, it stops and offers /inspire-feature instead. It settles the scope with the operator, choosing the narrowest scope whose domain the process touches, and the module or face must already have its *.module.md or *.face.md. It validates the id ({scope}.{process}, a slug that never starts with _ and is unique), then interviews the sections in template order: Trigger, Requires, Before, Behaviour (steps keyed B{n}), After and Affects. Every action or entity that does not exist yet is created as a draft. It writes the file with lifecycle: draft and offers the link back from a module's hub to /inspire-module.
- Reads
- the operator's answers · the scope's module or face file · existing actions and entities
- Writes
- inspire_kb/01_spec/_processes/{process}.process.md (global) · inspire_kb/01_spec/_modules/{module}/_processes/ (module scope) · inspire_kb/01_spec/_faces/{face}/_processes/ (face scope) · draft actions and entities it links
Exactly one trigger. Requires and Affects produce no test of their own; the trigger, each step and each pre- and post-action become claims INSPIRE Factory derives. Keys are write-once. The file is checked with review.sh and trust-stamped (--skill process).
update
Change a process's trigger, actions, steps or affects
/inspire-process update <process-id>
Reads the file and presents the plan, which sections change and why, before writing. A new step takes the next free B{n}, a removed step leaves its gap, and a change of meaning is a new key. Moving a process to another scope changes its id, so the skill moves the file, rewrites the links to it and tells the operator that a process the Factory has built is cited by its old id. Every new link gets a file as in create.
- Reads
- the process file
- Writes
- the process file (on approval) · links to it when its scope changes
Writes only after the operator approves the plan.
review
Read-only check of one process, or every process of a module, a face or global
/inspire-process review <process-id|scope>
Runs .inspire/bin/process-shape.sh, which checks that ## Trigger holds something, that ## Requires links at least one action, that every entity in ## Affects is touched by a required action, and that the id is {scope}.{process}. It then adds judgment checks: whether it is really a process, whether the scope is the narrowest, whether the trigger is testable, whether steps and pre- and post-actions agree with Requires, and what happens when a step fails.
- Reads
- the process file(s) · the actions they require
- Writes
- nothing (read-only)
Findings use the shared operator-facing format; validator findings name their rule.
/inspire-screens
inspire_kb/01_spec/_faces/{face}/_screens/
Owns screen specifications, one file per navigable view ({slug}.screen.md) in the face that shows it, with the id {face}.{slug}. Each screen declares its own bindings (parameters, data, dispatches, navigation, states) and how each value is drawn, and names a pattern, a layout and components from the shared catalog in _design-system/. Routes derive from module and screen under the face's shell and are never written into files. There are no shared screens: faces share structure through layouts and patterns.
create
Scaffold a screen in a face: mint its id, declare its bindings, name a layout
/inspire-screens create <face>.<slug>
Checks the ground first: the design system names the supported viewports and the reference, the face has its {face}.face.md and its shell layout exists. It identifies the covered features, resolves the face and mints the id {face}.{slug} at lifecycle draft. It asks one question for the ## Purpose paragraph, then declares ## Bindings: ### Parameters (what the screen is opened with), ### Data, ### Dispatches, ### Navigation and ### States. It runs face-exposure.sh to check that every bound action belongs to a bundle of the face. It names a pattern only if one fits, names the layout that frames it, links the components and writes ## Render, which says how each value is drawn.
- Reads
- *.feature.md files · the face's {face}.face.md · _design-system/ (patterns, layouts, components, design-system.md) · the reference (the prototype by default)
- Writes
- inspire_kb/01_spec/_faces/{face}/_screens/{slug}.screen.md · draft screens, catalog entries and actions it links
No routes, no ASCII layout diagrams, no inline mock data. A face that does not exist goes to /inspire-face add. A named component gets its entry in the same turn at State: to-extract. Afterwards it asks whether to carry the change to the prototype.
update
Edit an existing screen or bring an older-shape one to the current shape
/inspire-screens update <id> [args]
Finds the screen by searching *.screen.md frontmatter for its id and applies the change to its bindings, pattern, layout, components, Purpose, deviations or notes. A file of an older shape that has no identity block gets one, minted once at draft. The id, module, screen and lifecycle fields are never rewritten.
- Reads
- the screen file
- Writes
- the screen file
Refuses stable screens: move them back to accepted with promote, update, then promote again. Taking a screen to another face is a create plus a supersession, or a split run by /inspire-face.
validate
Validate a screen against its pattern, components and the running prototype
/inspire-screens validate <id>
Checks whether the pattern still fits, whether pattern regions and bindings match up and whether the screen contradicts any component, layout or design-system entry. When it can, it launches the prototype, visits the derived routes and compares what is rendered with the spec. Prototype-ahead-of-spec drift is reported separately, and the spec is updated to match.
- Reads
- the screen · _design-system/ catalog · *.feature.md files · the running prototype
- Writes
- the screen spec when it is stale
On functional drift the prototype wins and the spec is updated; on UI conventions (patterns, layouts, components, design tokens, current UX ADRs) the catalog wins. A prototype feature with no feature file triggers a question to the user.
promote
Move a screen through draft / accepted / stable / superseded, both directions
/inspire-screens promote <id> <state>
Confirms the target state and re-runs the checks for it. draft → accepted locks the bindings and runs face-exposure.sh, which refuses the promotion if the screen binds an action no bundle of its face exposes. accepted → stable requires every declared component at State: implemented and every named pattern to have its regions declared. Moving backwards re-runs no gates; superseded requires superseded_by to resolve to an existing screen.
- Reads
- the screen · declared components and patterns · the face's bundles
- Writes
- the screen's lifecycle field
Screens have no demote command; promote handles both directions. A superseded screen cannot move back; create a new screen instead.
routes
Render the route map and the screen transition graph, per face
/inspire-screens routes [<face>]
Builds one table per face of screen id, route and lifecycle, with each route derived as {shell}/{module}/{screen} from the screen's own fields and each path parameter appended as a segment. It flags route collisions. It also builds a transition graph per face from Navigation rows and Dispatches outcomes, listing unreachable screens and dangling targets.
- Reads
- all *.screen.md files · each face's {face}.face.md
- Writes
- nothing (read-only)
Neither view is ever saved to disk.
backfill
Bring every screen, layout and component up to the current presentation shape
/inspire-screens backfill [<reference>]
Fills the presentation half of a KB written before layouts and ## Render: the shell layout, one layout per distinct geometry with its breakpoints, how every value is drawn, and the component entries those name. It first checks that the design system is ready, resolves the reference (the prototype by default), and lists the gaps with screen-presentation.sh. Each row is sourced from a token, from design-system.md, from the reference or marked generated or undecided. If no reference is available, every value is generated from the tokens first.
- Reads
- screen-presentation.sh findings · the design system and its token file · the reference
- Writes
- layouts, component entries and the presentation sections of screens in the gap list
It never touches an id, a lifecycle, a binding, ## Purpose or a feature link, so it re-emanates nothing and may run on a stable screen. /inspire:update runs it after /inspire-bootstrap design-system backfill when the KB has a presentation gap.
audit
Scan a face's screens for drift, duplication and extraction candidates
/inspire-screens audit <face>
Runs the validate checks across every screen in a face, including drift in both directions against the running prototype under that face's shell. It also uses the catalog rules to find duplicated UI that should become shared patterns, layouts or components.
- Reads
- the face's screens · the catalog · the running prototype
- Writes
- nothing (report)
/inspire-prototype
prototype/
Builds and evolves the horizontal prototype: a wide, shallow, mock-data model of the whole product used to see and steer functional and UI/UX decisions. What the prototype teaches goes back into the KB through the skill that owns each artifact; the prototype keeps no learnings file of its own.
(no command)
Scaffold or iterate the horizontal prototype from the specs
/inspire-prototype
Before writing code, reads the screen spec, its pattern and layout, its ## Render table, the shared components, the design system and tokens, and the source feature and domain files. Builds only what the spec says, using mock data and existing components. As the user reacts, each insight is applied to the KB in the same session through the owning skill (/inspire-feature, /inspire-screens, /inspire-face, /inspire-domain, /inspire-adr). It then runs the prototype and walks through the affected flow before calling it done.
- Reads
- *.screen.md, *.pattern.md, *.layout.md and *.component.md files · design-system.md and design-system.tokens.json · *.feature.md, *.entity.md and *.action.md files · every *.face.md
- Writes
- prototype code under prototype_root · KB artifacts via the owning skills (after proposal)
The skill defines no subcommands. No tests, auth or persistence. It keeps one shell per face, mounted at the face's shell:, and with two or more faces a landing page in front of them that is derived from the face files. Each mocked action call stays inside its face's bundles. Changes to shared artifacts are proposed to the user before they are written. Where it lives is prototype_root in stack.md; none means the project has no prototype.
/inspire-spike
inspire_kb/06_spikes
Registers vertical spikes (narrow, deep, throwaway builds in their own external repos) and brings their learnings into the KB as a gap analysis. The skill never builds the spike itself.
register
Record an external spike repo and prepare learnings capture
/inspire-spike register <name>
Creates 06_spikes/{name}.md from the template with the repo link, the question it explores, its scope and the features it covers. It checks the spike repo's CLAUDE.md for a structured place to record learnings. If there is none, it proposes adding a Learnings section and a Learnings.md file. A hand-maintained index block in 06_spikes/README.md is the operator's, and the skill only suggests removing it.
- Reads
- the external spike repo (read-only)
- Writes
- inspire_kb/06_spikes/{name}.md
Writing into the external repo needs explicit operator permission.
capture
Compare the spike's findings with the KB and record what applies
/inspire-spike capture <name>
Imports the spike's Learnings.md, or reads its code around the relevant feature if there is none. It compares the spike against features, entities and actions, screens, processes and ADRs under inspire_kb/01_spec/ to see what it proves, contradicts or extends. It separates the real finding from the spike's throwaway shortcuts, asking the operator when unsure. It writes self-contained learnings to the spike note, routes actionable ones (for example an ADR promote to prototyped) and records the outcome.
- Reads
- spike Learnings.md or code · the *.feature.md, *.entity.md, *.action.md, *.screen.md, *.process.md and *.adr.md files under 01_spec/
- Writes
- inspire_kb/06_spikes/{name}.md · follow-ups via /inspire-adr, /inspire-feature, /inspire-domain; a learning that links a missing file creates it as a draft through its owning skill
Learnings must make sense even if the spike repo disappears.
Codification
Coding runs in INSPIRE Factory. Six stack skills carry the conventions it reads — layering, tests, bindings, persistence — each scoped to the units whose stack lists it.
inspire-code-react
.claude/skills/inspire-code-react/
React conventions for a face's package. Served to the units whose stack.md profiles: lists react, together with inspire-code-typescript, the language it names. It is a skill the coding agent reads, not a command; coding itself runs in INSPIRE Factory. Rules use MUST, MUST NOT, SHOULD and MAY.
stack: react
layer: frontend
language: typescript
Layering
Components render, hooks orchestrate, services hold logic, repositories reach data
## Layering
Components render and hold local UI state only. Hooks orchestrate state and side effects. Use-cases and services hold the business logic. A repository layer puts all data access behind an interface with a mock/real switch, and a hook is the only caller of the api/ client. Global state lives in a dedicated store.
Module boundaries are not yet formulated for this stack.
Test conventions
Testing Library by role, a centralized mock layer, GIVEN/WHEN/THEN
## Test conventions
Unit and component tests use the component test runner with Testing Library, querying by role first and asserting what the user sees. E2E uses the project's browser test runner against the running app. Tests are GIVEN/WHEN/THEN, and mocks live in a shared tests/**/mocks/ layer, never inline. Run with npm run test and npm run test:e2e.
The authoring detail is in references/testing.md.
Forbidden patterns
No logic or data fetching in components, no inline mocks, no hardcoded strings
## Forbidden patterns
Business logic and data fetching do not belong in components. Tests do not define mocks inline. User-facing strings go through the i18n or constants layer. External URLs are sanitized before use in href or navigation, and dangerouslySetInnerHTML never receives unsanitized input.
Review focus
Styling, accessibility and security lenses
## Review focus
Styling uses the design-system tokens (a token {color.primary} is the CSS custom property --color-primary) and the shared component layer. Accessibility requires keyboard-navigable elements with roles and labels and announced form errors. Security requires validated input and protection against XSS and open redirects.
Quality gates
Not yet formulated for this stack
## Quality gates
Deferred: the gates were measured on a NestJS codebase and this stack has had no equivalent iteration. The shared rules still bind, so a project derives its own gates from a frontend iteration. The candidates named are the type-aware typescript/no-unsafe-* rules and typescript/ban-ts-comment in .oxlintrc.json, the escape-hatch plugin from inspire-code-typescript, oxlint's react/rules-of-hooks and react/exhaustive-deps, its jsx-a11y plugin and a bundle-size budget.
Build & verify
The concrete build, lint, type-check and test commands
## Build & verify
build: npm run build. lint: npm run lint (oxlint). format: npx oxfmt --check. types: npx tsgo --noEmit. tests: npm run test (vitest run) and npm run test:e2e. The default toolchain is oxlint with oxlint-tsgolint for the type-aware rules, oxfmt, tsgo and Vitest transforming through SWC; a project whose stack.md names other tools uses its own commands. In a monorepo every command is scoped to the face's package, for example pnpm --filter {package} build, and never run workspace-wide when a filtered form exists.
Routes
How module: and screen: become a route inside the face's shell
## Routes
A route is /{module}/{screen}, both kebab-cased, derived from the screen's frontmatter and never from its file path or id. A screen named index renders the module's landing route, and a screen identifying one entity appends /:{param}. The face contributes only its shell prefix. There is one route table per face, generated from its screens, and code resolves every route through routeOf('{screen id}'). The table also carries each screen's module and face from its frontmatter, read through moduleOf('{screen id}') and faceOf('{screen id}'): code never reads either from the id, whose first segment is the face and which a migration can rewrite.
A seed: the project's own convention. Code follows it exactly as written until the project edits it. /inspire:update keeps an edited seed and asks only if the release changed the same file.
Bindings
How a screen's ## Bindings keys reach an action
## Bindings
One client function per action, named from the dotted id (auth.user.list becomes authUserList()), in the face's api/ layer. Data keys become one query hook per key on TanStack Query, with cache key ['{screen-id}', '{key}']. Dispatch keys become mutation hooks whose On success and On error outcomes become navigation, state writes or cache invalidation. State keys are a slice of the screen's own store, and navigation keys use navigate(routeOf(...)). A postcondition head of created, updated or deleted makes an action a mutation.
A seed: the project's own convention. Code follows it exactly as written until the project edits it. /inspire:update keeps an edited seed and asks only if the release changed the same file.
Persistence
Not applicable: a face owns no store
## Persistence
Every write leaves through a dispatch binding to a backend action, and that action's profile owns persistence. Browser storage is UI state only, never a source of truth.
Declaration-only tree
How the bodies-stripped tree is produced for the test phase
## Declaration-only tree
The recipe is the language skill's (inspire-code-typescript). Component and hook signatures survive as .d.ts, props types included, and JSX bodies do not. Routes are absent from a packed tree, so the test phase derives them from the Routes section.
References
Deeper files read on demand
## References
Points to references/testing.md: the GIVEN/WHEN/THEN comment discipline and the centralized mock architecture with its extension steps. It is read before writing or modifying any spec or mock.
inspire-code-nestjs
.claude/skills/inspire-code-nestjs/
NestJS conventions for a bundle's package. Served to the units whose stack.md profiles: lists nestjs, together with inspire-code-typescript. The gates: list in its frontmatter is the machine-checkable half of Quality gates, verified by profile-gates-installed.sh. It is a skill the coding agent reads, not a command; coding itself runs in INSPIRE Factory.
stack: nestjs
layer: backend
language: typescript
gates: [...]
Layering
Four layers: domain, infrastructure, application, controllers
## Layering
domain/ holds pure TypeScript types with no framework imports. infrastructure/ holds persistence entities, repositories with a toDomain() mapper and adapters for external systems. application/ holds the services, one primary service per aggregate. controllers/ holds DTOs and the controller, which calls one service method and never catches errors; domain errors reach HTTP through an exception filter. A module exports only its application services, and the database client lives in src/common/<system>/ from its first use.
Test conventions
Object Mothers, unit specs per service, e2e against the assembled app and a real database
## Test conventions
Test data comes from Object Mothers built with faker. Every application service has a unit spec covering every branch. E2E specs are written first from the acceptance criteria and run against the assembled application and a real database, through the real guard. Every database repository has its own e2e suite. A level roll-call before a cycle closes lists the spec each touched file requires. Both suites run on Vitest through SWC, which Nest's dependency injection needs for decorator metadata. Each e2e file gets its own database, copied from one template the global setup migrates once, and the config runs the files one at a time, the choice that is safe on any machine; running them side by side is left to the factory's e2e check. Run with npm run test and npm run test:e2e.
The authoring detail is in references/testing.md.
Test infrastructure
The probe recipe to run before the first red test
## Test infrastructure
Checks that every component stack.md declares is up and healthy (docker compose config --services, then docker compose ps) before the first red test. It never starts a component: an attended run asks the operator to run docker compose up -d, and an unattended INSPIRE Factory run refuses and names the unhealthy components. A connection error is not red; it is a suite that never ran.
Forbidden patterns
No HTTP exceptions in services, no validation in repositories, no silent mutations
## Forbidden patterns
Services throw a generic Error with cause and never HTTP exceptions. Repositories do not validate input. DI uses the concrete class, or an abstract class when there are several implementations, never an interface with a string token. Class names do not carry an ORM or database technology. Every meaningful create, update or delete emits the project's typed audit event from the service layer.
Review focus
API contract and security lenses
## Review focus
api-contract: routes carry @ApiOperation and @ApiResponse, DTO fields carry @ApiProperty, the OpenAPI document is served at /api/docs and request DTOs validate at the boundary. security: new endpoints, guards and auth logic pass OWASP checks, covering authorization, input validation and no sensitive data in logs or errors.
Quality gates
Absolute and ratcheted gates, rules dropped with a reason, and the escape hatches the linter refuses
## Quality gates
Absolute oxlint gates in .oxlintrc.json include type-aware linting, the strict any and non-null rules named one by one, max-depth, max-lines-per-function, import/no-cycle, the layer boundary as one no-restricted-imports override per layer, the vitest rules and reportUnusedDisableDirectives. complexity is deliberately not adopted, with the measured reason written. Coverage is ratcheted through coverage.thresholds in vitest.config.ts. Mutation score as a ratcheted metric is dropped with its reason. Escape hatches are allowed or refused by the lint config, never counted: @ts-expect-error needs a description and @ts-ignore is refused, as any and x! are refused, and the three rules of the escape-hatch plugin are gated: a disable names its rules and says why, no inline comment re-allows a refused rule, and as unknown as is refused. A spec file that needs a negative-path cast gets a permanent config override, never a disable. On existing code, the refused rule is turned off by path in an overrides entry, and that list is the baseline.
Build & verify
The concrete build, lint, type-check and test commands
## Build & verify
build: npm run build. lint: npm run lint (oxlint). format: npx oxfmt --check. types: npx tsgo --noEmit. tests: npm run test and npm run test:e2e (vitest run). The default toolchain is oxlint with oxlint-tsgolint, oxfmt, tsgo and Vitest with unplugin-swc; a project whose stack.md names other tools uses its own commands and declares its own gates:. In a monorepo every command is scoped to the bundle's package, and e2e still runs against a real database.
Bindings
How an action id becomes a route and a guard
## Bindings
The path is derived from the id {module}::{entity}::{verb}: create is POST /{module}/{entities}, list is GET, get is GET /{id}, update is PATCH /{id} and delete is DELETE /{id}. Any other verb is a named POST operation. One controller per entity carries all its routes. An actor({role}) precondition renders as the route's role guard, and no such precondition means a public route. Three claims derive per action: the route exists, it dispatches to the service method, and its guard matches the actor constraint.
A seed: the project's own convention. Code follows it exactly as written until the project edits it. /inspire:update keeps an edited seed and asks only if the release changed the same file.
Persistence
TypeORM against the seeded Postgres stack
## Persistence
One table per domain entity, named with the plural the binding path uses, in snake_case, and snake_case columns whose types come from inspire-code-typescript's Rendering table. A field's Constraints line renders as column constraints, and immutable becomes a BEFORE UPDATE trigger in the same migration. The persistence entity lives in infrastructure/ and is not the domain entity. Migrations live in src/migrations/ and are append-shaped, and synchronize: true is never used outside a throwaway local run.
A seed: the project's own convention. Code follows it exactly as written until the project edits it. /inspire:update keeps an edited seed and asks only if the release changed the same file. A project on another ORM replaces the section wholesale.
Declaration-only tree
What stripping loses here: decorators
## Declaration-only tree
The recipe is the language skill's. The addendum is that decorators do not survive declaration emission, so routes, guards, DI tokens and @ApiProperty shapes are invisible in a packed tree. Routes and guards are derived from Bindings, the DI shape follows from Layering, and @ApiProperty shapes derive from the descriptor and the language skill's Rendering.
References
Deeper files read on demand
## References
references/testing.md (spec authoring), db-assertions.md (persisted-state assertions), error-assertions.md (asserting a throw), nock-helpers.md (mocking external HTTP in e2e) and coding-standards.md (the audit-event rule and typed invariants). Each is read only when its topic is touched.
inspire-code-angular
.claude/skills/inspire-code-angular/
Angular conventions for a face's package. Served to the units whose stack.md profiles: lists angular, together with inspire-code-typescript. It has no Routes, Bindings or Persistence seed. It is a skill the coding agent reads, not a command; coding itself runs in INSPIRE Factory.
stack: angular
layer: frontend
language: typescript
Layering
Smart and dumb components, services with inject(), signals and an optional global store
## Layering
Smart components orchestrate state and navigation. Dumb components take inputs and emit outputs, use OnPush and never touch the store or HTTP. Services hold business logic and data access through inject(), with HTTP behind a service layer. Signals hold local and service state, and a global store such as NgRx holds cross-feature state where the project adopts it. Features live under @features/* behind lazy routes, cross-cutting singletons under @core/*, and presentational pieces under @shared/*.
Test conventions
Jasmine and TestBed, optional Cypress component tests, Playwright e2e
## Test conventions
Unit specs use Jasmine with TestBed (Karma runner), colocated as *.spec.ts, with signal inputs set through setInput() and HTTP through HttpTestingController. Cypress component tests (*.cy.ts) apply where the project adopts them. E2E uses Playwright against the running app. Tests are GIVEN/WHEN/THEN, and expected user-facing text is asserted against constants or i18n keys.
Forbidden patterns
No logic in dumb components, no leaked subscriptions, no function calls in templates
## Forbidden patterns
No business logic, store access or HTTP in dumb components. No state mutation under OnPush. No subscription without cleanup. No custom structural directives for control flow, and no @for without a meaningful track. No function calls in template bindings, no hardcoded strings, no hardcoded colors or spacing, no barrel Material imports and no derived data stored in state.
Review focus
Styling, accessibility, performance, state and SSR safety
## Review focus
styling uses the design tokens and BEM with the project's class prefix. accessibility covers roles, labels and keyboard operability. performance covers OnPush, signals, track, @defer and leaks. state covers the right level for state and the right RxJS flattening operator. ssr-safety applies when the project uses @angular/ssr.
Quality gates
Prose only: candidates, not yet a gates: block
## Quality gates
This stack ships no machine-checkable gates: block yet. The candidates its conventions imply are angular-eslint with the template accessibility rules, typescript-eslint strictTypeChecked with ban-ts-comment at allow-with-description, bundle budgets in angular.json and a coverage floor from ng test --code-coverage.
Build & verify
The concrete build, lint, type-check and test commands
## Build & verify
build: ng build (-c production for release). lint: ng lint. types: npx tsc --noEmit. tests: npm run test and npm run test:e2e. In a multi-project workspace every command is scoped to the target project, for example ng build {project}.
References
Thirteen deeper files read on demand
## References
components, di, directives, forms, http, ngrx, performance, routing, signals, ssr, styles, testing and tooling, under references/. ngrx and ssr apply only when the project uses NgRx or @angular/ssr.
inspire-code-ios
.claude/skills/inspire-code-ios/
iOS conventions. Served to the units whose stack.md profiles: lists ios. Only its test conventions and build commands are written; the other sections are deliberate deferrals. It declares no language: skill. /inspire-config stops when ios is in profiles, because iOS needs macOS and INSPIRE Factory's sandbox is Linux. It is a skill the coding agent reads, not a command.
stack: ios
layer: frontend
Layering
Not yet formulated for this stack
## Layering
Not yet formulated for this stack. The section is a deliberate deferral until an iteration on a real codebase exercises it.
Test conventions
Swift Testing, parameterized cases, fast tests
## Test conventions
New suites use Swift Testing, not XCTest: a @Suite per feature and a @Test per case, with #expect for assertions and #require for unwrapping. Tests are Arrange-Act-Assert and test behavior, never implementation. Parameterized cases use @Test(arguments:). Edge cases include empty strings, nil, boundaries and different locales, and each test runs in under a second.
Forbidden patterns
Not yet formulated for this stack
## Forbidden patterns
Not yet formulated for this stack. The section is a deliberate deferral until an iteration on a real codebase exercises it.
Review focus
Not yet formulated for this stack
## Review focus
Not yet formulated for this stack. The section is a deliberate deferral until an iteration on a real codebase exercises it.
Quality gates
Not yet formulated for this stack
## Quality gates
Deferred until an iteration on a real codebase. A project derives its own gates, for example a SwiftLint rule set and a coverage floor.
Build & verify
The concrete test commands
## Build & verify
tests: swift test. One test: swift test --filter <testName>. Coverage: swift test --enable-code-coverage. Parallel: swift test --parallel.
inspire-code-android
.claude/skills/inspire-code-android/
Android conventions. Served to the units whose stack.md profiles: lists android. Only its test conventions and build commands are written; the other sections are deliberate deferrals. It declares no language: skill. It is a skill the coding agent reads, not a command.
stack: android
layer: frontend
Layering
Not yet formulated for this stack
## Layering
Deferred. The test-level table implies the working shape (ViewModel, UseCase, Repository, DataSource), but the boundary rules are unwritten.
Test conventions
JUnit 5, one mock framework, a test-level table
## Test conventions
JUnit 5 with one mock framework per project, MockK or Mockito, never mixed. Tests are GIVEN/WHEN/THEN with backtick names, use test-data builders and verify collaborator calls with exact counts. A table maps each layer to its framework and mock strategy: ViewModel, use case and repository with JUnit 5, Compose UI with Compose Testing, fragments and activities with Espresso. Coroutines use runTest with a TestDispatcher, and emitted states are asserted in order.
Forbidden patterns
Not yet formulated for this stack
## Forbidden patterns
Not yet formulated for this stack. The section is a deliberate deferral until an iteration on a real codebase exercises it.
Review focus
Not yet formulated for this stack
## Review focus
Not yet formulated for this stack. The section is a deliberate deferral until an iteration on a real codebase exercises it.
Quality gates
Not yet formulated for this stack
## Quality gates
Deferred until an iteration on a real codebase. A project derives its own gates, for example a detekt or ktlint rule set and a coverage floor from the jacoco report.
Build & verify
The concrete test commands
## Build & verify
unit: ./gradlew test (debug only: ./gradlew testDebugUnitTest). Instrumented: ./gradlew connectedAndroidTest. Coverage: ./gradlew jacocoTestReport.
inspire-code-typescript
.claude/skills/inspire-code-typescript/
The language skill for TypeScript. It carries no architecture: layering, tests and build commands belong to the framework skills that name it with language: typescript. It is the one home for how a semantic type renders as a type, a schema and a column, and for how the language yields a declaration-only tree. A unit built under react, nestjs or angular gets it too, and a project can list typescript directly in profiles:. It is a skill the coding agent reads, not a command.
stack: typescript
layer: language
Rendering
One row per universal semantic type: TypeScript type, OpenAPI schema, SQL column
## Rendering
Renders each universal semantic type in three targets. For example timestamp is a string, an OpenAPI date-time string and TIMESTAMPTZ, and enum<A,B,C> is a union of literals, a string enum and TEXT with a CHECK. The SQL column is Postgres.
Mapping tokens
How each Mapping token expands in TypeScript and SQL
## Mapping tokens
Expands tokens such as uuid(), now(), today(), current_user, input.{field}, hash({field}) and from {R.{field}}. The token meanings are universal and live in type-mapping.md; only the expansions are here.
Project semantic types
The base-type fallback and how to add a row
## Project semantic types
A project type with no row renders as its declared universal base type in all three targets, so no type is ever a rendering hole. A row added here wins. A type with no base type and no row is a readiness refusal.
Engine notes
Where the SQL column assumes Postgres and how to move it
## Engine notes
On another engine the SQL column is edited in place, not duplicated. The usual substitutions are UUID to CHAR(36), TIMESTAMPTZ to DATETIME, JSONB to JSON and a native ENUM where one exists.
Compile stub
The form a declared-but-unimplemented method takes
## Compile stub
A stub throws, and its message names every parameter, so oxlint's no-unused-vars rule, which reports a parameter a function never reads, is satisfied without a suppression or a renamed parameter.
Escape-hatch plugin
The oxlint rules that refuse the escape hatches oxlint has no rule for
## Escape-hatch plugin
Ships references/oxlint-escape-hatches.mjs, a local oxlint JS plugin with three rules: escape-hatches/require-reason (a disable directive names its rules and says why after --), escape-hatches/no-restricted-disable (no directive disables a rule in its option list, under any plugin prefix, or one of the plugin's own rules) and escape-hatches/no-double-cast (as unknown as). A framework profile that lints with oxlint gates them; the project copies the file into its package, lists it in jsPlugins and owns it from then on.
oxlint's JS plugins are alpha and run without type information. A bare /* oxlint-disable */, or an oxlint-disable-line naming the plugin's rules, still switches them off; both stay visible in the diff.
Declaration-only tree
The recipe that strips bodies for the test phase
## Declaration-only tree
Type-checks the package with tsgo --declaration --emitDeclarationOnly (with --rootDir set to the package root) and swaps the emitted .d.ts files for the sources, path for path. Emission is the gate: a package that does not type-check cannot be packed. Function bodies, private members and decorators do not survive.
Scoped by frontmatter. A stack skill is an ordinary skill with one optional field, stack: <id>. It is served only to the units whose stack.md profiles: lists that id, and a skill without the field is served to every unit. layer: decides which units it reaches, and a framework skill's language: brings its language skill along: react, nestjs and angular name typescript. The id can be a framework, a language, a database or a library, so a project adds its own beside these, for example stack: postgres. A database skill declares layer: backend and no language: or Bindings, so it reaches entities and actions only. A project with two databases names them in stack.md datastores:, with an optional default_datastore:, and an entity elsewhere says datastore:: its table follows that database skill's Persistence. Bindings, Routes and Persistence are seeds the project owns, and the contract is .claude/skills/_references/stack-skills.md.
Housekeeping
Set up and keep the workspace coherent — foundation, the Factory's project file, faces and bundles, brownfield onboarding, review, tracker and lessons.
/inspire-bootstrap
inspire_kb/00_bootstrap/ and inspire_kb/01_spec/_design-system/
Owns the project foundation: output language (project.md), tech stack, shape and product roots (stack.md), the project's own style tokens (style-tokens.md), the default theme (theme.md and theme.tokens.json), the live design system (design-system.md and design-system.tokens.json, both in 01_spec/_design-system/) and the project's root README. Every other layer depends on what is declared here.
init
First-time setup: language, stack, theme, CLAUDE.md, README, git remote
/inspire-bootstrap init
Runs the language flow, then the stack flow (shape first, then layers), then shows the default theme and offers changes. It fills in the placeholders /inspire:init left in CLAUDE.md, creates the root README with the readme flow and, optionally, sets the git origin remote on an explicit yes. Each seeded default is shown with the choice to keep or change it.
- Reads
- project.md · stack.md · theme.md · CLAUDE.md · git remote -v
- Writes
- project.md · stack.md · theme.md · CLAUDE.md · README.md
Ends by pointing to /inspire-module create.
language
Set the output_language every skill writes artifacts in
/inspire-bootstrap language
Reads the current output_language from project.md and asks for a new one (ISO 639-1 code or name; English by default). It explains that this sets the language of KB artifacts only, not of the conversation or the product's own UI. It writes the value on approval. When the language is not English and style-tokens.md has no rows, it proposes tokens for the R6 (history-narrating words) and R7 (intensifiers) checks.
- Reads
- 00_bootstrap/project.md · 00_bootstrap/style-tokens.md
- Writes
- 00_bootstrap/project.md · 00_bootstrap/style-tokens.md (approved rows)
Changing it does not translate existing artifacts; translation is offered on request. An empty token list is a valid answer.
stack
Define or update stack.md: shape, faces and bundles, layers, product roots
/inspire-bootstrap stack
Asks about the shape one question at a time: platform, which faces and bundles the product has, web and/or mobile, database deployed or external, local dev database, and source_root and prototype_root. It delegates each face and bundle declaration to /inspire-face add. When the data layer names more than one database, it writes datastores: (an id per database, mapped to its stack id) and asks whether one is the default_datastore:, never picking it itself, and offers to scaffold a database skill with a Persistence section for an engine that has none. It then confirms each layer that applies, shows a diff and applies it on approval, also setting profiles:, wire conventions, test infrastructure and quality gates.
- Reads
- 00_bootstrap/stack.md
- Writes
- 00_bootstrap/stack.md · in-repo quality gates from the profiles
A face or bundle is never written here; /inspire-face writes it. Replacing a load-bearing choice or changing the shape needs an ADR, so it offers /inspire-adr create. The server-side half of the gates becomes a tracker ticket with a human owner.
theme
Define or update the reusable design-system default (theme.md)
/inspire-bootstrap theme
Sets theme mode, typography, color tokens with the status map, density and layout tokens, shows a diff and applies it on approval. It can also derive the theme from a mockup's CSS by taking its values and turning product-specific names into token roles.
- Reads
- 01_spec/_design-system/theme.md and theme.tokens.json · optionally a mockup's CSS
- Writes
- 01_spec/_design-system/theme.md and theme.tokens.json
theme.md is the default template; the project's live design system is edited with design-system.
design-system
View or edit the live design system in 01_spec/_design-system/
/inspire-bootstrap design-system
Reads design-system.md and design-system.tokens.json, seeding both from the theme if they are missing. It agrees the change, shows a diff and applies it on approval: a value changes in the token file and a meaning changes in the markdown. It then flags the effect on screens and the prototype. There is one design system for every face: a face extends it with scoped catalog entries, named variant sections inside the file or its own {face}.tokens.json that only adds tokens, and has no channel to override it.
- Reads
- 01_spec/_design-system/design-system.md and design-system.tokens.json · theme.md
- Writes
- 01_spec/_design-system/design-system.md and design-system.tokens.json
Token roles stay stable even when values change. design-system.md is trust-stamped; the token file carries no frontmatter and is not.
design-system backfill
Bring an older design system up to the token file, viewports, icons and reference
/inspire-bootstrap design-system backfill [<reference>]
Lists the gaps with design-system-coherence.sh, resolves the reference (the prototype by default), and builds design-system.tokens.json in the W3C Design Tokens format. Every value design-system.md already states moves into the token file and the markdown cites it. Missing ## Supported viewports, ## Icons and ## Reference sections are filled from the reference, and from common sense only where the reference shows nothing.
- Reads
- design-system.md · the reference · design-system-coherence.sh findings
- Writes
- design-system.tokens.json · the missing sections of design-system.md
What the project already decided stays decided. /inspire:update runs it before /inspire-screens backfill whenever a section or the token file is missing.
readme
Create or update the project's own root README.md
/inspire-bootstrap readme
Suggests a title from the repo name and asks for an optional one-line description, both in a single question. It writes a minimal README with a Development note pointing to inspire_kb/ and CLAUDE.md. An existing README that belongs to the operator is only overwritten after a diff is shown and confirmed.
- Reads
- repo name · existing README.md · CLAUDE.md
- Writes
- README.md
The git remote is never written into the README.
review
Read-only coherence check of the bootstrap artifacts
/inspire-bootstrap review
Checks that project.md, stack.md, theme.md, glossary.md and style-tokens.md exist and parse, and that output_language is valid. It checks that stack layers match the declared shape, that source_root and prototype_root are declared and that the root README belongs to the project. When stack.md declares datastores:, each maps to a stack id in profiles: whose skill has a Persistence section, and the default is one of them; a data layer naming two or more databases without datastores: is flagged. It checks that no stack choice contradicts a current global ADR, that design-system.md and its token file exist with their viewports, icons and reference sections, that no second design-system file exists, and that a face's tokens only add paths. A theme or roster file left in 00_bootstrap/ means the KB was not migrated.
- Reads
- 00_bootstrap/* · 01_spec/_design-system/ · 01_spec/_adr/ · README.md
- Writes
- nothing (read-only)
Face and bundle coherence is left to /inspire-face review. A leftover layered layout points to /inspire:migrate.
/inspire-config
.inspire/emanate.yml
Writes and checks .inspire/emanate.yml, the one file INSPIRE Factory reads to run a project. It holds the Factory's own settings (the factory section) and the image, services, environment, setup and phases of checks every unit runs with. The skill derives a proposal from stack.md and its profiles, asks only what they cannot answer and validates the result with the Factory's own reader. It is operator work and never part of coding a unit.
init
Derive, ask, validate, then write the file on approval
/inspire-config init
Checks that the project is a git repository, that stack.md exists and that its profiles resolve; ios in profiles stops the skill, because iOS needs macOS and the Factory's sandbox is Linux. It reads stack.md, every *.face.md and *.bundle.md (their package and profiles) and the resolved stack skills, and inspects the repository read-only for lockfiles, package.json scripts, runner configs, test directories and the compose file. It proposes the whole draft first, each key with one line saying where it came from, then asks one question at a time for what cannot be deduced, with the default in brackets. Every Jest or Vitest unit suite in the tests phase gets a run_related command by default: its run narrowed to the tests related to the files a unit changed, with --passWithNoTests (jest --findRelatedTests {files}, vitest related --run {files}). An e2e suite gets none unless the operator asks. A review phase goes after quality and before tests, so a change the review rejects is repaired before a full test run is spent. On Factory 0.19.0 or later, a Vitest e2e suite that runs one file at a time over per-file databases gets --fileParallelism with --maxWorkers=4 from sandbox.memory 2g and 2 below. bash_timeout is proposed at 600 seconds, since without it an agent's shell command is killed after 300. It asks how strict a unit is when its agent reports a spec problem (spec_strictness: strict, auto or yolo; default strict, and auto also asks for spec_classifier_model). factory.sandbox.memory defaults to 1536m and must be a Docker size, and each service takes a memory limit (default 512m). It validates with the Factory's reader and with checks the reader cannot make, one error per round, and writes on approval.
- Reads
- 00_bootstrap/stack.md · *.face.md and *.bundle.md under 01_spec/ · the stack skills' Build & verify and Test conventions · the repository · .inspire/emanate.json when it exists
- Writes
- .inspire/emanate.yml
On an existing file it proposes a migration through a shown diff, never a rewrite, and an emanate.json is moved under factory and deleted. It never writes a secret (env is committed and read in plain text), never invents an image, never starts a service and never commits. Without the Factory's reader the verdict is validation pending. The factory section needs Factory 0.13.0 or later, a review check 0.11.0 or later, run_related 0.17.0 or later, the spec_* keys 0.18.0 or later, and check_concurrency and the parallel e2e flags 0.19.0 or later; the Factory's version is read from its checkout, and without one neither of the last two is proposed: an older Factory refuses the file at start with has unknown key run_related, and the fix is to update the Factory, not to drop the key. Re-running init on an existing file proposes the run_related commands, a missing bash_timeout and the parallel e2e flags, and moves a review phase that sits after tests.
review
Read-only validation of the file with every warning listed
/inspire-config review
Validates .inspire/emanate.yml with the Factory's own reader, then lists every warning from the checks the reader cannot make, among them a Jest or Vitest run_related without --passWithNoTests, {files} quoted again, a run_related that is not its run narrowed, a review phase after tests, a missing bash_timeout, and an e2e suite over per-file databases that still runs one file at a time on Factory 0.19.0 or later. An optional image probe runs one throwaway container, only on an explicit yes.
- Reads
- .inspire/emanate.yml · stack.md and the stack skills
- Writes
- nothing (read-only)
A gap in stack.md or a profile goes to /inspire-bootstrap stack and is never patched here. /inspire:update runs it as its last step without asking for the Factory's path and, when it warns, offers init.
/inspire-face
inspire_kb/01_spec/_faces/ and _bundles/
Owns the project's faces and bundles. A face is an application a person uses (a web portal, a back office, a mobile app) and holds its screens, shell and tokens. A bundle is a headless grouping of actions published together (an API, an SDK, a library, a backend for a frontend). It owns every {face}.face.md and {bundle}.bundle.md, and is the only skill that creates or retires either.
add face
Declare a new face, from scratch or split out of an existing one
/inspire-face add face
Greenfield: interviews the id, display name and the optional package, profiles and shell, validates the id (a slug, unique, never starting with _) and the shell (unique among faces), names the bundles the face uses, and writes the file with lifecycle: draft. It hands the shell to /inspire-prototype and proposes an ADR. Split: creates the new face first, then sweeps every screen of the source face and every global ADR, feature and design-system entry scoped to it, and shows the whole set as one batch. The operator classifies each entry as stays, moves or both, and only then are the moves performed.
- Reads
- the operator's answers · existing faces and bundles · face-scope.md and face-format.md
- Writes
- inspire_kb/01_spec/_faces/{face}/{face}.face.md · moved screens and their new ids (split) · inspire_kb/01_spec/_migration/id-map.json (split) · draft bundles it links
A moved screen changes id from {source}.{slug} to {face}.{slug}, and every changed id is recorded in id-map.json before the change is committed. A screen marked both stays and a copy with a new id lands in the new face; there are no shared screens. It creates no screen files. A face candidate from /inspire-extract enters as a pre-filled interview.
add bundle
Declare a new bundle and the actions it exposes
/inspire-face add bundle
Interviews the id (no version in it: api, never api@v1), display name, package and profiles. It asks which actions the bundle exposes, each entry a whole module (a link to its {module}.module.md, marked (whole module)) or one action, linked to its *.action.md. INSPIRE may suggest a grouping, such as one bundle per module, and never decides it. A module or action that does not exist yet is created as a draft. It asks what kind of bundle it is: a grouping bundle has exactly one claim, {bundle}/mount/every-action, and a bundle with its own artifact describes what that code does. It then offers to add the bundle to the faces whose screens bind these actions.
- Reads
- the operator's answers · existing modules and actions
- Writes
- inspire_kb/01_spec/_bundles/{bundle}.bundle.md · draft modules and actions it links
Exposure stays on the action: a bundle lists actions and never restates their route, dispatch or guard. Adding the bundle to a face's bundles: is offered per face, never applied unasked.
retire
Wind a face or bundle down and unpick its scope
/inspire-face retire <id>
Resolves the id to its *.face.md or *.bundle.md and lists what depends on it: for a face its screens, ADRs, processes, _index.md, tokens, prototype shell and package path and every global artifact scoped to it alone, and for a bundle every face that lists it. Each of those takes an explicit decision, archive or rescope, presented as one batch. It applies the decisions, then retires the file last by setting lifecycle: superseded, or removing it if asked, and proposes an ADR.
- Reads
- the face or bundle file · everything scoped to it
- Writes
- the face or bundle file's lifecycle · rescoped artifacts · inspire_kb/01_spec/_migration/id-map.json (rescoped screens)
It never deletes an artifact on the operator's behalf, and retiring a bundle never touches the actions it listed.
review
Read-only coherence check of every face and bundle
/inspire-face review
Runs spec-identity.sh (unique ids, no _ prefix, unique shells, bundles that exist and declare a package) and face-exposure.sh (a screen binds only actions its face's bundles expose). It adds judgment checks: packages resolve under source_root, bundle boundaries match the use cases, a bundle's kind is clear, every faces: and bundles: value names an existing file, one face's screens do not link another face's, and no id-map.json entry points at a screen that does not exist.
- Reads
- every *.face.md and *.bundle.md · faces: and bundles: values across the KB · the validators' output
- Writes
- nothing (read-only)
Findings use the shared operator-facing format.
/inspire-workspace
inspire_kb/ (all)
Workspace-level validation: the global pre-merge review that runs every module review plus cross-module checks, and validation of the 01_spec/ layout. It reads ADRs and tickets but does not write them; those belong to /inspire-adr and /inspire-task.
review
Global pre-PR gate: validators, module reviews and cross-module checks
/inspire-workspace review [<module>...]
Required before any PR that touches inspire_kb/. It picks the modules in scope (every *.module.md by default), runs /inspire-module review on each, and runs .inspire/bin/review.sh over the whole KB, which includes spec-identity.sh, face-exposure.sh and process-shape.sh. It then runs the cross-module checks: dependencies, ADR references at every scope, ADR propagation by maturity, faces: and bundles: values, exposure across faces, processes that reach across modules and cycles. It also checks vault structure, that no screen is shared between faces, prototype component adoption per shell and catalog coherence. The report ends with Signals: the trust report, which includes the CHANGED SINCE ENDORSED group, and the design-system variance count.
- Reads
- the whole inspire_kb/ · prototype · task tracker · trust.sh report
- Writes
- nothing (read-only)
Runs sequentially by default; review.workflow.mjs can run module reviews in parallel, where a review that does not complete becomes a critical finding. Signals are measurements and never block the gate.
structure
Validate the 01_spec/ layout, typed extensions and tracker invariants
/inspire-workspace structure
Checks for CLAUDE.md at the root and that every .md under 01_spec/ is a typed artifact, a README, a face's _index.md or design-system.md and theme.md. It flags the old layered names and a layered directory (01_adr to 05_screens) beside 01_spec/ as critical, with /inspire:migrate as the fix. It checks that placement agrees with the concept (a module's files under _modules/{module}/, a face's screens under its _screens/, bundles in _bundles/, a process under the scope its id names) and that every face holding screens has an _index.md. It validates the tracker: ID format, open tickets at top level and closed ones in archive, no duplicates, resolvable links. It also flags orphan files and a theme or roster file left in 00_bootstrap/.
- Reads
- inspire_kb/ layout · CLAUDE.md · 99_tracker
- Writes
- nothing (read-only)
The layout is for people and no tool depends on it, so a misplaced file is a minor finding. Uniqueness of ids and the agreement between extension and type are spec-identity.sh's.
/inspire-task
inspire_kb/99_tracker
A plain-file ticket tracker: one Markdown file per ticket, open tickets in tickets/ and closed ones in tickets/archive/. It tracks work, drift and skill-feedback without an external tool.
create
Open a new ticket with a random TASK id
/inspire-task create <title> [--epic X --size M --importance Mid --skills a,b]
Gets the reporter handle from git config user.email and today's date. It generates a unique 6-character base36 id and applies the flags: --epic is required; defaults are size M, importance Mid, status Open; --blocked-by and --related-to are optional. It writes TASK-{id}.md with frontmatter and an empty Description (or --body) and prints the id.
- Reads
- git config · tracker-format reference
- Writes
- inspire_kb/99_tracker/tickets/TASK-{id}.md
Skill-feedback tickets use epic: skill-feedback and the source skill in skills:.
update
Change ticket fields; status changes move the file
/inspire-task update TASK-<id> [--field value ...]
Finds the ticket in tickets/ or archive/, applies field changes checked against the allowed values and sets updated. Moving to Done or Cancelled moves the file into archive/ and fills closed_by and closed_at; reopening moves it back and clears them. It shows a diff before saving.
- Reads
- the ticket
- Writes
- the ticket (possibly moved)
close
Close a ticket as Done (or Cancelled) and archive it
/inspire-task close TASK-<id> [--cancelled --reason "..."]
A shortcut that sets status Done, or Cancelled with --cancelled, adding a Cancellation reason section if --reason is given. It sets closed_by, closed_at and updated, and moves the file to tickets/archive/.
- Reads
- the ticket
- Writes
- the ticket, moved to archive/
Tickets are never deleted and ids are never reused.
list
List open tickets as a compact table, with filters
/inspire-task list [--status X --epic Y --skill Z]
Reads the frontmatter of the top-level tickets, and also archived ones with --include-archived or --all. Filters are --status, --epic, --size, --importance, --reporter, --skill and --blocked. Prints id, status, epic, size, importance, skills and title.
- Reads
- 99_tracker/tickets/ (and archive/)
- Writes
- nothing (read-only)
Other skills run this at the start of multi-step work so they don't report tracked items again.
show
Print one ticket's frontmatter and body
/inspire-task show TASK-<id>
Reads the ticket from tickets/ or archive/ and prints it in full.
- Reads
- the ticket
- Writes
- nothing (read-only)
/inspire-lesson
inspire_kb/98_lessons
A catalog of write-once lessons: one-line instructions that change how an inspire-* skill behaves in this project. Each is stored as YYYYMMDD_<slug>.md and records the INSPIRE version it was captured on, so an upstream reader can find patterns across forks.
note
Capture a one-line, write-once lesson for a skill
/inspire-lesson note <title> [--skill X --category preference --supersedes id]
Gets the reporter handle and date, and reads inspire_version and template_sha from .inspire.lock (falling back to plugin.json, then unknown). It builds YYYYMMDD_<slug>.md and applies --skill (required; runtime for lessons that span skills), --category (default preference) and --supersedes. It drafts the single instruction with the operator, optionally with a Not: line and an example, writes the file once and prints the id.
- Reads
- .inspire.lock · git config
- Writes
- inspire_kb/98_lessons/YYYYMMDD_<slug>.md
Always written in English. To revise a lesson, write a new one with --supersedes; the old file is never edited. Skills offer this command; they never write a lesson on their own.
list
List lessons as a table, filtered by date, skill or category
/inspire-lesson list [--since YYYYMMDD --until YYYYMMDD --skill X --category Z]
Reads 98_lessons/*.md, and also archive/ with --archived. Date filters use the filename prefix; --skill, --category and --reporter use frontmatter. Prints date, category, skill, version and instruction.
- Reads
- 98_lessons/
- Writes
- nothing (read-only)
show
Print one lesson's frontmatter and body
/inspire-lesson show <id>
Reads the lesson file and prints it.
- Reads
- the lesson
- Writes
- nothing (read-only)
purge
Delete old archived lessons (dry run unless confirmed)
/inspire-lesson purge [--months N | --before YYYYMMDD] [--confirm]
Selects archived lessons older than the threshold (default 6 months) by filename date and lists them. Files are deleted only with --confirm or approval in the conversation, and only whole files are removed.
- Reads
- 98_lessons/archive/
- Writes
- deletes archived lesson files (on confirm)
Optional. Deleted files can be recovered from git history. Does nothing until an update flow fills archive/.
Provenance. Every artifact a skill writes under inspire_kb/01_spec/ carries a produced block, stamped by the tooling after the write: which skill wrote it, the exact deployed bytes it ran against, and the runtime version. Separately, an operator can vouch for it with endorsed — a name and a date, written only after an explicit yes. The trust report in /inspire-workspace review groups what it finds, and CHANGED SINCE ENDORSED lists an endorsed artifact that changed after the commit that recorded its endorsement. No block means "never endorsed" or "provenance unknown"; nothing is stamped retroactively.