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.

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.

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/fingerprint/ package that ordinary Git review can approve.

The Shape

The canonical package is intentionally small:

.ghost/
  config.yml                    # optional local routing, not portable context
  fingerprint/
    manifest.yml                # ghost.fingerprint-package/v1 anchor
    prose.yml                   # surface intent
    inventory.yml               # curated material and exemplars
    composition.yml             # patterns, flows, states, and arrangements
    enforcement/checks.yml      # optional deterministic gates
    memory/intent.md            # optional human-approved intent
    memory/decisions/           # optional rationale history
    sources/cache/              # optional generated observations

Generation uses the three core layers:

• prose.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.

Checks, memory, generated cache, nested packages, and custom --memory-dir locations are supporting features. They do not replace the core fingerprint layers. Generated cache answers what exists; curated fingerprint layers 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 or cache workflows, but new Ghost work should target .ghost/fingerprint/.

Project Status: Beta

Warning

Ghost is pre-1.0 and under active development. The CLI, fingerprint schema, on-disk .ghost/fingerprint/ 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.

Install

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 <command> --help.

Install the BYOA skill bundle so Codex, Claude, Cursor, Goose, or another host agent knows how to author and use the fingerprint:

npx ghost skill install
# or choose an explicit destination
npx ghost skill install --dest ~/.codex/skills/ghost

Then ask your agent in plain English:

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.

Author A Fingerprint

Ghost authoring is a human-plus-agent workflow. The CLI creates, inspects, and validates the package; the host agent interviews, reads the repo, drafts layer edits, and asks you to curate the claims.

ghost init
ghost scan --format json
mkdir -p .ghost/fingerprint/sources/cache
ghost inventory > .ghost/fingerprint/sources/cache/inventory.json
ghost lint .ghost
ghost verify .ghost --root .

Use --with-intent, --with-config, --reference, --scope, or --memory-dir only when the repo needs those optional files, reference libraries, nested product areas, or host-wrapper storage paths.

Drafted fingerprint edits are just ordinary file changes until Git review accepts them. Checked-in fingerprint/ core files are the Ghost source of truth.

Generate From Ghost

Before generating or revising UI, emit the context bundle:

ghost emit context-bundle

The bundle gives a host agent the selected prose, inventory, composition, optional memory, and active checks. The important shift is timing: Ghost gives agents surface-composition context before they build, not only after a review finds drift.

After implementation, run the deterministic and advisory workflows against the same fingerprint:

ghost check --base main
ghost review --base main --include-memory

ghost check runs active ghost.checks/v1 gates and can fail. ghost review emits an evidence-routed advisory packet for a human or host adapter to use.

Compare And Govern

Advanced workflows remain available when a repo needs package stacks, comparison, or explicit drift stance:

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 scan --format json emits deterministic readiness state. A fingerprint is fingerprint-ready only when prose, inventory, and composition all contain useful layer content. It does not call an LLM.

CLI Commands

Command	Description
ghost init	Create .ghost/fingerprint/ package layers.
ghost scan	Report fingerprint layer readiness for prose, inventory, and composition.
ghost lint	Validate a fingerprint package or individual artifact.
ghost verify	Validate evidence paths, exemplar paths, typed check refs, and optional rationale files.
ghost check	Run active deterministic gates against a diff.
ghost review	Emit an evidence-routed advisory packet from fingerprint layers and a diff.
ghost emit <kind>	Emit review-command or context-bundle artifacts.
ghost skill install	Install the unified Ghost skill bundle.
ghost stack	Inspect resolved root-to-leaf fingerprint stacks.
ghost inventory	Emit raw repo signals as JSON for optional cache material.
ghost describe	Print optional intent or 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.

Repo Layout

Ghost is a pnpm monorepo. The public package is self-contained for npm; private workspace packages remain development context.

Path	Role	Published?
packages/ghost	Public package. Ships the ghost CLI, fingerprint package helpers, deterministic checks, advisory review packets, comparison/stance helpers, and the unified skill bundle.	yes: @anarchitecture/ghost
packages/ghost-core	Private historical shared library. Runtime code needed for npm is folded into packages/ghost.	no
packages/ghost-fleet	Private fleet view across many Ghost bundles.	no
packages/ghost-ui	Reference design system: shadcn registry plus ghost-mcp MCP server.	no
apps/docs	Docs site.	no

Development

pnpm install
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

Resource	Description
docs/fingerprint-format.md	Portable .ghost/fingerprint/ package format.
docs/generation-loop.md	Brief, generate, check, review, and remediate loop.
docs/host-adapters.md	Adapter-neutral JSON, severity mapping, and custom fingerprint directories.
docs/ghost-fleet.md	Current private fleet package model.
GOVERNANCE.md	Project governance.
LICENSE	Apache License, Version 2.0.