Marcação e blocos ricos

O Jiraya entende dois recursos além do Markdown comum:

• Elementos de marcação, como critérios de aceite e definição de pronto, que dão estrutura a uma descrição. Cada elemento aparece como um cartão.
• Blocos ricos, como gráficos, tabelas e métricas, que mostram dados. Cada bloco é um bloco de código cuja linguagem diz o que desenhar.

Os dois servem a pessoas e a agentes: o texto salvo é exatamente o que você escreveu, e um agente que lê a descrição encontra cada seção no mesmo lugar.

Onde cada recurso apareceCopiar link da seção

Os elementos de marcação também estruturam os textos que orientam os agentes: as instruções de agentes, o conteúdo de skills e os prompts de automações, projetos, squads e do workspace.

Elementos de marcaçãoCopiar link da seção

No editor da descrição, digite / para abrir o menu e escolha um item dos grupos SPEC ou Elementos. Você também pode escrever as tags direto no texto.

Critérios de aceite e definição de pronto são coisas diferentes: os critérios dizem o que o produto faz ("o botão exporta um CSV"), e a definição de pronto diz como a entrega termina ("testes passando, documentação atualizada").

Exemplo de descriçãoCopiar link da seção

<context>

O export de pedidos demora mais de um minuto em contas grandes.

</context>

<scope>

- Gerar o CSV em segundo plano.
- Avisar por e-mail quando o arquivo estiver pronto.

</scope>

<acceptance>
  <acceptance-criterion>Um export de 100 mil pedidos chega por e-mail em até 5 minutos.</acceptance-criterion>
</acceptance>

<dod>
  <dod-condition>Testes de integração do export passando.</dod-condition>
  <dod-condition>Documentação de uso atualizada.</dod-condition>
</dod>

<risk level="medium">

O envio de e-mail pode falhar. **Mitigação:** o link também aparece na tarefa.

</risk>

Regras de escritaCopiar link da seção

• Linha em branco em volta do Markdown. Dentro de um elemento, deixe uma linha em branco depois da tag de abertura e antes da de fechamento. Sem isso, listas, negrito e links aparecem como texto cru.
• Atributos entre aspas duplas, como type="warning", e só os listados acima.
• Aninhamento fixo. Os critérios só existem dentro de acceptance, e as condições só dentro de dod. As seções ficam lado a lado, sem uma dentro da outra.
• Feche todos os elementos. Só mcp-tool se fecha sozinho: <mcp-tool server="..." name="..." />.
• Tags dentro de código, como nos exemplos desta página, nunca são interpretadas.

Um elemento com atributo inválido ou sem fechamento aparece como texto cru, com um aviso no editor. O texto é salvo do mesmo jeito.

Blocos ricosCopiar link da seção

Um bloco rico é um bloco de código cuja linguagem é o nome do componente.

Gráficos, tabelas e métricas aceitam title, description e source. Use description para a conclusão em uma frase: ela também é o texto alternativo para leitores de tela.

Exemplo de gráficoCopiar link da seção

```chart
{
  "type": "bar",
  "title": "Tarefas concluídas por semana",
  "description": "As entregas dobraram depois da troca de squad.",
  "source": "Quadro do projeto Web, setembro de 2026",
  "x": { "key": "semana", "label": "Semana" },
  "series": [{ "key": "concluidas", "label": "Concluídas", "color": "1" }],
  "data": [
    { "semana": "S1", "concluidas": 6 },
    { "semana": "S2", "concluidas": 7 },
    { "semana": "S3", "concluidas": 12 },
    { "semana": "S4", "concluidas": 14 }
  ]
}
```

Exemplo de métricasCopiar link da seção

```metric
{
  "items": [
    { "label": "Tempo de ciclo", "value": 3.2, "unit": "dias", "delta": -0.8, "goodDirection": "down" },
    { "label": "Entregas aprovadas", "value": 94, "unit": "%", "delta": 4, "compare": "vs. agosto" }
  ]
}
```

CoresCopiar link da seção

As cores vêm só de um índice da paleta, de "1" a "8", ou de um tom: positive, negative, warning, info e neutral. Não há campo para código hexadecimal: assim os blocos seguem o tema do workspace, no modo claro e no escuro.

Erros e limitesCopiar link da seção

Um bloco com JSON inválido ou com um campo desconhecido não quebra a mensagem: ele aparece como código, com um aviso que aponta o campo com problema.

Acima de um limite, o bloco aparece recolhido, com a contagem real e o máximo.

Validar pela CLICopiar link da seção

Antes de publicar um texto com gráficos, tabelas ou métricas, confira os blocos:

$jiraya markup lint ./comentario.md

O comando valida o JSON de chart, table e metric, o tamanho de cada bloco e o número de blocos do texto. Os comandos jiraya issue create, jiraya issue update, jiraya issue comment add e jiraya issue draft update fazem a mesma checagem e mostram um aviso, sem impedir a publicação.