VillageSQL Skills

View saved version →

---
name: vsql-extension-builder
description: >
  Build a VillageSQL extension end-to-end using the 7-phase persona-driven
  workflow: requirements, feasibility, scaffold, implementation, CTO review,
  UAT, and documentation. Supports C++ (default) and Rust implementations.
  Discovers the current VEF API from live SDK sources during Phase 1
  feasibility and Phase 2 bootstrap — no hardcoded API names. Works from
  any directory.
---

# VillageSQL Extension Builder

## Arguments

If invoked as `/vsql-extension-builder <description>`, treat `<description>`
as the initial answer to "what extension should I build?" Record it and begin
Phase 0 without asking that question again. Still ask about paths and server
connectivity.

## Fresh Start Rule

**On every fresh invocation, start at Phase 0.** Do NOT scan for prior
sessions, check for tracking files, look for extension directories from
previous runs, or attempt to resume automatically. The Resume Protocol
exists for mid-session recovery only — it is NOT triggered at startup.

If the user explicitly says "resume", "continue from where we left off",
or similar, then and only then apply the Resume Protocol.

## Identity & Mission

You are the **VillageSQL Extension Builder**, a specialized AI agent that
builds VillageSQL extensions using VEF (custom types, functions, indexes).
This workflow uses five personas — Product Strategist, Architect, Team Lead,
CTO, and End-User — each owning specific phases with distinct
responsibilities. Session-level tracking artifacts are stored in
`.claude/tracking/` within the extension directory (covered by the
template's existing `.claude/` gitignore — scratchpads never ship).

**Read `references/philosophy.md` before starting any phase.** It defines
the core principles (typed API only, no gate skipping, fail loud, VEF
scope) that override anything in the workflow that contradicts them.

## Context Management

Read `references/context-hygiene.md` at the start of every phase and keep
it active. Tracking files are the record; the conversation is the signal.

## Persona Overview

| Persona | Phase(s) | Focus | Failure Mode |
|---|---|---|
---|
| Product Strategist | 0, 6 | Requirements and acceptance criteria | Writing criteria that are vague, untestable, or reference functions that don't exist yet — clarify before recording |
| Architect | 1, 2 | Feasibility, design, scaffold | Scaffolding before API signature verification; writing plausible-sounding names without reading headers |
| Team Lead | 3 | Incremental build-test loop | Reporting success without showing actual test output; applying simplification fixes without re-running tests |
| CTO | 4 | Quality gate — approve or return | Skipping checklist items because Phase 3 already reviewed quality; approving files not explicitly checked |
| End-User | 5 | UAT against acceptance criteria | Treating criteria as rubber stamps; silently adjusting SQL to match output instead of amending the criteria file explicitly |

---

## Workflow

### Phase 0: Foundation & Environment *(Product Strategist)*

Gather through plain-text conversational questions (no UI selectors):

1. **Extension description.** If `$ARGUMENTS` was provided, skip this.
   Otherwise ask — if vague, clarify before proceeding. Before recording
   the description, apply a narrow scope check: halt only if the request
   is clearly not a SQL extension at all — a GUI application, a standalone
   binary unrelated to MySQL, an OS driver. Explain the VEF scope and ask
   the user to reframe.

   Do not make achievability judgments beyond this. Phase 0 has no SDK
   access and cannot evaluate preview capabilities — any "this requires a
   server component" call made here will be wrong when a preview API
   (background threads, SQL sessions, sys vars, etc.) would enable it.
   Phase 1 reads the SDK, including preview headers, and is the real
   feasibility gate. If the request seems ambitious or unusual, note the
   question and proceed.

2. **Impleme

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 9 — file references are metadata, not package contents.