Open-source skills for designing and reviewing software with AI agents
Contributing to the Elephant-Goldfish Model (EGM) Plugin
We welcome contributions! We all benefit when new ideas, skills, and reviewer perspectives are shared across the open-source community.
Which track is my change?
Pick a track before you open an issue or PR. The full rules for each track are in Contribution Tracks & Workflow; this section points to them.
- Small fix within the Track 1 limits: open a PR with the PR template.
- New feature, architectural change, or anything over the Track 1 limits: open a feature proposal issue and follow the Track 2 steps. Existing design docs are listed in docs/designs/README.md.
Design Principles
These general principles guide development of the EGM framework:
- Humans Own the Outcomes: AI is an exploration and review partner, but human engineers remain responsible for all design decisions and code.
- Artifact-First UX: Large proposals, drafts, and reviews belong in dedicated files, not dumped into chat streams.
- Living Specifications: Code and design specifications must evolve together.
Contribution Tracks & Workflow
Write a short PR title that starts with an action verb. Use sentence case and
describe the change. Omit unnecessary words when the meaning stays clear.
Keep articles such as "a" and "the" when needed for clarity.
Example: Explain ignored agents folder warning in Claude Code.
Add applicable labels: docs for documentation, site for the website,
ci for GitHub Actions, or deps for dependencies. If you cannot apply labels,
suggest them in the PR description. Maintainers control design-ready and
pr-ready. Automation manages design-needed.
All contributions must comply with our AI & Automated Contribution Policy: every pull request requires a human author who has reviewed and tested the change. They should be able to explain it themselves.
Contributions follow a two-track intake model defined in
.github/PULL_REQUEST_TEMPLATE.md:
Track 1: Bug Fix / Minor Patch (<= 100 Non-Test Lines, < 3 Core Files)
Targeted fixes, typo corrections, and test additions that do not alter core
agent behavior or touch 3+ core files (skills/, agents/) can be
submitted directly as a Pull Request without a prior issue or design document.
PRs exceeding these limits without an approved design doc receive an advisory label
(design-needed) recommending two-stage alignment.
Track 2: Feature / Architectural Change (Two-Stage Alignment)
Any new skill, persona, or change exceeding 100 non-test
lines (or touching >= 3 core files in skills/ or agents/)
follows the EGM Spec-Driven Development process:
Reach Out & Align (
design-ready): Before investing in a large implementation or full specification, open a Feature / Architectural Inquiry Issue (.github/ISSUE_TEMPLATE/feature_proposal.md) outlining the problem statement and proposedGoalsvs.Non-Goals. We recommend using/egm-brainstormto complete this section. Maintainers will review and applydesign-readyonce aligned on direction.Draft & Review Design Specification: Draft a technical design specification under
docs/designs/<name>.md. We recommend using/egm-draft, and registering it indocs/designs/README.md. We also recommend running/egm-review docs/designs/<name>.mdto stress-test the proposal.Submit a Design Doc PR (
pr-ready): Open a dedicated Design Doc PR containingdocs/designs/<name>.mdanddocs/designs/README.md(referencing your aligned issue withRefs #<issue>rather thanCloses #<issue>so the issue stays open). When maintainers merge the Design Doc PR, the specification is checked into the codebase and maintainers manually transition the issue label topr-ready.Submit the Implementation PR: Once the specification is merged and your issue is labeled
pr-ready, open the implementation PR (Closes #<issue>) referencingdocs/designs/<name>.md.
Automated Validation & Testing
- Skill Definitions: Ensure all
SKILL.mdfiles contain valid YAML frontmatter (name,description, and optionaldisable-model-invocation). - Evaluation Suites: Skills must include a co-located behavioral
evaluation suite in
skills/<skill_name>/test_scenarios.yamland verification instructions inskills/<skill_name>/TEST.md. See TESTING.md for running static checks (pytest tests/unit). - Formatting: Format markdown files cleanly using standard formatters (e.g., Prettier or markdownlint).
Contributor License Agreement (CLA)
Contributions to this project must be accompanied by a Contributor License Agreement (CLA). You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project.
If you or your current employer have already signed the Google CLA (even if it was for a different project), you probably don't need to do it again.
Visit https://cla.developers.google.com/ to see your current agreements or to sign a new one.
Community Guidelines
See our accessibility statement for goals, current limits, and how to report accessibility barriers.
This project follows Google's Open Source Community Guidelines.