grate-devs / grate-devs/grate

Add an agent skill for authoring and running grate migrations

Open
#821 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
C#
Stars
297
Forks
55
Avg merge
18m
Merged PRs (30d)
1

Description

**Is your feature request related to a problem? Please describe.**

Coding agents can write valid SQL while missing grate's migration lifecycle. For example, combining table creation, indexes, constraint changes and seed inserts in one migration file makes recovery difficult if an earlier statement succeeds and a later statement fails without an effective transaction. Adding a batch separator does not give each operation its own migration-history entry.

General C# or database guidance does not reliably cover grate's script types, ordering, change detection, transaction configuration and retry behavior.

**Describe the solution you'd like**

Create a focused, agent-neutral skill for **using grate in consumer projects**, maintained in this repository alongside the implementation and documentation. A possible name is `use-grate`, distributed as a standard `SKILL.md` with concise supporting references/examples where useful.

The skill should cover:

- Inspect the project's grate version, database provider, folder configuration and existing conventions before generating SQL or commands. Use the matching CLI help/docs; do not invent flags or silently upgrade the tool.
- Explain one-time, anytime and everytime scripts, alphabetical ordering, environment selection and token replacement.
- Teach **one independently tracked DML statement or DDL operation per one-time migration file** as the authoring rule. Separate table creation, individual indexes, constraint changes and seed inserts into ordered files. Explain this as an authoring policy, not a claim that grate cannot execute SQL batches. A procedure definition is one DDL operation even when its body contains multiple statements.
- Keep already-deployed one-time scripts immutable. Add forward migrations; do not casually recommend change-warning/hash-bypass flags. Renaming or splitting an unpublished migration is different from rewriting one already recorded in a shared database.
- Explain actual transaction and failure behavior for the selected provider/configuration: what commits, what is recorded, what may remain after failure, and how to inspect and resume. Do not claim that dry run proves SQL execution or that all providers support transactional DDL.
- Show local/CI verification with disposable databases and the real migration runner. Respect existing target authorization and avoid exposing connection-string credentials. Preparing scripts or running isolated tests must not introduce redundant approval steps.

Keep the skill independent of a particular application, cloud or agent vendor. Its trigger should target grate authoring, review, execution and troubleshooting, rather than every SQL task.

**Acceptance criteria**

- [ ] A usable skill with clear scope, valid metadata and discoverable references is added and linked from the grate documentation.
- [ ] A synthetic table/index/seed example produces separate, correctly ordered migration files.
- [ ] Behavioral checks cover clean apply, a second run with no repeated one-time changes, deliberate failure/recovery under the tested transaction modes, and refusal to silently rewrite an applied script.
- [ ] Examples distinguish a batch separator from a separately tracked migration, and handle parallel-branch naming/order without collisions.
- [ ] Verification records the grate version/provider used and does not claim untested database or agent-client compatibility.

**Describe alternatives you've considered**

A skill in a general engineering-skills library would work, but upstream ownership keeps grate-specific guidance close to releases and lets other skill libraries reference one maintained source instead of copying it.

**Additional context**

Use the existing documentation as the starting point and verify version-sensitive behavior against code/tests:

- [One-time scripts](https://github.com/grate-devs/grate/blob/main/docs/ScriptTypes/OneTimeScripts.md)
- [Configuration options](https://github.com/grate-devs/grate/blob/main/docs/ConfigurationOptions/index.md)
- [Folder configuration](https://github.com/grate-devs/grate/blob/main/docs/ConfigurationOptions/FolderConfiguration.md)

This issue requests a documentation/agent-skill deliverable, not a change to grate's SQL execution semantics.

Contributor guide

Open the contributing guide

Research direction

Start with docs/ScriptTypes/OneTimeScripts.md, docs/ConfigurationOptions/index.md, and docs/ConfigurationOptions/FolderConfiguration.md, then inspect the implementation and tests for version-sensitive behavior. Build the documented skill and synthetic migration example around the stated grate conventions, and verify clean apply, repeat runs, failure/recovery, ordering, and refusal to rewrite applied scripts with the real runner and disposable databases.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp, sql
Domain
databases, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.