@luanpdd/kit-mcp 0.2.0 → 0.3.0

package/kit/framework/templates/context.md

@@ -0,0 +1,352 @@
+# Template de Contexto de Fase
+
+Template para `.planning/phases/XX-name/{phase_num}-CONTEXT.md` - captura decisões de implementação para uma fase.
+
+**Propósito:** Documentar decisões que agentes downstream precisam. O Pesquisador usa isso para saber O QUE investigar. O Planejador usa isso para saber quais escolhas estão travadas vs. flexíveis.
+
+**Princípio chave:** As categorias NÃO são predefinidas. Elas emergem do que foi realmente discutido para ESTA fase. Uma fase CLI tem seções relevantes para CLI, uma fase de UI tem seções relevantes para UI.
+
+**Consumidores downstream:**
+- `phase-researcher` — Lê decisões para focar a pesquisa (ex.: "layout de card" → pesquisar padrões de componentes card)
+- `planner` — Lê decisões para criar tarefas específicas (ex.: "scroll infinito" → tarefa inclui virtualização)
+
+---
+
+## Template do Arquivo
+
+```markdown
+# Fase [X]: [Nome] - Contexto
+
+**Coletado:** [data]
+**Status:** Pronto para planejamento
+
+<domain>
+## Limite da Fase
+
+[Declaração clara do que esta fase entrega — a âncora de escopo. Vem do ROADMAP.md e é fixo. A discussão esclarece a implementação dentro deste limite.]
+
+</domain>
+
+<decisions>
+## Decisões de Implementação
+
+### [Área 1 que foi discutida]
+- **D-01:** [Decisão específica tomada]
+- **D-02:** [Outra decisão, se aplicável]
+
+### [Área 2 que foi discutida]
+- **D-03:** [Decisão específica tomada]
+
+### [Área 3 que foi discutida]
+- **D-04:** [Decisão específica tomada]
+
+### A Critério do Claude
+[Áreas onde o usuário disse explicitamente "você decide" — Claude tem flexibilidade aqui durante o planejamento/implementação]
+
+</decisions>
+
+<specifics>
+## Ideias Específicas
+
+[Quaisquer referências, exemplos ou momentos "quero como X" da discussão. Referências de produto, comportamentos específicos, padrões de interação.]
+
+[Se nenhum: "Sem requisitos específicos — aberto a abordagens padrão"]
+
+</specifics>
+
+<canonical_refs>
+## Referências Canônicas
+
+**Agentes downstream DEVEM ler isso antes de planejar ou implementar.**
+
+[Liste toda especificação, ADR, doc de funcionalidade ou design doc que define requisitos ou restrições para esta fase. Use caminhos relativos completos para que agentes possam lê-los diretamente. Agrupe por área de tópico quando a fase tem múltiplas preocupações.]
+
+### [Área de tópico 1]
+- `path/to/spec-or-adr.md` — [O que este doc decide/define que é relevante]
+- `path/to/doc.md` §N — [Seção específica e o que ela cobre]
+
+### [Área de tópico 2]
+- `path/to/feature-doc.md` — [Que capacidade isto define]
+
+[Se o projeto não tem specs externas: "Sem specs externas — requisitos estão totalmente capturados nas decisões acima"]
+
+</canonical_refs>
+
+<code_context>
+## Insights do Código Existente
+
+### Ativos Reutilizáveis
+- [Componente/hook/utilitário]: [Como poderia ser usado nesta fase]
+
+### Padrões Estabelecidos
+- [Padrão]: [Como restringe/habilita esta fase]
+
+### Pontos de Integração
+- [Onde o novo código se conecta ao sistema existente]
+
+</code_context>
+
+<deferred>
+## Ideias Diferidas
+
+[Ideias que surgiram durante a discussão mas pertencem a outras fases. Capturadas aqui para não serem perdidas, mas explicitamente fora do escopo desta fase.]
+
+[Se nenhuma: "Nenhuma — a discussão ficou dentro do escopo da fase"]
+
+</deferred>
+
+---
+
+*Fase: XX-nome*
+*Contexto coletado: [data]*
+```
+
+<good_examples>
+
+**Example 1: Visual feature (Post Feed)**
+
+```markdown
+# Phase 3: Post Feed - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Display posts from followed users in a scrollable feed. Users can view posts and see engagement counts. Creating posts and interactions are separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Layout style
+- Card-based layout, not timeline or list
+- Each card shows: author avatar, name, timestamp, full post content, reaction counts
+- Cards have subtle shadows, rounded corners — modern feel
+
+### Loading behavior
+- Infinite scroll, not pagination
+- Pull-to-refresh on mobile
+- New posts indicator at top ("3 new posts") rather than auto-inserting
+
+### Empty state
+- Friendly illustration + "Follow people to see posts here"
+- Suggest 3-5 accounts to follow based on interests
+
+### Claude's Discretion
+- Loading skeleton design
+- Exact spacing and typography
+- Error state handling
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+### Feed display
+- `docs/features/social-feed.md` — Feed requirements, post card fields, engagement display rules
+- `docs/decisions/adr-012-infinite-scroll.md` — Scroll strategy decision, virtualization requirements
+
+### Empty states
+- `docs/design/empty-states.md` — Empty state patterns, illustration guidelines
+
+</canonical_refs>
+
+<specifics>
+## Specific Ideas
+
+- "I like how Twitter shows the new posts indicator without disrupting your scroll position"
+- Cards should feel like Linear's issue cards — clean, not cluttered
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Commenting on posts — Phase 5
+- Bookmarking posts — add to backlog
+
+</deferred>
+
+---
+
+*Phase: 03-post-feed*
+*Context gathered: 2025-01-20*
+```
+
+**Example 2: CLI tool (Database backup)**
+
+```markdown
+# Phase 2: Backup Command - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+CLI command to backup database to local file or S3. Supports full and incremental backups. Restore command is a separate phase.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Output format
+- JSON for programmatic use, table format for humans
+- Default to table, --json flag for JSON
+- Verbose mode (-v) shows progress, silent by default
+
+### Flag design
+- Short flags for common options: -o (output), -v (verbose), -f (force)
+- Long flags for clarity: --incremental, --compress, --encrypt
+- Required: database connection string (positional or --db)
+
+### Error recovery
+- Retry 3 times on network failure, then fail with clear message
+- --no-retry flag to fail fast
+- Partial backups are deleted on failure (no corrupt files)
+
+### Claude's Discretion
+- Exact progress bar implementation
+- Compression algorithm choice
+- Temp file handling
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+### Backup CLI
+- `docs/features/backup-restore.md` — Backup requirements, supported backends, encryption spec
+- `docs/decisions/adr-007-cli-conventions.md` — Flag naming, exit codes, output format standards
+
+</canonical_refs>
+
+<specifics>
+## Specific Ideas
+
+- "I want it to feel like pg_dump — familiar to database people"
+- Should work in CI pipelines (exit codes, no interactive prompts)
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Scheduled backups — separate phase
+- Backup rotation/retention — add to backlog
+
+</deferred>
+
+---
+
+*Phase: 02-backup-command*
+*Context gathered: 2025-01-20*
+```
+
+**Example 3: Organization task (Photo library)**
+
+```markdown
+# Phase 1: Photo Organization - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Organize existing photo library into structured folders. Handle duplicates and apply consistent naming. Tagging and search are separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Grouping criteria
+- Primary grouping by year, then by month
+- Events detected by time clustering (photos within 2 hours = same event)
+- Event folders named by date + location if available
+
+### Duplicate handling
+- Keep highest resolution version
+- Move duplicates to _duplicates folder (don't delete)
+- Log all duplicate decisions for review
+
+### Naming convention
+- Format: YYYY-MM-DD_HH-MM-SS_originalname.ext
+- Preserve original filename as suffix for searchability
+- Handle name collisions with incrementing suffix
+
+### Claude's Discretion
+- Exact clustering algorithm
+- How to handle photos with no EXIF data
+- Folder emoji usage
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+### Organization rules
+- `docs/features/photo-organization.md` — Grouping rules, duplicate policy, naming spec
+- `docs/decisions/adr-003-exif-handling.md` — EXIF extraction strategy, fallback for missing metadata
+
+</canonical_refs>
+
+<specifics>
+## Specific Ideas
+
+- "I want to be able to find photos by roughly when they were taken"
+- Don't delete anything — worst case, move to a review folder
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Face detection grouping — future phase
+- Cloud sync — out of scope for now
+
+</deferred>
+
+---
+
+*Phase: 01-photo-organization*
+*Context gathered: 2025-01-20*
+```
+
+</good_examples>
+
+<guidelines>
+**Este template captura DECISÕES para agentes downstream.**
+
+A saída deve responder: "O que o pesquisador precisa investigar? Quais escolhas estão travadas para o planejador?"
+
+**Bom conteúdo (decisões concretas):**
+- "Layout baseado em cards, não timeline"
+- "Tentar 3 vezes em falha de rede, então falhar"
+- "Agrupar por ano, depois por mês"
+- "JSON para uso programático, tabela para humanos"
+
+**Conteúdo ruim (muito vago):**
+- "Deve parecer moderno e limpo"
+- "Boa experiência do usuário"
+- "Rápido e responsivo"
+- "Fácil de usar"
+
+**Após a criação:**
+- O arquivo fica no diretório da fase: `.planning/phases/XX-nome/{phase_num}-CONTEXT.md`
+- `phase-researcher` usa decisões para focar a investigação E lê canonical_refs para saber QUAIS docs estudar
+- `planner` usa decisões + pesquisa para criar tarefas executáveis E lê canonical_refs para verificar alinhamento
+- Agentes downstream NÃO devem precisar perguntar ao usuário novamente sobre decisões capturadas
+
+**CRÍTICO — Referências canônicas:**
+- A seção `<canonical_refs>` é OBRIGATÓRIA. Todo CONTEXT.md deve ter uma.
+- Se o seu projeto tem specs externas, ADRs ou design docs, liste-os com caminhos relativos completos agrupados por tópico
+- Se ROADMAP.md lista `Canonical refs:` por fase, extraia e expanda-os
+- Menções inline como "ver ADR-019" espalhadas nas decisões são inúteis para agentes downstream — eles precisam de caminhos completos e referências de seção em uma seção dedicada que podem encontrar
+- Se não existem specs externas, diga explicitamente — não omita silenciosamente a seção
+</guidelines>

package/kit/framework/templates/continue-here.md

@@ -0,0 +1,78 @@
+# Template Continue-Here
+
+Copie e preencha esta estrutura para `.planning/phases/XX-name/.continue-here.md`:
+
+```yaml
+---
+phase: XX-name
+task: 3
+total_tasks: 7
+status: in_progress
+last_updated: 2025-01-15T14:30:00Z
+---
+```
+
+```markdown
+<current_state>
+[Onde exatamente estamos? Qual é o contexto imediato?]
+</current_state>
+
+<completed_work>
+[O que foi feito nesta sessão - seja específico]
+
+- Tarefa 1: [nome] - Concluída
+- Tarefa 2: [nome] - Concluída
+- Tarefa 3: [nome] - Em andamento, [o que foi feito nela]
+</completed_work>
+
+<remaining_work>
+[O que falta nesta fase]
+
+- Tarefa 3: [nome] - [o que falta fazer]
+- Tarefa 4: [nome] - Não iniciada
+- Tarefa 5: [nome] - Não iniciada
+</remaining_work>
+
+<decisions_made>
+[Decisões chave e por que — para que a próxima sessão não reabra o debate]
+
+- Decidiu usar [X] porque [motivo]
+- Escolheu [abordagem] em vez de [alternativa] porque [motivo]
+</decisions_made>
+
+<blockers>
+[Qualquer coisa travada ou aguardando fatores externos]
+
+- [Bloqueio 1]: [status/contorno]
+</blockers>
+
+<context>
+[Estado mental, "vibe", qualquer coisa que ajude a retomar suavemente]
+
+[O que você estava pensando? Qual era o plano?
+Este é o contexto "retomar exatamente de onde parou".]
+</context>
+
+<next_action>
+[A primeira coisa a fazer ao retomar]
+
+Começar com: [ação específica]
+</next_action>
+```
+
+<yaml_fields>
+Frontmatter YAML obrigatório:
+
+- `phase`: Nome do diretório (ex.: `02-authentication`)
+- `task`: Número da tarefa atual
+- `total_tasks`: Quantas tarefas na fase
+- `status`: `in_progress`, `blocked`, `almost_done`
+- `last_updated`: Timestamp ISO
+</yaml_fields>
+
+<guidelines>
+- Seja específico o suficiente para que uma instância fresca do Claude entenda imediatamente
+- Inclua POR QUE as decisões foram tomadas, não apenas o quê
+- O `<next_action>` deve ser acionável sem ler mais nada
+- Este arquivo é DELETADO após o retorno — não é armazenamento permanente
+</guidelines>

package/kit/framework/templates/copilot-instructions.md

@@ -0,0 +1,7 @@
+# Instruções para framework
+
+- Use a skill framework quando o usuário pedir framework ou usar um comando `framework-*`.
+- Trate `/framework-...` ou `framework-...` como invocações de comando e carregue o arquivo correspondente de `.github/skills/framework-*`.
+- Quando um comando disser para spawnar um subagente, prefira um agente customizado correspondente de `.github/agents`.
+- Não aplique workflows framework a menos que o usuário peça explicitamente.
+- Após concluir qualquer comando `framework-*` (ou qualquer entregável que ele acione: feature, bug fix, testes, docs, etc.), SEMPRE: (1) ofereça ao usuário o próximo passo via `ask_user`; repita esse ciclo de feedback até o usuário indicar explicitamente que terminou.

package/kit/framework/templates/debug-subagent-prompt.md

@@ -0,0 +1,91 @@
+# Template de Prompt do Subagente de Debug
+
+Template para spawnar o agente debugger. O agente contém toda a expertise de debug — este template fornece apenas o contexto do problema.
+
+---
+
+## Template
+
+```markdown
+<objective>
+Investigate issue: {issue_id}
+
+**Summary:** {issue_summary}
+</objective>
+
+<symptoms>
+expected: {expected}
+actual: {actual}
+errors: {errors}
+reproduction: {reproduction}
+timeline: {timeline}
+</symptoms>
+
+<mode>
+symptoms_prefilled: {true_or_false}
+goal: {find_root_cause_only | find_and_fix}
+</mode>
+
+<debug_file>
+Create: .planning/debug/{slug}.md
+</debug_file>
+```
+
+---
+
+## Placeholders
+
+| Placeholder | Fonte | Exemplo |
+|-------------|-------|---------|
+| `{issue_id}` | Atribuído pelo orquestrador | `auth-screen-dark` |
+| `{issue_summary}` | Descrição do usuário | `Auth screen is too dark` |
+| `{expected}` | Dos sintomas | `See logo clearly` |
+| `{actual}` | Dos sintomas | `Screen is dark` |
+| `{errors}` | Dos sintomas | `None in console` |
+| `{reproduction}` | Dos sintomas | `Open /auth page` |
+| `{timeline}` | Dos sintomas | `After recent deploy` |
+| `{goal}` | Orquestrador define | `find_and_fix` |
+| `{slug}` | Gerado | `auth-screen-dark` |
+
+---
+
+## Uso
+
+**A partir de /debug:**
+```python
+Task(
+  prompt=filled_template,
+  subagent_type="debugger",
+  description="Debug {slug}"
+)
+```
+
+**A partir de diagnose-issues (UAT):**
+```python
+Task(prompt=template, subagent_type="debugger", description="Debug UAT-001")
+```
+
+---
+
+## Continuação
+
+Para checkpoints, spawnar novo agente com:
+
+```markdown
+<objective>
+Continue debugging {slug}. Evidence is in the debug file.
+</objective>
+
+<prior_state>
+Debug file: @.planning/debug/{slug}.md
+</prior_state>
+
+<checkpoint_response>
+**Type:** {checkpoint_type}
+**Response:** {user_response}
+</checkpoint_response>
+
+<mode>
+goal: {goal}
+</mode>
+```

package/kit/framework/templates/dev-preferences.md

@@ -0,0 +1,20 @@
+---
+description: Carregar preferências do desenvolvedor nesta sessão
+---
+
+# Preferências do Desenvolvedor
+
+> Gerado pelo framework em {{generated_at}} a partir de {{data_source}}.
+> Execute `/profile-user --refresh` para regenerar.
+
+## Diretivas Comportamentais
+
+Siga estas diretivas ao trabalhar com este desenvolvedor. Diretivas de maior confiança
+devem ser aplicadas diretamente. Diretivas de menor confiança devem ser tentadas
+com ressalva ("Com base no seu perfil, vou tentar X — me diga se estiver errado").
+
+{{behavioral_directives}}
+
+## Preferências de Stack
+
+{{stack_preferences}}

package/kit/framework/templates/discovery.md

@@ -0,0 +1,146 @@
+# Template de Discovery
+
+Template para `.planning/phases/XX-name/DISCOVERY.md` - pesquisa rasa para decisões de biblioteca/opção.
+
+**Propósito:** Responder perguntas "qual biblioteca/opção devemos usar" durante a discovery obrigatória no plan-phase.
+
+Para pesquisa profunda de ecossistema ("como especialistas constroem isso"), use `/research-phase` que produz RESEARCH.md.
+
+---
+
+## Template do Arquivo
+
+```markdown
+---
+phase: XX-name
+type: discovery
+topic: [discovery-topic]
+---
+
+<session_initialization>
+Before beginning discovery, verify today's date:
+!`date +%Y-%m-%d`
+
+Use this date when searching for "current" or "latest" information.
+Example: If today is 2025-11-22, search for "2025" not "2024".
+</session_initialization>
+
+<discovery_objective>
+Discover [topic] to inform [phase name] implementation.
+
+Purpose: [What decision/implementation this enables]
+Scope: [Boundaries]
+Output: DISCOVERY.md with recommendation
+</discovery_objective>
+
+<discovery_scope>
+<include>
+- [Question to answer]
+- [Area to investigate]
+- [Specific comparison if needed]
+</include>
+
+<exclude>
+- [Out of scope for this discovery]
+- [Defer to implementation phase]
+</exclude>
+</discovery_scope>
+
+<discovery_protocol>
+
+**Source Priority:**
+1. **Context7 MCP** - For library/framework documentation (current, authoritative)
+2. **Official Docs** - For platform-specific or non-indexed libraries
+3. **WebSearch** - For comparisons, trends, community patterns (verify all findings)
+
+**Quality Checklist:**
+Before completing discovery, verify:
+- [ ] All claims have authoritative sources (Context7 or official docs)
+- [ ] Negative claims ("X is not possible") verified with official documentation
+- [ ] API syntax/configuration from Context7 or official docs (never WebSearch alone)
+- [ ] WebSearch findings cross-checked with authoritative sources
+- [ ] Recent updates/changelogs checked for breaking changes
+- [ ] Alternative approaches considered (not just first solution found)
+
+**Confidence Levels:**
+- HIGH: Context7 or official docs confirm
+- MEDIUM: WebSearch + Context7/official docs confirm
+- LOW: WebSearch only or training knowledge only (mark for validation)
+
+</discovery_protocol>
+
+
+<output_structure>
+Create `.planning/phases/XX-name/DISCOVERY.md`:
+
+```markdown
+# Descoberta: [Tópico]
+
+## Resumo
+[Resumo executivo de 2-3 parágrafos — o que foi pesquisado, o que foi encontrado, o que é recomendado]
+
+## Recomendação Principal
+[O que fazer e por quê — seja específico e acionável]
+
+## Alternativas Consideradas
+[O que mais foi avaliado e por que não foi escolhido]
+
+## Descobertas Chave
+
+### [Categoria 1]
+- [Descoberta com URL de fonte e relevância para nosso caso]
+
+### [Categoria 2]
+- [Descoberta com URL de fonte e relevância]
+
+## Exemplos de Código
+[Padrões de implementação relevantes, se aplicável]
+
+## Metadados
+
+<metadata>
+<confidence level="high|medium|low">
+[Por que este nível de confiança — baseado na qualidade das fontes e verificação]
+</confidence>
+
+<sources>
+- [Fontes autoritativas primárias usadas]
+</sources>
+
+<open_questions>
+[O que não pôde ser determinado ou precisa de validação durante a implementação]
+</open_questions>
+
+<validation_checkpoints>
+[Se a confiança for LOW ou MEDIUM, liste coisas específicas a verificar durante a implementação]
+</validation_checkpoints>
+</metadata>
+```
+</output_structure>
+
+<success_criteria>
+- All scope questions answered with authoritative sources
+- Quality checklist items completed
+- Clear primary recommendation
+- Low-confidence findings marked with validation checkpoints
+- Ready to inform PLAN.md creation
+</success_criteria>
+
+<guidelines>
+**Quando usar discovery:**
+- Escolha de tecnologia incerta (biblioteca A vs B)
+- Melhores práticas necessárias para integração desconhecida
+- Investigação de API/biblioteca necessária
+- Decisão única pendente
+
+**Quando NÃO usar:**
+- Padrões estabelecidos (CRUD, auth com biblioteca conhecida)
+- Detalhes de implementação (diferir para execução)
+- Perguntas respondíveis a partir do contexto existente do projeto
+
+**Quando usar RESEARCH.md em vez disso:**
+- Domínios niche/complexos (3D, jogos, áudio, shaders)
+- Necessidade de conhecimento de ecossistema, não apenas escolha de biblioteca
+- Perguntas "como especialistas constroem isso"
+- Use `/research-phase` para esses casos
+</guidelines>