promptus

name

promptus

description

Orchestrator and map for the Promptus research knowledge system — a substrate for the LLM agent. Use at the start of research book-keeping to choose the right verb/script/skill — STORE (kb-add/kb-amend), BOOK-KEEP (promptus-check + kb-index + graph + checkpoint), RETRIEVE (kb-find → kb-get + recall). grannie is the one human read-port. Knows the four stores, substrate:status tagging, the [[link]] graph, and the invariant.

Promptus — orchestrator

Portable path rule: in commands below, replace <plugin-root> with the absolute plugin root two directories above this SKILL.md. Resolve it from the loaded skill path; do not assume a host-specific environment variable exists in the project shell.

Promptus stores / keeps / retrieves what a research project knows as gated markdown — a substrate for the agent; grannie is the one human read-port. Read .promptus/TELOS.md for the canonical statement and the invariant. This skill is the map: pick the verb, run the piece.

Decision table — intent → do this

You are about to…	Verb	Do
record a decision / run / observation / dead-end / finding	STORE	bun "<plugin-root>/scripts/kb-add.ts" --substrate ledger … (or the research-ledger skill for the habit)
distill a settled finding into a concept page	STORE	kb-add --substrate finding … (one concept per file, [[linked]])
capture external prior art you read	STORE	kb-add --substrate lit --source "<src#anchor>" …
remember a durable, cross-session fact	STORE	kb-add --substrate memory …
change the status or metadata of an existing curated unit	STORE	`bun "/scripts/kb-amend.ts" --path --substrate <finding
make the index current after writes	BOOK-KEEP	bun "<plugin-root>/scripts/kb-index.ts"
verify the whole store is classified, uniquely identified, related, and current	BOOK-KEEP	the promptus-check skill (bun "<plugin-root>/scripts/promptus-check.ts" --strict)
check the knowledge web's health (dangling [[links]], orphans)	BOOK-KEEP	bun "<plugin-root>/scripts/kb-graph.ts" lint
flush a session before compaction	BOOK-KEEP	the promptus-checkpoint skill (/promptus:checkpoint in Claude Code)
answer "what did we decide / find / read about X"	RETRIEVE	the recall skill (drives kb-find → kb-get)
read one unit's body without opening the whole ledger	RETRIEVE	bun "<plugin-root>/scripts/kb-get.ts" "<path>" (the path column kb-find prints)
find the load-bearing units (what to read first)	RETRIEVE	bun "<plugin-root>/scripts/kb-graph.ts" rank
find related-but-unlinked notes to connect	RETRIEVE	bun "<plugin-root>/scripts/kb-graph.ts" suggest
write something the project already knows	RETRIEVE	recall to ground it; editio's humanizer for style, when installed
explain a stored concept to a human	read-port	grannie (/grannie explain <concept>) — grounds from the store
audit a draft for AI-tells + unsourced claims	audit	the grounded-writing-reviewer skill
initialize Promptus in a repo	—	the promptus-init skill (runs telos; /promptus:promptus-init in Claude Code)
change the project's direction (edit the Telos)	—	operator-triggered: record a ledger DECISION + propose (the telos skill's boundary); rewrite in place on the operator's word — the frontier goes to kb-now, never into TELOS.md

The four stores

Telos (.promptus/TELOS.md, direction) · Ledger (.promptus/ledger/RESEARCH-LEDGER.md, events) · Knowledge (.promptus/docs/ findings + .promptus/docs/lit/ literature) · Memory (.promptus/memory/, durable facts). Every unit is tagged substrate:status — ledger:DEADEND, finding:VALIDATED, lit:CITE, memory:validated.

The knowledge graph

The [[wikilinks]] between units are the graph (no DB, no embeddings — see the invariant); kb-index derives .promptus/cache/graph.json from them, and kb-graph queries it:

• kb-graph rank — PageRank over the page-link graph: the load-bearing units, what to read first.
• kb-graph lint — health: dangling [[handles]] (with a "did you mean?") and orphans. --strict to gate.
• kb-graph suggest — latent links: unit pairs that are unlinked but probably related (shared vocabulary + shared source), so you can draw the missing [[link]]. Suggest-only; you judge.

Retrieval is two-tier: kb-find reads the card-catalog of headers (cheap, header-first), then kb-get fetches only the bodies the headers earned — so a ledger term never costs the whole file.

The invariant (do not break)

markdown is the only source of truth · the index is derived & disposable · writes go through a gated script, never freehand · prefer a script over a server · add machinery only past a threshold you've measured.

When NOT to use Promptus

Throwaway scratch work, a one-off answer, or anything you would not want to resume after a compaction. Storing noise is as bad as losing signal — record what you'd hate to lose.