| name | mosk-suggestion |
| description | Suggestion: interpreta o ponto atual da sessão (spec ativa, current_phase, artefatos no disco e foco da conversa) e sugere o próximo agente MOSK a chamar, já com um prompt pronto para colar. Use quando o usuário perguntar 'e agora?', 'qual o próximo passo?', 'qual agente devo chamar?' ou quiser orientação para avançar no pipeline (specify → plan → tasks → implement → qa-gate → archive). Apenas sugere — nunca invoca outro agente automaticamente. |
| argument-hint | O que você quer fazer a seguir? (opcional) |
Suggestion (MOSK)
Read the current session state and recommend the single next MOSK
agent to call, with a ready-to-paste prompt. This is the inverse of a
handoff: instead of writing a document, you produce one concrete next
step the user can run immediately.
Idioma: responda no idioma de comunicação do projeto (campo Idioma de
comunicação em .claude/rules/project.md); o padrão é português (pt-BR)
quando nenhum estiver definido. Mantenha em forma literal apenas nomes de
skill, comandos, caminhos e ids de spec.
IMPORTANT — suggest only, never invoke. It proposes the next agent
and waits. Never activate another persona, run its task, or chain agents
automatically. The user decides whether to run the prompt, skip, or redirect.
Workflow
Step 1 — Read the current state
- Read every file in
.claude/rules/*.md for durable project context.
- Resolve the active spec and phase:
- Run
bash .claude/mosk/scripts/validate.sh prerequisites --json --paths-only (when available) to resolve BRANCH, FEATURE_DIR, and AVAILABLE_DOCS.
- If a
FEATURE_DIR resolves, read its spec-meta.yaml: spec_id, type, status, current_phase.
- Note which artifacts exist on disk:
spec.md, plan.md, tasks.md, stories/, tests/, gate.yaml.
- If
current_phase is qa-gate, read gate.yaml to learn the verdict (PASS | CONCERNS | FAIL | WAIVED) and the score_history.
- If there is no active spec yet, route from the table's first two rows.
- Read the conversation focus: what was just completed or discussed this session. The chat is authoritative when it is clearly ahead of the metadata (e.g. the user just finished implementing but
current_phase still says tasks).
- Reconcile: when the conversation and
current_phase disagree, trust what actually happened in the session and say so in the suggestion.
Step 2 — Locate the position in the MOSK lifecycle
Use the mapping table below. Pick one primary suggestion; add at most two
alternatives only when a real fork exists.
If grounding is missing — no PRD/discovery/architecture/UX for a decision the
next step depends on — recommend the agent that owns that ground instead, in the
same suggestion block. A gap in ADR, PRD or flow is a routing signal, and
routing belongs to the user.
Escreva a sugestão em palavras comuns. "Preâmbulo", "side-trip", "escalação" e
"fase" são vocabulário nosso: diga o que fazer e por quê, não em que caixa
do modelo aquilo cai.
Step 3 — Emit the suggestion block
Output exactly one block. Fill the prompt with the real spec_id /
description, not placeholders:
> **Próximo passo sugerido**
> - Onde estamos: <fase atual ou o que acabou de ser concluído>
> - Próximo agente: `/mosk-<x>`
> - Prompt pronto: `/mosk-<x> <ação com o spec-id/descrição reais>`
> - Por quê: <uma linha justificando>
> - Alternativas: <0–2 opções, ou "nenhuma">
Then stop. End with one short line telling the user to colar o prompt
para prosseguir (ou pedir outra direção). Do not run anything.
Mapping — estado → próximo agente
| Estado detectado | Próximo agente | Prompt pronto (modelo) |
|---|
| Sem spec ativa e ideia ainda não aterrada (sem PRD/discovery) | /mosk-analyst ou /mosk-pm | /mosk-pm criar PRD para <ideia> |
| Sem spec ativa, escopo claro | /mosk-po | /mosk-po full-spec <descrição> |
current_phase: specify (existe spec.md) | /mosk-po | /mosk-po plan {spec-id} |
current_phase: plan (existe plan.md) | /mosk-po | /mosk-po tasks {spec-id} |
current_phase: tasks, stories ainda não revisadas | /mosk-sm (opcional) | /mosk-sm revisar prontidão das stories da spec {spec-id} |
current_phase: tasks (pronto para codar) | /mosk-dev | /mosk-dev implement {spec-id} |
current_phase: implement, diff tocou superfície sensível | /mosk-security (opcional) | /mosk-security review do diff da spec {spec-id} |
current_phase: implement (código entregue) | /mosk-qa | /mosk-qa qa-gate {spec-id} |
current_phase: qa-gate, gate PASS/WAIVED | /mosk-dev | /mosk-dev archive {spec-id} |
current_phase: qa-gate, gate CONCERNS/FAIL, score subindo | /mosk-dev | /mosk-dev apply-qa-fixes {spec-id} |
current_phase: qa-gate, gate FAIL com score parado entre voltas |
Sobre a penúltima linha do gate. Score parado entre duas voltas é o sinal de
que mais uma volta não resolve: o problema está acima da execução — design, PRD
ou story ambígua. Sugerir apply-qa-fixes de novo ali é o erro que a série de
score existe para evitar. Leia score_history no gate.yaml antes de decidir
entre as duas linhas.
Notes
full-spec cobre specify → plan → tasks de uma vez; depois dele o
próximo passo é /mosk-dev implement./mosk-sm, /mosk-security, /mosk-ui-expert e /mosk-ux-expert são
desvios opcionais: entram quando algum sinal os justifica, nunca no
caminho padrão, e devolvem o trabalho para a fase de onde saiu.- Se o usuário passou um argumento, trate-o como a intenção do próximo passo
e enviese a sugestão para ela (sem abandonar a checagem de fase).
Rules
- Apenas sugere. Nunca ative outra persona nem rode a task dela. Pare
após emitir o bloco e aguarde a decisão do usuário.
- Uma sugestão primária. Evite menus: escolha o passo mais provável e
ofereça no máximo duas alternativas reais.
- Prompt pronto, com dados reais. Preencha
{spec-id} e a descrição
com o que foi detectado — o usuário deve conseguir copiar e colar.
- A conversa vence a metadata quando estiver claramente à frente; diga
isso na linha "Onde estamos".
- Saída no idioma de comunicação do projeto (default pt-BR), exceto nomes
de skill, comandos, caminhos e ids.
