diff --git a/.changeset/docs-node-model-refresh.md b/.changeset/docs-node-model-refresh.md new file mode 100644 index 00000000..96d5ba3c --- /dev/null +++ b/.changeset/docs-node-model-refresh.md @@ -0,0 +1,5 @@ +--- +"@anarchitecture/ghost": patch +--- + +Refresh the README and docs onto the node-graph model and the current command set. diff --git a/CLAUDE.md b/CLAUDE.md index 89dd8174..2e09ca34 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,10 +4,12 @@ Agents can assemble UI. What they cannot reliably preserve is the product surface composition behind that UI: hierarchy, density, restraint, repetition, trust, flow, and the choices that make a surface feel intentional. -Ghost keeps that surface composition in a repo-local `.ghost/` fingerprint package. The public npm shape -is one package, `@anarchitecture/ghost`, with one user-facing bin, `ghost`. -The CLI validates, computes, compares, and emits deterministic packets. The -host agent does the interpretive BYOA work through the installed `ghost` skill. +Ghost keeps that surface composition in a repo-local `.ghost/` fingerprint +package — a graph of prose nodes. The public npm shape is one package, +`@anarchitecture/ghost`, with one user-facing bin, `ghost`. The CLI validates +the node graph, composes context, routes checks, and emits deterministic +packets. The host agent does the interpretive BYOA work through the installed +`ghost` skill. ## Build & Run @@ -30,38 +32,42 @@ pnpm --filter @anarchitecture/ghost exec ghost Ghost is **BYOA (bring your own agent)**. Claude Code, Codex, Cursor, Goose, or another host agent reads, decides, and writes. Ghost is the deterministic -calculator the agent reaches for: schema validation, repo-signal helpers, -structural diffs, drift checks, comparison math, and handoff packets. +calculator the agent reaches for: schema and graph validation, repo-signal +helpers, context composition, check routing, and advisory review packets. -The canonical root `.ghost/` package follows: +The canonical root `.ghost/` package is a flat folder: ```text -manifest.yml -intent.yml -inventory.yml -composition.yml -validate.yml +manifest.yml # schema + id +surfaces.yml # the spine: surfaces and their parent (core is implicit) +nodes/*.md # prose nodes — the design expression +checks/*.md # optional ghost.check/v1 checks ``` -The three root facet files are the core model: +The fingerprint is a **graph of nodes**. A node is one markdown file: +frontmatter handles (`id`, `description`, `under`, `relates`, `incarnation`) +plus a prose body. The body is written through three authoring lenses — they +guide what to capture, they are not fields or node types: -- `intent.yml` for surface intent. -- `inventory.yml` for curated material, exemplars, and source links. -- `composition.yml` for experience patterns. +- **intent** — the why and the stance. +- **inventory** — the materials, and pointers to code the agent can inspect. +- **composition** — the patterns that make the surface feel intentional. -`validate.yml` validates output through deterministic checks; it is not -generation input. -Ordinary Git review is the approval boundary for fingerprint edits. +`under` cascades a node downward (`core` is the implicit root and reaches every +surface). `relates` links nodes laterally. `description` is the retrieval +payload. `checks/*.md` validate output, routed by surface; they are not +generation input. Surfaces are declared in `surfaces.yml`, never inferred from +filenames. Ordinary Git review is the approval boundary for fingerprint edits. -Legacy `resources.yml`, `map.md`, `survey.json`, and `patterns.yml` may still -appear in older repos or as migration source material. They are not canonical -fingerprint input for new Ghost work. +A package may `extend` another by identity (the shared-brand pattern): the +manifest's `extends` maps a package id to where it lives, and nodes reference +inherited context by identity (`under: brand:core`), never by path. ## Packages | Package | Published? | Description | | --- | --- | --- | -| `packages/ghost` | yes: `@anarchitecture/ghost` | Unified public package. Ships the `ghost` CLI, fingerprint package authoring, checks, advisory review packets, comparison, drift stance verbs, and the unified skill bundle. | +| `packages/ghost` | yes: `@anarchitecture/ghost` | Unified public package. Ships the `ghost` CLI, node authoring, graph validation, check routing, advisory review packets, and the unified skill bundle. | | `packages/ghost-core` | no | Private historical shared package. Runtime code needed by npm is folded into `packages/ghost/src/ghost-core`. | | `packages/ghost-fleet` | no | Private fleet view across many Ghost bundles. Consumes workspace exports from `@anarchitecture/ghost`. | | `packages/ghost-ui` | no | Reference design system: shadcn registry plus `ghost-mcp` MCP server. | @@ -69,34 +75,33 @@ fingerprint input for new Ghost work. ## CLI Commands +Core workflow: + +| Command | Description | +| --- | --- | +| `ghost init` | Scaffold `.ghost/` — manifest, surfaces spine, and a seed node. | +| `ghost scan` | Report node and surface contribution. | +| `ghost validate` | Validate the package: artifact shape and the node graph (links resolve, one root, acyclic). | +| `ghost gather` | List nodes by id + description, or compose a surface's context slice (own + inherited + edges). | +| `ghost checks` | Select and ground the markdown checks governing the named surfaces. | +| `ghost review` | Emit an advisory review packet: touched surfaces, routed checks, fingerprint grounding, and the diff. | +| `ghost skill install` | Install the unified `ghost` skill bundle. | + +Advanced/maintenance: + | Command | Description | | --- | --- | -| `ghost init` | Create `.ghost/` with manifest, facets, and deterministic checks. | -| `ghost scan` | Report fingerprint contribution facets and BYOA next-step guidance. | | `ghost signals` | Emit raw repo signals as JSON for fingerprint authoring. | -| `ghost lint` | Validate a fingerprint package or single artifact. | -| `ghost verify` | Validate fingerprint evidence and exemplar paths, and typed check refs. | -| `ghost describe` | Print direct markdown section ranges. | -| `ghost diff` | Structural direct-fingerprint prose diff between direct fingerprints. | -| `ghost survey ` | Legacy survey helpers for optional `ghost.survey/v1` workflows. | -| `ghost check` | Run active `ghost.validate/v1` deterministic gates against a diff. | -| `ghost review` | Emit an evidence-routed advisory review packet grounded in fingerprint facets, inventory exemplars, checks, and the diff. | -| `ghost compare` | Pairwise or composite comparison over packages or direct fingerprints. | -| `ghost ack` | Record stance toward the tracked fingerprint in `.ghost-sync.json`. | -| `ghost track` | Shift the tracked fingerprint. | -| `ghost diverge` | Declare intentional divergence on a dimension. | -| `ghost emit ` | Emit `review-command`. | -| `ghost skill install` | Install the unified `ghost` agentskills.io bundle. | - -`ghost scan --format json` is deterministic contribution and source-signal state. -It does not run an LLM. +| `ghost migrate` | Migrate a legacy `.ghost/` package onto the node-graph surface model. | + +`ghost scan --format json` is deterministic contribution state. It does not run +an LLM. ## Public Exports - `@anarchitecture/ghost` for the combined surface. -- `@anarchitecture/ghost/scan` for scan contribution, source signals, and stack discovery. -- `@anarchitecture/ghost/fingerprint` for fingerprint package authoring, linting, verification, parsing, and serialization. -- `@anarchitecture/ghost/drift` for check/review/compare/stance helpers. +- `@anarchitecture/ghost/scan` for scan contribution and source signals. +- `@anarchitecture/ghost/fingerprint` for node package authoring, validation, parsing, and serialization. - `@anarchitecture/ghost/core` for shared schemas, types, and loaders. - `@anarchitecture/ghost/cli` for `buildCli()`. @@ -132,8 +137,10 @@ Use `patch` for fixes and docs, `minor` for new commands/flags/exports, and - Keep publishable runtime code self-contained in `packages/ghost`; no `workspace:*` runtime dependencies in the packed public artifact. -- The canonical on-disk form is a flat `.ghost/` package. -- Direct `fingerprint.md` remains only for legacy/direct compare workflows. +- The canonical on-disk form is a flat `.ghost/` package: `manifest.yml`, + `surfaces.yml`, `nodes/*.md`, and optional `checks/*.md`. +- The graph is the only model. Surfaces are the only locality; they are + declared in `surfaces.yml`, never inferred from paths or filenames. - Skill recipes live in `packages/ghost/src/skill-bundle/references/`; install them with `ghost skill install`. - The CLI manifest at `apps/docs/src/generated/cli-manifest.json` is generated diff --git a/README.md b/README.md index 3aa464c0..7aef4327 100644 --- a/README.md +++ b/README.md @@ -1,189 +1,141 @@ # Ghost -**Ghost captures the composition of a product surface: the intent behind it, -the materials it draws from, and the patterns that make it feel intentional.** +**Agents can assemble UI. They can't reliably preserve the _composition_ behind +it — the hierarchy, density, restraint, copy, trust, and flow that make a +surface feel intentional.** -Ghost gives AI agents a checked-in product fingerprint they can read before -they generate UI and validate after they change it. The public package is -`@anarchitecture/ghost`, and it installs one CLI: `ghost`. +Ghost is a checked-in product-surface fingerprint your agent reads before it +builds and checks after it changes. One package, `@anarchitecture/ghost`. One +CLI, `ghost`. -Agents can assemble components. What they need help preserving is the product -surface behind those components: hierarchy, density, restraint, behavior, copy, -accessibility, trust, and flow. Ghost keeps that surface composition in a -portable `.ghost/` package that ordinary Git review can approve. +[Documentation](https://block.github.io/ghost/) · [npm](https://www.npmjs.com/package/@anarchitecture/ghost) · [Skill](#skill) ## The Shape -The canonical package is intentionally small: +A fingerprint is a small folder of prose. The CLI computes; your agent reads, +writes, and decides. ```text .ghost/ - manifest.yml # ghost.fingerprint-package/v1 anchor - intent.yml # surface intent - inventory.yml # curated material and exemplars - composition.yml # patterns, flows, states, and arrangements - validate.yml # optional deterministic gates + manifest.yml # schema + id + surfaces.yml # the spine: surfaces and their parent (core is implicit) + nodes/*.md # prose nodes — the design expression + checks/*.md # optional rules an agent evaluates ``` -A package can be sparse: it contributes whichever facets are locally true. Generation usually uses intent + inventory + composition: +The fingerprint is a **graph of nodes**. A node is one markdown file: +frontmatter handles (`id`, `description`, `under`, `relates`, `incarnation`) +plus a prose body. You write that body through three lenses — they guide what to +capture, they are not fields: -- `intent.yml` says what the surface is trying to do and for whom. -- `inventory.yml` points agents at materials they can inspect or reuse. -- `composition.yml` captures the patterns that make those materials feel like - one intentional product. +- **intent** — the why and the stance. +- **inventory** — the materials, and pointers to the code an agent can inspect. +- **composition** — the patterns that make the surface feel like one product. -`validate.yml`, nested packages, custom host-wrapper package locations, and raw repo -signals are supporting features. They do not replace curated fingerprint -facets. `ghost signals` answers what exists; curated fingerprint facets answer -what the surface is trying to preserve. - -Older `resources.yml`, `map.md`, `survey.json`, `patterns.yml`, and direct -`fingerprint.yml` artifacts can still inform migration workflows, but new Ghost -work should target `.ghost/`. - -## Project Status: Beta - -> [!WARNING] -> Ghost is pre-1.0 and under active development. The CLI, fingerprint schema, -> on-disk `.ghost/` package shape, and public JavaScript exports may -> change in breaking ways before a stable 1.0 release. -> -> Breaking changes may ship in minor versions while Ghost is pre-1.0. Patch -> versions are reserved for fixes that should not require migration. If you adopt -> Ghost today, expect some churn, pin the version you depend on, and review -> release notes before upgrading. +`under` cascades a node downward (`core` reaches every surface). `relates` links +nodes laterally. `description` is the retrieval payload — how an agent finds the +right node for a task. Checks validate output; they are never generation input. ## Install ```bash npm install -D @anarchitecture/ghost npx ghost --help -npx ghost --help --all ``` -`ghost --help` shows the core workflow. `ghost --help --all` shows the complete -command index, and each command supports `ghost --help`. - -Install the BYOA skill bundle so Codex, Claude, Cursor, Goose, or another host -agent knows how to author and use the fingerprint: +## Quick Start ```bash -npx ghost skill install -# or choose an explicit destination -npx ghost skill install --dest ~/.codex/skills/ghost -``` - -Then ask your agent in plain English: - -```text -Set up the Ghost fingerprint for this repo. -Brief this work from the Ghost fingerprint. -Review this PR against the Ghost fingerprint. -Compare these two Ghost bundles. +ghost init # scaffold .ghost/ — manifest, surfaces spine, one seed node +ghost validate # links resolve, one root, acyclic +ghost gather # list nodes; ghost gather composes a context slice ``` -## Author A Fingerprint +A node looks like this: -Ghost authoring is a human-plus-agent workflow. The CLI creates, inspects, and -validates the package; the host agent interviews, reads the repo, drafts facet -edits, and asks you to curate the claims. +```markdown +--- +id: checkout-trust +description: Trust at the payment moment. +under: checkout +relates: + - to: core-trust + as: reinforces +--- -```bash -ghost init -ghost init --package product-surface -ghost scan --format json -ghost signals . -ghost lint .ghost -ghost lint product-surface -ghost verify .ghost --root . +Near the moment of payment, reduce felt risk. Proximity of reassurance to the +action beats completeness. Never introduce a new visual system here. ``` -Use `--reference` when a reference library should seed inventory, `--scope` -for nested product areas, or `--package ` when initializing an exact -package directory such as `product-surface/`. -For monorepos, `ghost init --monorepo` creates or preserves the root package, -detects workspace child roots, and prints proposed `ghost init --scope ...` -commands by default. Run `ghost init --monorepo --apply` to create the detected -child packages. Host wrappers that need Ghost files somewhere other than -`.ghost` may set `GHOST_PACKAGE_DIR=` on the child `ghost` -process. Exact `--package ` values win over the environment default. - -Drafted fingerprint edits are just ordinary file changes until Git review -accepts them. Checked-in Ghost facet files are the Ghost source of truth. +## Skill -## Generate From Ghost - -Before generating or revising UI, gather the Relay brief for the target path: +Ghost is **bring-your-own-agent**. Install the skill bundle so Claude Code, +Codex, Cursor, Goose, or another host agent knows how to author and use the +fingerprint: ```bash -ghost relay gather apps/checkout/review/page.tsx +npx ghost skill install ``` -Relay compiles selected context from the resolved stack as context hits: -fingerprint refs, why they matched, suggested reads, omissions, and gaps. -The important shift is timing: Ghost gives agents surface-composition context -before they build, not only after a review finds drift. +Then ask in plain English: -After implementation, run the deterministic and advisory workflows against the -same fingerprint: - -```bash -ghost check --base main -ghost review --base main +```text +Set up the Ghost fingerprint for this repo. +Brief this work from the Ghost fingerprint. +Review this change against the Ghost fingerprint. ``` -`ghost check` runs active `ghost.validate/v1` gates and can fail. `ghost review` -emits an evidence-routed advisory packet for a human or host adapter to use. +The skill tells the agent what to read, what to write, and which CLI checks to +run. The CLI does the deterministic work; the agent does the interpretation. -## Compare And Govern - -Advanced workflows remain available when a repo needs package stacks, -comparison, or explicit drift stance: +## The Loop ```bash -ghost stack apps/checkout/review/page.tsx -ghost compare market/.ghost dashboard/.ghost -ghost ack --stance aligned --reason "Initial baseline" -ghost track new-tracked.fingerprint.md -ghost diverge typography --reason "Editorial product uses a different type scale" -ghost emit review-command --path apps/checkout/review/page.tsx +ghost gather # before: compose the context slice for the work +ghost checks --surface # route the markdown checks the change touches +ghost review --surface # after: an advisory packet grounded in the diff ``` -`ghost scan --format json` emits deterministic contribution state for `intent`, -`inventory`, `composition`, and `validate`. A sparse package can be useful with -only one contributing facet; absent facets may be inherited from broader stack -context. It does not call an LLM. +The shift is timing: Ghost gives agents surface-composition context **before** +they build, not only after a review finds drift. Checked-in nodes are the source +of truth; ordinary Git review is the approval boundary for fingerprint edits. ## CLI Commands | Command | Description | | --- | --- | -| `ghost init` | Create `.ghost/` package facet files. | -| `ghost scan` | Report sparse fingerprint contribution facets. | -| `ghost lint` | Validate a fingerprint package or individual artifact. | -| `ghost verify` | Validate evidence paths, exemplar paths, and typed check refs. | -| `ghost check` | Run active deterministic gates against a diff. | -| `ghost review` | Emit an evidence-routed advisory packet from fingerprint facets and a diff. | -| `ghost relay gather` | Gather fingerprint-grounded context for an agent target. | -| `ghost emit ` | Emit `review-command` artifacts. | -| `ghost skill install` | Install the unified Ghost skill bundle. | -| `ghost stack` | Inspect resolved root-to-leaf fingerprint stacks. | -| `ghost signals` | Emit raw repo signals as JSON for fingerprint authoring. | -| `ghost describe` | Print markdown section ranges. | -| `ghost compare` | Compare fingerprint packages. | -| `ghost ack` / `track` / `diverge` | Record stance toward tracked drift. | -| `ghost diff` / `survey` | Maintain direct markdown fingerprints or survey/cache files for compatibility workflows. | +| `ghost init` | Scaffold `.ghost/` — manifest, surfaces spine, and a seed node. | +| `ghost scan` | Report node and surface contribution. | +| `ghost validate` | Validate the package: artifact shape and the node graph. | +| `ghost gather` | List nodes, or compose a surface's context slice. | +| `ghost checks` | Select and ground the checks a change touches, by surface. | +| `ghost review` | Emit an advisory review packet grounded in fingerprint + diff. | +| `ghost skill install` | Install the BYOA skill bundle. | +| `ghost signals` | Emit raw repo signals as authoring evidence _(advanced)_. | +| `ghost migrate` | Migrate a legacy `.ghost/` package onto the node model _(maintenance)_. | + +Run `ghost --help` for the core workflow, `ghost --help --all` for everything, +and `ghost --help` for flags. + +## Status: Beta + +> [!WARNING] +> Ghost is pre-1.0 and under active development. The CLI, node schema, on-disk +> `.ghost/` shape, and public exports may change in breaking ways before 1.0. +> Breaking changes may ship in minor versions while pre-1.0; patch versions are +> reserved for fixes that should not require migration. Pin the version you +> depend on and review release notes before upgrading. ## Repo Layout Ghost is a pnpm monorepo. The public package is self-contained for npm; private -workspace packages remain development context. +workspace packages are development context. | Path | Role | Published? | | ---- | ---- | --- | -| [`packages/ghost`](./packages/ghost) | Public package. Ships the `ghost` CLI, folded core runtime, fingerprint package helpers, deterministic checks, advisory review packets, comparison/stance helpers, and the unified skill bundle. | yes: `@anarchitecture/ghost` | +| [`packages/ghost`](./packages/ghost) | Public package: the `ghost` CLI, folded core runtime, node authoring, checks, advisory review, and the skill bundle. | yes: `@anarchitecture/ghost` | | [`packages/ghost-fleet`](./packages/ghost-fleet) | Private fleet view across many Ghost bundles. | no | -| [`packages/ghost-ui`](./packages/ghost-ui) | Reference design system: shadcn registry plus `ghost-mcp` MCP server. | no | +| [`packages/ghost-ui`](./packages/ghost-ui) | Reference design system: shadcn registry plus `ghost-mcp` server. | no | | [`apps/docs`](./apps/docs) | Docs site. | no | ## Development @@ -194,17 +146,11 @@ pnpm build pnpm test pnpm check pnpm dump:cli-help -pnpm --filter @anarchitecture/ghost pack ``` No API key is required to run Ghost. `OPENAI_API_KEY` / `VOYAGE_API_KEY` are optional and only used by semantic embedding helpers when a host opts in. -## Resources +## License -| Resource | Description | -| --- | --- | -| [docs/purposes.md](./docs/purposes.md) | What fingerprints are for: one model, many projections. | -| [docs/ideas/](./docs/ideas) | Live design notes, anchored by `fingerprint-first-architecture.md`. | -| [GOVERNANCE.md](./GOVERNANCE.md) | Project governance. | -| [LICENSE](./LICENSE) | Apache License, Version 2.0. | +[Apache License 2.0](./LICENSE) · [Governance](./GOVERNANCE.md) diff --git a/apps/docs/src/app/docs/page.tsx b/apps/docs/src/app/docs/page.tsx index 2bf96ca0..541383bb 100644 --- a/apps/docs/src/app/docs/page.tsx +++ b/apps/docs/src/app/docs/page.tsx @@ -1,7 +1,7 @@ "use client"; import { useStaggerReveal } from "ghost-ui"; -import { BookOpen, Rocket } from "lucide-react"; +import { BookOpen, FileText, Rocket } from "lucide-react"; import type { ReactNode } from "react"; import { Link } from "react-router"; import { AnimatedPageHeader } from "@/components/docs/animated-page-header"; @@ -20,11 +20,18 @@ const sections: { "Install Ghost, set up the repo fingerprint, and learn the loop around .ghost.", icon: , }, + { + name: "Fingerprint Authoring", + href: "/docs/fingerprint-authoring", + description: + "Co-author nodes through the intent, inventory, and composition lenses, and place them for inheritance.", + icon: , + }, { name: "CLI Reference", href: "/docs/cli", description: - "Commands for checks and comparison, plus the skill recipes your agent runs.", + "Every command around the node-graph fingerprint: init, validate, gather, checks, and review.", icon: , }, ]; diff --git a/apps/docs/src/app/page.tsx b/apps/docs/src/app/page.tsx index 12e77918..0326b569 100644 --- a/apps/docs/src/app/page.tsx +++ b/apps/docs/src/app/page.tsx @@ -29,120 +29,80 @@ export default function Home() {

- Agents can assemble UI. What they cannot reliably preserve is the - surface composition that UI belongs to. + Agents can assemble UI. What they can't reliably preserve is the + composition behind it — the hierarchy, density, restraint, copy, + trust, and flow that make a surface feel intentional.

- For years, design systems solved a human assembly problem. They - gave teams shared tokens, components, examples, and usage rules so - new surfaces could be composed from known parts. + Design systems solved a human assembly problem: shared tokens, + components, and usage rules so teams could build from known parts. + That layer still matters. But agents already recombine those + parts. The scarce layer now is the composition that tells them + when and how the parts belong.

- That layer still matters, but agents change the scarce layer. - Models can copy local patterns and recombine components. They do - not consistently preserve the composition that makes a product - surface feel intentional: hierarchy, density, restraint, behavior, - copy, accessibility, trust, and flow. + Ghost captures that composition and checks it into the repo, where + generation happens. It is a{" "} + graph of prose nodes — + one markdown file each — that your agent reads before it builds + and checks after it changes.

-

- Ghost captures the composition of a product surface: the intent - behind it, the materials it draws from, and the patterns that make - it feel intentional. -

-

- It stores that composition as checked-in fingerprint facets: which - intent shapes the surface, which materials agents can draw from, - which situations change the obligation, which patterns hold the - surface together, and which examples show it at its best. -

-

- Components, tokens, and libraries become implementation material. - Ghost does not replace them. It gives agents the surface context - that tells them when and how those materials belong. -

-

Ghost keeps that model compact:

  • - .ghost/ is the default portable fingerprint package + .ghost/ is the portable fingerprint package
  • - intent.yml, inventory.yml, and{" "} - composition.yml store the three facets + surfaces.yml is the spine; nodes/*.md{" "} + are the design expression
  • - validate.yml stores optional deterministic gates - grounded in fingerprint refs + each node is written through intent,{" "} + inventory, and composition — the why, + the materials, the patterns
  • - ordinary Git review separates draft fingerprint edits from - checked-in truth + checks/*.md validate output; they are never + generation input
    • +
  • ordinary Git review is the approval boundary for edits

- The split is deliberate. intent.yml captures the - intent behind the surface. inventory.yml captures the - materials it draws from. composition.yml captures the - patterns that make it feel intentional. Checks validate output; - they are not generation input. + A node inherits everything it sits under. The brand + soul lives at core and reaches every surface; + surface-specific nodes refine it; relates links them + laterally. Asking for context becomes a graph traversal:{" "} + ghost gather <surface> composes the slice that + applies.

-

A typical loop becomes:

+

The loop is small:

    -
  1. Brief from the fingerprint facets and exemplars
    2. -
  2. Generate or edit with the host agent
    3. -
  3. Run active deterministic checks and advisory review
  4. - Fix code, explain intentional divergence, or update the Ghost - package through Git + Gather the composed context for the surface you're touching +
    5. +
  5. Generate or edit with your agent
    6. +
  6. Route checks and emit an advisory review against the diff
    7. +
  7. + Fix code, explain intentional divergence, or update the + fingerprint through Git

Ghost stays bring-your-own-agent. The agent reads, decides, and - writes. Ghost does the repeatable work: initialization, schema - validation, inventory, evidence verification, checks, advisory - review packets, comparison, and upstream handoff packets. -

-

- This is critical because surface composition that cannot be - recalled or evaluated cannot be delegated. A product surface that - only its original author can assess is not transferable: to - agents, to new engineers, or to forks of the product. -

-

- Drift becomes measurable within this system. When generated or - modified UI diverges from checked-in fingerprint facets, the - failure is not just error; it is signal. Drift can originate from: -

-
    -
  • incorrect generation: agent failure
    • -
  • missing-fingerprint: under-specified surface context
    • -
  • intentional product evolution
    • -
-

- Ghost does not eliminate drift; it surfaces and localizes it. The - system's boundary becomes visible where composition fails. -

-

- The fingerprint package must live where generation happens: in the - repository, versioned alongside the code it governs. As the - product changes, fingerprint edits move through the same ordinary - Git review that introduces new UI. -

-

- This leads to a practical governance model. Each repository owns - its product-surface fingerprint. Advanced workflows can add nested - packages for product areas, custom fingerprint directories for - host wrappers, comparison across systems, and declared drift - stances. + writes. Ghost does the repeatable work: scaffolding, schema and + graph validation, context composition, check routing, and advisory + review packets.

- Across an organization, the collection of Ghost packages forms a - higher-order map: a distributed model of product-surface - composition as it is actually practiced, not as it is only - described. + Composition that can't be recalled or evaluated can't be + delegated. A surface only its author can assess isn't transferable + — not to agents, not to new engineers, not to forks. Ghost makes + it transferable, and makes drift measurable: where generated UI + diverges from the fingerprint, the gap is signal, and it is + localized.

Design systems were libraries for humans. Ghost is composition - context for agents: every surface can carry the fingerprint it + context for agents — every surface carries the fingerprint it extends, and every deviation can carry evidence.

diff --git a/apps/docs/src/app/tools/page.tsx b/apps/docs/src/app/tools/page.tsx index ffaefd8f..4ea48d66 100644 --- a/apps/docs/src/app/tools/page.tsx +++ b/apps/docs/src/app/tools/page.tsx @@ -78,7 +78,7 @@ export default function ToolsIndex() { diff --git a/apps/docs/src/app/tools/scan/page.tsx b/apps/docs/src/app/tools/scan/page.tsx index c4a97f49..ee36b79d 100644 --- a/apps/docs/src/app/tools/scan/page.tsx +++ b/apps/docs/src/app/tools/scan/page.tsx @@ -22,16 +22,16 @@ const cards: { }, { name: "CLI reference", - href: "/docs/cli#ghost--fingerprint-layers-and-package-checks", + href: "/docs/cli", description: - "Check fingerprint contribution facets, validate packages, and emit context.", + "Report node and surface contribution, validate the graph, and compose context.", icon: , }, { - name: "Format spec", - href: "https://github.com/block/ghost/blob/main/docs/fingerprint-format.md", + name: "Authoring", + href: "/docs/fingerprint-authoring", description: - "The full package format for fingerprint intent, inventory, composition, and validation.", + "How to write nodes through the intent, inventory, and composition lenses.", icon: , }, ]; @@ -48,7 +48,7 @@ export default function GhostScanLanding() {
Ghost +

+ The product-surface fingerprint your agent reads before it builds + and checks after it changes. +

diff --git a/apps/docs/src/content/docs/cli-reference.mdx b/apps/docs/src/content/docs/cli-reference.mdx index 2fed608b..cb236d95 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: Commands around the portable fingerprint lifecycle. Your agent handles the composition work. +description: The deterministic commands around the node-graph fingerprint lifecycle. Your agent does the reading, writing, and reviewing. kicker: Docs section: guide order: 30 @@ -9,25 +9,22 @@ slug: cli -The CLI does the repeatable parts around the fingerprint lifecycle: create -packages, report contribution state, validate files, gather optional source material, -emit handoff packets, govern diffs, compare packages, and record intent. Your -agent does the reading, writing, and reviewing. +The CLI does the repeatable parts around the fingerprint lifecycle: scaffold a +package, validate the node graph, compose context for a surface, route checks, +and emit advisory review packets. Your agent does the interpretation. -`ghost --help` intentionally shows the short core workflow for new adopters. -Run `ghost --help --all` for the complete command index; command-specific help -remains available with `ghost --help`. +`ghost --help` shows the short core workflow. `ghost --help --all` shows the +complete command index, and `ghost --help` shows flags for one +command. -Canonical Ghost fingerprints start here, with optional child packages for scoped -product areas: +The canonical fingerprint is a flat `.ghost/` package: ```text -.ghost/manifest.yml -.ghost/intent.yml -.ghost/inventory.yml -.ghost/composition.yml -.ghost/validate.yml -apps/checkout/.ghost/manifest.yml +.ghost/ + manifest.yml # schema + id + surfaces.yml # the spine: surfaces and their parent (core is implicit) + nodes/*.md # prose nodes — the design expression + checks/*.md # optional rules an agent evaluates ``` The command tables below are generated from the CLI source. Run @@ -37,59 +34,40 @@ The command tables below are generated from the CLI source. Run -### Initialize - `init` +### Initialize — `init` -Create a `.ghost/` package with a manifest, raw facet files, -and deterministic checks. Use `--scope ` for nested package roots. Use -`--monorepo` to create or preserve the root package, detect workspace child -roots, and print scoped init commands; add `--apply` to create the detected -child packages. Use -`GHOST_PACKAGE_DIR=` only when a host wrapper stores Ghost package -roots under a different safe relative directory; raw `ghost` defaults to -`.ghost`. Exact `--package ` values win over the environment default. +Scaffold a `.ghost/` package: a manifest, an empty surfaces spine (the `core` +root needs no declaration), and one seed node placed at `core`. Use +`--template ` to pick a starter, `--package ` for an exact directory, +or set `GHOST_PACKAGE_DIR` when a host wrapper stores Ghost files outside the +default `.ghost`. ```bash ghost init -ghost init --monorepo -ghost init --monorepo --apply -ghost init --scope apps/checkout +ghost init --template default ghost init --package product-surface -ghost init --package .design/custom-ghost GHOST_PACKAGE_DIR=.agents/ghost ghost init -GHOST_PACKAGE_DIR=.design/memory ghost init --scope apps/checkout ``` -### Contribution facets - `scan` +### Contribution — `scan` -Report whether `manifest.yml` is present and which sparse facets -this package contributes: `intent`, `inventory`, `composition`, and `validate`. -Raw repo signals do not count toward inventory contribution. +Report what the package contributes: presence of the manifest and surfaces +spine, and the nodes and surfaces it carries. ```bash ghost scan ghost scan --format json -GHOST_PACKAGE_DIR=.agents/ghost ghost scan --format json -GHOST_PACKAGE_DIR=.design/memory ghost scan --include-nested --format json ``` -### Stack inspection - `stack` - -Inspect the root-to-leaf fingerprint stack for one or more paths. - - - -```bash -ghost stack apps/checkout/review/page.tsx --format json -``` - -### Inspect repo signals - `signals` +### Repo signals — `signals` Emit raw signals about a frontend repo as JSON. Use this as scratch evidence -while authoring curated fingerprint facets. +while authoring curated nodes — it does not contribute to the fingerprint by +itself. @@ -99,108 +77,109 @@ ghost signals . - + -### Validation - `lint` +### Validation — `validate` -Validate a root `.ghost` fingerprint package or an individual split artifact. -`--all` validates every nested package and merged stack. +Validate the package: artifact shape plus the node graph — every `under` and +`relates` link resolves, there is exactly one root, and the graph is acyclic. +Defaults to `.ghost`; pass a file to validate a single artifact. - + ```bash -ghost lint -ghost lint .ghost/intent.yml -ghost lint .ghost/validate.yml --format json -ghost lint --all +ghost validate +ghost validate .ghost/nodes/checkout-trust.md +ghost validate --format json ``` -### Package fidelity - `verify` + + + + +### Compose a surface slice — `gather` -Validate fingerprint evidence and exemplar paths, typed check refs, and -optional rationale files. +With no argument, list every node by id and description so an agent can match a +task to one. With a surface, compose its context slice: the surface's own nodes, +the ancestors it inherits via `under`, and one-hop `relates` edges. Use `--as` +to filter to a single incarnation; untagged essence nodes always pass. - + ```bash -ghost verify .ghost --root . -GHOST_PACKAGE_DIR=.design/memory ghost verify --all +ghost gather +ghost gather checkout +ghost gather checkout --as email +ghost gather checkout --format json ``` -### Reusable Review Command - `emit` +This is the pre-generation step: Ghost gives agents surface-composition context +before they build, not only after a review finds drift. -Emit `review-command` from split fingerprint facets when a host wants a -reusable review prompt. + - + -### Agent Context - `relay gather` +### Route checks — `checks` -Gather Relay context for a target path or structured Relay request. Relay loads -config first; omitted `base` means `base.kind: fingerprint`, while -`base.kind: none` lets agent-framework repos gather declared request context -without a `.ghost` package. For agents and host adapters, use JSON: the full -`ghost.relay.gather/v2` result is the stable contract, and its nested `context` -is `ghost.relay-context/v1`. Plain markdown output remains a compact human -preview. +Select and ground the markdown checks governing the named surfaces. The agent +names the surfaces the change touches, then evaluates the returned checks. Use +`--no-grounding` to omit the grounded nodes and return only the relevant checks. - + ```bash -ghost relay gather apps/checkout/review/page.tsx --format json -ghost relay gather apps/checkout/review/page.tsx --package product-surface --format json -ghost relay gather apps/checkout/review/page.tsx --config .ghost/relay.yml --format json -GHOST_RELAY_CONFIG=.agents/ghost/relay.yml ghost relay gather --request-stdin --format json -ghost relay gather stacks/portal.renewal-reminder.email.yml --config .agents/ghost/relay.yml --format json -ghost relay gather --request request.yml --format json -ghost relay gather --request-stdin --format json -ghost relay gather apps/checkout/review/page.tsx # human preview +ghost checks --surface checkout +ghost checks --surface checkout,billing +ghost checks --surface checkout --format json ``` -### Inspection - `describe` - -Print a markdown section map. +### Advisory review packet — `review` - +Emit an advisory packet for a diff: touched surfaces, routed checks, and +fingerprint grounding, with the diff embedded verbatim. Diff against a git ref +with `--base`, or pass a patch with `--diff` (use `-` for stdin). -### Survey/cache ops - `survey ` + -Operate on `ghost.survey/v1` files as compatibility cache source material. +```bash +ghost review --surface checkout --base main +ghost review --surface checkout --diff change.patch +git diff | ghost review --surface checkout --diff - +ghost review --surface checkout --format json +``` - +Wrappers should consume `--format json` and map Ghost severities (`critical`, +`serious`, `nit`) into their own review format. Advisory review is never a CI +gate on its own. - - -### Deterministic gates - `check` + -Run active `ghost.validate/v1` gates against a git diff. Without `--package`, -Ghost groups changed files by resolved fingerprint stack and runs merged checks -per group. +### Install the skill — `skill` - +Install the unified Ghost skill bundle so a host agent knows how to author and +use the fingerprint. -### Advisory governance packet - `review` - -Emit an evidence-routed advisory review packet grounded in selected context, -validation checks, and the diff. - - + -### Comparison - `compare` - -Pairwise distance or composite analysis over fingerprint packages. +```bash +ghost skill install +ghost skill install --agent claude +ghost skill install --dest ~/.codex/skills/ghost +``` - +### Migrate a legacy package — `migrate` -### Drift stance - `ack` / `track` / `diverge` +Migrate a legacy `.ghost/` package onto the node-graph surface model. Use +`--dry-run` to print the plan without writing. -Record how the repo should treat tracked fingerprint drift. These compatibility -governance verbs still operate on tracked direct fingerprint markdown files. + - - - +```bash +ghost migrate +ghost migrate .ghost --dry-run +``` diff --git a/apps/docs/src/content/docs/fingerprint-authoring.mdx b/apps/docs/src/content/docs/fingerprint-authoring.mdx index 6f285361..d12a1c21 100644 --- a/apps/docs/src/content/docs/fingerprint-authoring.mdx +++ b/apps/docs/src/content/docs/fingerprint-authoring.mdx @@ -1,6 +1,6 @@ --- title: Fingerprint Authoring -description: Co-author Ghost fingerprints with human intent, repo evidence, agent synthesis, and Git review. +description: Co-author a Ghost fingerprint as a graph of prose nodes — human intent, repo evidence, agent synthesis, and Git review. kicker: Docs section: guide order: 20 @@ -10,32 +10,65 @@ slug: fingerprint-authoring A Ghost fingerprint is not a scan dump. It is durable product-surface -composition that a human and agent shape together. +composition that a human and agent shape together, stored as a graph of prose +**nodes**. -The human names the intent: what the product surface should feel like, who it -serves, which situations matter, and what should not drift. Repo scans provide -evidence: components, routes, docs, stories, copy, screenshots, tokens, -examples, and UI library references. The agent synthesizes drafts, but ordinary -Git review is where fingerprint edits become canonical. +The human names the intent: what the surface should feel like, who it serves, +which situations matter, and what should not drift. Repo scans provide evidence: +components, routes, docs, stories, copy, tokens, and library references. The +agent synthesizes drafts. Ordinary Git review is where node edits become +canonical. + + + + + +Each node is one markdown file in `nodes/`. Frontmatter carries the machine +handles; the body carries the design expression, written through the intent / +inventory / composition lenses. + +```markdown +--- +id: checkout-trust +description: Trust at the payment moment. +under: checkout +relates: + - to: core-trust + as: reinforces +--- + +Near the moment of payment, reduce felt risk. Proximity of reassurance to the +action beats completeness… +``` + +| Handle | Role | +| --- | --- | +| `id` | Unique, stable identifier. How the node is referenced. | +| `description` | The retrieval payload — a one-line "what this is / when to gather it." Write one on any node worth anchoring a task at. | +| `under` | Places the node so it is inherited downward. `core` is the implicit root and reaches every surface. | +| `relates` | Lateral links carrying rationale (`reinforces`, `contrasts`, `variant`). | +| `incarnation` | Tags a medium-bound expression (`email`, `voice`, …). Essence is untagged. | + +Free-form keys (`audience`, `stage`, …) are allowed and pass through untouched. +Surfaces themselves are declared in `surfaces.yml`, never inferred from paths. -Start by classifying the authoring scenario. The scenario determines how much -weight to give human intent, existing code, and library evidence. +Classify the authoring scenario first. It determines how much weight to give +human intent, existing code, and library evidence. | Scenario | Authoring posture | | --- | --- | | Net new repo | Human-led. Capture intent, audience, posture, and early anti-goals before inventory grows. | | Net new repo + UI library | Human-led with library evidence. Explain how this product uses the library. | | Existing repo | Human + scan. Find repeated patterns and exemplars, then ask which ones are canonical. | -| Existing repo with mixed quality | Curated scan. Separate durable surface composition from legacy debt and accidental repetition. | -| Design system or UI library | Grammar-led. Describe primitives, tokens, component behavior, accessibility, and composition constraints. | -| Rebrand, redesign, or migration | Human-led transition. Capture current, target, and migration cautions. | +| Existing repo, mixed quality | Curated scan. Separate durable composition from legacy debt and accidental repetition. | +| Design system or UI library | Grammar-led. Describe primitives, tokens, behavior, accessibility, and composition constraints. | +| Rebrand, redesign, migration | Human-led transition. Capture current, target, and migration cautions. | | Prototype becoming product | Ratification-led. Preserve only the emergent patterns humans want to keep. | -| Fork, white label, or tenant variant | Shared base + local divergence. Keep common surface composition broad and local differences scoped. | -| Monorepo or nested surfaces | Stack-aware. Use root guidance for broad composition and nested packages for surfaces assessed differently. | +| Fork, white label, tenant variant | Shared base + local divergence. Keep common composition at `core`, scope differences to surface nodes. | @@ -43,109 +76,86 @@ weight to give human intent, existing code, and library evidence. Ghost supports two agent authoring modes: -- **Default** - interview first, scan as needed, draft facet edits, then - curate. -- **Auto-draft** - scan first, draft a small starter fingerprint, then curate +- **Default** — interview first, scan as needed, draft nodes, then curate. +- **Auto-draft** — scan first, draft a small starter fingerprint, then curate the claims with a human. -Auto-draft is a skill workflow, not a Ghost CLI command. Ask for it in plain -English: +Auto-draft is a skill workflow, not a CLI command. Ask for it in plain English: ```text Set up the Ghost fingerprint for this repo with auto-draft. ``` -1. **Interview** - ask what the product should feel like, who it serves, which +1. **Interview** — ask what the product should feel like, who it serves, which surfaces show it at its best, and which existing patterns are accidental or - legacy. In auto-draft mode, use this step after the starter draft to curate - claims. -2. **Scan** - inspect routes, components, stories, tests, docs, screenshots, - copy, tokens, assets, and UI library references. -3. **Draft** - write the smallest useful `intent.yml`, `inventory.yml`, and - `composition.yml` entries. -4. **Curate** - have the human keep, soften, reject, scope, or record important - claims before treating them as durable surface context. -5. **Validate** - run Ghost validation and use Git review as the approval + legacy. +2. **Scan** — inspect routes, components, stories, tests, docs, copy, tokens, + and library references. Use `ghost signals` for raw observations. +3. **Draft** — write the smallest useful nodes. Place durable, cross-surface + guidance at `core`; place surface-specific obligations `under` that surface. +4. **Curate** — have the human keep, soften, reject, or scope each claim before + it is treated as durable context. +5. **Validate** — run `ghost validate` and use Git review as the approval boundary. ```bash -ghost scan --format json ghost signals . -ghost lint .ghost -ghost verify .ghost --root . +ghost scan +ghost validate ``` -Raw repo signals are source evidence only. They can support curated inventory, -but they do not establish surface-composition guidance by themselves. Signal -frequency may seed a draft, but it does not decide what the surface should do. +Raw repo signals are source evidence only. Signal frequency may seed a draft, +but it does not decide what the surface should do. - + -Keep each claim in the file that will make it useful later: +The graph is the model. Decide where each claim lives by how far it should +reach. -| Facet | What belongs there | -| --- | --- | -| `intent.yml` | Audience, goals, anti-goals, situations, principles, and experience contracts. | -| `inventory.yml` | Scopes, surface types, files, routes, libraries, assets, building blocks, exemplars, and source links. | -| `composition.yml` | Repeatable rules, layouts, structures, flows, states, content patterns, behavior, and visual arrangements. | -| `validate.yml` | Deterministic gates that can be checked from a diff. | +- Put the brand soul — voice, trust posture, broad product intent — at `core`. + It cascades to every surface. +- Put surface-specific obligations `under` the surface that owns them + (`under: checkout`). +- Link nodes laterally with `relates` only when the relationship carries + rationale a future agent needs. - +```bash +ghost gather # list nodes by id + description +ghost gather checkout # compose checkout's slice (own + inherited + edges) +``` + +`ghost gather ` is the test: if the composed slice reads like coherent +guidance for that surface, the placement is right. - + -A useful fingerprint should help future agents choose, restrain, route, anchor, -and review. It should not only describe what exists or collect every available -style detail. + -Write facet content so generation decisions become explicit: +A useful node helps a future agent choose, restrain, and review — not just +describe what exists. Write the body so generation decisions become explicit: -- `goals` name what generated work should preserve. -- `anti_goals` block plausible defaults that would make the surface feel - generic or wrong. -- `tradeoffs` say which value wins when choices conflict. -- `situations` route guidance by task, surface type, state, or audience need. -- `principles` capture broad product intent. -- `experience_contracts` turn taste, trust, recovery, or disclosure into - obligations. -- `composition.patterns` give repeatable layout, flow, state, content, - behavior, or visual rules. -- `inventory.exemplars` anchor the guidance in concrete material an agent can - inspect. +- Name what generated work should preserve. +- Block the plausible defaults that would make the surface feel generic. +- Say which value wins when choices conflict. +- Anchor the guidance in concrete material an agent can inspect. Write less like a brand book and more like a decision engine. - + -Nested fingerprints are opt-in. Create a local `.ghost/` only when a surface -should be assessed differently from the root product fingerprint. +Uncommitted or unmerged node edits are drafts. Checked-in nodes are canonical. -Use a nested package when a surface has distinct users, information density, -trust or recovery posture, interaction rhythm, component grammar, UI library -usage, or review criteria for the same UI decision. - -Keep broad product-family guidance at the root. Put local obligations in the -nearest package that owns the surface. +Add `ghost.check/v1` markdown checks in `checks/*.md` sparingly, and only when a +rule can be enforced from a diff. Checks are routed by surface and validate +output — they are never generation input. ```bash -ghost init --scope apps/checkout -ghost stack apps/checkout -ghost lint --all -ghost verify --all +ghost checks --surface checkout +ghost review --surface checkout --base main ``` - - - -Uncommitted or unmerged fingerprint edits are drafts. Checked-in -Ghost package facet files are canonical. - -Add deterministic checks sparingly, and only when a rule can be enforced -deterministically. - - diff --git a/apps/docs/src/content/docs/getting-started.mdx b/apps/docs/src/content/docs/getting-started.mdx index ebc88699..8be29b1f 100644 --- a/apps/docs/src/content/docs/getting-started.mdx +++ b/apps/docs/src/content/docs/getting-started.mdx @@ -1,35 +1,40 @@ --- title: Getting Started -description: Install Ghost, author a product-surface composition fingerprint, and use it to generate, validate, compare, and govern product surfaces. +description: Install Ghost, scaffold a product-surface fingerprint as a graph of prose nodes, and use it to brief, validate, and review your agent's work. kicker: Docs section: guide order: 10 slug: getting-started --- - + -Ghost captures the composition of a product surface: the intent behind it, the -materials it draws from, and the patterns that make it feel intentional. The -public package is `@anarchitecture/ghost`, and it installs one CLI: `ghost`. +Ghost captures the composition of a product surface — the intent behind it, the +materials it draws from, and the patterns that make it feel intentional — and +checks it into the repo. The public package is `@anarchitecture/ghost`, and it +installs one CLI: `ghost`. -The canonical portable fingerprint is a folder: +A fingerprint is a small folder of prose: ```text .ghost/ - manifest.yml - intent.yml - inventory.yml - composition.yml - validate.yml + manifest.yml # schema + id + surfaces.yml # the spine: surfaces and their parent (core is implicit) + nodes/*.md # prose nodes — the design expression + checks/*.md # optional rules an agent evaluates ``` -Generation starts from `intent.yml`, `inventory.yml`, and `composition.yml`. -`validate.yml` checks validate the result afterward; they are not generation input. +The fingerprint is a **graph of nodes**. A node is one markdown file: +frontmatter handles plus a prose body. You write that body through three lenses +— they guide what to capture, they are not fields: -Nested product areas can add child package roots such as -`apps/checkout/.ghost/`. Ghost resolves fingerprint stacks -root-to-leaf for the file or diff being reviewed. +- **intent** — the why and the stance. +- **inventory** — the materials, and pointers to the code an agent can inspect. +- **composition** — the patterns that make the surface feel like one product. + +`under` cascades a node downward (`core` is the implicit root and reaches every +surface). `relates` links nodes laterally. Checks validate output afterward; +they are never generation input. @@ -37,20 +42,20 @@ root-to-leaf for the file or diff being reviewed. -Ghost is pre-1.0 and under active development. The CLI, fingerprint schema, -on-disk `.ghost/` package shape, and public JavaScript exports may -change in breaking ways before a stable 1.0 release. +Ghost is pre-1.0 and under active development. The CLI, node schema, on-disk +`.ghost/` shape, and public JavaScript exports may change in breaking ways +before a stable 1.0 release. Breaking changes may ship in minor versions while Ghost is pre-1.0. Patch versions are reserved for fixes that should not require migration. If you adopt -Ghost today, expect some churn, pin the version you depend on, and review -release notes before upgrading. +Ghost today, pin the version you depend on and review release notes before +upgrading. - + ```bash npm install -D @anarchitecture/ghost @@ -59,15 +64,16 @@ npx ghost --help --all npx ghost skill install ``` -`ghost --help` shows the core new-adopter workflow. Use `ghost --help --all` -when you want the complete command index. +`ghost --help` shows the core workflow. `ghost --help --all` shows the complete +command index, and `ghost --help` shows flags for one command. -Once the skill is installed, ask your agent in plain English: +Ghost is **bring-your-own-agent**. Once the skill is installed, ask your agent +in plain English: ```text Set up the Ghost fingerprint for this repo. Brief this work from the Ghost fingerprint. -Review this PR against the Ghost fingerprint. +Review this change against the Ghost fingerprint. ``` The skill tells the agent what to read, what to write, and which CLI checks to @@ -75,95 +81,108 @@ run. - + -The CLI handles the deterministic package work. Your agent handles the -composition work: interviewing, reading repo evidence, drafting facet edits, and -asking you to curate the claims. +`ghost init` writes a minimal package: a manifest, an empty surfaces spine (the +`core` root needs no declaration), and one seed node placed at `core`. ```bash ghost init -ghost scan --format json -ghost signals . -ghost lint .ghost -ghost verify .ghost --root . +ghost validate +ghost scan ``` -The fingerprint records durable surface-composition guidance: - -1. **Intent** - what must remain true: what product this is, who it - serves, which situations matter, and which principles or contracts apply. -2. **Inventory** - the materials it draws from: topology, building blocks, - files, routes, assets, libraries, exemplars, and source links agents may - inspect or use. -3. **Composition** - the patterns that make it intentional: rules, layouts, - structures, flows, states, content, behavior, and visual arrangements. - -Raw repo signals are optional authoring evidence. Curate durable intent, -inventory, and composition into the facet files, then use normal Git -review for approval. For a fuller human-agent workflow, read -[Fingerprint Authoring](/docs/fingerprint-authoring). +`ghost validate` confirms the package is well-formed: artifact shape plus the +node graph (links resolve, exactly one root, acyclic). `ghost scan` reports what +the package contributes. - + -Before generating or revising UI, gather Relay JSON for the target path: +A node is one markdown file in `nodes/`. The frontmatter is machine handles; the +body is the design expression. -```bash -ghost relay gather apps/checkout/review/page.tsx --format json -``` +```markdown +--- +id: checkout-trust +description: Trust at the payment moment. +under: checkout +relates: + - to: core-trust + as: reinforces +incarnation: web +--- -`ghost.relay.gather/v2` is the agent contract. Agents should read `context`, -`selected_context`, `targetPaths`, `source`, `stackDirs`, gaps, and trace fields -from JSON. Plain `ghost relay gather ` remains a compact human preview. -For prompt-shaped work where there is no clear path, host agents can create a -`ghost.relay-request/v1` and run -`ghost relay gather --request-stdin --format json`. -Relay config controls the runtime. Omitted `base` uses the resolved fingerprint -stack; `base.kind: none` lets frameworks provide declared request context -without a `.ghost` package: +Near the moment of payment, reduce felt risk. Proximity of reassurance to the +action beats completeness. Never introduce a new visual system here. +``` -```bash -GHOST_RELAY_CONFIG=.agents/ghost/relay.yml ghost relay gather --request-stdin --format json -ghost relay gather stacks/portal.renewal-reminder.email.yml --config .agents/ghost/relay.yml --format json +- **`id`** — unique and stable; how the node is referenced. +- **`description`** — the retrieval payload: a one-line "what this is and when to + gather it," exactly like a tool's name and description. `ghost gather` with no + argument lists nodes by id and description so an agent can match a task to one. +- **`under`** — places the node so it is inherited downward. `core`-placed nodes + reach every surface. +- **`relates`** — links nodes laterally (`reinforces`, `contrasts`, `variant`). +- **`incarnation`** — tags a medium-bound expression (`email`, `voice`, …). + Leave essence untagged. Free-form keys (`audience`, `stage`, …) pass through. + +Surfaces are declared in `surfaces.yml`, never inferred from filenames: + +```yaml +schema: ghost.surfaces/v1 +surfaces: + - id: checkout + parent: core ``` -The package remains the approved product-surface context; review and check -commands apply it after implementation. +The CLI handles the deterministic work — scaffolding, validation, context +composition. Your agent handles the composition work: interviewing, reading +repo evidence, drafting nodes, and asking you to curate the claims. Use +`ghost signals` for raw repo observations while authoring. For the full +human-agent workflow, read [Fingerprint Authoring](/docs/fingerprint-authoring). + +Drafted fingerprint edits are ordinary file changes until Git review accepts +them. Checked-in nodes are the Ghost source of truth. - + -After implementation, run Ghost against the same fingerprint: +Before generating or revising UI, compose the context slice for the surface +you're touching: ```bash -ghost check --base main -ghost review --base main +ghost gather # list nodes by id + description +ghost gather checkout # compose checkout's slice +ghost gather checkout --as email # filter to one incarnation ``` -`ghost check` applies active deterministic gates from the resolved fingerprint -stack for each changed file. `ghost review` emits advisory context grounded in -the same selected context as Relay, selected validation checks, and the diff. - -Wrappers should consume `ghost check --format json` and map Ghost severities -outside Ghost. Ghost severities remain `critical`, `serious`, and `nit`. +`ghost gather ` traverses the graph: the surface's own nodes, the +ancestors it inherits via `under`, and one-hop `relates` edges. The important +shift is timing — Ghost gives agents surface-composition context **before** they +build, not only after a review finds drift. - + + +After implementation, route the relevant checks and emit an advisory packet +against the diff. The agent names the surfaces the change touches. ```bash -ghost compare market/.ghost dashboard/.ghost -ghost stack apps/checkout/review/page.tsx -ghost ack --stance aligned --reason "Initial baseline" -ghost track new-tracked.fingerprint.md -ghost diverge typography --reason "Editorial product uses a different type scale" +ghost checks --surface checkout +ghost review --surface checkout --base main ``` -Package comparison uses canonical `.ghost/` packages. `ack`, -`track`, and `diverge` record stance for compatibility drift workflows that -track direct fingerprint markdown references. +`ghost checks` selects and grounds the markdown checks governing the named +surfaces — the agent evaluates them. `ghost review` emits an advisory packet: +touched surfaces, routed checks, and fingerprint grounding, with the diff +embedded verbatim. + +Wrappers should consume `--format json` and map Ghost severities into their own +review format. Ghost severities are `critical`, `serious`, and `nit`. Advisory +review is never a CI gate on its own. diff --git a/packages/ghost/README.md b/packages/ghost/README.md index bdef9c74..3983b78a 100644 --- a/packages/ghost/README.md +++ b/packages/ghost/README.md @@ -2,24 +2,24 @@ **A unified Ghost CLI for product-surface composition fingerprints.** -Ghost captures the composition of a product surface: the intent behind it, the -materials it draws from, and the patterns that make it feel intentional. It -stores that composition in a repo-local `.ghost/` package that host -agents can read before generation and validate after changes. +Agents can assemble UI. They can't reliably preserve the _composition_ behind it +— the hierarchy, density, restraint, copy, trust, and flow that make a surface +feel intentional. Ghost captures that composition in a repo-local `.ghost/` +package that a host agent reads before it builds and checks after it changes. This package ships one CLI: `ghost`. ## Project Status: Beta > [!WARNING] -> Ghost is pre-1.0 and under active development. The CLI, fingerprint schema, -> on-disk `.ghost/` package shape, and public JavaScript exports may -> change in breaking ways before a stable 1.0 release. +> Ghost is pre-1.0 and under active development. The CLI, node schema, on-disk +> `.ghost/` package shape, and public JavaScript exports may change in breaking +> ways before a stable 1.0 release. > > Breaking changes may ship in minor versions while Ghost is pre-1.0. Patch > versions are reserved for fixes that should not require migration. If you adopt -> Ghost today, expect some churn, pin the version you depend on, and review -> release notes before upgrading. +> Ghost today, pin the version you depend on and review release notes before +> upgrading. ## Install @@ -30,7 +30,24 @@ npx ghost --help --all ``` `ghost --help` shows the core workflow. `ghost --help --all` shows the complete -command index. +command index, and `ghost --help` shows flags for one command. + +## The Shape + +A fingerprint is a small folder of prose — a **graph of nodes**: + +```text +.ghost/ + manifest.yml # schema + id + surfaces.yml # the spine: surfaces and their parent (core is implicit) + nodes/*.md # prose nodes — the design expression + checks/*.md # optional rules an agent evaluates +``` + +A node is one markdown file: frontmatter handles (`id`, `description`, `under`, +`relates`, `incarnation`) plus a prose body written through three lenses — +**intent** (the why), **inventory** (the materials), and **composition** (the +patterns). `under` cascades a node downward; `core` reaches every surface. ## Use @@ -38,65 +55,63 @@ Create and validate the fingerprint package: ```bash ghost init -ghost scan --format json -ghost lint .ghost -ghost verify .ghost --root . +ghost validate +ghost scan ``` Gather context before generation: ```bash -ghost relay gather apps/checkout/review/page.tsx +ghost gather # list nodes by id + description +ghost gather checkout # compose a surface's context slice ``` Govern changes afterward: ```bash -ghost check --base main -ghost review --base main +ghost checks --surface checkout +ghost review --surface checkout --base main ``` -Install the BYOA skill bundle so your host agent can author, brief, review, -verify, remediate, and update fingerprints: +Install the BYOA skill bundle so your host agent can author, brief, review, and +verify fingerprints: ```bash ghost skill install ``` -Advanced commands such as `signals`, `stack`, `compare`, `ack`, `track`, and -`diverge` remain available in the full command index. +Advanced and maintenance commands — `signals` and `migrate` — remain available +in the full command index. -Zero config for every verb. No API key is required. `OPENAI_API_KEY` / -`VOYAGE_API_KEY` are optional and only used by semantic embedding helpers when a -host opts in. +No API key is required. `OPENAI_API_KEY` / `VOYAGE_API_KEY` are optional and +only used by semantic embedding helpers when a host opts in. ## Library ```ts -import { compare } from "@anarchitecture/ghost/compare"; -import { runGhostCheck } from "@anarchitecture/ghost/govern"; -import { gatherRelayContext } from "@anarchitecture/ghost/relay"; import { initFingerprintPackage, lintFingerprintPackage, - verifyFingerprintPackage, } from "@anarchitecture/ghost/fingerprint"; +import { buildCli } from "@anarchitecture/ghost/cli"; ``` +Available subpath exports: `@anarchitecture/ghost`, +`@anarchitecture/ghost/scan`, `@anarchitecture/ghost/fingerprint`, +`@anarchitecture/ghost/core`, and `@anarchitecture/ghost/cli`. + ## BYOA Ghost is bring-your-own-agent. The CLI performs deterministic work: repo -signals, readiness reporting, linting, verification, comparison, checks, and -advisory review packet generation. The installed `ghost` skill teaches a host -agent how to capture canonical `.ghost/` surface-composition -context, brief and generate work from it, review changes against it, verify -generated UI, remediate issues, and suggest fingerprint edits when the user -asks. +signals, contribution reporting, graph validation, context composition, check +routing, and advisory review packets. The installed `ghost` skill teaches a host +agent how to capture canonical `.ghost/` surface-composition context, brief and +generate work from it, review changes against it, and verify generated UI. ```text Set up the Ghost fingerprint for this repo. Brief this work from the Ghost fingerprint. -Review this PR against the Ghost fingerprint. +Review this change against the Ghost fingerprint. ``` ## Maintainers