--- name: sails-program-evolution-b7a0cd3af406 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--architecture.md` - `docs/plans/YYYY-MM-DD--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 `ReadOnly` or write-disable behavior - a future migration path must be designed even if migration is not implemented now - state migration from `V1` to `V2` is part of scope ## Working Model 1. Classify the change first: additive, breaking, migration-readiness only, or migration now. 2. Treat Gear/Sails evolution as `V1 -> V2 -> cutover`, not as hot-swapping live contract code in place. 3. Keep public routes, reply shapes, and emitted events stable unless the architecture explicitly versions them. 4. Make contract version, status, and cutover behavior explicit. 5. If migration is required, split responsibilities across `V1`, `V2`, and the off-chain migrator. 6. Record frontend, generated-client, and indexer implications before implementation begins. 7. 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.md` as 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 `ReadOnly` or 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. --- Source attribution: gear-foundation Original project: https://github.com/gear-foundation/vara-skills/blob/44c1454141ececc8ef3a88903b625260f370c4de/skills/sails-program-evolution/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 Gear Foundation Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: gear-foundation Original project: https://github.com/gear-foundation/vara-skills/blob/44c1454141ececc8ef3a88903b625260f370c4de/skills/sails-program-evolution/SKILL.md Attribution basis: Source repository record Fields of work: Development & Engineering, Product Management Roles: Backend Developer, DevOps / SRE, Product Manager Specialties: Backend Tools: Sails Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: a4958ef8bc01a4a1b11691308071ba7b11fa53ac78276f09df8bab2357187e25