agentleFS
otavioserraotavioserra/conn2flow-ai-workspace/.claude/skills/mdd-workflow/SKILL.md

mdd-workflow

Skill4 starsChanged 33 days agoMITView on GitHub

LEIA ANTES de criar ou alterar qualquer arquivo na pasta memory/ (process, implementation, validation, decisions). Se não ler: o fluxo de Agente Duplo é quebrado e os artefatos de controle perdem a governança.

  • Reads credentials
  • Commits and pushes

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use esta skill quando o projeto for guiado por documentos MDD versionados.

    line 16
  2. Distinctive:

    Commit semântico e push na branch de trabalho.

    line 81
  3. Distinctive:

    Preferências subjetivas de interação do operador (estilo de resposta, atalhos de prompt, idioma preferido).

    line 118

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

MDD workflow

⚡ Gatilho Obrigatório

  • TRIGGER: Iniciar qualquer tarefa do framework MDD, interpretar requisições humanas ou classificar artefatos nas pastas de controle.
  • SKIP APENAS SE: Tarefas completamente alheias ao ciclo de governança MDD (ex: git commits diretos de infraestrutura).
  • CONSEQUÊNCIA DE IGNORAR: Desalinhamento entre Arquiteto e Executor, criação de arquivos em locais errados e colapso da metodologia de Agente Duplo.

Use esta skill quando o projeto for guiado por documentos MDD versionados.

🚫 Bloqueio de Memory Gardening: não invoque nem pode a memória de execução apenas por encerrar uma sessão ou concluir um batch. Abaixo de 50 KB e 200 linhas o arquivo está saudável e não deve ser reescrito; em 50 KB / 200 linhas há somente alerta preventivo, e a poda é obrigatória apenas em 75 KB / 300 linhas.

Leitura mínima inicial

Comece por memory/README.md, memory/process/00-START-HERE.md, memory/process/01-WORKFLOW.md, memory/implementation/BATCH-INDEX.md, o batch atual, memory/validation/VALIDATION-CHECKLIST.md e memory/decisions/DECISION-LOG.md.

Se a tarefa apontar para memory/human-requests/*.md ou para a pasta memory/human-requests/, leia primeiro esse intake humano. Quando vier apenas a pasta, use a seguinte ordem determinística:

  1. CURRENT.md
  2. README.md
  3. o arquivo .md mais recente

Classificação da demanda

  1. Mudança de requisito ou contrato:
    • registre em memory/change-requests/
    • avalie impacto nos documentos normativos numerados, decisions, batches e validation
  2. Feedback de review sem mudança normativa:
    • registre em memory/human-reviews/
    • mantenha os documentos normativos numerados estáveis
  3. Implementação incremental:
    • confira o batch atual em memory/implementation/
    • implemente o menor slice aprovado
    • valide e atualize memory/validation/ quando necessário
  4. Validação ou spec drift check:
    • comece pela menor checagem automatizada
    • registre evidência e pendências nos artefatos certos

Regras de ouro

  • Os documentos normativos numerados são a fonte normativa.
  • memory/human-requests/ nunca é fonte normativa; ele só alimenta change requests, reviews, batches, decisions ou validação.
  • Não reescreva os documentos normativos numerados para comentários pequenos de review.
  • Não abra o próximo batch antes de o atual estar estável e revisável.

Regra dos 10 Ativos na Raiz e Integridade de Links

  • A raiz de memory/human-requests/ mantém no máximo 10 requisições soltas (além de CURRENT.md e README.md); a raiz de memory/implementation/ mantém no máximo 10 relatórios de lote (além de BATCH-INDEX.md). O excedente mais antigo vive em archive/.
  • Arquivar sem reescrever links é proibido: todo link de markdown em BATCH-INDEX.md, VALIDATION-CHECKLIST.md, DECISION-LOG.md e CURRENT.md deve continuar resolvendo após a movimentação.
  • Na raiz MDD, audite com mdd compact --path RAIZ_ABSOLUTA e aplique somente a manutenção autorizada com mdd compact --path RAIZ_ABSOLUTA --apply; preservação dual e reparo de links são obrigatórios. Não invente um comando ai:archive-mdd.
  • Não mova esses arquivos com mv/Move-Item manualmente.

📋 Protocolo de Transparência & Checklist Vivo (Live Todo List)

  • Ao iniciar qualquer requisição ou lote, renderize imediatamente a lista completa de tarefas (Todo List) com caixas de seleção [ ].
  • A cada término de etapa/comando relevante, atualize e re-exiba a lista marcando [x] nas etapas concluídas e destacando a etapa atual (⏳ [EM ANDAMENTO]).
  • Nunca execute sequências longas de comandos sem atualizar o status visual para o usuário.

🛡️ Espectro de 3 Níveis de Autonomia de IA

  1. Nível 1: SUPERVISIONADO (Padrão Mandatório / Human-in-the-Loop):
    • O agente implementa código e executa testes, mas NÃO realiza commit, push ou deploy automático.
    • O desenvolvedor revisa e aprova as mudanças no chat/IDE antes da consolidação.
  2. Nível 2: AUTÔNOMO MONITORADO (Live Autopilot / Glass-Box no Chat):
    • Ativado quando a requisição contiver modo: autonomo_monitorado ou o usuário autorizar expressamente o acompanhamento contínuo na tela.
    • O agente executa a esteira completa com Live Todo List ([ ] ➔ [x]) visível e atualizado em tempo real:
      • Criação de branch (feat/req-XXX); worktree apenas sob concorrência comprovada, conforme REQ-077.
      • Codificação e compilação de recursos (c2f resources:sync).
      • Execução de testes automatizados (c2f db:test).
      • DEPLOY EXCLUSIVAMENTE EM AMBIENTE DE TESTE LOCAL (c2f manager:update-all ou Docker local).
      • ⛔ REGRA INVIOLÁVEL DE SEGURANÇA: NUNCA REALIZAR DEPLOY AUTOMÁTICO EM AMBIENTE DE PRODUÇÃO OU SERVIDORES REMOTOS.
      • Commit semântico e push na branch de trabalho.
      • Relatório final com logs de execução e evidências de validação.
    • Goal Mode (/goal) para Execução Contínua:
      • Em tarefas complexas ou fatias que exigem múltiplos ciclos de teste e correção, utilize o comando /goal no prompt do Claude / IDE.
      • Exemplo de instrução: "/goal Execute o lote BATCH-XXX até que todos os testes do VALIDATION-CHECKLIST.md passem e o relatório esteja preenchido."
      • O agente permanece em loop autônomo ininterrupto até satisfazer deterministamente todas as condições de encerramento do checklist técnico, impedindo paradas prematuras.
  3. Nível 3: AUTÔNOMO HEADLESS (Background Silencioso / Black-Box):
    • Ativado quando a requisição contiver modo: autonomo_headless.
    • O agente executa a esteira via MCP Hub, emitindo notificação e relatório consolidado ao término; worktree somente sob concorrência comprovada e com expurgo seguro ao fechar o lote.

🔒 Regras Mandatórias de Concorrência & Reserva Atômica de Requisições (req-XXX.md)

  1. Proibição Absoluta de git add -A e git commit -a:
    • O agente DEVE executar git add <caminho-1> <caminho-2> listando estritamente os arquivos tocados no seu lote aprovado, prevenindo que commits arrastem código concorrente ou arquivos de outros agentes.
  2. Protocolo de Reserva Atômica para Criação de req-XXX.md:
    • Qualquer agente (Arquiteto ou Executor) está autorizado a criar novos arquivos req-XXX.md quando instruído pelo usuário no chat ou ao levantar uma demanda técnica essencial, seguindo estritamente:
      1. Executar git pull origin <branch> para obter o estado mais recente.
      2. Reler atomicamente o diretório memory/human-requests/ para identificar o próximo número sequencial vago.
      3. Criar o arquivo req-XXX.md, atualizar memory/human-requests/CURRENT.md e commitar/pushar imediatamente:
        git add memory/human-requests/req-XXX.md memory/human-requests/CURRENT.md
        git commit -m "docs(mdd): reserve REQ-XXX for <titulo>"
        git push origin <branch>
  3. Identificação Obrigatória de Repositório nos Handoffs:
    • Todo handoff humano-agente ou inter-agentes deve explicitar no topo da mensagem o identificador e o caminho absoluto da raiz do repositório alvo:
      • Projeto: <nome-do-projeto>
      • Caminho Raiz: <caminho-absoluto-da-raiz>
      • Requisição: REQ-XXX | Batch: BATCH-YYY
    • Previne que agentes executores ou revisores operem no repositório incorreto em ambientes com múltiplos workspaces abertos.

🧠 Camadas Canônicas de Memória

  1. Memória do Repositório (memory/04-memory-engineering-execution.md — Git Compartilhado):
    • Fatos técnicos objetivos do software: bugs resolvidos no core, hacks temporários de build/banco, particularidades de compilação CSS/Tailwind, comandos CLI descobertos e lições aprendidas. Visível a todos os agentes e desenvolvedores.
  2. Memória Privada da Ferramenta de IA (Local):
    • Preferências subjetivas de interação do operador (estilo de resposta, atalhos de prompt, idioma preferido).

⚖️ Princípio da Autoridade do Código e da SPEC sobre Memórias

  • Toda anotação de restrição técnica em memória deve carregar a data de registro (YYYY-MM-DD).
  • O código-fonte real, as configurações vigentes (settings.json, .env), os schemas e os arquivos normativos (memory/SPEC.md, memory/0X-*.md) possuem autoridade absoluta sobre anotações de memórias passadas. Se uma restrição mudar no projeto, a anotação antiga em memória deve ser invalidada e atualizada.

🧯 Árvore compartilhada: o que conferir antes de cada commit

Outro agente pode trocar a branch da árvore e deixar arquivos em stage sem aviso. Antes de todo commit numa árvore que não é só sua:

git branch --show-current          # é a branch em que você pretende commitar?
git diff --cached --name-only      # há stage que não é seu?

Se a branch não for a esperada, ou houver stage alheio, não commite na árvore. Monte o commit por índice separado, sem tocar nos arquivos nem na branch:

export GIT_INDEX_FILE="$TEMP/idx-meu-lote"
git read-tree origin/main
git add -- <caminho-1> <caminho-2>
commit=$(git commit-tree "$(git write-tree)" -p origin/main -F mensagem.txt)
unset GIT_INDEX_FILE
git push origin "$commit:refs/heads/main"

Arquivo compartilhado (pages.json, índices do MDD) entra nesse commit como "versão da main mais as minhas entradas", nunca como a cópia da árvore, que carrega o trabalho do outro.

Proibido em árvore compartilhada

  • git checkout -- <arquivo> e git restore <arquivo>: apagam alteração sem commit de qualquer lote, não só a sua edição. Para desfazer a própria mudança, faça a edição inversa.
  • git reset que mova a branch, git stash e git clean.
  • git add -N e qualquer git add sem lista de caminhos.

Dois agentes no mesmo arquivo-fonte

Quando dois lotes precisam escrever no mesmo arquivo de conteúdo, separe por arquivo (um canal, uma pasta) e deixe o gerador juntar. Quando não der, a ferramenta de edição relê o arquivo no instante de gravar e troca só os blocos que são seus.

Deixe um aviso onde o outro vai ler

Coordenação entre agentes é escrita na requisição do outro lote (um bloco "Coordenação", com data e autor), não só dita no chat.


🧾 Antes de afirmar que algo é pré-existente

Falha de teste "que já existia" precisa de prova: rode o mesmo teste sem a sua mudança, ou aponte o lote em que a falha foi registrada. Sem isso, ela é sua até prova em contrário.

MDD, links externos e reserva via git ls-remote (BL-028)

Na matriz conn2flow-ai-workspace e nos satélites migrados, use memory/; leia 00-baseline-architecture.md, 01-general-memory.md e 02-policy.md e navegue pelos index.md. As skills de governança usam exclusivamente seus nomes MDD; boilerplates legados exigem migração explícita. Não execute ai:archive-sdd sobre memory/ sem suporte explícito no CLI. O teto de dez decisões/validações exige verificação própria, não se presume pela saída do comando.

CURRENT.md pode apontar para requisição externa: resolva o link contra a origem, identifique repositório/raiz e leia a aprovação lá. Não crie cópia fictícia local nem execute no repo incorreto. Reparadores só reescrevem caminhos internos; links que saem do repositório são classificados e preservados. Se ferramenta legada rejeitar o link externo, registre a incompatibilidade e não remova o ponteiro só para conseguir PASS.

Antes de reservar número novo, consulte refs com git ls-remote --heads origin para todas as branches envolvidas, fetch das refs relevantes e confira a sequência incluindo arquivos arquivados. Código de saída de grep encadeado não prova reserva nem ausência remota. Crie o intake com caminhos explícitos, faça o push autorizado e confira novamente a ref exata via git ls-remote; em rejeição ou movimento concorrente, releia a sequência e resolva a colisão sem force push. ls-remote é verificação, não lock atômico por si só; o push condicionado à ref anterior e a conferência da reserva são a garantia. Nesta entrega REQ-067 já está reservada: não reserve novo número.

REQ-077 — Pipeline, worktrees e preservação (DEC-136)

  • Projeto: ./c2f project:deploy <id> é o padrão (95% dos casos). Core: ./c2f manager:update-all. ./c2f project:update-all <id> é proibido na rotina de projeto; permitido exclusivamente em lote que altera Core e projeto simultaneamente.
  • Antes de deploy, confira git branch --show-current e git status --short na origem; não publique trabalho alheio/inacabado. Confira o destino e sua autorização. Categoria B (skills/documentação/testes/memória): somente checks locais, sem deploy. Execução sequencial, foreground, logs e locks continuam obrigatórios.
  • Worktrees por conveniência são proibidas. Só criar com concorrência multi-agente comprovada no mesmo repositório; em dúvida, consultar o humano antes. Registre raiz original, caminho temporário e concorrência na requisição e lote. Ao concluir/homologar, audite trabalho único, integração na main e junctions, então git worktree remove <caminho> e git worktree prune. Nunca use força para destruir trabalho não integrado; preserve e reporte impedimentos.
  • DEC-136: manter por padrão; nada é removido (arquivo, status='D', DELETE) sem confirmação explícita do operador humano. Retirada vira choque pendente; --confirmar-retirada só quando pedido pelo operador. Fonte incompleta não autoriza retirada.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.