| name | ghost |
| description | Author, validate, consume, and review against a repo-local Ghost fingerprint — the medium-agnostic articulation of a product's brand. Use when the user wants to set up a .ghost fingerprint, write or update brand-truth nodes, gather brand context before generation, or assemble a review packet from Ghost checks. |
| license | Apache-2.0 |
| metadata | {"homepage":"https://github.com/block/ghost","cli":"ghost"} |
Ghost — Brand Fingerprints
A Ghost fingerprint is the medium-agnostic articulation of a brand: its truths,
its stance, its conditions, and optional pointers to the concrete materials those
truths govern. One brand truth is stated once, at the altitude it is actually
true, and an agent reads the relevant truths before building.
.ghost/
manifest.yml # schema + id (the package anchor)
glossary.md # the author's kind vocabulary
materials/ # bundled materials; reserved, never nodes
<kind>.<slug>.md # a brand truth of a declared kind
<slug>.md # a brand truth without a kind
checks/ # optional review assertions; never nodes
The model in one breath
- A node is a markdown file:
description, optional materials, and a prose
brand truth.
materials is one list of locators for the concrete stuff the truth is about:
repo-relative paths/globs or absolute HTTPS URLs. materials/ is reserved for
bundled materials; reference living implementations where they already live.
Guidance stays in prose.- A node's kind comes from its filename prefix (
principle.density.md →
kind principle). A bare name (voice.md) has no kind.
- The glossary declares the kind vocabulary and what each kind means.
- The manifest's
cover names the node gather inlines above the menu every
time. It carries essence, temperature, and brand-only refusals. Admission
test: a violation visible in one element belongs in that element's chapter;
visible in one view, in the composition chapter; visible only across the
whole body of work, on the cover.
- There is no hierarchy, no inheritance, no edges. Directories are for browsing
only; the model reads a flat menu.
- Checks are optional review assertions in a flat
.ghost/checks/*.md
directory. Checks are feed-back only; they never leak into generation
context. Each check declares references to node ids and is used by
ghost review. A check may
include probe: <command>; review runs it as evidence unless --no-probes is
set. Checks are never emitted by ghost gather or ghost pull.
The loop
ghost init
ghost checks init
ghost validate
ghost gather <ask>
ghost pull <ids>
ghost review
ghost export
ghost pulse
gather does no selection. It emits the menu and you read the ask against it,
then pull the truths you judge relevant. Its header includes a coverage line —
total nodes and nodes carrying concrete material — so an all-prose
fingerprint is visible before generation.
Prefer ghost pull over reading files directly: it emits the same prose,
inlines small local materials by default, turns binary materials into
inspect-pointers, orders the packet for steering (cover when selected, concrete nodes,
prose rules), extracts Skeletons dead last, and appends structured
events to .ghost/.events for local tuning.
review does no grading. It assembles an advisory packet: touched files,
matched material-backed nodes, offered checks, probe
evidence, coverage gaps, and the diff. The host agent renders findings.
CLI verbs
| Verb | Purpose |
|---|
ghost init | Scaffold .ghost/ with the skeleton starter: manifest, glossary, a brand.md cover, foundation chapters, context nodes, and the cliche floor. --template minimal writes a smaller cover-led starter. --with checks also adds the checks directory. |
ghost checks init | Scaffold .ghost/checks/ with an example review assertion. |
ghost validate [file-or-dir] | Validate manifest, nodes, material locators, check references, and glossary kind prefixes. |
ghost gather [ask…] [--format json] | Emit the node menu for selection plus coverage line; log exposed ids. |
ghost pull <id> [<id>…] | Emit selected nodes' full bodies and materials in steering order; log selected/missed ids. |
| `ghost review [--diff <path | ->] [--base ] [--format json] [--no-probes]` |
ghost export [--out <path>] [--no-checks] [--strict] [--format json] | Package .ghost/ as a portable brand artifact and report which material locators will not travel. |
ghost pulse [--format json] | Summarize local .ghost/.events. |
ghost skill install | Install this skill bundle. |
ghost manifest [--format json] | Emit a self-describing JSON manifest of every command and flag. |
Skeleton convention
A ## Skeleton section in a node contains the literal opening structure for a
surface, usually on a pattern.* node. ghost validate warns unless each
Skeleton section has exactly one fenced block. ghost pull removes Skeletons
from the node body and emits the fences at the end under a begin-from-this banner.
If a pulled Skeleton matches the task, start the artifact from it verbatim, then
fill with task facts.
Receiving a fingerprint
Unpack the exported archive, run ghost validate --package <dir>, then run
ghost skill install in the receiving workspace. From there, gather and pull
against the unpacked package with --package <dir>.
Workflows
Fingerprint authoring is elicitation, not scanning. The raw material is what
the human brings and points at: words, images, links, exemplar products, brand
docs, copy they love or hate. Repo code can supply material locators and local
conventions, but durable brand truth should be curated by the human.
When the fingerprint is silent
A silent fingerprint does not require stopping. Proceed from nearby product
surfaces, local conventions, and ordinary reasoning when safe, and label that
reasoning as provisional and non-Ghost-backed — unless the fingerprint itself
declares a stricter silence posture (check the cover), which overrides
this default. Ask a human before high-risk, irreversible, privacy, security,
legal, or brand-defining choices.
Never
- Never invent hierarchy, inheritance, or cross-node edges.
- Never file a truth by destination (
for-emails.md); state its condition in prose.
- Never put guidance in
materials; it belongs in the node body.
- Never gather checks as generation context.
- Never claim provisional or local-convention reasoning as Ghost-backed.
