gc-demo-script

Files (1)

• SKILL.md

SKILL.md (first lines)

# GC Demo Script — Gas City Bead to Demo Script

Generate a `demo:capture`-format markdown script from a completed Gas City
work bead.
This skill is the Gas City-native sibling of `demo:epic`: it reads the bead
description, notes, parent molecule, sibling design-leg beads, and git/PR
diff, then produces a user-facing demo script that `demo:capture` can
execute.

**This skill DOES NOT run `demo:capture`.** It writes a script file and
returns the path.
The caller (human or another skill) invokes `demo:capture` separately on the
generated script.
This matches `demo:epic`'s separation between generation and execution.

## When to use

Use this skill when:

- A Gas City work bead is closed (usually with a merged or open PR)
- You want a user-facing demo of what the bead's work actually changed
- The bead does NOT have BMAD artifacts (use `demo:epic` for BMAD-driven
  work that lives under `_bmad-output/`)

## Input

You receive parsed arguments from the command wrapper:

- **Bead ID** (required) — e.g., `tk-8jv`
- **`--pr <number>`** (optional) — PR number, otherwise derived from
  `metadata.pr_number` on the bead
- **`--focus "area"`** (optional) — bias the demo narration toward a
  specific functional area (e.g., "mobile", "diff viewing")

If no bead ID is provided, ask the caller for one.

## Prerequisites Check

Before gathering context, verify:

1. **`bd` CLI is available** — `command -v bd` succeeds
2. **Bead exists** — `bd show <id>` returns a valid result

If the bead doesn't exist, stop and report:
"Bead `<id>` not found. Check the ID and try again."

Unlike `demo:epic`, this skill needs no browser, no ffmpeg, and no running
app — it only reads the bead and its diff to write a script file. `demo:capture`
runs that script later, from a session that carries the demo toolchain.

## Phase A: Gather Context (sequential reads)

Gas City sources are interconnected — the work bead references sibling
design-leg beads, parent molecules, and commits.
Read them in order; do NOT dispatch parallel subagents (the inputs are
small enough for direct reads, and ordering matters for cross-references).

### Step A1: Read the work bead

```bash
bd show "$BEAD"                               # Human-readable summary
bd show "$BEAD" --json > /tmp/bead-"$BEAD".json  # Full structured data
```

From the JSON, extract and keep in working memory:

- `title` — becomes part of the demo title
- `description` — original assignment (the "what to build"). Scan for:
  - Goals and scope priorities (TIER 1, TIER 2, MUST HAVE)
  - Locked decisions or must-have behaviors
  - References to sibling beads (e.g., `tk-9hi`, `tk-so9`)
  - Test strategies (hints about what to verify in the demo)
- `notes` — the polecat's implementation report. Scan for:
  - "Implemented:" section — lists what was actually built
  - File paths mentioned (narrows user-facing changes)
  - "Quality" / "Tests" section — hints at Scrutiny items
  - "Out of scope" / "deferred" — what was NOT done (do NOT demo it)
- `metadata.branch` — the implementation branch
- `metadata.target` — the target branch (usually `main`)
- `metadata.pr_number`, `metadata.pr_url` — PR location (if any)
- `metadata.work_dir` — the polecat's worktree path (the gc-toolkit
  contract; older/other beads may record it as `metadata.worktree`, so
  prefer `work_dir` and fall back to `worktree`)
- `parent` — the convoy/molecule wrapping this work

### Step A2: Read the parent molecule (if any)

If the bead has a parent convoy or `metadata.molecule_id`, read it:

```bash
PARENT=$(bd show "$BEAD" --json | jq -r '.[0].parent // empty')
MOLECULE=$(bd show "$BEAD" --json | jq -r '.[0].metadata.molecule_id // empty')
[ -n "$MOLECULE" ] && bd show "$MOLECULE"
[ -n "$PARENT" ] && bd show "$PARENT"
```

The parent gives cross-bead context — the wider initiative, why this work
mattered, and how it fits with other beads.

### Step A3: Read sibling design-leg beads

Scan the work bead's `description` and `notes` for bead IDs referenced in
prose (e.g., "per tk-so9 §6", "tk-9hi G2.1").
Extract candidate IDs with a regex, validate each against the ledger, and
read the real ones:

```bash
# Bead IDs are <prefix>-<suffix>. Rig prefixes vary by consuming rig
# (tk, gc, …), so match the bead-id SHAPE — a short
# lowercase prefix + '-' + alphanumeric suffix — instead of a fixed
# prefix list, then VALIDATE each candidate with `bd show` before
# reading it. Validation drops the false positives the broader regex
# necessarily lets through (e.g. "utf-8", "sha-256").
bd show "$BEAD" --json \
  | jq -r '.[0].description, (.[0].notes // "")' \
  | grep -oE '\b[a-z]{2,4}-[a-z0-9]+\b' \
  | sort -u \
  | grep -v "^$BEAD$" \
  | while read -r SIBLING; do

From zookanalytics/gc-toolkit, MIT.

More from zookanalytics/gc-toolkit