new-operationlisted

Use when adding a new operation to the api/ package (new capture/search/branch/backup/etc method, new MCP tool, new HTTP endpoint). Scaffolds the typed Request/Response, XxxDescription constant, wires HTTP + MCP stdio + CLI MCP proxy transports, and stubs tests. Triggers include "add a new MCP tool for X", "new api operation", "add an endpoint for Y", "scaffold Z under api/". Do NOT use for migrating an existing inline handler — that's migrate-to-api.
gramaton-ai/gramaton · ★ 4 · AI & Automation · score 68

Install: claude install-skill gramaton-ai/gramaton

# new-operation The full recipe is in CONTRIBUTING.md under "Adding a feature: the recipe". This skill is the actionable checklist form. Read CONTRIBUTING.md once if you haven't; then use this as the per-step enforcer. ## Before you write code Decide and say out loud: 1. **Cluster** — which existing cluster does this belong to? (admin, collections, history, maintenance, records, search, sessions.) If none fits, that's a design question — stop and discuss with the user. 2. **Verb shape** — noun-verb, imperative. `BackupCreate`, `BranchCheckout`, `Reembed`. Match siblings in the cluster. 3. **Destructive?** — if yes, you'll need a loopback gate on the HTTP route. 4. **Slow work?** — if yes (disk I/O, network, embedding), use the three-phase lock pattern, not straight `Lock()`. See CONTRIBUTING.md:462. ## Files to touch For cluster `<cluster>` and operation `Example`: | File | What to add | |---|---| | `api/<cluster>.go` | `ExampleRequest`, `ExampleResponse`, `ExampleDescription` const, `func (a *API) Example(ctx, req) (ExampleResponse, *APIError)` | | `server/bindings_<cluster>.go` | HTTP route handler + MCP tool registration in `registerXxxMCPTools` | | `cli/mcp_proxy_<cluster>.go` | CLI proxy registration using `proxyPost("/v1/...", args)` | | `server/bindings_<cluster>_test.go` | Happy path + at least one error-path test | | `CHANGELOG.md` | Entry under `[Unreleased]` → `### Added` | ## Enforceable conventions Before declaring done, verify each: - [ ] `Request`/`Re