paulstraw/g-scheduler

O que g-scheduler faz?

Encontra horários de reunião onde todos os participantes estão livres e dentro de seus horários de trabalho; depois (somente se solicitado) cria o convite. Dois scripts incluídos fazem as chamadas ao Google e o cálculo de horários. Nunca faça contas de fuso horário ou horário de verão você mesmo: use a saída deles.

Execute os scripts com python3 (no Windows, python ou py) a partir do diretório deste skill: scripts/gcal.py e scripts/slots.py. Eles precisam de Python 3.9+.

1. Verificar acesso

Execute python3 scripts/gcal.py check.

• Se falhar porque gws está ausente ou não autenticado, ou um erro do Python pedir tzdata, pare e guie o usuário pelo SETUP.md, um passo de cada vez. Não há como continuar sem isso.
• Se funcionar, continue. my_working_hours: "not set" é normal.

2. Coletar as entradas

• Participantes: resolva todos para endereços de e-mail do Google Workspace. Para nomes sem e-mail, execute python3 scripts/gcal.py find "Ada Lovelace" "Grace", que pesquisa o diretório da organização; outras ferramentas que você tiver (Slack, a mensagem do usuário) também funcionam. Se find falhar (escopo ausente, accessNotConfigured, ou o administrador desabilitou o compartilhamento do diretório), a busca por nome não está disponível: mencione o motivo uma vez, aponte para Solução de Problemas no SETUP.md e use outras ferramentas. Se um e-mail estiver ausente, ambíguo ou parecer fora da organização do usuário, pergunte. O usuário é adicionado automaticamente; passe --exclude-me somente se ele disser que não vai participar.
• Intervalo de datas: mantenha simples. "Próximas 2 semanas" significa de hoje até cerca de 18 dias à frente (horários mais próximos já aparecem primeiro). Um dia específico significa apenas aquele dia. Datas estão no formato YYYY-MM-DD; a data final é inclusiva.
• Duração: padrão 60 minutos. Não pergunte; diga que você assumiu.
• Pessoas opcionais: não pergunte de início. Trate todos como obrigatórios.

3. Encontrar horários

python3 scripts/gcal.py gather [email protected] [email protected] --start 2026-11-10 --end 2026-11-27 \
  | python3 scripts/slots.py

Opções de gather: --duration MIN, --optional EMAIL (repetível), --exclude-me, --time-zone TZ (padrão é o fuso horário do calendário do usuário, que também é usado para classificar e exibir).

A saída contém slots (até 5, no máximo 2 por dia, do mais cedo para o mais tarde), all_required_free, attendees e warnings. Cada slot tem horários local para cada participante e no fuso do usuário, missing, missing_optional e at_day_edge (pessoas para quem o horário está nos primeiros ou últimos 30 minutos do dia).

Leia a saída completa. Não a filtre (por exemplo com jq ou python -c), pois isso descarta warnings.

Para verificar um horário específico (o usuário propõe um horário, um slot não aparece na lista ou um participante é adicionado tarde), execute o mesmo pipeline para todos os participantes com --start e --end definidos exatamente para aquela reunião, como horários RFC3339 com offset: --start 2026-11-19T11:00:00-08:00 --end 2026-11-19T12:00:00-08:00. O único slot na saída informa quem está ausente. Nunca calcule disponibilidade a partir de horários ocupados brutos por conta própria.

4. Apresentar os resultados

• Liste os slots no fuso horário do usuário, com o horário local de cada participante quando os fusos forem diferentes.
• Repita cada aviso em palavras simples. Mencione as pessoas cujos horários de trabalho foram assumidos (09:00-17:00 em dias úteis no fuso delas) e qualquer pessoa que foi deixada de fora porque o calendário não pôde ser lido.
• Informe a duração assumida se o usuário não tiver fornecido uma.
• Se all_required_free for falso, diga quem está ausente em cada slot e pergunte se deve repetir a busca com algum deles como --optional. Somente o usuário decide quem é opcional; nunca marque alguém como opcional por conta própria.
• Se slots estiver vazio, informe e sugira um intervalo maior ou uma reunião mais curta.

5. Criar o convite (somente quando solicitado)

1. Elabore um título a partir do contexto e uma descrição curta que inclua o link de origem (por exemplo, o thread do Slack), se houver.

2. Pergunte se deve adicionar um link de videoconferência. Se fornecido, coloque-o em location e na descrição. Não crie reuniões do Meet ou Zoom.

3. Mostre o evento exato (título, horário local, participantes, descrição, local) e aguarde um "sim, envie" explícito. Enviar e-mails para todos e não pode ser desfeito.

4. Escreva o evento em um arquivo JSON temporário como um recurso Events do Google Calendar, com horários no fuso do usuário:

   {
     "summary": "Project kickoff",
     "description": "Agendado a partir de https://example.slack.com/archives/...",
     "location": "https://zoom.us/j/123",
     "start": {"dateTime": "2026-11-18T10:00:00", "timeZone": "America/Los_Angeles"},
     "end": {"dateTime": "2026-11-18T11:00:00", "timeZone": "America/Los_Angeles"},
     "attendees": [{"email": "[email protected]"}, {"email": "[email protected]"}]
   }
   

5. Execute python3 scripts/gcal.py invite EVENT.json. Ele sempre envia convites para todos os participantes. Use --dry-run primeiro se quiser verificar a requisição.

6. Forneça ao usuário o htmlLink da saída e exclua o arquivo temporário.

Regras

• Tudo, exceto invite, é somente leitura. Nunca altere o calendário ou os horários de trabalho de ninguém.
• Nunca envie um convite sem a confirmação explícita do usuário sobre o evento visualizado.
• Se os horários de um fuso parecerem com uma hora de diferença, provavelmente os dados de fuso horário da máquina estão desatualizados (as regras de fuso mudam, como as da Colúmbia Britânica em 2026). Consulte Solução de Problemas no SETUP.md.