memory.setup
Setup multi-OS · ~30 min · Markdown + Git

Configure sua
memória de IA.

Vault compartilhado entre Claude Code, Cursor, Codex, Gemini e Kilocode. Cada agente lê o contexto da empresa e do projeto antes de qualquer sessão. Sem servidor, sem banco, sem plugin — só arquivos versionados em git.

macOS Linux Windows 11
Por que

Agentes de IA não têm memória — até você dar uma a eles.

Toda nova sessão começa do zero. Você repete contexto, padrões e decisões já tomadas. Pior: sem isolamento, contexto de uma empresa vaza para projetos de outra.

!
O problema

Esquecimento entre sessões

Cada conversa nova começa do zero. Stack, padrões, decisões — tudo perdido entre uma sessão e a seguinte.

×
O risco

Contextos misturados

Sem fronteiras claras, o agente vaza preferências da Empresa A para projetos da Empresa B. Não dá.

A solução

Vault Markdown versionado

Pasta de arquivos .md hierárquica por empresa, projeto e tarefa. Lida automaticamente em toda sessão de qualquer agente.

Como funciona

Bootstrap automático em toda sessão.

Cada ferramenta de IA carrega instruções globais ao iniciar. Essas instruções dizem ao agente: detecte a empresa pelo CWD, leia esses arquivos, siga esse protocolo, gere esse session ID. Tudo derivado do mesmo vault.

memory-vault/ ├── global/ # preferências e padrões válidos para todas as empresas │ ├── preferences.md │ └── work-patterns.md ├── companies/ # uma pasta por empresa (isolamento estrito) │ ├── empresa-a/ │ │ ├── memory/ # context.md, preferences.md, conventions.md │ │ └── projects/ │ │ └── projeto-x/ │ │ ├── memory/decisions.md │ │ └── tasks/ │ │ └── 2026-05-07-slug/ │ │ ├── CONTEXTO.md │ │ ├── TODO.md │ │ ├── PROGRESSO.md # append-only │ │ └── PR_DESCRIPTION.md │ └── empresa-b/ ├── configs/ # protocolo por ferramenta de IA │ ├── .claude/agent-protocol.md │ ├── .cursor/agent-protocol.md │ ├── .codex/agent-protocol.md │ ├── .gemini/agent-protocol.md │ └── .kilocode/agent-protocol.md ├── templates/task/ # 4 arquivos obrigatórios de toda task ├── logs/ # um arquivo por sessão └── agents/ # conhecimento promovido (curado)

Detecção de empresa pelo path do projeto. Você define um segmento único por empresa (ex.: /AcmeCorp/acme). O agente inspeciona o CWD da sessão e carrega só a pasta correspondente.

Antes de começar

Pré-requisitos.

Tudo padrão. Nada exótico. Provavelmente você já tem.

Coleta inicial

4 informações antes do agente começar.

Quando colar o prompt no agente, ele perguntará isso primeiro. Tenha as respostas prontas:

01

Caminho absoluto do vault

Onde o repo foi clonado na sua máquina. Confirme com pwd dentro da pasta clonada.

02

Lista de empresas + path segments

Para cada empresa que você separa, qual segmento de path identifica ela. Ex.: ~/work/AcmeCorp/acme.

03

Ferramentas de IA que você usa

Marque as aplicáveis: Claude Code, Cursor, Codex CLI, Gemini CLI, Kilocode. As outras são configuradas depois conforme você adotar.

04

Nome e e-mail do git

Só se ainda não estiverem configurados globalmente. Confira com git config --global user.name e user.email.

Setup

10 passos. Do zero ao funcionando.

Cada passo abaixo é executado pelo agente quando você cola o prompt do Apêndice. Esta seção é o panorama.

01

Criar repo privado no GitHub

Crie memory-vault (ou nome equivalente) no seu GitHub pessoal, sempre privado. Clone para uma pasta neutra fora de qualquer projeto: ~/Documents/memory-vault (macOS/Linux) ou C:\Users\<voce>\Documents\memory-vault (Windows).

git clone · git init
02

Criar a estrutura de pastas

Hierarquia de global/, companies/{empresa}/ (uma por empresa), configs/.{tool}/, templates/task/, logs/, agents/, docs/, prompts/. O agente cria tudo de uma vez.

mkdir -p · estrutura raiz
03

Preencher arquivos-base

Frontmatter YAML em todos: global/preferences.md, global/work-patterns.md, três arquivos de memória por empresa (context, preferences, conventions), 4 templates de task, 5 protocolos de agente em configs/.

Markdown + YAML
04

Criar AGENTS.md, CLAUDE.md e .gitignore

AGENTS.md é a fonte canônica para qualquer agente. CLAUDE.md aponta para AGENTS.md. .gitignore bloqueia .env, node_modules/, .DS_Store, etc.

root files
05

Instalar git hooks

pre-commit valida frontmatter (task, session_id, company obrigatórios em logs e tasks). post-checkout roda git pull --ff-only ao entrar em main. Ambos executáveis (bash puro).

.git/hooks/
06

(Opcional) Instalar Obsidian como viewer

Baixar em obsidian.md. Abrir o vault como Open folder as vault. Wikilinks, graph view, busca rápida — tudo opcional. O vault funciona sem Obsidian.

opcional
07

Criar skills globais

Duas skills essenciais: criar-skill-global (distribui SKILL.md para todas as ferramentas de IA da máquina) e memory-bootstrap (carrega o vault no início de cada sessão). Detalhes na próxima seção.

~/.claude/skills/
08

Configurar auto-start em cada ferramenta de IA

Cada ferramenta tem um arquivo de instruções globais diferente. Você cola o bloco de bootstrap (com path do vault e detecção de empresa) em cada um. Ver tabs abaixo.

~/.claude/CLAUDE.md · ~/.codex/instructions.md · ...
09

Configurar a skill jira-hagens (opcional)

Se você trabalha na Hagens/WeHandle: gere seu token em id.atlassian.com/manage-api-tokens e cole na skill. Cada usuário tem seu próprio token. Nunca compartilhe nem commite.

~/.claude/skills/jira-hagens/
10

Primeiro commit + push + verificação

Commits atômicos (Conventional Commits, em inglês). Push final obrigatório — o vault só está consolidado quando publicado. Depois, simulação: abra novo projeto, o agente deve detectar a empresa e carregar contexto sem você pedir.

git push origin main

Política de commits no vault. Sempre commits atômicos direto em main com push obrigatório ao fim da sessão. Branches longas criam janelas em que outros agentes operam sem o contexto mais recente. Nunca usar --force, --amend em commits publicados, ou --no-verify sem permissão explícita.

Skills globais

Três skills carregam todo o resto.

Skills são arquivos SKILL.md na pasta de cada ferramenta de IA. O agente as descobre automaticamente pelo campo description e as invoca quando o prompt do usuário casa.

criar-skill-global

Distribui skills para todas as ferramentas

Você escreve uma skill em ~/.claude/skills/<nome>/SKILL.md e essa meta-skill copia automaticamente para os diretórios de Cursor, Codex, Gemini, Kilocode. Sem ela, copiar manualmente cada vez.

  • Trigger: "crie uma skill global chamada X"
  • Distribui para 7 diretórios padrão
  • Sobrescreve se já existir
memory-bootstrap

Carrega o vault no início de toda sessão

Detecta a empresa pelo CWD, lê global/ + companies/{empresa}/memory/, identifica o protocolo da ferramenta atual, gera o session ID. Chamada implícita por convenção, sem ser pedida.

  • Trigger: início de sessão, "carrega memória"
  • Lê em ordem: global → empresa → projeto → task
  • Bloqueia cross-company writes
jira-hagens

Operações completas no Jira da Hagens

Skill com todas as receitas REST API v3 + Agile v1.0: search/JQL, create/update, transitions, board columns, sprints, comments, links, attachments. Cada usuário cola o próprio token.

  • Trigger: "meus cards no jira", "mova SOL-X pra Done"
  • Auth basic com email + API token pessoal
  • Suporta SOL (Solventum) e WH (WeHandle)

Sobre o token do jira-hagens. O token é pessoal e não pode ser commitado nem compartilhado. Cada usuário gera o seu em id.atlassian.com/manage-api-tokens e cola na própria SKILL.md local. Se você revogou um token antigo, gere outro e atualize.

Auto-start

Configure cada ferramenta para carregar o vault sem pedir.

Cada ferramenta tem um mecanismo diferente para instruções globais. Você cola o mesmo bloco em todos, mudando só o sufixo do session ID.

Claude Code

~/.claude/CLAUDE.md

Crie ou edite o arquivo. Carregado automaticamente em toda sessão, em qualquer projeto.

## Memory Bootstrap (auto, every session)

At the start of every conversation, before any task, load the shared memory vault.

1. Detect company from CWD:
   - Path contains `/EmpresaA/` -> company = empresa-a
   - Path contains `/EmpresaB/` -> company = empresa-b
   - Otherwise -> load global only

2. Read in order:
   {VAULT}/global/preferences.md
   {VAULT}/global/work-patterns.md
   {VAULT}/companies/{company}/memory/context.md
   {VAULT}/companies/{company}/memory/preferences.md
   {VAULT}/companies/{company}/memory/conventions.md

3. Follow the agent protocol:
   {VAULT}/configs/.claude/agent-protocol.md

4. Session ID format: YYYYMMDD-HHMMSS-claude

CRITICAL: Never mix context between companies.

Codex CLI

~/.codex/instructions.md

Mesma lógica do Claude Code. Apenas troque o protocolo e o sufixo do session ID:

# Same content as Claude Code, but:
3. Follow the agent protocol:
   {VAULT}/configs/.codex/agent-protocol.md

4. Session ID format: YYYYMMDD-HHMMSS-codex

Gemini CLI

~/.gemini/GEMINI.md

Se já existir conteúdo, adicione ao final sem sobrescrever. Use editor de texto ou a Write tool do agente — não sed, que pode zerar o arquivo no Windows/Git Bash.

# Same content as Claude Code, but:
3. Follow the agent protocol:
   {VAULT}/configs/.gemini/agent-protocol.md

4. Session ID format: YYYYMMDD-HHMMSS-gemini

Kilocode

~/.kilocode/rules/memory-bootstrap.md + ~/.config/kilo/kilo.jsonc

Dois passos. Primeiro, criar o arquivo de rules:

mkdir -p ~/.kilocode/rules
# crie ~/.kilocode/rules/memory-bootstrap.md com o bloco padrão
# (Session ID format: YYYYMMDD-HHMMSS-kilocode)

Depois, registrar no kilo.jsonc com path absoluto:

{
  "$schema": "https://app.kilo.ai/config.json",
  "instructions": [
    "/caminho/absoluto/para/.kilocode/rules/memory-bootstrap.md"
  ]
}

Cursor

Settings → General → Rules for AI

Não há arquivo de config — só a UI. Abra Cursor, vá em Settings → General → Rules for AI, cole o bloco de bootstrap (com sufixo cursor no session ID). Feito uma única vez, fica ativo em todos os projetos.

Apêndice

Prompts prontos para colar no agente.

Três prompts. Você cola, o agente pergunta as 4 informações da seção anterior e executa. Os dois primeiros são o setup do vault em cada SO. O terceiro cria a skill jira-hagens com o seu token pessoal.

Prompt — macOS / Linux

cole no Claude Code dentro do repo recém-clonado

Trabalha de forma autônoma. Pergunta apenas as 4 informações iniciais. Caminhos para zsh/bash.

# PROMPT — Configurar Memory Vault (macOS / Linux)

Você é um agente de IA executando dentro do repositório `memory-vault` que acabou
de ser clonado. Faça o bootstrap completo do vault de memória compartilhada.

Trabalhe de forma autônoma. Pergunte apenas o necessário (Passo 0). Use os
comandos do Passo 1 em diante sem confirmação a cada arquivo.

## 0. Coletar 4 informações do usuário (uma única mensagem)

1. Caminho absoluto onde o repositório foi clonado (confirmar com `pwd`).
2. Lista de empresas/contextos a separar (ex.: `acme`, `startup-x`, `pessoal`).
   Para cada uma, o segmento de path único (ex.: `/AcmeCorp/`).
3. Quais ferramentas de IA o usuário usa (Claude Code, Cursor, Codex CLI,
   Gemini CLI, Kilocode).
4. Nome e email do git (só se não estiverem em `git config --global`).

## 1. Conceito (internalize antes de criar arquivos)

- Vault = pasta de Markdown versionada em git. Sem banco, sem API, sem plugin.
- Toda sessão de qualquer agente, antes de qualquer ação:
  1. Detecta empresa pelo segmento de path do CWD.
  2. Carrega `global/` -> `companies/{empresa}/memory/` -> contexto da task.
  3. Aplica o protocolo da ferramenta em `configs/.{tool}/agent-protocol.md`.
- Hierarquia: global < companies/{empresa} < projects/{proj} < tasks/{task}.
- Isolamento estrito entre empresas: sem cross-reads, sem exceção.

## 2. Estrutura a criar

global/ (preferences.md, work-patterns.md, _index.md)
companies/{empresa}/_index.md + memory/ (3 arquivos) + projects/_index.md
configs/.claude .cursor .codex .gemini .kilocode (cada um com agent-protocol.md)
templates/task/ (CONTEXTO.md TODO.md PROGRESSO.md PR_DESCRIPTION.md)
templates/project/_index.md
agents/_index.md
logs/.gitkeep
docs/README.md
prompts/.gitkeep
AGENTS.md, CLAUDE.md, .gitignore na raiz

Use Write/Edit do agente — não `cat <<EOF` no shell.

## 3. Conteúdo dos arquivos-base

3.1 global/preferences.md
   Frontmatter YAML obrigatório: type=preference, scope=global, status=stable,
   created, updated, version, tags. Conteúdo: idioma (tasks PT, código/commits
   EN), datas em ISO 8601, atualização contínua de PROGRESSO.md, Markdown
   puro, nunca deletar memória (marcar status=deprecated).

3.2 global/work-patterns.md
   Git Flow (feature/*, bugfix/*, etc.), Conventional Commits, atomicidade,
   PR template. Inclua exceção: dentro deste repo, mudanças de memória
   sempre por commit atômico direto em `main` com push obrigatório.

3.3 companies/{empresa}/memory/{context,preferences,conventions}.md
   Os 3 arquivos com frontmatter (type, scope=company, company, datas, tags)
   e seções stub que o usuário preenche depois: stack, ambientes, stakeholders,
   padrões de código, ferramentas. Não inventar — deixar `[a preencher]`.

3.4 templates/task/*.md
   Os 4 obrigatórios. Frontmatter:
     type: task
     scope: task
     company: <empresa>
     project: <projeto>
     task: <YYYY-MM-DD-nome>
     agent: <claude|codex|cursor|kilocode|gemini>
     session_id: <YYYYMMDD-HHMMSS-agent>
     status: draft
     created/updated, tags
   - CONTEXTO.md: Problema, Contexto, Hipóteses, Escopo (in/out), Links.
   - TODO.md: checkboxes [ ].
   - PROGRESSO.md: append-only. Cada sessão adiciona um bloco com
     `## {session_id}`, Ações, Decisão, Próximo. Nunca reescrever blocos antigos.
   - PR_DESCRIPTION.md: rascunho de PR (problema, solução, áreas afetadas, risco).

3.5 configs/.{tool}/agent-protocol.md
   Canônico: configs/.claude/agent-protocol.md. Os outros herdam dele e mudam
   só o sufixo do session_id (-cursor, -codex, -gemini, -kilocode).
   Cada protocolo descreve: bootstrap (git pull, detectar empresa, carregar
   contexto), permissões de escrita por path, formato de session_id,
   commits atômicos em `main`, push obrigatório.

3.6 AGENTS.md (raiz)
   Fonte canônica para qualquer agente. Cobre: natureza do repo, estrutura,
   bootstrap obrigatório, tabela de permissões, convenções (Markdown +
   frontmatter, ISO 8601, append-only em PROGRESSO.md, isolamento entre
   empresas), §6 commits atômicos em `main`, §7 auto-sync (git pull/push),
   §8 task management (uma task por sessão, validação em pre-commit), §9
   fluxo de início/fim de sessão.

3.7 CLAUDE.md (raiz) — apontador curto para AGENTS.md.

3.8 .gitignore
   .DS_Store, .env, node_modules/, __pycache__/, *.pyc, .claude/worktrees/,
   logs/*.tmp.md, .obsidian/workspace*

## 4. Git hooks

.git/hooks/pre-commit (executável): valida que todo arquivo novo em logs/
ou companies/*/projects/*/tasks/* tem `task:`, `session_id:`, `company:`
no frontmatter. Sem isso, rejeitar.

.git/hooks/post-checkout (executável): roda `git pull --ff-only origin main`
ao fazer checkout para `main`.

chmod +x .git/hooks/pre-commit .git/hooks/post-checkout

Bash puro nos hooks. Sem PowerShell.

## 5. Auto-start em cada ferramenta marcada no Passo 0.3

Bloco de bootstrap padrão (substituir {VAULT}, {SEGMENTOS}, {SUFIXO}):

```
## Memory Bootstrap (auto, every session)

At the start of every conversation, before any task, load the shared memory vault.

1. Detect company from CWD:
   - Path contains `/AcmeCorp/` -> company = acme
   - Path contains `/StartupX/` -> company = startup-x
   - Otherwise -> load global only

2. Read in order:
   {VAULT}/global/preferences.md
   {VAULT}/global/work-patterns.md
   {VAULT}/companies/{company}/memory/context.md
   {VAULT}/companies/{company}/memory/preferences.md
   {VAULT}/companies/{company}/memory/conventions.md

3. Follow the agent protocol:
   {VAULT}/configs/.{tool}/agent-protocol.md

4. Session ID format: YYYYMMDD-HHMMSS-{SUFIXO}

CRITICAL: Never mix context between companies.
```

Locais por ferramenta (macOS/Linux):
- Claude Code: ~/.claude/CLAUDE.md
- Codex CLI:   ~/.codex/instructions.md
- Gemini CLI:  ~/.gemini/GEMINI.md (anexar ao final, não sobrescrever)
- Kilocode:    ~/.kilocode/rules/memory-bootstrap.md + path absoluto
              registrado em ~/.config/kilo/kilo.jsonc (chave `instructions: [...]`)
- Cursor:      Settings -> General -> Rules for AI (UI — colar manualmente)

mkdir -p para diretórios faltantes. Não usar `sed` em GEMINI.md.

## 6. Primeiro commit + push

Conventional Commits em inglês. Atômicos. Lotes possíveis:
  chore(global): add preferences and work-patterns
  chore(templates): add task and project templates
  chore(configs): add agent-protocol for all tools
  chore(companies/{empresa}): scaffold memory and projects
  docs: add AGENTS.md and CLAUDE.md
  chore(git): install pre-commit and post-checkout hooks

Antes do push final:
  git status            # tree limpa
  git log origin/main..HEAD   # vazio depois do push

## 7. Verificação final

1. tree -L 3 (ou find . -maxdepth 3 -type d)
2. ls -l .git/hooks/pre-commit (executável)
3. Em sessão simulada, agente da ferramenta configurada detecta empresa
   pelo CWD e carrega contexto sem ser pedido.
4. Resumo final ao usuário em uma única mensagem:
   - Caminho do vault
   - Empresas criadas
   - Ferramentas configuradas e arquivos tocados
   - Próximos passos manuais (preencher context.md de cada empresa,
     instalar Obsidian se quiser viewer)

## Regras inegociáveis

- Nunca misturar conteúdo entre empresas.
- Nunca commitar .env ou tokens. Verificar antes de cada `git add`.
- Nunca usar --force, --amend em commits publicados, --no-verify, ou
  rebase sobre `main` sem instrução explícita.
- Datas em ISO 8601. Tasks em PT, commits em EN.
- Em dúvida sobre escopo: pergunte. Não invente conteúdo de empresa.

Prompt — Windows 11

cole no Claude Code dentro do repo recém-clonado

Mesma lógica do prompt macOS, ajustando os locais de auto-start e usando PowerShell como shell padrão.

# PROMPT — Configurar Memory Vault (Windows 11)

Idêntico ao prompt macOS/Linux, com estas diferenças apenas:

## 0. Coletar 4 informações
   - Caminho absoluto: C:\Users\<voce>\Documents\memory-vault
     (confirmar com `pwd` no PowerShell ou `cd` sem args).
   - Demais perguntas: iguais ao prompt macOS.

## 4. Git hooks (Git Bash, não PowerShell)
   Os hooks rodam no Git Bash interno. Mantenha bash puro:

     #!/usr/bin/env bash
     # ...validação de frontmatter...

   chmod +x .git/hooks/pre-commit .git/hooks/post-checkout
   (No Windows, abra Git Bash para chmod. PowerShell não tem chmod nativo.)

## 5. Auto-start em cada ferramenta — locais no Windows

Substituir {USER} pelo seu usuário. Caminhos:

  Claude Code: %USERPROFILE%\.claude\CLAUDE.md
               (= C:\Users\{USER}\.claude\CLAUDE.md)

  Codex CLI:   %USERPROFILE%\.codex\instructions.md

  Gemini CLI:  %USERPROFILE%\.gemini\GEMINI.md
               (anexar ao final, NÃO sobrescrever)

  Kilocode:    %USERPROFILE%\.kilocode\rules\memory-bootstrap.md
               registrar path em %APPDATA%\kilo\kilo.jsonc:
                 "instructions": [
                   "C:/Users/{USER}/.kilocode/rules/memory-bootstrap.md"
                 ]
               IMPORTANTE: usar barras `/` no JSON, não barras invertidas.

  Cursor:      Settings -> General -> Rules for AI (UI)

Crie diretórios ausentes via PowerShell:
  New-Item -ItemType Directory -Path "$env:USERPROFILE\.claude" -Force

Use Write/Edit do agente para o conteúdo dos arquivos.

## Caminhos do vault em bootstrap

No Windows, os caminhos no bloco de bootstrap usam barras normais
para máxima compatibilidade entre ferramentas:

  C:/Users/{USER}/Documents/memory-vault/global/preferences.md

(Algumas ferramentas aceitam C:\Users\... também, mas `/` é mais robusto.)

## 6. Commits e push: idênticos ao prompt macOS/Linux.

## 7. Verificação final

  PowerShell: tree /F | Select-Object -First 60
  Git Bash:   tree -L 3 (se instalado), ou ls -R | head -100
  Verificar hooks:  Get-ChildItem .git\hooks\pre-commit

Resumir ao usuário: vault path, empresas, ferramentas configuradas,
próximos passos manuais.

## Regras inegociáveis: as mesmas do prompt macOS.

Prompt — Skill jira-hagens (com seu token pessoal)

cole no Claude Code · cada usuário gera o próprio token

Token pessoal. Antes de usar este prompt, gere seu token em id.atlassian.com/manage-api-tokens → "Create API token". Substitua <SEU_EMAIL> e <SEU_TOKEN> antes de colar. Não compartilhe nem commite o token.

# Crie para mim a skill global `jira-hagens` no Claude Code.

Antes de criar, minhas credenciais:
- JIRA_INSTANCE_URL: https://hxlab-hagens.atlassian.net
- JIRA_USER_EMAIL:   <SEU_EMAIL>
- JIRA_API_KEY:      <SEU_TOKEN>
  (gerado em https://id.atlassian.com/manage-api-tokens)

Crie ~/.claude/skills/jira-hagens/SKILL.md com:

---
name: jira-hagens
description: Operate the Hagens/WeHandle Jira (https://hxlab-hagens.atlassian.net) end-to-end via REST API v3. Use when the user wants to list, search, read, create, update, transition, comment, link, label, assign, estimate, attach files, add to/remove from sprint, move across board columns, manage epics/subtasks, or perform any Kanban/Scrum operation on Jira. Triggers include "meus cards no jira", "lista o backlog", "cria um card", "mova SOL-X pra Done", "adiciona SOL-X na sprint atual", or any reference to a Jira issue key (SOL-*, WH-*).
---

# Jira Hagens — Full Kanban/Scrum Operations

## Credentials (this user)
- JIRA_INSTANCE_URL: https://hxlab-hagens.atlassian.net
- JIRA_USER_EMAIL:   <SEU_EMAIL>
- JIRA_API_KEY:      <SEU_TOKEN>

Auth = HTTP Basic com `email:api_key` base64-encoded.

### Bash one-liner
JIRA_AUTH="-u <SEU_EMAIL>:<SEU_TOKEN>"
JIRA_BASE="https://hxlab-hagens.atlassian.net"
JIRA_H='-H Content-Type:application/json -H Accept:application/json'

## Known projects/boards
- SOL — Solventum (board id 680, Scrum)
- WH — WeHandle

## API surface
- Issues / search / users / fields: /rest/api/3/...
- Boards / sprints / backlog / columns: /rest/agile/1.0/...

## 1. Search & List
1.1 Meus cards abertos:
  curl -s $JIRA_AUTH "$JIRA_BASE/rest/api/3/search?jql=assignee=currentUser()%20AND%20resolution=Unresolved%20ORDER%20BY%20updated%20DESC&fields=summary,status,priority,issuetype,duedate,project,sprint&maxResults=50"

1.2 JQL genérico (project = SOL AND ... ORDER BY rank), 1.3 issue completo
  com expand=transitions, 1.4 comentários e attachments.

## 2. Create — issue, sub-task, epic, link to epic.
## 3. Update — summary, description, priority, labels, duedate, assignee
   (descobrir accountId via /rest/api/3/user/search), story points
   (descobrir customfield via /rest/api/3/field).
## 4. Transitions — sempre descobrir IDs via /transitions antes de mover.
## 5. Boards & Columns — /rest/agile/1.0/board/{id}/configuration para
   mapear coluna -> status.
## 6. Sprints — list, issues, add, remove, create/start/close.
## 7. Comments — body em ADF.
## 8. Issue Links — types via /issueLinkType, criar via /issueLink.
## 9. Watchers, Votes, Worklog.
## 10. Attachments — multipart com -F + X-Atlassian-Token: no-check.
## 11. Labels, Components, Versions.
## 12. Bulk operations.
## 13. ADF (Atlassian Document Format) cheatsheet.
## 14. Custom field discovery: GET /rest/api/3/field | jq custom=true.
## 15. Error handling: 401, 403, 404, 400, 429.

## UX rules
- Comunicar em PT-BR.
- Mostrar issue keys como texto (SOL-42) com link para
  https://hxlab-hagens.atlassian.net/browse/SOL-42
- Agrupar listas por status ou sprint em tabela compacta.
- Confirmar antes de operações destrutivas (delete, close sprint,
  bulk transition > 5 issues).
- Descobrir transition IDs dinamicamente — nunca hard-code.
- "sprint atual" -> state=active no board 680.

Depois, distribua a skill para todos os diretórios usando a meta-skill
`criar-skill-global` (se já estiver instalada).

Por que cada usuário tem o próprio token? Tokens pessoais permitem rastrear ações no Jira por autor, podem ser revogados sem afetar outros, e respeitam permissões individuais por projeto. Compartilhar token mascara autoria, dá acesso indevido a quem não deveria, e expõe o owner do token a auditoria por algo que não fez.

Final

Como saber que ficou bom.

Cinco sinais de que o setup funcionou:

A partir daqui, o vault cresce sozinho. Cada decisão técnica vai pra decisions.md. Cada task vira 4 arquivos. Cada sessão adiciona um bloco em PROGRESSO.md. Em uma semana, qualquer agente abrindo seu vault sabe mais sobre seus projetos do que você lembra.