icepanel-proposal

name	icepanel-proposal
description	Analisa desenhos ou textos de arquitetura e cria planos reversíveis para o IcePanel. Use para diagramar, revisar ou propor mudanças em landscapes IcePanel.
compatibility	Requer Python 3.8+, acesso HTTPS a api.icepanel.io e ICEPANEL_API_KEY. Escritas exigem confirmação explícita e snapshot de segurança.
metadata	{"version":"0.3.0"}

Proposta de arquitetura no IcePanel

Transforme uma imagem ou descrição de arquitetura em uma proposta revisável no IcePanel. Preserve o modelo existente, explicite ambiguidades e trate toda escrita na versão latest como alteração de produção.

Regras de portabilidade

• Use os recursos de pergunta, terminal e entrega de arquivos disponíveis no host. Não dependa de nomes de ferramentas de um fornecedor.
• Localize o diretório raiz deste plugin procurando o ancestral que contém .claude-plugin e .codex-plugin. Guarde o caminho absoluto em ICEPANEL_PLUGIN_ROOT e execute o CLI por python3 "$ICEPANEL_PLUGIN_ROOT/scripts/icepanel_cli.py".
• Grave planos, especificações e resultados no workspace do usuário, nunca dentro do diretório instalado do plugin.
• Nunca peça que uma credencial seja colada na conversa. Se ICEPANEL_API_KEY estiver ausente, explique como configurá-la no ambiente seguro do host e aguarde.

Antes do fluxo, execute:

python3 "$ICEPANEL_PLUGIN_ROOT/scripts/preflight.py" --json

Se Python, rede ou credencial não estiverem disponíveis, limite-se à análise e gere um plano local; não simule que o IcePanel foi alterado.

Leia taxonomia antes de classificar elementos e a referência da API antes de diagnosticar erros.

Fluxo

1. Entenda a entrada

Extraia e apresente:

Campo	Conteúdo esperado
Componentes	nome, tipo C4/IcePanel, tecnologia, parent e externalidade
Conexões	origem, destino, fluxo, direção, sincronismo e intermediário
Ambiguidades	texto ilegível, direção incerta, tipo ou fronteira duvidosa

Não converta ambiguidade em fato. Solicite somente as respostas que mudem o modelo e obtenha aprovação do inventário antes de consultar ou modificar o IcePanel.

2. Escolha o landscape e a estratégia

Liste landscapes e diagramas existentes:

python3 "$ICEPANEL_PLUGIN_ROOT/scripts/icepanel_cli.py" landscapes
python3 "$ICEPANEL_PLUGIN_ROOT/scripts/icepanel_cli.py" diagrams --landscape LANDSCAPE_ID --version latest --compact

Confirme o landscape e se a proposta deve criar um diagrama ou ampliar um existente. Explique que latest é o modelo vivo: objetos propostos entram como future e itens substituídos ficam deprecated. Se o usuário exigir isolamento, recomende duplicar o landscape e interrompa as escritas até ele escolher.

3. Reuse antes de criar

python3 "$ICEPANEL_PLUGIN_ROOT/scripts/icepanel_cli.py" objects --landscape LANDSCAPE_ID --version latest --compact
python3 "$ICEPANEL_PLUGIN_ROOT/scripts/icepanel_cli.py" connections --landscape LANDSCAPE_ID --version latest --compact
python3 "$ICEPANEL_PLUGIN_ROOT/scripts/icepanel_cli.py" match --landscape LANDSCAPE_ID --version latest --names "Pedidos API:app,Pedidos DB:store"

Use o tipo como pista de matching. Revise candidatos entre 0,50 e 0,72 e apresente uma tabela separando reuse, create, update e deprecate. O valor desta etapa é evitar duplicação sem fundir conceitos apenas porque os nomes se parecem.

4. Gere um plano, sem escrever

Crie proposal-plan.json seguindo o contrato do plano. Toda criação deve usar uma referência simbólica estável; objetos e conexões novos usam status: future; updates incluem os valores anteriores usados pelo rollback.

Valide o plano:

python3 "$ICEPANEL_PLUGIN_ROOT/scripts/icepanel_cli.py" plan-check --plan proposal-plan.json --seal

Apresente ao usuário:

1. o landscape e o diagrama afetados;
2. o resumo das operações;
3. os trade-offs e pontos de atenção;
4. o hash de confirmação retornado pelo plan-check;
5. onde serão gravados o ledger e os artefatos.

Não aplique o plano na mesma etapa em que ele foi apresentado. Aguarde uma confirmação explícita que faça referência ao plano ou ao hash.

5. Aplique com snapshot e ledger

Depois da confirmação:

python3 "$ICEPANEL_PLUGIN_ROOT/scripts/icepanel_cli.py" plan-apply \
  --plan proposal-plan.json \
  --ledger operation-ledger.json \
  --confirm PLAN_HASH \
  --create-snapshot

O snapshot é a proteção contra uma operação parcial. O ledger registra snapshot, operações executadas, IDs resolvidos e dados anteriores. Se o CLI interromper no meio, não repita o apply: leia o ledger e retome ou faça rollback.

6. Verifique e revise

Exporte o diagrama ou faça a verificação estrutural:

python3 "$ICEPANEL_PLUGIN_ROOT/scripts/icepanel_cli.py" diagram-export --landscape LANDSCAPE_ID --version latest --diagram DIAGRAM_ID --out proposta.png
python3 "$ICEPANEL_PLUGIN_ROOT/scripts/icepanel_cli.py" content-get --landscape LANDSCAPE_ID --version latest --diagram DIAGRAM_ID

Revise somente riscos relevantes para a proposta: ponto único de falha, cadeia síncrona, ownership de dados, consistência, exposição externa, segurança, observabilidade, capacidade e custo operacional.

Cada ajuste posterior gera um novo plano e uma nova confirmação. Não use comandos CRUD diretos para contornar esse limite.

7. Finalize ou reverta

Se aprovado, gere approved-architecture.json conforme o contrato de handoff. Esse artefato é a entrada portável para a skill cloud-solution-diagram e não depende do histórico da conversa.

Se rejeitado, primeiro obtenha o hash de rollback e depois confirme o rollback seletivo:

python3 "$ICEPANEL_PLUGIN_ROOT/scripts/icepanel_cli.py" plan-rollback --ledger operation-ledger.json
python3 "$ICEPANEL_PLUGIN_ROOT/scripts/icepanel_cli.py" plan-rollback \
  --ledger operation-ledger.json \
  --confirm ROLLBACK_HASH

Use version-revert apenas se o rollback seletivo falhar ou se o usuário escolher restaurar integralmente o snapshot; isso substitui todo o latest, inclusive mudanças concorrentes de terceiros.

Condições de parada

• Credencial, rede ou permissão ausente: entregue somente o plano local.
• Landscape ou sentido das conexões incerto: solicite mediação.
• Hash divergente: regenere e reapresente o plano.
• Alteração concorrente detectada: interrompa o apply e reconcilie o plano.
• Falha parcial: preserve o ledger; não invente IDs nem declare sucesso.