Introdução ao ClawSpec + OpenSpec: Como automatizar o progresso do projeto de forma contínua, evitando interrupções e intervenções manuais

Dificuldade: Iniciante | Duração: 20 minutos | Resultado: Gerencie todo o fluxo do projeto via OpenSpec na janela de chat, mantendo o AI trabalhando continuamente sem travamentos

---

Público-alvo

Você já está rodando o OpenClaw e começou a usá-lo para tarefas diárias. Durante o uso, você provavelmente encontrou este problema:

Os requisitos foram bem explicados, o agent concordou em começar, mas depois de um tempo você percebe que ele parou, não avançou e está esperando por sua cobrança.

Especialmente em tarefas de longo prazo, mudanças de requisitos ou cenários de "conversar enquanto faz", esse problema é nítido. Você não precisa apenas de uma IA que saiba conversar, mas de um sistema de execução que organize os requisitos, avance continuamente, não dependa de monitoramento humano e possa se recuperar automaticamente.

Este artigo é para quem:

• Já usa o OpenClaw e deseja completar o ciclo completo do projeto (Requisito → Planejamento → Código → Arquivamento) via chat.
• Já teve a experiência de ver o agent estagnar após começar e busca uma solução de execução contínua controlável.
• Tem interesse no fluxo de trabalho OpenSpec e quer integrá-lo diretamente ao OpenClaw.

---

Dependências e Ambiente

Repositório GitHub: https://github.com/bytegh/clawspec

---

Estrutura Completa do Projeto

Estrutura de diretórios do plugin ClawSpec (pós-instalação):

clawspec/
├── index.ts                    # Entrada do plugin
├── src/                       # Código-fonte principal
│   ├── service/               # Camada de serviço
│   ├── watcher/               # Gerenciamento do watcher de segundo plano
│   ├── stores/                # Armazenamento de estado
│   └── hooks/                 # Hooks do OpenClaw
├── skills/                    # Textos de skill OpenSpec (embutidos)
├── test/                      # Casos de teste
├── openclaw.plugin.json       # Configuração do plugin
├── package.json
└── tsconfig.json

Durante a execução, arquivos de gerenciamento serão gerados em cada repo:

<repo>/
├── .openclaw/clawspec/        # Estado de runtime do ClawSpec
│   ├── state.json             # Estado atual do projeto
│   ├── execution-control.json # Controle de execução cs-work
│   ├── execution-result.json  # Resultado da execução
│   ├── worker-progress.jsonl  # Logs de progresso em segundo plano
│   ├── planning-journal.jsonl  # Registro de discussão de requisitos
│   ├── planning-journal.snapshot.json  # Snapshot do journal
│   ├── rollback-manifest.json # Lista de rollback
│   ├── snapshots/             # Linha de base de snapshots de mudança
│   │   └── <change-name>/
│   │       └── baseline/
│   └── archives/              # Mudanças arquivadas
├── openspec/                  # Diretório de especificações OpenSpec
│   └── changes/<change-name>/
│       ├── .openspec.yaml
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/

---

Passo a Passo

Passo 1: Instalar o Plugin ClawSpec

O ClawSpec oferece três métodos de instalação, o primeiro é o recomendado:

Opção A: Via instalador de plugins do OpenClaw (Recomendado)

openclaw plugins install clawspec@latest

Opção B: Via ClawHub CLI

npx clawhub@latest install clawspec

Opção C: Instalação manual via pacote npm (Reserva)

$pkg = npm pack clawspec@latest
openclaw plugins install $pkg

@latest sempre resolverá para a versão mais recente do ClawSpec no npm.

---

Passo 2: Configurar o OpenClaw

Após a instalação, ative o ACP e configure o ClawSpec em ~/.openclaw/openclaw.json:

{
  "acp": {
    "enabled": true,
    "backend": "acpx",
    "defaultAgent": "claude"
  },
  "plugins": {
    "entries": {
      "clawspec": {
        "enabled": true,
        "config": {
          "defaultWorkspace": "~/clawspec/workspace",
          "openSpecTimeoutMs": 120000,
          "watcherPollIntervalMs": 4000
        }
      }
    }
  }
}

Descrição das configurações principais:

Após configurar, reinicie o gateway:

openclaw gateway restart
openclaw gateway status

---

Passo 3: Vincular Workspace e Projeto

O ClawSpec memoriza o workspace por canal de chat. Cada canal pode ser vinculado a um diretório raiz de projeto diferente.

/clawspec workspace "D:\clawspec\workspace"
/clawspec use "demo-app"

Resultados esperados:

• O ClawSpec salva o caminho no canal atual.
• Se o diretório demo-app não existir, ele será criado.
• Na primeira seleção do repo, openspec init será executado automaticamente.

---

Passo 4: Criar uma Change OpenSpec

/clawspec proposal add-login-flow "Build login and session handling"

Isso executa três ações:

1. Cria o scaffold padrão em openspec/changes/add-login-flow/.
2. Gera um snapshot baseline dos arquivos rastreados.
3. Define o contexto do chat para a mudança ativa add-login-flow.

---

Passo 5: Descrever Requisitos no Chat

Descreva seus requisitos normalmente:

Suporte login com e-mail e senha.
Precisa de refresh token.
Access token expira em 15 minutos.

O ClawSpec adicionará isso ao planning-journal.jsonl. Neste estágio, os artefatos não são atualizados e o código não é escrito ainda — é apenas registro.

Para desconectar o chat do registro mas manter o progresso do watcher:

cs-detach

Para reconectar:

cs-attach

---

Passo 6: cs-plan, Sincronização de Planejamento Visível

Quando os requisitos estiverem claros, execute:

cs-plan

O ClawSpec atualizará os seguintes artefatos diretamente na janela de chat:

• proposal.md — Proposta do projeto
• design.md — Design da arquitetura
• specs/ — Especificações detalhadas
• tasks.md — Lista de tarefas

---

Passo 7: cs-work, Iniciar Implementação Contínua

Após o planejamento, inicie a implementação:

cs-work

O cs-work não escreve código diretamente na janela principal. Ele segue este fluxo:

1. Valida se o planejamento está limpo (impede execução se houver journal sujo).
2. Ativa o watcher via execution-control.json.
3. O watcher inicia uma sessão de worker ACP via acpx.
4. O worker executa tarefa por tarefa de acordo com tasks.md.
5. O progresso é enviado de volta ao chat pelo watcher.

---

Passo 8: Rastreamento e Recuperação de Progresso

Esta é a capacidade central do ClawSpec — o worker continua automaticamente após o reinício do gateway.

O gerenciador do watcher irá:

• Escanear projetos ativos.
• Tentar assumir sessões de worker ACP sobreviventes.
• Se o worker antigo morreu, inicia um novo mantendo o progresso das tarefas.

Verificar status do worker:

/clawspec worker status

---

Passo 9: Arquivamento e Encerramento

Quando todas as tarefas terminarem, limpe a mudança ativa:

/clawspec archive

Isso valida a integridade, move a mudança para archives/ e limpa o estado do chat.

---

Solução de Problemas Comuns

1. cs-work solicita "planning sync"

Causa: O planning journal tornou-se dirty (novos requisitos após o snapshot).
Solução: Execute cs-plan e depois cs-work.

2. Watcher indica que ACPX está indisponível

Verifique se acp.enabled está como true e se acp.backend é acpx. Se necessário, reinicie o gateway.

3. Chat comum poluiu o planning journal

Use cs-detach para separar conversas informais do registro de requisitos do projeto.

4. Worker conectado mas sem iniciar tarefas

Isso indica que o worker está processando prompts de implementação ou lendo artefatos. Verifique o status detalhado com /clawspec worker status.

5. Erro "stdin is not a terminal"

Causa: Configurações personalizadas de agent no ACPX.
Solução: Execute /clawspec doctor fix ou limpe o objeto agents em ~/.acpx/config.json.

6. /clawspec use indica mudança inacabada

O ClawSpec não permite abandonar mudanças ativas silenciosamente. Escolha entre /clawspec continue, /clawspec archive ou /clawspec cancel.