skills.rest
civitas-cerebrum
civitas-cerebrumOFFICIAL
Explore all skills by this author →
GitHub

contributing-to-achilles-protocol

Guides contributions to the element-interactions Playwright facade package and its skill suite.

5|2|Updated May 19, 2026
Search Tags:#code review#contribution#api design#playwright#e2e testing#testing framework#harness hooks
One-click install
npx skills add https://github.com/civitas-cerebrum/achilles --skill contributing-to-achilles-protocol-civitas-cerebrum
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: contributing-to-achilles-protocol
Source: https://github.com/civitas-cerebrum/achilles/tree/main/skills/contributing-to-achilles-protocol
Command: npx skills add https://github.com/civitas-cerebrum/achilles --skill contributing-to-achilles-protocol-civitas-cerebrum

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Contributing to the @civitas-cerebrum/element-interactions package without breaking its architecture is hard: the package enforces strict invariants (no raw selectors, no raw Playwright Locator calls in user tests, 100% API coverage, no mocked tests), and contributors often cannot tell whether a gap is an API gap, a structural gap, or already fixed upstream. This Skill encodes the full contribution methodology so changes land in the right layer without violating design contracts. ## Core Features & Use Cases - Architecture and decision tree: Explains the two-package split (element-interactions vs. element-repository), layer responsibilities, and a five-step decision tree for where a new API belongs (Element interface, ExpectMatchers, Steps, ElementAction, or BaseFixture). - Hard rules and invariants: Enforces argument order (elementName, pageName), async-everywhere, presence-detection on actions, causally meaningful test assertions, no mocked tests, and mandatory harness hooks for every new methodology rule. - Issue and PR workflow: Mandates duplicate-prevention checks (searching open/closed issues, diffing against origin/main, verifying published dependency versions) and Reported-by attribution for issue-driven commits. - Use Case: A user asks to add a missing matcher to the Steps API. The Skill routes the change to ExpectMatchers, requires a real end-to-end test against the Vue test app with a non-tautological assertion, and requires a harness hook if any SKILL.md rule is strengthened. ## Quick Start Ask the agent to extend the Steps API with a new assertion for the element-interactions package and follow the contribution protocol.

Frequently Asked Questions about contributing-to-achilles-protocol

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new method to the element-interactions Steps API?▼

Follow the decision tree: raw element capabilities go to the Element interface in element-repository, assertions go to ExpectMatchers, composite workflows go to Steps in CommonSteps.ts, and strategy selectors go to ElementAction. Every new public method needs a passing test to maintain 100% API coverage.

How do I tell an API gap from a structural framework gap?▼

An API gap means a method or matcher is missing but the architecture can support it, so you extend the package. A structural gap means a documented rule cannot be satisfied without changing the package's architecture or underlying tooling, which requires a package-level change rather than a skill-level workaround.

Can I use raw Playwright locator calls inside element-interactions?▼

No. Raw locator.click() or locator.fill() calls in src/ are treated as regressions. If Playwright exposes a primitive the Element interface lacks, add it to the Element interface in element-repository first; the WebElement constructor is the only legitimate boundary for raw Locators.

Does the package allow mocked unit tests?▼

No. Every test runs against the real Vue test app via Playwright, because mocked tests would only verify wiring rather than actual Playwright behavior. Tests must also end with assertions that would fail if the exercised method were a no-op.

What checks are required before filing an issue or opening a PR?▼

Search open and closed issues and PRs in both element-interactions and element-repository repos, diff your local branch against origin/main to confirm the gap still exists, and verify the pinned dependency version against the latest published release. Report the results of all three checks in the issue or PR body.

Why must methodology rules ship with harness hooks?▼

Markdown rules alone fail under context pressure because an orchestrator can rationalize around them, as documented in issues #139, #154, #155, and #156. Every rule added to a SKILL.md must ship a corresponding hook in hooks/ that enforces it programmatically, or be explicitly tagged as markdown-only.

Related Skills

Explore More Software Engineering Skills→
ssu96ldssu96ld

magnus-setup

Bootstrap the Magnus Consulting website repository and install dependencies via npm.

Community
Advanced
AzureAzure
27

hotfix-release

Publish npm package hotfixes from Azure TypeSpec release branches with validation and backmerges.

Official
Advanced
zenbuappszenbuapps

wp-abilities-api

Register WordPress Abilities and categories and expose them via REST endpoints.

Official
Intermediate
gittowergittower
413

resolve-issue

Orchestrate GitHub spec issue resolution from analysis through pull request preparation.

Official
Advanced