@erclx/aitk 0.8.0

package/claude/skills/claude-review/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: claude-review
+description: Reviews all changes since main for bugs, edge cases, and logic flaws. Reads CLAUDE.md, REQUIREMENTS.md, and ARCHITECTURE.md for context, then applies a structured review to the full diff and outputs a findings report. Coding standards from `.claude/rules/` are auto-loaded by Claude Code. Use when asked to review changes, run a code review, or check the current branch. Do NOT auto-trigger on vague signals like "looks good" or "can you check this". Require an explicit review request or an autoship invocation.
+---
+
+# Claude review
+
+## Guards
+
+- Resolve the base ref first, per Diff baseline below. If the staged set, the branch set, and the working set are all empty, stop: `✅ No changes to review.` A guard reading bare local `main` stops the skill on `main` before it ever reaches Step 2.
+
+## Diff baseline
+
+Resolve the base ref once and reuse it in the guard and in Step 2:
+
+```bash
+git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null
+```
+
+Prefer `origin/main` over local `main`. On `main` itself the local ref resolves to HEAD, so every committed change drops out of the set and the skill reports a clean branch rather than admitting it cannot see the work.
+
+The baseline is unusable in two cases:
+
+- No merge base resolves against either ref.
+- The base equals HEAD, whichever ref resolved it. Nothing is committed ahead of the base to compare against. This is the ordinary shape on `main`, and on a feature branch before its first commit.
+
+An unusable baseline costs only the committed half. `git diff <base> HEAD` is empty by definition once the base equals HEAD, while the staged set and `git diff HEAD` still report work at correct scope. Review those and lead the report with `⚠ Baseline unusable. Reviewed the uncommitted set only.`, so a clean summary is never read as a clean branch.
+
+## Step 1: read context
+
+Read these in parallel from the project root, skipping any that do not exist:
+
+- `CLAUDE.md`: project type, conventions, and commands
+- `.claude/REQUIREMENTS.md`: feature scope and non-goals
+- `.claude/ARCHITECTURE.md`: technical design decisions
+
+Coding standards from `.claude/rules/` are auto-loaded by Claude Code. Always-on rules apply every session. Path-scoped rules apply to files matching their `paths:` glob.
+
+## Step 2: get the diff and changed files
+
+Resolve the base ref per Diff baseline above, then run these in parallel from the project root:
+
+```bash
+git diff --staged
+```
+
+```bash
+git diff --staged --name-only
+```
+
+```bash
+git diff <base> HEAD
+```
+
+```bash
+git diff <base> HEAD --name-only
+```
+
+If `git diff --staged` is non-empty, use it as the diff scope and use the `--staged --name-only` list as the file list. Otherwise use `git diff <base> HEAD` and its name-only list.
+
+When the baseline is unusable, substitute `git diff HEAD` and `git diff HEAD --name-only` for the branch pair. Never substitute the whole tree for a missing baseline.
+
+## Step 3: read changed files
+
+Read each file from the changed file list. Skip deleted files. Run reads in parallel.
+
+## Step 4: review and persist
+
+Review the full diff and changed file contents for:
+
+1. Bugs and edge cases
+2. Error handling gaps
+3. Logic flaws that will cause problems when the code is extended
+4. Security issues relevant to the project context
+5. Violations of rules from `.claude/rules/` that apply to the changed files
+
+Use `CLAUDE.md`, `.claude/REQUIREMENTS.md`, `.claude/ARCHITECTURE.md`, and the auto-loaded `.claude/rules/` as project context to inform what is intentional vs problematic. Do not fix, rewrite, or suggest refactors outside the scope of a finding.
+
+### High-signal filter
+
+Flag only issues that will definitely cause incorrect behavior or break a documented rule. Skip:
+
+- Code style or quality concerns
+- Subjective suggestions
+- Linter territory
+- Issues that depend on unverified state
+
+If uncertain, do not flag. False positives erode trust.
+
+### Severity
+
+- **critical**: blocks the feature. Broken in production if shipped.
+- **should-fix**: fix in same session while context is fresh. Not a blocker.
+- **minor**: not worth fixing now. Include for visibility.
+
+### Report format
+
+Start with a summary line. Group findings by file. Within each file, list findings sorted by severity (critical first, then should-fix, then minor). Omit files with no findings.
+
+```markdown
+X critical, Y should-fix, Z minor across N files.
+
+File: path/to/file.ext
+
+- **critical**: finding
+- **should-fix**: finding
+- **minor**: finding
+
+File: path/to/other.ext
+
+- **critical**: finding
+- **minor**: finding
+```
+
+If nothing is wrong, use: `✅ No findings.`
+
+### Persist
+
+Derive a slug from the current git branch: run `git branch --show-current` and replace any `/` with `-`. If the result is empty (detached HEAD), use `latest`.
+
+Write the full report directly to `.claude/review/review-<slug>.md` at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`. Create the directory if it does not exist. Always overwrite.
+
+If there are no findings, write `✅ No findings.` to the file with a timestamp.
+
+The `.claude/review/` directory is gitignored. Do not stage or commit the file.
+
+### Chat output
+
+Output only the summary line and the file path. Do not repeat the full report in chat.
+
+```plaintext
+X critical, Y should-fix, Z minor across N files.
+📝 Wrote .claude/review/review-<slug>.md
+```
+
+If no findings: `✅ No findings. Wrote .claude/review/review-<slug>.md`

package/claude/skills/claude-roadmap/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: claude-roadmap
+description: Drafts or updates `.claude/ROADMAP.md` by sequencing the MVP scope from `.claude/REQUIREMENTS.md` into ordered versions, each a usable increment. Use when asked to "draft a roadmap", "build the roadmap", "sequence the versions", "plan the roadmap", or "update the roadmap". Do NOT break versions into task-level steps. That is `claude-feature` and `.claude/tasks/`.
+---
+
+# Claude roadmap
+
+## Guards
+
+- If `.claude/REQUIREMENTS.md` is absent or has no MVP features, stop: `❌ No requirements to sequence. Draft .claude/REQUIREMENTS.md first.`
+- If the requirements file carries a later scope section, stop per Lifecycle gate below
+- Sequence versions and their outcomes only. Do not produce file lists or task steps.
+
+## Lifecycle gate
+
+A roadmap sequences the MVP list alone, so a later scope section means that list has shipped and a fresh requirements pass owns what follows. The rule is the Lifecycle section of `.claude/standards/requirements.md`, falling back to `${CLAUDE_SKILL_DIR}/../../standards/requirements.md` when the project has no copy.
+
+- A later scope section is a `##` heading after `## MVP features` that `.claude/standards/requirements.md` names nowhere, neither among the six it fixes nor as the conditional `## Distribution`
+- On finding one, stop: `❌ MVP scope already sequenced. ## <section> is later scope, which a fresh requirements pass sequences rather than this roadmap. Say to sequence it anyway to override.`
+- Draft without the gate when neither copy of the standard resolves. Refusing on a rule that could not be read stops more than it protects.
+- When the caller overrides, sequence the later scope section's entries as versions and proceed
+
+## Step 1: read context
+
+Read these in parallel from the project root, skipping any that do not exist:
+
+- `.claude/REQUIREMENTS.md`: the MVP feature scope to sequence
+- `.claude/ROADMAP.md`: the existing roadmap, when updating rather than drafting
+- `.claude/tasks/index.md`: what is in flight, to mark the active version
+- `.claude/ARCHITECTURE.md`: technical dependencies that constrain ordering
+
+Follow `${CLAUDE_SKILL_DIR}/references/roadmap.md` for the doc shape, sections, and version format.
+
+## Step 2: sequence
+
+Group the MVP features into versions, each a usable increment that stands on its own. Order the versions by two forces:
+
+- Dependency: a version that produces data or a contract another version consumes comes first.
+- De-risking: a version that de-risks an unproven subsystem comes early, inside the version that first needs it.
+
+For each version, state the observable outcome as what the user can then do, list the features it groups by name, and note what it depends on and why.
+
+When updating an existing roadmap, preserve rows that still hold. Resequence, add, or split only where scope shifted. Do not rewrite rows that did not change.
+
+## Step 3: write
+
+Write the roadmap to `.claude/ROADMAP.md` at the project root, following `${CLAUDE_SKILL_DIR}/references/roadmap.md`. Create the file when absent.
+
+Unlike `.claude/plans/` and `.claude/tasks/`, `.claude/ROADMAP.md` is committed. Do not stage or commit it here. Leave staging to the git skills.
+
+## Step 4: output
+
+```markdown
+📝 Wrote .claude/ROADMAP.md
+
+<N> versions sequenced. Active: vX.Y.
+
+Next: /claude-feature for the first version's opening feature.
+```
+
+When updating, replace the first line with `📝 Updated .claude/ROADMAP.md` and name which versions changed.

package/claude/skills/claude-roadmap/references/roadmap.md

@@ -0,0 +1,52 @@
+---
+title: Roadmap reference
+description: Shape and content rules for .claude/ROADMAP.md
+consumers: claude-roadmap
+---
+
+# Roadmap reference
+
+Applies to `.claude/ROADMAP.md`. Sequences the scope from `.claude/REQUIREMENTS.md` into ordered versions, each a usable increment. Update when the sequence changes or a version ships. The roadmap is committed because the sequence and its rationale are shared strategic truth a fresh session needs, unlike `.claude/tasks/`, which is ephemeral scratch.
+
+The roadmap is one scannable table. That is what keeps it distinct from `.claude/tasks/`: the roadmap is an overview read at a glance, while tasks are worked one file at a time.
+
+## What goes in
+
+- One row per version, ordered top to bottom by sequence
+- A status per version: active, next in line, or deferred
+- The observable outcome each version delivers, as a short phrase
+- The features a version groups, by name, drawn from the MVP list in `.claude/REQUIREMENTS.md`
+- The version each row depends on, and a short why
+
+## What does not go in
+
+- Task breakdown, checkboxes, or per-feature file lists. Those live in `.claude/tasks/` and `.claude/plans/`.
+- Implementation detail, API names, or component references
+- Rationale for tech choices. That belongs in `.claude/ARCHITECTURE.md`.
+- Sentence-long cells. Keep each cell terse so the table stays scannable.
+
+## Format
+
+One table. Columns, in order:
+
+- `Version`: the `vX.Y` phase label. Phase-label format is governed by `standards/versioning.md`.
+- `Status`: `Now` for the active version, `Next` for sequenced upcoming versions, `Later` for deferred themes.
+- `Outcome`: what the user can do once this version ships, as a phrase.
+- `Features`: the feature names this version groups, comma-separated.
+- `Depends on`: the version this one needs and a short why, or `none` when independent.
+
+## Template
+
+```markdown
+# Roadmap
+
+| Version | Status | Outcome  | Features             | Depends on         |
+| ------- | ------ | -------- | -------------------- | ------------------ |
+| v0.1    | Now    | <phrase> | <feature>, <feature> | none               |
+| v0.2    | Next   | <phrase> | <feature>            | v0.1, for <reason> |
+| v0.3    | Later  | <phrase> | <feature>            | none               |
+```
+
+## Lifecycle
+
+The roadmap sequences a finite, known scope. When the last version ships, the scope is exhausted and the project cuts a semver release per `standards/versioning.md`. Later work arrives as discrete items, a fresh requirements pass or tracked issues, rather than extending the original roadmap without end.

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

@@ -0,0 +1,160 @@
+---
+name: claude-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.
+---
+
+# Claude screencast
+
+## Guards
+
+- If no topic is provided, stop: `❌ No screencast topic. Describe what you are recording.`
+- Do not record, edit video, or generate captions. Output the script and stop.
+- Stack-agnostic. Never name recording software, editing software, fonts, or window managers in the draft.
+
+## 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.
+
+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 beats and resolved decisions, then record.
+```
+
+Do not proceed to recording. Do not generate captions. Stop.

package/claude/skills/claude-seed-sync/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: claude-seed-sync
+description: Audits a project's installed Claude seed docs against the toolkit's current seed source and proposes per-section edits without overwriting customizations. Use when asked to "sync seeds", "update my seeds", "check seed drift", "did the toolkit seeds change", or when reconciling `CLAUDE.md` and `.claude/` preambles after an upstream toolkit update.
+---
+
+# Claude seed sync
+
+Surfaces drift between the toolkit's current seed docs and what was installed in this project, then proposes targeted edits. The CLI emits seed content. This skill diffs, reasons, and writes the proposal to a review file. It does not write target files until the user confirms.
+
+## Guards
+
+- If the `aitk` CLI is not on PATH, stop: `❌ aitk CLI not found. Install the toolkit first.`
+- If no `.claude/` directory exists at the project root, stop: `❌ No .claude/ directory found. Run aitk claude init first.`
+
+## Step 1: read toolkit sources
+
+Run both in parallel from the project root:
+
+```bash
+aitk claude seeds list --json 2>/dev/null
+aitk standards list --json 2>/dev/null
+```
+
+Seeds emit an array of `{name, source, target, content}`. Standards emit `{standards: [{name, description, target, content}]}`. In both cases `target` is the path relative to the project root where the file installs. Merge the two into one list of entries tagged by source (`seed` or `standard`).
+
+If the target project has no `.claude/standards/` directory, skip the standards stage silently.
+
+## Step 2: read installed copies
+
+For each entry in the merged list, read the file at its `target` path from the project root. Run reads in parallel. Mark missing files for **Add** treatment. Skip non-text seeds (`.json`) for section diffing. Record a one-line note in the scope table that the user can compare manually.
+
+When detecting target-only files for `local-only` flagging, skip files the toolkit's own walkers regenerate from sibling frontmatter (today: any `index.md` produced by `aitk indexes regen`). They are absent from source catalogs by design, so flagging them as `local-only` is a false positive.
+
+Note on `settings.json`: the seed now ships only the PostToolUse hook block. If a target project's `.claude/settings.json` carries `attribution` or `permissions` keys, those are stale: the user-level `~/.claude/settings.json` (installed via `aitk claude setup`) owns them now. Flag those keys in the scope table for removal rather than diffing them as content drift.
+
+## Step 3: diff per section
+
+For each seed file present in both sides, parse the body into a preamble (everything between H1 and the first H2) plus one part per `##` header, then compare part by part. Treat the preamble as a single unit with the same verdicts as a section. Use `(preamble)` as its label in the proposal.
+
+- **Identical:** ignore.
+- **Toolkit-only section** (present in source, absent in target): candidate to **Add**.
+- **Target-only section** (present in target, absent in source): preserve, never propose removal. These are user customizations.
+- **Drifted section** (present in both, content differs): candidate to **Update**.
+  - If the target version looks customized (extra bullets, project-specific paths, filled-in placeholders), call it out as **Customized**. Default action: skip, record in the scope table only, never numbered.
+  - If the target version looks like the original toolkit version with the toolkit having moved on, call it out as **Stale**. Default action: propose update.
+
+The user judges intent. The skill makes the judgment legible.
+
+### Absorbed-already check
+
+Before proposing an Update, grep the target section for the seed text's keywords. If the rule is already implied by an adjacent bullet in the target version, drop the proposal and record the section as `in sync` in the scope table.
+
+## Step 4: write the proposal to the review file
+
+Derive a slug from the current git branch: run `git branch --show-current` and replace `/` with `-`. Fall back to `latest` on empty output.
+
+Write the full proposal to `.claude/review/seed-audit-<slug>.md` at the main worktree root. Do not print the proposal inline.
+
+Structure: a summary block at the top, a legend, a scope table, then one H2 per numbered item. Number items across all files so the user can reference them by number. Fuse the status, action, and target into each H2. Every item starts as 📝 pending.
+
+````markdown
+# Seed audit: <slug>
+
+**Pending:** <all numbers>
+
+Legend: ✅ applied · ⏭ skipped · 📝 pending
+
+How to respond: fill in `Decision:` per item (`apply` or `skip`), then ping. Chat shortcut: `all`, `none`, or a list of numbers.
+
+## Scope
+
+Group rows by source. `Seeds` first, then `Standards`. Mark target-only files (present in target, absent in source) as `local-only` and leave them untouched.
+
+| Source   | File       | Status     | Note                         |
+| -------- | ---------- | ---------- | ---------------------------- |
+| seed     | `<target>` | diffed     | <counts>                     |
+| seed     | `<target>` | in sync    |                              |
+| seed     | `<target>` | skipped    | non-text, compare manually   |
+| seed     | `<target>` | customized | <section> skipped by default |
+| standard | `<target>` | diffed     | <counts>                     |
+| standard | `<target>` | local-only | not in toolkit, preserved    |
+
+## 1. 📝 Update → `<target-path>` / <section>
+
+Why: <one-line reason>
+
+``​`diff
+
+- <project line removed>
+  <unchanged context line>
+
+* <seed line added>
+  ​```
+
+Decision:
+
+## 2. 📝 Add → `<target-path>` / <section>
+
+Why: <one-line reason>
+
+``​`diff
+
+- <seed section body, each line prefixed with +>
+  ​```
+
+Decision:
+````
+
+Update items show both sides in one `diff` block: removed lines from the project version with `-`, added lines from the seed version with `+`, unchanged context lines without a prefix. Add items show only `+` lines. Customized sections appear in the scope table only, never numbered. A file with no drift still appears in the scope table as `in sync`.
+
+After writing, tell the user `✅ Wrote proposal to .claude/review/seed-audit-<slug>.md`. Ask them to fill in `Decision:` per item, then re-ping or use the chat shortcut.
+
+Rewrite the review file in place whenever the proposal changes mid-review. The file stays the source of truth for the current decisions.
+
+## Step 5: apply
+
+Re-read the review file as source of truth. For each item, parse `Decision:`:
+
+- `apply` (or affirmative): run the `Edit`, flip emoji to ✅.
+- `skip`: leave the target section as-is, flip emoji to ⏭.
+- `defer` or empty: leave 📝 pending, no action.
+- Contains `?` or unrecognized verb: leave 📝 pending, no action.
+
+Chat shortcut: the user replies with `all`, `none`, or a comma-separated list of numbers. Apply only the numbered items.
+
+Apply edits one at a time via `Edit`, replacing one section at a time. Never rewrite a whole file. Claude Code's tool permission dialog is the confirmation gate per edit.
+
+As each item resolves, update its status in the review file: flip the H2 emoji from 📝 to ✅ for applied or ⏭ for skipped. Refresh the summary block counts at the top. Do not delete the review file. It stays as a receipt until the next `claude-seed-sync` run overwrites it or the user clears it.
+
+## After completion
+
+Output one line per action taken:
+
+- `✅ Updated: <target-path> / <section>`
+- `⏭ Skipped: <target-path> / <section>`
+
+End with a one-line bucket summary: `✅ Applied: <nums> | ⏭ Skipped: <nums> | 📝 Pending: <nums>`. Omit empty buckets. If anything is pending, remind the user they can fill in a `Decision:` and re-ping, or commit a skip with `skip <nums>` in chat.
+
+If the user accepted nothing, output:
+
+`✅ No changes applied.`

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

@@ -0,0 +1,62 @@
+---
+name: claude-slides-draft
+description: Drafts a `.claude/SLIDES.md` source from a topic, picks a layout per slide, then renders it to PowerPoint via `aitk 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 `aitk` CLI is on PATH.
+---
+
+# Slides draft
+
+Author a `SLIDES.md` source, then shell out to `aitk 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
+aitk 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
+aitk 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 `AITK_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/claude-standards-audit/REQUIREMENT.md

@@ -0,0 +1,33 @@
+---
+name: claude-standards-audit
+description: What the standards audit is for, the gaps it closes, and the fixing it deliberately refuses
+---
+
+# Claude standards audit requirement
+
+## Gap
+
+Without this skill, markdown ships unchecked against the authoring standards it was written under. A session that just wrote prose does not reopen the standard it was meant to follow, banned punctuation survives because it reads fine, and the mapping from a file to the standards governing it gets re-derived by guess on every pass.
+
+## Must
+
+- Scope the audit to markdown the project hand-authors, so a generated file is not reported against a standard nobody applies to it
+- Decide which standards govern each changed file, rather than auditing every file against every standard
+- Grep for the violations a standard makes mechanically detectable, because reading alone misses occurrences
+- Report each finding with a file and a line, grouped so one file is one fix pass
+
+## Must not
+
+- Fix a violation, or propose the fix inline. The cheap swap satisfies the grep and breaks the rule the grep was standing in for.
+- Enumerate specific rules or tokens from a standard. The standard is the list, and a copy of it here drifts the moment the standard changes.
+
+## Guards
+
+- No markdown changed since main: stop with a pass, not an error
+- No installed standards to audit against: stop and say where they come from
+
+## Out of scope
+
+- Code style and structure, which `.claude/rules/` governs and Claude Code loads directly
+- Whether a standard is itself correct. A finding against the corpus is an argument to change the standard, and that is a standards edit rather than an audit result.
+- Persisting a report. The diff is the living state and the audit is a check against it at a moment.