// Auto-generated from src/ai-service/skills/system/superblocks-migration/SKILL.md
// Do not edit directly - edit the .md file instead
export const content = `---
name: superblocks-migration
description: |
  Convert legacy Superblocks 2.0 YAML APIs ("block-chain" format) to the new 3.0 sdk-api TypeScript format.
  Load when executing a v2→v3 migration turn — the runtime prompt will tell you to.
readOnly: true
metadata:
  author: superblocks
  version: "1.0"
---

# v2 → v3 API Translation

You are converting **legacy Superblocks "block-chain" YAML APIs** into the **new code-mode \`@superblocksteam/sdk-api\` TypeScript format**. Each YAML file under \`scratch/v2-backup/apis/<ApiName>/api.yaml\` must be emitted as a single TypeScript file at \`server/apis/<ApiName>/api.ts\` that compiles, typechecks, and preserves behavior exactly.

## Meta-rule: ZERO judgment calls

If any situation below is not resolved deterministically by this document, **STOP** for that API. Do **not** pick a default. Do **not** guess a factory, a shape, or an import. Skip it, continue with other APIs, and mark the checklist item as \`failed\` via \`build_manageChecklist\` with a short \`failureReason\` describing the exact ambiguity (failing rule, block name if any, what would be needed to proceed). This rule overrides everything else.

Corollary: do not add \`// TODO\` comments that silently ship. Unresolved items live only as \`failed\` checklist entries.

## Inputs and outputs

- **Source tree:** \`scratch/v2-backup/apis/<ApiName>/api.yaml\`. Discover the actual set by listing the directory — do not hardcode a count or list.
- **Target tree:** \`server/apis/<ApiName>/api.ts\`. Do not create scaffolding trees that do not already exist (see "Registry registration" below).
- **Checklist:** the migration checklist has already been seeded with one item per API (id \`api_<ApiName>\`, origin \`seed_api\`, status \`pending\`). Pull the live set by calling \`build_manageChecklist\` with \`action: "get"\` and filtering to \`origin: "seed_api"\` and \`status: "pending"\` — that is your authoritative API list and count for this turn.

## Required reading (read these BEFORE writing any output)

Authoritative. If a rule here conflicts with your priors, these win.

1. \`node_modules/@superblocksteam/sdk-api/README.md\` — whole thing (api() contract, execution model, \`ctx.*\`, exports, error classes, performance best practices, \`useApi\` frontend hook, integration method table).
2. \`node_modules/@superblocksteam/sdk-api/src/index.ts\` (the **barrel**) — the authoritative list of exported factory names. Integration factory names are whatever this file exports, not whatever the directory name is. Never invent or case-fold a factory name without confirming it here.
3. The README for **every integration** referenced by the YAMLs you convert:
   - \`node_modules/@superblocksteam/sdk-api/src/integrations/<kind>/README.md\`
   - If a vendor-specific factory exists for the target service (e.g., a dedicated one for a given LLM provider), prefer it over a generic HTTP one.
4. \`skills/system/superblocks-migration/references/yaml-block-mapping.md\` — full YAML → TS mapping for each legacy block type.

There is **no \`javascript\` integration** in sdk-api — inline JS/TS lives directly inside \`run(ctx, input)\`. Any block whose YAML key is \`javascript:\` becomes plain TypeScript in \`run()\`.

## Preflight gate (MUST pass before any file edits)

Complete this orientation sequence before writing or modifying any API file:

1. Call \`build_manageChecklist\` with \`action: "get"\` and filter to \`origin: "seed_api"\` \`status: "pending"\` — this is your authoritative API list and count for this turn.
2. Read \`node_modules/@superblocksteam/sdk-api/src/index.ts\` and treat it as the **only** source of truth for sdk-api export/factory names.
3. Read \`node_modules/@superblocksteam/sdk-api/README.md\`.
4. For each API, read only the integration README(s) needed for that API right before migrating it (just-in-time). Do **not** preload every integration README for the entire app.

Hard constraints:

- Do **not** rely on prior conversation memory, "knowledge" summaries, or inferred export names.
- Do **not** start editing API files until preflight steps 1–3 are complete.
- If a required file cannot be read, mark that API's checklist item \`failed\` with a concrete \`failureReason\` that names the missing path.

## File layout & exports

- One API per file, default export: \`export default api({ ... });\`.
- Use ESM-style relative \`.js\` specifiers in imports.
- File path: \`server/apis/<ApiName>/api.ts\` where \`<ApiName>\` is the YAML \`metadata.name\` (for example, \`GetFloors\` → \`server/apis/GetFloors/api.ts\`).
- The \`api({ name })\` string and the registry key must both equal the YAML \`metadata.name\` verbatim — frontends call \`useApi("<metadata.name>")\`.

### Registry registration (conditional)

- If \`server/apis/index.ts\` exists in the target tree: add an import + entry for each new module. Do not reorder existing entries.
- If it does **not** exist: do **not** create it, do not create scaffolding. Mark the checklist item \`failed\` with a \`failureReason\` noting the missing registry.

## Critical rules

1. **Integration IDs are opaque per-YAML.** Extract each distinct \`step.integration\` UUID to a named \`const\` at the top of the file. Never carry UUIDs across files.
2. **SQL: parameterize always.** Zero \`\${…}\` interpolations may remain inside any SQL string. Dynamic lists use \`= ANY($N::<type>[])\` — never string-building \`IN (…)\`.
3. **\`query\` vs \`execute\`.** Rows returned → \`query\` with Zod schema. Nothing actionable → \`execute\`.
4. **Output shape preservation.** Mirror the legacy API's externally-visible response exactly — shape, nullability, cardinality. Do not wrap in envelopes.
5. **Default is sequential.** \`TYPE_FOREACH\` → \`for ... of\` with sequential \`await\`. \`Promise.all\` only when YAML explicitly used a \`parallel:\` block.
6. **Determinism, no slop.** No retries, no caching, no extra logging beyond a single \`ctx.log.info("<ApiName> start", {...})\` at the top of \`run\`. No narrative code comments.
7. **Never invent client methods.** If the integration README only documents \`apiRequest\`, use \`apiRequest\`.

## Security / user identity

- \`authorization.type: AUTHORIZATION_TYPE_APP_USERS\` is enforced by the server; rely on \`ctx.user\` in TS.
- If the YAML accepts \`userId\` / \`email\` / etc. as API input, remove that input and read from \`ctx.user\` instead.

## Observability

- One \`ctx.log.info("<ApiName> start", { <safe-ids> })\` at the top of \`run\` is allowed. Never log secrets, tokens, or PII.

## Verification before you hand off

Runtime verification (required):

1. \`build_debug\` passing is required but not sufficient. Do not treat compile/typecheck success as proof that runtime behavior is correct.
2. Use risk-based runtime checks: run \`testApi\` for APIs with integrations (REST/vendor/SQL), multi-step control flow, transformed outputs, or any uncertainty. For obviously simple APIs, you may skip \`testApi\`.
3. If \`testApi\` output appears stale or mismatched, run \`build_reloadFile\` once and re-test. If runtime still fails after documented-method verification + one reload/retest cycle, record a concrete \`failureReason\` and continue.

For each converted API, self-check:

1. File default-exports exactly one \`api({...})\`; \`name\` matches \`metadata.name\`.
2. Zero \`\${…}\` interpolations remain in any SQL string.
3. No SQL \`IN (…)\` built by concatenation; dynamic lists use \`= ANY($N::<type>[])\`.
4. Every prior block's \`.output\` read is replaced by an actual result \`const\`.
5. Input is the minimal union of identifiers the YAML references that are not produced by earlier blocks or \`Variables\`.
6. Output shape exactly mirrors the legacy API's external response.
7. If \`server/apis/index.ts\` exists, it registers the new module under \`metadata.name\`.

## Parallelization policy

Count pending APIs from the checklist (\`build_manageChecklist\` \`action: "get"\`, filter \`origin: "seed_api"\` \`status: "pending"\`).

- **If the pending count is \`< 8\`:** migrate the APIs yourself, sequentially. Do NOT call \`spawnCodingSubagents\`. Work through each API using the per-API procedure below.
- **If the pending count is \`>= 8\`:** you **MUST spawn sub-agents** to migrate these APIs in parallel. There are too many APIs to migrate sequentially yourself. Do NOT attempt to migrate APIs yourself in this run — use \`spawnCodingSubagents\`.
  - Split the APIs into batches of ~5 (aim for 4–6 per batch), with a hard cap of **5 sub-agents total**. If more than 25 APIs remain, give later batches larger shares rather than spawning more than 5 workers.
  - For each batch, craft an \`instructions\` string that:
    - Names the exact \`<ApiName>\` values that sub-agent owns, verbatim, as a bulleted list.
    - Restates the per-API procedure below so the sub-agent is self-contained.
    - Reminds the sub-agent to update the shared checklist (id \`api_<ApiName>\`) for every item it owns.
  - **Call \`spawnCodingSubagents\` as the ONLY tool call in that turn.** Do not emit any other tool calls alongside it — no reads, no writes, no checklist updates. The tool blocks until every sub-agent finishes; you cannot do migration work "while waiting" because there is no waiting from your perspective — your next turn only begins after the tool returns. If you emit other tool calls in the same turn, you and the sub-agents will race on the shared checklist and corrupt state.
  - **After \`spawnCodingSubagents\` returns** — only in a subsequent turn — read the checklist via \`build_manageChecklist\` with \`action: "get"\`. For any \`failed\` items, review the \`failureReason\`. Retry small numbers of recoverable failures yourself (sequentially, using the per-API procedure below). Leave deterministic failures as \`failed\`.

## Per-API procedure

For APIs you migrate yourself, or that you embed in a sub-agent's \`instructions\`:

1. Call \`build_manageChecklist\` with \`action: "update"\`, \`itemId: "api_<ApiName>"\`, \`status: "in_progress"\`.
2. Read \`scratch/v2-backup/apis/<ApiName>/api.yaml\` and any sibling files the blocks reference.
3. Produce the TypeScript module at \`server/apis/<ApiName>/api.ts\`, overwriting the stub. Use the YAML block → TS mapping in \`skills/system/superblocks-migration/references/yaml-block-mapping.md\`.
4. If \`server/apis/index.ts\` exists, update it to register the new module.
5. On success → \`build_manageChecklist\` with \`status: "completed"\`.
6. On deterministic failure → \`build_manageChecklist\` with \`status: "failed"\` and a concrete \`failureReason\` (the rule that failed + what is needed to proceed). Continue with the next API.

## Run-level rules

- Do NOT emit a free-text UNRESOLVED report — every unresolved item must be a \`failed\` checklist entry with a \`failureReason\`.
- Do NOT stop the run because one API failed. Only stop once every API is either \`completed\` or \`failed\`.
`;
//# sourceMappingURL=skill.generated.js.map