adi_dev_workflow 1.0.0

package/frameworks/commands/sync-tasks-to-linear.md

@@ -0,0 +1,588 @@
+---
+description: Sincroniza tasks dos frameworks (miniStack, SDD, TaskCard) com Linear (bidirecional)
+argument-hint: [caminho-das-tasks] [projeto-linear] [team-linear]
+---
+
+Você é um **Sincronizador de Tasks** especializado em sincronização bidirecional entre os frameworks miniStack, SDD e TaskCard e o Linear.
+
+Sua missão é **analisar arquivos de tasks**, **criar issues estruturadas no Linear** e **atualizar os arquivos locais** com os IDs do Linear para permitir rastreamento de status pelos comandos de execução.
+
+---
+
+## Argumentos
+
+O `$ARGUMENTS` deve conter:
+
+1. **Caminho das tasks** (obrigatório) - Caminho do arquivo ou pasta contendo as tasks
+2. **Projeto no Linear** (obrigatório) - Nome ou ID do projeto no Linear
+3. **Team no Linear** (obrigatório) - Nome ou ID do time no Linear
+
+**Formatos aceitos:**
+- `docs/minha-feature/v1 MeuProjeto Backend` - Pasta miniStack com projeto e team
+- `docs/minha-feature/v1/task_plan.md MeuProjeto Backend` - Arquivo específico SDD
+- `docs/minha-feature/v1/taskcard-001.md MeuProjeto Backend` - TaskCard individual
+
+---
+
+## Fluxo de Execução
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  FASE 1: DETECÇÃO E LEITURA                                 │
+│  - Detectar tipo de framework (miniStack/SDD/TaskCard)      │
+│  - Ler arquivos de tasks                                    │
+│  - Extrair metadados da feature                             │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│  FASE 2: PARSING DAS TASKS                                  │
+│  - Extrair lista de tasks com todos os campos               │
+│  - Mapear dependências entre tasks                          │
+│  - Identificar tasks paralelas vs sequenciais               │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│  FASE 3: VALIDAÇÃO COM USUÁRIO                              │
+│  - Exibir resumo das tasks encontradas                      │
+│  - Confirmar projeto e team no Linear                       │
+│  - Solicitar aprovação antes de criar                       │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│  FASE 4: CRIAÇÃO NO LINEAR                                  │
+│  - Obter status disponíveis do time                         │
+│  - Criar issue principal da feature (pai)                   │
+│  - Criar issues das tasks (subtasks)                        │
+│  - Configurar dependências (blockedBy)                      │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│  FASE 5: ATUALIZAÇÃO DOS ARQUIVOS LOCAIS                    │
+│  - Adicionar metadados Linear nas tasks                     │
+│  - Registrar IDs, URLs e status de cada issue               │
+│  - Criar arquivo linear-sync.json para rastreamento         │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│  FASE 6: RELATÓRIO FINAL                                    │
+│  - Exibir todas as issues criadas                           │
+│  - Mostrar hierarquia e dependências                        │
+│  - Fornecer links para o Linear                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Fase 1: Detecção e Leitura
+
+### 1.1 Detectar Tipo de Framework
+
+Analise o caminho fornecido para identificar o framework:
+
+| Framework | Arquivos Esperados |
+|-----------|-------------------|
+| **miniStack** | `intent.md` + `scope.md` + `tasks.md` |
+| **SDD** | `task_plan.md` + `task-XX-*.md` individuais |
+| **TaskCard** | `taskcard-*.md` ou arquivo único com seção "Guardrails" |
+
+### 1.2 Leitura dos Arquivos
+
+**Para miniStack:**
+```
+- Ler intent.md → Extrair nome, objetivo, contexto
+- Ler scope.md → Extrair escopo incluído/excluído
+- Ler tasks.md → Extrair lista de tasks
+```
+
+**Para SDD:**
+```
+- Ler task_plan.md → Extrair metadados e tabela de tasks
+- Ler cada task-XX-*.md → Extrair detalhes individuais
+```
+
+**Para TaskCard:**
+```
+- Ler taskcard-*.md → Extrair task individual completa
+```
+
+---
+
+## Fase 2: Parsing das Tasks
+
+### 2.1 Estrutura de Task Normalizada
+
+Independente do framework, normalize cada task para:
+
+```
+{
+  id: "T1" | "TASK-001" | ID original,
+  titulo: "Nome da task",
+  objetivo: "O que será entregue",
+  descricao: "Descrição detalhada de como fazer",
+  arquivos: ["lista", "de", "arquivos"],
+  dependencias: ["T0"] | [] se nenhuma,
+  criterios_aceite: ["critério 1", "critério 2"],
+  fase: "Fase 1" | null,
+  guardrails: { // apenas TaskCard
+    deve: ["item 1"],
+    nao_deve: ["item 1"]
+  }
+}
+```
+
+### 2.2 Mapeamento de Dependências
+
+Construa o grafo de dependências:
+```
+T1 → sem dependências (pode rodar primeiro)
+T2 → depende de T1
+T3 → depende de T1
+T4 → depende de T2, T3 (aguarda ambas)
+```
+
+### 2.3 Extração de Metadados da Feature
+
+```
+{
+  nome: "Nome da Feature",
+  objetivo: "Objetivo geral",
+  escopo_incluido: ["item 1", "item 2"],
+  escopo_excluido: ["item A", "item B"],
+  framework: "miniStack" | "SDD" | "TaskCard"
+}
+```
+
+---
+
+## Fase 3: Validação com Usuário
+
+### 3.1 Exibir Resumo
+
+```
+═══════════════════════════════════════════════════════════════
+📋 TASKS DETECTADAS PARA SINCRONIZAÇÃO
+═══════════════════════════════════════════════════════════════
+
+📁 Origem: docs/auth-feature/v1/
+🔧 Framework: miniStack
+📦 Projeto Linear: MeuProjeto
+👥 Team Linear: Backend
+
+🚀 FEATURE: Autenticação de Usuários
+───────────────────────────────────────────────────────────────
+
+📋 TASKS ENCONTRADAS (5)
+
+| ID | Título | Dependências | Paralelo? |
+|----|--------|--------------|-----------|
+| T1 | Criar estrutura base | - | ✅ Sim |
+| T2 | Implementar login | T1 | ❌ Não |
+| T3 | Implementar registro | T1 | ❌ Não |
+| T4 | Criar middleware auth | T2 | ❌ Não |
+| T5 | Criar testes | T2, T3, T4 | ❌ Não |
+
+📊 ORDEM DE EXECUÇÃO
+───────────────────────────────────────────────────────────────
+Rodada 1: T1
+Rodada 2: T2, T3 (paralelo)
+Rodada 3: T4
+Rodada 4: T5
+
+═══════════════════════════════════════════════════════════════
+```
+
+### 3.2 Solicitar Confirmação
+
+> "✅ Encontradas **5 tasks** para sincronizar com o Linear.
+>
+> **Projeto:** MeuProjeto
+> **Team:** Backend
+>
+> Deseja criar as issues no Linear? (sim/não)"
+
+**Se o usuário negar**, encerrar sem criar nada.
+
+---
+
+## Fase 4: Criação no Linear
+
+### 4.1 Preparação
+
+1. Use `mcp__linear-server__list_issue_statuses` para obter status válidos do time
+2. Use `mcp__linear-server__get_project` para validar o projeto
+3. Identifique status equivalentes: Todo, In Progress, Done, Blocked
+
+### 4.2 Criar Issue Principal da Feature
+
+**PRIMEIRO**, crie uma issue pai que representa toda a feature:
+
+```
+title: "🚀 [FEATURE] {nome-da-feature}"
+description: |
+  ## Feature: {nome-da-feature}
+
+  **Framework:** {miniStack | SDD | TaskCard}
+  **Origem:** {caminho-do-arquivo}
+
+  ### Objetivo
+  {objetivo da feature}
+
+  ### Escopo
+  **Dentro:**
+  {lista do que está incluído}
+
+  **Fora:**
+  {lista do que está excluído}
+
+  ## Tasks Incluídas
+  - [ ] T1: {titulo}
+  - [ ] T2: {titulo}
+  - [ ] T3: {titulo}
+  ...
+
+  ## Grafo de Dependências
+  {representação visual do grafo}
+
+  ---
+  *Sincronizado automaticamente via /sync-tasks-to-linear*
+
+project: [projeto especificado]
+team: [time especificado]
+state: "Todo" ou "Backlog"
+```
+
+**Guarde o ID desta issue** - será o `parentId` de todas as Tasks.
+
+### 4.3 Criar Issues das Tasks
+
+Para **CADA Task** encontrada:
+
+```
+title: "[{ID}] {titulo}"
+description: |
+  ## Objetivo
+  {objetivo da task}
+
+  ## Descrição
+  {descrição detalhada de como fazer}
+
+  ## Dependências
+  {lista de dependências ou "Nenhuma"}
+
+  ## Arquivos Impactados
+  {lista de arquivos}
+
+  ## Critérios de Aceite
+  - [ ] {critério 1}
+  - [ ] {critério 2}
+
+  {Se TaskCard, incluir seção de Guardrails:}
+  ## Guardrails
+  ### DEVE
+  - ✅ {item}
+
+  ### NÃO DEVE
+  - ❌ {item}
+
+  ---
+  *Task ID: {id-original}*
+  *Framework: {framework}*
+
+project: [projeto especificado]
+team: [time especificado]
+state: "Todo"
+parentId: [ID da issue da feature]
+```
+
+### 4.4 Configurar Dependências
+
+Para tasks com dependências, configure `blockedBy`:
+
+```
+T2 depende de T1 → blockedBy: [issue_id_T1]
+T4 depende de T2, T3 → blockedBy: [issue_id_T2, issue_id_T3]
+```
+
+---
+
+## Fase 5: Atualização dos Arquivos Locais
+
+Após criar as issues no Linear, **ATUALIZE os arquivos de tasks locais** para permitir rastreamento bidirecional.
+
+### 5.1 Criar Arquivo de Sincronização
+
+Crie/atualize o arquivo `linear-sync.json` na pasta da feature:
+
+```json
+{
+  "synced_at": "2024-01-15T10:30:00Z",
+  "project": "MeuProjeto",
+  "team": "Backend",
+  "feature_issue": {
+    "id": "abc123-uuid",
+    "identifier": "PROJ-100",
+    "url": "https://linear.app/workspace/issue/PROJ-100"
+  },
+  "tasks": {
+    "T1": {
+      "linear_id": "def456-uuid",
+      "identifier": "PROJ-101",
+      "url": "https://linear.app/workspace/issue/PROJ-101",
+      "status": "Todo"
+    },
+    "T2": {
+      "linear_id": "ghi789-uuid",
+      "identifier": "PROJ-102",
+      "url": "https://linear.app/workspace/issue/PROJ-102",
+      "status": "Todo"
+    }
+  }
+}
+```
+
+### 5.2 Atualização por Framework
+
+#### Para miniStack (tasks.md)
+
+Adicione uma seção `## Linear Tracking` no final do arquivo ou atualize metadados inline:
+
+**Formato com seção dedicada:**
+```markdown
+---
+
+## Linear Tracking
+
+| Task | Linear Issue | Status | URL |
+|------|--------------|--------|-----|
+| T1 | PROJ-101 | Todo | [Link](https://linear.app/...) |
+| T2 | PROJ-102 | Todo | [Link](https://linear.app/...) |
+
+*Última sincronização: 2024-01-15 10:30*
+```
+
+**Formato inline (atualizar cada task):**
+```markdown
+### T1 - Criar estrutura base
+- **Linear:** PROJ-101 | Todo
+- **Objetivo:** ...
+```
+
+#### Para SDD (task_plan.md + task-XX-*.md)
+
+**No task_plan.md**, adicione coluna Linear na tabela:
+
+```markdown
+| ID | Título | Dependências | Linear | Status |
+|----|--------|--------------|--------|--------|
+| TASK-01 | Criar estrutura | - | PROJ-101 | Todo |
+| TASK-02 | Implementar login | TASK-01 | PROJ-102 | Todo |
+```
+
+**Em cada task-XX-*.md**, adicione frontmatter ou seção:
+
+```markdown
+---
+linear_issue: PROJ-101
+linear_status: Todo
+linear_url: https://linear.app/workspace/issue/PROJ-101
+synced_at: 2024-01-15T10:30:00Z
+---
+
+# TASK-01: Criar estrutura base
+...
+```
+
+#### Para TaskCard (taskcard-*.md)
+
+Adicione seção de tracking no final:
+
+```markdown
+---
+
+## 🔗 Linear Integration
+
+- **Issue:** PROJ-101
+- **Status:** Todo
+- **URL:** https://linear.app/workspace/issue/PROJ-101
+- **Sincronizado em:** 2024-01-15 10:30
+```
+
+### 5.3 Mapeamento de Status
+
+Ao atualizar arquivos locais, use o mapeamento de status:
+
+| Linear Status | Status Local |
+|---------------|--------------|
+| Backlog | `pending` |
+| Todo | `pending` |
+| In Progress | `in_progress` |
+| In Review | `in_progress` |
+| Done | `completed` |
+| Canceled | `canceled` |
+
+---
+
+## Fase 6: Relatório Final
+
+```
+═══════════════════════════════════════════════════════════════
+✅ SINCRONIZAÇÃO CONCLUÍDA
+═══════════════════════════════════════════════════════════════
+
+📁 Origem: docs/auth-feature/v1/
+🔧 Framework: miniStack
+📦 Projeto: MeuProjeto
+👥 Team: Backend
+
+🚀 FEATURE PRINCIPAL
+───────────────────────────────────────────────────────────────
+Issue: PROJ-100
+Título: 🚀 [FEATURE] Autenticação de Usuários
+Link: https://linear.app/workspace/issue/PROJ-100
+
+📋 TASKS CRIADAS (5)
+───────────────────────────────────────────────────────────────
+
+| ID | Título | Issue Linear | Dependências |
+|----|--------|--------------|--------------|
+| T1 | Criar estrutura base | PROJ-101 | - |
+| T2 | Implementar login | PROJ-102 | PROJ-101 |
+| T3 | Implementar registro | PROJ-103 | PROJ-101 |
+| T4 | Criar middleware auth | PROJ-104 | PROJ-102 |
+| T5 | Criar testes | PROJ-105 | PROJ-102, PROJ-103, PROJ-104 |
+
+📊 HIERARQUIA NO LINEAR
+───────────────────────────────────────────────────────────────
+🚀 [FEATURE] Autenticação de Usuários (PROJ-100)
+├── [T1] Criar estrutura base (PROJ-101)
+├── [T2] Implementar login (PROJ-102) → blockedBy: PROJ-101
+├── [T3] Implementar registro (PROJ-103) → blockedBy: PROJ-101
+├── [T4] Criar middleware auth (PROJ-104) → blockedBy: PROJ-102
+└── [T5] Criar testes (PROJ-105) → blockedBy: PROJ-102, PROJ-103, PROJ-104
+
+📈 ESTATÍSTICAS
+───────────────────────────────────────────────────────────────
+Total de Issues: 6 (1 feature + 5 tasks)
+Tasks Paralelas na Rodada 1: 1 (T1)
+Tasks com Dependências: 4
+
+📁 ARQUIVOS ATUALIZADOS
+───────────────────────────────────────────────────────────────
+✅ docs/auth-feature/v1/linear-sync.json (criado)
+✅ docs/auth-feature/v1/tasks.md (atualizado com Linear Tracking)
+
+💡 PRÓXIMOS PASSOS
+───────────────────────────────────────────────────────────────
+- Use `/run-ministack-withlinear` para executar tasks com sync automático
+- O arquivo `linear-sync.json` será usado para rastrear status
+- Atualizações no Linear serão refletidas nos arquivos locais
+
+═══════════════════════════════════════════════════════════════
+```
+
+---
+
+## Comandos Linear MCP Utilizados
+
+| Comando | Uso |
+|---------|-----|
+| `mcp__linear-server__list_teams` | Descobrir times disponíveis |
+| `mcp__linear-server__get_team` | Validar time especificado |
+| `mcp__linear-server__list_projects` | Listar projetos disponíveis |
+| `mcp__linear-server__get_project` | Validar projeto especificado |
+| `mcp__linear-server__list_issue_statuses` | Obter status válidos do time |
+| `mcp__linear-server__create_issue` | Criar issue da feature e tasks |
+| `mcp__linear-server__update_issue` | Configurar dependências blockedBy |
+
+---
+
+## Tratamento de Erros
+
+### Projeto não encontrado
+```
+❌ ERRO: Projeto "MeuProjeto" não encontrado no Linear.
+
+Projetos disponíveis:
+- Projeto A
+- Projeto B
+- Projeto C
+
+Por favor, especifique um projeto válido.
+```
+
+### Team não encontrado
+```
+❌ ERRO: Team "Backend" não encontrado no Linear.
+
+Teams disponíveis:
+- Engineering
+- Design
+- Product
+
+Por favor, especifique um team válido.
+```
+
+### Arquivo de tasks não encontrado
+```
+❌ ERRO: Não foi possível detectar tasks no caminho especificado.
+
+Esperado um dos seguintes:
+- tasks.md (miniStack)
+- task_plan.md (SDD)
+- taskcard-*.md (TaskCard)
+
+Verifique o caminho: docs/minha-feature/v1/
+```
+
+### Nenhuma task encontrada
+```
+❌ ERRO: Nenhuma task encontrada para sincronizar.
+
+O arquivo tasks.md existe, mas não contém tasks no formato esperado.
+Verifique se o arquivo segue o template do framework.
+```
+
+---
+
+## Regras Obrigatórias
+
+- ✅ **SEMPRE validar** projeto e team antes de criar issues
+- ✅ **SEMPRE exibir resumo** e pedir confirmação antes de criar
+- ✅ **SEMPRE criar issue da feature PRIMEIRO** como pai
+- ✅ **SEMPRE preservar** todos os detalhes das tasks originais
+- ✅ **SEMPRE configurar** dependências blockedBy corretamente
+- ✅ **SEMPRE atualizar** os arquivos locais com IDs do Linear após criar issues
+- ✅ **SEMPRE criar** arquivo `linear-sync.json` para rastreamento
+- ❌ **NUNCA criar issues** sem confirmação do usuário
+- ❌ **NUNCA ignorar** dependências entre tasks
+- ❌ **NUNCA sobrescrever** conteúdo original das tasks (apenas adicionar metadados Linear)
+
+---
+
+## Exemplos de Uso
+
+### miniStack
+```
+/sync-tasks-to-linear docs/auth-feature/v1 MeuProjeto Backend
+```
+
+### SDD
+```
+/sync-tasks-to-linear docs/checkout/v1/task_plan.md EcommerceProjeto Engineering
+```
+
+### TaskCard Individual
+```
+/sync-tasks-to-linear docs/bugfix/v1/taskcard-hotfix-001.md Manutenção Backend
+```
+
+### Múltiplos TaskCards
+```
+/sync-tasks-to-linear docs/refactor/v1/ RefatoracaoProjeto Engineering
+```
+
+---
+
+## Entrada
+
+$ARGUMENTS

package/frameworks/commands/taskcard/generate-taskcard.md

@@ -0,0 +1,25 @@
+---
+description: Gera uma TaskCard individual clara e executável para uma task específica
+argument-hint: [contexto da tarefa ou Intent + Scope]
+---
+
+Seu papel: **Gerador de TaskCard**. Voce NAO executa — apenas gera o documento.
+
+Carregue a skill **taskcard-expert** para obter o framework completo (template, regras, guardrails, convencoes).
+Toda a inteligencia do framework esta centralizada nessa skill — siga-a integralmente.
+
+## Instrucoes
+
+1. Leia o contexto fornecido pelo usuario
+2. Identifique lacunas — faca **uma pergunta por vez** ate ter tudo
+   - **Claude Code**: use a ferramenta `AskUserQuestion` para fazer as perguntas. Ofereça opcoes concretas baseadas na analise do codebase (o usuario sempre pode escolher "Other" para texto livre)
+3. Preencha o **template oficial** (todas as 11 secoes) conforme a skill taskcard-expert
+4. Salve imediatamente em `docs/<nome-feature>/task-<numero>-<slug>.md` — **NAO peca aprovacao antes de salvar**
+5. Apresente um **resumo curto** do que foi criado (ID, nome, arquivos gerados, escopo resumido)
+6. Se trabalho for grande, quebre em multiplas (gere apenas a primeira)
+7. Se multiplas TaskCards, pergunte se quer gerar a proxima
+8. Ao final de todas, ofereca criar `task-plan.md` com ordem e dependencias
+
+## Entrada
+
+$ARGUMENTS

package/frameworks/commands/taskcard/generate-tests.md

@@ -0,0 +1,37 @@
+---
+description: Gera/enriquece a secao 10 (Testes) de uma TaskCard com rigor de QA Senior / SDET
+argument-hint: [caminho da TaskCard individual — ex: docs/feature/v1/task-01-slug.md]
+---
+
+Use a skill **taskcard-qa-expert** para gerar/enriquecer a secao 10 (Testes) da TaskCard.
+
+## Contexto
+
+Voce deve atuar como um **QA Engineer Senior / SDET** e seguir todo o processo definido na skill taskcard-qa-expert para gerar testes com qualidade profissional.
+
+## Modo de Uso
+
+```
+/taskcard:generate-tests docs/nome-feature/v1/task-01-slug.md
+```
+
+Gera a secao 10 completa da TaskCard (10.1 a 10.6):
+- 10.1 Testes Existentes a Modificar
+- 10.2 Testes a Criar (unitarios, integracao, e2e)
+- 10.3 Cenarios Obrigatorios
+- 10.4 Padroes de Teste
+- 10.5 Cenarios de Erro
+- 10.6 Rastreabilidade: Aceite Tecnico -> Testes
+
+## Regras Adicionais
+
+- **Claude Code**: use a ferramenta `AskUserQuestion` para esclarecer duvidas com o usuario
+- **NUNCA** gere testes genericos — cada teste deve ter cenario especifico e verificavel
+- **SEMPRE** pesquise padroes de teste existentes no projeto antes de gerar
+- **SEMPRE** mapeie criterios de Aceite Tecnico (secao 9) para testes (secao 10.6)
+- **SEMPRE** considere cenarios de erro, boundary values e edge cases
+- Todo fluxo de sucesso deve ter **pelo menos 2 cenarios de falha** correspondentes
+
+## Entrada
+
+$ARGUMENTS

package/frameworks/commands/taskcard/run-taskcard.md

@@ -0,0 +1,34 @@
+---
+description: Executa uma TaskCard aprovada com precisão seguindo guardrails definidos
+argument-hint: [caminho da taskcard] [agente opcional ex: go-backend-implementer]
+---
+
+Seu papel: **Executor de TaskCard**. Execute com precisao, sem desvios ou reinterpretacao.
+
+Carregue a skill **taskcard-expert** para obter o framework completo (template, regras, guardrails, convencoes).
+Toda a inteligencia do framework esta centralizada nessa skill — siga-a integralmente.
+
+## Argumentos
+
+- `$0` — Caminho da TaskCard (obrigatorio)
+- `$1` — Agente executor opcional (subagent_type para ferramenta Task)
+
+Agentes disponiveis em `.claude/agents/`.
+
+## Instrucoes
+
+1. Leia a TaskCard completa no caminho `$0`
+2. Leia os arquivos da secao 8.1 (existentes/referencia) para contexto
+3. Valide secoes 3-9 preenchidas e dependencias satisfeitas
+4. Execute os **Passos Sugeridos** (secao 7) na ordem
+5. A cada passo, valide guardrails DEVE e NAO DEVE (secao 6)
+6. Se guardrail for violado ou algo conflitar: **PARE e avise**
+   - **Claude Code**: use a ferramenta `AskUserQuestion` para apresentar o bloqueio e opcoes de resolucao ao usuario
+7. Valide aceite tecnico (secao 9) ao final
+8. Produza relatorio de execucao no formato padrao da skill
+
+Se agente `$1` for especificado, delegue a execucao via ferramenta Task com `subagent_type: $1`.
+
+## Entrada
+
+$ARGUMENTS