Pular para o conteúdo
UseIA
0
Skill

Allium

Crédito: juxt no GitHub (juxt/allium) · 0 cópias

Indicada na UseIA por Cristiano Rochenbach Abreu em 5 de out. de 2026

505 estrelas no GitHubVer no GitHub
Salvar

Tradução feita por IA. Em caso de dúvida, vale o texto original (aba “Original”).

---
name: allium
description: Dê aos seus agentes de IA algo mais útil que um prompt. Velocidade por meio da clareza.
version: 3
auto_trigger:
  - file_patterns: ["**/*.allium"]
  - keywords: ["allium", "allium spec", "allium specification", ".allium file"]
---

# Allium

Allium é uma linguagem formal para capturar o comportamento do software no nível do domínio. Ela fica entre as descrições informais de funcionalidades e a implementação, oferecendo uma forma precisa de especificar o que o software faz sem prescrever como ele é construído.

O nome vem da família botânica que contém as cebolas e as echalotas, dando continuidade a uma tradição nas ferramentas de especificação de comportamento iniciada pelo Cucumber e pelo Gherkin.

Princípios principais:

- Descreve o comportamento observável, não a implementação
- Captura a lógica de domínio que importa no nível do comportamento
- Gera testes de integração e de ponta a ponta (não testes unitários)
- Força as ambiguidades a virem à tona antes da implementação
- Agnóstica quanto à implementação: a mesma especificação poderia ser implementada em qualquer linguagem

Allium NÃO especifica escolhas de linguagem de programação ou de framework, esquemas de banco de dados ou mecanismos de armazenamento, designs de API ou layouts de interface, nem algoritmos internos (a menos que sejam preocupações de nível de domínio).

## Tabela de roteamento

| Tarefa | Ferramenta | Quando |
|--------|------------|--------|
| Escrever ou ler arquivos `.allium` | esta skill | Você precisa da sintaxe e da estrutura da linguagem |
| Construir uma especificação por meio de conversa | skill `elicit` | O usuário descreve uma funcionalidade ou comportamento que quer construir |
| Extrair uma especificação de código existente | skill `distill` | O usuário tem código de implementação e quer uma especificação a partir dele |
| Modificar uma especificação existente | skill `tend` | O usuário quer mudanças pontuais em arquivos `.allium` |
| Verificar o alinhamento entre especificação e código | skill `weed` | O usuário quer encontrar ou corrigir divergências entre a especificação e a implementação |
| Gerar testes a partir de uma especificação | skill `propagate` | O usuário quer gerar testes, propriedades de PBT ou testes de máquina de estados a partir de uma especificação |
| Atestar a convergência de um ciclo | skill `witness` | O usuário quer confirmar de forma independente a alegação de convergência de uma execução a partir da verdade de base — os testes realmente passam, nenhum teste gerado foi enfraquecido, nenhuma pergunta bloqueante foi deixada de lado em silêncio |
| Conduzir o ciclo inteiro até a convergência | esta skill (veja [conduzindo o ciclo](./references/driving-the-loop.md)) | O usuário quer construir ou reconciliar uma funcionalidade de ponta a ponta — `/allium <goal>` executa o ciclo reunir→agir→verificar→repetir de forma autônoma até que especificação, testes e código concordem |

## Respondendo a `/allium` (ciclo em primeiro lugar)

`/allium` é o ponto de entrada. Incline-se para o caminho autônomo — o valor do ciclo completo é exatamente o que o uso ocasional de uma skill isolada deixa escapar:

- **Tarefa única e clara** → encaminhe direto para essa skill (conforme a tabela de roteamento); não faça o usuário atravessar um menu.
- **Um objetivo ou funcionalidade** (por exemplo, "adicionar cartões-presente", "fazer a redefinição de senha funcionar") → conduza você mesmo o ciclo inteiro, de ponta a ponta, em vez de executar uma única fase. Siga [conduzindo o ciclo](./references/driving-the-loop.md).
- **Pedido vazio ou ambíguo** → oriente o usuário começando pelo ciclo: ofereça conduzir o ciclo como padrão, depois liste as skills individuais como o caminho de controle, com uma dica de uma linha cada, e sugira um ponto de partida concreto a partir do estado do projeto (já existem especificações `.allium`? há código, mas nenhuma especificação? há divergências a reconciliar?). Por exemplo:

  > Diga-me um objetivo e eu conduzo o ciclo inteiro — especificação → testes → código, até que concordem. Ou execute um passo você mesmo: `elicit` (especificação a partir da intenção), `distill` (especificação a partir de código existente), `propagate` (testes a partir de uma especificação), `tend` (editar uma especificação), `weed` (corrigir a divergência entre especificação e código). Você tem código, mas ainda nenhum `.allium`, então eu começaria destilando — ou simplesmente me dê o objetivo e eu levo de ponta a ponta.

Comece pelo ciclo; mantenha as skills individuais a um passo de distância para os usuários que querem controle manual. E, quando uma skill isolada terminar, sugira proativamente a próxima fase em vez de esperar que lhe peçam.

## O ciclo Allium (sequenciamento recomendado)

As skills não são comandos de uso único; elas se combinam em um ciclo de estilo autônomo — **reunir contexto → agir → verificar → repetir** — que leva três artefatos ao acordo: a **especificação** (intenção), os **testes** (contrato) e o **código** (implementação). Reúna contexto com `/elicit` ou `/distill` (a especificação é um contexto durável); aja com `/propagate` e depois com a implementação (em trabalho que começa pela especificação, confirme que os novos testes falham primeiro — um teste que já está verde antes de você implementar já está coberto ou é vazio); verifique rodando os testes, depois `/weed` e depois as verificações estruturais do CLI; repita até convergir. A verificação é a fase que mais importa, e o sinal de especificação + testes + weed é o que torna o ciclo confiável. Depois de invocar uma skill, sugira proativamente o próximo passo em vez de esperar que lhe peçam. Para rodar o ciclo inteiro até a convergência de uma vez, basta dar um objetivo ao `/allium` — ele conduz o ciclo para você, seguindo [conduzindo o ciclo](./references/driving-the-loop.md).

Dois pontos de entrada, um único ciclo de convergência:

- **Primeiro a especificação (para a frente, a partir da intenção):** `/elicit` → `/propagate` → implementar → `/weed`; use `/tend` e depois `/propagate` de novo quando os requisitos mudarem.
- **Primeiro o código (para trás, a partir de código existente):** `/distill` → revisar comportamento pretendido vs. acidental → `/propagate` → rodar os testes contra o código → `/weed` para reconciliar → repetir por área.

O trabalho está "concluído" quando os testes passam, o `/weed` não relata divergência, não resta nenhuma pergunta em aberto (e, no caso de começar pelo código, um novo `/distill` não encontra nada de novo), e uma passada independente do `/witness` atesta essa alegação contra a verdade de base. Duas regras permanentes durante o ciclo: nunca enfraqueça um teste gerado para fazê-lo passar (corrija a especificação e propague de novo) e escale a ambiguidade genuína para o humano em vez de adivinhar — as duas são aplicadas pelo witness no portão de convergência, e não deixadas à confiança.

A implementação em si é programação comum — o Allium produz a especificação e os testes, não o código da aplicação. Veja a referência de [ciclos recomendados](./references/recommended-loops.md) para o passo a passo completo, os diagramas, as condições de saída e o prompt de implementação.

## Resumo rápido da sintaxe

### Entidade

```
entity Candidacy {
    -- Fields
    candidate: Candidate
    role: Role
    status: pending | active | completed | cancelled   -- inline enum
    retry_count: Integer

    -- Relationships
    invitation: Invitation with candidacy = this         -- one-to-one
    slots: InterviewSlot with candidacy = this           -- one-to-many

    -- Projections
    confirmed_slots: slots where status = confirmed
    pending_slots: slots where status = pending

    -- Derived
    is_ready: confirmed_slots.count >= 3
    has_expired: invitation.expires_at <= now
}
```

### Entidade externa

```
external entity Role { title: String, required_skills: Set<Skill>, location: Location }
```

### Tipo de valor

```
value TimeRange { start: Timestamp, end: Timestamp, duration: end - start }
```

### Tipo soma

Uma entidade base declara um campo discriminador cujos valores com inicial maiúscula nomeiam as variantes. As variantes usam a palavra-chave `variant`.

```
entity Node {
    path: Path
    kind: Branch | Leaf              -- discriminator field
}

variant Branch : Node {
    children: List<Node?>
}

variant Leaf : Node {
    data: List<Integer>
    log: List<Integer>
}
```

Valores separados por barra, em minúsculas, são literais de enumeração (`status: pending | active`). Valores com inicial maiúscula são referências a variantes (`kind: Branch | Leaf`). Guardas de tipo (`requires:` ou ramos `if`) restringem a uma variante e liberam seus campos.

### Module given

Declara as instâncias de entidades sobre as quais as regras de um módulo operam. Todas as regras herdam essas vinculações. Nem todo módulo precisa de uma: regras delimitadas por gatilhos em entidades de domínio obtêm suas entidades do gatilho. O `given` serve para especificações em que as regras operam sobre instâncias compartilhadas que existem uma vez por escopo de módulo.

```
given {
    pipeline: HiringPipeline
    calendar: InterviewCalendar
}
```

As instâncias de módulos importados são acessadas por nomes qualificados (`scheduling/calendar`) e não aparecem no bloco `given` local. É diferente do `context` de uma surface, que vincula um escopo paramétrico para um contrato de fronteira.

### Regra

```
rule InvitationExpires {
    when: invitation: Invitation.expires_at <= now
    requires: invitation.status = pending
    let remaining = invitation.proposed_slots where status != cancelled
    ensures: invitation.status = expired
    ensures:
        for s in remaining:
            s.status = cancelled
    @guidance
        -- Non-normative implementation advice.
}
```

### Tipos de gatilho

- **Estímulo externo**: `when: CandidateSelectsSlot(invitation, slot)` — ação vinda de fora do sistema
- **Transição de estado**: `when: interview: Interview.status transitions_to scheduled` — a entidade mudou de estado (apenas transição, não criação)
- **Estado passa a ser**: `when: interview: Interview.status becomes scheduled` — a entidade tem esse valor, seja por criação ou por transição
- **Temporal**: `when: invitation: Invitation.expires_at <= now` — condição baseada em tempo (sempre adicione uma guarda `requires` contra o disparo repetido)
- **Condição derivada**: `when: interview: Interview.all_feedback_in` — um valor derivado passa a ser verdadeiro
- **Criação de entidade**: `when: batch: DigestBatch.created` — dispara quando uma nova entidade é criada
- **Encadeado**: `when: AllConfirmationsResolved(candidacy)` — assina a emissão de um gatilho vinda da cláusula ensures de outra regra

Todos os gatilhos com escopo de entidade usam a vinculação explícita `var: Type`. Use `_` como vinculação descartável quando o nome não for necessário: `when: _: Invitation.expires_at <= now`, `when: SomeEvent(_, slot)`.

### Iteração no nível da regra

Uma cláusula `for` aplica o corpo da regra uma vez para cada elemento de uma coleção:

```
rule ProcessDigests {
    when: schedule: DigestSchedule.next_run_at <= now
    for user in Users where notification_setting.digest_enabled:
        let settings = user.notification_setting
        ensures: DigestBatch.created(user: user, ...)
}
```

### Padrões de ensures

Ensures

[…] Conteúdo completo no GitHub.