diff --git a/project-manager/skills/project-init/SKILL.md b/project-manager/skills/project-init/SKILL.md new file mode 100644 index 0000000..0fcf352 --- /dev/null +++ b/project-manager/skills/project-init/SKILL.md @@ -0,0 +1,215 @@ +--- +name: project-init +description: Use when starting a new project from scratch — scaffolds .desk-project, CLAUDE.md, README.txt, CHANGELOG.md, initializes git, creates Gitea repo, and makes first commit. Step zero before /brainstorm or /spec. +--- + +# /project-init v1.0 - Scaffolding de Projecto + +Automatiza a criação de toda a estrutura de arranque de um projecto novo. +Passo zero antes de `/brainstorm → /spec → /sprint → código`. + +--- + +## Protocolo + +### 1. Recolher dados + +Perguntar ao utilizador (em bloco, uma só vez): + +``` +Para inicializar o projecto preciso de: +1. Nome do projecto (ex: FluxoSEO) +2. Descrição curta (1 linha) +3. ID da tarefa Desk CRM (ex: #2049) +4. ID do projecto Desk CRM (ex: #58) +5. Nome do projecto Desk (ex: DES 360º) +6. Directório local (ex: /media/ealmeida/Dados/Dev/NomeProjecto) +7. Nome do repositório Gitea (ex: fluxo-seo-audit) — deixar vazio para não criar +``` + +Se o utilizador já estiver numa pasta de projecto, assumir essa pasta como directório. + +--- + +### 2. Criar estrutura de ficheiros + +**2.1 `.desk-project`** + +```json +{ + "project_id": , + "project_name": "", + "client_id": null, + "desk_url": "https://desk.descomplicar.pt/admin/projects/view/", + "gdrive_folder": null, + "local_path": "", + "default_milestone": null, + "default_tags": ["development"], + "changelog_discussion_id": null, + "created_at": "" +} +``` + +**2.2 `CLAUDE.md`** + +```markdown +# CLAUDE.md — + +## Contexto +- **Tarefa Desk:** # +- **Projecto Desk:** (#) +- **Directório:** +- **Gitea:** https://git.descomplicar.pt/ealmeida/ +- **Criado:** + +## Descrição + + +## Stack +(preencher durante o projecto) + +## Caminhos Críticos +(preencher durante o projecto) + +## Regras do Projecto +- Seguir QR-Sites-CWP.md antes de referenciar paths WordPress +- Deploy paths validados antes de usar +- (adicionar regras específicas do projecto) + +## Comandos Frequentes +(preencher durante o projecto) +``` + +**2.3 `README.txt`** + +``` + +===================================== + +DeskCRM Task: # +Project: (#) +Description: +Created: +Gitea: https://git.descomplicar.pt/ealmeida/ + +Componentes +----------- +(preencher durante o projecto) + +Stack +----- +(preencher durante o projecto) + +Deploy +------ +(preencher durante o projecto) +``` + +**2.4 `CHANGELOG.md`** + +```markdown +# Changelog — + +## [Unreleased] + +## [0.1.0] — +### Adicionado +- Scaffolding inicial do projecto +- `.desk-project`, `CLAUDE.md`, `README.txt`, `CHANGELOG.md` +``` + +--- + +### 3. Inicializar Git + +```bash +cd +git init +git config user.email "emanuel@descomplicar.pt" +git config user.name "Emanuel Almeida" +git add .desk-project CLAUDE.md README.txt CHANGELOG.md +git commit -m "chore: scaffolding inicial — " +``` + +--- + +### 4. Criar repositório Gitea (se pedido) + +``` +mcp__gitea__create_repo({ + name: "", + description: "", + private: true, + auto_init: false +}) +``` + +Depois configurar remote e push: + +```bash +git remote add origin https://git.descomplicar.pt/ealmeida/.git +git push -u origin main +``` + +> Se o push via HTTPS falhar (SSH bloqueado), usar o workaround Python em `memory/gitea-push-workaround.md`. + +--- + +### 5. Actualizar CLAUDE.md com URL Gitea confirmado + +Preencher o campo `Gitea:` no CLAUDE.md após criação bem-sucedida do repo. + +--- + +### 6. Confirmar ao utilizador + +``` +✅ Projecto inicializado: + +📁 Ficheiros criados: + .desk-project (Desk #) + CLAUDE.md + README.txt + CHANGELOG.md + +🔧 Git inicializado e primeiro commit criado + +🔗 Gitea: https://git.descomplicar.pt/ealmeida/ + +Próximo passo: /brainstorm ou /spec create +``` + +--- + +## Regras + +1. **NUNCA** criar ficheiros sem ler o directório primeiro (evitar sobrescrever trabalho existente) +2. Se `.desk-project` já existir → avisar e perguntar se continua +3. Usar sempre `mcp__mcp-time__current_time` para a data (não assumir) +4. Gitea repo sempre `private: true` por omissão +5. Campos "Stack", "Caminhos Críticos" e "Componentes" ficam em branco — serão preenchidos conforme o projecto avança +6. Git config `user.email` e `user.name` obrigatórios antes do commit (evita "unable to auto-detect" error) + +--- + +## Anti-Patterns + +- **NÃO** criar repo Gitea público sem confirmação explícita +- **NÃO** assumir o directório — perguntar se não estiver óbvio +- **NÃO** pre-preencher Stack/Deploy sem informação real +- **NÃO** fazer `git add .` — adicionar apenas os 4 ficheiros do scaffolding + +--- + +## Integração + +| Skill | Relação | +|-------|---------| +| `/brainstorm` | Passo seguinte — explorar a ideia | +| `/spec create` | Passo seguinte — formalizar arquitectura | +| `/desk` | Usa `.desk-project` criado aqui | +| `/desk init` | Alternativa se o projecton já existir no Desk mas sem `.desk-project` | + +--- + +*Skill v1.0.0 | 2026-04-13 | Descomplicar®* diff --git a/project-manager/skills/start/SKILL.md b/project-manager/skills/start/SKILL.md new file mode 100644 index 0000000..7198693 --- /dev/null +++ b/project-manager/skills/start/SKILL.md @@ -0,0 +1,133 @@ +--- +name: start +description: Orquestrador do pipeline de trabalho novo — brainstorm → discover → spec → plan → execute. Use quando iniciar sistema novo, feature grande, ou projecto com múltiplos componentes. Impede saltar para execução sem planeamento. +--- + +# /start — Pipeline de trabalho novo + +Orquestra as 5 fases obrigatórias para qualquer trabalho novo não-trivial. +Anti-pattern que combate: saltar directamente para código sem brainstorm/spec/plan. + +--- + +## Quando usar + +**USAR quando:** +- Utilizador pede sistema/pipeline/feature nova com >2 componentes +- Trabalho estimado >1h ou >3 ficheiros +- Projecto novo em `05-Projectos/` ou `Dev/` +- Qualquer tarefa em que a abordagem não está obviamente definida + +**NÃO usar quando:** +- Bugfix / correcção pontual +- Operação unitária conhecida +- Continuação de plano já existente +- Admin / manutenção / diagnóstico + +--- + +## Protocolo (5 fases sequenciais) + +### Fase 1 — Brainstorming (obrigatório) + +Invocar `superpowers:brainstorming` skill OU `project-manager:brainstorm` skill. + +Objectivos: +- Explorar 3+ abordagens alternativas +- Identificar requisitos explícitos e implícitos +- Listar trade-offs conhecidos +- Detectar ambiguidades que precisam de clarificação do utilizador + +Output: secção "Brainstorming" com alternativas consideradas. + +### Fase 2 — Discover / Research (obrigatório) + +Invocar `project-manager:discover` skill. + +Verificar em paralelo: +- **Codebase actual** — existem componentes reutilizáveis? Glob + Grep +- **NotebookLM** — há notebook relevante? `mcp__notebooklm-mcp__notebook_list` + query +- **Hub** — procedimentos, QRs, decisões anteriores? Grep em `Hub/06-Operacoes/` +- **Memórias** — contexto de sessões anteriores? `mcp__mem0__search_memories` +- **Web** (se externo) — context7, WebSearch para libs/frameworks +- **Desk CRM** — tarefa associada? Projecto relacionado? + +Output: secção "Discovery" com fontes consultadas e descobertas relevantes. + +### Fase 3 — SPEC (obrigatório) + +Invocar `gestao:spec-coauthor` OU `project-manager:spec` (skill `spec create`). + +Gerar `SPEC.md` no directório do projecto (Hub/05-Projectos/NOME/ ou Dev/NOME/) com: +- **Porquê** — problema que resolve +- **Escopo** — o que entra +- **Não-escopo** — o que NÃO entra (crítico contra scope creep) +- **Critérios de sucesso** — como saber que está pronto +- **Arquitectura** — diagrama ou descrição dos componentes +- **Riscos** — o que pode correr mal +- **Plano faseado** — divisão em MVPs + +Aguardar aprovação do utilizador. Marcar como aprovado com `` no topo. + +### Fase 4 — Plan detalhado (obrigatório) + +Invocar `superpowers:writing-plans` skill. + +Traduzir SPEC em plano executável: +- Lista numerada de passos concretos +- Cada passo tem: acção, comando/código esperado, critério de validação +- Ordem de execução e dependências +- Checkpoints de revisão humana + +Guardar em `Hub/05-Projectos/NOME/PLAN.md` ou `.claude/plans/NOME.md`. + +### Fase 5 — Execução (finalmente) + +Invocar `superpowers:executing-plans` ou `superpowers:subagent-driven-development`. + +Durante execução: +- Seguir PLAN.md passo a passo +- Marcar progresso em TodoWrite +- Validar cada passo antes do seguinte +- Comentar no Desk CRM task associada +- Se desviar do spec → parar e actualizar SPEC.md primeiro (scope creep alert) + +--- + +## Output esperado da skill + +Ao invocar `/start "descrição do trabalho"`: + +``` +/start detectou novo trabalho: "descrição" + +Fase actual: 1 — Brainstorming +Próxima: Discovery + +[invoca brainstorming skill automaticamente] +``` + +Skill não salta fases. Se utilizador insistir em saltar, avisa mas aceita override explícito (`/start --skip-to=execute`). + +--- + +## Anti-patterns + +- **NUNCA** começar Fase 5 (execução) sem Fases 1-4 completas +- **NUNCA** criar código antes de SPEC.md aprovado +- **NUNCA** inventar decisões arquitecturais sem brainstorming documentado +- **NUNCA** tratar "pareceu boa ideia" como substituto de discovery +- **SEMPRE** criar SPEC.md no repositório do projecto (não em `/tmp` ou inline) +- **SEMPRE** aguardar aprovação explícita entre fases críticas + +--- + +## Integração com spec-gate.sh + +O hook `spec-gate.sh` (PreToolUse Write|Edit) valida que existe SPEC.md aprovado antes de permitir edições em `/Dev`. Esta skill garante que esse SPEC é criado via pipeline correcto antes de chegar à execução. + +Para bypass temporário (quick fixes, 30min): `/spec bypass`. + +--- + +*Skill v1.0.0 | 2026-04-08 | Descomplicar®*