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.md
docs/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
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
- 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.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.
1---2name: sails-program-evolution3description: 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.4metadata:5 source: https://skillmd.com/skills/gear-foundation/sails-program-evolution6---78# Sails Program Evolution910## Overview1112Plan how a released Sails contract evolves after deployment.1314Use 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`.1516## Start Here1718Read `../../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`.1920Use `../../assets/architecture-template.md` for the architecture note and `../../assets/task-plan-template.md` for the ordered task plan.2122Write outputs to:2324- `docs/plans/YYYY-MM-DD-<topic>-architecture.md`25- `docs/plans/YYYY-MM-DD-<topic>-tasks.md`2627## Route Here When2829- a released contract must gain a new deployed version30- public routes, replies, or events may change31- frontend or indexer compatibility must be preserved during cutover32- the old contract may need `ReadOnly` or write-disable behavior33- a future migration path must be designed even if migration is not implemented now34- state migration from `V1` to `V2` is part of scope3536## Working Model37381. Classify the change first: additive, breaking, migration-readiness only, or migration now.392. Treat Gear/Sails evolution as `V1 -> V2 -> cutover`, not as hot-swapping live contract code in place.403. Keep public routes, reply shapes, and emitted events stable unless the architecture explicitly versions them.414. Make contract version, status, and cutover behavior explicit.425. If migration is required, split responsibilities across `V1`, `V2`, and the off-chain migrator.436. Record frontend, generated-client, and indexer implications before implementation begins.447. 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.4546## Default Outputs4748The resulting architecture and task artifacts should make these points explicit when relevant:4950- whether the change is additive or breaking51- whether a new deployed contract version is required52- whether `ReadOnly` or write-disable behavior is required53- whether migration is in scope now or only prepared for later54- how frontend and indexer switch to the new version55- what rollback target exists during cutover5657## Guardrails5859- Do not describe Gear/Sails evolution as in-place replacement of live contract code.60- Do not hide compatibility-sensitive changes inside generic “update contract” wording.61- Do not change released public routes or event payloads casually.62- Do not treat IDL regeneration alone as proof of safe rollout.63- Do not merge `V1`, `V2`, and migrator responsibilities into one vague implementation step.64- Classify each change as interface-ID-preserving or interface-ID-breaking. Adding or removing methods changes the interface ID; renaming does not.