Asw Programming

Antigravity Swarm Programming

Use this skill when editing source code, tests, hook scripts, installer logic, package scripts, or generated-asset tooling.

Language Gate

Before editing:

1. Identify the language and runtime.
2. Read local project conventions.
3. Find the authoritative test command.
4. Find typecheck, lint, format, and package commands if present.
5. Write or identify the RED test before production edits.

Do not start implementation from memory. Let the repo tell you how code is shaped.

Shared Philosophy

The Type System Is A Proof System

Make invalid states hard to express:

• use semantic names for IDs, paths, modes, states, and options,
• prefer discriminated variants over loose strings,
• keep nullable values near the boundary,
• do not use catch-all shapes when the variants are known.

Parse, don't validate

Untrusted input crosses a boundary once:

• CLI args,
• JSON payloads,
• config files,
• environment variables,
• hook payloads,
• package manifests,
• external API responses.

At that boundary, parse into a typed or structured value. Inside the code, operate on parsed values instead of re-validating the same assumptions.

One name, one concept

Avoid using one primitive to represent several concepts. A path, package name, plugin id, color, model label, and command are different concepts even if all are strings.

Exhaustive variants

When handling modes, commands, languages, colors, result states, or hook phases, make the handling exhaustive. Unknown values should fail clearly at the boundary.

Small files, honest ownership

Use a 250 pure LOC ceiling as a warning. A file above that line count needs either a clear reason or a split by responsibility. Split by concept, never by chunk number.

TDD Contract

Use RED to GREEN for behavior changes:

1. Name the observable behavior.
2. Write the failing test or reproduction.
3. Capture RED output.
4. Implement the smallest change.
5. Capture GREEN output.
6. Run the real surface when users can observe the change.

For refactors, write or identify characterization coverage first. The test should be green before the refactor and stay green after.

Test Pyramid

Use the smallest test that proves the behavior, then climb only when needed:

• pure function tests for deterministic formatting and parsing,
• command tests for CLI arguments and stdout,
• file-system tests for installers and package layout,
• hook payload tests for Antigravity lifecycle behavior,
• integration tests for config merge and installed paths,
• manual QA for terminal rendering, browser rendering, IDE behavior, or generated images.

Avoid replacing a narrow deterministic test with a broad smoke test. Broad smoke tests are useful after the narrow test has made the failure easy to locate.

Given / When / Then

Behavior tests should make the scenario obvious:

• Given: existing config, payload, files, flags, or state.
• When: the command, hook, helper, or UI action runs.
• Then: the observable output, file, error, or status line is asserted.

BDD comments are allowed when they clarify the shape of the scenario. Do not delete them as clutter.

Less Mocking

Prefer real temp directories, real files, real JSON parsing, real process execution, and real stdout when the behavior depends on those surfaces.

Mocks are appropriate when:

• the external service is slow or unavailable,
• the test would mutate a real user account,
• the dependency is nondeterministic,
• the mock captures a stable contract.

If a mock hides path handling, shell output, terminal width, package contents, or config merge behavior, it is probably the wrong test.

Prompt And Skill Tests

Markdown skills and agent prompts are product code in this repo. Test them when they define behavior:

• inventory tests for names,
• section tests for required execution contracts,
• residue tests for private terminology,
• line-depth tests when a port must preserve operational substance,
• README tests when examples must match hook or HUD output.

Do not treat docs as harmless if users copy commands from them.

TypeScript And JavaScript

Prefer:

• explicit command parsing,
• small pure helpers around string formatting,
• Map or object lookup tables for closed sets,
• narrow error handling,
• package tests for npm surfaces,
• no implicit mutation of shared process env unless scoped to the command.

Avoid:

• broad any shapes,
• hidden process exits inside helpers,
• catch-all catch blocks that swallow errors,
• stringly config updates when JSON parsing is available,
• long functions combining parse, IO, rendering, and write phases.

Recommended checks:

• npm test,
• project typecheck if defined,
• targeted script smoke,
• package dry run when shipped files changed.

Python

Prefer:

• small scripts with explicit main,
• typed helper signatures,
• Path for filesystem paths,
• structured command arguments,
• deterministic output for generated assets,
• narrow exceptions around optional fonts or platform-specific paths.

Avoid:

• broad exceptions around core logic,
• comments explaining what a function name already says,
• global writes that cannot be overridden in tests,
• mutable default arguments,
• silently ignoring missing dependencies.

Recommended checks:

• python3 -m py_compile <file>,
• project test,
• run the script through the real command path.

Go

Prefer:

• explicit context propagation,
• structured logging at boundaries,
• small interfaces only where they decouple real implementations,
• table tests for variants,
• clear error wrapping.

Avoid:

• panic for ordinary errors,
• global mutable state,
• broad utility packages,
• interface definitions with one local implementation and no test seam.

Rust

Prefer:

• typed errors,
• exhaustive matches,
• small modules,
• Result over panic,
• clear ownership boundaries.

Avoid:

• unwrap in non-test paths,
• large enum matches without default audit,
• hidden clones in loops,
• unsafe code unless the task explicitly requires it and tests cover it.

Cross-language Iron List

These rules apply everywhere:

• no behavior change without behavior proof,
• no catch-all type when variants are known,
• no duplicate validation inside trusted internal paths,
• no global mutable state unless it is the platform contract,
• no hidden IO inside pure-named helpers,
• no silent fallback that hides broken config,
• no broad exception swallowing,
• no public API removal without explicit request,
• no generated asset change without regeneration proof,
• no package surface claim without dry-run evidence,
• no user-visible text drift from README examples,
• no oversized module split by arbitrary chunk names,
• no new dependency for a small local helper,
• no final status that hides skipped checks.

Canonical Libraries

Prefer established standard or project-local facilities:

• filesystem paths through the language path library,
• JSON through structured parsers,
• TOML/YAML through the project parser when already present,
• CLI args through the existing command parser,
• subprocesses through explicit argv arrays,
• colors through the existing palette or UI helper,
• terminal rendering through tested width-aware helpers,
• image generation through deterministic scripts,
• package validation through the package manager,
• plugin validation through the Antigravity CLI.

Adding a dependency is justified only when it removes real complexity and is acceptable for the package surface.