Planetscale Safe Orchestrator

PlanetScale safe orchestrator (master skill)

Purpose

Run the complete PlanetScale safe best-practices skill pack end to end. Load and execute each sub-skill in order, accumulate evidence, and produce one unified recommendations report. The first pass is assessment-only.

Non-negotiable safety contract

Default to read-only.

You may inspect configuration, branches, query telemetry, recommendations, webhooks, roles, backups, traffic budgets, and repository code. You must not mutate PlanetScale, the database, the repository, the network posture, credentials, schema, production traffic controls, or automation endpoints without explicit approval of a named change set.

Class C/D/E mutations require approval per ../planetscale-change-gates-and-approval-contract/SKILL.md. When in doubt, stop and add to the proposed change set instead of executing.

One exception exists: if the operator explicitly acknowledges the risk and names a scope per ../planetscale-autonomous-execution-mode/SKILL.md, execution proceeds autonomously under that skill's status and halt discipline instead of stopping for per-change approval. The assessment phases below are identical either way.

Sub-skills are sibling folders next to this skill, referenced by relative path; if a referenced path does not exist, locate the sibling skill whose frontmatter name matches and use it instead.

Ground all CLI and API usage in the official documentation rather than guessing: the docs index is at https://planetscale.com/docs/llms.txt (append .md to any docs URL for the markdown version) and the API reference is https://planetscale.com/docs/openapi.yaml. When a command or endpoint fails, check the docs for the correct form before recording an evidence gap. Tooling and access failures belong in the internal run log, never in the customer report.

Before you start

1. Read this file completely.

2. Copy the progress checklist below into your working notes and update it as you go.

3. Collect inputs (ask or infer from AGENTS.md, MCP context, environment, repository):

   • Organization slug
   • Database name
   • Branch name
   • Engine: PlanetScale Vitess or PlanetScale Postgres
   • Production branch or branches
   • Connected application repository path, if available
   • Application language, framework, ORM, query builder, connection pooling
   • Operator tolerance: report-only, PR-generation, branch-only migrations, or supervised production apply

If inputs are missing, continue with discovery. Do not block on completeness.

Progress checklist

Copy and track:

Master assessment progress:
- [ ] Phase 0: Safety contract loaded
- [ ] Phase 1: Read-only inventory
- [ ] Phase 2: Engine safety review (Vitess OR Postgres)
- [ ] Phase 3: Query Insights and tags
- [ ] Phase 4: Traffic Control (Postgres only — skip for Vitess)
- [ ] Phase 5: Webhook automation
- [ ] Phase 6: Schema recommendations agent loop
- [ ] Phase 7: Codebase SQLCommenter instrumentation
- [ ] Phase 8: MCP agent operating model
- [ ] Phase 9: Best-practices matrix coverage check
- [ ] Phase 10: Unified customer report
- [ ] Phase 11: Change gates verified — stop, no mutations

Interface preference order

1. PlanetScale MCP insights-only server — autonomous analysis without query execution
2. Full PlanetScale MCP with read-only scope — schema or limited read queries
3. pscale CLI and pscale api — structured inventory and exact API state
4. Repository inspection — codebase analysis and instrumentation recommendations
5. Direct SQL — read-only introspection only when operator grants database read access

The operator's stated interface constraint overrides this order. If the run is restricted to specific interfaces (for example CLI-only), use those interfaces; this is not a conflict and needs no workaround or note in the customer report beyond the Scope section's interfaces line.

Execution plan

For each phase: read the skill file, follow its instructions, capture its required output, and carry findings forward. Do not skip phases unless the checklist says to skip.

Phase 0 — Safety contract

Read: ../planetscale-change-gates-and-approval-contract/SKILL.md

Internalize operation classes A–E. All later phases operate under Class A unless the operator explicitly approves a named change.

Phase 1 — Read-only inventory

Read and execute: ../planetscale-readonly-inventory/SKILL.md

Deliverables to carry forward:

• Inventory table with evidence (source, path/command, timestamp, confidence)
• Missing evidence table
• Risk flags
• Confirmed engine (Vitess or Postgres)
• Branch topology and production branch

If engine is still unknown after inventory, determine it before Phase 2.

Phase 2 — Engine safety review

Run exactly one:

Deliverables: engine-specific safety gaps, workflow gaps, and proposed changes requiring approval.

Phase 3 — Query Insights and tags

Read and execute: ../planetscale-query-insights-and-tags/SKILL.md

Deliverables: query risk table, tag coverage table, bad/high-cardinality tags, recommended tag schema, candidate Traffic Control slices, candidate schema and code changes.

Phase 4 — Traffic Control (Postgres only)

Skip this phase for Vitess. Mark checklist item complete with note "N/A — Vitess".

For Postgres, read and execute: ../planetscale-traffic-control-recommendations/SKILL.md

Deliverables: proposed budgets (name, mode, traffic slice, rule type, limits rationale, test/rollback plan).

If query tags are weak, note "tagging first" per that skill and defer enforce-mode recommendations.

Phase 5 — Webhook automation

Read and execute: ../planetscale-webhook-automation-recommendations/SKILL.md

Deliverables: webhook inventory, missing subscriptions, destination quality review, automation opportunities, unsafe automation risks.

Phase 6 — Schema recommendations agent loop

Read and execute: ../planetscale-schema-recommendations-agent-loop/SKILL.md

Deliverables: per-recommendation triage (type, severity, evidence, safe implementation path, validation/rollback plan).

Phase 7 — Codebase SQLCommenter instrumentation

Read and execute: ../planetscale-codebase-sqlcommenter-instrumentation/SKILL.md

Skip only if no repository is available. Note "no repository reviewed" in the final report.

Deliverables: detected stack, current tagging state, recommended package/path, proposed tag schema, files likely to change.

Phase 8 — MCP agent operating model

Read and execute: ../planetscale-mcp-agent-operating-model/SKILL.md

Deliverables: recommended MCP server choice, AGENTS.md additions, allowed/disallowed autonomous work, proposed agent loops.