ealmeida/claude-plugins
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(gestao): adiciona plugin gestao (agents, skills, knowledge e metadados do projeto)

Browse Source
This commit is contained in:
ealmeida
2026-10-28 16:08:53 +00:00
parent 7b2162ff29
commit de2d6f2fb5
91 changed files with 13525 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
gestao/skills/spec-coauthor/SKILL.md
+182
View File
@@ -0,0 +1,182 @@
---
name: spec-coauthor
description: Co-autoria iterativa de documentos estruturados — SPECs de projecto, propostas comerciais e PROCs operacionais. Workflow 3 fases com brainstorming, curadoria e teste de leitura por sub-agente. Usar quando "spec", "proposta", "PROC", "documento", "co-autoria", "redigir", "estruturar documento", "escrever proposta".
layer: wiki
---
# /spec-coauthor - Co-Autoria de Documentos Estruturados
Co-autoria iterativa de SPECs, propostas comerciais e PROCs operacionais com workflow de 3 fases: recolha de contexto, refinamento estruturado e teste de leitura.
---
## Tipos de Documento Suportados
| Tipo | Audiência | Exemplos |
|------|-----------|----------|
| **SPEC de projecto** | Equipa técnica, Emanuel | WhatSMS-v2-SPEC.md, DashDescomplicar-SPEC.md |
| **Proposta comercial** | Cliente, stakeholders | Proposta-ClienteX-SEO.md, Proposta-ERP-2026.md |
| **PROC operacional** | Equipa interna, ops | PROC-Deploy-EasyPanel.md, PROC-Onboarding-Cliente.md |
---
## Fase 1: Recolha de Contexto
### 1.1 Identificar tipo de documento
Perguntar ao utilizador:
```
1. Que tipo de documento precisas criar?
a) SPEC de projecto (requisitos, arquitectura, milestones)
b) Proposta comercial (solução, pricing, timeline)
c) PROC operacional (passos, checklist, troubleshooting)
d) Outro (descrever)
2. Para quem é este documento?
- Emanuel (uso interno / decisão)
- Cliente (venda / aprovação)
- Equipa técnica (execução)
- Múltiplas audiências (especificar)
3. Qual o impacto esperado?
- Aprovar orçamento / go-ahead
- Alinhar equipa em requisitos
- Documentar processo para replicar
- Outro (especificar)
```
### 1.2 Recolher contexto existente
Após identificar tipo e audiência, recolher contexto via:
**Desk CRM:**
```
mcp__desk-crm-v3__get_projects → projectos activos relacionados
mcp__desk-crm-v3__get_tasks → tarefas e sub-tarefas relevantes
mcp__desk-crm-v3__get_customers → dados do cliente (se proposta)
```
**Hub / Ficheiros:**
```
Read ficheiros relevantes em:
/media/ealmeida/Dados/Hub/05-Projectos/[projecto]/
/media/ealmeida/Dados/Hub/07-Clientes/[cliente]/
/media/ealmeida/Dados/Hub/90-Templates/
```
**Perguntas complementares de contexto:**
```
4. Existe documentação anterior? (SPEC, proposta, email, notas)
→ Partilhar caminho ou colar conteúdo
5. Há restrições ou requisitos não-negociáveis?
→ Prazo, orçamento, tecnologia obrigatória
6. Qual o nível de detalhe desejado?
→ Resumo executivo (1-2 pág.) / Documento completo (5-15 pág.) / Ultra-detalhado
```
### 1.3 Confirmar antes de avançar
Apresentar resumo do contexto recolhido e confirmar com utilizador antes de passar à Fase 2.
```
**Contexto confirmado:**
- Tipo: [SPEC / Proposta / PROC]
- Audiência: [quem vai ler]
- Impacto: [decisão esperada]
- Referências encontradas: [ficheiros / tarefas]
- Nível de detalhe: [resumo / completo / ultra]
Avançar para estruturação? (s/n)
```
---
## Fase 2: Refinamento e Estrutura
### 2.1 Brainstorming de secções
Para cada secção principal do documento, gerar **5 a 20 opções** de abordagem/conteúdo.
**Formato de apresentação:**
```
## Secção: [Nome da Secção]
Opções de abordagem:
1. [Opção concisa — 1 linha de descrição]
2. [Opção alternativa]
3. [Opção mais detalhada]
4. [Opção focada em audiência técnica]
5. [Opção focada em audiência não técnica]
...
→ Quais queres manter? (ex: "1,3,5" ou "todas" ou "nenhuma, tentar de novo")
```
**Regras do brainstorming:**
- Apresentar opções reais e diferenciadas (não variações mínimas)
- Indicar vantagens de cada abordagem em 1 linha
- Nunca gerar menos de 5 opções por secção
- Para SPECs técnicas: incluir sempre opção de maior e menor detalhe
- Para propostas: incluir sempre opção orientada a valor e a custo
### 2.2 Curadoria pelo utilizador
O utilizador selecciona opções com sintaxe simples:
```
"Keep 1,4,7" → manter apenas essas opções
"Todas" → aceitar todas
"Nenhuma" → tentar de novo com abordagem diferente
"1 mas mais curto" → manter com refinamento
"Combinar 2 e 5" → fusão das opções
```
### 2.3 Drafting iterativo
Após curadoria de cada secção, produzir rascunho com `str_replace_editor` ou apresentar em bloco markdown.
**Ciclo por secção:**
```
1. Brainstorm (5-20 opções)
2. Curadoria pelo utilizador
3. Draft da secção
4. Revisão inline ("mudar X para Y" / "expandir parágrafo Z")
5. Confirmar → avançar para secção seguinte
```
**Ordem de secções por tipo:**
Para SPEC de projecto:
```
1. Contexto e problema
2. Objectivo e scope
3. Requisitos funcionais
4. Requisitos técnicos / arquitectura
5. Milestones e timeline
6. Riscos e dependências
7. Definition of Done
8. Referências
```
Para proposta comercial:
```
1. Sumário executivo
2. Contexto e diagnóstico
3. Solução proposta
4. Entregáveis e timeline
5. Investimento e condições
6. Próximos passos
7. Sobre a Descomplicar
```
Para PROC operacional:
```
1. Objectivo e âmbito
2. Pré-requisitos
3. Passos detalhados
4. Checklis
gestao/skills/spec-coauthor/references/templates.md
+484
View File
@@ -0,0 +1,484 @@
# Templates spec-coauthor
Templates de referência para os três tipos de documento suportados pela skill /spec-coauthor.
---
## Template 1: SPEC de Projecto
```markdown
---
title: [Nome do Projecto] — SPEC
date: YYYY-MM-DD
type: spec
status: draft
version: 1.0
projecto_desk_id: [ID Desk CRM]
tags: [spec, projecto, tecnologia]
---
# [Nome do Projecto] — Especificação Técnica
**Versão:** 1.0 | **Data:** YYYY-MM-DD | **Status:** Draft
**Autor:** Emanuel Almeida | **Revisão:** [nome revisor]
---
## 1. Contexto e Problema
### 1.1 Contexto actual
Descrição do estado actual do sistema/processo que este projecto vai resolver ou melhorar.
### 1.2 Problema identificado
Descrição clara e específica do problema. Incluir:
- Impacto actual (tempo perdido, custo, risco)
- Frequência do problema
- Quem é afectado
### 1.3 Oportunidade
O que se torna possível ao resolver este problema.
---
## 2. Objectivo e Scope
### 2.1 Objectivo principal
Uma frase clara do que este projecto entrega.
### 2.2 Scope incluído
- [Feature ou entregável 1]
- [Feature ou entregável 2]
- [Feature ou entregável 3]
### 2.3 Scope excluído (fora de scope)
- [Item explicitamente excluído 1]
- [Item explicitamente excluído 2]
### 2.4 Critérios de sucesso
| Critério | Medição | Target |
|----------|---------|--------|
| [Critério 1] | [Como medir] | [Valor] |
| [Critério 2] | [Como medir] | [Valor] |
---
## 3. Requisitos Funcionais
### 3.1 [Módulo ou área funcional A]
| ID | Requisito | Prioridade | Notas |
|----|-----------|------------|-------|
| RF-001 | [Descrição] | Must / Should / Could | [Detalhe] |
| RF-002 | [Descrição] | Must / Should / Could | [Detalhe] |
### 3.2 [Módulo ou área funcional B]
| ID | Requisito | Prioridade | Notas |
|----|-----------|------------|-------|
| RF-010 | [Descrição] | Must / Should / Could | [Detalhe] |
---
## 4. Requisitos Técnicos e Arquitectura
### 4.1 Stack tecnológico
| Camada | Tecnologia | Justificação |
|--------|------------|-------------|
| Frontend | [ex: Next.js 14] | [razão] |
| Backend | [ex: Laravel 11] | [razão] |
| Base de dados | [ex: MySQL 8] | [razão] |
| Infra | [ex: EasyPanel + CWP] | [razão] |
### 4.2 Diagrama de arquitectura
```
[Componente A] → [API] → [Componente B]
↓
[Base de dados]
```
### 4.3 Integrações externas
| Sistema | Tipo integração | Dados trocados | Responsável |
|---------|----------------|----------------|-------------|
| [Sistema X] | REST API | [dados] | [quem] |
| [Sistema Y] | Webhook | [eventos] | [quem] |
### 4.4 Requisitos não-funcionais
| Requisito | Descrição | Target |
|-----------|-----------|--------|
| Performance | Tempo resposta API | < 500ms (p95) |
| Disponibilidade | Uptime | 99.5% |
| Segurança | Autenticação | JWT + refresh tokens |
| Escalabilidade | [detalhe] | [target] |
---
## 5. Milestones e Timeline
| Milestone | Entregável | Data alvo | Dependências |
|-----------|-----------|-----------|-------------|
| M1 — Setup | Infra + repo configurado | YYYY-MM-DD | — |
| M2 — MVP | [Feature core] funcional | YYYY-MM-DD | M1 |
| M3 — Beta | Testes com utilizadores | YYYY-MM-DD | M2 |
| M4 — Launch | Deploy produção | YYYY-MM-DD | M3 |
**Estimativa total:** [X semanas / meses]
**Velocidade estimada:** [X story points/sprint]
---
## 6. Riscos e Dependências
| Risco | Probabilidade | Impacto | Mitigação |
|-------|---------------|---------|-----------|
| [Risco 1] | Alta / Média / Baixa | Alto / Médio / Baixo | [acção] |
| [Risco 2] | Alta / Média / Baixa | Alto / Médio / Baixo | [acção] |
**Dependências bloqueantes:**
- [Dependência externa 1 — quem / quando]
- [Dependência externa 2 — quem / quando]
---
## 7. Definition of Done
Uma user story / feature é considerada concluída quando:
- [ ] Código em PR aprovado por pelo menos 1 revisor
- [ ] Testes unitários escritos (cobertura > X%)
- [ ] Testes de integração passam em CI
- [ ] Documentação actualizada
- [ ] Sem issues críticas em `pnpm audit`
- [ ] Deploy em staging testado e aprovado
- [ ] Tarefa Desk CRM actualizada com comentário HTML
---
## 8. Referências
**Projectos relacionados:**
- [Link para projecto Desk CRM]
- [Link para repositório Gitea]
**Documentação técnica:**
- [Link para API externa]
- [Link para PROC relevante]
**Ficheiros relevantes:**
- `[path local do ficheiro]`
---
**[Nome do Projecto] SPEC v1.0 | YYYY-MM-DD | Descomplicar®**
```
---
## Template 2: Proposta Comercial
```markdown
---
title: Proposta — [Cliente] — [Tema]
date: YYYY-MM-DD
type: proposta
status: draft
cliente_desk_id: [ID Desk CRM]
validade: YYYY-MM-DD
valor_total: [X EUR]
tags: [proposta, cliente, tema]
---
# Proposta Comercial
## [Título do Serviço / Projecto]
**Para:** [Nome Cliente] | [NIF se disponível]
**De:** Descomplicar — Crescimento Digital | NIF: 514 785 691
**Data:** YYYY-MM-DD | **Válida até:** YYYY-MM-DD
**Referência:** PROP-[YYYY]-[NNN]
---
## 1. Sumário Executivo
[2-3 parágrafos que respondem a: qual é o problema do cliente, o que propomos, e qual o resultado esperado. Escrito para quem não vai ler o documento completo.]
**Em síntese:** [Uma frase que resume proposta e valor.]
---
## 2. Contexto e Diagnóstico
### 2.1 Situação actual
[Descrever o estado actual do cliente com base no que foi partilhado. Mostrar que compreendemos o negócio e os desafios.]
### 2.2 Oportunidade identificada
[O que está a ser perdido / o que pode ser ganho. Contextualizar o valor da solução.]
### 2.3 Objectivo do projecto
[O que o cliente vai conseguir após a conclusão. Focado em resultado de negócio, não em features técnicas.]
---
## 3. Solução Proposta
### 3.1 Abordagem
[Descrever a solução de forma clara e não técnica. Como vamos resolver o problema.]
### 3.2 Entregáveis
| # | Entregável | Descrição | Formato |
|---|-----------|-----------|---------|
| 1 | [Nome] | [O que é] | [ficheiro / deploy / formação] |
| 2 | [Nome] | [O que é] | [ficheiro / deploy / formação] |
| 3 | [Nome] | [O que é] | [ficheiro / deploy / formação] |
### 3.3 O que não está incluído
[Listar explicitamente o que está fora de scope para evitar mal-entendidos.]
- [Item excluído 1]
- [Item excluído 2]
---
## 4. Timeline e Fases
| Fase | Descrição | Duração | Entregável |
|------|-----------|---------|-----------|
| 1 — [Nome] | [Actividades] | [X dias/semanas] | [O quê] |
| 2 — [Nome] | [Actividades] | [X dias/semanas] | [O quê] |
| 3 — [Nome] | [Actividades] | [X dias/semanas] | [O quê] |
**Início estimado:** [data, condicionada a aprovação em X dias]
**Conclusão estimada:** [data]
**Condições de prazo:**
- [Condição 1 — ex: receber acessos até X]
- [Condição 2 — ex: feedback em até X dias úteis]
---
## 5. Investimento
### 5.1 Resumo de valores
| Serviço | Valor |
|---------|-------|
| [Fase 1 / componente 1] | [X EUR] |
| [Fase 2 / componente 2] | [X EUR] |
| [Manutenção mensal] | [X EUR/mês] |
| **Total projecto** | **[X EUR]** |
*Valores sem IVA. IVA à taxa legal em vigor (23%).*
### 5.2 Condições de pagamento
- [X]% na assinatura — [valor EUR]
- [X]% na entrega de [milestone] — [valor EUR]
- [X]% na conclusão e aprovação final — [valor EUR]
### 5.3 Validade da proposta
Esta proposta é válida até **[data]**. Após esta data os valores poderão ser revistos.
---
## 6. Próximos Passos
Para avançar com este projecto:
1. **Aprovação** — responder a este email com "aprovado" ou solicitar reunião para esclarecimentos
2. **Contrato** — envio de contrato para assinatura em [X dias úteis]
3. **Pagamento inicial** — processamento do primeiro pagamento
4. **Kickoff** — reunião de arranque em [X dias após pagamento]
**Contacto:** Emanuel Almeida | emanuel@descomplicar.pt | 911 510 005
---
## 7. Sobre a Descomplicar
A Descomplicar é uma empresa portuguesa especializada em crescimento digital para PMEs.
**O que fazemos:** Desenvolvimento web, automação de processos, integração de sistemas e consultoria digital.
**Experiência relevante:**
- [Projecto ou cliente relevante 1]
- [Projecto ou cliente relevante 2]
**Website:** descomplicar.pt | **NIF:** 514 785 691
---
*Proposta PROP-[YYYY]-[NNN] | [Cliente] | YYYY-MM-DD | Descomplicar®*
```
---
## Template 3: PROC Operacional
```markdown
---
title: [Título do Procedimento]
date: YYYY-MM-DD
type: procedimento
status: draft
dept_id: [1-7]
desk_dept_id: [1-7]
desk_dept_name: [D1-Comercial | ... | D7-Tecnologia | Cross-Departamental]
codigo: [DEPT]-[TEMA]-[NUM]
tags: [tag1, tag2, tag3]
---
# [Título do Procedimento]
**Código:** [DEPT]-[TEMA]-[NUM] | **Departamento:** [Nome] | **Status:** Draft
**Criado:** YYYY-MM-DD | **Revisão:** [data da próxima revisão]
---
## 1. Objectivo
[Uma ou duas frases que descrevem o que este procedimento permite fazer e qual o resultado esperado ao segui-lo.]
---
## 2. Âmbito
### Aplica-se a:
- [Situação ou contexto onde usar este PROC]
- [Quem executa este procedimento]
- [Frequência de execução]
### Não se aplica a:
- [Situação excluída — e qual PROC usar em alternativa]
---
## 3. Pré-requisitos
| Requisito | Descrição | Como verificar |
|-----------|-----------|----------------|
| [Acesso X] | [Para quê] | [Onde confirmar] |
| [Ferramenta Y] | [Versão mínima] | [Comando de verificação] |
| [Conhecimento Z] | [Nível esperado] | [PROC ou doc de referência] |
---
## 4. Procedimento
### Passo 1: [Nome descritivo do passo]
**Objectivo:** [O que se consegue neste passo]
**Acções:**
1. [Acção concreta com comando se aplicável]
2. [Acção seguinte]
3. [Acção final do passo]
**Exemplo:**
```bash
# Comando de exemplo (se técnico)
exemplo-comando --opcao valor
```
**Validação:** [Como confirmar que este passo foi bem-sucedido]
---
### Passo 2: [Nome descritivo do passo]
**Objectivo:** [O que se consegue neste passo]
**Acções:**
1. [Acção concreta]
2. [Acção seguinte]
**Validação:** [Como confirmar sucesso]
---
### Passo 3: [Nome descritivo do passo]
[...]
---
## 5. Checklist de Execução
Usar para confirmar cada passo antes de avançar:
- [ ] Pré-requisitos verificados
- [ ] Passo 1 concluído e validado
- [ ] Passo 2 concluído e validado
- [ ] Passo 3 concluído e validado
- [ ] Resultado final validado
- [ ] Tarefa Desk CRM actualizada (se aplicável)
- [ ] Comentário HTML adicionado (se aplicável)
---
## 6. Troubleshooting
| Problema | Causa provável | Solução | Escalação |
|----------|----------------|---------|-----------|
| [Erro ou situação X] | [Porquê acontece] | [Passos para resolver] | [Quem contactar se não resolver] |
| [Erro ou situação Y] | [Porquê acontece] | [Passos para resolver] | [Quem contactar] |
---
## 7. Métricas e Validação
| Métrica | O que mede | Target | Como medir |
|---------|------------|--------|------------|
| [Tempo de execução] | Eficiência do processo | < [X min] | Cronometrar na primeira execução |
| [Taxa de sucesso] | Fiabilidade | > [X%] | Registo de execuções |
---
## 8. Referências Cruzadas
**Procedimentos relacionados:**
- [PROC-Outro.md](../PROC-Outro.md) — [Quando usar em vez deste]
- [PROC-Dependente.md](../PROC-Dependente.md) — [Executar antes/depois]
**Skills relacionadas:**
- `/skill-name` — [Para que serve em relação a este PROC]
**Documentação externa:**
- [Nome da doc](URL) — [O que cobre]
**Quick Reference:**
- `Hub/06-Operacoes/Documentacao/Quick-Reference/QR-[Tema].md`
---
## 9. Histórico de Revisões
| Data | Versão | Autor | Alterações |
|------|--------|-------|------------|
| YYYY-MM-DD | 1.0 | Emanuel Almeida | Criação inicial |
---
**[Título] | Código: [DEPT]-[TEMA]-[NUM] | [Departamento]**
**Última actualização:** YYYY-MM-DD
```
---
*Templates spec-coauthor v1.0.0 | 2026-03-10 | Plugin gestao | Descomplicar®*