diff --git a/.changeset/repo-front-door.md b/.changeset/repo-front-door.md new file mode 100644 index 00000000..dfbecea4 --- /dev/null +++ b/.changeset/repo-front-door.md @@ -0,0 +1,5 @@ +--- +"@design-intelligence/ghost": patch +--- + +Clarify how ghost brings brand intelligence into agent work, and restructure the README around the workflow, quickstart, comparisons, and repository map. diff --git a/README.md b/README.md index 4001e0a9..0db8cfa9 100644 --- a/README.md +++ b/README.md @@ -1,164 +1,82 @@ -# ghost +# ghost: brand intelligence for your agents -ghost is a brand context router for agents. You record your brand's design -decisions and when they apply. Your agent selects the guidance for the task, -and ghost delivers it before work begins. +[![npm version](https://img.shields.io/npm/v/@design-intelligence/ghost.svg)](https://www.npmjs.com/package/@design-intelligence/ghost) +[![CI](https://github.com/block/ghost/actions/workflows/ci.yml/badge.svg)](https://github.com/block/ghost/actions/workflows/ci.yml) +[![Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-black.svg)](./LICENSE) -Keep the guidance as markdown files in your repo, alongside the code and -assets it refers to. You confirm the decisions and review the work your -agent makes with them. +![without ghost on left, with ghost on right](https://github.com/user-attachments/assets/83047373-a9ee-4a76-b0e5-1cb446c2b59c) -ghost works with Claude Code, Codex, Cursor, OpenCode, and Goose. The CLI -calls no model and needs no API key. +Agents can make almost anything. The hard part is making it yours. -[Project site](https://block.github.io/ghost/) · -[npm](https://www.npmjs.com/package/@design-intelligence/ghost) +**ghost** keeps your brand decisions alongside your code and assets. Before each task, it gives your agent the relevant guidance and materials. -> [!NOTE] -> ghost is an early preview. The CLI, package format, and APIs can change -> without migration support, and breaking changes can ship in minor versions. -> Try it on a real repo and tell us what broke or confused you. - -## Install +Models generate the likeliest thing. **ghost** helps make *your brand* the likeliest thing. -Requires Node 20.19+ or 22.12+. - -```bash -npm install -D @design-intelligence/ghost -npx ghost skill install -``` +It works with the tools, agents, and models you already use. The CLI doesn't make its own model calls or need an API key. -The skill gives your agent instructions for setting up and using ghost. -If you use several agents, choose the destination with -`npx ghost skill install --agent goose`, for example. - -With the skill installed, ask your agent to do the setup: - -```text -Set up the ghost package for this repo. -``` - -Your agent runs `ghost init` to create a `.ghost/` folder with starter -guidance. Treat those starting answers as provisional until you accept or -replace them. Share existing brand docs, examples you like, or corrections -you keep making; your agent can help turn them into guidance for you to -confirm. - -## Write down one decision - -Give your agent one decision and the situation it applies to: +> [!NOTE] +> **ghost** is an early preview. The CLI, package format, and APIs can change +> without migration support, and breaking changes can ship in minor versions. +> +> _Try it on a real repo and tell us what broke or confused you._ -```text -Record this decision as ghost guidance: a payment-failure message states -the known fact and the recovery action. It never speculates about the cause. -``` -Your agent drafts a file for you to confirm. Something like -`.ghost/payment-failure.md`: -```markdown ---- -for: Writing an email, error message, or support reply about a failed payment. ---- +[Get started](./packages/ghost/README.md#get-started) · +[Authoring guide](./packages/ghost/src/skill-bundle/references/authoring.md) · +[Package format](./packages/ghost/src/skill-bundle/references/schema.md) -State what we know and what the customer can do next. "Your card was -declined. Try another card or contact your bank." Do not guess at the -reason, and do not imply fault. -``` -Check the wording before accepting the draft. The `for` line tells the -agent when to use it; the body gives the decision. Ask your agent to link -relevant code or assets if you have them. Review changes to the guidance -through Git, as you would any other file in your repo. +## How it works -The same rule can apply to an email, an error message, or a support reply. -Each task may need different guidance alongside it, such as email structure -or the tone of a support response. +**ghost** separates mechanics from guidance. The mechanics determine which +nodes are available, when they apply, what travels with them, and what +reviewers check. Guidance is the brand context those mechanics deliver to the +agent. -Now give your agent the actual work: +![guidance moving from a ghost package into agent work](https://github.com/user-attachments/assets/8685af17-fb8e-4ae2-bdca-6cdff41fcf44) ```text -Use the ghost guidance to write the email we send when a subscription -renewal is declined. +Your task + │ + ▼ +ghost gather shows the complete guidance menu + │ + ▼ +Your agent selects every item that applies + │ + ▼ +ghost pull delivers the guidance and materials + │ + ▼ +Your agent makes the work; you review the result ``` -You don't need to run retrieval commands yourself. Under that request, -your agent runs something like: - -```bash -npx ghost gather "email for a declined subscription renewal" -npx ghost pull payment-failure foundation.voice -``` - -`foundation.voice` comes from the starter; `payment-failure` is the file you -added. `gather` lists all valid, selectable guidance, without filtering or -ranking by the task. Your agent selects every applicable file and uses -`pull` to read it, along with the package's cover if it has one. A rule can -apply even if its words don't appear in your request. - -When guidance points to source files, the CLI includes eligible local text -or provides pointers for your agent to inspect. It doesn't fetch external -references. `ghost stats` summarizes the local selection log so you can see -which guidance agents pull. - -## What you still have to do - -Review the email against the decision you recorded. Did it state the known -failure and give a recovery action without inventing a cause? - -ghost doesn't learn your brand on its own or score the result. You confirm -the decisions; your agent interprets them. The local log records selections -and delivery counts, not proof that the model received or followed the -guidance. You can use the same guidance files with another agent or model. - -## Review checks, if you want them - -You can add review instructions in `.ghost/checks/` for your agent to assess -a change against your guidance. Ask it: +A `.ghost/` package is a versioned set of markdown files: ```text -Set up ghost review checks for our payment-failure guidance. -Review this diff against those checks. +.ghost/ +├── manifest.yml package identity and cover +├── glossary.md your vocabulary +├── brand.md guidance every task receives +├── foundation.voice.md a broad brand decision +├── payment-recovery.md guidance for one situation +├── materials/ tokens, examples, and source files +└── checks/ optional review instructions ``` -The default starter has no checks. `ghost checks init` adds an example for -you to adapt. `ghost review` requires the checks directory and a diff; it -assembles the change, matched guidance, and checks for your agent to assess. -It doesn't grade the work. Checks stay out of gather and pull output. - -## Reference - -If you want to run the CLI yourself, use `npx ghost`: - -```bash -npx ghost validate # check guidance and review checks -npx ghost gather "" # list the guidance menu for your agent to select from -npx ghost pull # read selected guidance and the cover, if present -npx ghost review # assemble a review packet for a diff -npx ghost stats # summarize local usage -``` - -See the [package and CLI reference](./packages/ghost/src/skill-bundle/references/schema.md) -for formats and flags, or the [authoring guide](./packages/ghost/src/skill-bundle/references/authoring.md) -for creating and updating guidance. - -## Alongside other tools - -Keep repo-wide instructions in `AGENTS.md`. Use `.ghost/` for brand decisions -that apply to particular tasks, so email rules don't need to accompany a -dashboard request. - -For a short guide, pasting the text into a prompt may be enough. With ghost, -you maintain the guidance in your repo and let your agent choose from the -menu for each task, rather than choosing passages to paste each time. +Your agent sees the complete menu and pulls only what applies. **ghost** never +ranks the menu or selects guidance for the agent. -## Contributing and evaluations +## Go deeper -See [Contributing](./CONTRIBUTING.md) for development and release checks. -To test your own guidance, use [context-control](./packages/context-control) -to measure selection and [steering-control](./packages/steering-control) -to compare outputs with and without a package. +- [Package guide](./packages/ghost/README.md) — setup, everyday use, and review +- [Authoring guide](./packages/ghost/src/skill-bundle/references/authoring.md) — write and maintain guidance +- [Package format](./packages/ghost/src/skill-bundle/references/schema.md) — package layout, fields, checks, and command behavior +- [context-control](./packages/context-control) — test whether agents select the right guidance +- [steering-control](./packages/steering-control) — compare work made with and without **ghost** +- [Contributing](./CONTRIBUTING.md) — develop and release the project ## License -[Apache License 2.0](./LICENSE) · [Governance](./GOVERNANCE.md) +[Apache License 2.0](./LICENSE) diff --git a/packages/ghost/README.md b/packages/ghost/README.md index 0f6b89a1..f2ed1db2 100644 --- a/packages/ghost/README.md +++ b/packages/ghost/README.md @@ -1,25 +1,75 @@ # @design-intelligence/ghost -ghost is a brand context router for agents. You record your brand's design -decisions and when they apply. Your agent selects the guidance for the task, -and ghost delivers it before work begins. +[![npm version](https://img.shields.io/npm/v/@design-intelligence/ghost.svg)](https://www.npmjs.com/package/@design-intelligence/ghost) +[![CI](https://github.com/block/ghost/actions/workflows/ci.yml/badge.svg)](https://github.com/block/ghost/actions/workflows/ci.yml) +[![Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-black.svg)](https://github.com/block/ghost/blob/main/LICENSE) -Keep the guidance as markdown files in your repo, alongside the code and -assets it refers to. You confirm the decisions and review the work your -agent makes with them. +**Brand intelligence for your agents.** -ghost works with Claude Code, Codex, Cursor, OpenCode, and Goose. The CLI -calls no model and needs no API key. +Agents give more people the tools to bring an idea to life. They do not give +everyone the guidance or experience to direct that work. Without clear brand +context, model output tends toward the average. -[Project site](https://block.github.io/ghost/) · -[Repo](https://github.com/block/ghost) +ghost brings the right brand context into the work your agents create. Record +your brand's decisions as markdown, alongside the code and assets they refer +to. For each task, ghost provides the complete guidance menu. Your agent selects +what is relevant rather than receiving all brand context every time, then ghost +delivers the full guidance and materials before work begins. + +A model generates the likeliest thing. ghost helps make your brand the +likeliest thing, so agents can produce work your team would actually use. + +ghost works where you do: Claude Code, Codex, Cursor, OpenCode, and Goose. It +uses the agent and model you already use. The CLI does not call a model on its +own or require an API key. + +[Get started](#get-started) · +[Authoring guide](https://github.com/block/ghost/blob/main/packages/ghost/src/skill-bundle/references/authoring.md) · +[Package format](https://github.com/block/ghost/blob/main/packages/ghost/src/skill-bundle/references/schema.md) > [!NOTE] > ghost is an early preview. The CLI, package format, and APIs can change > without migration support, and breaking changes can ship in minor versions. > Try it on a real repo and tell us what broke or confused you. -## Install +## How it works + +```text +Your task + │ + ▼ +ghost gather shows the complete guidance menu + │ + ▼ +Your agent selects every item that applies + │ + ▼ +ghost pull delivers the selected guidance and materials + │ + ▼ +Your agent makes the work; you review the result +``` + +A `.ghost/` package turns your brand's identity into guidance an agent can +find and use. It keeps broad brand stances, task-specific decisions, and +pointers to concrete materials in one versioned place. The agent sees the +shape of the whole package, then loads only what the current task needs. + +```text +.ghost/ +├── manifest.yml package identity and cover +├── glossary.md your vocabulary +├── brand.md guidance every task receives +├── foundation.voice.md a broad brand decision +├── payment-failure.md guidance for a specific situation +├── materials/ tokens, examples, and other source files +└── checks/ optional review instructions +``` + +You confirm the decisions. Your agent interprets and applies them. ghost makes +that exchange portable, inspectable, and repeatable across agents and models. + +## Get started Requires Node 20.19+ or 22.12+. @@ -28,33 +78,38 @@ npm install -D @design-intelligence/ghost npx ghost skill install ``` -The skill gives your agent instructions for setting up and using ghost. -If you use several agents, choose the destination with -`npx ghost skill install --agent goose`, for example. +The skill teaches your agent how to set up and use ghost. If you use several +agents, choose a destination explicitly: + +```bash +npx ghost skill install --agent claude +npx ghost skill install --agent cursor +npx ghost skill install --agent codex +npx ghost skill install --agent opencode +npx ghost skill install --agent goose +``` -With the skill installed, ask your agent to do the setup: +Then ask your agent to create the package: ```text Set up the ghost package for this repo. ``` -Your agent runs `ghost init` to create a `.ghost/` folder with starter -guidance. Treat those starting answers as provisional until you accept or -replace them. Share existing brand docs, examples you like, or corrections -you keep making; your agent can help turn them into guidance for you to -confirm. +Your agent runs `ghost init` and creates starter guidance in `.ghost/`. Treat +those starting answers as provisional until you accept or replace them. Share +existing brand docs, examples you like, or corrections you keep making. Your +agent can turn them into guidance for you to confirm. -## Write down one decision +## Record one decision -Give your agent one decision and the situation it applies to: +Give your agent a decision and the situation where it applies: ```text Record this decision as ghost guidance: a payment-failure message states the known fact and the recovery action. It never speculates about the cause. ``` -Your agent drafts a file for you to confirm. Something like -`.ghost/payment-failure.md`: +Your agent drafts a file such as `.ghost/payment-failure.md`: ```markdown --- @@ -66,102 +121,116 @@ declined. Try another card or contact your bank." Do not guess at the reason, and do not imply fault. ``` -Check the wording before accepting the draft. The `for` line tells the -agent when to use it; the body gives the decision. Ask your agent to link -relevant code or assets if you have them. Review changes to the guidance -through Git, as you would any other file in your repo. +The `for` line tells the agent when to use the decision. The body says what to +do. Review the draft before accepting it, and link the code or assets that make +the decision concrete. -The same rule can apply to an email, an error message, or a support reply. -Each task may need different guidance alongside it, such as email structure -or the tone of a support response. - -Now give your agent the actual work: +Now give your agent the work: ```text Use the ghost guidance to write the email we send when a subscription renewal is declined. ``` -You don't need to run retrieval commands yourself. Under that request, -your agent runs something like: +Under that request, the agent runs the selection loop: ```bash npx ghost gather "email for a declined subscription renewal" npx ghost pull payment-failure foundation.voice ``` -`foundation.voice` comes from the starter; `payment-failure` is the file you -added. `gather` lists all valid, selectable guidance, without filtering or -ranking by the task. Your agent selects every applicable file and uses -`pull` to read it, along with the package's cover if it has one. A rule can -apply even if its words don't appear in your request. +`gather` shows every valid, selectable guidance item. It does not filter or +rank the menu. The agent selects every item that applies and uses `pull` to +load the full guidance, the package cover, and eligible materials. + +## What ghost changes -When guidance points to source files, the CLI includes eligible local text -or provides pointers for your agent to inspect. It doesn't fetch external -references. `ghost stats` summarizes the local selection log so you can see -which guidance agents pull. +A model starts from broad patterns. Your brand lives in specific decisions: +what to emphasize, what to leave out, which materials to use, and how the parts +fit together. ghost makes those decisions available at the moment an agent +needs them, helping close the gap between model output and brand intent. -## What you still have to do +| Without ghost | With ghost | +| --- | --- | +| Rely on the model's default guess at your brand | Direct the work with decisions your team confirmed | +| Choose passages by hand for each prompt | Let the agent select from the complete guidance menu | +| Load a whole guide into every task | Pull only the guidance relevant to the task | +| Keep agent-specific copies of brand rules | Use the same package across supported agents | +| Guess whether drift began in selection or execution | Inspect the menu, selections, and local usage summary | +| Review against memory | Add checks tied to the recorded guidance | + +To measure the effect on your own brand, use +[context-control](https://github.com/block/ghost/tree/main/packages/context-control) +to test selection and +[steering-control](https://github.com/block/ghost/tree/main/packages/steering-control) +to compare work made with and without a ghost package. -Review the email against the decision you recorded. Did it state the known -failure and give a recovery action without inventing a cause? +## Where ghost fits -ghost doesn't learn your brand on its own or score the result. You confirm -the decisions; your agent interprets them. The local log records selections -and delivery counts, not proof that the model received or followed the -guidance. You can use the same guidance files with another agent or model. +| Tool | Best used for | +| --- | --- | +| `AGENTS.md` | Repo-wide instructions that accompany every task | +| Agent or editor rules | Preferences for one tool or working environment | +| Design tokens | Machine-readable visual values | +| Component libraries | Reusable implementation materials | +| Asset libraries and design files | Source artwork and visual references | +| **ghost** | Broad brand stances and decisions for particular situations | -## Review checks, if you want them +These tools work together. Keep repo-wide operating instructions in +`AGENTS.md`, concrete values in tokens, implementation in components, and +conditional brand guidance in `.ghost/`. -You can add review instructions in `.ghost/checks/` for your agent to assess -a change against your guidance. Ask it: +## Review the work + +You still judge whether the result follows the decision you recorded. ghost +does not learn your brand on its own, choose guidance for the agent, or score +the result. + +Optional checks in `.ghost/checks/` give an agent review instructions tied to +specific guidance. Ask your agent: ```text Set up ghost review checks for our payment-failure guidance. Review this diff against those checks. ``` -The default starter has no checks. `ghost checks init` adds an example for -you to adapt. `ghost review` requires the checks directory and a diff; it -assembles the change, matched guidance, and checks for your agent to assess. -It doesn't grade the work. Checks stay out of gather and pull output. - -## Reference +`ghost review` assembles the change, relevant guidance, and checks for the +agent to assess. Checks never enter the generation menu. -If you want to run the CLI yourself, use `npx ghost`: +## CLI ```bash +npx ghost init # create a starter package npx ghost validate # check guidance and review checks -npx ghost gather "" # list the guidance menu for your agent to select from -npx ghost pull # read selected guidance and the cover, if present +npx ghost gather "" # show the complete guidance menu +npx ghost pull # read selected guidance and the cover npx ghost review # assemble a review packet for a diff npx ghost stats # summarize local usage +npx ghost skill install # install the agent skill ``` -See the [package and CLI reference](https://github.com/block/ghost/blob/main/packages/ghost/src/skill-bundle/references/schema.md) -for formats and flags, or the [authoring guide](https://github.com/block/ghost/blob/main/packages/ghost/src/skill-bundle/references/authoring.md) +Run `npx ghost --help` or `npx ghost --help` for current commands and +flags. See the [package format](https://github.com/block/ghost/blob/main/packages/ghost/src/skill-bundle/references/schema.md) +for the on-disk contract, or the [authoring guide](https://github.com/block/ghost/blob/main/packages/ghost/src/skill-bundle/references/authoring.md) for creating and updating guidance. -## Alongside other tools +## What's in the repo -Keep repo-wide instructions in `AGENTS.md`. Use `.ghost/` for brand decisions -that apply to particular tasks, so email rules don't need to accompany a -dashboard request. +| Path | Role | +| --- | --- | +| [`packages/ghost`](https://github.com/block/ghost/tree/main/packages/ghost) | The public CLI and agent skill bundle. Install this. | +| [`packages/context-control`](https://github.com/block/ghost/tree/main/packages/context-control) | Tests whether agents select the right guidance. | +| [`packages/steering-control`](https://github.com/block/ghost/tree/main/packages/steering-control) | Compares work made with and without a ghost package. | +| [`packages/vessel-light`](https://github.com/block/ghost/tree/main/packages/vessel-light) | An example design language packaged for raw HTML and CSS work. | +| [`packages/vessel-react`](https://github.com/block/ghost/tree/main/packages/vessel-react) | The reference component system used to exercise ghost workflows. | +| [`apps/docs`](https://github.com/block/ghost/tree/main/apps/docs) | The project site and development log. | -For a short guide, pasting the text into a prompt may be enough. With ghost, -you maintain the guidance in your repo and let your agent choose from the -menu for each task, rather than choosing passages to paste each time. +## Contributing -## Contributing and evaluations - -See [Contributing](https://github.com/block/ghost/blob/main/CONTRIBUTING.md) -for development and release checks. To test your own guidance, use -[context-control](https://github.com/block/ghost/tree/main/packages/context-control) -to measure selection and -[steering-control](https://github.com/block/ghost/tree/main/packages/steering-control) -to compare outputs with and without a package. +See [Contributing](https://github.com/block/ghost/blob/main/CONTRIBUTING.md) for +local development, tests, and release checks. Project decisions follow the +public [Governance](https://github.com/block/ghost/blob/main/GOVERNANCE.md). ## License -[Apache License 2.0](https://github.com/block/ghost/blob/main/LICENSE) · -[Governance](https://github.com/block/ghost/blob/main/GOVERNANCE.md) +[Apache License 2.0](https://github.com/block/ghost/blob/main/LICENSE)