gear-foundation/sails-program-evolution
skills/sails-program-evolution/SKILL.md
Use when a builder needs to evolve a released Gear or Vara Sails contract, prepare a new deployed contract version, plan safe cutover, or design state migration from V1 to V2. Do not use for greenfield feature work on an unreleased contract, non-Sails repositories, or ethexe-first paths.
$ install --global
skillsauthnpx skillsauth add gear-foundation/vara-skills sails-program-evolutionInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: May 23, 2026, 2:39 AM15.8s1 file scanned
SKILL.md
- name:
- sails-program-evolution
- description:
- Use when a builder needs to evolve a released Gear or Vara Sails contract, prepare a new deployed contract version, plan safe cutover, or design state migration from V1 to V2. Do not use for greenfield feature work on an unreleased contract, non-Sails repositories, or ethexe-first paths.
Sails Program Evolution
Overview
Plan how a released Sails contract evolves after deployment.
Use this skill when the work is no longer just “implement a feature”, but instead requires thinking about versioning, compatibility, cutover, ReadOnly handling, frontend/indexer impact, or migration from V1 to V2.
Start Here
Read ../../references/contract-interface-evolution.md, ../../references/gear-sails-production-patterns.md, ../../references/sails-idl-client-pipeline.md, ../../references/sails-program-and-service-architecture.md, and ../../references/sails-header-wire-format.md.
Use ../../assets/architecture-template.md for the architecture note and ../../assets/task-plan-template.md for the ordered task plan.
Write outputs to:
docs/plans/YYYY-MM-DD-<topic>-architecture.mddocs/plans/YYYY-MM-DD-<topic>-tasks.md
Route Here When
- a released contract must gain a new deployed version
- public routes, replies, or events may change
- frontend or indexer compatibility must be preserved during cutover
- the old contract may need
ReadOnlyor write-disable behavior - a future migration path must be designed even if migration is not implemented now
- state migration from
V1toV2is part of scope
Working Model
- Classify the change first: additive, breaking, migration-readiness only, or migration now.
- Treat Gear/Sails evolution as
V1 -> V2 -> cutover, not as hot-swapping live contract code in place. - Keep public routes, reply shapes, and emitted events stable unless the architecture explicitly versions them.
- Make contract version, status, and cutover behavior explicit.
- If migration is required, split responsibilities across
V1,V2, and the off-chain migrator. - Record frontend, generated-client, and indexer implications before implementation begins.
- Route implementation to
../sails-architecture/SKILL.md,../task-decomposer/SKILL.md,../sails-rust-implementer/SKILL.md,../sails-idl-client/SKILL.md, and../sails-local-smoke/SKILL.mdas needed.
Default Outputs
The resulting architecture and task artifacts should make these points explicit when relevant:
- whether the change is additive or breaking
- whether a new deployed contract version is required
- whether
ReadOnlyor write-disable behavior is required - whether migration is in scope now or only prepared for later
- how frontend and indexer switch to the new version
- what rollback target exists during cutover
Guardrails
- Do not describe Gear/Sails evolution as in-place replacement of live contract code.
- Do not hide compatibility-sensitive changes inside generic “update contract” wording.
- Do not change released public routes or event payloads casually.
- Do not treat IDL regeneration alone as proof of safe rollout.
- Do not merge
V1,V2, and migrator responsibilities into one vague implementation step. - Classify each change as interface-ID-preserving or interface-ID-breaking. Adding or removing methods changes the interface ID; renaming does not.
Related Skills
gear-foundation/sails-ethexe-implementer
development
VerifiedTrustedCommunity
Use when approved tasks require Rust code changes in a Sails ethexe workspace with the ethexe feature enabled. Do not use for standard Gear/Vara Sails apps without ethexe, or when the spec or architecture is still unsettled.
17SKILL.mdUpdated May 23, 2026
gear-foundation/sails-ethexe-architecture
development
VerifiedTrustedCommunity
Use when a builder needs to design or review architecture for a Sails ethexe app with dual-transport, payable methods, Solidity interface generation, or Ethereum-style events. Do not use for standard Gear/Vara Sails apps without ethexe.
17SKILL.mdUpdated May 23, 2026
gear-foundation/gear-builtin-actors
development
VerifiedTrustedCommunity
Use when a builder needs to design or debug calls from a standard Gear/Vara Sails program into runtime builtin actors such as BLS12-381, staking, proxy, or ETH bridge, including ActorId derivation, request encoding, reply decoding, and gas or ED budgeting. Do not use for regular program-to-program messaging, Vara.eth or ethexe-only work, non-Sails repositories, or runtime-maintenance tasks inside the Gear repo.
17SKILL.mdUpdated May 16, 2026
gear-foundation/sails-indexer
development
VerifiedTrustedCommunity
Use when a builder needs a read-side indexer and query API for a standard Gear/Vara Sails app using program events, IDL-driven decoding, projected read models, and optional on-chain query enrichment. Do not use for command-side backends, generic Node APIs, non-Sails repositories, Vara.eth or ethexe-first work.
17SKILL.mdUpdated May 13, 2026