65 added, 68 removed. Audit A to A.
---
name: kelly-brand
- description: "Brand-narrative single source of truth (TALE: Trace/Architect/Land/Evaluate) with a local App-in-Skill workbench. The agent drafts positioning, the message house of value pillars, the story bank, evidence-backed proof points, and vocabulary/tone guardrails; the human curates which drafts become the CANONICAL narrative; a drift monitor flags off-brand usage across channels. Use when the user invokes $kelly-brand or /kelly-brand, mentions brand narrative, brand messaging, positioning, message house, value pillars, story bank, proof points, tone/vocabulary guardrails, narrative quality (NQS), brand drift, or wants a single source of truth for what the brand says."
+ description: "Brand-narrative single source of truth (Busabase App-in-Skill) built on the TALE discipline — Trace / Architect / Land / Evaluate. The agent drafts positioning, the message house of value pillars, the story bank, evidence-backed proof points, and vocabulary/tone guardrails; the human curates which drafts become the CANONICAL narrative; a drift monitor flags off-brand usage across channels. Use when the user invokes $kelly-brand or /kelly-brand, mentions brand narrative, brand messaging, positioning, message house, value pillars, story bank, proof points, tone/vocabulary guardrails, narrative quality (NQS), brand drift, or wants a single source of truth for what the brand says."
---
# Kelly Brand
## Overview
- Use this skill as the operator for a brand's **narrative single source of truth**. It keeps a file-backed App-in-Skill workbench over the whole message house — positioning, value pillars, the story bank, evidence-backed proof points, and vocabulary/tone guardrails — plus a drift monitor that flags off-brand usage across channels. The agent drafts; the human curates which drafts are **adopted as the canonical narrative**; the skill records those adoptions and can export the canonical narrative for downstream use.
+ Kelly Brand is a Busabase Cloud App-in-Skill. Its canonical product surface
+ is the AirApp in Busabase, not a separate local-data product. The same Hono
+ source supports an explicitly requested local preview with OAuth connection
+ bootstrap. Use this skill as the operator for a brand's **narrative single
+ source of truth**: it keeps a dashboard over the whole message house —
+ positioning, value pillars, the story bank, evidence-backed proof points,
+ and vocabulary/tone guardrails — plus a drift monitor that flags off-brand
+ usage across channels. The agent drafts; the human curates which drafts are
+ **adopted as the canonical narrative**; the skill records those adoptions
+ and can export the canonical narrative for downstream use.
Everything is organized by Aaron's **TALE** discipline — **Trace → Architect → Land → Evaluate** — and every narrative asset carries the TALE `phase` and the `sub_skill` that produced it.
- Default interaction mode: App UI. Unless the user explicitly asks for chat-only handling, check onboarding/config, refresh or regenerate the local brand snapshot, start/reuse the local app with `app/start.sh`, and give the actual local URL. Use chat-only mode only when the user says "纯聊天", "chat only", "不要打开 UI", or similar; in that mode present numbered assets (`#1`, `#2`) and take verdicts in the conversation.
+ Default behavior is AirApp-first. Unless the user explicitly asks only for
+ explanation, update Busabase directly and give the user the clickable AirApp
+ URL. Start localhost only when local preview/debugging is explicitly
+ requested; it uses the same Busabase resources and never offers another data
+ provider. Use chat-only mode only when the user says "纯聊天", "chat only", "不要打开 UI", or similar; in that mode present numbered assets (`#1`, `#2`) and take verdicts in the conversation.
- Design philosophy follows the App-in-Skill specification paper: <https://mr-kelly.github.io/research/app-in-skill-specification-for-pairing-agent-skills-with-a-local-companion-ui.pdf>. The agent owns drafting and any external reads/writes; the app reads and writes local files only; the file handoff is the contract; the human's clicks are reserved for judgment — chiefly **adopting a draft as canonical**.
+ ## Mandatory Dependencies
+ 1. Read and follow `$kelly-app-skill-creator` for product behavior, visual
+ quality, responsive layout, and the complete canonical `app/` artifact.
+ 2. Read and follow `$busabase` for connection, target Space, node discovery,
+ ChangeRequests, review, and merge behavior.
+ 3. Read and follow `$busabase-app-creator` for resource modeling, AirApp
+ runtime limits, security, validation, and deployment.
+
+ If a dependency is unavailable, preserve this skill's local artifact and
+ product contracts, stop before the unavailable Busabase operation, and report
+ the exact missing dependency. Do not invent a second data backend.
+
## App UI Screenshots
<table>
<tr>
<td width="50%"><img src="assets/screenshots/overview.webp" alt="Kelly Brand message house"></td>
<td width="50%"><img src="assets/screenshots/drift.webp" alt="Kelly Brand drift alerts"></td>
</tr>
<tr>
<td><strong>Overview</strong><br>The message house — positioning, value pillars, overall NQS, and the drift-alert count.</td>
<td><strong>Drift</strong><br>Cross-channel off-brand alerts — offending usage versus the canonical guardrail.</td>
</tr>
<tr>
<td width="50%"><img src="assets/screenshots/narrative.webp" alt="Kelly Brand narrative"></td>
<td width="50%"><img src="assets/screenshots/stories.webp" alt="Kelly Brand story bank"></td>
</tr>
<tr>
<td><strong>Narrative</strong><br>Message pillars and vocabulary guardrails, canonical versus draft.</td>
<td><strong>Story bank</strong><br>Customer stories and evidence-backed proof points.</td>
</tr>
</table>
- ## Boundary
-
- - The skill may read sources the user provides (positioning inputs, existing site/deck copy, channel exports), draft narrative assets, score them, validate schemas, and write local handoff files.
- - The app reads and writes local files only. It must never publish copy, call channel APIs, or change any remote system.
- - Adopting an asset to the canonical narrative, exporting the narrative, and resolving a drift alert are approval-required and skill-executed **after** the human's verdict. `scripts/execute_decisions.ts` only records operations in `execution_report.json`; it performs no publishing itself.
- - Treat unverified claims, regulated claims, and legal/compliance wording as approval-required. A proof point with no named source must be `blocked`, not shipped.
-
## The TALE Framework
The 4 phases are both an item facet (`phase`) and the shape of the work. The 16 sub-skills below are the capability taxonomy — each drafted asset names the sub-skill that produced it in `sub_skill`.
### Trace — map the ground truth
- **narrative-baseline-mapper** — capture the brand's current story as it actually reads today (origin story, status quo).
- **category-narrative-mapper** — map how the category talks so the brand can stand apart from it.
- **audience-belief-mapper** — surface what the audience already believes, needs, and objects to.
- **positioning-truth-tracer** — trace the defensible truths the positioning can stand on.
### Architect — design the message system
- **strategic-narrative-designer** — write the core **positioning statement** (the roof of the house).
- **message-system-architect** — build the **value pillars** that hold the positioning up.
- **brand-language-codifier** — codify the **vocabulary** (say-this/not-that) and **guardrails** (banned/regulated language).
- **story-bank-builder** — assemble the **story bank** of reusable customer and brand stories.
### Land — make it usable across channels
- **narrative-cascade-planner** — plan how the narrative cascades to each channel.
- **pitch-narrative-builder** — shape the narrative into a pitch.
- **narrative-enablement-kit** — package the narrative so teams can actually use it.
- **proof-point-packager** — package **proof points** with their evidence (a named source and stat).
### Evaluate — test, monitor, gate
- **message-test-designer** — design tests for whether messages land.
- **narrative-resonance-monitor** — monitor how the narrative resonates.
- **narrative-drift-monitor** — flag off-brand / misaligned usage across channels (the Drift view).
- **narrative-quality-auditor ⛩** — the **gate**: score narrative quality (NQS 0–100) via the TALE framework and output **SHIP / FIX / BLOCK**. This gate is prominent on the overview and on every asset.
## Narrative Quality Score (NQS) gate
- The `narrative-quality-auditor ⛩` scores each asset and the narrative as a whole:
+ The `narrative-quality-auditor ⛩` scores each asset and writes its own `SHIP`/`FIX`/`BLOCK` judgment as the item's `nqs-gate` — this is the auditor's call, not a numeric formula, so it is stored as-is. The **overall** NQS shown on the overview is a pure aggregate computed client-side from every scored item (mean of `nqs-score`, `Math.round`) with a purely numeric gate:
- **SHIP** (score ≥ 80) — ready to adopt as canonical.
- **FIX** (55–79) — usable but flagged for a concrete revision.
- **BLOCK** (< 55, or a proof point missing its source) — must not be published or adopted until fixed.
- The overview shows the **overall NQS** with its gate, and each asset card shows its own NQS chip. A `BLOCK` verdict from the auditor should be mirrored by a `blocked` status on the item until resolved.
+ A `BLOCK` verdict from the auditor should be mirrored by a `blocked` status on the item until resolved.
## First Run And Onboarding
- On invocation, check `app/.data/onboarding.json` and private config readiness. If onboarding is absent/incomplete, guide setup before doing real narrative work.
-
- Private config priority:
-
- 1. `KELLY_BRAND_CONFIG=/absolute/path/to/config.json`
- 2. `skills/kelly-brand/config.local.json`
- 3. `~/.config/kelly-brand/config.json`
- 4. `skills/kelly-brand/config.example.json` as template only
+ On invocation, check the `kelly-brand-profile` settings row for readiness.
+ If it is absent, guide setup before doing real narrative work.
- Env priority:
+ Ask for non-secret setup details only: brand profile (name, category, audience, mission), the positioning inputs (for whom / who need / our brand is / that / unlike / because), channels monitored for drift and how each is reached, tone/style and reading level, official URLs, and the risk policy (banned phrases, regulated claims). Never ask the user to paste secret values into chat. Busabase authentication is ambient inside the deployed AirApp.
- 1. Existing environment variables
- 2. `KELLY_BRAND_ENV_FILE=/absolute/path/to/.env`
- 3. Repository root `.env`
- 4. `skills/kelly-brand/.env.local`
- 5. `~/.config/kelly-brand/.env`
+ ## Busabase Resources
- Ask for non-secret setup details only: brand profile (name, category, audience, mission), the positioning inputs (for whom / who need / our brand is / that / unlike / because), channels monitored for drift and how each is reached, tone/style and reading level, official URLs, and the risk policy (banned phrases, regulated claims). Never ask the user to paste secrets into chat; channel source URLs/tokens belong only in local env files, referenced by `source_url_env`/`token_env`.
+ Three Bases under one application Folder (`kelly-brand`), declared in
+ `app/app/js/config.js` and `app/resource-map.json`:
- When setup is complete and the user confirms, write `app/.data/onboarding.json`:
+ - `items`: every narrative asset under review — positioning, message pillars, story bank, proof points, vocabulary, and guardrails — with `type`, TALE `phase`, `sub_skill`, editable `draft`, NQS (`nqs-score`/`nqs-gate`), evidence (`evidence-source`/`evidence-stat`/`evidence-url`, proof points only), `risk`, workflow `status`, and the human verdict fields `decision-note` / `decided-at`.
+ - `drift_alerts`: cross-channel off-brand usage the drift monitor flagged — offending usage vs. canonical guidance, severity, and the same verdict fields.
+ - `settings`: one row per `kind` — `kelly-brand-profile` (brand profile, style/tone, official URLs, risk policy, monitored channels) and `kelly-brand-lock`.
- ```json
- {
- "completed": true,
- "completed_at": "ISO timestamp",
- "config_version": "1"
- }
- ```
+ Resources provision lazily through an idempotent Busabase ChangeRequest the
+ first time the app runs in a Space; see `references/brand-schema.md` for
+ exact field shapes. The **overall NQS** and every metric on the overview are
+ computed client-side from the `items`/`drift_alerts` Bases on every read —
+ they are never stored.
## Local App
- Start the workbench with:
-
- ```bash
- skills/kelly-brand/app/start.sh
- ```
-
- The app uses local HTTP on `127.0.0.1`, preferring port **3230** through **3999**, or `KELLY_BRAND_UI_PORT` when set. The launcher reuses a running instance only when `/api/state` proves it is the same app (`app: "kelly-brand"`).
+ Default behavior is AirApp-first — give the user the clickable AirApp URL.
+ Start `pnpm --dir app dev` only when local preview/debugging is explicitly
+ requested.
Required app views (hash routes):
- - `#/overview` — **the message house**. The canonical/draft positioning statement at the top, the value pillars, the overall NQS with its gate, canonical vs needs-review counts, and the open drift-alert count.
+ - `#/overview` — **the message house**. The canonical/draft positioning statement at the top, the value pillars, the overall Narrative Quality Score (NQS) with its gate, canonical vs needs-review counts, and the open drift-alert count.
- `#/narrative` — message pillars plus vocabulary/guardrails, canonical vs draft, each editable with its NQS and TALE phase. Adopt / Request changes / Block per asset.
- `#/stories` — the story bank and the proof points with their evidence (source + stat). A proof point missing evidence is blocked.
- `#/drift` — off-brand/misalignment alerts the drift monitor flagged, each showing the offending usage vs the canonical guardrail, with Approve fix / Dismiss.
- - `#/settings` — sanitized config summary: brand profile, tone/reading level, banned/regulated language, official URLs, monitored channels with source-readiness booleans, data provider, and onboarding state. Never expose secret values.
+ - `#/settings` — sanitized config summary: brand profile, tone/reading level, banned/regulated language, official URLs, monitored channels, data provider, and onboarding state. Never expose secret values.
The left sidebar keeps the fixed **workflow filters** (`All`, `Needs Review`, `Canonical` (= approved), `Done`, `Blocked`) as primary nav alongside the views. "Canonical" is the UI label for the `approved` state.
Demo mode:
- `?demo=1` opens a deterministic mock brand (invented "Fernpath") for documentation and screenshots.
- `?demo=overview`, `?demo=narrative`, `?demo=stories`, `?demo=drift`, and `?demo=settings` select named scenes.
- `lang=en` or `lang=zh` forces UI chrome language for screenshots.
- - Demo API responses never read or write files under `app/.data/` or any private config.
+ - Demo mode never reads or writes Busabase.
UI language: support English and Chinese chrome with `Auto` default. Keep the brand's own narrative content (positioning, pillars, stories) in its original language.
- ## File Contract
-
- Read `references/brand-schema.md` before editing the app, scripts, or any generated brand JSON.
-
- Primary local files:
+ ## Review Workflow
- - `app/.data/brand_snapshot.json`: normalized narrative snapshot (positioning, items, drift alerts, metrics) generated by the skill/scripts.
- - `app/.data/decisions.json`: user verdicts and review notes keyed by `item_id` or `alert_id`, written by the app.
- - `app/.data/agent_tasks.json`: queued agent work — assets in `changes_requested` with the user's comment. The skill polls this to pick up revisions.
- - `app/.data/execution_report.json`: latest operations written by `scripts/execute_decisions.ts`.
- - `app/.data/onboarding.json`: onboarding completion marker.
- - `app/.data/agent.lock`: temporary lock while the skill is generating or executing. The app rejects decision writes while it exists.
- - `config.local.json`: private brand configuration, ignored by git.
+ Read `references/brand-schema.md` before editing the app or its domain logic.
- Use `scripts/validate_ui_schema.ts` before relying on a snapshot in the UI. The app shows an empty setup state when no snapshot exists.
+ A human verdict (`approve` / `request_changes` / `block` / `revise` for a
+ narrative item; `resolve_drift` / `dismiss_drift` for a drift alert) writes
+ the new `status` plus `decision-note` / `decided-at` directly onto the
+ record through `busabase-sdk`. From a standalone local preview the write
+ merges immediately (trusted operator); from the deployed AirApp it creates a
+ pending ChangeRequest for the trusted process to merge.
## Normal Workflow
1. Detect mode. Default to App UI.
- 2. Load private config through the config helpers. If only `config.example.json` exists, enter onboarding.
- 3. When the user feeds material (positioning inputs, existing copy, channel exports): acquire `app/.data/agent.lock`, update `brand_snapshot.json` — draft/upsert narrative assets by stable `item_id` across the six `type`s, tag each with its TALE `phase` and `sub_skill`, run the **narrative-quality-auditor** to set each `nqs` and the overall NQS, run the **narrative-drift-monitor** over monitored channels to (re)populate `drift_alerts`, recompute metrics — validate with `scripts/validate_ui_schema.ts`, then release the lock.
- 4. Start/reuse the UI and report the URL so the user can review the message house, the story bank, and the drift alerts.
- 5. Poll `app/.data/agent_tasks.json` for `changes_requested` items. Re-draft each per the user's comment, re-score it, set it back to `needs_review`, and clear the task.
- 6. On "adopt" / "promote approved narrative": re-read `decisions.json`, re-check the lock, and run `scripts/execute_decisions.ts --apply` to record `promote_to_canonical` (registry `narrative`) and `resolve_drift` operations in `execution_report.json`. Then, only for approved assets, update the canonical narrative and — if asked — `export_narrative` to a markdown file. Mark each `done` in the snapshot afterwards.
- 7. Never adopt or export an asset without an explicit `approve` verdict. Never let a `BLOCK`/blocked proof point (no named source) reach any channel.
+ 2. When the user feeds material (positioning inputs, existing copy, channel exports): write narrative items to Busabase — draft/upsert by stable `item_id` across the six `type`s, tag each with its TALE `phase` and `sub_skill`, run the **narrative-quality-auditor** to set each item's `nqs-score`/`nqs-gate`, and run the **narrative-drift-monitor** over monitored channels to (re)populate `drift_alerts`. The overview's overall NQS and every count recompute automatically on every read.
+ 3. Give the user the AirApp URL (or local preview URL) to review the message house, the story bank, and the drift alerts.
+ 4. For an item moved to `changes_requested`, re-draft it per the review comment and write it back to `needs_review`.
+ 5. On "adopt" / "promote approved narrative": run `node scripts/execute_decisions.mjs --apply` to re-read approved items from Busabase and mark them `done`. Then, only for those promoted assets, update the canonical narrative and — if asked — `export_narrative` to a markdown file.
+ 6. Never adopt or export an asset without an explicit `approve` verdict, and never re-promote an item already `done`. Never let a `BLOCK`/blocked proof point (no named source) reach any channel.
## Safety Defaults
- Treat unverified claims, regulated claims (`organic`, `#1`, `guaranteed`, `certified`, `carbon-neutral`), and legal/compliance wording as approval-required. Every public number must cite a named source.
- A proof point without evidence is `blocked` by the NQS gate; do not adopt or publish it.
- - Store only the narrative content needed for review; keep raw channel exports out of the snapshot.
- - Redact tokens and credential-like strings from logs, reports, and UI state; expose only boolean source-readiness for configured env vars.
+ - Store only the narrative content needed for review; keep raw channel exports out of Busabase.
+ - Redact tokens and credential-like strings from logs, reports, and UI state; expose only boolean source-readiness for configured channels.
- Keep stable ids (`item_id`, `alert_id`) so repeated updates and executions are idempotent.
- - If decisions and the snapshot disagree (missing item, stale ref), stop and regenerate rather than guessing.