speccycle 1.0.0__tar.gz

speccycle-1.0.0/LICENSE

@@ -0,0 +1,100 @@
+Copyright (c) 2026 Spec-Cycle
+
+Spec-Cycle is licensed under the Elastic License 2.0 (ELv2), reproduced below.
+The licensor is Spec-Cycle and the software is the Spec-Cycle client
+(the "speccycle" package, including its CLI, web dashboard, agent prompts,
+workflows, templates and checkpoints).
+
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

speccycle-1.0.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE README.md pyproject.toml
+graft src/speccycle
+prune tests
+prune docs
+global-exclude __pycache__ *.py[cod] *.log .env .env.*

speccycle-1.0.0/PKG-INFO

@@ -0,0 +1,436 @@
+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.