From 35fa947267d02ebbbaf2e59dd3be3cdfcb17cae6 Mon Sep 17 00:00:00 2001 From: Chai Landau Date: Tue, 3 Nov 2026 17:33:53 -0500 Subject: [PATCH 01/16] Restructure the public README Reframe the root and npm READMEs around brand intelligence, the gather-and-pull workflow, a direct quickstart, and the repository map. --- .changeset/repo-front-door.md | 5 + README.md | 224 +++++++++++++++++++++------------ packages/ghost/README.md | 228 ++++++++++++++++++++++------------ 3 files changed, 300 insertions(+), 157 deletions(-) create mode 100644 .changeset/repo-front-door.md 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..2dcac502 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,75 @@ # 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)](./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/) · -[npm](https://www.npmjs.com/package/@design-intelligence/ghost) +ghost brings the right brand context into the work your agents create. Record +your brand's decisions 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](./packages/ghost/src/skill-bundle/references/authoring.md) · +[CLI reference](./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 the package's own categories +├── 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,99 +121,114 @@ 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 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. +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. -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 | -Review the email against the decision you recorded. Did it state the known -failure and give a recovery action without inventing a cause? +To measure the effect on your own brand, use +[context-control](./packages/context-control) to test selection and +[steering-control](./packages/steering-control) to compare work made with and +without a ghost package. -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. +## Where ghost fits -## Review checks, if you want them +| 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** | Brand decisions that apply only in particular situations | -You can add review instructions in `.ghost/checks/` for your agent to assess -a change against your guidance. Ask it: +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/`. + +## 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. +`ghost review` assembles the change, relevant guidance, and checks for the +agent to assess. Checks never enter the generation menu. -## Reference - -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](./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. +## What's in this repo -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. +| Path | Role | +| --- | --- | +| [`packages/ghost`](./packages/ghost) | The public CLI and agent skill bundle. Install this. | +| [`packages/context-control`](./packages/context-control) | Tests whether agents select the right guidance. | +| [`packages/steering-control`](./packages/steering-control) | Compares work made with and without a ghost package. | +| [`packages/vessel-light`](./packages/vessel-light) | An example design language packaged for raw HTML and CSS work. | +| [`packages/vessel-react`](./packages/vessel-react) | The reference component system used to exercise ghost workflows. | +| [`apps/docs`](./apps/docs) | The project site and development log. | -## Contributing and evaluations +## Contributing -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. +See [Contributing](./CONTRIBUTING.md) for local development, tests, and release +checks. Project decisions follow the public [Governance](./GOVERNANCE.md). ## License -[Apache License 2.0](./LICENSE) · [Governance](./GOVERNANCE.md) +[Apache License 2.0](./LICENSE) +s pro diff --git a/packages/ghost/README.md b/packages/ghost/README.md index 0f6b89a1..31c0e74e 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) · +[CLI reference](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 the package's own categories +├── 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,115 @@ 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** | Brand decisions that apply only in 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) 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) From 87bcf9010c7ab3b75763f1fb8129970d0baae383 Mon Sep 17 00:00:00 2001 From: Chai Landau <112015853+chailandau@users.noreply.github.com> Date: Tue, 3 Nov 2026 17:38:23 -0500 Subject: [PATCH 02/16] Enhance README with image and .ghost package details Added an image and expanded on the functionality of the .ghost package in the README. --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 2dcac502..05debe42 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,9 @@ ghost pull delivers the selected guidance and materials Your agent makes the work; you review the result ``` +guidance-animation + + 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 From 4fd27437305d5affe265cfb12a97b772e68ecb1c Mon Sep 17 00:00:00 2001 From: Chai Landau <112015853+chailandau@users.noreply.github.com> Date: Tue, 3 Nov 2026 17:40:08 -0500 Subject: [PATCH 03/16] Fix README formatting and remove duplicate image Removed duplicate guidance animation image and cleaned up the text. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 05debe42..4f72d81c 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,8 @@ own or require an API key. ## How it works +guidance-animation + ```text Your task │ @@ -50,8 +52,6 @@ ghost pull delivers the selected guidance and materials Your agent makes the work; you review the result ``` -guidance-animation - 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 From b211f9ba705b0cdb085ab06eb187dd3d11c094cb Mon Sep 17 00:00:00 2001 From: Chai Landau <112015853+chailandau@users.noreply.github.com> Date: Tue, 3 Nov 2026 17:40:43 -0500 Subject: [PATCH 04/16] Update image width in README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4f72d81c..44d9bc98 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ own or require an API key. ## How it works -guidance-animation +guidance-animation ```text Your task From 1fbb7b9503f7272f2ca266351374f8a953d6f30a Mon Sep 17 00:00:00 2001 From: Chai Landau <112015853+chailandau@users.noreply.github.com> Date: Tue, 3 Nov 2026 17:51:29 -0500 Subject: [PATCH 05/16] Update README with images and formatting fixes --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 44d9bc98..0a19bfc9 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![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) -**Brand intelligence for your agents.** +![brand intelligence for your agents](https://github.com/user-attachments/assets/d4dce405-387e-44b9-93c1-fad91743622c) 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 @@ -30,11 +30,12 @@ own or require an API key. > [!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. ## How it works -guidance-animation +![guidance-animation](https://github.com/user-attachments/assets/8685af17-fb8e-4ae2-bdca-6cdff41fcf44) ```text Your task @@ -234,4 +235,3 @@ checks. Project decisions follow the public [Governance](./GOVERNANCE.md). ## License [Apache License 2.0](./LICENSE) -s pro From b3d65d68cf04a09294b7aa5310cd67b7fab309be Mon Sep 17 00:00:00 2001 From: Chai Landau <112015853+chailandau@users.noreply.github.com> Date: Tue, 3 Nov 2026 18:01:27 -0500 Subject: [PATCH 06/16] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0a19bfc9..589ef254 100644 --- a/README.md +++ b/README.md @@ -177,7 +177,7 @@ without a ghost package. | Design tokens | Machine-readable visual values | | Component libraries | Reusable implementation materials | | Asset libraries and design files | Source artwork and visual references | -| **ghost** | Brand decisions that apply only in particular situations | +| **ghost** | Broad brand stances and decisions for particular situations | These tools work together. Keep repo-wide operating instructions in `AGENTS.md`, concrete values in tokens, implementation in components, and From 80c22103f490ee220e69946bd3accb8cc352a2f9 Mon Sep 17 00:00:00 2001 From: Chai Landau <112015853+chailandau@users.noreply.github.com> Date: Tue, 3 Nov 2026 18:01:36 -0500 Subject: [PATCH 07/16] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 589ef254..480efe23 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ shape of the whole package, then loads only what the current task needs. ```text .ghost/ ├── manifest.yml package identity and cover -├── glossary.md the package's own categories +├── glossary.md the package's own kinds ├── brand.md guidance every task receives ├── foundation.voice.md a broad brand decision ├── payment-failure.md guidance for a specific situation From 4a4eedb360011d10dd98e139c3ea0b74b098ad19 Mon Sep 17 00:00:00 2001 From: Chai Landau <112015853+chailandau@users.noreply.github.com> Date: Tue, 3 Nov 2026 18:09:00 -0500 Subject: [PATCH 08/16] Revise README for clarity on agents and ghost Updated the README to clarify the role of agents and the ghost tool in providing brand context and guidance. --- README.md | 23 +++++++---------------- 1 file changed, 7 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 480efe23..844e28c1 100644 --- a/README.md +++ b/README.md @@ -6,22 +6,13 @@ ![brand intelligence for your agents](https://github.com/user-attachments/assets/d4dce405-387e-44b9-93c1-fad91743622c) -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. - -ghost brings the right brand context into the work your agents create. Record -your brand's decisions 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. +Agents help us bring more ideas to life, faster. But without the right brand context, the result looks exactly like what it is: agent work. + +_ghost_ keeps your brand decisions alongside your code and assets. Before each task, it gives your agent the relevant guidance and materials. + +Models generate the likeliest thing. _ghost_ helps make **your brand** the likeliest thing. + +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. [Get started](#get-started) · [Authoring guide](./packages/ghost/src/skill-bundle/references/authoring.md) · From 6a7d900219f94767892ebc8f0f9fbe2f6b432b39 Mon Sep 17 00:00:00 2001 From: Chai Landau <112015853+chailandau@users.noreply.github.com> Date: Wed, 4 Nov 2026 16:09:46 -0500 Subject: [PATCH 09/16] Update README to remove duplicate preview note Removed duplicate note about ghost being an early preview. --- README.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 844e28c1..f96a0b04 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,10 @@ + +> [!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. + # ghost [![npm version](https://img.shields.io/npm/v/@design-intelligence/ghost.svg)](https://www.npmjs.com/package/@design-intelligence/ghost) @@ -18,12 +25,6 @@ It works with the tools, agents, and models you already use. The CLI doesn't mak [Authoring guide](./packages/ghost/src/skill-bundle/references/authoring.md) · [CLI reference](./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. - ## How it works ![guidance-animation](https://github.com/user-attachments/assets/8685af17-fb8e-4ae2-bdca-6cdff41fcf44) From efcbdf1645df5ab9c117a47ece0899a17638abcc Mon Sep 17 00:00:00 2001 From: Chai Landau <112015853+chailandau@users.noreply.github.com> Date: Wed, 4 Nov 2026 20:45:00 -0500 Subject: [PATCH 10/16] Clean up README by removing duplicate note Removed duplicate note about ghost being an early preview. --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index f96a0b04..797fc94b 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,3 @@ - -> [!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. - # ghost [![npm version](https://img.shields.io/npm/v/@design-intelligence/ghost.svg)](https://www.npmjs.com/package/@design-intelligence/ghost) @@ -21,6 +14,13 @@ Models generate the likeliest thing. _ghost_ helps make **your brand** the likel 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. + +> [!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. + [Get started](#get-started) · [Authoring guide](./packages/ghost/src/skill-bundle/references/authoring.md) · [CLI reference](./packages/ghost/src/skill-bundle/references/schema.md) From c54f2c6d1ac73f15cf7803dbafe4d19f541986ed Mon Sep 17 00:00:00 2001 From: Chai Landau <112015853+chailandau@users.noreply.github.com> Date: Wed, 4 Nov 2026 20:48:33 -0500 Subject: [PATCH 11/16] Enhance README with details on _ghost_ mechanics Clarify the role of _ghost_ in separating mechanics from guidance, and update the explanation of the .ghost/ package. --- README.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 797fc94b..ea1b20a8 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,8 @@ It works with the tools, agents, and models you already use. The CLI doesn't mak ## How it works +_ghost_ separates mechanics from guidance. The mechanics handle selection, assembly, and review: which nodes are available, when they apply, what materials accompany them, and what reviewers check. The guidance is the brand context those mechanics deliver to the agent. + ![guidance-animation](https://github.com/user-attachments/assets/8685af17-fb8e-4ae2-bdca-6cdff41fcf44) ```text @@ -45,12 +47,6 @@ 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 From db801720c5d2fe0dddd5e49d37607067be34856e Mon Sep 17 00:00:00 2001 From: Chai Landau Date: Wed, 4 Nov 2026 21:00:33 -0500 Subject: [PATCH 12/16] Streamline the README front door Keep the introduction, workflow, and package outline concise. Link setup and detailed usage to existing guides so readers can choose how far to go. Co-authored-by: Sol 5.6 <2be45693458a7d45edf11882226b8bc6246772f8719faed540576070d8b0464f@buzz.block.builderlab.xyz> --- README.md | 201 ++++++++---------------------------------------------- 1 file changed, 28 insertions(+), 173 deletions(-) diff --git a/README.md b/README.md index ea1b20a8..30458118 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ ![brand intelligence for your agents](https://github.com/user-attachments/assets/d4dce405-387e-44b9-93c1-fad91743622c) -Agents help us bring more ideas to life, faster. But without the right brand context, the result looks exactly like what it is: agent work. +Agents can make almost anything. The hard part is making it yours. _ghost_ keeps your brand decisions alongside your code and assets. Before each task, it gives your agent the relevant guidance and materials. @@ -14,22 +14,25 @@ Models generate the likeliest thing. _ghost_ helps make **your brand** the likel 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. - > [!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. -[Get started](#get-started) · +[Get started](./packages/ghost/README.md#get-started) · [Authoring guide](./packages/ghost/src/skill-bundle/references/authoring.md) · [CLI reference](./packages/ghost/src/skill-bundle/references/schema.md) + ## How it works -_ghost_ separates mechanics from guidance. The mechanics handle selection, assembly, and review: which nodes are available, when they apply, what materials accompany them, and what reviewers check. The guidance is the brand context those mechanics deliver to the agent. +_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. -![guidance-animation](https://github.com/user-attachments/assets/8685af17-fb8e-4ae2-bdca-6cdff41fcf44) +![guidance moving from a ghost package into agent work](https://github.com/user-attachments/assets/8685af17-fb8e-4ae2-bdca-6cdff41fcf44) ```text Your task @@ -41,184 +44,36 @@ ghost gather shows the complete guidance menu Your agent selects every item that applies │ ▼ -ghost pull delivers the selected guidance and materials +ghost pull delivers the guidance and materials │ ▼ Your agent makes the work; you review the result ``` -```text -.ghost/ -├── manifest.yml package identity and cover -├── glossary.md the package's own kinds -├── 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+. - -```bash -npm install -D @design-intelligence/ghost -npx ghost skill install -``` - -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 -``` - -Then ask your agent to create the package: - -```text -Set up the ghost package for this repo. -``` - -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. - -## Record one decision - -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 such as `.ghost/payment-failure.md`: - -```markdown ---- -for: Writing an email, error message, or support reply about a failed payment. ---- - -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. -``` - -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. - -Now give your agent the work: +A `.ghost/` package is a versioned set of markdown files: ```text -Use the ghost guidance to write the email we send when a subscription -renewal is declined. -``` - -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 -``` - -`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 - -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. - -| 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](./packages/context-control) to test selection and -[steering-control](./packages/steering-control) to compare work made with and -without a ghost package. - -## Where ghost fits - -| 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 | - -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/`. - -## 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. -``` - -`ghost review` assembles the change, relevant guidance, and checks for the -agent to assess. Checks never enter the generation menu. - -## CLI - -```bash -npx ghost init # create a starter package -npx ghost validate # check guidance and review checks -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 +.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 ``` -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. - -## What's in this repo - -| Path | Role | -| --- | --- | -| [`packages/ghost`](./packages/ghost) | The public CLI and agent skill bundle. Install this. | -| [`packages/context-control`](./packages/context-control) | Tests whether agents select the right guidance. | -| [`packages/steering-control`](./packages/steering-control) | Compares work made with and without a ghost package. | -| [`packages/vessel-light`](./packages/vessel-light) | An example design language packaged for raw HTML and CSS work. | -| [`packages/vessel-react`](./packages/vessel-react) | The reference component system used to exercise ghost workflows. | -| [`apps/docs`](./apps/docs) | The project site and development log. | +Your agent sees the complete menu and pulls only what applies. _ghost_ never +ranks the menu or selects guidance for the agent. -## Contributing +## Go deeper -See [Contributing](./CONTRIBUTING.md) for local development, tests, and release -checks. Project decisions follow the public [Governance](./GOVERNANCE.md). +- [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 +- [CLI reference](./packages/ghost/src/skill-bundle/references/schema.md) — commands, formats, and flags +- [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 From e3e80f4eaee22084306ea14e05d85187b351d4fd Mon Sep 17 00:00:00 2001 From: Chai Landau Date: Wed, 4 Nov 2026 21:44:07 -0500 Subject: [PATCH 13/16] Add a README comparison placeholder Reserve space for side-by-side results from the same prompt, with and without ghost guidance. --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index 30458118..509a0e14 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,11 @@ It works with the tools, agents, and models you already use. The CLI doesn't mak [Authoring guide](./packages/ghost/src/skill-bundle/references/authoring.md) · [CLI reference](./packages/ghost/src/skill-bundle/references/schema.md) +## Same prompt, two results + +| Without ghost | With ghost | +| --- | --- | +| _Add image_ | _Add image_ | ## How it works From 0198c6cf5c81d080a606c9cc6e30059322e9b8b3 Mon Sep 17 00:00:00 2001 From: Chai Landau <112015853+chailandau@users.noreply.github.com> Date: Wed, 4 Nov 2026 21:49:37 -0500 Subject: [PATCH 14/16] Revise branding and formatting in README.md Updated README to improve branding emphasis and formatting. --- README.md | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 509a0e14..d05fd446 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,35 @@ -# ghost +# ghost: brand intelligence for your agents [![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) -![brand intelligence for your agents](https://github.com/user-attachments/assets/d4dce405-387e-44b9-93c1-fad91743622c) +![without ghost on left, with ghost on right](https://github.com/user-attachments/assets/83047373-a9ee-4a76-b0e5-1cb446c2b59c) Agents can make almost anything. The hard part is making it yours. -_ghost_ keeps your brand decisions alongside your code and assets. Before each task, it gives your agent the relevant guidance and materials. +**ghost** keeps your brand decisions alongside your code and assets. Before each task, it gives your agent the relevant guidance and materials. -Models generate the likeliest thing. _ghost_ helps make **your brand** the likeliest thing. +Models generate the likeliest thing. **ghost** helps make *your brand* the likeliest thing. 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. > [!NOTE] -> ghost is an early preview. The CLI, package format, and APIs can change +> **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. +> _Try it on a real repo and tell us what broke or confused you._ + + [Get started](./packages/ghost/README.md#get-started) · [Authoring guide](./packages/ghost/src/skill-bundle/references/authoring.md) · [CLI reference](./packages/ghost/src/skill-bundle/references/schema.md) -## Same prompt, two results - -| Without ghost | With ghost | -| --- | --- | -| _Add image_ | _Add image_ | ## How it works -_ghost_ separates mechanics from guidance. The mechanics determine which +**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. @@ -68,7 +65,7 @@ A `.ghost/` package is a versioned set of markdown files: └── checks/ optional review instructions ``` -Your agent sees the complete menu and pulls only what applies. _ghost_ never +Your agent sees the complete menu and pulls only what applies. **ghost** never ranks the menu or selects guidance for the agent. ## Go deeper @@ -77,7 +74,7 @@ ranks the menu or selects guidance for the agent. - [Authoring guide](./packages/ghost/src/skill-bundle/references/authoring.md) — write and maintain guidance - [CLI reference](./packages/ghost/src/skill-bundle/references/schema.md) — commands, formats, and flags - [context-control](./packages/context-control) — test whether agents select the right guidance -- [steering-control](./packages/steering-control) — compare work made with and without ghost +- [steering-control](./packages/steering-control) — compare work made with and without **ghost** - [Contributing](./CONTRIBUTING.md) — develop and release the project ## License From d230b256fa5d2aabd37661ea20986f59cab1a62c Mon Sep 17 00:00:00 2001 From: "Sol 5.6" <2be45693458a7d45edf11882226b8bc6246772f8719faed540576070d8b0464f@buzz.block.builderlab.xyz> Date: Wed, 4 Nov 2026 22:04:49 -0500 Subject: [PATCH 15/16] Clarify npm README guidance wording Signed-off-by: Sol 5.6 <2be45693458a7d45edf11882226b8bc6246772f8719faed540576070d8b0464f@buzz.block.builderlab.xyz> --- packages/ghost/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/ghost/README.md b/packages/ghost/README.md index 31c0e74e..3c3993b2 100644 --- a/packages/ghost/README.md +++ b/packages/ghost/README.md @@ -58,7 +58,7 @@ shape of the whole package, then loads only what the current task needs. ```text .ghost/ ├── manifest.yml package identity and cover -├── glossary.md the package's own categories +├── 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 @@ -174,7 +174,7 @@ to compare work made with and without a ghost package. | Design tokens | Machine-readable visual values | | Component libraries | Reusable implementation materials | | Asset libraries and design files | Source artwork and visual references | -| **ghost** | Brand decisions that apply only in particular situations | +| **ghost** | Broad brand stances and decisions for particular situations | These tools work together. Keep repo-wide operating instructions in `AGENTS.md`, concrete values in tokens, implementation in components, and From b8bc3e5aa4ec5c624f044ea60182da70b7674d39 Mon Sep 17 00:00:00 2001 From: "Sol 5.6" <2be45693458a7d45edf11882226b8bc6246772f8719faed540576070d8b0464f@buzz.block.builderlab.xyz> Date: Wed, 4 Nov 2026 22:16:34 -0500 Subject: [PATCH 16/16] Point CLI readers to built-in help Relabel the package schema links so they describe their actual target. Direct readers to the built-in help for current commands and flags. Signed-off-by: Sol 5.6 <2be45693458a7d45edf11882226b8bc6246772f8719faed540576070d8b0464f@buzz.block.builderlab.xyz> --- README.md | 4 ++-- packages/ghost/README.md | 7 ++++--- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index d05fd446..0db8cfa9 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ It works with the tools, agents, and models you already use. The CLI doesn't mak [Get started](./packages/ghost/README.md#get-started) · [Authoring guide](./packages/ghost/src/skill-bundle/references/authoring.md) · -[CLI reference](./packages/ghost/src/skill-bundle/references/schema.md) +[Package format](./packages/ghost/src/skill-bundle/references/schema.md) ## How it works @@ -72,7 +72,7 @@ ranks the menu or selects guidance for the agent. - [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 -- [CLI reference](./packages/ghost/src/skill-bundle/references/schema.md) — commands, formats, and flags +- [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 diff --git a/packages/ghost/README.md b/packages/ghost/README.md index 3c3993b2..f2ed1db2 100644 --- a/packages/ghost/README.md +++ b/packages/ghost/README.md @@ -25,7 +25,7 @@ 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) · -[CLI reference](https://github.com/block/ghost/blob/main/packages/ghost/src/skill-bundle/references/schema.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 @@ -209,8 +209,9 @@ 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. ## What's in the repo