@delegance/claude-autopilot 5.0.7 → 5.2.0

package/skills/autopilot/SKILL.md

@@ -83,19 +83,39 @@ For each task:
 - Skip formal spec/quality review to maintain speed (the validate step catches issues)
 - If subagent fails to write to worktree: implement directly
 
-### Step 4: Auto-Migrate
+### Step 4: Migrate
 
-For any `.sql` files created in `data/deltas/` during implementation:
+After implementation creates schema changes, the autopilot pipeline runs the migrate phase via the canonical dispatcher contract. The dispatcher:
 
-```bash
-/migrate
-```
+1. Reads `.autopilot/stack.md` → looks up `migrate.skill` (default: `migrate@1`)
+2. Resolves the skill via the alias map (path-escape protected)
+3. Performs version handshake (skill manifest must declare a runtime range that includes the current `claude-autopilot` version, and an API version major matching the envelope contract)
+4. Builds an invocation envelope (`{ contractVersion, invocationId, nonce, env, repoRoot, changedFiles, gitBase, gitHead, ci, ... }`) passed to the skill via env vars + stdin
+5. Enforces policy (4-flag CI prod gate + clean-git + manual-approval + dry-run-first)
+6. Executes the configured command via `spawn(shell:false)` — structured argv only, no shell injection
+7. Parses the result artifact (file-first, nonce-bound stdout fallback only if skill manifest opts in)
+8. Writes a hash-chained audit log entry to `.autopilot/audit.log`
+9. Branches on `nextActions[]` from the result (e.g. `regenerate-types` triggers `npm run typecheck`)
+
+For the autopilot pipeline, this is invoked once per migration affected by the implementation changes.
+
+#### CI prod safety floor
+
+Running `--env prod` from CI requires **all four** of these (skills cannot relax):
+1. `--yes` flag explicit
+2. `AUTOPILOT_CI_POLICY=allow-prod` env var
+3. `AUTOPILOT_TARGET_ENV=prod` env var (must match `--env`)
+4. `migrate.policy.allow_prod_in_ci: true` in stack.md
 
-Run against **dev only** by default. Stop after dev succeeds and continue the pipeline.
+Plus a recognized CI provider env (GitHub Actions / GitLab CI / CircleCI / Buildkite / Jenkins) — or an explicit `AUTOPILOT_CI_PROVIDER=<name>` override for self-hosted CI.
 
-Only promote to QA → prod if the user has explicitly enabled it (e.g., `AUTOPILOT_ALLOW_PROD_MIGRATIONS=true` in their env) or asked for it directly. Production migrations are irreversible — never auto-promote without a clear signal.
+#### Configuration source of truth
 
-If migration fails, fix the SQL and retry (max 2 retries). If it still fails, stop and report.
+All migrate behavior is configured in `.autopilot/stack.md`. The autopilot skill never invokes a specific runner directly; it always dispatches through `claude-autopilot dispatch`. See:
+- `docs/superpowers/specs/2026-04-29-migrate-skill-generalization-design.md` — full spec
+- `docs/skills/rich-migrate-contract.md` — envelope + result artifact contract for skill authors
+- `docs/skills/version-compatibility.md` — runtime/skill version compatibility matrix
+- `presets/schemas/migrate.schema.json` — JSON Schema for the stack.md migrate block
 
 ### Step 5: Validate
 
@@ -157,7 +177,7 @@ Tell the user:
 ## Error Recovery
 
 - **Subagent failure:** Re-dispatch with more context or implement directly
-- **Migration failure:** Fix SQL, re-run /migrate
+- **Migration failure:** Fix the migration source (per the configured `migrate.skill` in stack.md), re-dispatch via `claude-autopilot dispatch migrate`
 - **Validate failure:** Fix issues, re-run (max 3 retries)
 - **Codex critical findings:** Fix, push, re-review (max 2 retries)
 - **Bugbot findings:** /bugbot handles triage + fix automatically (max 3 rounds)

package/skills/migrate/skill.manifest.json

@@ -0,0 +1,7 @@
+{
+  "skillId": "migrate@1",
+  "skill_runtime_api_version": "1.0",
+  "min_runtime": "5.2.0",
+  "max_runtime": "5.x",
+  "stdoutFallback": false
+}

package/skills/migrate-none/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: migrate-none
+description: No-op migrate skill. Emits a skipped ResultArtifact and exits cleanly. Used when migrations are intentionally not configured (e.g., a doc-only PR, a brand-new project before any DB exists).
+---
+
+# /migrate-none — Migration intentionally not configured
+
+The explicit "no migrations" state for the autopilot pipeline. Set `migrate.skill: "none@1"` in `.autopilot/stack.md` to short-circuit the migrate phase.
+
+## What it does
+
+1. Read `AUTOPILOT_ENVELOPE` for the invocationId + nonce
+2. Write a ResultArtifact to `AUTOPILOT_RESULT_PATH` with:
+   - `status: "skipped"`
+   - `reasonCode: "migration-disabled"`
+   - `appliedMigrations: []`
+   - `destructiveDetected: false`
+   - `sideEffectsPerformed: ["no-side-effects"]`
+   - `nextActions: []`
+3. Exit with code 0
+
+That's it. The dispatcher reads the result and continues to the next pipeline phase.
+
+## When to use
+
+- Brand-new project with no schema yet (you don't have a DB or migration tool yet)
+- Docs-only or refactor-only PRs that touch no schema
+- Repos where migrations are managed entirely outside the autopilot pipeline
+
+For everything else, use `migrate@1` (thin orchestrator) or `migrate.supabase@1` (rich Supabase runner).
+
+## Configuration
+
+```yaml
+schema_version: 1
+migrate:
+  skill: "none@1"
+```
+
+No `envs` block needed.

package/skills/migrate-none/skill.manifest.json

@@ -0,0 +1,7 @@
+{
+  "skillId": "none@1",
+  "skill_runtime_api_version": "1.0",
+  "min_runtime": "5.2.0",
+  "max_runtime": "5.x",
+  "stdoutFallback": false
+}

package/skills/migrate-supabase/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: migrate-supabase
+description: Run database migrations against Supabase environments (dev → QA → prod). Validates SQL, executes with ledger tracking, and auto-generates the configured types output. Reads paths from .autopilot/stack.md (migrate.supabase.deltas_dir / types_out / envs_file).
+---
+
+# Database Migration — Supabase
+
+Run a migration through the dev → QA → prod pipeline with validation at each step. This is the "rich" Supabase variant of the migrate skill, configured via `.autopilot/stack.md`.
+
+All paths are parameterized — the skill reads them from stack.md instead of hardcoding repo-specific locations:
+
+- `migrate.supabase.deltas_dir` — directory holding timestamped `.sql` delta files (e.g. `data/deltas`)
+- `migrate.supabase.types_out` — generated TypeScript types output path (e.g. `types/supabase.ts`)
+- `migrate.supabase.envs_file` — JSON file with per-env `dbUrl` values (e.g. `.claude/supabase-envs.json`, gitignored)
+
+Examples below show common defaults in angle brackets. Substitute the values from your stack.md.
+
+## Usage
+
+### 1. Identify the migration file
+
+If given as argument, use that. Otherwise find the most recently modified `.sql` file in the configured deltas directory (`${migrate.supabase.deltas_dir}`, e.g. `data/deltas/`).
+
+### 2. Validate (dry run on dev)
+
+```bash
+npx tsx scripts/supabase/migrate.ts <file> --env dev --dry-run
+```
+
+Present validation results. If errors, help the user fix them before proceeding.
+
+### 3. Run on dev
+
+```bash
+npx tsx scripts/supabase/migrate.ts <file> --env dev
+```
+
+### 4. Ask the user
+
+> "Migration succeeded on dev. The configured types output (`${migrate.supabase.types_out}`) was updated. Promote to QA?"
+
+### 5. Run on QA
+
+```bash
+npx tsx scripts/supabase/migrate.ts --promote qa
+```
+
+### 6. Ask the user
+
+> "Migration succeeded on QA. Promote to prod?"
+
+### 7. Run on prod
+
+```bash
+npx tsx scripts/supabase/migrate.ts --promote prod --confirm-prod
+```
+
+### 8. Commit
+
+After all environments are done, commit the updated types output and the migration file:
+
+```bash
+git add ${migrate.supabase.types_out} ${migrate.supabase.deltas_dir}/<migration-file>
+git commit -m "feat: <description of schema change>"
+```
+
+## Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--env dev\|qa\|prod` | Target environment |
+| `--dry-run` | Validate only, don't execute |
+| `--force` | Allow destructive operations (DROP, TRUNCATE) |
+| `--confirm-prod` | Required for prod execution |
+| `--promote qa\|prod` | Run missing migrations from source env |
+
+## Validation Checks
+
+The system validates before every execution:
+- Duplicate table/column detection
+- snake_case naming enforcement
+- RLS + policy required for every new table
+- Destructive operation blocking (unless --force)
+- Cross-env prerequisite verification
+- Checksum integrity (modified files are rejected)
+- Promotion chain enforcement (prod requires QA first)
+
+## Requirements
+
+- The configured envs file (`${migrate.supabase.envs_file}`, e.g. `.claude/supabase-envs.json`) with `dbUrl` for each env (gitignored)
+- `postgres` npm package installed
+
+## Canonical result artifact (autopilot dispatcher integration)
+
+When invoked under the autopilot pipeline (`AUTOPILOT_ENVELOPE` env var set), this skill writes a result artifact to `AUTOPILOT_RESULT_PATH` (or to nonce-bound stdout markers if `stdoutFallback: true` is set in the manifest):
+
+```json
+{
+  "contractVersion": "1.0",
+  "skillId": "migrate.supabase@1",
+  "invocationId": "<from envelope>",
+  "nonce": "<from envelope>",
+  "status": "applied" | "skipped" | "validation-failed" | "needs-human" | "error",
+  "reasonCode": "<short string>",
+  "appliedMigrations": ["<file.sql>"],
+  "destructiveDetected": false,
+  "sideEffectsPerformed": ["migration-ledger-updated", "types-regenerated"],
+  "nextActions": ["regenerate-types"]
+}
+```
+
+Required `sideEffectsPerformed` values reserved by the contract: `types-regenerated`, `migration-ledger-updated`, `schema-cache-refreshed`, `seed-data-applied`, `snapshot-written`, `no-side-effects`.
+
+## Stack.md configuration
+
+```yaml
+schema_version: 1
+migrate:
+  skill: "migrate.supabase@1"
+  supabase:
+    deltas_dir: "data/deltas"
+    types_out: "types/supabase.ts"
+    envs_file: ".claude/supabase-envs.json"
+  policy:
+    allow_prod_in_ci: false
+```

package/skills/migrate-supabase/skill.manifest.json

@@ -0,0 +1,7 @@
+{
+  "skillId": "migrate.supabase@1",
+  "skill_runtime_api_version": "1.0",
+  "min_runtime": "5.2.0",
+  "max_runtime": "5.x",
+  "stdoutFallback": false
+}