---
name: build-chasing-mastery-package
description: Design, build, preview, iterate, verify, and prepare a Chasing Mastery Experience Suite from a plain-language idea. Use when someone asks to make or improve a Practice Mode, multi-mode package, progression, portable player, overlay, Story Events, correction flow, coordinated multiplayer policy, or narration policy; to work in Package Workbench; or to prepare immutable review bytes.
---

# Build a Chasing Mastery package

Turn the user's idea into a working package through one guided authoring journey.
Keep the user focused on the experience they want; handle SDK and Workbench
mechanics yourself.

## Start the journey

1. Locate the package workspace. If
   `chasing-mastery.package.json` already exists, inspect `package.json`, install
   its declared dependencies when needed, and use its `.chasing-mastery/run.sh`
   or `.chasing-mastery/run.ps1` launcher when present. Fall back to local
   `npm run` scripts only when a compatible Node runtime is already available.
   Never require or install a global `cm` binary.
2. For a new package, read [authoring-interview.md](references/authoring-interview.md)
   and ask one compact batch of only the unanswered product questions. Infer
   safe defaults from the request and label them as assumptions.
3. Summarize the resulting Experience Suite in plain language: the member
   promise, how its Practice Modes work together, the featured entry mode, and
   the explicit display order. Then summarize each mode's canonical name,
   ready-to-practice default, Attempt, input, result, progression, player view,
   overlay, Story Events, correction policy, and edge cases. Summarize any
   coordinated multiplayer and narration policy separately because they are
   optional deterministic contributions, not hidden activity behavior. A
   one-mode suite is valid. Ask for confirmation only when a missing choice
   would materially change the product.
4. Create a valid version-3 `chasingmastery.package-authoring-brief` using
   [authoring-brief.example.json](assets/authoring-brief.example.json) as the
   structural template. The brief is the durable provider-neutral system of
   record; never put chat transcripts, secrets, absolute host paths, or model
   metadata in it.
5. Bootstrap once through this skill's deterministic setup script. On macOS or
   Linux run:

   ```bash
   bash <skill-directory>/scripts/bootstrap-posix.sh \
     --directory <directory> --brief <brief.json>
   ```

   On Windows run:

   ```powershell
   powershell -NoProfile -ExecutionPolicy Bypass -File \
     <skill-directory>\scripts\bootstrap-windows.ps1 \
     -Directory <directory> -Brief <brief.json>
   ```

   The bootstrap reuses a compatible Node 24 runtime or downloads the pinned
   portable runtime into the Chasing Mastery author cache, verifies its digest,
   installs the bundled immutable toolchain, scaffolds the package, installs
   project-local dependencies, and prints JSON status. It must not use sudo,
   an OS package manager, a global npm install, or the platform source checkout.
   Never silently overwrite a non-empty directory. If bundled toolchain assets
   are absent or fail digest verification, stop and report a damaged plugin.

## Build the first pass

Read [sdk-map.md](references/sdk-map.md),
[implementation-patterns.md](references/implementation-patterns.md), and
[contract-checklist.md](references/contract-checklist.md), then inspect the
installed `@chasingmastery/sdk` type declarations for exact signatures. Implement
the brief using that public package and, when useful, a checked Domain Kit
bundled with this toolchain. Treat the generated package as a safe, working
scaffold, not a finished design.

- Make every Practice Mode's Attempt boundary explicit. Completion must commit
  immediately; do not invent sessions, boards, rounds, or a required Stop
  action.
- Give every activity one stable package-owned `defaultPreset`. Its ID,
  configuration version, instructions, and complete configuration are part of
  the immutable release. The configuration must contain exactly the defaults
  declared by the activity's form and must be accepted by `describe`. A member
  adds the Suite once and receives every mode ready to practice; never design
  the ordinary journey around renaming or configuring individual modes.
- Give every activity an explicit package-owned `resultContract`. Its ID and
  revision mean that two completed Attempts are semantically comparable; they
  do not identify the UI or artifact bytes. Keep that pin only while scoring,
  units, metric meaning, aggregation, default configuration, and result
  behavior remain equivalent.
- Keep rules, scoring, rank thresholds, rich UI, overlay behavior, and Story
  Events package-owned. The host owns identity, clocks, persistence, network,
  Station, OBS, and authorization.
- Add deterministic scenarios for every mode's acceptance scenarios and
  important invalid, duplicate, stale, abort, correction, and completion paths.
- Implement the brief's exact correction contract. Stable transition identity,
  deterministic replay, terminal reopen/deny policy, and Story Event
  retractions must agree; never bolt correction onto a mutable result record.
- When the brief declares coordination, use `defineCoordinationEngine` and
  `createCoordinationWorkerHandler`. Keep participant eligibility, input
  arbitration, rounds, teams, reconnect, and result policy deterministic while
  each Practice Mode Attempt remains its own atomic evidence record.
- When the brief declares narration, use `defineNarrationDirector` and
  `createNarrationWorkerHandler`. Plan only from committed broadcast facts;
  define intentional silence, expiry, correction cancellation, and a visual
  fallback when speech is unavailable.
- Build the real portable player and overlay when the brief requests them.
  They must use the public bridge and work in browser iframe and native WebView
  hosts without network or native authority.
- Reuse a Domain Kit only for pure build-time rules, schemas, fixtures, or
  presentation helpers. Follow the Domain Kit steps in
  [implementation-patterns.md](references/implementation-patterns.md). Never
  invent or copy an integrity digest; inspect the installed bytes through the
  package-local launcher and let Workbench derive packed provenance.
- Run `npm run status` from the package directory after meaningful changes.
  Follow its JSON `nextActions`; do not scrape friendly terminal prose.

## Preview and iterate

Run `.chasing-mastery/run.sh dev` on macOS/Linux or
`.chasing-mastery/run.ps1 dev` on Windows in a persistent terminal and give the
user the printed Workbench URL. Work against every declared Practice Mode in
the real Workbench player. Switch among activity, coordination, and narration
contributions when declared. Check device viewports, overlay, progression,
measurements, Story Events, corrections, multiplayer directives, narration
cues/cancellations, scenarios, and diagnostics for each contribution.
Interactive player commands execute that mode's real package reducer; they do
not advance through a canned scenario. Use the closed **Developer
tools > Simulate automatic input** panel to inject declared Station-shaped
observations into that same live Attempt when the package supports automatic
input.

For each feedback round:

1. restate the visible behavior being changed;
2. update the brief if the product intent changed, then update code and fixtures;
3. run package tests and inspect JSON status through the project launcher;
4. keep the Workbench available for the next review.

Do not create an AI-only preview, hidden fork, or second runtime. Do not mark a
visual request complete solely from conformance tests when the preview can be
inspected.

## Evolve an existing release safely

Never edit or republish an existing version. Preserve its `.cmpkg`, update the
brief when intent changes, increment the package's semantic version, pack the
candidate, and compare both immutable archives through the project launcher:

```bash
.chasing-mastery/run.sh evolution <previous.cmpkg> <candidate.cmpkg> --json
```

Use `.chasing-mastery/run.ps1 evolution ...` on Windows. Treat the report as
authoritative: do not hand-label an update compatible. Presentation-only changes
may preserve the result and progression lane when differential fixtures agree.
Changed scoring, units, metric meaning, default/configuration semantics, or
result aggregation requires a new result-contract revision. Changed thresholds
or progression evidence requires a new immutable progression version and lane.
Resolve every `blocked` finding before readiness and explain any historical lane
boundary to the user.

## Finish honestly

Only when the user says the package is ready, read
[release-and-submission.md](references/release-and-submission.md), run the final
checks, then execute:

Use `.chasing-mastery/run.sh ready` on macOS/Linux or
`.chasing-mastery/run.ps1 ready` on Windows. For a legacy package without the
launcher but with compatible Node, use its local `npm run ready` script.

Report the `.cmpkg`, digest, and `chasing-mastery.submission.json`. “Ready for
review” is not “published.” Never claim upload, approval, signing, installation,
or community-library availability unless that operation actually succeeded. If
the authenticated Chasing Mastery MCP tools are available and the member has
clearly authorized private submission, hand off to
the `manage-chasing-mastery-club` skill through the current agent's native skill
syntax; otherwise direct the author to the signed-in
private-authoring screen. Never ask for, copy, store, or use their Chasing
Mastery session, password, API key, or browser credential. Approval creates an
owner-only private Library release; it does not publish to the community
marketplace.

## Boundaries

- Never import another `@chasingmastery/*` package from authored source except
  an exact declared, authority-free Domain Kit shipped by the local toolchain.
- Never grant a package filesystem, arbitrary network, process, Station, OBS,
  account, or database authority.
- This skill builds portable Practice Mode and overlay packages. It does not
  scaffold, compile, sign, or install native Station connector sidecars. A
  portable package may declare and simulate exact connector observation
  protocols, but that never authorizes a sidecar or local resource grant.
- Never embed provider credentials in a brief or package.
- Do not use Station as a coding-agent host. Station remains an input/capture
  surface unless a later product decision establishes a separate safe runner.
- If the SDK cannot express a required behavior, stop and identify the missing
  public contract instead of reaching into platform internals.
