Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

adding-an-operation

/adding-an-operation

Prowadzi przez ścieżkę operacji od katalogu do handlera, sklepu, CLI, MCP i testów.

Repozytorium
spur-board ↗
Licencja
MIT
Ostatnia zmiana repozytorium
13.11.2026

Ocena i bezpieczeństwo

90/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść25 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Prowadzi przez ścieżkę operacji od katalogu do handlera, sklepu, CLI, MCP i testów.

Oryginalny opis (EN)

Path of an operation from catalog to handler, store, CLI, MCP, generated files and tests. Use when you add or change an entry in packages/contracts/src/ops/catalog.ts or its handler. Don't use for field or break rules (use working-with-contracts) or CLI/MCP output (use designing-agent-surfaces).

Jak działa

  1. 1. Catalog entry
  2. 2. Core handler
  3. 3. Store
  4. 4. HTTP, CLI and MCP
  5. 5. MCP annotations
  6. 6. Generated files
  7. 7. Tests to extend
  8. 8. Reference operations
Sekcje z nagłówków SKILL.md, w oryginale · 83 linii, 523 słów
Podgląd SKILL.md
---
name: adding-an-operation
description: Path of an operation from catalog to handler, store, CLI, MCP, generated files and tests. Use when you add or change an entry in packages/contracts/src/ops/catalog.ts or its handler. Don't use for field or break rules (use working-with-contracts) or CLI/MCP output (use designing-agent-surfaces).
---

# Adding an operation

One catalog entry drives the daemon route, the CLI command and the MCP tool. Work the steps in
path order. A PR that changes this path or these rules updates this skill in the same PR.

## 1. Catalog entry

- Add the entry to `OPERATIONS` in `packages/contracts/src/ops/catalog.ts`; shapes, grants,
  errors and bindings follow `.agents/skills/working-with-contracts/references/operation.md`,
  which names each check in `describe('catalog')` and `describe('snapshot')` of
  `packages/contracts/test/ops.test.ts`.

## 2. Core handler

- Write a `Mutation<'<id>'>` (`packages/core/src/app/commands.ts`) or `Query<'<id>'>`
  (`packages/core/src/app/queries.ts`) in the matching module under `packages/core/src/app/`, and
  register it in `createOperationRegistry` (`packages/core/src/app/registry.ts`).
- A mutation that must read an external source first adds `prepare`: `createApply` runs it after
  the input and key checks, a stored-key replay check and a read-only authorization, before the
  transaction, and passes its result as `ctx.prepared`. A stored key skips `prepare`, and a
  same-key call waits for the one in flight. `prepare` never writes. Reference: `task.submit` in
  `packages/core/src/app/turn-commands.ts`.
- `createOperationRegistry` returns the total `OperationHandlers`
  (`packages/core/src/app/operations.ts`), so a catalog entry without a registration fails
  `tsc`. `OperationRegistry` stays `Partial` for transports, and `dispatchOperation` answers
  `not_implemented` when the requested handler is missing or has a mismatched `id`. The coverage
  test is in
  `packages/core/test/app/registry.test.ts`.

## 3. Store

- A new table or column is a migration in `packages/core/src/store/migrations/` plus its types
  in `packages/core/src/store/schema.ts`; follow `working-with-storage`.

## 4. HTTP, CLI and MCP

- No per-operation code. `/v1/ops/:id` in `packages/core/src/api/server.ts`, `createProgram` in
  `packages/cli/src/cli.ts` and `createMcpServer` in `packages/cli/src/mcp.ts` loop over the
  catalog. An operation that seems to need a special case there needs a catalog field instead;
  raise it in the issue before implementing.
- Command, tool and output conventions: `designing-agent-surfaces`.

## 5. MCP annotations

- Leave `mcp.destructive` unset unless the mutation passes the additive rule under "Bindings" in
  `.agents/skills/working-with-contracts/references/operation.md`. Decide it by reading every
  write the handler reaches, helpers included; the pin sees only the catalog.

## 6. Generated files

- Run `pnpm gen` and commit every file it changes: `packages/contracts/ops.snapshot.json`, the
  product skill `packages/skills/spur-board/SKILL.md` with its pages in
  `packages/skills/spur-board/references/`, and `docs/cli.md`. The gen job in
  `.github/workflows/ci.yml` fails on a diff or an untracked page.
- Any catalog change moves the `version` in `packages/contracts/ops.snapshot.json`: a running
  daemon and live `board mcp` sessions answer `version_mismatch` until both restart. Say so in
  the PR Description.

## 7. Tests to extend

- The literal table under `describe('grants')` in `packages/contracts/test/ops.test.ts`.
- The non-destructive pin under `describe('catalog')` there, for a `destructive: false` entry.
- `packages/cli/test/__snapshots__/mcp.test.ts.snap`: rerun `packages/cli/test/mcp.test.ts` with
  `-u` and read the diff.
- A handler test in `packages/core/test/app/` that goes through `createOperationRegistry`.
- A daemon integration test in `packages/daemon/test/` when the operation reaches a gateway.
- Each changed expected value above, and the snap that `pnpm guardrails` reports, is a Changed
  checks entry (`gitflow`).

## 8. Reference operations

- `comment.add`, the plain mutation: its entry in `packages/contracts/src/ops/catalog.ts` ->
  `add` in `createBlockMutations` -> `addComment` (both `packages/core/src/app/blocks.ts`) ->
  `'comment.add'` in `createOperationRegistry` -> `dispatchOperation` -> `/v1/ops/:id` ->
  `createProgram` and `createMcpServer`. Tests: `describe('production query handlers')` in
  `packages/core/test/app/queries.test.ts`, which calls it through `createOperationRegistry`, and
  `describe('board mcp')` in `packages/cli/test/mcp.test.ts`.
- `block.ask`, through a gateway: `packages/daemon/test/worker-question.integration.test.ts`.
- `link.add`, a union input with `cli.modes` (`linkModes` in the catalog) and a migration
  (`packages/core/src/store/migrations/0010_manual_links.sql`); handler `createLinkMutations` in
  `packages/core/src/app/links.ts`.

Wersje

W bazie nie ma innych skilli o nazwie adding-an-operation.

Migawka bazy z 13.11.2026 · wersja paczki e5e3d1b207d5 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100designing-agent-surfaces
    Ustala, co agenci widzą: nazwy, opisy i schematy narzędzi MCP oraz wyjście CLI i pomoc, według zasad dla powierzchni agentów.
  • 100add-operation
    Wskazuje jedną instrukcję dodania nowej operacji LoreKit (narzędzie MCP, polecenie CLI lub trasa REST) w katalogu narzędzi, obu lustrach uprawnień, słowniku audytu i dokumentacji.
  • 100add-operation
    Opisuje procedurę dodania, nadpisania lub wyłączenia operacji Kavo: wpis w rejestrze, sloty DTO, handler, metadane trasy i testy, dla nowej operacji CRUD lub własnej operacji encji.
  • 100check-coverage
    Zapewnia pokrycie testami handlera polecenia CLI przy dodawaniu nowego polecenia lub audycie istniejącego pokrycia.
  • 100adding-mcp-store-servers
    Dodaje zewnętrzny serwer MCP (Linear, Notion, GitHub) do katalogu sklepu MCP PostHog: znajduje endpoint, sonduje go, pisze wpis katalogowy i weryfikuje.
  • 95add-command
    Dodaje obsługę nowego polecenia CLI, pisze jego handler i wpisuje je na listę SIMPLE_SAFE.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.