Skip to content

Rewrite public docs around applicable brand guidance #302

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nahiyankhan merged 5 commits into from
Oct 10, 2026
Merged

Rewrite public docs around applicable brand guidance #302

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
30740df
Rewrite public docs around applicable brand guidance
nahiyankhan Oct 8, 2026
02c17bc
Omit host integration docs from the public rewrite
nahiyankhan Oct 8, 2026
86e45d1
Describe ghost through making and review
nahiyankhan Oct 8, 2026
fc18343
Consolidate demo caveats and loop bookkeeping
nahiyankhan Oct 8, 2026
6b882df
Open with what an agent is never handed
nahiyankhan Oct 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/applicable-guidance-docs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@design-intelligence/ghost": patch
---

Clarify task-specific brand guidance, early-preview status, agent selection, and delivery boundaries.
247 changes: 159 additions & 88 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
# ghost

Use ghost to give agents applicable brand guidance before they start work. A
`.ghost/` package stores your stance, voice, trust moves, and concrete materials
in the repo. Agents select and read that guidance while working on a screen,
email, empty state, or sentence.
An agent holds nothing it isn't handed. It can build the screen, write the
email, draft the sentence, but your brand's stance, restraint, and trust
moves live in heads and PDFs it never sees. ghost puts those decisions in
the repo as plain files, each stating when it applies, so any agent can
pick up what governs the task.

```text
.ghost/
Expand All @@ -13,78 +14,102 @@ email, empty state, or sentence.
asset.logo.md # points at the actual SVGs
```

Reviewers repeat the same feedback on every surface: "that's not our voice."
Write the decision in `.ghost/` so the next agent has it before starting work.
Each file says when it applies, what the brand wants, what it refuses, and
which real files back it up.

Claude Code, Codex, Cursor, and Goose can all use the same guidance.
ghost is bring-your-own-agent: the CLI never calls a model and needs no
API key.

[Project site](https://block.github.io/ghost/) · [npm](https://www.npmjs.com/package/@design-intelligence/ghost)

> [!WARNING]
> ghost is a public development preview. It is not ready for adoption, and we
> are not seeking external testers yet. The CLI, package format, and APIs may
> change without migration support.
## What it looks like

This demo uses a filled-in package; `ghost init` gives you a usable
starter. You ask your agent for a transactional email. The agent runs:

```bash
ghost gather "write a transactional email about seller reverification"
```

gather prints the complete menu: every selectable guidance file and when it
applies. The cover is excluded from selection and included by every pull.
gather never filters or ranks the menu. Selection belongs to the agent,
which reads the menu and picks what governs the task:

> *Agent's selection:* `foundation.voice`,
> `context.email-transactional`, `shared.content-integrity` apply.
> `context.marketing-web` is the wrong register for a transactional email.
> `foundation.motion` does not apply; email has no motion.

The agent then runs
`ghost pull foundation.voice context.email-transactional shared.content-integrity`.
pull delivers the cover, the selected guidance in its original words, and
the sources each file declares, inlined or as pointers. Successful gather
and pull calls are logged locally, so you can see what the CLI delivered
for the run.

> [!NOTE]
> ghost is an early preview. The CLI, package format, and APIs may change
> without migration support, and breaking changes can ship in minor
> versions. If that doesn't scare you, we'd love your feedback: try it on a
> real repo and tell us what broke or confused you.

## Install

Use the local CLI with `npx ghost`, or make `ghost` available on your PATH
for the commands below.

```bash
npm install -D @design-intelligence/ghost
npx ghost skill install
```

After upgrading, run `npx ghost skill check` to compare the installed skill
with this CLI's bundle. Use `--agent` or `--dest` to select an installation;
the command prints the directory it checks and never modifies it. Review any
local edits before reinstalling with `ghost skill install --force`.

## Use It

ghost is **bring-your-own-agent**. Install the skill bundle so Claude Code,
Codex, Cursor, Goose, or another host agent knows how to author and use the
Install the skill bundle so your host agent knows how to author and use the
ghost package, then ask in plain English:

```text
Set up the ghost package for this repo.
Write down the decision I keep repeating about checkout.
Brief this work from the ghost package.
Review this diff against the ghost checks.
Review this diff against the ghost review checks.
```

Your agent selects, interprets, and applies the guidance. The CLI handles the
repeatable work without calling an LLM, so ghost needs no API key and does not
lock you into one agent.
Your agent selects, interprets, and applies the guidance.

ghost never grades the work. It makes sure the CLI delivers the brand's
actual words, and shows you what it delivered. Whether the result is good is
still your call, and `ghost review` is built for that moment: it lays the
change, the guidance, and the review checks side by side so a reviewer can
judge quickly.

## Use Guidance While Making
## The loop

Your agent works with the package through a small set of commands. The default
scaffold is intentionally usable before the brand is fully documented. Its
provisional decisions should be replaced or confirmed as the brand becomes
known.
The starter package is usable before the brand is fully documented. Confirm
or replace its provisional guidance as the brand becomes known. Run setup
once per repo, then gather, pull, and review for each task:

```bash
ghost init # scaffold .ghost/ with a robust provisional baseline
ghost checks init # opt in to review assertions
ghost validate # make sure the package is well-formed
ghost gather <ask> # before building: show the complete guidance menu
ghost pull <ids> # read the cover plus picked nodes' full bodies
ghost review # during review: match a diff to guidance and checks
ghost stats # while tuning: see what agents reached for
ghost skill install # install the unified ghost skill bundle
ghost skill check # compare an installation with the shipped skill
ghost manifest # emit a machine-readable index of commands and flags
# Setup (once per repo)
ghost init # create .ghost/ with a usable starter package
ghost checks init # opt in to review checks
ghost validate # check the package is well-formed

# The loop (every task)
ghost gather "write a transactional email about seller reverification"
ghost pull foundation.voice # deliver the cover plus selected guidance and sources
ghost review # assemble an advisory review packet for a diff
```

For a task-specific gather, your agent reads the complete, unfiltered menu and
pulls every node whose stated situation applies. `ghost gather --format json` inspects
the catalog without grounding a task. Because only selected nodes enter the
working context, the agent can see the shape of the brand without loading the
whole package.
Your agent supplies the task and the applicable IDs; the example above uses
an ID from the starter package. Review requires review checks and a Git diff
against an existing commit.

`gather` and `pull` write a Git-ignored local log. Use `ghost stats` to inspect
it and tune node contexts.

Run `ghost --help` for the core workflow and `ghost <command> --help` for
current flags and command behavior.
While tuning the package, `ghost stats` summarizes what agents actually
reached for. See the [CLI reference](https://github.com/block/ghost/blob/main/packages/ghost/src/skill-bundle/references/schema.md#command-behavior)
for all commands, including `stats`, `skill check`, and `manifest`.

## Thesis

Expand All @@ -93,34 +118,35 @@ help the next generation. Record where the model's default is good enough and
where the brand must differ, then give those decisions to the agent before it
starts.

A `.ghost/` package keeps that guidance in the repo with the materials it
A `.ghost/` package keeps that guidance in the repo with the sources it
points at and the conditions where it applies. Buttons stay buttons. The
moments that carry your brand get your stance instead of the default. Write the
decision once, and each agent can use it when the same situation returns.

## How It Works
Selection is by applicability, not similarity. The menu states when each
file applies, and the agent pulls what governs the task, including guidance
whose words never appear in the prompt.

## How it works

A ghost package is a small folder of prose. Your agent finds the guidance that
applies, reads it, and uses it while making. The CLI supports that work with
repeatable commands for scaffolding, validation, retrieval, and review.
The package is a folder of guidance files. Each file is one brand
decision: frontmatter saying when it applies and which sources back it,
and the guidance itself in prose. There is no hierarchy to learn. The
folder is flat, and directories are only for browsing.

```text
.ghost/
manifest.yml # schema + package id + optional cover id
glossary.md # your kind vocabulary + what each kind means
brand.md # example cover included by every pull
principle.trust.md # guidance of kind `principle`
asset.logo.md # guidance that points at concrete materials
checks/ # optional review assertions; never nodes
asset.logo.md # guidance that points at concrete sources
checks/ # optional review checks; not guidance files
```

The package is a **flat set of nodes**. The optional `cover:` in
`manifest.yml` may name any node. `ghost gather` excludes it from selection;
every `ghost pull` includes it before selected guidance. The default skeleton
calls that node `brand`, but the filename is not reserved.
A node is one markdown file: a `for` payload in frontmatter (the situation or
activity the guidance is for), optional `materials`, and brand guidance in the
prose body.
The optional `cover:` in `manifest.yml` names the one page always included
by pull. gather excludes it from the selectable menu. The starting structure
calls it `brand`, but the filename is not reserved.

```markdown
---
Expand All @@ -135,22 +161,14 @@ Use the full lockup when recognition matters. Use the glyph only when space is
constrained or when brand presence should recede.
```

`materials` points at the concrete stuff the guidance is about through
explicit repo-relative file paths or supported external references. Name each
file rather than reaching for a glob pattern. An opaque entry may
include a short note describing what the agent will find there. Components,
patterns, logos, motion files, illustrations, and external asset libraries all
use the same field. Guidance stays in prose; `materials` only says where the
material is.

**Checks** are optional review assertions in a flat `.ghost/checks/` directory.
Core `ghost init` ships no checks; add them explicitly:

```bash
ghost checks init
```
`for` states when the file applies. `materials` lists its sources as explicit
repo-relative paths or supported external references. Name each file instead
of using a glob. A reference may include a short note about what the agent
will find there. Guidance stays in prose; sources say where to look.

Checks are not nodes. They are review assertions used by `ghost review`:
**Review checks** are optional assertions in `.ghost/checks/`. Core
`ghost init` ships no review checks; opt in with `ghost checks init`.
They are used only by review, never by gather or pull:

```markdown
---
Expand All @@ -161,26 +179,79 @@ references:
- asset.logo
---

Grade whether the change preserves the logo guidance in `asset.logo`.
Assess whether the change preserves the logo guidance in `asset.logo`.
```

`gather` and `pull` give your agent applicable guidance before it builds.
`review` supports the same agent after a change exists: the CLI reads a diff,
matches touched files to node `materials`, and offers relevant checks for the
agent to weigh. Review output never enters generation context.

## The Package Travels

Different agents can read the same guidance and apply it to a screen, page,
email, or sentence. The package moves with the repo when someone clones or
forks it. To move the package on its own, copy the `.ghost/` directory and run
`ghost validate --package <dir>` in the receiving workspace.
review reads a diff, matches touched files to guidance sources, and offers
review checks for the agent to weigh. Review output never enters generation
context. Use `ghost review --node` to add guidance that governs a change even
when its sources were not touched. See the CLI reference for flag usage.

## What ghost can verify

ghost's CLI delivery is observable by design. That is a deliberate contrast
with pasting a document into a prompt: ghost supplies a local record of what
its CLI delivered, not evidence of what the model read.

- Successful `gather` and `pull` calls are logged locally in a private
run log excluded from git, so a run shows which guidance was requested and delivered.
- Agents can keep delivered context task-scoped. An email task can pull the
email guidance; a deck task can pull the deck guidance. Different tasks
can pull different subsets instead of the whole book every time.
- Delivery is tested end to end: transport tests verify that complete
guidance survives the pipe, and included source content is always marked
as untrusted source data.

One honest boundary: a pull proves CLI delivery, not adherence. It does not
prove that the host passed the full output to the model or that the model
read it. Whether the agent followed the guidance is what review, and your
assessment, are for.

Don't take our word for it. The repo ships two evaluation harnesses:
[`packages/context-control`](./packages/context-control) measures whether
agents select the applicable guidance from the menu, and
[`packages/steering-control`](./packages/steering-control) measures what a
package buys before and after, as a self-contained report. Run them
against your own package.

## What ghost does not do

- It does not score brand quality or grade outputs.
- It does not learn the brand automatically; humans confirm every decision.
- It does not guarantee adherence; it makes delivery and review inspectable.
- It does not lock you to a model, agent, or service. The package is plain
files in your git.

## Why not just…

**…put it in AGENTS.md?** Agent instruction files are always-on: every
rule rides along on every task, whether it applies or not. ghost guidance
is selected per task, so the agent can leave email rules out of a dashboard,
and the package can grow without growing every prompt.

**…paste the brand guide into the prompt?** All-or-nothing delivery, no
CLI record of what was delivered, and the guide competes with the task for
attention. ghost delivers the subset the agent selects and logs successful
pulls.

**…use RAG over the brand docs?** Search finds what sounds similar.
Applicability is situational: the guidance that governs a payment form may
never share vocabulary with the request. ghost shows the whole selectable
menu with explicit conditions and lets the agent judge applicability directly.

## What it costs to start

You do not need a finished brand book. `ghost init` scaffolds a usable
starter package, and one real decision beats an empty taxonomy: write down
the thing reviewers keep repeating, give it a condition, and let the
package grow from use. Guidance is markdown in your repo, so maintenance
is ordinary review: edit the file, see the diff, merge.

## Repo Layout

| Path | Role | Published? |
| ---- | ---- | --- |
| [`packages/ghost`](./packages/ghost) | The public `ghost` CLI, node authoring, package validation, gather/pull, review packet assembly, and the skill bundle. | yes: `@design-intelligence/ghost` |
| [`packages/ghost`](./packages/ghost) | The public `ghost` CLI, guidance authoring, package validation, gather/pull, review packet assembly, and the skill bundle. | yes: `@design-intelligence/ghost` |
| [`packages/vessel-react`](./packages/vessel-react) | A standalone shadcn component registry and reference component system. | no |
| [`packages/vessel-light`](./packages/vessel-light) | Vessel's design language as a portable `.ghost/` package for agents writing raw HTML/CSS. | no |
| [`packages/context-control`](./packages/context-control) | Selection evaluation bench: measures whether agents choose applicable guidance from the complete menu. | no |
Expand Down
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "ghost",
"private": true,
"description": "Portable brand guidance for AI agents",
"description": "Portable brand guidance that agents read before making and use during review.",
"license": "Apache-2.0",
"packageManager": "pnpm@10.33.0",
"engines": {
Expand Down
Loading
Loading