vinta-schedule-api

Rewrite code comments and docs touched during the current conversation into Simple English, stripping AI-slop / AI-lingo vocabulary and negative framing. Use when the user says "deslop these comments", "clean up the comments we just wrote", "rewrite this in plain English", or after a review flags comments as convoluted/AI-sounding. Comment-only - never changes function names, APIs, or behavior.

Execute a phased implementation plan from `ai-plans/` in vinta_schedule_api by orchestrating one subagent per phase (using whatever model the plan suggests and the runtime supports), pushing one stacked branch per phase to GitHub, and tracking progress. Use when the user says "implement the plan", "execute plan X", "start implementation", "run phase N of plan Y", "implement {feature} plan", or asks to drive a `*_IMPLEMENTATION_PLAN.md` file phase-by-phase. NOT for one-off changes, single-file edits, or work that doesn't have an existing plan. Agents push branches and open PRs via `open-pr-from-context` after review passes.

Author a phased implementation plan for a new feature following the repo's `ai-plans/` conventions. Use when the user asks to "plan", "design", "scope", or "break down" a feature, write an implementation plan / IMPLEMENTATION_PLAN.md, or turn a spec/idea into a phased roadmap. Always interrogates the requester before drafting.

Provision a fully-runnable git worktree for parallel feature work so a long-running plan (or experiment) can build, test, lint, run migrations, and hit databases without disturbing the main checkout — or other parallel worktrees. Reads the active plan (when given one) plus the project's `.gitignore`, package manifests, env templates, and docker config to decide what to symlink, what to copy, what to fork (DBs, env files, compose project names, test databases, sandboxes). Use when the user says "set up a worktree for plan X", "create an isolated env for this feature", "I want to run two plans in parallel without breaking the main checkout", or when [implement-plan](../implement-plan/SKILL.md) opts in via Step 0 question (c). NOT for one-off branch switches that don't need a separate runnable copy of the app.

Add a new environment variable end-to-end in the Vinta Schedule API. Covers every layer the var must reach — `.env.example`, `.env.docker.example`, Django settings, Render production envVarGroups, CI workflow, AGENTS.md env section. Use when adding a new secret, API key, feature toggle, or third-party integration credential. Skip for renames (use rename-env-var pattern) and for removals.

Author a Django migration in the Vinta Schedule API. Couples with the `migration-author` sub-agent. Handles standard `makemigrations` flow, lock-aware schema changes on hot tables, raw-SQL DB code (functions / procedures / triggers / views / materialized views) through the bespoke framework at `common/raw_sql_migration_managers.py`, and the reverse path. Use whenever a model change, FK change, index change, or DB-defined-code change must ship. Skip for pure code refactors that don't touch the database.

Add a new Django model in the Vinta Schedule API, following the project's multi-tenancy contract (OrganizationModel inheritance, OrganizationForeignKey for tenant-scoped relations), custom manager + queryset pattern, admin registration, and factory for tests. Use when adding a tenant-scoped or shared model to any app (accounts, calendar_integration, organizations, payments, public_api, webhooks, etc.). Skip for ad-hoc through-tables that don't deserve a manager; use a plain `class Meta` model + comment for those.

Adjust an existing implementation plan in `ai-plans/` after implementation has started or finished. Updates the plan file (revising existing phases or appending new ones), then for each affected phase that was already implemented adjusts its commits (`git commit --amend` or new commits) on the phase branch, force-pushes the rewritten branch, rebases every downstream stacked phase branch, force-pushes each, and refreshes the PR-context files. Use when the user says "amend the plan", "update phase N", "add a phase to plan X", "the spec changed, fix the plan", or "rewrite the implementation for phase N". NOT for one-off changes to a single file unrelated to a plan; use the regular implement skill for that. Agents push branches and open PRs via `open-pr-from-context` after review passes.

Add a query or mutation to the public GraphQL API at `public_api/` in the Vinta Schedule API. Wires up the strawberry-django type in `<app>/graphql.py`, registers the field on `public_api/queries.py` (or `mutations.py`), applies the project's auth + organization-scope permission classes, maps the field to a resource in `OrganizationResourceAccess.FIELD_TO_RESOURCE_MAPPING`, and uses DI-injected services for business logic. Use when exposing internal data to external integrations. Skip for internal-only data — those go through the REST surface (`create-rest-endpoint`).

Create or version a Postgres FUNCTION (or PROCEDURE, or TRIGGER) in the Vinta Schedule API through the bespoke raw-SQL framework at `common/raw_sql_migration_managers.py`. Use for DB-side computation that ORM expressions can't model: timezone conversions, recurring-event occurrence calculation, aggregate functions, complex CASE-driven derivations, custom operators. Skip for one-shot computations that belong in Python services and for pgvector / extension functions installed via DDL (use a stock migration for those).

Create or version a Postgres VIEW or MATERIALIZED VIEW in the Vinta Schedule API through the bespoke raw-SQL framework at `common/raw_sql_migration_managers.py`. Use when adding read-side projections that ORM queries can't express efficiently, denormalized aggregates, multi-tenant flattening for reporting, or a materialized cache for expensive computations. Skip for purely-ORM-derived projections (use querysets / annotations / virtual models instead) and for DBA-managed views maintained outside the migration system.

Add a REST endpoint to the Vinta Schedule API using DRF ViewSets, the project's `VintaScheduleModelViewSet` base, organization-scoped permissions, serializer-driven virtual models, optional django-filter filtersets, and drf-spectacular OpenAPI schema export. Wires the viewset, serializer, permissions, filterset, route registration in `<app>/routes.py`, and regenerates `schema.yml`. Use for internal REST endpoints consumed by the project's frontends or first-party integrations. For external-integration data, use [create-graphql-public-query](../create-graphql-public-query/SKILL.md).

Use when debugging any defect, test failure, regression, performance issue, or unexpected behavior in vinta_schedule_api (Django 6 + DRF + Strawberry GraphQL + Celery, multi-tenant (OrganizationModel), Postgres, deployed to Render). Enforces a root-cause-first investigation flow before any code change is proposed. Pulls evidence from the project's observability MCP tools (none configured) before forming a hypothesis. Cites the project's real test, lint, and type-check commands so reproduction steps are concrete.

Author a safe operational one-off script (data backfill, ad-hoc cleanup, schema fixup, tenant migration outside the regular migration pipeline). Enforces a strict contract every script must follow — dry-run by default, idempotent on re-run, batched DB operations, streamed reads, segmented CSV backups before destructive writes, interruption-safe, and console + filesystem + S3 logging that survives the interruption. Generates a per-script folder (`<scripts_dir>/<YYYY-MM-DD>-<name>/`) containing the subclass + tests + (when a sister `run-one-off-script-<stack>` skill is invoked) the stack-specific runner artefact (Django mgmt command, Jupyter notebook, Medplum bot, Vercel Function, Lambda, K8s Job). The bundled `BaseOneOffScript` class delegates every runtime-specific concern (logging sink, lease, stop signal, artifact upload) to a pluggable `Runtime` interface — `LocalRuntime` is the default for plain CLI invocation; stack runner skills ship their own adapters. Use whenever the user asks for a one-off script, b

Bootstrap a project's `QA_USE_CASES.md` from scratch using the canonical pattern (immutable PA###/PR### ids, role table, per-app numbered sections with role-tagged checklists). Invoked from inside [plan-feature](../plan-feature/SKILL.md) when the project has no `QA_USE_CASES.md` yet — the active feature's spec + plan are already in hand. Seeds the file with use cases from those two documents only; does not sweep prior plans. Asks the user for the few gaps spec/plan don't answer (app boundaries, role list, prefix conventions). Project-agnostic — works in any repo that adopts this skill set.

Turn raw feature prompt into structured spec doc at `ai-plans/YYYY-MM-DD-FEATURE_NAME_SPEC.md`. Sections fixed — Business Context, Hypothesis, Objectives, Decisions (Use-cases / State transitions & edge cases / Acceptance scenarios / Negative scope), Alternatives considered (optional), Open questions, Risks assumed. Use when user asks "write a spec", "draft a spec doc", "turn this idea into a spec", or hands one-line / paragraph feature description needing structure before plan. Skill ALWAYS interviews requester before drafting — never turn vague prompt into plausible-sounding spec by guessing.

Publish one `.vinta-ai-workflows/prs-context/{feature-name}/{phase-name}.md` file as a real PR + inline review comments by invoking the bundled [open-pr.sh](scripts/open-pr.sh) shell script. The script handles all parsing + CLI calls (`gh` for GitHub, `glab` for GitLab); this skill is a thin wrapper that picks the file, runs the script, and reports the result. Use after `implement-plan` has pushed a phase branch + written the context file, or any time afterwards to publish a `status: pending` file. Does nothing else — no diff editing, no extra checks, no skill-side parsing.

Author the Django-specific runner for a one-off operational script in the Vinta Schedule API — either a `BaseCommand` under `<app>/management/commands/<name>.py` (headless / cron / CI invocation) or a Jupyter notebook under `notebooks/<name>/runner.ipynb` (interactive review on production data). Ships the matching Runtime adapter at `scripts/one_off/_runtime_django.py` (`DjangoMgmtRuntime` for management commands, `JupyterRuntime` for notebooks). Sister skill to [add-one-off-script](../add-one-off-script/SKILL.md) — that skill authors the script body (`BaseOneOffScript` subclass), this skill wires the Django-specific runner around it.