claude-plugins/gestao/skills/time/SKILL.md

---
name: time
description: Gestão de tempo integrada com Desk CRM. Alertas >4h, total semanal, integração worklog. Usar quando "time", "timer", "horas", "timesheet", "start", "stop", "tempo".
disable-model-invocation: true
---

# /time v2.0 - Gestão de Tempo

Timer integrado com Desk CRM. Alertas inteligentes, resumo semanal.

---

## Novidades v2.0

- **Alerta >4h:** Perguntar se timer ainda activo
- **Total semana:** Mostrar horas Seg-Dom no status
- **Link worklog:** Oferecer criar worklog ao parar
- **Verificação:** Comparar estado local vs Desk

---

## Comandos

| Comando | Função |
|---------|--------|
| `/time` | Ver status (timer + semana) |
| `/time start <task_id>` | Iniciar timer |
| `/time stop` | Parar timer actual |
| `/time switch <task_id>` | Trocar para outra tarefa |
| `/time log <hours> <task_id>` | Entrada manual |

---

## Protocolo

### /time (Status)

```
1. Obter hora actual via mcp__mcp-time__current_time
2. Ler ~/.claude-work/active-timer.json
3. Se timer activo:
   a. Calcular duração
   b. SE >4h: Mostrar alerta "Timer activo há Xh. Ainda a trabalhar?"
4. Obter timesheets da semana:
   mcp__desk-crm-v3__get_timesheets_advanced({
     staff_id: 1,
     start_date: segunda_da_semana,
     end_date: domingo_da_semana
   })
5. Mostrar resumo
```

**Output:**

```markdown
## ⏱️ Timer Activo
🟢 #1446 - Documentação Skills
   Projecto: Stack Workflow (#65)
   Iniciado: 14:30 (há 2h 15m)

## 📊 Esta Semana (03-09 Fev)
| Dia | Horas |
|-----|-------|
| Seg | 6h 30m |
| Ter | 7h 15m |
| Qua | 4h 45m ← Hoje |
| **Total** | **18h 30m** |
```

**Se timer >4h:**

```markdown
⚠️ Timer activo há **5h 30m**

Ainda a trabalhar em #1446?
- [Sim, continuar]
- [Parar timer]
- [Ajustar tempo]
```

---

### /time start <task_id>

```
1. Verificar se já existe timer activo
   - Se sim: "Já tens timer em #X. Parar primeiro?"
2. Obter detalhes da tarefa:
   mcp__desk-crm-v3__get_task({ task_id })
3. **VALIDAR WORKFLOW (obrigatório):**
   a. Verificar se tarefa está atribuída ao utilizador:
      - Verificar se staff_id: 1 está em task.assignees
      - Se NÃO: Erro "⚠️ Tarefa não atribuída a ti. Atribui primeiro."
   b. Verificar status da tarefa:
      - Status deve ser apropriado para timer (não "Não Iniciada")
      - Se status inadequado: Erro com instruções
   c. **Se validação falhar:**
      ```
      ⚠️ Para iniciar timer:
      1. Atribuir tarefa a ti (staff_id: 1)
      2. Mudar status para "Em progresso"
      3. Só depois iniciar timer

      Tarefas que precisam ser executadas:
      [Listar acções necessárias]
      ```
4. Iniciar timer no Desk:
   mcp__desk-crm-v3__start_timer({
     task_id: task_id,
     staff_id: 1,
     note: "Iniciado via Claude Code"
   })
5. Guardar estado local:
   ~/.claude-work/active-timer.json
6. Confirmar
```

**Ficheiro estado:**

```json
{
  "task_id": 1446,
  "task_name": "Documentação Skills",
  "project_id": 65,
  "project_name": "Stack Workflow",
  "started_at": "2026-02-05T14:30:00Z",
  "staff_id": 1
}
```

---

### /time stop

```
1. Ler estado local
2. SE vazio: "Sem timer activo"
3. Calcular duração
4. Parar timer no Desk:
   mcp__desk-crm-v3__stop_timer({
     task_id: task_id,
     staff_id: 1
   })
5. Limpar estado local
6. Perguntar: "Criar worklog? [Sim/Não]"
   - Se sim: Invocar /worklog com contexto
7. Confirmar
```

**Output:**

```markdown
⏹️ Timer parado!

📋 Tarefa: #1446 - Documentação Skills
⏱️ Duração: 2h 15m
📁 Projecto: Stack Workflow

Criar worklog? [Sim] [Não]
```

---

### /time switch <task_id>

```
1. Parar timer actual (silencioso, nota: "Switched")
2. Iniciar novo timer na tarefa indicada
3. Confirmar troca
```

---

### /time log <hours> <task_id>

```
1. Validar formato horas (ex: "2h", "2.5", "2h30m")
2. Converter para decimal
3. Registar entrada manual:
   mcp__desk-crm-v3__add_timesheet_entry({
     task_id: task_id,
     staff_id: 1,
     hours: hours_decimal,
     note: "Entrada manual via Claude Code"
   })
4. Confirmar
```

---

## Integração /today

O `/today` deve mostrar timer activo:

```markdown
## ⏱️ Timer Activo
🟢 #1446 - Documentação (2h 15m)
```

---

## Integração /worklog

Ao parar timer, oferecer criar worklog com contexto:
- Tarefa trabalhada
- Duração
- Projecto

---

## Constantes

```javascript
const STAFF_ID = 1;  // Emanuel
const AIKTOP_ID = 25;  // Para comentários automáticos
const TIMER_STATE = "/home/ealmeida/.claude-work/active-timer.json";
const ALERT_HOURS = 4;  // Alertar após 4h
```

---

## Anti-Patterns

- **NUNCA** deixar timer overnight sem perguntar
- **NUNCA** iniciar timer sem tarefa associada
- **NUNCA** criar tarefa só para ter timer (usar tarefas existentes)
- **NUNCA** iniciar timer sem validar workflow:
  - Tarefa DEVE estar atribuída ao utilizador
  - Status DEVE ser apropriado ("Em progresso", não "Não Iniciada")
  - SEMPRE validar antes de start_timer

---

## Changelog

### v2.0.0 (2026-02-05)
- Alerta se timer >4h
- Mostrar total horas da semana no status
- Integração com /worklog ao parar
- Verificar estado Desk vs local
- Semana: Seg-Dom

### v1.1.0 (2026-02-03)
- Workflows organizados
- MCP Tools corrigidos

### v1.0.0 (2026-01-27)
- Versão inicial

---

*Skill v2.0.0 | 2026-02-05 | Descomplicar®*