Migrar Layout

Visão Geral

O agent-skills upstream mantém os arquivos de trabalho na raiz do projeto. A equipe os mantém em .claude-work/ (veja a tabela de Caminhos nas substituições da equipe). Esta skill move um projeto em andamento para o layout da equipe em um único commit. Cada arquivo mantém seu histórico git. As caixas de seleção das tarefas acompanham os arquivos, de modo que o trabalho continua de onde parou.

O argumento é o <id> para os arquivos de plano e tarefas, por exemplo /agent-skills-jksim:migrate-layout fl-debug.

Quando Usar

Um projeto tem SPEC.md, tasks/plan.md, tasks/todo.md ou CONSTRAINTS.md em sua raiz.
Um projeto tem tanto arquivos de trabalho raiz quanto .claude-work/.

Não use para um novo projeto. A fase de especificação escreve em .claude-work/ desde o início.

Processo

1. Verificar o estado inicial

Pare e informe o usuário quando uma das seguintes condições for verdadeira:

A pasta não é um repositório git.
git status --porcelain --untracked-files=no mostra alterações em arquivos rastreados. Peça ao usuário para commitar ou fazer stash deles primeiro. Arquivos não rastreados podem permanecer: o passo 8 faz stage com git add -u, que nunca os adiciona.
git check-ignore -q .claude-work/spec/SPEC.md é bem-sucedido. Verifique um caminho de arquivo: um padrão como .claude-work/ não corresponde à pasta antes dela existir. Projetos consumidores commitam .claude-work/.

2. Encontrar os arquivos antigos

Procure apenas nestes caminhos, relativos à raiz do projeto:

Caminho antigo	Caminho da equipe
`SPEC.md`, `docs/SPEC.md`	`.claude-work/spec/SPEC.md`
`SPEC-<modulo>.md`	`.claude-work/spec/SPEC-<modulo>.md`
`CAPABILITY-MAP.md`	`.claude-work/spec/CAPABILITY-MAP.md`
`tasks/plan.md`	`.claude-work/tasks/plan-<id>.md`
`tasks/todo.md`	`.claude-work/tasks/todo-<id>.md`
`CONSTRAINTS.md`	`.claude-work/docs/CONSTRAINTS.md`
`docs/ideas/<nome>.md`	`.claude-work/docs/ideas/<nome>.md`
`docs/intent/<topico>.md`	`.claude-work/docs/intent/<topico>.md`
`docs/decisions/`	Permanece. Pergunte (veja passo 4)

Não mexa em spec/. RSpec e outros layouts de teste o utilizam.

Use apenas arquivos que o git rastreia (git ls-files). git mv falha em outros arquivos. Nomeie qualquer arquivo antigo não rastreado ou ignorado e pergunte ao usuário.

Quando nenhum arquivo antigo existir, informe ao usuário que não há nada para migrar. Pare.

3. Obter o `<id>`

Use o argumento. Sem argumento, sugira um id curto em kebab-case a partir do nome do projeto e pergunte ao usuário. Pule esta etapa quando não houver tasks/plan.md ou tasks/todo.md.

4. Mostrar o plano e aguardar aprovação

Mostre uma tabela: caminho antigo, caminho novo. Em seguida, liste cada conflito e pergunte sobre ele:

Destino existe: um arquivo já está no caminho da equipe. Não mova esse arquivo. Pergunte o que fazer.
Duas especificações: tanto SPEC.md quanto docs/SPEC.md existem. Pergunte qual é a especificação.
Outros arquivos em tasks/: mova apenas plan.md e todo.md. Nomeie os outros arquivos.
docs/decisions/ existe: o padrão é mantê-lo, porque um projeto mantém sua própria pasta ADR. Mova para .claude-work/docs/adr/ apenas quando o usuário assim o disser.

Não mova nada até que o usuário aprove a tabela.

5. Mover com `git mv`

Execute git mv <antigo> <novo> para cada arquivo. Crie as pastas de destino primeiro (mkdir -p). Nunca copie e exclua: git mv mantém o histórico. Se tasks/ agora estiver vazia, execute rmdir tasks.

6. Corrigir referências ativas

Pesquise também pelos nomes de arquivo simples, porque um arquivo movido pode nomear seu parceiro sem pasta: git grep -n -E '(^|[^-/A-Za-z0-9_])(plan|todo)\.md'. Exemplo: "detalhe em todo.md" no plano se torna "detalhe em todo-.md".

Uma referência ativa informa ao leitor ou ao agente onde o arquivo está agora. Altere-a:

CLAUDE.md: "SPEC.md: especificação aprovada" se torna ".claude-work/spec/SPEC.md: especificação aprovada".
README.md: [SPEC.md](SPEC.md) se torna [SPEC.md](.claude-work/spec/SPEC.md).
Um link relativo em um arquivo movido: ../SPEC.md no antigo tasks/plan.md se torna ../spec/SPEC.md em .claude-work/tasks/plan-<id>.md.
A linha do ponteiro de restrições em CLAUDE.md.
Outros links relativos em cada arquivo movido. Um arquivo movido está em uma nova profundidade, então um link para um arquivo que não foi movido também quebra. Exemplo: [x](src/a.kt) na raiz SPEC-foo.md se torna [x](../../src/a.kt) em .claude-work/spec/SPEC-foo.md.

Um registro informa o que aconteceu em um momento passado. Deixe-o como está:

Uma entrada de tarefa concluída: "Arquivos: README.md, SPEC.md".
Um log de alterações, uma nota de revisão ou uma mensagem de commit.

Quando você não tiver certeza, deixe o texto e liste-o no passo 7.

7. Mostrar o resultado

Mostre git status, o diff das referências alteradas e uma lista das referências de caminho antigo que você não alterou, com a razão para cada uma.

8. Commitar uma vez

git mv já preparou as movimentações. Prepare as referências editadas com git add -u. Não use git add -A: ele pode adicionar arquivos não relacionados. Faça commit com a mensagem Move working files to .claude-work. Não faça push.

Se um hook rejeitar o commit, pare e relate-o. Não use --no-verify.

9. Relatar o próximo passo

Informe ao usuário quais arquivos foram movidos e quais permaneceram. Se .claude-work/docs/VOCABULARY.md não existir, diga que a próxima fase de especificação o criará (regra 2). Não o crie agora.

Racionalizações Comuns

Racionalização	Realidade
"Copiar é mais simples que `git mv`."	Uma cópia perde o histórico do arquivo. Revisores e `git log --follow` precisam dele.
"Vou atualizar todas as menções de `SPEC.md`."	Registros descrevem o passado. Alterá-los reescreve a história.
"A árvore está só um pouco suja."	Trabalho não commitado acaba no commit de migração. Pergunte ao usuário primeiro.
"O plano é óbvio, então vou pular a aprovação."	O usuário decide o `<id>` e cada conflito. Espere.

Bandeiras Vermelhas

git log --follow não mostra histórico anterior ao commit de migração.
Uma entrada de tarefa concluída ou um log de alterações nomeia um caminho da equipe que não existia na época.
spec/ ou docs/decisions/ foram movidos sem a aprovação do usuário.
Mais de um commit, ou um push.

Verificação

Cada arquivo antigo está em seu caminho da equipe. Nenhum arquivo antigo foi deixado na raiz, exceto aqueles que o usuário optou por manter.
git log --follow <novo caminho> mostra o histórico antigo.
Referências ativas apontam para os caminhos da equipe. Registros permanecem inalterados.
Caixas de seleção de tarefas permanecem inalteradas.
Um commit, Move working files to .claude-work. git status está limpo. Nada foi enviado (push).

jksim/agent-skills-jksim

O que é agent-skills-jksim?

Perguntar na sua IA favorita

Documentação