From 86758b28b2f1bd2f0bcc71181d553fb67d8f1d82 Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Thu, 5 Mar 2026 12:45:53 +0300 Subject: [PATCH 1/3] skill for stellar wizard update --- skills/stellar-update.md | 124 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 skills/stellar-update.md diff --git a/skills/stellar-update.md b/skills/stellar-update.md new file mode 100644 index 000000000..91a664caa --- /dev/null +++ b/skills/stellar-update.md @@ -0,0 +1,124 @@ +# Skill: Sync Stellar Contracts into Contract Wizard + +## Purpose +When a new release of `stellar-contracts` is published, this skill guides the process of inspecting what changed and updating the corresponding code in `contracts-wizard` under `packages/core/stellar`. + +--- + +## Inputs Required + +Before starting, collect the following from the user: + +| Input | Description | +| --------------------- | ------------------------------------------------------------ | +| `CONTRACTS_REPO_PATH` | Absolute path to the local `contracts-wizard` repository | +| `NEW_TAG` | Tag or commit SHA of the new `stellar-contracts` release | +| `OLD_TAG` | Tag or commit SHA of the previous release to compare against | + +--- + +## Step 1 — Inspect the Wizard's Current Stellar Code + +Navigate to `/packages/core/stellar` and get the full picture of what contracts and traits are currently implemented. This will help you understand the scope of the update and identify which parts of the Wizard codebase are relevant. + +--- + +## Step 2 — Diff the Two Releases of `stellar-contracts` + +Run the following to get the full diff between the two releases: + +```bash +cd {CONTRACTS_REPO_PATH} +git diff {OLD_TAG}..{NEW_TAG} +``` + +Also get a high-level summary of what changed: + +```bash +git log {OLD_TAG}..{NEW_TAG} --oneline +git diff {OLD_TAG}..{NEW_TAG} --stat +``` + +Organize findings into these categories: + +### 2a. New Crates / Packages +For each new crate introduced: +- Does it represent a standalone, user-facing contract? (e.g., a token, an NFT, a governance contract) +- Or is it a helper/utility used internally by other contracts? (e.g., an `access` or `storage` helper) +- **Decision rule:** Only surface it in the Wizard UI if it makes sense as a contract on its own that a user would want to deploy or configure. + +### 2b. Changes to Existing Packages +For each modified package: +- Were any **public traits** changed? (added/removed methods, changed signatures) → **High priority** +- Were any **public function signatures** changed? → **High priority** +- Were changes internal only (e.g., storage layout, private helpers)? → Likely low impact, but verify +- Cross-reference: is this package currently used anywhere in `packages/core/stellar`? If yes, the change **must** be applied. + +### 2c. Breaking Changes +Flag any change that: +- Removes or renames a public function or trait method +- Changes a function's parameter types or return type +- Changes the expected behavior of an interface the Wizard currently generates code for + +Breaking changes require the most careful handling — trace every usage in the Wizard code before updating. + +### 2d. Removed Crates / Deprecated APIs +- Check if anything the Wizard currently references has been removed or deprecated +- These must be updated or removed from the Wizard output accordingly + +--- + +## Step 3 — Plan the Updates + +Produce a structured update plan before touching any code: + +``` +[ ] New contract to add: → new tab/section "" +[ ] Trait change: in → update generator in +[ ] Signature change: in → update call site in +[ ] Internal-only change: → no Wizard change needed (reason: ...) +[ ] Breaking change: → impacts , update plan: ... +[ ] Removed/deprecated: → remove/replace in +``` + +--- + +## Step 4 — Apply the Updates + +### If adding a new contract: +1. Add a new tab or section in the relevant Wizard UI component +2. Define the options/configuration the user can set (mirroring the crate's constructor or init parameters) +3. Implement the code generation logic in `packages/core/stellar` to produce the correct Stellar contract code +4. Ensure the generated code uses the correct imports from the new crate + +### If updating an existing contract: +1. Locate all files in `packages/core/stellar` that reference the changed crate +2. Apply trait/signature changes precisely — do not approximate +3. If a parameter was added, decide on a sensible default or expose it as a new Wizard option +4. If a parameter was removed, clean up any Wizard options or generated code that set it + +### If a crate was removed or deprecated: +1. Remove or replace references in the Wizard's code generator +2. If the functionality was merged into another crate, re-map accordingly + +--- + +## Step 5 — Verify + +- Run through each contract type the Wizard supports and confirm the generated output matches the new `stellar-contracts` API +- Pay particular attention to trait implementations — these are the most likely source of subtle breakage +- Confirm no old import paths, removed functions, or stale signatures remain in the generated code + +--- + +## Key Heuristics + +| Situation | Action | +| -------------------------------------------- | ---------------------------------------------------- | +| New crate is a helper/utility | Skip — don't expose in Wizard | +| New crate is a deployable contract | Add UI tab + code generator | +| Changed function is not referenced in Wizard | Note it, no code change needed | +| Changed function **is** referenced in Wizard | Must update, no exceptions | +| Trait method signature changed | Treat as breaking — audit all usages | +| Internal storage change only | Low risk, but verify no Wizard codegen depends on it | +| Breaking change of any kind | Full trace required before updating | From 37fdbee7540b0f08ea3c10a370a7f28a07da0004 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=96zg=C3=BCn=20=C3=96zerk?= Date: Thu, 5 Mar 2026 17:47:08 +0300 Subject: [PATCH 2/3] Update skills/stellar-update.md Co-authored-by: Eric Lau --- skills/stellar-update.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/stellar-update.md b/skills/stellar-update.md index 91a664caa..f0943e139 100644 --- a/skills/stellar-update.md +++ b/skills/stellar-update.md @@ -11,7 +11,7 @@ Before starting, collect the following from the user: | Input | Description | | --------------------- | ------------------------------------------------------------ | -| `CONTRACTS_REPO_PATH` | Absolute path to the local `contracts-wizard` repository | +| `CONTRACTS_REPO_PATH` | Absolute path to the local `stellar-contracts` repository | | `NEW_TAG` | Tag or commit SHA of the new `stellar-contracts` release | | `OLD_TAG` | Tag or commit SHA of the previous release to compare against | From ae263aa7af656a1647db1c3207eb8714ea26c4fa Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Thu, 5 Mar 2026 17:48:56 +0300 Subject: [PATCH 3/3] skill for stellar wizard update --- skills/stellar-update.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/skills/stellar-update.md b/skills/stellar-update.md index f0943e139..f2c3e0315 100644 --- a/skills/stellar-update.md +++ b/skills/stellar-update.md @@ -11,7 +11,7 @@ Before starting, collect the following from the user: | Input | Description | | --------------------- | ------------------------------------------------------------ | -| `CONTRACTS_REPO_PATH` | Absolute path to the local `stellar-contracts` repository | +| `CONTRACTS_REPO_PATH` | Absolute path to the local `stellar-contracts` repository | | `NEW_TAG` | Tag or commit SHA of the new `stellar-contracts` release | | `OLD_TAG` | Tag or commit SHA of the previous release to compare against | @@ -86,9 +86,10 @@ Produce a structured update plan before touching any code: ## Step 4 — Apply the Updates ### If adding a new contract: -1. Add a new tab or section in the relevant Wizard UI component -2. Define the options/configuration the user can set (mirroring the crate's constructor or init parameters) -3. Implement the code generation logic in `packages/core/stellar` to produce the correct Stellar contract code + +1. Define the options/configuration the user can set (mirroring the crate's constructor or init parameters) +2. Implement the code generation logic in `packages/core/stellar` to produce the correct Stellar contract code +3. Add a new tab or section in the relevant Wizard UI component 4. Ensure the generated code uses the correct imports from the new crate ### If updating an existing contract: