Metadata-Version: 2.4
Name: speccycle
Version: 1.0.0
Summary: Spec-Cycle - Spec-Driven Development orchestrated by Intelligent Agents: 8 phases, approval gates and versioned artifacts in the repository
Author-email: Marcelo Pelegrini <mlpelegrini@gmail.com>
License-Expression: Elastic-2.0
Project-URL: Homepage, https://spec-cycle.com
Project-URL: Documentation, https://github.com/mlpelegrini/speccycle/blob/main/docs/manual-do-client.md
Project-URL: Repository, https://github.com/mlpelegrini/speccycle
Project-URL: Issues, https://github.com/mlpelegrini/speccycle/issues
Keywords: spec-driven-development,sdd,bdd,gherkin,claude-code,claude-agent-sdk,ai-agents,developer-tools
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: Portuguese (Brazilian)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: claude-agent-sdk>=0.1.0
Provides-Extra: antigravity
Requires-Dist: google-antigravity>=0.1.3; extra == "antigravity"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Dynamic: license-file

<p align="center">
  <img alt="Spec-Cycle" src="https://raw.githubusercontent.com/mlpelegrini/speccycle/main/src/speccycle/web/assets/brand/logo-light.svg" width="440">
</p>

> **Especifique. Aprove. Avance.** — Spec-Driven Development orquestrado pelo Claude Code.

> 📘 Manual completo de uso do client: [docs/manual-do-client.md](https://github.com/mlpelegrini/speccycle/blob/main/docs/manual-do-client.md)
>
> 🚀 Para mantenedores, o passo a passo de publicação no PyPI: [docs/howto-publicar-pypi.md](https://github.com/mlpelegrini/speccycle/blob/main/docs/howto-publicar-pypi.md)

O Spec-Cycle organiza o trabalho em 8 fases sequenciais — Discovery → Intent → Behavior → Blueprint → Breakdown → Build → Quality → Learning — orquestradas pelo Claude Code (via Claude Agent SDK).

O `scycle init` instala o vocabulário do framework no projeto:

- **Subagents** em `.claude/agents/` — um por agente do Spec-Cycle, com permissões mínimas por papel (fases de especificação não executam código; Build e Quality sim);
- **Slash commands** em `.claude/commands/scycle/` — um por fase (+ foundation);
- **Hooks de quality gate** em `.claude/settings.json` — bloqueiam a transição de fase sem o artefato anterior aprovado e verificam a consistência do diff contra a spec durante o Build.

---

## Pré-requisitos

- Python 3.10 ou superior
- pip

Para verificar:

```bash
python --version
pip --version
```

---

## Instalação

### Opção 1 — direto do repositório (recomendado para testar)

```bash
# Clone o repositório
git clone https://github.com/mlpelegrini/speccycle.git
cd speccycle

# Instale em modo editável (alterações no código refletem imediatamente)
pip install -e .
```

### Opção 2 — instalação global via pip

```bash
pip install speccycle
```

Após a instalação, o comando `scycle` estará disponível no terminal:

```bash
scycle --version
# Spec-Cycle 1.0.0
```

### Dados enviados à plataforma

O client conversa com a plataforma Spec-Cycle (`identity.spec-cycle.com`) para
validar a chave da organização e registrar o andamento das voltas. O que sai da
máquina:

- **Identificação:** e-mail, nome e organização do perfil conectado, um
  `project_id` derivado do remote git e um `machine_id` anônimo.
- **Eventos da volta:** nome e descrição da volta, fase em andamento, tempo
  decorrido e tokens consumidos por fase, além da versão do client e do sistema
  operacional.

O que **não** sai da máquina: conteúdo de artefatos, código-fonte, prompts e
respostas dos agentes.

Para desligar o envio de eventos, defina `SPEC_CYCLE_TELEMETRY=0`. O comando
`scycle telemetry` mostra o estado da fila local e o que está pendente.

---

## Como usar

### 1. Inicializar um projeto

Dentro da pasta do seu projeto (ou em uma nova pasta):

```bash
# Na pasta atual
scycle init --here

# Ou em uma nova pasta
scycle init meu-projeto
cd meu-projeto
```

Isso cria a seguinte estrutura:

```
.speccycle/
  agents/          # prompts dos agentes por fase
  workflows/       # guias de workflow
  templates/       # templates dos artefatos
  checkpoints/     # critérios de pronto entre fases
  knowledge/
    learnings/     # aprendizados acumulados entre ciclos
cycles/            # aqui ficam as voltas de desenvolvimento
```

### 2. Abrir o dashboard web

```bash
scycle start
```

Acesse `http://127.0.0.1:8473` no navegador.

O cliente abre na **tela de conexão**: e-mail de trabalho + chave da organização
(criada em *Organização → API keys*, na plataforma). A chave vai para o cofre do
sistema operacional — Keychain no macOS, Secret Service no Linux, DPAPI no
Windows — e o perfil da sessão fica no diretório de configuração do usuário.
Nada disso entra no repositório. O botão **Sair**, no rodapé do sidebar, apaga
os dois.

Depois de conectar, o **Wizard da Foundation** pede as escolhas de stack
(linguagem, arquitetura e cloud).

Para usar uma porta diferente:

```bash
scycle start --port 9000
```

### 3. Criar uma nova volta (ciclo)

Pelo dashboard, digite o nome da feature no campo "Nova volta", descreva em uma
linha o que ela entrega e clique em **Nova volta**.

Ou pela linha de comando:

```bash
scycle new "Autenticação de usuários" --desc "Login com a chave da organização"
# Cria: cycles/001-autenticacao-de-usuarios/
```

O nome e a descrição acompanham os eventos da volta enviados à plataforma —
junto do andamento das fases, tempo e tokens consumidos. Nenhum conteúdo de
artefato ou de código sai da máquina; `scycle telemetry` mostra o que está
pendente de envio.

### 4. Executar as fases no Claude Code

Cada fase tem um comando de prompt correspondente:

```
/scycle:discovery    # fase 1 — problema e contexto
/scycle:intent       # fase 2 — critérios de sucesso
/scycle:behavior     # fase 3 — cenários Gherkin
/scycle:blueprint    # fase 4 — arquitetura e contratos
/scycle:breakdown    # fase 5 — incrementos com critérios de aceite
/scycle:build        # fase 6 — construção com TDD
/scycle:quality      # fase 7 — execução dos cenários e code review
/scycle:learn        # fase 8 — aprendizados para a próxima volta
```

O dashboard acompanha o progresso automaticamente (atualiza a cada 5 segundos) conforme os artefatos de cada fase são gerados na pasta `cycles/NNN-nome/`.

Também é possível executar as fases direto pelo dashboard (botão **▶ rodar**): o servidor abre uma sessão com o Claude Agent SDK e transmite os eventos em tempo real. Requer a variável de ambiente `ANTHROPIC_API_KEY` (veja `.env.example`).

### 5. Aprovar os gates

Nenhuma fase começa sem a anterior aprovada. Quando uma fase conclui, aprove o gate pelo dashboard (botão **aprovar gate**) ou pela CLI:

```bash
python -m speccycle.gates approve discovery
```

O hook de gate do Claude Code bloqueia `/scycle:<fase>` enquanto o artefato anterior não existir ou não estiver aprovado.

---

## As 8 fases do ciclo

O Spec-Cycle impõe uma sequência deliberada: as fases de **especificação** (1–5) precisam estar aprovadas antes que qualquer linha de código seja escrita nas fases de **execução** (6–7). Isso garante que o código sempre reflita uma decisão consciente, não uma suposição.

Cada fase termina com um **gate**: o artefato produzido é revisado e aprovado (pelo desenvolvedor ou pelo time) antes da fase seguinte começar. O hook do Claude Code bloqueia o comando da próxima fase enquanto o gate anterior não tiver sido aprovado.

---

### Fase 0 — Foundation

**Objetivo:** selar as decisões estruturais do projeto antes de qualquer volta de desenvolvimento. A Foundation não é uma fase recorrente — ela é executada uma única vez na inicialização do projeto e serve de contexto permanente para todos os agentes de todas as voltas.

**O que o agente faz:** conduz um diálogo guiado para capturar a linguagem principal, a arquitetura adotada, a plataforma de cloud/infraestrutura e princípios inegociáveis do projeto (padrões de código, regras de segurança, convenções de time).

**Artefato:** `.speccycle/knowledge/foundation.md` — consultado automaticamente por todos os agentes antes de gerar qualquer artefato.

**Gate:** foundation selada → dashboard libera a criação de voltas.

---

### Fase 1 — Discovery

**Objetivo:** entender profundamente o problema antes de propor qualquer solução. A Discovery é deliberadamente livre de decisões técnicas — seu único produto é clareza sobre o contexto.

**O que o agente faz:**
- Pesquisa o estado atual do sistema (lê código, documentação, histórico de issues)
- Mapeia o problema central, os usuários afetados e o impacto esperado
- Identifica restrições conhecidas, riscos e hipóteses que precisam ser validadas
- Lê os `learnings.md` de voltas anteriores para não repetir erros já documentados

**Artefato:** `discovery.md` — contém o problema mapeado, contexto técnico e de negócio, hipóteses levantadas e perguntas ainda abertas.

**Gate:** o desenvolvedor confirma que o problema está descrito com precisão suficiente para escrever critérios de sucesso mensuráveis.

---

### Fase 2 — Intent

**Objetivo:** converter o entendimento da Discovery em critérios de sucesso concretos e mensuráveis, sem ainda decidir como serão implementados.

**O que o agente faz:**
- Define o que significa "feito" para esta volta (critérios de aceite de negócio)
- Estabelece o que está **fora de escopo** (tão importante quanto o que está dentro)
- Lista restrições não-funcionais relevantes (performance, segurança, compatibilidade)
- Não cita tecnologias, frameworks ou estruturas de dados — essas decisões são da Blueprint

**Artefato:** `intent.md` — lista de critérios de sucesso numerados, escopo delimitado e restrições. Cada critério deve ser testável.

**Gate:** todo critério de sucesso é verificável e terá pelo menos um cenário Gherkin na fase seguinte.

---

### Fase 3 — Behavior

**Objetivo:** traduzir cada critério de sucesso da Intent em cenários Gherkin executáveis. Os cenários são o **contrato** entre spec e código — se o cenário passa, o critério foi atendido.

**O que o agente faz:**
- Escreve arquivos `.feature` com cenários no formato `Dado / Quando / Então`
- Cobre o caminho feliz e os casos de borda relevantes para cada critério
- Garante cobertura total: nenhum critério da Intent sem ao menos um cenário
- Usa linguagem de domínio (não de implementação) para que os cenários sejam legíveis por qualquer stakeholder

**Artefato:** `behaviors/*.feature` — um ou mais arquivos Gherkin, um por área funcional ou por critério de sucesso.

**Gate:** cada critério numerado na Intent tem cobertura de cenário; nenhum cenário pressupõe uma implementação específica.

---

### Fase 4 — Blueprint

**Objetivo:** decidir **como** a feature será construída — arquitetura, contratos de API, modelo de dados e decisões técnicas com suas justificativas. É aqui que tecnologias e padrões entram pela primeira vez.

**O que o agente faz:**
- Projeta a arquitetura da solução respeitando a Foundation (stack, padrões e restrições do projeto)
- Define contratos de API ou interfaces entre componentes (endpoints, assinaturas de função, esquemas)
- Documenta decisões técnicas relevantes como Architecture Decision Records (ADRs) embutidos
- Identifica dependências externas e pontos de integração
- Descreve o modelo de dados e as migrações necessárias, se aplicável

**Artefato:** `blueprint.md` — diagrama textual da arquitetura, contratos de interface, ADRs e qualquer decisão de design que afete a implementação.

**Gate:** a Blueprint é consistente com a Foundation; os contratos cobrem todos os cenários da Behavior; nenhuma decisão relevante ficou implícita.

---

### Fase 5 — Breakdown

**Objetivo:** decompor a Blueprint em incrementos de implementação pequenos, sequenciados e independentes — cada um com seus próprios critérios de aceite derivados dos cenários Gherkin.

**O que o agente faz:**
- Divide o trabalho em incrementos de 1–4 horas de implementação cada
- Ordena os incrementos respeitando dependências técnicas (ex.: modelo de dados antes da API)
- Para cada incremento: define o que deve ser implementado, quais cenários Gherkin ele fecha e como verificar que está pronto
- Identifica quais incrementos podem ser desenvolvidos em paralelo

**Artefato:** `breakdown.md` + `increments/NNN-nome.md` — lista de incrementos com critérios de aceite individuais e ordem de execução.

**Gate:** o somatório dos incrementos cobre todos os cenários da Behavior; nenhum incremento é grande demais para ser construído e verificado em uma única sessão de Build.

---

### Fase 6 — Build

**Objetivo:** implementar cada incremento do Breakdown seguindo TDD guiado pelos cenários Gherkin. O código só avança quando os cenários do incremento passam.

**O que o agente faz:**
- Processa os incrementos na ordem definida no Breakdown, um de cada vez
- Para cada incremento: escreve ou adapta os testes derivados dos cenários → implementa o mínimo para passar → refatora
- Respeita os contratos da Blueprint: não inventa interfaces, não muda o modelo de dados sem documentar
- Registra decisões de implementação relevantes e desvios justificados no log

**Artefato:** `build-log.md` — registro de cada incremento: o que foi implementado, quais testes passaram, e qualquer desvio da Blueprint com justificativa.

**Gate:** todos os incrementos estão implementados; os testes dos cenários cobertos passam; nenhum desvio da Blueprint está sem justificativa registrada.

---

### Fase 7 — Quality

**Objetivo:** verificar que o que foi construído no Build corresponde ao que foi especificado na Behavior — e que a qualidade geral do código está adequada.

**O que o agente faz:**
- Executa a suíte de testes completa e verifica que todos os cenários Gherkin da volta passam
- Faz code review do diff da volta: correctness, segurança, performance e aderência à Foundation
- Verifica consistência entre o código produzido e os contratos da Blueprint
- Aponta regressões ou cenários que passaram na Behavior mas falharam na execução real
- Produz um relatório com o resultado de cada cenário e os achados do review

**Artefato:** `quality-report.md` — resultado dos cenários (✓ passou / ✗ falhou), achados do code review categorizados por severidade e lista de itens que precisam de correção antes da aprovação.

**Gate:** todos os cenários da Behavior passam; os achados críticos e altos do review foram endereçados; nenhuma regressão identificada sem plano de resolução.

---

### Fase 8 — Learning

**Objetivo:** extrair aprendizados concretos desta volta para que a próxima comece com mais contexto e menos fricção. É o mecanismo de melhoria contínua do Spec-Cycle.

**O que o agente faz:**
- Revisa os artefatos de toda a volta (do discovery.md ao quality-report.md)
- Identifica o que funcionou bem e deve ser repetido
- Documenta o que não funcionou e como deveria ter sido feito
- Registra surpresas: o que a Discovery não antecipou, o que a Blueprint errou, o que o Build revelou
- Consolida os aprendizados em um formato que o agente de Discovery da próxima volta conseguirá consumir diretamente

**Artefato:** `learnings.md` — lista estruturada de aprendizados com contexto suficiente para serem acionáveis na próxima volta.

**Gate:** os aprendizados são específicos e acionáveis (não genéricos); a volta está encerrada e o dashboard marca todas as 8 fases como concluídas.

---

## Integração opcional com o GitHub

Com um remote GitHub e a variável `GITHUB_TOKEN` definida, as sessões de agente ganham o servidor MCP do GitHub e espelham o estado: volta ↔ issue (label `speccycle`), fase ↔ branch/PR `cycle/NNN-nome/fase`, gate ↔ review. Os arquivos locais continuam sendo a fonte de verdade — sem token, tudo funciona offline.

---

## API de orquestração

O servidor local expõe a API que o dashboard (e futuras interfaces) consome:

| Rota | Função |
|---|---|
| `GET /api/state` | Estado das fases, derivado dos arquivos da volta |
| `POST /api/sessions` · `POST /api/sessions/{id}/messages` · `GET /api/sessions/{id}/stream` (SSE) | Iniciar fase, conversar com o agente, stream de eventos |
| `POST /api/gates/approve` | Registrar aprovação de gate |
| `GET/PUT/DELETE /api/config/...` | CRUD de toda a configuração do Claude Code (subagents, commands, hooks/permissões, servidores MCP, CLAUDE.md), com validação de esquema e commit automático |

Exemplo de ponta a ponta em [`examples/run_cycle.py`](examples/run_cycle.py).

---

## Executar os testes

```bash
pip install -e ".[test,antigravity]"   # pytest, pytest-asyncio e o SDK do Antigravity
python -m pytest tests/ -q
```

Sem o extra `antigravity`, os testes do runtime Antigravity são pulados.

---

## Estrutura de uma volta

```
cycles/001-autenticacao-de-usuarios/
  cycle.json          # metadados (nome, data de criação)
  discovery.md        # artefato da fase Discovery
  intent.md           # artefato da fase Intent
  behaviors/          # cenários Gherkin (.feature)
  blueprint.md        # artefato da fase Blueprint
  breakdown.md        # decomposição em incrementos
  increments/         # arquivos de incremento individuais
  contracts/          # contratos de API / interfaces
  build-log.md        # log da fase Build
  quality-report.md   # relatório da fase Quality
  learnings.md        # aprendizados da volta
```

---

## Licença

Distribuído sob a [Elastic License 2.0 (ELv2)](LICENSE). Copyright 2026 Spec-Cycle.

Em resumo, você pode usar, copiar, modificar e redistribuir o client, inclusive
em uso comercial dentro da sua organização. Você **não** pode:

- oferecer o Spec-Cycle a terceiros como serviço gerenciado ou hospedado;
- mover, alterar, desabilitar ou contornar a exigência da chave da plataforma,
  nem remover funcionalidades protegidas por ela;
- remover ou ocultar os avisos de licença, copyright e marca.

O texto completo, em inglês, está em [LICENSE](LICENSE). A ELv2 não é uma
licença open source segundo a definição da OSI; o código-fonte fica disponível
para leitura e adaptação sob os termos acima.
