# Skill Registry — Canonical Names

This file is the single source of truth for every skill in the `@civitas-cerebrum/element-interactions` suite. Agents MUST copy skill names from this registry verbatim — never reconstruct them from memory, never re-case them, never paraphrase.

**How to use:**
- Invoking a skill via the Skill tool → copy the value in **Invocation string** exactly.
- Writing prose that references a skill → copy the value in **Skill name** exactly, backticked.
- Cross-linking between `SKILL.md` files → use the **Skill name** as slug.

Names drift silently. A `coverage-expansion` written as `Coverage Expansion` in one doc and `coverage_expansion` in another doesn't fail any compiler — it just quietly confuses downstream agents. This registry is the fix.

---

## Registry

| Skill name | Invocation string | Owner orchestrator | Activation triggers |
|---|---|---|---|
| `element-interactions` | `element-interactions` | — (top-level orchestrator) | Any request to test, automate tests, or verify application behaviour ("test the app", "test this", "lets test", "write tests", "add tests", "run tests", "automate tests", "test automation", "e2e tests", "browser testing", "UI testing", "functional testing", "smoke test", "regression test", "QA", "quality assurance"); any mention of Playwright (including writing, fixing, adding, or running Playwright tests); framework keywords (`@civitas-cerebrum/element-interactions`, `@civitas-cerebrum/element-repository`, Steps API, `baseFixture`, `ContextStore`, `page-repository.json`). The three clauses are independent — any one of them triggers the skill; Playwright is a keyword trigger alongside the general test/automate intent, not a gate over it. |
| `onboarding` | `onboarding` | `element-interactions` (cascade-detector routes here when project is not onboarded) | "onboard this project", "set up element-interactions", "start from scratch", "automate this app from zero"; auto-invoked when the cascade detector finds a missing framework dep / missing scaffold / missing sentinel-bearing `journey-map.md`. |
| `journey-mapping` | `journey-mapping` | `onboarding` (Phase 4), `coverage-expansion` (prerequisite) | "map the app", "discover user journeys", "map user flows", "understand the app"; auto-invoked before coverage expansion or any large-scale test composing activity when a sentinel-bearing `journey-map.md` is missing or stale. |
| `coverage-expansion` | `coverage-expansion` | `onboarding` (Phase 5) | "increase coverage", "expand tests", "iterative coverage", "deep coverage pass"; auto-invoked by `onboarding` Phase 5. Three modes: `breadth` (one horizontal sweep, fast), `standard` (DEFAULT — 3 compositional + 2 adversarial passes + ledger dedup, journey-by-journey), `depth` (strict per-journey parallel on every pass, ~20× dispatch cost, explicit opt-in for high-fidelity audits). |
| `test-composer` | `test-composer` | `coverage-expansion` (per journey, compositional passes 1–3) | "write all tests for the login journey", "compose tests for journey X", "think like a QA for this journey"; auto-invoked once per journey per compositional pass by `coverage-expansion`. |
| `bug-discovery` | `bug-discovery` | `onboarding` (Phase 6), `coverage-expansion` (adversarial passes 4–5, scoped per journey) | "find bugs", "break the app", "bug hunt", "quality audit", "edge case testing", "stress test the app", "exploratory testing", "find issues"; auto-invoked per journey inside `coverage-expansion` adversarial probe subagents, or cross-app by `onboarding` Phase 6. |
| `failure-diagnosis` | `failure-diagnosis` | Any skill that runs tests; explicit Phase-6 handoff target for `companion-mode` on a FAILED-verdict bundle | A test fails during any mode (authoring, maintenance, `test-composer`, `bug-discovery`, `companion-mode` Phase 6); "test is failing", "debug this", "why is this failing", "fix this test". |
| `test-repair` | `test-repair` | `element-interactions` (on user request); auto-escalated from `failure-diagnosis` / `test-composer` / `bug-discovery` when a single run produces many failures | "repair the suite", "fix my tests", "restore green", "heal the suite", "the tests are broken", "the suite rotted", "triage the failures", "my suite is flaky". |
| `self-repair` | `self-repair` | `element-interactions` (on user request); invoked non-interactively by the `achilles-self-repair` CLI driver (`npm run test:repair`, wired by `onboarding` Phase 1 scaffold) | "self repair", "self-repair the suite", "run self repair", "autonomous repair", "repair per file", "run test:repair". Autonomous per-file repair: baseline ×3 → classify (deterministic vs flaky) → one `repair-worker-<file-slug>:` worker per red spec file (each loads `failure-diagnosis`) → suite-order verification → `.achilles/self-repair/<run-id>/report.{md,json}`. Cluster-first in-session batch triage stays with `test-repair`; a single failing test stays with `failure-diagnosis`. |
| `agents-vs-agents` | `agents-vs-agents` | `element-interactions` (when app has AI features) | "test AI guardrails", "adversarial testing", "red team the AI", "test for bias", "prompt injection testing", "AI safety testing", "agents vs agents", "AI compliance testing", "guardrail verification". |
| `contract-testing` | `contract-testing` | `element-interactions` (when a test consumes a backend HTTP endpoint) | "contract test", "API contract", "schema test", "consumer-driven contract", "provider verification", "pact test", "breaking change detection", "OpenAPI conformance", "lock API contract"; auto-invoked whenever a test (API-only or UI-flow) emits any `steps.api*` / `steps.verifyApi*` call. |
| `work-summary-deck` | `work-summary-deck` | `onboarding` (Phase 8) | "generate a report", "export a deck", "summarize work", "create a presentation", "QA report", "achievement report", "progress deck"; auto-invoked by `onboarding` Phase 8. On-demand only — never activates during test writing or debugging workflows. |
| `secrets-sweep` | `secrets-sweep` | `onboarding` (Phase 7) | Phase-7 methodology for extracting hardcoded credentials, API keys, PII-shape literals, and app URLs out of a test suite into `.env`. Final guardrail before publishing a suite or treating it as portable across environments; auto-invoked by `onboarding` Phase 7. Returns conform to the ComposerReturn schema. |
| `database-testing` | `database-testing` | `element-interactions` (when a test reads from or asserts against a SQL database) | "database test", "SQL test", "query the db in a test", "verify db state", "assert the database", "check the table", "data-layer test", "persistence test"; auto-invoked whenever a test (UI- or API-flow) emits any `steps.sqlQuery/sqlExecute/sqlTransaction/sqlSelect/sqlInsert/sqlUpdate/sqlDelete` or `steps.verifySql*` call. Adds the persistence layer as a verifiable oracle (L3). |
| `performance-testing` | `performance-testing` | `element-interactions` (when the user wants to load/stress/soak-test or measure performance with k6) | "load test", "performance test", "perf test", "k6", "stress test the endpoint", "spike test", "soak test", "breakpoint test", "check p95 under load", "latency under load", "how many concurrent users", "throughput test", "requests per second", "SLO", "performance budget". Sibling of `contract-testing` / `database-testing`; runs inline. Load / throughput / latency-under-concurrency routes here — adversarial functional probing ("stress test the app") stays with `bug-discovery`. |
| `bug-report` | `bug-report` | `element-interactions` / `bug-discovery` (when a found defect needs a tracker ticket) | "write a bug ticket", "create a defect report", "file an issue", "report this bug to Jira"; used when a defect, issue, or unexpected behaviour found during testing needs to be reported in a defect-tracking system (Jira). |
| `test-catalogue` | `test-catalogue` | `element-interactions` (on user request) | "produce a test catalogue", "generate a scenario report", "catalogue the suite", "client-ready catalogue", "export the scenario inventory"; any request for a stakeholder-facing list answering "what scenarios are we running, and why?". Opt-in and on-demand only — never activates during test writing, coverage expansion, repair, or debugging. Requires a sentinel-bearing `journey-map.md` and at least one spec file. |
| `workflow-reviewer` | `workflow-reviewer` | Subagent-only; dispatched by `onboarding`, `coverage-expansion`, and `journey-mapping` as `workflow-reviewer-phase<N>:` / `workflow-reviewer-pass<N>:` / `workflow-reviewer-cycle<N>:` | Reviews the closing handover of an onboarding phase, a coverage-expansion pass, or a journey-mapping cycle against the canonical methodology exit criteria; returns verdict `approve \| reject \| escalate` per the `workflow-reviewer.schema.json` contract. Owns the 3-cycle reject cap and the skip / early-stop authorisation rules. Triggers when the brief carries one of the three role prefixes, or when the orchestrator names the skill in a Skill-tool invocation. |
| `companion-mode` | `companion-mode` | `element-interactions` (on user request); never auto-invoked by another companion. May INVOKE `element-interactions` (Phase-6 graduation, `entry: "stage3"`), `onboarding` (Phase-6 full-onboarding handoff), or `failure-diagnosis` (Phase-6 deferred-automation handoff on FAILED verdict) — all on explicit user assent. | "companion mode", "companion entry mode", "QA companion", "verify this flow with evidence", "evidence package for X", "screenshot every step", "record this scenario", "video of this flow", "evidence-backed test", "daily QA task", "manual test assistance". Single-task functional verification with an evidence bundle (per-step screenshots + video + trace + HAR + console + summary), followed in Phase 6 by a proactive automation-graduation offer: on a passed verdict the skill runs the onboarding cascade detector and offers either Stage-3 graduation (fully onboarded) or "(a) just this task / (b) full onboarding" (Level A/B/C). The handoff requires an explicit `yes / (a) / (b)` from the user; vague replies get a clarifying re-prompt. Failed/inconclusive verdicts defer the automation question until `failure-diagnosis` or a retry resolves the verdict. |
| `contributing-to-element-interactions` | `contributing-to-element-interactions` | — (cross-cutting; invoked from any skill or by the user when a package-level change is needed) | Two trigger families. **(A) API gap:** "extend the Steps API", "add a new method to ElementAction", "no equivalent in the framework", "the package doesn't have", "missing API in element-interactions", "missing matcher", "drop down to raw Playwright", "fall back to page.locator", "the framework doesn't expose X", "how do I add to this framework". **(B) Structural / framework / protocol gap** (the case the package itself can't satisfy): "the framework can't satisfy", "framework limitation", "this rule cannot be satisfied", "the package's architecture prevents", "structural gap", "protocol gap", "isolation can't be guaranteed", "this prereq isn't satisfiable", "the underlying tooling doesn't support", "should I file an issue against the package", "is this a skill issue or a package issue", "do we need to change the package to fix this". Auto-invoke whenever a skill is about to silently weaken or skip a documented invariant because the package can't back it. Also: "contribute to element-interactions", any request to modify files under the package's `src/`, opening an issue/PR against this repo. |
| `selector-development` | `selector-development` | `failure-diagnosis` (when a fragile selector is diagnosed), `test-composer` (when Stage 2 finds no stable selector and frontend source is in the workspace) | "add stable selectors", "audit selectors across the app", "selector is too fragile"; auto-invoked when `failure-diagnosis` reports fragile-selector root cause AND frontend source is in workspace, or when `test-composer` Stage 2 exhausts selector strategies for an element. |
| `perf-onboarding` | `perf-onboarding` | — (top-level orchestrator; user-invoked) | "perf-onboard this project", "performance onboard", "set up the performance pipeline", "autonomous perf suite", "load-test the whole app end to end", "build a perf suite from zero". Autonomous seven-phase k6 performance pipeline (scaffold → readiness → scenario-model → baseline → load-run → threshold-gate → report), enforced by the perf ledger + `perf-onboarding-ledger-gate.sh` + `perf-reviewer-*` at every phase/pass transition. Distinct from the `performance-testing` COMPANION skill (which it dispatches for per-scenario authoring). |
| `ticket-driven-testing` | `ticket-driven-testing` | — (top-level orchestrator; user-invoked). INVOKES `companion-mode` for the evidence run, and may route to `bug-report` for defects and `contributing-to-element-interactions` for framework gaps. | A tracker ticket is the unit of QA work: a QA ticket paired to a dev ticket, a PR awaiting QA sign-off, "test this feature" naming an issue key, "QA this branch", "automate the tests for <TICKET>", "verify the acceptance criteria", "produce evidence for <TICKET>". Wraps `companion-mode` with the ticket, branch and diff context its Phase 1 presumes: ticket intake (QA ticket **and** parent), PR review-state as a QA signal, worktree isolation, diff review before touching the app, then durable regression tests plus a `test.fail()` sentinel per confirmed defect. Also owns the **"show me"** contract — headed, `slowMo` ≥ 1500ms, serial, recorded, mp4 when an encoder is available. Free-standing "verify X with evidence" with no ticket or branch stays with `companion-mode`. |

---

**SKILL.md path convention.** Every skill's main doc lives at `skills/<skill-name>/SKILL.md` — slug the Invocation string to get the path. Reference docs live under `skills/<skill-name>/references/`. For example, `coverage-expansion` → `skills/coverage-expansion/SKILL.md`.

---

## Non-skill sentinel strings

Some markers in the workflow are not skill names but are case-sensitive and must also be copied verbatim:

| String | Purpose | Where it appears |
|---|---|---|
| `<!-- journey-mapping:generated -->` | Sentinel on line 1 of `tests/e2e/docs/journey-map.md`; confirms the map was produced by `journey-mapping` and is in the precise-embedding format. | First line of `tests/e2e/docs/journey-map.md`. |
| `<!-- coverage-expansion-adversarial:generated -->` | Sentinel on line 1 of `tests/e2e/docs/adversarial-findings.md`; confirms the ledger was produced by a Pass-4 subagent and conforms to the canonical schema. | First line of `tests/e2e/docs/adversarial-findings.md`. |
| `<!-- app-wide-scan:generated -->` | Sentinel on line 1 of `tests/e2e/docs/app-wide-patterns.md`; confirms the file is the canonical Pass-4-prelude scan output and serves as the resume signal (per `coverage-expansion/references/app-wide-scan.md` Hard constraint #1). | First line of `tests/e2e/docs/app-wide-patterns.md`. |
| `<!-- subagent-returns:reviewer:<JOURNEY>:pass-<N>:cycle-<C> -->` | Per-journey Stage B reviewer spill file (legacy gap — exists in `subagent-return-schema.md` §2.6 + `reviewer-subagent-contract.md` but was previously unlisted here). | Line 1 of `tests/e2e/docs/.subagent-returns/reviewer-<JOURNEY>-<pass>-c<cycle>.md`. |
| `<!-- subagent-returns:reviewer-batch:pass-<N>:cycle-1 -->` | Batch reviewer spill file (compositional Pass 1/2/3 cycle-1 only). One spill file per pass, with `## <JOURNEY>` sections inside. The batch reviewer never appears at cycle-2+ or in adversarial passes. | Line 1 of `tests/e2e/docs/.subagent-returns/reviewer-batch-pass-<N>-c1.md`. |
| `<!-- perf-onboarding:scenario-model -->` | Sentinel on line 1 of `tests/perf/docs/scenario-model.md`; confirms the scenario model was produced by the `perf-onboarding` Phase 3 subagent. The `perf-onboarding-ledger-write-gate.sh` hook denies a phase-3 → completed transition if this sentinel is absent. | First line of `tests/perf/docs/scenario-model.md`. |
| `<!-- perf-onboarding:report -->` | Sentinel on line 1 of `tests/perf/docs/perf-report.md`; confirms the report was produced by the `perf-onboarding` Phase 7 subagent. The `perf-onboarding-ledger-write-gate.sh` hook denies a phase-7 → completed transition if this sentinel is absent. | First line of `tests/perf/docs/perf-report.md`. |
| `autonomousMode: true` | Invocation flag passed to `element-interactions` by companion skills to disable hard gates. | `args` when `onboarding` Phase 3 (`entry: "stage1"`) or `companion-mode` Phase 6 (`entry: "stage3"`) invoke `element-interactions`. |
| `mode: breadth` / `mode: standard` / `mode: depth` | `coverage-expansion` run-mode selector (`standard` is the default). | `args` when invoking `coverage-expansion`. |
| `mode: live` / `mode: static` | `bug-discovery` probing-mode selector. | `args` when invoking `bug-discovery` (static mode is first-class, not a fallback — see that skill's §"Static mode — first-class adversarial probing"). |
| `mode: re-pass` | `test-composer` pass-2/3 discipline selector. | `args` when `coverage-expansion` dispatches `test-composer` for Pass 2 or Pass 3. |
| `<!-- performance-testing:generated -->` | Sentinel on line 1 of `tests/perf/docs/perf-report.md`; confirms the report was produced by `performance-testing`. | First line of `tests/perf/docs/perf-report.md`. |

---

## Companion reference docs

The registry is one of two canonical reference documents in this directory. Callers should treat both as authoritative:

| Reference | Scope |
|---|---|
| [`skill-registry.md`](skill-registry.md) (this file) | Canonical skill names, invocation strings, sentinel strings. |
| [`subagent-return-schema.md`](subagent-return-schema.md) | Canonical subagent finding-return format, the coverage-expansion result enum (`new-tests-landed`, `covered-exhaustively`, `blocked`, `skipped`), and the adversarial-ledger schema. |
| [`cascade-detector.md`](cascade-detector.md) | Canonical onboarding-state probe (Levels A/B/C/None) and caller-specific responses. Cited by `onboarding`, `element-interactions` (routing), and `companion-mode` (Phase 6) — drift between callers is the bug it exists to prevent. |
| [`playwright-cli-protocol.md`](playwright-cli-protocol.md) | Canonical browser-automation primitive: `@playwright/cli` session model, parallel-isolation guarantee, dispatch-brief template, snapshot/ref-ID format, auth-state replay, lifecycle, troubleshooting. Replaces the prior MCP-based protocol and dissolves the Rule-11-era isolation prereq check. Cited by every skill that drives a live browser. |

Commit-message conventions for every pass in every skill are governed by `coverage-expansion`'s §"Commit-message conventions" (the per-pass table) and referenced from `test-composer` and `bug-discovery`. If a commit template drift is observed, fix the table in `coverage-expansion/SKILL.md` first; the caller skills cite it rather than re-defining it.

---

## Maintenance

- **Adding a skill:** add a row to the registry, scaffold `skills/<skill-name>/SKILL.md` with YAML frontmatter whose `description` follows the "Use when..." format (per the `superpowers:writing-skills` guidance — triggering conditions only, no workflow summary), and add a "Skill names: see registry" note near the top of the new SKILL.md pointing here.
- **Renaming a skill:** do NOT. Renaming breaks every caller that copied the old name. If rename is unavoidable, land it as a single PR that updates the registry plus every caller in one commit.
- **Deprecating a skill:** mark the row with a strikethrough and add a "Deprecated — use `<replacement>` instead" note in the skill's `SKILL.md`. Keep the registry row until the skill is removed.
- **Changing an invocation string:** same rule as renaming. The invocation string is part of the public contract — do not change it independent of the skill name.
- **Adding a sentinel string:** append to the "Non-skill sentinel strings" table with a purpose and location. Every sentinel in the codebase that callers rely on belongs in that table; drift in the other direction (sentinel used somewhere but not listed here) is a bug.