Adicionar a skill da taiga-cli TG-254

README.md

@@ -8,15 +8,41 @@
 
 ## Install
 
+Install the binary in `~/.local/bin` (it must be on your `PATH`). The commands below use `v0.3.0`, which exists only once that release is published; until then, use the latest tag on [GitHub Releases](https://github.com/BasisTI/taiga-cli/releases).
+
+Download the tarball for your platform together with `SHA256SUMS`; the binary is installed only if its checksum matches. The block runs in a subshell with `set -eu`, so any failing step (download, a missing or failed checksum, extraction) stops it before anything is installed, and your shell stays open. On macOS, where `sha256sum` may be missing, it uses `shasum -a 256`:
+
+```sh
+(
+  set -eu
+  V=0.3.0
+  P=linux_amd64   # linux_arm64, darwin_amd64 or darwin_arm64
+  F="taiga_${V}_${P}.tar.gz"
+  cd "$(mktemp -d)"
+  gh release download "v$V" -R BasisTI/taiga-cli -p "$F" -p SHA256SUMS
+  awk -v f="$F" '$2 == f' SHA256SUMS > checksum
+  test -s checksum || { echo "$F is not in SHA256SUMS" >&2; exit 1; }
+  if command -v sha256sum >/dev/null; then sha256sum -c checksum; else shasum -a 256 -c checksum; fi
+  tar -xzf "$F" taiga
+  mkdir -p "$HOME/.local/bin"
+  install -m 0755 taiga "$HOME/.local/bin/taiga"
+  "$HOME/.local/bin/taiga" version
+)
+```
+
+Or, with Go:
+
 ```sh
-go install github.com/BasisTI/taiga-cli/cmd/taiga@latest
+GOBIN="$HOME/.local/bin" go install github.com/BasisTI/taiga-cli/cmd/taiga@v0.3.0
 ```
 
-Or download the tarball for your platform from [GitHub Releases](https://github.com/BasisTI/taiga-cli/releases), together with `SHA256SUMS`, and check it:
+### Agent skill
+
+[`skills/taiga-cli/SKILL.md`](skills/taiga-cli/SKILL.md) teaches coding agents to use the CLI (in Portuguese): which command to use, how to stop and ask a person on authentication errors, and what to check after an uncertain write instead of repeating it. Install it with the [skills CLI](https://github.com/vercel-labs/skills):
 
 ```sh
-sha256sum -c SHA256SUMS --ignore-missing
-tar -xzf taiga_*_linux_amd64.tar.gz taiga && sudo install taiga /usr/local/bin/
+npx skills add BasisTI/taiga-cli --global   # for every project
+npx skills update --global --yes            # the installed copy never updates itself
 ```
 
 ## Quickstart
@@ -283,6 +309,8 @@ The last check, `project`, reads the selected project (it only reads) and report
 
 ## Coding agents and sandboxes
 
+The [agent skill](#agent-skill) carries these rules for agents.
+
 - A person runs `taiga auth login` once per machine; agents only read the session cache and never see the password.
 - An agent that gets `session_expired` inside a sandbox cannot renew the session there: run `taiga auth refresh` outside the sandbox and retry. `taiga` never spends the stored refresh token when it cannot save the new one, and with a read-only cache it logs in only with `TAIGA_PASSWORD`/`TAIGA_PASSWORD_FILE` (keeping that token in memory), never with the keyring, `secret_command` or the `--insecure-storage` file, whether or not a session exists. Without a session and without an env password it fails with `session_cache_readonly`: run `taiga auth login` outside the sandbox.
 - Codex: enable `network_access = true` and add the state dir to `writable_roots`:

docs/examples/taiga-project.toml

@@ -1,8 +1,10 @@
-# Exemplo de configuração de projeto para `taiga project plan|apply -f`.
+# Configuração de projeto para `taiga project plan|apply -f`.
 #
-# Reproduz o que o configurar-taiga-projeto.sh da skill basis-ci-gitlab prepara: os status
-# opcionais do fluxo da story e os campos de registro de início e de teste. Nomes, cores e
-# descrições são exemplo, não valores embutidos na CLI: confirme a convenção do seu projeto.
+# Este arquivo é a convenção canônica do fluxo da skill basis-ci-gitlab: os status
+# `In revision` e `Waiting for deployment` e os 6 campos de registro de início e de teste.
+# Substitui o configurar-taiga-projeto.sh; as diferenças de comportamento em relação ao
+# script foram aprovadas na US #254 (decisão D5). Mude nomes, cores ou descrições aqui, e
+# não num board isolado, para o fluxo continuar igual em todos os projetos.
 #
 # - Nada é removido nem alterado: status e campos fora do arquivo ficam como estão, e um
 #   declarado que já existe com outra cor, outro `closed`, outro tipo ou outra descrição é

docs/guia.md

@@ -2,6 +2,19 @@
 
 Guia curto para a equipe. A referência completa está no [README](../README.md) (em inglês) e os códigos de erro em [errors.md](errors.md).
 
+## Instalação
+
+O binário vai em `~/.local/bin`, como o `sgo`. O caminho principal é o tar.gz da [release](https://github.com/BasisTI/taiga-cli/releases), conferido pelo `SHA256SUMS` antes de instalar; a alternativa é `GOBIN="$HOME/.local/bin" go install github.com/BasisTI/taiga-cli/cmd/taiga@v0.3.0`. Os comandos estão na seção "Install" do README. Os exemplos com `v0.3.0` só funcionam depois de publicada essa release.
+
+Agentes usam a CLI pela skill [`taiga-cli`](../skills/taiga-cli/SKILL.md), que mora neste repositório e é instalada pelo skills CLI:
+
+```sh
+npx skills add BasisTI/taiga-cli --global   # para todos os projetos
+npx skills update --global --yes            # a cópia instalada não se atualiza sozinha
+```
+
+A skill diz ao agente qual comando usar, que ele para e pede o login a uma pessoa nos erros de autenticação, e o que conferir depois de uma escrita incerta em vez de repeti-la. Quando a CLI e o MCP do Taiga estão disponíveis, a CLI tem precedência; não é aconselhado manter os dois.
+
 ## Login com a conta de serviço
 
 Em cada máquina onde agentes vão usar o Taiga, uma pessoa faz o login uma vez com a conta de serviço:
@@ -172,14 +185,14 @@ taiga story field set 246 --unset "Testado em staging" --unset "Data de entrega"
 - `--unset NOME` (repetível, nome ou id) limpa um campo `checkbox` ou `date`: o Taiga guarda `null` na chave do campo, que continua no dicionário mesmo quando é o último (o Taiga recusa dicionário vazio). Campo sem valor, ou já `null`, não gera escrita. Campo `text` não se limpa (erro de uso); para esvaziar, `"Notas="`. No JSON o valor limpo aparece como `null`; no texto, vazio, como campo sem valor.
 - `story field set` junta os campos informados aos atuais e grava o dicionário inteiro com o `version` do recurso de valores, que é outro, independente do `version` da story. `story get` mostra os dois: o da story no topo e o dos valores em `custom_attributes`.
 - O Taiga não recusa `version` antigo nos valores de campos customizados. A CLI confere a resposta: se outra gravação caiu junto da nossa, sai `field_values_postcondition_failed` (exit 4) e a alteração **foi gravada**; confira com `taiga story field list` antes de repetir.
-- Campos de task: as definições já têm `field list/create --kind task`; o comando de valores de task vem com a #253.
+- Campos de task: as definições têm `field list/create --kind task`, e os valores, `task field list/set`.
 
 ## Status e campos do projeto como código
 
 Substitui o `configurar-taiga-projeto.sh` da skill basis-ci-gitlab. O arquivo TOML declara status de story e campos
-customizados de story; [docs/examples/taiga-project.toml](examples/taiga-project.toml) traz o equivalente ao script
-(`In revision`, `Waiting for deployment` e os seis campos de registro). Nomes, cores e descrições do exemplo são
-exemplo, não configuração embutida na CLI.
+customizados de story. [docs/examples/taiga-project.toml](examples/taiga-project.toml) é a convenção canônica do fluxo
+da `basis-ci-gitlab` (`In revision`, `Waiting for deployment` e os seis campos de registro); as diferenças de
+comportamento em relação ao script foram aprovadas na US #254. A CLI não embute esses valores: eles vêm do arquivo.
 
 ```sh
 taiga status list --output text
@@ -215,7 +228,7 @@ taiga project apply -f taiga-project.toml          # exige admin do projeto
 
 ## `taiga api` para o que ainda não tem comando próprio
 
-Enquanto os comandos curados das próximas fases não chegam, `taiga api` cobre as receitas que hoje estão na skill `basis-ci-gitlab`. O caminho é relativo a `/api/v1/`, e `--auto-version` lê o `version` atual antes de gravar.
+`taiga api` é a saída de emergência para o que não tem comando curado; bloqueio e campos customizados, por exemplo, já têm (`story update --block`, `story field set`). O caminho é relativo a `/api/v1/`, e `--auto-version` lê o `version` atual antes de gravar. O `taiga api` não confere a escrita: um exit 7 depois do envio pode ter gravado, então confira com um `GET` antes de repetir.
 
 ```sh
 # bloquear com motivo