Stabilizer Skill V1.0

Stabilizer is a capability-first, tool-aware skill specification for agentic coding tools. It defines a skill as a schema-validated JSON package rather than a long prompt: manifest, execution graph, runtime contract, validation layer, recovery policy, capability model, resources, metrics, and optional interpreter proof.

The reference skill in this repository is static-repair-protocol, a project-wide static repair protocol that activates before code changes on an existing project. It discovers available environment tools, maps target artifacts to the strongest available validation paths, groups errors by root cause, applies only sample-validated smallest-safe-scope fixes, and blocks feature work until validation is clean or a deterministic handoff terminal is reached.

Purpose

Stabilizer exists to make operational repair skills portable, verifiable, and executable by any AI tool or agent that can read JSON. It is not bound to Codex, Claude, OpenAI, Anthropic, Gemini, MCP, Cursor, or any specific runtime.

The core philosophy is unchanged:

• project-wide static analysis first;
• root-cause grouping;
• smallest safe fix;
• validation after every repair cycle;
• no feature work before the target is clean;
• deterministic verification over assumptions;
• repair error classes, not isolated symptoms.

Package Structure

stabilizer/
├── README.md
├── validate.py
├── interp.py
├── launcher.json
├── launcher.py
├── schema/
│   ├── meta-schema.json
│   └── runtime-contract-schema.json
└── skills/
    └── static-repair-protocol/
        ├── SKILL.md
        ├── manifest.json
        └── runtime-contract.json

Project Definition

A Stabilizer skill package contains:

1. manifest.json: the binding skill specification, including identity, activation, scope, inputs, preconditions, capability model, execution graph, decisions, safety rules, tool policy, validation, output contract, recovery, examples, resources, and metrics.
2. runtime-contract.json: the generic execution model for interpreting graph nodes, action references, adapter selection, fallback chains, coverage gaps, decisions, parallel branches, merges, recovery nodes, state, cycle counters, success, failure, launcher behavior, and capability-first execution order.
3. SKILL.md: a lightweight discovery file for tools that scan for Markdown skill entry points.
4. schema/*.json: validation schemas for the manifest and runtime contract.
5. validate.py: the dependency-free package audit.
6. interp.py: an optional deterministic proof that the graph and capability model can be interpreted.
7. launcher.json: the machine-readable startup protocol specification.
8. launcher.py: the public entrypoint implementation.

🔹 Launcher

The launcher is the single public entrypoint for Stabilizer. It enforces capability-first execution by mandating that capability discovery and coverage matrix generation complete before any repair begins, then executes the manifest repair workflow through to a terminal node.

• Run the launcher:

python3 launcher.py [--workspace PATH] [--manifest PATH]
                     [--target PATH ...] [--initial-error-count N]
                     [--simulate-gap-suffix SUFFIX ...]

• prompt runner:

Run the Stabilizer Skill from "./stabilizer" against the current workspace (excluding "./stabilizer") exactly as defined, then continue until clean or human handoff.

The launcher performs the startup protocol in order (defined in launcher.json):

1. Discovers the installed Stabilizer package
2. Loads and validates the active manifest and runtime contract
3. Resolves the target workspace
4. Runs capability discovery (available validators, parsers, linters, etc.)
5. Generates the mandatory coverage matrix (maps every artifact to strongest available validator)
6. Selects validators and fallback chains
7. Gates on unresolved coverage gaps — stops at n18_terminal_human_handoff if validation coverage is exhausted
8. Executes the manifest execution graph from n00_discover_capabilities through static analysis, grouping, sample-gated smallest-safe-scope repair, revalidation, regression checks, bounded repair loops, and deterministic verification
9. Reaches a terminal node (clean, partially_clean_max_cycles_reached, aborted, or human_handoff_required) and emits structured output matching the manifest's output contract

The launcher does not stop after readiness checks. When the coverage matrix is clean it actually runs the repair workflow. When coverage gaps remain it stops at the human-handoff terminal and reports the gaps. The launcher never proceeds to automated repair when coverage gaps block deterministic verification of affected artifacts.

CLI flags:

• --workspace PATH — target workspace path (defaults to the Stabilizer package directory)
• --manifest PATH — manifest path relative to the package root (defaults to skills/static-repair-protocol/manifest.json)
• --target PATH — explicit target artifact, relative to workspace; repeatable; defaults to the full project surface
• --initial-error-count N — simulated baseline error count for the reference repair workflow (default 3)
• --simulate-gap-suffix SUFFIX — force a coverage gap for artifacts with this suffix, for exercising the human-handoff path; repeatable and proof-only

All output is deterministic and machine-readable JSON conforming to manifest.output_contract.schema.

Capability Discovery

Before any repair or edit, Stabilizer must inspect the current environment and project surface. A conforming runtime discovers validators, parsers, linters, compilers, formatters, test runners, smoke-check tools, package scripts, and project-native verification commands.

Discovery is capability-based, not language-list-based. Implementations may support any programming-related artifact by adding adapters that declare what they can validate and how strong that validation is.

Validator Selection

For each target artifact, Stabilizer builds a validation coverage matrix. The runtime maps every target artifact to the strongest available deterministic validation path.

The selection order is generic:

1. project-declared validator;
2. artifact parser or compiler;
3. static analyzer or linter;
4. formatter check;
5. test or smoke check;
6. readability or integrity check.

This order is a capability ranking, not a fixed language stack.

Fallback

If the preferred validator is unavailable or cannot start, the runtime tries the next compatible adapter. Fallback continues until a validator succeeds or the compatible chain is exhausted.

The final report must distinguish:

• what was verified by the strongest available tool;
• what was verified through fallback;
• which preferred tool was missing or failed;
• which artifacts remain unverified.

Coverage Gaps

A coverage gap exists when no compatible validator or acceptable smoke check remains for a target artifact. Stabilizer must not silently skip that artifact.

When a gap affects an artifact that would be repaired or edited, execution stops at n18_terminal_human_handoff. The report must include the artifact path, artifact family, missing capability, attempted fallbacks, and required human action.

Human Handoff

Human handoff is a deterministic terminal state, not an error hidden in prose. It is used when the runtime cannot verify the affected target surface with available tools.

The handoff report must state:

• what can be verified now;
• what was verified with fallback tools;
• what cannot be verified;
• what must be installed, configured, or manually checked next.

Execution Flow

The reference skill starts at n00_discover_capabilities in manifest.json. A conforming runtime must complete capability discovery and coverage gating before static repair begins.

Node behavior is defined by runtime-contract.json:

• action: resolve action_ref through the action binding layer and adapter selection model.
• decision: evaluate decision_policy_ref rules in order and transition to the selected node.
• parallel_split: create deterministic branch states in manifest order.
• merge: wait according to merge_strategy and merge branch history deterministically.
• terminal: stop and emit output matching output_contract.schema.

Recovery nodes are explicit graph nodes whose IDs begin with r. They are not implicit prose instructions.

Runtime Contract

The runtime contract is intentionally generic. It defines capability discovery, adapter selection, validator fallback policy, coverage gap policy, optional interpreter gating, human handoff behavior, graph execution, state, cycle control, success, failure, and determinism.

The contract does not require any specific model provider, shell, editor, protocol, language, or orchestration system.

Validation Flow

Run the full package audit:

python3 validate.py

The validator checks JSON validity, manifest structure, runtime contract presence, capability model presence, action binding coverage, duplicate IDs, missing references, invalid transitions, recovery graph integrity, reachability, terminal reachability, resource paths, documentation consistency, package artifact coverage, fallback/handoff contract fields, launcher presence and wiring, capability-first execution order enforcement, and renamed interpreter references.

Run the optional executable proof:

python3 interp.py

The interpreter demonstrates capability discovery, adapter selection, fallback selection, optional proof gating, bounded repair loops, deterministic coverage reporting, and final output generation. It is an optional proof path, not the only source of correctness.

Installation / Setup

No third-party dependencies are required. Use Python 3.11 or newer for the validator and optional interpreter proof.

To install the reference skill in an agentic tool, copy skills/static-repair-protocol/ into the tool's skill or context directory. Tools that understand SKILL.md can discover the skill from that file. Tools that do not can read manifest.json directly.

Invocation / Usage

Invoke the reference skill when:

• a user requests a code change in an existing project;
• a build, compile, import, type, lint, parser, formatter, test, or smoke-check failure is present;
• the user explicitly says stabilizer, run static repair protocol, or fix errors.

The preferred entrypoint is python3 launcher.py [--workspace PATH] (see the Launcher section for all flags). The launcher discovers the package, loads the manifest and runtime contract, runs capability discovery, generates the coverage matrix, gates on coverage gaps, and executes the repair workflow through to a terminal node.

A runtime must read manifest.json, validate it, read runtime-contract.json, validate it, execute the graph from the entry node, and refuse automated repair when coverage gaps block deterministic validation.

Versioning

schema_version identifies the manifest schema version. identity.version identifies the reference skill version. runtime-contract.json has its own contract_version so execution semantics can evolve independently.

Backward compatibility rule: do not remove existing manifest fields or change their semantics without a major version change. New optional fields are preferred when extending the specification.

Extension Strategy

To add another Stabilizer skill or adapter:

1. Create or update skills/<skill-id>/manifest.json.
2. Keep capability discovery generic; do not hardcode the skill to one language family.
3. Add adapters by capability class: parser, compiler, linter, formatter, test runner, smoke check, or project-native validator.
4. Ensure every action_ref, decision_policy_ref, graph transition, recovery node, coverage/handoff terminal, and resource path is defined.
5. Update runtime-contract.json when execution semantics change.
6. Run python3 validate.py and python3 interp.py.

Maintenance Notes

This project should not be modified arbitrarily. Changes must preserve the core architecture: JSON-first specification, explicit execution graph, capability discovery, strict validation, sample-gated repairs, fallback transparency, coverage gap reporting, recovery paths, bounded repair cycles, deterministic output, and tool independence.

Before publishing or merging changes, run:

python3 validate.py
python3 interp.py

Copyright / Ownership

Stabilizer is created and maintained by NiteO9. The reference package declares the MIT license in manifest.json. Add a standalone LICENSE file before external distribution if a hosting platform or package registry requires one.