@design-intelligence/ghost 0.20.0

package/dist/skill-bundle/references/authoring-scenarios.md

@@ -0,0 +1,147 @@
+---
+name: authoring-scenarios
+description: Choose the right human-agent workflow for authoring Ghost brand fingerprints.
+handoffs:
+  - label: Validate the fingerprint
+    command: ghost validate --format json
+    prompt: Classify this fingerprint's authoring scenario and confirm the package validates.
+---
+
+# Recipe: Collaborative Fingerprint Authoring
+
+**Goal:** help a human and agent co-author durable brand truths through
+conversation — without laundering what a codebase happens to do into what the
+brand means.
+
+The fingerprint is medium-agnostic and is not derived from a repo. Its raw
+material is **elicitation**: what the human says, shows, and points at — words,
+screenshots, links, exemplar products, marketing copy, a competitor they define
+themselves against. Agent synthesis is draft work until the human curates it
+and ordinary Git review accepts it.
+
+Repo-bound reality — components, tokens, paths, building blocks — can be
+recorded as `materials` on the node whose prose explains their purpose. When a
+conversation surfaces "we have a component for that," treat it as material to
+locate and interpret, not as brand truth by itself.
+
+## 1. Start With One Repeated Decision
+
+Do not try to fingerprint the whole brand at once. Ask the human for the one
+decision whose feedback keeps repeating — the checkout always flagged for
+trust, the voice always re-toned, the empty state always rewritten — and
+capture that one truth as a node first. One high-confidence truth beats an
+empty catalog; the fingerprint grows as the next repeated decision shows up.
+
+The scenario below tunes the authoring *posture* for that first node; it is not
+a gate to clear before writing anything.
+
+| Scenario | Default authoring posture |
+| --- | --- |
+| Net new brand | Stance-first. Elicit feel, audience, and early anti-goals before anything else exists to point at. |
+| Established brand, first fingerprint | Artifact-rich interview. The human can show a lot — shipped surfaces, brand docs, campaigns. Elicit which of it is *intentional*. |
+| Strong opinions, weak articulation | Example-led. The human knows it when they see it: work from exemplars and counter-exemplars ("this feels like us, this never would") toward the stance underneath. |
+| Brand doc or design-language deck exists | Distillation. The document is testimony, not truth: pull the claims that actually steer decisions, drop the aspirational filler, and have the human ratify each survivor. |
+| Rebrand, redesign, migration | Transition-led. Capture current, target, and what must not be lost in between. |
+| Fork, white label, tenant variant | Shared base + local divergence. Keep common truths broad; scope divergence with conditions. |
+| Monorepo or product suite | One contract per package. |
+
+If more than one applies, start with the broad scenario, then narrow.
+
+## 2. Interview The Human
+
+The interview is the engine. Ask only high-leverage questions that change the
+fingerprint:
+
+- What should this brand feel like, and what should it never become? (The
+  "never become" answers are anti-goal nodes — capture them with the same care
+  as the affirmative stance.)
+- Who is the audience, and what are they trying to get done?
+- Which surfaces, campaigns, or moments show the brand at its best? Show me.
+- Which brand or product do you admire — and where do you deliberately differ?
+  (The deliberate differences also route to anti-goal nodes: the rejected
+  neighbor, named.)
+- What keeps getting flagged in review, re-toned, or rewritten?
+- Where do trust, density, pacing, accessibility, recovery, or disclosure
+  matter most?
+- Which truths are universal, and which only hold under a specific situation?
+
+Capture human-authored or human-approved answers as nodes. Do not treat
+unapproved notes as canonical.
+
+## 3. Work The Material The Human Brings
+
+Ask for artifacts and read them closely: screenshots, links, exemplar products,
+brand docs, marketing copy, past campaigns, a rejected design and why it was
+rejected. Treat every artifact as *testimony* — evidence of a stance the human
+holds — never as truth by itself. A pattern that appears everywhere may be
+legacy; a pattern that appears once may be the brand at its best. The human
+says which.
+
+Counter-exemplars are as valuable as exemplars when they name the replacement.
+"We would never ship this; we would ship that instead" with artifacts attached
+usually yields a sharper guard than an hour of affirmative description. Avoid
+blacklist-only anti-goals: the rejected pattern should be purged from exemplars
+and enforced in review, not repeated as the model's main example.
+
+## 4. Draft The Nodes
+
+Write the smallest useful set of nodes, each a purpose-coherent prose truth with
+a one-line `description`, named `<kind>.<slug>.md` (or a bare slug when no kind is present). Ask three questions of each body: why (the stance), with what
+(the materials), and how it is assembled (the patterns). These are drafting
+prompts, not fields.
+
+Draft only what the human said or showed. State universal truths plainly; give
+narrower truths a **condition** in the prose — the situation they apply in,
+never a destination. Label uncertain reasoning as provisional. Prefer a few
+high-confidence truths over a broad catalog. Hold draft prose to the node prose
+stances in [capture.md](capture.md) and score each node against its drafting
+gate before presenting drafts for curation.
+
+## 5. Curate With The Human
+
+Before treating draft content as durable, ask the human to classify important
+claims:
+
+- keep as canonical
+- soften into guidance
+- reject as accidental or legacy
+- move to scratch notes
+- restate at a broader or narrower altitude (add or drop a condition)
+
+## 6. Decide Kinds And Altitude
+
+Two authoring decisions replace any notion of hierarchy:
+
+- **Kind** — declare the kind vocabulary in `glossary.md` and name each node
+  `<kind>.<slug>.md` so its normative weight is clear. The glossary defines what
+  each kind means and how strongly it binds. Use `posture: guard` for
+  review-critical replacement nodes, `posture: wild` for opt-in provocations,
+  and the default steady posture for ordinary truths. Kinds are your choice;
+  Ghost ships no fixed vocabulary.
+- **Altitude** — state a truth at the level it is actually true. Universal → state
+  it plainly. Narrower → name the situation that activates it, in the prose. Never
+  file a truth by destination (`for-emails.md`); the model reads the condition and
+  decides when it applies.
+
+## 7. Validate And Ratify
+
+```bash
+ghost validate .ghost
+```
+
+`validate` checks artifact shape, per-node validity, and that each node's kind
+prefix is a declared glossary kind (undeclared → warning with a "did you
+mean" suggestion). Use ordinary Git review as the approval boundary: uncommitted
+edits are drafts; checked-in nodes are canonical.
+
+## Never
+
+- Never derive brand truth from repo code alone; what the codebase repeats may
+  be legacy, not stance. Use repo paths as `materials` only after the prose
+  truth has been curated.
+- Never draft a node the human neither said nor showed; that is invention
+  wearing the brand's clothes.
+- Never treat a brand doc, an artifact, or repetition frequency as brand
+  authority; the human ratifies what is intentional.
+- Never invent a hierarchy, inheritance, or edges — the package is flat.
+- Never file a truth by destination; state its condition in the prose.

package/dist/skill-bundle/references/blocks.md

@@ -0,0 +1,180 @@
+---
+name: blocks
+description: Author block and material nodes so an agent can match a fingerprint's stance to concrete building blocks.
+handoffs:
+  - label: List the node menu
+    command: ghost gather
+    prompt: What materials does this fingerprint document, and what is absent?
+---
+
+# Recipe: Author Block And Material Nodes
+
+**Goal:** when you are documenting the **materials** a brand draws from — its
+building blocks, assets, and reusable pieces — write that prose so an agent can
+translate the fingerprint's stance into concrete building blocks without the
+fingerprint ever naming a component.
+
+This is opinionated method, not new schema. **"Block node" is shorthand in this
+recipe, not a Ghost concept**: it means any node whose truth is a reusable
+building block, whatever kind the author's glossary declares for it (`block`,
+`asset`, `pattern`, …). A block node is a node like any other: a markdown file
+with a `description` and a prose body, named `<kind>.<slug>.md` (or a bare
+slug). See [capture.md](capture.md) for the node shape. Block prose can be one
+paragraph inside a broader node, or split across many nodes, one per block,
+whatever keeps each node purpose-coherent.
+
+## Where it sits
+
+A fingerprint declares stance. Block and material nodes ground that stance in
+concrete materials — they are what makes a node **concrete** in gather, pull
+ordering, and review matching. A realizing agent **reads** them and matches
+against them. Strip every block node and the fingerprint is still valid — it
+just gives the agent less to draw on, and prose-only steering is weak steering.
+The agent does the matching.
+
+## Concreteness is the grounding dial
+
+This trade belongs to the author:
+
+- **Abstract materials** (principles, arrangement, no concrete components) →
+  leaves the agent more room, grounds it less.
+- **Concrete materials** (named building blocks) → strongly grounds the agent in
+  the materials it should reach for, at the cost of that room.
+
+Neither is correct. A concrete block node is a deliberate trade, not a leak.
+
+## Tier first: not everything earns a node
+
+- **Primitives** (button, input, badge, avatar, spinner…) get **no prose body**
+  when the generic form serves. They are shared vocabulary, not stance. If you
+  record one at all, give it only a `description` so `gather` can surface it;
+  the absence of a body is the signal that training priors are acceptable here.
+  When a primitive is itself brand-distinctive (a button whose shape, weight, or
+  focus treatment is a recognizable brand move), its *divergence from the
+  generic form* is a truth worth a body: state what differs and why, not the
+  full API.
+- **Anything that encodes a user moment** (confirmation, plan, task, tool,
+  reasoning, sources…) earns **one short prose body**. This is what the method is
+  for.
+- The **composer middle** (card, table, form, sidebar…) is a call to weigh. Give
+  it a body when its arrangement carries a stance worth matching.
+
+If a primitive ever seems to need stance guidance, that is a signal it is doing
+a composer's job. Promote the pattern into a node; do not write a body on the
+primitive.
+
+## The shape of a block node
+
+A node like any other. Frontmatter carries `description` (the retrieval payload —
+write one on every block worth matching); the body is prose the agent reasons
+over.
+
+**Body:** one short paragraph in a consistent rhythm, *for / reach when / not
+when (use X instead) / never*:
+
+- **for**: the user need or moment it exists for, framed as the problem, not the
+  widget.
+- **reach when**: phrased as the user's *first question* ("who/what is this?" vs
+  "what's happening / what do I do?"). First-question framing forces a clean pick
+  between overlapping blocks.
+- **not when**: name the rival node to reach for instead, by its id. This is what
+  makes the set navigable — since the package is flat with no edges, the prose
+  "not when" *is* the see-also link. Point at the other node's id in the text.
+- **never**: what it must not be conscripted into, so the agent does not stretch
+  it to fit.
+
+Keep props, markup, and API reference out; the body documents purpose, and the
+implementation beneath it is swappable. Explicit values are the exception when
+the value itself is the brand truth — an exact color, a specific corner radius —
+not a swappable implementation detail.
+
+## How a match runs
+
+The agent reads the fingerprint's stance, `gather`s the menu, ranks candidate
+block nodes by description, separates near-neighbors on *not when* and
+*never*, and assembles. The realizing surface authors the chosen blocks in its
+medium. The fingerprint never named a component; the agent bridged via documented
+purpose.
+
+## Curation rule
+
+A block earns its node when its purpose is **distinguishable** from every
+other's. Two blocks may overlap heavily and still be distinct *as long as their
+"reach when" answers a different first question*. If they answer the same first
+question, they are one node, not two.
+
+## Worked example
+
+These examples use a `block` kind. The starter glossary does not ship one, so
+declare it (or reuse a declared kind such as `pattern`) before copying the
+filenames:
+
+```yaml
+kinds:
+  - name: block
+    purpose: a reusable building block matched by purpose, not named by component
+```
+
+`block.confirmation.md` (kind `block`, slug `confirmation`):
+
+```markdown
+---
+description: Gate a consequential action behind explicit user approval.
+---
+Gates a tool action behind explicit user approval. Reach for it when the user's
+first question is "do I allow this?", when a consequential action needs a human
+decision before it runs. Not when the action is already complete (that's
+`block.tool`) or when no decision is required. It is never a status display;
+with no decision to make, it only manufactures friction.
+```
+
+`block.table.md`:
+
+```markdown
+---
+description: Present many records across shared, comparable columns.
+---
+Presents many records across shared, comparable columns. Reach for it when the
+user's first question is "how do these compare across the same attributes?" Not
+when each item needs rich, non-uniform presentation (use repeated `block.card`)
+or there is a single subject rather than a collection. It is never a single
+record's detail view.
+```
+
+`block.button.md`:
+
+```markdown
+---
+description: A primitive action trigger.
+---
+```
+
+(A primitive the generic form serves: a `description` so `gather` can surface
+it, no body. If this brand's button were itself a recognizable brand move, its
+divergence from the generic form would earn a short body.)
+
+## Materials: bundle brand-owned materials, reference implementations
+
+Use the rule of thumb literally. Bundle brand-owned materials: brand-owned artifacts that
+should travel with the fingerprint and survive export or refactors — tokens.css,
+motion.json, logo.svg, type materials. Reference implementations: living app
+code, components, stories, or tests whose home is still the product repo. The
+`materials` list locates both; the prose says what the material proves.
+
+## Reuse vs. free-compose
+
+Do not pin a block by prop or markup shape. Document the *purpose* and any
+*guarantees* a block must hold (an action routes through a declared tool, a
+control is keyboard-reachable). Let the realizing agent author the form. Pinning
+prop APIs re-imports implementation opinion and creates a mirror to maintain.
+
+## Never
+
+- Never write a prose body on a primitive the generic form serves; the absence
+  of a body is the signal. A brand-distinctive primitive earns a body for its
+  divergence, never for its API.
+- Never put props, markup, or API reference in a block body; explicit
+  values belong only when the value itself is the brand truth.
+- Never let the fingerprint reference the realizing surface; blocks are read,
+  not addressed.
+- Never split two blocks that answer the same first question; that is one node.

package/dist/skill-bundle/references/brief.md

@@ -0,0 +1,49 @@
+---
+name: brief
+description: Build a compact pre-generation packet from pulled Ghost truths.
+---
+
+# Recipe: Brief Work From Ghost Fingerprint
+
+A brief is an ephemeral steering packet for the generating pass. It is not a new
+schema and is never written back into `.ghost/`.
+
+1. Run `ghost gather <ask> --format json` and select against descriptions.
+2. Pull a small set: **3–5 nodes is normal; 10 is a bad selection** unless the
+   task is unusually broad. Always include `index` unless already read this
+   session.
+3. Prefer concrete nodes: `materials`, substantial fenced examples, or a
+   `## Skeleton`. If there is **no concrete material for this surface**, the
+   readiness ceiling is **Yellow**.
+4. Keep provisional reasoning visibly separate from Ghost-backed claims.
+
+## The packet: five sections only
+
+Return this shape:
+
+```markdown
+## Grounded in
+- `node.id` — why it was selected
+
+## Non-negotiables
+- ≤5 lines, each cited to a node id
+
+## Materials inline
+- concrete locators, inlined snippets, inspect-pointers, and what to view/use
+
+## Skeleton
+- matching pulled Skeleton, or "none pulled"
+
+## Silent / provisional
+- what Ghost does not cover and what local evidence carries
+```
+
+Rules:
+
+- Do not add sections for every kind. Sections dilute instruction weight.
+- Treat `ghost pull` ordering as signal: stance first, concrete material next,
+  prose rules, guards late, Skeletons dead last.
+- If a pulled Skeleton matches the surface, begin the artifact from it verbatim
+  before filling.
+- Guards (`posture: guard`) are review-critical anti-goals: state the positive
+  replacement, not just the rejected pattern.