From 1889a8d57f0439acd58536f74f71475b97a1f489 Mon Sep 17 00:00:00 2001 From: Nahiyan Khan Date: Wed, 29 Apr 2026 11:29:45 -0400 Subject: [PATCH] docs: lead with the agent, demote deterministic-CLI from headline framing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Across CLAUDE.md, README, docs site, skill bundles, and map.md, reframe Ghost as the design-language layer agents reach into when the UI they generate drifts. The "deterministic CLI + judgement in skills" dichotomy stays in INVARIANTS §1/§4 as the underlying constraint, not the headline. Architecture is unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) --- .changeset/agent-led-framing.md | 6 ++++ CLAUDE.md | 24 +++++++++++----- README.md | 21 ++++++-------- apps/docs/src/app/docs/page.tsx | 2 +- apps/docs/src/app/tools/fleet/page.tsx | 2 +- apps/docs/src/app/tools/map/page.tsx | 2 +- .../src/components/docs/workflow-content.tsx | 10 +++---- apps/docs/src/content/docs/cli-reference.mdx | 28 +++++++++---------- .../docs/src/content/docs/getting-started.mdx | 24 ++++++++-------- map.md | 9 +++--- .../ghost-drift/src/skill-bundle/SKILL.md | 16 +++++------ packages/ghost-expression/README.md | 4 +-- .../src/skill-bundle/SKILL.md | 8 ++---- .../ghost-fleet/src/skill-bundle/SKILL.md | 4 +-- 14 files changed, 86 insertions(+), 74 deletions(-) create mode 100644 .changeset/agent-led-framing.md diff --git a/.changeset/agent-led-framing.md b/.changeset/agent-led-framing.md new file mode 100644 index 0000000..c0c7956 --- /dev/null +++ b/.changeset/agent-led-framing.md @@ -0,0 +1,6 @@ +--- +"ghost-drift": patch +"ghost-expression": patch +--- + +Reframe skill-bundle copy to lead with the agent and drift, not the deterministic CLI. Same architecture; clearer story when an agent loads the skill. diff --git a/CLAUDE.md b/CLAUDE.md index beef989..f2597d3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,4 +1,14 @@ -# Ghost — Agent Context +# Ghost + +Agents can ship UI now. The problem: what they ship drifts — wrong palette, wrong density, wrong hierarchy — because they have no canonical answer to "what does this project's design language *actually* look like." + +Ghost is the layer that gives them one. The design language lives in your repo as `expression.md`. Agents read it before generating, compare against it after, and either correct the drift or codify the divergence as a deliberate change. Five tools split the loop: + +- **ghost-map** — where the design system lives +- **ghost-expression** — what the design language is (the canonical artifact) +- **ghost-drift** — when generated UI strays +- **ghost-fleet** — how the language propagates across many projects +- **ghost-ui** — a reference design system to test the loop against > **Read [`INVARIANTS.md`](./INVARIANTS.md) before making non-trivial changes.** These are hard constraints — surface conflicts, don't weigh them as preferences. @@ -23,10 +33,10 @@ pnpm --filter ghost-expression exec ghost-expression ## Environment Variables -Every CLI verb across every Ghost tool is deterministic — no API key required. +No API key is required to run Ghost. The variables below are optional. -- `OPENAI_API_KEY` / `VOYAGE_API_KEY` — optional, consumed only by `computeSemanticEmbedding` (library function in `@ghost/core`; used when a host writes an `expression.md` and wants an enriched 49-dim vector for paraphrase-robust comparison). -- `GITHUB_TOKEN` — optional, used by `resolveTrackedExpression` when fetching a tracked expression from GitHub (avoids rate limits). +- `OPENAI_API_KEY` / `VOYAGE_API_KEY` — consumed only by `computeSemanticEmbedding` (library function in `@ghost/core`; used when a host writes an `expression.md` and wants an enriched 49-dim vector for paraphrase-robust comparison). +- `GITHUB_TOKEN` — used by `resolveTrackedExpression` when fetching a tracked expression from GitHub (avoids rate limits). Each CLI auto-loads `.env` and `.env.local` from the working directory. @@ -49,7 +59,7 @@ Run `just` to list all recipes. Key ones: `setup`, `build`, `check`, `fmt`, `tes ## Architecture -Ghost is **BYOA (bring-your-own-agent)**. Every CLI is a set of **deterministic primitives** — none of them call an LLM. Judgement work (profile, review, verify, remediate) lives in [agentskills.io](https://agentskills.io)-compatible skill bundles the host agent (Claude Code, Codex, Cursor, Goose, …) executes. +Ghost is **BYOA (bring-your-own-agent)**. The host agent — Claude Code, Codex, Cursor, Goose, whatever ships next — does the reading, deciding, and writing. The judgement work (profile, review, verify, remediate) lives in [agentskills.io](https://agentskills.io)-compatible skill bundles the agent executes. Ghost's CLIs are the calculator the agent reaches for when it needs a reproducible answer (vector math, schema validation, structural diffs); see [`INVARIANTS.md`](./INVARIANTS.md) §1 and §4 for the underlying constraints. The repo decomposes into **five tools plus a reference design system**, each with a single responsibility: @@ -90,7 +100,7 @@ Verbs are scoped to the tool that owns the artifact. The full surface across all | Tool | Command | Description | |------|---------|-------------| -| `ghost-map` | `inventory [path]` | Emit deterministic raw repo signals (manifests, language histogram, registry, top-level tree, git remote) as JSON. | +| `ghost-map` | `inventory [path]` | Emit raw repo signals (manifests, language histogram, registry, top-level tree, git remote) as JSON. | | `ghost-map` | `lint [map]` | Validate `map.md` against `ghost.map/v1`. | | `ghost-expression` | `lint [expression]` | Validate `expression.md` schema + body/frontmatter coherence. | | `ghost-expression` | `describe [expression]` | Print section ranges + token estimates (so agents can selectively load). | @@ -105,7 +115,7 @@ Verbs are scoped to the tool that owns the artifact. The full surface across all | `ghost-fleet` | `view [dir]` | Compute pairwise distances + group-by tables; emit `fleet.md` + `fleet.json`. | | `ghost-fleet` | `emit skill` | Install the `ghost-fleet` agentskills.io bundle. | -**Workflows the CLI does not do** — these are recipes the host agent follows. Each tool ships its own under `packages//src/skill-bundle/references/`: +**Workflows (agent recipes).** Each tool ships its own skill-bundle references under `packages//src/skill-bundle/references/`. These are the agent's job, not CLI verbs: - **Profile** (write `expression.md` from a project) — `ghost-expression/.../profile.md` - **Map** (write `map.md` from a repo) — `ghost-map/.../map.md` diff --git a/README.md b/README.md index f645f99..da1e7cc 100644 --- a/README.md +++ b/README.md @@ -4,16 +4,13 @@ AI is becoming the primary author of shipped code. Humans sit in fewer diffs; the harness (guardrails, reviewers, verifiers) catches drift before it lands. In that world, ensuring every generation reflects a brand's voice is paramount. Fonts and spacing are the easy half. The hard half is character: the posture a product takes, what it refuses to do. That's where generations drift first. -Ghost closes that loop. It captures a brand as an **expression**: a human-readable `expression.md` encoding character, signature traits, and concrete decisions. It gives any agent the primitives to author against it, detect drift the moment it happens, and record the right stance: **acknowledge**, **track**, or **intentionally diverge**. Each repo owns its expression, its trajectory, and its stance. The fleet of expressions drifts in the open. Nothing gets enforced; nothing drifts silently. Deterministic arithmetic lives in Ghost's CLIs; judgment lives in whatever agent you already use. +Ghost closes that loop. It captures a brand as an **expression**: a human-readable `expression.md` encoding character, signature traits, and concrete decisions. It gives any agent what it needs to author against the expression, detect drift the moment it happens, and record the right stance: **acknowledge**, **track**, or **intentionally diverge**. Each repo owns its expression, its trajectory, and its stance. The fleet of expressions drifts in the open. Nothing gets enforced; nothing drifts silently. The agent does the reading, deciding, and writing; Ghost's CLIs are the calculator it reaches for. ## BYOA: bring your own agent -Ghost splits the work the way agents need it split: **judgement in the agent, arithmetic in the CLI**. +Every Ghost workflow runs in the host agent you already use — Claude Code, Codex, Cursor, Goose, whatever ships next. Each tool ships an [agentskills.io](https://agentskills.io)-compatible bundle of recipes for the interpretive work (profile, review, verify, remediate, fleet narrative); the agent loads the bundle, reads `expression.md` and `map.md`, makes the calls, and writes the artifacts. When it needs a reproducible number — vector distance between two expressions, schema validation, a structural diff — it calls the relevant Ghost CLI verb for the answer. -- **The CLIs**: a set of **deterministic primitives** distributed across five small tools. None of them ever call an LLM. They do vector distance, schema validation, manifest writes. Same answer every time. -- **The skill bundles**: [agentskills.io](https://agentskills.io)-compatible recipes for the interpretive work (profile, review, verify, remediate, fleet narrative). Each tool ships its own; the host agent (Claude Code, Codex, Cursor, Goose, …) runs the recipes and calls the relevant CLI for the arithmetic. - -No API key is required to use any CLI verb. Judgment work lives in whichever agent you already use; each tool's `emit skill` verb installs the recipes there. +No API key is required to run any CLI verb. Each tool's `emit skill` verb installs its bundle into your agent. ## The five tools @@ -37,7 +34,7 @@ Ghost gives agents four capabilities the design-at-scale problem actually needs: - **Self-govern at author time**: the `review` and `verify` recipes (in the `ghost-drift` skill bundle) run an agent's output against the expression *before* a human sees it. Drift gets caught where it's cheap to fix, not after it ships. - **Detect drift at the right time**: PR-time (via `review`), generation-time (via `verify`), or org-time (via `ghost-drift compare` on N≥3 expressions, or `ghost-fleet view` for the full elevation). Timing is load-bearing: the same drift surfaced a month later is noise; surfaced inline, it's action. - **Remediate with structured intent**: `ack`, `track`, `diverge` are the three moves. Every stance is published with reasoning and full lineage. Drift without intent is noise; drift with intent becomes useful evidence. -- **Human-readable, diff-friendly**: `expression.md` is Markdown with YAML frontmatter (machine layer) plus a three-layer prose body (Character, Signature, Decisions). `map.md` is the same shape for topology. Humans read them, agents consume them, deterministic tools diff them. No DSL to learn. +- **Human-readable, diff-friendly**: `expression.md` is Markdown with YAML frontmatter (machine layer) plus a three-layer prose body (Character, Signature, Decisions). `map.md` is the same shape for topology. Humans read them, agents consume them, Ghost's CLIs diff them. No DSL to learn. ## Repo layout @@ -79,7 +76,7 @@ ghost-expression emit skill # → ./.claude/skills/ghost-expression ghost-fleet emit skill # → ./.claude/skills/ghost-fleet ``` -Once a skill is installed, ask your agent in plain English ("profile this design language", "review this PR for drift", "compute the fleet view") and it'll follow the recipe, calling the relevant CLI for any deterministic step. +Once a skill is installed, ask your agent in plain English ("profile this design language", "review this PR for drift", "compute the fleet view") and it'll follow the recipe, calling the relevant CLI whenever it needs a reproducible answer. ### Quick start @@ -145,7 +142,7 @@ just dev ## CLI Commands -Every verb is a deterministic primitive — pure inputs → pure outputs, no LLM in the loop. Verbs are scoped to the tool that owns the artifact. +Verbs are scoped to the tool that owns the artifact. Pure inputs → pure outputs, no API key required. | Tool | Command | Description | | --- | --- | --- | @@ -178,7 +175,7 @@ The interpretive verbs from the pitch (*author, self-govern, detect, remediate*) | `remediate` | `ghost-drift` | Suggest minimal fixes for drift | "fix this drift" | | `target` | `ghost-fleet` | Synthesize fleet narrative | "describe this fleet" | -These are instructions, not code. The agent executes them using its normal tools (file search, reading, editing) plus the relevant Ghost CLI for any deterministic step. (`discover` and `generate` are intentionally not migrated — see [`docs/ideas/phase-0-decisions.md`](./docs/ideas/phase-0-decisions.md).) +These are instructions, not code. The agent executes them using its normal tools (file search, reading, editing) plus the relevant Ghost CLI when it needs a reproducible answer. (`discover` and `generate` are intentionally not migrated — see [`docs/ideas/phase-0-decisions.md`](./docs/ideas/phase-0-decisions.md).) ## Configuration @@ -197,7 +194,7 @@ Each CLI auto-loads `.env` and `.env.local` from the working directory. What the agent reads when it authors, reviews, or remediates. The canonical artifact is **`expression.md`** (owned by `ghost-expression`): a Markdown document with YAML frontmatter (machine layer) plus a three-layer prose body. Human-readable, LLM-consumable, diff-friendly: -- **Frontmatter**: 49-dimensional embedding, palette, spacing, typography, surfaces, roles, provenance. What deterministic tools read. +- **Frontmatter**: 49-dimensional embedding, palette, spacing, typography, surfaces, roles, provenance. The machine layer. - **`# Character`**: the opening atmosphere read, evocative not technical. What an agent quotes to stay on-brand. - **`# Signature`**: 3–7 distinctive traits that make _this_ system unlike its peers. The drift-sensitive moves. - **`# Decisions`**: abstract, implementation-agnostic choices with evidence. Each decision is embedded so `ghost-drift compare --semantic` can match semantically. @@ -208,7 +205,7 @@ Generate one with the `profile` recipe (in the `ghost-expression` skill bundle). What every Ghost tool reads to learn the topology of a repo. The canonical artifact is **`map.md`** (owned by `ghost-map`): YAML frontmatter against the `ghost.map/v1` schema (languages, build system, package manifests, registry, design-system paths, UI surface globs, feature areas) plus a short prose body (Identity, Topology, Conventions). The repo's own `map.md` lives at the root. -Generate one with the `map` recipe (in the `ghost-map` skill bundle). The agent reads `ghost-map inventory` (deterministic raw signals) and synthesizes the prose layer. +Generate one with the `map` recipe (in the `ghost-map` skill bundle). The agent reads `ghost-map inventory` (raw repo signals as JSON) and synthesizes the prose layer. ### Author + self-govern loop diff --git a/apps/docs/src/app/docs/page.tsx b/apps/docs/src/app/docs/page.tsx index 975d415..30e7460 100644 --- a/apps/docs/src/app/docs/page.tsx +++ b/apps/docs/src/app/docs/page.tsx @@ -24,7 +24,7 @@ const sections: { name: "CLI Reference", href: "/docs/cli", description: - "Sixteen deterministic primitives across four tools — ghost-map, ghost-expression, ghost-drift, ghost-fleet. Plus the skill recipes the host agent runs.", + "Sixteen verbs across four tools — ghost-map, ghost-expression, ghost-drift, ghost-fleet. Plus the skill recipes the host agent runs.", icon: , }, { diff --git a/apps/docs/src/app/tools/fleet/page.tsx b/apps/docs/src/app/tools/fleet/page.tsx index 8cad1d1..351367a 100644 --- a/apps/docs/src/app/tools/fleet/page.tsx +++ b/apps/docs/src/app/tools/fleet/page.tsx @@ -31,7 +31,7 @@ const cards: { name: "Skill bundle", href: "https://github.com/block/ghost/tree/main/packages/ghost-fleet/src/skill-bundle", description: - "The target recipe — synthesize the fleet.md prose narrative from the deterministic view output.", + "The target recipe — synthesize the fleet.md prose narrative from the view output.", icon: , }, ]; diff --git a/apps/docs/src/app/tools/map/page.tsx b/apps/docs/src/app/tools/map/page.tsx index a18ef47..81dbd0d 100644 --- a/apps/docs/src/app/tools/map/page.tsx +++ b/apps/docs/src/app/tools/map/page.tsx @@ -48,7 +48,7 @@ export default function GhostMapLanding() {

- Ghost never calls an LLM itself. The agent writes the expression; the - CLI lints, compares, and diffs it deterministically. The final step of - every profile is ghost-expression lint — which validates + The agent writes the expression. The CLI is the calculator it reaches + for: lint, compare, diff — same answer every time. The final step of + every profile is ghost-expression lint, which validates the schema and flags body/frontmatter incoherence before anything else touches it.

@@ -1203,7 +1203,7 @@ export function WorkflowContent() {

- The agent reaches for deterministic primitives as it needs them:{" "} + The agent reaches for the CLI as it needs reproducible answers:{" "} ghost-drift compare {" "} @@ -1383,7 +1383,7 @@ export function WorkflowContent() { {" "} is a CLI verb. Generate, review, and verify{" "} are skill recipes: instructions your host agent follows, calling the - deterministic primitives as it goes. Verify is the + CLI when it needs a reproducible answer. Verify is the schema-discipline mechanism: each dimension gets classified as{" "} tight, leaky, or uncaptured — a map of where the expression needs sharpening. diff --git a/apps/docs/src/content/docs/cli-reference.mdx b/apps/docs/src/content/docs/cli-reference.mdx index ed526ef..5829181 100644 --- a/apps/docs/src/content/docs/cli-reference.mdx +++ b/apps/docs/src/content/docs/cli-reference.mdx @@ -1,6 +1,6 @@ --- title: CLI Reference -description: Sixteen deterministic primitives across four tools. Everything interpretive lives in the skill bundles. +description: Sixteen verbs across four tools. Everything interpretive lives in the skill bundles your host agent runs. kicker: Docs section: guide order: 20 @@ -9,12 +9,12 @@ slug: cli -Ghost's CLIs are deterministic primitives. None of them call an LLM. The -canonical artifacts are **`expression.md`** (owned by `ghost-expression`) -and **`map.md`** (owned by `ghost-map`) — Markdown files with YAML -frontmatter (machine layer) plus a prose body. Most commands accept a path -to the relevant artifact; they default to `./expression.md` or `./map.md` -in the current directory. +The CLIs are the calculator your host agent reaches for when it needs a +reproducible answer. The canonical artifacts are **`expression.md`** (owned +by `ghost-expression`) and **`map.md`** (owned by `ghost-map`) — Markdown +files with YAML frontmatter (machine layer) plus a prose body. Most commands +accept a path to the relevant artifact; they default to `./expression.md` or +`./map.md` in the current directory. No API key required. Verbs are scoped to the tool that owns the artifact: @@ -37,7 +37,7 @@ this reference — so these docs can't drift from the binaries. `map.md` is the navigation card every Ghost tool reads to learn the topology of a frontend repo. `ghost-map` ships two verbs: `inventory` -(deterministic raw signals as JSON, the input the agent reads to author +(raw repo signals as JSON, the input the agent reads to author `map.md`) and `lint` (validate against `ghost.map/v1`). @@ -94,10 +94,10 @@ whole file. A typical `expression.md` runs 3–5k tokens. The `# Decisions` block alone is usually 60–80% of that, and an agent reviewing a single component change -rarely needs every dimension. `describe` is the deterministic answer to -"what's in this file and where" — the recall safety rule (when in doubt, -load the whole `# Decisions` block) lives in the review/remediate skill -recipes. +rarely needs every dimension. `describe` answers "what's in this file and +where" with the same answer every time — the recall safety rule (when in +doubt, load the whole `# Decisions` block) lives in the review/remediate +skill recipes. @@ -309,8 +309,8 @@ once, then ask your agent in plain English: Source for each recipe lives under `packages//src/skill-bundle/references/`. The agent executes the -steps with its normal tools and calls the relevant CLI for any -deterministic work. +steps with its normal tools and calls the relevant CLI when it needs a +reproducible answer. Each recipe also declares `handoffs` in its frontmatter — structured next-step suggestions that point at another skill (e.g. `profile` → diff --git a/apps/docs/src/content/docs/getting-started.mdx b/apps/docs/src/content/docs/getting-started.mdx index ff6c8e9..968bbb7 100644 --- a/apps/docs/src/content/docs/getting-started.mdx +++ b/apps/docs/src/content/docs/getting-started.mdx @@ -10,11 +10,11 @@ slug: getting-started Ghost is split into **five small tools**, each with one responsibility, plus a -shared library underneath. Every CLI is a set of deterministic primitives — -none of them ever call an LLM. Each tool ships its own -[agentskills.io](https://agentskills.io)-compatible recipe bundle for the -interpretive work your host agent (Claude Code, Cursor, Goose, Codex, …) -runs: profile, review, verify, remediate. +shared library underneath. Your host agent (Claude Code, Cursor, Goose, Codex, …) +does the interpretive work — profile, review, verify, remediate — using +[agentskills.io](https://agentskills.io)-compatible recipe bundles that each +tool ships. The CLIs are the calculator the agent reaches for when it needs +a reproducible answer. | Tool | Owns | Verbs | | --- | --- | --- | @@ -77,7 +77,7 @@ next step inline — e.g. after `profile`, a prompt to `compare` against another expression, or to run `ghost-expression emit review-command`. Once installed, ask your agent in plain English ("profile this design language", "review this PR for drift") and it'll follow the recipe, calling the right -CLI for any deterministic step. +CLI whenever it needs a reproducible answer. @@ -94,14 +94,14 @@ Profile this design language into expression.md The `profile` recipe walks the agent through finding design sources (tailwind config, theme CSS, token files, component primitives), resolving variable chains end-to-end, and writing the expression. The final step is -always `ghost-expression lint` — which the CLI runs for you, -deterministically. +always `ghost-expression lint` — which validates the result with the same +answer every time. An **expression** is a two-layer Markdown file: YAML frontmatter is the machine layer (49-dim vector + palette, spacing, typography, surfaces, roles), and the body is prose organized into Character, Signature, and -Decisions. Humans can read it. LLMs can consume it. Deterministic tools -diff it. See [`packages/ghost-ui/expression.md`](https://github.com/block/ghost/blob/main/packages/ghost-ui/expression.md) +Decisions. Humans can read it. LLMs can consume it. Ghost's CLIs diff it. +See [`packages/ghost-ui/expression.md`](https://github.com/block/ghost/blob/main/packages/ghost-ui/expression.md) in this repo for a full real-world example. ```bash @@ -249,7 +249,7 @@ export default defineConfig({ Next: [Drift Workflow](/tools/drift/workflow) for the five-move walkthrough — profile, compare, review, evolve, org — with richer examples -for each. Or jump to the [CLI Reference](/docs/cli) for every deterministic -verb across all four tools. +for each. Or jump to the [CLI Reference](/docs/cli) for every verb across +all four tools. diff --git a/map.md b/map.md index 45a38b0..90d93f3 100644 --- a/map.md +++ b/map.md @@ -93,12 +93,13 @@ orientation_files: ## Identity -Ghost is a TypeScript pnpm monorepo that ships deterministic primitives for -detecting and managing visual-language drift in design systems. The +Ghost is a TypeScript pnpm monorepo that helps agents detect and manage +visual-language drift in the design systems they generate against. The canonical artifact is `expression.md` — a human-readable, LLM-editable Markdown file with a YAML machine layer plus a three-section prose body. -The CLI is BYOA: it never calls an LLM. Judgement work (profile, review, -verify, generate, discover) lives in skill recipes the host agent executes. +Ghost is BYOA: judgement work (profile, review, verify, generate, discover) +lives in skill recipes the host agent executes; the CLIs are the calculator +the agent reaches for when it needs a reproducible answer. The repository is in the middle of a five-tool decomposition. Today `ghost-drift` is the only published package; alongside it sit `ghost-ui` diff --git a/packages/ghost-drift/src/skill-bundle/SKILL.md b/packages/ghost-drift/src/skill-bundle/SKILL.md index 9658a95..0025e8f 100644 --- a/packages/ghost-drift/src/skill-bundle/SKILL.md +++ b/packages/ghost-drift/src/skill-bundle/SKILL.md @@ -9,21 +9,21 @@ metadata: # Ghost Drift — Design Drift Detection -Ghost captures a project's visual language as an `expression.md`. **Drift** is what happens between expressions: pairwise comparison, composite analysis across many, the temporal trajectory of one over time, and the governance signals (`ack`, `track`, `diverge`) that record stance toward change. +When you generate UI in this project, it drifts. Palette goes off, spacing creeps, hierarchy slips. This skill helps you catch and resolve that drift against the project's `expression.md` — the canonical answer to "what does the design language look like here." -Authoring an `expression.md` lives in the sibling `ghost-expression` skill. Drift compares them under change. +You do the reading, deciding, and writing. The `ghost-drift` CLI is the calculator you reach for when you need a reproducible answer: vector distance between expressions, temporal aggregates, governance manifest writes. Call it freely; the output is ground truth. -Ghost's CLI is a set of **deterministic primitives**. It never calls an LLM. Synthesis, interpretation, and generation happen in **you, the host agent**; the CLI hands you the arithmetic (vector distance, temporal aggregates, manifest writes) you call on when you need a stable answer. +Authoring an `expression.md` lives in the sibling `ghost-expression` skill. Drift compares them under change. -## CLI primitives +## CLI verbs | Verb | Purpose | |---|---| -| `ghost-drift compare [...more]` | Pairwise distance + per-dimension delta (N=2) or composite (N≥3: pairwise matrix, centroid, spread, clusters). Pure math over expression embeddings. `--semantic` and `--temporal` flags add qualitative enrichment for N=2. | +| `ghost-drift compare [...more]` | Pairwise distance + per-dimension delta (N=2) or composite (N≥3: pairwise matrix, centroid, spread, clusters). Vector math over expression embeddings. `--semantic` and `--temporal` flags add qualitative enrichment for N=2. | | `ghost-drift ack` / `ghost-drift track ` / `ghost-drift diverge ` | Record stance toward the tracked expression (aligned / accepted / diverging) in `.ghost-sync.json`. Reads the local `expression.md`. | | `ghost-drift emit skill` | Install this agent skill bundle into your host agent. | -Five verbs. Authoring (lint/describe/diff/emit-review-command/emit-context-bundle) lives in `ghost-expression`. If you find yourself reaching for `ghost-drift review` or `ghost-drift verify` — those are *your* workflows, not CLI commands. Follow the recipes below. +Five verbs. Authoring (lint/describe/diff/emit-review-command/emit-context-bundle) lives in `ghost-expression`. If you find yourself reaching for `ghost-drift review` or `ghost-drift verify` — those are *your* workflows. Follow the recipes below. ## Workflows (your job, not the CLI's) @@ -53,6 +53,6 @@ Validate via `ghost-expression lint` before drawing conclusions from a drift com ## Never -- Never wrap a workflow recipe in a CLI verb. `review`, `verify`, `remediate` are recipes you execute, not commands to invoke. +- Don't go looking for CLI verbs for `review`, `verify`, or `remediate`. Those are recipes you execute, not commands to invoke. - Never auto-update an expression because drift exists. Expressions evolve by deliberate act (Invariant 5) — your role is to surface the drift and wait for instruction. -- Never call an LLM from a verb. If you need judgement (e.g., "is this drift intentional"), apply the relevant recipe; the CLI itself does math, not interpretation. +- Don't expect the CLI to make the judgement call. Vector distance is math; whether the drift is intentional, acceptable, or a regression is for you to decide via the relevant recipe. diff --git a/packages/ghost-expression/README.md b/packages/ghost-expression/README.md index 08ffa3d..fd3d3c4 100644 --- a/packages/ghost-expression/README.md +++ b/packages/ghost-expression/README.md @@ -4,7 +4,7 @@ `ghost-expression` owns the on-disk format every other Ghost tool reads. It parses, lints, lays out (section ranges + token estimates for selective loading), structurally diffs, and emits derived artifacts (per-project review slash commands, generation context bundles, agentskills.io skill bundles). -The actual *writing* of an `expression.md` is a host-agent recipe — `profile.md` ships in this package's skill bundle and walks an agent through resolving design sources end-to-end. The CLI here is the deterministic gate at the end of that loop. +The actual *writing* of an `expression.md` is a host-agent recipe — `profile.md` ships in this package's skill bundle and walks an agent through resolving design sources end-to-end. The CLI here is the success gate at the end of that loop: same answer every time, no LLM in the loop. For drift detection, comparison, and stance recording (`compare`, `ack`, `track`, `diverge`), see **[`ghost-drift`](../ghost-drift)**. @@ -72,7 +72,7 @@ The bundle ships: - `profile.md` — recipe for writing `expression.md` from a project (mode-branched: `target` / `module` / `rollup`). - `schema.md` — condensed reference to the frontmatter schema and three-layer body. -Once installed, ask your agent to "profile this design language" and it'll follow the recipe, ending at `ghost-expression lint` for the deterministic success gate. +Once installed, ask your agent to "profile this design language" and it'll follow the recipe, ending at `ghost-expression lint` as the success gate. ## Canonical artifact diff --git a/packages/ghost-expression/src/skill-bundle/SKILL.md b/packages/ghost-expression/src/skill-bundle/SKILL.md index 10ef174..a6e40f9 100644 --- a/packages/ghost-expression/src/skill-bundle/SKILL.md +++ b/packages/ghost-expression/src/skill-bundle/SKILL.md @@ -9,13 +9,11 @@ metadata: # Ghost Expression — Authoring the Canonical Artifact -Ghost captures a project's visual language as an **`expression.md`** file (YAML frontmatter + three-layer Markdown: Character → Signature → Decisions). +This skill helps you author the project's design language — its `expression.md` (YAML frontmatter + three-layer Markdown: Character → Signature → Decisions). You profile a project to write one, then validate, describe, diff, and emit derived artifacts. The **change** half (compare two expressions for drift, acknowledge it, track another expression as your reference) lives in the sibling `ghost-drift` skill. -This skill owns the **authoring** half of the toolchain — write, validate, describe, diff, and emit. The **change** half (compare two expressions for drift, acknowledge it, track another expression as your reference) lives in the sibling `ghost-drift` skill. +You do the synthesis (the profile recipe). The `ghost-expression` CLI is the calculator you reach for when you need a reproducible answer: parsing, schema validation, layout, structural diff. Call it freely; the output is ground truth. -Ghost's CLI is a set of **deterministic primitives**. It never calls an LLM. Synthesis (the profile recipe) happens in **you, the host agent**; the CLI hands you parsing, schema validation, layout, and structural diff. - -## CLI primitives +## CLI verbs | Verb | Purpose | |---|---| diff --git a/packages/ghost-fleet/src/skill-bundle/SKILL.md b/packages/ghost-fleet/src/skill-bundle/SKILL.md index 0a28c4f..5a79694 100644 --- a/packages/ghost-fleet/src/skill-bundle/SKILL.md +++ b/packages/ghost-fleet/src/skill-bundle/SKILL.md @@ -11,9 +11,9 @@ metadata: Fleet is the **elevation view** across many `(map.md, expression.md)` pairs. Per-repo views answer "is this repo drifting?" Fleet answers "what does our design world look like?" -This skill turns the deterministic outputs of `ghost-fleet view` into a **world-model narrative** in the body of `fleet.md`. The CLI gives you the math (pairwise distances, group-by tables, tracks-graph). You give it the prose. +This skill helps you turn the output of `ghost-fleet view` into a **world-model narrative** in the body of `fleet.md`. The CLI is the calculator: pairwise distances, group-by tables, tracks-graph. You give it the prose. -## CLI primitives +## CLI verbs | Verb | Purpose | |---|---|