Pack Author

---
name: pack-author
description: Author a new ccsidekick character pack end-to-end - source the figure, pick a theme, write 620 voice lines and 25 spinner verbs, then ship through lint, a generated README, and an autonomous review. Use when creating, building, or scaffolding a ccsidekick character pack.
---

# Authoring a ccsidekick character pack

A pack is data: one `pack.json` and a `package.json`, never executed code. The engine reads it;
nothing in a pack runs. All constraints are enforced by `pack:lint`. This skill drives the authoring
loop to a hard finish.

## Prerequisite

The skill scripts run under `bun`. Confirm it is on `PATH` before starting:

```
bun --version
```

Both Claude Code and Codex CLIs spawn a shell, but `bun` is not guaranteed in a Codex environment.
If it is absent, none of the skill scripts will run.

## Terminal state

The pack is done when all four conditions hold:

1. `bun run pack:lint packages/packs/<name>` exits 0: schema guard, placeholder gate, cross-cell
   gate, pool counts, 66-column width, spinner-verb floor, near-duplicate threshold, legibility, and
   `package.json` completeness (name, `files` covering the README and assets,
   `repository.directory`, author).
2. `bun test packages/core/src/packs/registry.test.ts` passes.
3. Every user-approval gate in the stages below is cleared.
4. The user has approved the final `pack.json`.

Lint passing is necessary, not sufficient. It passes on placeholder text, so a green lint does not
certify voice or art. User approval (gates 3 and 4) is the binding quality check.

## Stage 1: Figure

The figure is a single static array of at most **9 rows × 25 columns**. Mood changes engine-applied
color only: no per-mood art, no glyph shifts.

**1. Scaffold the pack first** (skip if the directory already exists):

```
bun .claude/skills/pack-author/scripts/scaffold.ts <name> --display "<DisplayName>" --emblem "<glyph>"
```

Creates `packages/packs/<name>/` with a skeleton `pack.json` (every pool keyed, one unique
placeholder per leaf cell), a `package.json`, a `README.md`, and a `REVIEW.md`. Registers `<name>`
in `PACKS` and links it as a `workspace:*` runtime dependency of `packages/core` (every pack ships
bundled), both idempotently; re-running the scaffold overwrites the skeleton files and leaves an
existing registry entry and dependency untouched.

**2. Install the workspace link.** Run `bun install` from the workspace root. The render loader
resolves each pack through `packages/core/node_modules/@ccsidekick/pack-<name>`, which the workspace
only materializes for the declared core dependency the scaffold just added. Skip this and the pack
fails to load at render time: the statusline shot (Stage 7) silently drops the figure and leads with
the chip. This is a one-time step per pack.

**3. Ask the user** whether they have a reference image, a specific ASCII or braille art source, or
want generated candidates.

**4. Generate five candidates.** Art is sourced through tooling, never hand-drawn. **The figure is
ALWAYS braille: every candidate, every pack, no exceptions.** Braille packs four times the vertical
resolution of block or ASCII glyphs into the same 9×25 box, so the figure stays legible at
status-line size; ASCII and block art do not. Do not ship an ASCII or block figure even if it looks
fine in the preview.

- Use the **`ascii-art` skill** with `--style braille` to convert a reference image, then hand-clean
  it: fix ragged rows, thin the density, drop stray glyphs. Set `attribution.artist` and
  `attribution.source` to the image credit. A clean, high-contrast
  **line drawing or bold silhouette** converts far better than a flat-colored render or a
  photograph. A solid-fill vector collapses to a featureless blob, and a photo turns to mush at nine
  rows.
- For braille art, draw from a catalog (emojicombos.com, asciiart.eu). **Pad blank braille cells
  with `⠀` (U+2800), not an ASCII space.** Mixing braille glyphs with ASCII spaces skews alignment
  in most fonts; a uniform braille grid stays aligned. The legibility gate counts both `⠀` and a
  space as empty, so density is the inked glyphs alone.
- Catalog braille sized larger than 9×25 rarely survives a down-rescale: shrinking a detailed
  line drawing fragments its strokes, and a near-solid fill flattens to a block. Prefer a source
  that is already at box size, or re-source from a clean line-drawing image.

Fit each candidate to ≤9×25.

**5. Run the figure-options preview.** Write the candidates to
`packages/packs/<name>/figure-candidates.json` — an array of `{ name, rows }` objects — then pass
that file path:

```
bun .claude/skills/pack-author/scripts/figure-options.ts <packDir> \
  --candidates packages/packs/<name>/figure-candidates.json
```

This writes `.author/figures.html`. Open it in a browser. The user picks a candidate or asks for a
tweak. Delete `figure-candidates.json` once a figure is chosen.

**6. Ingest the figure.** Write the chosen art into `.author/figure.txt` (the user may hand-edit
it), then run:

```
bun .claude/skills/pack-author/scripts/figure-ingest.ts <packDir>
```

This writes the `art` array into `pack.json` and runs `--schema-only` lint to confirm the figure
clears the box and legibility gate.

**7. Attribution.** Fill `attribution.artist` and `attribution.source`. Both are required; lint
fails on either being empty.

**Gate:** `bun run pack:lint --schema-only packages/packs/<name>` exits 0.

## Stage 2: Emblem

Present four emblem candidates drawn from the character's visual vocabulary, plus a custom option.
Write the chosen glyph into `pack.json` `emblem`.

**Gate:** User confirms the emblem.

## Stage 3: Theme

Every pack ships a `theme` block in `pack.json`, registering it as a selectable palette under its
own name. Four fields:

- **`hues`**: 4 or 5 xterm-256 indices. Paints the statusline as solid bands and the figure as a
  diagonal shimmer gradient.
- **`comment`**: 2 or 3 xterm-256 indices for the character-line gradient.
- **`signals`**: `nominal` (green-family, HSV 70° to 165°), `caution` (amber-family, 20° to 55°),
  `critical` (red-family, ≤15° or ≥345°). Shade a signal color to fit the character; do not invert
  its meaning.
- **`separator`**: one index for `│` and `⋯` dividers.

All indices must be in `17..231` with chroma (max minus min of R, G, B) ≥ 40 and brightness (max of
R, G, B) ≥ 95. No system colors (0 to 16), no greyscale (232 to 255).

**1.** Seed 5–10 candidates from the character's dominant colors. Write them to
`packages/packs/<name>/theme-candidates.json` — an array of objects, each with `name`, `hues`,
`comment`, `signals`, and `separator`.

**2.** Run the preview:

```
bun .claude/skills/pack-author/scripts/theme-options.ts <packDir> \
  --candidates packages/packs/<name>/theme-candidates.json
```

This writes `.author/themes.html`. Open it. The script skips failing candidates and prints a
diagnostic for any index that violates the visibility rule.

**3.** Iterate until the user picks a candidate. Write the chosen `theme` object into `pack.json`.
Delete `theme-candidates.json`.

**Gate:** User has named the chosen theme and it is written into `pack.json`.

## Stage 4: Voice anchor

**1.** Ask the user for voice references: canonical quotes, approved samples, character-defining
moments, and tone constraints. Record everything.

**2.** Propose `tone` (`mild | edgy | offensive`). Config carries no edginess knob; the pack's tone
is the only choice a user gets. Write every line at the pack's tone: there is no separate edgy pool.
Confirm tone after the taste sample in step 4.

**3.** Build `voice-pack.md` from `voice-pack.template.md`: calibration notes (tone, phrasing,
edginess ceiling, taboo subjects) and roughly 50 canonical lines drawn from the user's references.

**4.** Draft about 50 taste-sample lines spanning all five familiarity tiers (
`stranger | acquaintance | friend | partner | legend`), one named stack key per family, and a few
spinner verbs. Keep each line ≤ 66 display columns. Keep failure and limit lines uplifting. The
character emotes; it does not scold.

**5.** Show the samples to the user and confirm `tone`.

**Gate:** User approves the samples. Approval certifies the voice axes and unblocks Stage 5.

## Stage 5: Write the 620

The voice library is exactly **620 lines**, lint-enforced:

| pool                                      | per cell | cells                 | lines |
|-------------------------------------------|----------|-----------------------|-------|
| mood idle                                 | 10       | 5 tiers               | 50    |
| mood busy / happy / struggling / recovery | 5        | 4 × 5 tiers           | 100   |
| greeting                                  | 3        | 5 buckets × 5 tiers   | 75    |
| first contact                             | 3        | 5 tiers               | 15    |
| tier_up / comeback / streak / anniversary | 3        | 4 × 5 tiers           | 60    |
| positive-git                              | 3        | 4 moments × 5 tiers   | 60    |
| easter egg                                | 5        | 5 tiers               | 25    |
| pressure mood                             | 3        | 3 moods               | 9     |
| event reaction                            | 3        | 18 categories         | 54    |
| stack moment                              | 3        | 2 moments × 27 stacks | 162   |
| date/clock egg                            | 10       | flat                  | 10    |

**Rules for every line:**

- ≤ 66 display columns (ANSI-stripped). Longer lines may wrap or truncate.
- No near-duplicates: within any leaf cell, no two lines at token-set Jaccard ≥ 0.80. Two lines that
  share most of their words read as a repeat.
- Stay off the helpful catalog. The engine gives actionable instructions: billing, quota, context,
  git commands. A character line reacts to the moment; it never restates a do-this directive. Do not
  write "add it to `.gitignore`", "unset `ANTHROPIC_API_KEY`", "run `/compact`", or any other action
  command.

**Writing strategy:**

Partition leaf cells into non-overlapping batches.

On Claude: spawn one Sonnet subagent per batch (`model: sonnet`). Hand each writer `voice-pack.md`,
its assigned cells with per-cell counts, `packages/packs/batman/pack.json` as the structural
template, and `bun run pack:lint --status packages/packs/<name>` as the self-check command.

**Writers share one working tree, so forbid tree-wide commands in every writer.** A writer edits
only its assigned `pack.json` cells and runs only `bun run pack:lint` to self-check. It must never
run `bun run format` (Prettier rewrites the whole workspace) or any mutating git command (
`checkout`, `add`, `reset`, `stash`) — a writer that formats and then reverts with `git checkout`
silently wipes every other writer's edits and any staged changeset. Normalize formatting once
yourself, after all batches merge; never inside a writer.

Without subagents: write batches sequentially, same inputs per batch.

After merging all batches, run one cross-cell variety pass: break any joke or phrase that reappears
across cells, which the per-cell gate cannot catch.

**Gate:** `bun run pack:lint packages/packs/<name>` passes the full content gates.

## Stage 6: Spinner verbs

The character rewrites Claude Code's spinner verbs in its own voice.

1. Draft five verbs and show them to the user.
2. After the user confirms the style, write the full set of at least **25** verbs into `pack.json`
   `spinnerVerbs`.

**Gate:** User approves the verb set. Lint enforces the 25-verb floor.

## Stage 7: Ship

**1. README + shot.** Generate the pack's `README.md` and its themed statusline shot (needs a built
render binary):

```
bun run build
bun run pack:readme packages/packs/<name>
```

This writes `README.md`: the non-affiliation disclaimer, a tagline, the statusline preview rendered
in the pack's own theme (`assets/statusline.svg`), the figure as verbatim plain glyphs (no ANSI,
braille blanks preserved), one representative line per pool, and attribution. Do not hand-edit it;
regenerate whenever the figure, theme, or voice changes — including any hand-edit to `pack.json`
`art`, which the user may make directly. `README.md` and `assets/statusline.svg` are generated,
tracked artifacts: after any such change, re-run `bun run pack:readme packages/packs/<name>` (with a
current `bun run build`) so both stay in sync with `pack.json`, then eyeball the shot.

The shot only shows the figure if the pack resolves through its workspace link. If the statusline
leads with a `[name]` chip and no figure appears, the Stage 1 `bun install` never ran (or the core
devDependency is missing); fix the link and regenerate, don't touch the art.

**2. Review.** Dispatch a reviewer subagent (never an author). It records its findings in
`REVIEW.md`. The lint gates content the per-cell way; the reviewer catches what a per-cell check
cannot. Hand it the character's canonical references so it can judge authenticity, and require it to
quote offenders with their pool/tier location. It must check:

- **Figure** legibility and recognizability, and **attribution** filled with a real credit.
- **Voice authenticity:** every line reads as the actual character, not a generic buddy. Flag lines
  that could belong to any pack once the emblem is swapped.
- **Cross-cell templates.** The `stack.*` slow/fail pools are the top offenders: they invite a
  fill-in-the-blank mold (`[subsystem] does X slowly. [detached aphorism].` or
  `[error]. [one-word reaction].`) with a tech noun swapped per cell. Real molds caught in review: a
  shared closer verb (`We'll <fix> it and <retry>.` on 64 of 81 fail lines), a shared shape
  (`[failure]. [Gerund action]!` on most fail lines), and a shared reassurance (every `slow[2]`
  ending "soon it arrives"). Read down a column, not across a row: flag any phrase, joke, image,
  metaphor, or closer that recurs across cells with only trivial variation. The per-cell Jaccard
  gate is blind to it, but a user working across stacks sees the same clever line every time.
- **Signature-reference saturation.** A catchphrase, name, or motif (the character's "elementary",
  "Watson", cards, cheeks, ketchup) reused as a catch-all until it reads as wallpaper. Name a
  sensible ceiling per motif. A **signature syntax** counts too: if the character's gimmick is a
  speech pattern (Yoda's inverted word order), canon applies it selectively; a pack that inverts
  every line reads as parody. Mix the gimmick with plain sentences.
- **Cross-pack contamination.** Every line must be this character's own. Flag any line lifted from
  another pack's canon (Batman's "Why do we fall?" pasted into another figure) or any signature line
  that belongs to a different character within the same franchise (a Naruto pack voicing Kakashi's
  or Rock Lee's catchphrase). When a shared reference is unavoidable, it must sound like this
  character saying it.
- **AI tells** against the house norm: em-dash density (the batman reference uses the em-dash in
  ~1 line across all 620; flag a pack that leans on it in dozens), negative-parallelism closers
  ("X, not Y"; "not defeat, merely data"), the rule of three, hollow motivational filler, and
  doubled-adverb tics.
- **Safety and uplift.** Failure/limit lines must stay uplifting and must never nudge the user
  toward harm or toward prolonging a breakage — no cheering on a dangerous op, no "keep it broken".
  This holds even for a menacing character; the figure emotes, it does not scold or egg the user on.
- **No actionable instructions:** the character reacts to a moment, it never restates a do-this
  directive (no "run /compact", "add to `.gitignore`", "try a shorter query", or any command).

**3. Re-author.** Address every cell the reviewer flags. Re-run `pack:lint` and regenerate the
`README.md` + shot.

**4. Final approval.** Show the user the final `pack.json` and generated `README.md`. Their sign-off
satisfies terminal-state gate 4.

**5. Reflect the pack in the top-level README, then refresh the reel and the landing page.** Make
two hand edits to the repo root `README.md` (the `readme:drift` guard enforces the count):

- Add the character to the **Available packs** list — its display name and a one-line description in
  the existing style (tone + signature palette, e.g. "a mild, upbeat pack that crackles in electric
  yellow"). Keep the list alphabetical.
- Bump the `characters-<n>%20packs` count badge to the new pack-directory count. Widgets and themes
  do not change per pack (themes is an advertised floor, so a growing catalog still passes).

Then regenerate the repo-wide assets. Both the reel and the landing page auto-discover packs from
`packages/packs/*`, so the new one is picked up with no list to edit:

- the cross-fade reel MP4 (`assets/characters.mp4`, for social) and a slower, size-capped GIF (
  `assets/characters.gif`, the animated README hero) — every card a live render in a varied session
  state (different widgets, helpful tip, and mood);
- the landing page under `website/` — `site:build` re-renders every theme and character shot and
  regenerates `website/data.js`. The character wall, the theme and widget filmstrips, and the
  headline counts all derive from `pack.json` and the engine's exported constants, so the new pack's
  card, its own theme, and the bumped counts appear automatically. Its **position** on the wall is
  the one thing that is not auto-derived: it comes from the `ORDER` list in
  `scripts/website/site-data-build.ts`, and `site:drift` fails until the new pack is added there (
  see below).

```
bun run build && bun run character:reel     # reel: needs ffmpeg + Chrome
bun run site:build                          # landing page: re-render every shot + regenerate website/data.js
bun run readme:drift && bun run site:drift  # confirm the README and the website both match the packs
```

`site:drift` is the website's counterpart to `readme:drift`: it recomputes `website/data.js` from
the
packs/themes/widgets and deep-compares, failing on any drift (a changed colour, an added pack, a
relabelled widget). Add the new pack to two ordered lists:

- `ORDER` in `scripts/website/site-data-build.ts` — the authoritative character-wall order.
  **`site:drift` fails until every pack is listed here**, so add the name wherever you want it on
  the wall (not just the tail).
- `CURATED=(…)` in `scripts/assets/character-reel.sh` — the reel order; add the name to lead the
  pack earlier than the tail.

Also add a `"<name> pack"` entry to `.github/labeler.yml`: every pack has its own PR label, and the
CI labeler (which colours each pack label from its theme) reads this list. Commit the README and the
refreshed source assets under `assets/` alongside the pack in step 7; `website/data.js` and the
copied `website/` media are CI-built and gitignored, so they are not committed.

**6. Add a changeset so the pack gets released.** Releases run
on [Changesets](https://github.com/changesets/changesets):
a package is published only when a changeset raises its version. The Release workflow discovers
packs through a `packages/packs/*` glob, so no workflow edit is ever needed. Just declare the bump:

```
bun run changeset
```

Select `@ccsidekick/pack-<name>`, choose `minor` (a brand-new pack's first real version), and write
a one-line summary. That writes a `.changeset/*.md` file; commit it with the pack. Nothing publishes
until a maintainer runs the Release workflow, which opens a "Version Packages" PR and, once merged,
publishes.

Note the internal-dependency behavior, in case the pack is `batman`: the engine (`ccsidekick`) has a
runtime dependency on `@ccsidekick/pack-batman`, so a batman changeset also cascades a patch bump to
the engine (it ships batman). The other packs are engine `devDependencies` and never cascade;
they version independently. Do not add `linked`/`fixed` entries for packs; independent versioning is
intentional.

**7. Delete `REVIEW.md` and commit.** `REVIEW.md` is transient reviewer scratch, removed at ship
so packs never carry it — the same treatment as the `.author/` working files. Delete it before the
commit so it never enters history, confirm the parity test, then commit by path (include the
changeset from step 6 and the refreshed assets from step 5):

```
rm packages/packs/<name>/REVIEW.md
bun test packages/core/src/packs/registry.test.ts
git add packages/packs/<name> .changeset README.md assets/characters.mp4 assets/characters.gif website/data.js
git commit -m "feat(packs): add <name> pack"
```

Do not `git commit --amend` across a multi-commit local series (amend hits `HEAD`, not the commit
you intend). A secret-scanning hook runs on every push.

## Quick reference

| Command                                                                                    | Purpose                                                                                         |
|--------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|
| `bun .claude/skills/pack-author/scripts/scaffold.ts <name> --display "<N>" --emblem "<g>"` | Create skeleton pack, register in `PACKS`, link as core runtime dependency (then `bun install`) |
| `bun .claude/skills/pack-author/scripts/figure-options.ts <packDir> --candidates <json>`   | Render figure candidates → `.author/figures.html`                                               |
| `bun .claude/skills/pack-author/scripts/figure-ingest.ts <packDir>`                        | Write `.author/figure.txt` into `pack.json` art; runs `--schema-only` lint                      |
| `bun .claude/skills/pack-author/scripts/theme-options.ts <packDir> --candidates <json>`    | Render theme candidates → `.author/themes.html`                                                 |
| `bun run pack:lint --schema-only packages/packs/<name>`                                    | Schema guard + legibility gate (skips content counts)                                           |
| `bun run pack:lint --status packages/packs/<name>`                                         | Per-cell fill status: current count vs. target per leaf                                         |
| `bun run pack:lint packages/packs/<name>`                                                  | Full lint: all schema, content, and quality gates                                               |
| `bun run pack:readme packages/packs/<name>`                                                | Write `README.md` + themed `assets/statusline.svg` (needs `bun run build`)                      |
| `bun run character:reel`                                                                   | Regenerate the roster reel: `assets/characters.mp4` (social) + `assets/characters.gif` (README) |
| `bun run site:build`                                                                       | Rebuild the landing page: re-render every theme/character shot + regenerate `website/data.js`   |
| `bun run site:drift`                                                                       | Guard: fail if `website/data.js` or the render set is stale against the packs                   |
| `bun test packages/core/src/packs/registry.test.ts`                                        | Registry parity test                                                                            |