@erclx/canon 4.0.0

package/claude/skills/canon-screencast/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: canon-screencast
+description: Drafts a screencast script with pre-seeded beats, defaults, and decisions to `.claude/.tmp/screencast/<slug>.md`. Reads project context, asks four discovery questions with proposed defaults, then writes a shippable draft. Use when asked to "draft a screencast", "write a recording script", "plan a demo video", or "scaffold a screencast for X". Do NOT re-invoke to refine an existing draft. Re-running overwrites. Edit the draft file directly.
+---
+
+# Canon screencast
+
+## Guards
+
+- If no topic is provided, stop: `❌ No screencast topic. Describe what you are recording.`
+- Draft, then hand off. Do not edit video or generate captions, and do not drive the application. A recording is another command's job rather than something forbidden: write the draft, name `canon demo compile` as the next step, and stop.
+- Stack-agnostic in the draft. Never name a recording tool, an editing tool, a font, or a window manager. Keep selectors, URLs, wait conditions, and timings out of the beats too, since those four are exactly what the compiler adds in a plan of its own. A beat carrying them stops being a document a person can read and edit down.
+
+## Step 1: read the project context
+
+Read these in parallel from the project root, skipping any that do not exist:
+
+- `CLAUDE.md`: behavior rules and project pitch
+- `.claude/REQUIREMENTS.md`: feature scope, non-goals, audience hints
+- `.claude/tasks/index.md`: current scope
+- Recent commits via `git log --oneline -20 2>/dev/null || echo "FALLBACK"`: what shipped recently is usually the recording subject.
+
+## Step 2: discovery with proposed defaults
+
+Ask exactly four questions in chat. Each carries a proposed default derived from Step 1. The user confirms, overrides, or says "use defaults" to accept all.
+
+```markdown
+**Discovery:**
+
+1. Audience: proposing technical peers. Override?
+2. Length: proposing 75-90s. Override?
+3. Hero moment: proposing <best guess from context, or "the single thing that has to land">. Override?
+4. What to cut: proposing <best guess, or "anything that is not the hero moment">. Override?
+```
+
+Wait for answers before drafting. Do not infer silence as acceptance.
+
+## Step 3: derive the slug
+
+Build a 2-to-4-word kebab-case slug from the topic and discovery answers. Examples: `auth-flow-redesign`, `cli-onboarding`, `inline-edit-launch`.
+
+## Step 4: write the draft
+
+Create `.claude/.tmp/screencast/<slug>.md` at the main worktree root. Create the directory if it does not exist. The file is gitignored.
+
+From a linked worktree the file-editing tools refuse that path, so the draft goes out through `Bash`. Send the `mkdir -p` and the heredoc as two plain commands rather than joining them with `&&`, which is refused as compound.
+
+Write all eight sections. Pre-seed every section with concrete content so the draft is shippable as-is. The user edits down rather than fills blanks.
+
+```markdown
+# Screencast: <short title>
+
+## 1. Header
+
+- Audience: <from discovery>
+- Length: <from discovery>
+- Hero moment: <from discovery>
+- Pitch: <one sentence, derived from project context>
+
+## 2. Pre-recording checklist
+
+- [ ] Browser at 1920x1080 with notifications silenced
+- [ ] Session storage and history cleared for the recorded surfaces
+- [ ] Cursor highlighter on
+- [ ] Live URLs and fixtures verified healthy
+- [ ] <one or two project-specific items derived from context>
+
+## 3. Beat sheet
+
+Five beats. Each uses five fields. Add a sixth `Transition out` only when non-default.
+
+### Beat 1: Cold open
+
+- On screen: <derived from hero moment>
+- Action: <one verb, derived>
+- Watch for:
+- Emphasis: zoom 1.4x
+- Caption:
+
+### Beat 2: Setup
+
+- On screen:
+- Action:
+- Watch for:
+- Emphasis: none
+- Caption:
+
+### Beat 3: Hero moment
+
+- On screen: <hero moment from discovery>
+- Action:
+- Watch for:
+- Emphasis: highlight overlay
+- Caption:
+
+### Beat 4: Payoff
+
+- On screen:
+- Action:
+- Watch for:
+- Emphasis: none
+- Caption:
+
+### Beat 5: Outro
+
+- On screen:
+- Action:
+- Watch for:
+- Emphasis: zoom 1.2x out
+- Caption:
+
+## 4. Sequencing notes
+
+- Hover before click. The cursor needs a beat to register.
+- Do not cut mid-reset. Let state changes complete on screen.
+- Cut on action, not on stillness.
+- <one or two project-specific gotchas derived from context>
+
+## 5. Production notes
+
+- Resolution: 1920x1080
+- Frame rate: 30fps
+- Container: mp4 H.264
+- Zoom: max 1.8x with always-zoom-out before cut
+- Highlight overlay: ~1.5s soft glow
+
+## 6. Caption typography
+
+- White text on dark scrim at ~60% opacity
+- ~200ms fade in and out
+- One line max per caption, split across beats if needed
+
+## 7. Distribution
+
+Where the recording ships. Strike rows that do not apply.
+
+- [ ] Native upload to social platform
+- [ ] Canonical host (long-form video platform)
+- [ ] Linked from project README or release notes
+
+## 8. Resolved decisions
+
+Pre-seeded with the common picks. Strike or rewrite as needed.
+
+- Audio: silent plus captions
+- Music: none
+- Language: English
+- Chip order: <leave for user, derived from beats>
+- Thumbnail: hero-moment frame
+```
+
+## Step 5: output
+
+Print the file path on its own line and a one-line summary. Do not paraphrase the path into prose.
+
+```markdown
+📝 Wrote .claude/.tmp/screencast/<slug>.md
+
+Draft has 5 beats and pre-seeded defaults. Edit the beats and the resolved decisions.
+
+To record it rather than shoot it by hand:
+canon demo compile .claude/.tmp/screencast/<slug>.md
+```
+
+Name the command and stop there. Do not compile the draft, do not run it, and do not generate captions. The operator edits the beats first, and the compiler reports which selectors and URLs they still owe it.
+
+Say so plainly if `canon demo compile` is not available, rather than driving the application some other way. The command ships with the CLI and the skills ship with the plugin, so a project carrying one and not the other is a real state.

package/claude/skills/canon-slides-draft/REQUIREMENT.md

@@ -0,0 +1,39 @@
+---
+name: canon-slides-draft
+description: Why the skill owns deck content and the CLI owns layout, and why one render is read back before the deck is called done
+---
+
+# Canon slides draft requirement
+
+## Gap
+
+Without this skill, a deck request turns into hand-built layout. The session invents layout names the renderer does not have, so the render falls back or fails, and it writes centered body text and bullet lines that overflow the slide because nothing told it the type scale is fixed. Every slide comes out as a title over bullets, which is the shape that needs no decision and reads as a document rather than a deck.
+
+Reimplementing spacing and palette logic is the failure that survives the session. The CLI already owns both, so a deck that styles itself drifts from every other deck and stops being recognizable. And a first render shipped unread hands the audience the overlap and the overflow, since a source that looks correct says nothing about the picture it produces.
+
+## Must
+
+- Read the layout catalog from the CLI before drafting and pick only from what it returns
+- Match the content shape to the layout, since each one parses a different body
+- Vary layouts across the deck rather than repeating one
+- Size content to fit the fixed type scale, keeping titles short and bullet lines tight
+- Shell out to the render command for the deck itself
+- Run one QA pass over the rendered images and fix what it reports
+
+## Must not
+
+- Hardcode a layout name, which goes stale the moment the catalog changes
+- Reimplement layout, palette, or type scale, which the CLI owns
+- Write centered body text or content that overflows a slide
+- Loop on aesthetics past a single fix pass
+
+## Guards
+
+- Image conversion tools missing: skip the image pass and say so. Do not fail the render over a verification step.
+
+## Out of scope
+
+- Rendering, which the CLI owns end to end
+- The palette and the type scale, which live in the CLI rather than in the source
+- Writing the content the deck is about, which the caller brings
+- Recording a demo, which `canon-screencast` owns

package/claude/skills/canon-slides-draft/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: canon-slides-draft
+description: Drafts a `.claude/SLIDES.md` source from a topic, picks a layout per slide, then renders it to PowerPoint via `canon slides render`. Use when asked to "draft slides", "make a deck", "build a presentation", "turn this into slides", or "render a SLIDES.md". Holds the deck design rules. Do NOT reimplement render logic. The CLI owns layout and styling. Assumes the `canon` CLI is on PATH.
+---
+
+# Slides draft
+
+Author a `SLIDES.md` source, then shell out to `canon slides render`. The CLI owns all layout and styling. This skill owns content and the design choices encoded in the source.
+
+## Read the catalog
+
+Run this first to load the available layouts. Never hardcode layout names. The catalog is the source of truth.
+
+```bash
+canon slides list --json 2>/dev/null
+```
+
+## Draft the source
+
+Write the deck to `.claude/SLIDES.md` from the project root. Structure:
+
+- Deck frontmatter between `---` delimiters: `title`, optional `subtitle`, `palette`, and `variant` (light or dark).
+- One slide per section, separated by a `---` rule. Each slide opens with a `# Title` and a `layout:` line naming a layout from the catalog, followed by its content.
+
+Match content shape to the layout: bullet lists for list layouts, `## Heading` blocks for columns, `- value : caption` pairs for stats and cards, a quote with a `- attribution` line for quotes.
+
+For a deck with chapters, add a `toc` slide near the front and mark each chapter opener with the `section` layout. The render fills the contents links and the per-slide footer automatically from the section slides. Leave the `toc` slide body empty.
+
+## Design rules
+
+The palette and type scale live in the CLI. Own the choices the source controls.
+
+- Pick the variant that fits the topic. Light is a paper background, dark is near black. Both carry the same rust accent.
+- Vary the layout across slides. Never repeat title-and-bullets on every slide. Reach for columns, stat callouts, grids, and section dividers.
+- The CLI enforces the type scale, so size content to fit rather than overflow. Keep titles short and bullet lines tight.
+- Never write centered body text or content that overflows a slide. Let the layouts place the elements.
+
+## Render
+
+Shell out to the CLI. It writes the deck and reports the path.
+
+```bash
+canon slides render --source .claude/SLIDES.md --out .claude/review/slides
+```
+
+Pass `--variant light` or `--variant dark` to override the source variant for a one-off render. Pass `--open` to open the deck, and `--mirror <dir>` (or set `CANON_SLIDES_MIRROR`) to copy it into a synced folder.
+
+## QA loop
+
+Run this once after the first render, then stop.
+
+1. Convert the deck to images: `soffice --headless --convert-to pdf <deck>.pptx` then `pdftoppm -r 90 -png <deck>.pdf slide`. If `soffice` or `pdftoppm` is missing, skip the image pass and say so. Do not fail the render.
+2. Inspect the images with fresh eyes. Spawn a subagent to check every slide for overlap, overflow, low contrast, and empty regions.
+3. Fix the reported issues in `SLIDES.md` once, re-render, and stop. Do not loop indefinitely on aesthetics.
+
+## Response
+
+After rendering, report:
+
+- Slide count and the deck path
+- The palette and variant used
+- Any QA issues found and what changed, or that the deck passed clean

package/claude/skills/ci-workflow/REQUIREMENT.md

@@ -0,0 +1,40 @@
+---
+name: ci-workflow
+description: Scope boundary for pipeline structure against job contents, and the reproducibility rules under it
+---
+
+# CI workflow requirement
+
+## Gap
+
+Without this skill, a session writes a pipeline whose jobs run in sequence because `needs` was used to express the order a person reads them in rather than a data dependency. The pipeline then costs the sum of its jobs where it could have cost the longest one, and the waste compounds on every push.
+
+The same session splits a gate that finishes in a minute into three parallel jobs, which fails in the other direction. Each job repays checkout, dependency install, and toolchain setup before it reaches a stage, so the gate gets slower while reporting no earlier, and the roster reads as a design decision rather than as a cost nobody measured.
+
+The rest are reproducibility failures that surface as flakes. An action pinned to a moving ref changes under the project, so a run that passed yesterday fails today with no commit behind it and the diff explains nothing.
+
+A cache keyed on a static string serves a stale browser or toolchain after a version bump, and the failure reads as a broken test rather than a stale cache. Artifacts upload on every run and never expire, so storage grows with the commit count while the ones worth reading are the failures. And a workflow with no manual trigger can only be reproduced by pushing a commit, which is the wrong instrument for a run that failed for an environmental reason.
+
+## Must
+
+- Gate a job only on a data dependency or on a cost that justifies the wait, and leave every other job parallel
+- Start the checks that share setup in one job and split them only once a run log puts the gate past roughly two minutes
+- Pin every action to a tag that cannot cross a major version
+- Key a cache on the version string of the thing it caches
+- Give every workflow a manual trigger beside its primary one
+- Bound artifact upload to failures and set an expiry on it
+
+## Must not
+
+- Own what runs inside a job. The build, test, and deploy commands come from the project, and a workflow asserting its own is a second copy of the project's scripts.
+- Enumerate the job set as a fixed list. Projects add and remove jobs, and what has to survive that is the parallel and gated structure rather than the roster.
+
+## Guards
+
+- A request for a deploy, publish, or release step stops at the gate. The job's contents carry credentials and an environment this skill cannot see, so it emits the `needs` wiring and names what the caller has to fill in rather than guessing a deploy command.
+
+## Out of scope
+
+- The shell scripts a job invokes: `bash-cli-script`
+- Secrets, environments, and deploy targets, which live in the repository settings rather than in the workflow this skill writes
+- CI systems other than GitHub Actions. The structure rules generalize and the file format does not, so a different system is a different skill rather than a flag on this one.

package/claude/skills/ci-workflow/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: ci-workflow
+description: Generates GitHub Actions CI workflow files with parallel jobs, emoji job names, and gated deploy stages. Use when asked to "write a CI workflow", add GitHub Actions, set up a CI pipeline, or create a `.github/workflows` file.
+---
+
+# CI workflow
+
+Generate GitHub Actions workflow files for CI pipelines. Enforce parallel job execution, emoji job naming, and gated deployment stages.
+
+## Guards
+
+- A request for what runs inside a deploy, publish, or release job stops at the gate. Credentials, environments, and deploy targets are invisible to this skill, so emit the job with its `needs` wiring and a placeholder step, then name what the caller fills in. Never guess a deploy command.
+- The build, test, and deploy commands belong to the project. Read them from its scripts rather than asserting a second copy in the workflow.
+
+## Workflow setup
+
+- Include `workflow_dispatch` on every workflow alongside the primary trigger.
+- Pin all actions to major version tags (`@v4`, never `@latest` or `@main`).
+- Use `runs-on: ubuntu-latest` for all jobs.
+
+## Job naming
+
+- Name jobs with emoji + title: `🛡️ Checks`, `🛡️ Static Checks`, `🧪 Unit Tests`, `📦 Build Check`, `🎭 E2E Tests`, `🚀 Deploy`, `🔍 Code Quality`, `🏷️ Release`, `🔒 Security`.
+
+## Job granularity
+
+- Start a new pipeline with the checks that share setup in one job: static analysis, unit tests, and build. A project with no run history has nothing to measure, and one job is the shape that costs least to reverse.
+- Keep them in one job while the gate runs under roughly two minutes end to end. Each extra job repays checkout, dependency install, and toolchain setup before it reaches a stage, so a split at that duration costs more than the parallelism returns.
+- Split once a run log puts the gate past that, then apply the dependency rules below. The run log is the revision trigger rather than the entry condition, since repository size and stage count answer nothing.
+- Give E2E, release, and deploy their own jobs from the start. Each carries a data dependency or a gate, so this rule never folds them into the check job.
+
+## Job dependencies
+
+- Run independent jobs in parallel.
+- Use `needs` only when there is a data dependency (a job requires an artifact) or the job is prohibitively expensive relative to its gate.
+- Run static, unit, and build jobs in parallel once the gate is split.
+- Gate E2E on whichever job uploads the build artifact, since it consumes that artifact. That job is the folded check job in a new pipeline and the separate build job once the gate is split.
+- Gate release and deploy on E2E.
+
+## Artifacts
+
+- Upload artifacts on `if: failure()` only. Set `retention-days: 7`.
+
+## Bun stack
+
+- Use `oven-sh/setup-bun@v2` with `bun-version: latest`.
+- Install with `bun install --frozen-lockfile`.
+- Cache Playwright browsers keyed on the Playwright version string, never a static key.
+
+## Template
+
+Load `${CLAUDE_SKILL_DIR}/references/workflows.md` for the base workflow template. Adapt it to the project's stack, test commands, and build output. Add or remove jobs as needed. The template already carries the folded shape, and the split beside it applies once the granularity rule above calls for it.
+
+## Validation
+
+Before responding, verify:
+
+- `workflow_dispatch` is present alongside the primary trigger.
+- All actions pinned to major version tags, no `@latest` or `@main`.
+- A new pipeline folds static, unit, and build into one job, and a gate a run log put past two minutes gives them no `needs` so they run in parallel.
+- Every name in a `needs` matches a job declared in the same file. E2E names the artifact producer, release and deploy name E2E.
+- Artifacts upload on `if: failure()` only with `retention-days: 7`.
+- Job names use emoji + title format.
+- Deploy, publish, and release jobs carry a placeholder step and a named handoff, never a guessed deploy command.
+- Bun projects use `oven-sh/setup-bun@v2` with `bun install --frozen-lockfile`.

package/claude/skills/ci-workflow/references/workflows.md

@@ -0,0 +1,98 @@
+# CI workflow template
+
+Copy this base template and adapt it to the project's stack, test commands, and build output. It carries the shape a new pipeline starts in, with the checks that share setup in one job, per the granularity rule in the skill body. `e2e` and anything gated on it stay separate jobs at either size.
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  checks:
+    name: '🛡️ Checks'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - run: bun run check
+      - run: bun run test
+      - run: bun run build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: build-output
+          path: dist/
+
+  e2e:
+    name: '🎭 E2E Tests'
+    needs: checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - uses: actions/download-artifact@v4
+        with:
+          name: build-output
+          path: dist/
+      - run: bun run test:e2e
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: e2e-results
+          path: test-results/
+          retention-days: 7
+```
+
+## Splitting the check job
+
+Apply this once a run log puts the gate past roughly two minutes, never before. Each job below repays checkout, dependency install, and toolchain setup before it reaches a stage, which is the cost the duration has to cover. Replace the `checks` job above with these three and point `e2e` at `needs: build`.
+
+```yaml
+jobs:
+  static:
+    name: '🛡️ Static Checks'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - run: bun run check
+
+  unit:
+    name: '🧪 Unit Tests'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - run: bun run test
+
+  build:
+    name: '📦 Build Check'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - run: bun run build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: build-output
+          path: dist/
+```

package/claude/skills/claude-address-review/REQUIREMENT.md

@@ -0,0 +1,57 @@
+---
+name: claude-address-review
+description: What the review return leg is for, the gaps it closes, and why the push lands before the reply
+---
+
+# Claude address review requirement
+
+## Gap
+
+Without this skill, review findings are worked in whatever order the author read them and the thread never records which landed. A reply posted before the push describes code the remote does not have, so a reviewer checks the branch and finds the old version. A failing check gets treated as separate from the review, which produces a follow-up that answers every comment and leaves continuous integration red. One finding nobody can resolve stalls the rest.
+
+A branch also goes stale from `main` moving rather than from anything the branch did. Nothing in the return leg rebases it, so the worker closes every finding, reports the pull request answered, and the branch still cannot merge. Half the resolution is mechanical and wrong to do by hand, since a generated file merged manually produces a diff the next regen discards.
+
+A declined finding fails on a third axis, which is where its reason ends up. A worker answering a dispatch by naming the plan question that already settled the finding, or the constraint the diff never showed, settles it in whichever session heard the answer. Both sessions end, so a reader opening the thread later finds a finding that stopped being mentioned and no record of what stopped it, which is the durability the posted review already has by design.
+
+## Must
+
+- Treat a failing check as a finding alongside the review comments, so the follow-up closes both
+- Handle each finding independently, so one unresolved item does not block the others
+- Verify before pushing, since a red follow-up costs the reviewer a second pass
+- Rebase onto `origin/main` when the branch no longer merges, after the findings are addressed and before the push, so one force-push carries both
+- Test staleness on every invocation, including one carrying no findings, since a branch goes stale from `main` moving rather than from anything the review said
+- Re-test once the fixes are commits, since the first test reads committed history and cannot see a fix that touches lines `main` moved
+- Rebuild a generated file through the project check rather than resolving its conflict by hand
+- Push before replying, so the comment never runs ahead of the code it describes
+- Map every finding to what changed, or to a one-line reason when it is a question or a conscious accept
+- Carry the fact behind a declined finding into the posted reply rather than into the message that answered the dispatch, since both sessions end and the thread is what the next reader opens
+- Post the terminal comment only when the findings are addressed and every check passes
+- Say what the run actually did on a rebase-only pass, since a reply mapping findings and a terminal comment claiming they were addressed are both false on a pull request carrying none
+- Scan the reply for banned characters and internal phase labels before posting, since the comment leaves for the remote unchecked
+
+## Must not
+
+- Merge, or read the closing comment as an approval. The author cannot approve their own pull request.
+- Write a review. This skill consumes findings and does not produce them.
+- Post the closing comment while a check is failing
+- Reimplement the follow-up push or the doc refresh. Both have owners, and a second copy here drifts from them.
+- Edit silently. A finding answered without a reply leaves the reviewer re-deriving the change from the diff.
+- Answer a finding in the channel alone. A reply that changes what the review concluded is the one the thread has to carry.
+- Post a correction to what the reviewing session believes about the world. That class changes no finding here and belongs in the session record.
+- Take one side of a conflict wholesale. Both sides are valid content, so `--ours` or `--theirs` drops one silently and passes every check.
+- Merge `main` into the branch. The repository squash-merges, so a merge commit reads as noise on the pull request.
+- Guess at a hunk the tree does not settle. That case reaches the operator as an ordinary finding on the next pass only if the worker stops.
+
+## Guards
+
+- No open pull request for the current branch: stop
+- The pull request carries no review comments or threads and the branch still merges: stop with a pass. A closed review says nothing about whether the branch still merges, so the staleness test decides this one rather than the finding count.
+- A conflict needing a decision the tree does not carry: stop with the branch left on its old base
+
+## Out of scope
+
+- Writing the review, which `claude-pr-review` owns. The split is by side of the channel: that one posts findings from an independent session and this one is the worker's return leg.
+- Staging, committing, and pushing the follow-up, which `git-followup` owns under this skill's direction
+- Refreshing the `.claude/` docs the fixes made stale, which `claude-docs` owns
+- Re-reviewing its own fixes, which hands back to the orchestrator
+- Re-reading a rewritten branch, which `claude-pr-review` absorbs by testing whether the prior reviewed commit still reaches the head and paying for a full pass when it does not