| 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:
- o landscape e o diagrama afetados;
- o resumo das operações;
- os trade-offs e pontos de atenção;
- o hash de confirmação retornado pelo
plan-check;
- 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.
