# Contributing to Godot Clarity

**[Русская версия](CONTRIBUTING.ru.md)**

Thank you for improving how coding agents work with Godot. Keep contributions evidence-driven, portable across Agent Skills clients, and small enough to evaluate.

## Before changing guidance

A useful rule should answer all of these:

1. What observed agent failure does it prevent?
2. Under which Godot version, node/resource type, subsystem, and lifecycle does it apply?
3. Is it a stable decision rule, or should the agent consult an exact class reference instead?
4. What project evidence can distinguish the correct choice?
5. What behavioral check proves the outcome?

Prefer a concise rule plus a versioned official link. Do not copy long passages from documentation, add style preferences as correctness rules, or prescribe a universal game architecture.

## Edit the right layer

- Put selection triggers and the universal workflow in `skills/godot-clarity/SKILL.md`.
- Put subsystem-specific decisions in one directly linked `references/*.md` file.
- Keep reference depth to one level: every reference must be linked from `SKILL.md`.
- Add a contents list to a reference longer than 100 lines.
- Keep durable Godot documentation links pinned to `/en/4.7/` for directly supported guidance; explain branches for older versions.
- Keep `SKILL.md` portable: its YAML frontmatter may contain only `name` and `description`.
- Keep bundled tools dependency-free, read-only by default, deterministic, and portable across the supported Agent Skills clients. Put their tests outside the installable Skill directory.
- Keep eval prompts, fixtures, solutions, CI, and contributor documentation outside the installable Skill directory.

## Change the installer CLI

Keep installer code under `cli/`; never add Node.js or npm files to the portable `skills/godot-clarity` package. Record the next portable archive and SHA-256 in `release/skill-manifest.json`. Update the bundled CLI manifest only after that exact GitHub Release exists. Between those two phases, `release/skill-manifest.json` intentionally describes the new candidate while `cli/src/release-manifest.json` remains pinned to the previous public release. Installation must remain shell-free, staged, path-validated, and non-overwriting by default.

First-class installer targets are Codex, Claude Code, and Cursor. For every target, document and test both project and user destinations, the explicit invocation, and the restart/discovery hint. Keep client-specific paths and messages in the installer; do not fork or rewrite the portable `SKILL.md` for one client.

Run:

```bash
python scripts/test_package_skill.py
npm ci
npm test
npm pack --dry-run
```

Ordinary development tests package the current Skill source without pretending it is the pinned public release. On `v<skill-version>` tags, CI additionally sets `GODOT_CLARITY_VERIFY_RELEASE_SOURCE=1` and requires the source archive SHA-256 to match `release/skill-manifest.json` exactly.

CLI releases use Git tags named `cli-v<package-version>`. Skill releases continue to use `v<skill-version>`. Publish npm prereleases under the `next` dist-tag; do not move `latest` until the CLI is stable.

## Add or change an eval

Each case under `evals/cases/<name>/` contains:

- `prompt.md`: the task presented to a fresh agent;
- `rubric.md`: observable success criteria without implementation trivia;
- `fixture/`: the isolated broken Godot project;
- `solution/`: a reference overlay that makes the same oracle pass.

Register the case in `evals/manifest.json` with a stable `baseline_failure` substring that identifies the intended broken invariant. The verifier must be deterministic, bounded, inherit `SceneTree`, print a useful failure, and exit with `quit(0)` or `quit(1)`. Prefer gameplay invariants over exact floating-point trajectories or source-text matching.

Run:

```bash
python scripts/validate_repo.py
python scripts/test_project_doctor.py
python scripts/run_evals.py --godot /path/to/godot-4.7.1 --mode all
```

Baseline cases must fail for the registered reason and emit exactly one `VERIFY_FAIL`. Reference solutions must pass the same oracle and emit one case-matched `VERIFY_PASS`. Never weaken an oracle merely to make a solution green.

## Evaluate the Skill, not only the fixtures

Before a release, run critical prompts in clean workspaces and fresh agent sessions:

- with the candidate Skill;
- without the Skill or with the previous release;
- using the same agent/model, permissions, fixture, and time budget;
- at least three runs for collision-critical cases.

Record triggering, outcome, verifier result, unnecessary edits, and unsupported claims separately. A deterministic fixture test proves the oracle; it does not prove that an agent will discover and apply the Skill correctly.

The initial release target is all reference solutions passing, all broken baselines failing, no regression on a critical collision case, at least 80% overall agent-eval pass rate, and a meaningful improvement over the no-Skill baseline.

## Pull request checklist

- [ ] The change addresses a concrete Godot-agent failure.
- [ ] Version-sensitive claims use primary, versioned Godot documentation.
- [ ] `SKILL.md` stays concise and all references remain directly linked.
- [ ] A new/updated eval covers material behavior changes.
- [ ] Repository validation and runtime evals pass on Godot 4.7.1.
- [ ] No generated `.godot/`, binaries, credentials, eval results, or unrelated rewrites are included.
- [ ] Compatibility, README, changelog, and notice text are updated when required.

## License

By contributing, you agree that your contribution is licensed under the repository's MIT License.