git:20261021.cbc1c71 to git:20261029.7f379ee

45 added, 105 removed. Audit A to A.

- # Metapowers

- Structured, repeatable workflows for digital production domains. 283 skills across 16 plugins.

- ## Architecture

- - **Monorepo**: Bun + Turborepo workspaces

- - **Plugins** (`plugins/`): Each domain is a plugin with SKILL.md files, hooks, and shared resources

- - **Packages** (`packages/`): CLI (`create-metapowers`), skill-validator, plugin-tools, figma-mcp

- - **Evals** (`plugins/<domain>/evals/<skill>/`): `claude plugin eval` suites, run with `bun run evals` (`scripts/run-evals.sh`)

- - **Docs** (`apps/docs/`): Fumadocs + Next.js static site deployed to GitHub Pages

- ## Plugin Structure

- Every plugin follows this pattern:

- ```

- plugins/<domain>/

- ├── .claude-plugin/plugin.json # Plugin manifest

- ├── hooks/hooks.json # Quality gate hooks

- ├── shared/ # Templates and reference docs

- └── skills/<skill-name>/SKILL.md # One SKILL.md per skill

- ```

- ## SKILL.md Format

- ```markdown

- ---

- name: <skill-name> # must equal the directory name

- description: <Verb-first sentence>. Use when <user's situation, ≥6 words>. Not for <x>; see /<plugin>:<skill>. # 120–400 chars; "Not for" optional

- argument-hint: "<arg>" # when the skill takes an argument

- ---

- # Skill Name

- What the skill does with "$ARGUMENTS" placeholder.

- ## Prerequisites

- What must exist before running (or "None").

- ## Process

- Numbered steps with clear instructions.

- ## Output

- Where the artifact is written and what to present.

- ```

- ## Conventions

+ # singularskills

- - **Descriptions start with a verb**: "Create", "Analyze", "Review" — enforced by skill-validator

- - **Artifacts**: All stored in `.metapowers/<domain>/<project>/` with numbered prefixes (01-, 02-, etc.)

- - **Commits**: Conventional commits (`feat(domain):`, `fix(docs):`, `docs:`, `ci:`)

- - **Formatting**: Biome for linting and formatting (`bun run check`, `bun run format`)

- - **Testing**: Vitest for packages (`bun run test`)

- - **Skill validation**: `bun run lint:skills` validates all 283 SKILL.md files

+ One pack of Agent Skills: 283 skills across 16 domains, ordered into gated workflows. Read [AGENTS.md](AGENTS.md) first: it covers the layout, how a skill, a workflow file and a gate relate, and the checks.

## Commands

- ```bash

- bun run build # Build all packages

- bun run test # Run tests

- bun run lint:skills # Validate all SKILL.md files

- bun run check # Biome lint check

- bun run format # Biome auto-format

- bun run changeset # Create a changeset for npm release

- claude plugin validate . --strict # Validate plugin manifests

- bun run check:plugins # phase-deps, hooks, counts (plugin-tools), plus the

- # apps/docs data and skill-page checks below

- bun run evals --dry # List eval cases; fail if a prompt names its skill (free)

- bun run evals [plugin…] # Run claude plugin eval per plugin — spends Claude credits,

- # capped per plugin by EVALS_MAX_COST_USD (default 10)

- ```

- Docs site (`apps/docs`, run from that directory):

+ Run from the repository root unless a directory is given.

- ```bash

- bun run gen:data # Regenerate lib/site-data.json and lib/search-commands.json from plugins/

- bun run codemod # Rewrite skill pages in content/docs/ into the skill-page components

- bun run check # gen:data --check + codemod --check; fails if either would change a file

- bun run test # Vitest (site data, codemod, domains, search, motion)

- bun run build # gen:data, then next build to a static export in out/

- ```

+ | Command | What it does |

+ | --- | --- |

+ | `bun run build` | Build every package |

+ | `bun run test` | Vitest in every package (`SKIP_NETWORK_TESTS=1` skips the install smoke test) |

+ | `bun run lint:skills` | Validate every `skills/*/SKILL.md` |

+ | `bun run check:pack` | pack-tools checks: workflows, generated gates/references/adapters, fixers, counts |

+ | `bun run evals --dry` | List the eval cases; fail if a prompt names its own skill (free) |

+ | `bun run evals [skill…]` | Run `claude plugin eval` (spends credits, capped by `EVALS_MAX_COST_USD`, default 10) |

+ | `bun run check` / `bun run format` | Biome lint check / auto-format |

+ | `bun run gen:gates` (in `packages/pack-tools`) | Regenerate `skills/*/scripts/gate.sh` from `workflows/` |

+ | `bun run gen:references` (in `packages/pack-tools`) | Copy `references/<domain>/` files into the skills that link them |

+ | `bun run gen:adapters` (in `packages/pack-tools`) | Regenerate `adapters/` (command wrappers, `gates.json`, hook) |

+ | `bun run gen:data` (in `apps/docs`) | Regenerate the docs site data from the pack |

+ | `bash scripts/check-rename.sh` | Fail on any mention of the old project name outside the history allowlist |

- ## Adding a New Domain

+ ## Conventions

- 1. Create `plugins/<domain>/` following the structure above

- 2. Add plugin.json with name, description, author

- 3. Create SKILL.md files in `skills/<name>/SKILL.md`

- 4. Add to `.claude-plugin/marketplace.json`

- 5. Create docs in `apps/docs/content/docs/<domain>/`

- 6. Add to `apps/docs/content/docs/meta.json` sidebar

- 7. Add the domain to `apps/docs/lib/domains.ts` (slug, name, methodology, colour, icon, blurb, docsPath)

- - Also fill `animatedIcon` (a `line-md:` icon) and `bento` (`order` and `size`; re-tile the homepage bento so the cells still sum to full rows, and update `lib/site.test.ts`). A new supported agent goes in `apps/docs/lib/agents.ts` (slug, name, bundled `mark`, installation `href`).

- 8. In `apps/docs`, run `bun run gen:data` and commit `lib/site-data.json` and `lib/search-commands.json`

- 9. In `apps/docs`, run `bun run codemod` after adding the docs pages, so they get `kind`/`command` frontmatter

- 10. Run `bun run lint:skills` to validate

+ - **Skill names**: the folder is `skills/<domain>-<skill>/` and the frontmatter `name` equals it; invoked as `/<domain>-<skill>`.

+ - **Descriptions**: verb-first sentence, then `Use when <the user's situation, at least six words>.`, optionally `Not for <x>; see /<domain>-<skill>.`; 120 to 400 characters (enforced by skill-validator).

+ - **Frontmatter**: only `name`, `description`, `allowed-tools` and `metadata` at the top level; `metadata` holds `argument-hint`, `workflow`, `phase`, `artifact`, `disable-model-invocation`.

+ - **Artifacts**: written to `.singularskills/<folder>/<project>/` with numbered prefixes (`01-`, `02-`, ...); the run log is `.singularskills/log.jsonl`.

+ - **Generated files**: never edit `skills/*/scripts/gate.sh`, `skills/*/references/` copies of `references/<domain>/` files, or `adapters/`; edit the source and regenerate.

+ - **Commits**: conventional commits (`feat(design):`, `fix(docs):`, `chore:`, `ci:`).

+ - **Formatting**: Biome, tabs, width 100.

- `bun run check:plugins` fails until steps 7–9 are done.

+ ## Adding a skill to a domain

- ## Adding a Skill to an Existing Domain

+ 1. Create `skills/<domain>-<skill>/SKILL.md` (frontmatter as above; Prerequisites, Process and Output sections).

+ 2. If it belongs to a phase, add it to that phase's `skills` list in `workflows/<domain>.yml` and set `metadata.workflow`, `metadata.phase` and `metadata.artifact` to match.

+ 3. In `packages/pack-tools` (after `bun run build`): `bun run gen:gates`, `bun run gen:references`, `bun run gen:adapters`.

+ 4. Add its docs page in `apps/docs/content/docs/<domain>/<skill>.mdx` and list it in that domain's `meta.json`.

+ 5. In `apps/docs`: `bun run gen:data`, then `bun run codemod`; commit the regenerated files.

+ 6. Run `bun run lint:skills` and `bun run check:pack`.

- 1. Create `plugins/<domain>/skills/<skill-name>/SKILL.md`

- 2. Frontmatter: `name` = directory name; description = verb-first sentence + `Use when <≥6 words>.` (optional `Not for …; see /x:y.`), 120–400 chars; `argument-hint` if it takes an argument

- 3. Run `bun run lint:skills` to validate

- 4. Add documentation page in `apps/docs/content/docs/<domain>/<skill>.mdx`

- 5. Update the domain's `meta.json` pages array

- 6. In `apps/docs`, run `bun run gen:data` and commit `lib/site-data.json` and `lib/search-commands.json`

- 7. In `apps/docs`, run `bun run codemod` so the new page gets `kind`/`command` frontmatter

+ ## Adding a domain

- `bun run check:plugins` fails until steps 6–7 are done.

+ 1. Create its skills as above, named `<domain>-<skill>`. A domain name with a hyphen also goes in `HYPHENATED_DOMAINS` in `packages/skill-validator/src/parse-skill.ts` and `packages/pack-tools/src/skills.ts`.

+ 2. Write `workflows/<domain>.yml` with its phases, member skills, artifacts and `requires`.

+ 3. Put reference docs used by several of its skills in `references/<domain>/`.

+ 4. Regenerate: `gen:gates`, `gen:references`, `gen:adapters` (in `packages/pack-tools`).

+ 5. Add its docs pages in `apps/docs/content/docs/<domain>/`, the sidebar entry in `apps/docs/content/docs/meta.json`, and the domain in `apps/docs/lib/domains.ts`; then `bun run gen:data` and `bun run codemod` in `apps/docs`.

+ 6. Update the domain table in `README.md` (`check:pack` checks its counts), then run `bun run lint:skills` and `bun run check:pack`.

- ## Key Files

+ ## Key files

- - `.claude-plugin/marketplace.json` — all registered plugins

- - `apps/docs/content/docs/meta.json` — sidebar navigation

- - `packages/skill-validator/src/rules.ts` — validation rules and recognized verbs

- - `apps/docs/next.config.mjs` — basePath `/metapowers` for GitHub Pages

- - `fumadocs-ui`/`fumadocs-core` are pinned to `~16.8.1` because three files depend on their internals: `apps/docs/components/docs/sidebar.tsx`, the popover selector in `apps/docs/app/global.css`, and `apps/docs/components/search.tsx`; recheck all three before bumping

+ - `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`: the one Claude plugin and its marketplace entry.

+ - `workflows/*.yml`: the source of every gate and of the conductor's phases.

+ - `packages/skill-validator/src/rules.ts`: validation rules and recognized verbs.

+ - `apps/docs/content/docs/meta.json`: docs sidebar.

+ - `fumadocs-ui`/`fumadocs-core` are pinned to `~16.8.1` because three files depend on their internals: `apps/docs/components/docs/sidebar.tsx`, the popover selector in `apps/docs/app/global.css`, and `apps/docs/components/search.tsx`; recheck all three before bumping.