A skill termfy-command-set entrega uma família de commands de uma vez:
orders list, show, create, update e delete, ou só os verbos que a
spec aberta prevê. Ela extrai as operações para funções compartilhadas e
cria os três adaptadores: o command no CLI, a tool espelhada no MCP e a
screen de lista e detalhe na TUI. No fim, você tem um recurso disponível nos
três modos, com testes em cada um e os itens da spec marcados.
Quando usar
- A spec aberta descreve um recurso inteiro, como pedidos, com verbos, tools e screen.
- Você quer que
mycli orders list, a toolorders_liste a screenordersmostrem o mesmo resultado. - Um recurso existe só no CLI e precisa ganhar tool e screen.
Para um command isolado, sem tool nem screen, use termfy-cli. Para só uma tool, use termfy-mcp. Para só uma tela, use termfy-tui. O client HTTP do serviço sai antes, pela termfy-api.
Como pedir
Para a família completa nos três modos:
Use a skill termfy-command-set para entregar
orders listeorders showcom as toolsorders_listeorders_showe a screenorders, conforme a spec aberta.
Para um recurso que só tem leitura no CLI:
Use a skill termfy-command-set para acrescentar a tool
orders_liste a screenordersà famíliaordersque já existe no CLI.
Para verbos de gravação:
Use a skill termfy-command-set para entregar
orders createeorders_createcom--yesedryRun, como a spec define.
O que a skill faz
- Roda
git status --shorte relaciona cada verbo e cada modo aos itens de Tasks e Tests da spec aberta emspecs/. - Implementa as operações compartilhadas em módulo próprio sob
src/, separado dos adaptadores. Se houver HTTP, usa o client datermfy-api. - Cria
src/cli/commands/orders.tsa partir detemplate/command/example.tse acrescenta o agrupador aossubcommandsda raiz emsrc/cli/commands.ts. - Cria
src/mcp/tools/orders.tsa partir detemplate/tool/example.tse chamaregisterOrdersToolsemregisterAll, nosrc/mcp/server.ts. - Cria
src/tui/screens/orders.tsa partir detemplate/screen/example.tse registra a screen emsrc/tui/screens/index.ts. A tela segue o padrão lista e detalhe, comtable,stateView, os diálogos da edição e as açõesn,Enter,der. Se ela puder abrir primeiro, acrescentaordersemtui.initialTabe em--tab. - Escreve os testes: CLI em subprocesso, MCP com
Cliente TUI comcreateTestRendereremountTui. - Atualiza
docs/cli.md,docs/mcp.mdedocs/tui.md. Rodabun run opencli,bun test,bun run typecheckebun run docs:check. - Marca
[x]nos itens testados e rodabun run validateno fim.
Exemplo
A função listOrders({ limit, status }) vem do client da loja. O command
orders list valida as options e chama a função:
import { manifest } from "../../app/manifest.ts";import { ExitCode } from "../../app/exit-codes.ts";import { error } from "../../app/errors.ts";import { table } from "../format.ts";import type { Command } from "../registry.ts";import { listOrders } from "../../api/shop.ts";
const listCommand: Command = { name: "list", description: "List shop orders.", options: [ { name: "--limit", argument: { name: "n" }, default: "10", description: "Maximum number of orders, from 1 to 50. Default 10." }, { name: "--status", argument: { name: "status", values: ["open", "paid", "shipped"] }, description: "Only orders with this status. Absent means every status." }, ], exitCodes: [ExitCode.CONFIG, ExitCode.CREDENTIALS, ExitCode.NETWORK_OR_API], examples: [`${manifest.bin} orders list`, `${manifest.bin} orders list --status open --json`], run: async (ctx) => { const limit = Number(ctx.options.limit ?? 10); if (!Number.isInteger(limit) || limit < 1 || limit > 50) { throw error.usage("--limit must be an integer from 1 to 50."); } const status = typeof ctx.options.status === "string" ? ctx.options.status : undefined; const page = await listOrders({ limit, status }); const data = { count: page.items.length, orders: page.items, nextCursor: page.nextCursor }; return { data, text: () => table(page.items.map((o) => [o.id, o.status])) }; },};
export const ordersCommand: Command = { name: "orders", description: "Query shop orders.", subcommands: [listCommand],};A tool orders_list chama a mesma função e devolve o mesmo objeto:
import { z } from "zod";import { AppError } from "../../app/errors.ts";import { listOrders } from "../../api/shop.ts";import type { Registrar } from "../server.ts";
const description = "Use when the user asks about shop orders. Returns count, orders and nextCursor.";
export function registerOrdersTools({ server, catalog }: Registrar): void { catalog.tools.push({ name: "orders_list", description }); server.registerTool("orders_list", { title: "List orders", description, inputSchema: { limit: z.number().int().min(1).max(50).optional().describe("Maximum number of orders. Default 10."), status: z.enum(["open", "paid", "shipped"]).optional().describe("Only orders with this status."), }, }, async ({ limit, status }) => { try { const page = await listOrders({ limit: limit ?? 10, status }); const d = { count: page.items.length, orders: page.items, nextCursor: page.nextCursor }; return { content: [{ type: "text", text: JSON.stringify(d, null, 2) }], structuredContent: d }; } catch (e) { if (!(e instanceof AppError)) throw e; return { content: [{ type: "text", text: e.message }], isError: true }; } });}Na screen orders, mount devolve um container síncrono com a table e o
painel de detalhe. A carga roda em onEnter e atualiza a tabela com
setRows. A geração descarta respostas que chegam depois de onLeave. As
ações são n criar pelo ctx.prompt, Enter abrir o detalhe, d apagar
com ctx.confirm e danger, r recarregar. Em compact a tela mostra
uma visão por vez.
A saída nos dois formatos do CLI:
$ mycli orders list --status open o1 open o7 open$ mycli orders list --status open --json{ "ok": true, "command": "mycli orders list", "data": { "count": 2, "orders": [{ "id": "o1", "status": "open" }, { "id": "o7", "status": "open" }], "nextCursor": null }}$ mycli orders list --limit 0error --limit must be an integer from 1 to 50. [2 USAGE]Use "mycli orders list --help".Regras que a skill segue
- Só os verbos da spec. A skill gera o subconjunto combinado na Surface. Verbo criado por simetria vira código sem teste nem dono.
- Uma função, três adaptadores. A tool não chama
Command.rune a screen não executa a CLI em subprocesso. Formatação e protocolo ficam nos adaptadores para o domínio responder igual nos três modos. - Defaults aplicados em
run.OptionDefinition.defaultsó documenta. O parser não preenchectx.options, entãorunresolve o padrão. --jsonnão se repete. Ela é global e chega a todas as folhas.- Exit codes por folha. Cada verbo declara os seus em
exitCodes. O agrupador não repassa códigos para as folhas. - Tool com Zod descrito. Cada campo tem
.describe()e a tool entra emcatalog.tools, senãomcp --listnão a mostra. - Gravação sem prompt na tool. Confirmação ou
dryRunsão implementados na própria tool, porque um agente não responde a prompt de terminal. - Falha não vira lista vazia. Erro aparece como erro no CLI, como
isError: truena tool e como estado de erro na screen. - Tela em lista e detalhe. A screen usa
tablepara a coleção ekeyValueTableno detalhe, comstateViewpara vazio, carregando e erro.ncria peloctx.prompt,Enterabre o detalhe,dapaga comctx.confirmedanger,rrecarrega. - Mesma expectativa nos testes. Os três modos usam a mesma fonte local controlada, sem rede real nem o cofre da pessoa.
O que ela entrega
A skill relata verbos e modos entregues, arquivos, contratos de data,
itens marcados e o resultado da validação. Inclui exemplos em texto e JSON,
os nomes das tools e um frame da screen.
| Arquivo | Mudança |
|---|---|
src/cli/commands/orders.ts |
agrupador e folhas novos |
src/cli/commands.ts |
ordersCommand nos subcommands da raiz |
src/mcp/tools/orders.ts |
registerOrdersTools com as tools |
src/mcp/server.ts |
chamada em registerAll |
src/tui/screens/orders.ts |
screen de lista e detalhe |
src/tui/screens/index.ts |
screen na lista de abas |
tests/ e docs/ |
testes dos três modos e capítulos atualizados |
docs/opencli.json |
regenerado por bun run opencli |
Próxima skill
Para ajustar detalhes de cada modo, siga com termfy-cli, termfy-mcp ou termfy-tui. Se a família trouxe settings ou credenciais novas, confira com termfy-config.