npm - adi_dev_workflow - Versions diffs - 1.0.0 → 1.1.0 - Mend

adi_dev_workflow 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (130) hide show

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

@@ -1,588 +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
+---
+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