@design-intelligence/ghost 0.28.0 → 0.29.0

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

@@ -1,187 +0,0 @@
----
-name: authoring-scenarios
-description: Choose the right human-agent workflow for authoring ghost packages.
-handoffs:
-  - label: Validate the package
-    command: ghost validate --format json
-    prompt: Classify this package's authoring scenario and confirm the package validates.
----
-
-# Recipe: Collaborative Package Authoring
-
-**Goal:** help a human and agent co-author durable brand guidance through
-conversation — without laundering what a codebase happens to do into what the
-brand means.
-
-The ghost package 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 guidance on its own.
-
-## 1. Start With One Repeated Decision
-
-Do not try to capture 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 decision as a node first. One well-grounded node beats an
-empty catalog; the package 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 ghost package | 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. Treat the document as evidence: 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 shared guidance broad; scope divergence with conditions. |
-| Monorepo or product suite | One contract per package. |
-
-When supplied artifacts are the starting point or must be reconciled with an
-existing package, follow [distill.md](distill.md).
-
-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
-guidance:
-
-- 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 guidance is universal, and which guidance holds only 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 guidance 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 anti-goal 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 carrying purpose-coherent prose guidance with
-a one-line `context`, named `<kind>.<slug>.md` (or a bare slug when no kind is present). Ask three questions of each node 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 guidance plainly; give
-narrower guidance a **condition** in the prose — the situation they apply in,
-never a destination. Label uncertain reasoning as provisional. Prefer a few
-focused guidance 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 the 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. Kinds are your choice;
-  ghost ships no fixed vocabulary.
-- **Altitude** — state guidance at the level where it applies. Universal → state
-  it plainly. Narrower → name the situation that activates it, in the prose. Never
-  file a node 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.
-
-## Shapes Of A Useful Node
-
-The shapes below teach what steering prose looks like when it works. The
-examples use **Morrow Ledger**, a fictional bookkeeping product — teaching
-fiction for this recipe only, never content for a real corpus. Each shape is a
-pattern to imitate with the human's real guidance.
-
-- **Stance as forced choices.** Not adjectives — decisions under pressure:
-  "Clarity beats momentum: write '3 invoices are 14+ days late', not 'Cash
-  flow needs attention.'" A stance earns its place when it rejects a plausible
-  wrong answer.
-- **Composition floor.** Hard invariants with numbers, holding unless a
-  narrower condition says otherwise: "Maximum three figures above the fold —
-  if there are four, demote one into details instead of shrinking type."
-- **Anti-goal as not-X-instead-Y.** The rejected default *and* its committed
-  replacement: "Not 'Revenue is up 24% 🎉' — instead 'July receipts are $4,820
-  higher than June; 2 invoices explain most of the change.'" A bare ban prunes
-  one path; the replacement commits another.
-- **Pattern as bound/open.** Say what is decided and what remains free:
-  "Bound: status line first, one sentence, ≤11 words; one primary next step
-  last. Open: evidence may be a table row or a two-item list." All bound is a
-  template; nothing bound is vibes.
-- **Annotated exemplar.** A concrete reference plus what it is normative for
-  and what is incidental: "Copy the square edge, measured evidence, and action
-  cost. Do not copy the exact amounts or dates." An unannotated exemplar
-  teaches its accidents as brand.
-- **Material inventory.** `materials` locates; prose explains meaning:
-  "`src/styles/tokens.css` should define the ink, ledger, amber, and paper
-  colors." Never duplicate API docs unless the API itself is the brand guidance.
-- **Decision trace.** A worked tradeoff with the reversal condition: "We chose
-  visible evidence over shorter surfaces… Reverses when the evidence would
-  expose sensitive third-party details — then show the count only." Models
-  imitate reasoning as well as outputs.
-
-State the silence posture on the manifest-declared cover, which `gather`
-inlines for every task: when the package is silent, proceed provisionally
-from local conventions only when safe, and ask before brand-defining,
-irreversible, legal, privacy-sensitive, or high-risk choices.
-
-## Never
-
-- Never derive brand guidance from repo code alone; what the codebase repeats may
-  be legacy, not stance. Use repo paths as `materials` only after the prose
-  guidance 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 node by destination; state its condition in the prose.

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

@@ -1,179 +0,0 @@
----
-name: blocks
-description: Author block and material nodes so an agent can match a ghost package's stance to concrete building blocks.
-handoffs:
-  - label: List the node menu
-    command: ghost gather
-    prompt: What materials does this package 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 package's stance into concrete building blocks without the
-guidance 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 guidance 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 `context` 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 ghost package declares stance. Block and material nodes ground that stance in
-concrete material: materials, substantial fenced examples, or Skeletons. A
-realizing agent **reads** them and matches against them. Strip every block node
-and the package 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 `context` 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 decision worth a node: 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 prose 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 `context`, the direct applicability
-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 guidance — an exact color, a specific corner radius —
-not a swappable implementation detail.
-
-## How a match runs
-
-The agent reads the package's stance, `gather`s the menu, pulls block nodes
-whose contexts apply, separates near-neighbors on *not when* and *never*,
-and assembles. The realizing surface authors the chosen blocks in its medium.
-The guidance 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
----
-context: A consequential action needs explicit user approval before it runs.
----
-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
----
-context: Many records need comparison across shared 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
----
-context: A person can trigger an action.
----
-```
-
-(A primitive the generic form serves: a `context` 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 package 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 guidance.
-- Never let the package reference the realizing surface; blocks are read,
-  not addressed.
-- Never split two blocks that answer the same first question; that is one node.