Spec — Command Structure

Toda spec de comando /k-* em meta/context/commands/*.md segue um schema mínimo que permite (1) auditoria automática, (2) reuso por outros comandos, (3) classificação Code-First de cada fase.

Frontmatter obrigatório

---
name: <slug>                            # mesmo do filename sem extensão
type: command
category: mutation | read | audit | generation | meta
description: <one-line summary>         # < 200 chars; aparece em /k-help
inputs:                                 # arguments aceitos
  - name: <arg>
    type: string | path | flag | choice
    required: true | false
    description: <one-line>
outputs:                                # side effects esperados
  - <kind>: <description>               # ex: "filesystem: edits N files"
requires:                               # dependências
  binaries: [<list of koder-* tools>]   # binários invocados
  commands: [<list of /k-* commands>]   # outros /k-* chamados
  tasks: [<list of tasks/*.md>]         # task blocks @included
audit:                                  # opcional; se presente segue specs/audit/frontmatter.kmd
  applicable_to: [...]
  script: ./<basename>-audit.sh
  severity: hard | advisory
---

Seções markdown obrigatórias

1. Descrição (parágrafo inicial, sem heading)

Frase única ou parágrafo curto: o que o comando faz, em uma sentença que poderia entrar em /k-help. Reflete description do frontmatter.

2. Sintaxe

## Sintaxe

/k- # caso default /k- # com argumento /k- --flag # com flag

3. Fases numeradas (se aplicável)

Comandos multi-step declaram fases como ## FASE N — <nome>. Cada fase tem:

• Bloco de descrição
• Heading de classificação Code-First: > Determinismo: deterministic | analytical | mixed
• Conteúdo (procedimento)

Fases marcadas deterministic são candidatas a binário (policies/code-first.kmd audit detecta).

4. Regras

Lista numerada de regras invariantes do comando. Devem ser explícitas ("nunca push sem rebase") em vez de implícitas no procedimento.

5. Exemplos

Pelo menos 1 exemplo real de uso, com input e expected output.

Tasks reusáveis

Comando que repete lógica encontrada em outros comandos deve extrair em meta/context/commands/tasks/*.md e usar @include tasks/<x>.md em vez de duplicar. Per policies/divide-and-conquer.kmd (regra dos 3).

Audit

/k-audit commands (via koder-spec-audit) verifica:

1. Frontmatter parseável e contém campos obrigatórios
2. Frontmatter cita category válida
3. Pelo menos as 5 seções obrigatórias estão presentes
4. Fases têm heading de classificação Code-First quando declaradas
5. Tasks @include apontam para arquivos existentes em tasks/

Anti-patterns

Don't:

1. Comando sem frontmatter — perde metadados pra discovery e audit
2. Lógica determinística em narrativa sem classificação — bloqueia detecção pelo /k-audit code-first
3. Duplicar lógica de outro comando — extrair pra task ou wrappar

Do:

1. Declarar inputs/outputs explicitamente — evita IA reinterpretar
2. Marcar fases como determinísticas quando aplicável — semente pro refactor pra binário
3. Reusar tasks — @include tasks/concurrent-lock.md em vez de re-escrever

Origem

Spec criada durante o ticket KSTACK-101 ETAPA 2.3. Dependência de policies/command-creation.kmd (ETAPA 2.4) e /k-new <artifact> scaffolder (ETAPA 5.1).