up-cc 0.3.3 → 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lex Christopherson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -33,6 +33,8 @@ Sem UP, voce pede algo ao assistente e torce pra dar certo. Com UP:
 - **Agentes especializados** rodam em paralelo para pesquisa, planejamento, execucao e verificacao
 - **Tarefas rapidas** tem o mesmo rigor sem a cerimonia completa
 - **Detecta projetos existentes** e adapta o fluxo automaticamente (brownfield)
+- **Modo builder** constroi projetos inteiros autonomamente (briefing → sistema pronto + testado)
+- **UX tester** navega o sistema como usuario real e implementa melhorias automaticamente
 
 ## Instalacao
 
@@ -63,56 +65,40 @@ Apos instalar, reinicie o Claude Code e digite `/up:ajuda` para ver todos os com
 
 ### 1. Inicializando um projeto
 
-O UP tem duas formas de comecar, dependendo do que voce precisa.
+O UP funciona tanto para projetos novos (greenfield) quanto para codebases existentes (brownfield). A deteccao e automatica.
 
-#### Adocao leve — `/up:iniciar` (recomendado para projetos existentes)
-
-```
-/up:iniciar
-```
-
-O UP vai:
-1. Detectar automaticamente a stack, estrutura e features do seu projeto
-2. Criar `PROJECT.md` documentando o que existe — **sem fazer perguntas**
-3. Criar `config.json` com valores padrao
-4. Parar
-
-Sem questionario, sem requisitos, sem roadmap. Voce vai construindo incrementalmente conforme precisa:
-
-```
-/up:iniciar                    # Registra projeto, cria PROJECT.md
-/up:mapear-codigo              # Analise profunda do codebase (opcional)
-/up:melhorias                  # Descobre o que melhorar
-/up:planejar-fase 1            # Quando tiver algo para implementar
-```
-
-Ideal quando voce quer adotar o UP num projeto existente sem definir tudo de cara.
-
-#### Pipeline completo — `/up:novo-projeto`
+#### Projeto novo (do zero)
 
 ```
 /up:novo-projeto
 ```
 
 O UP vai:
-1. Perguntar "O que voce quer construir?" (greenfield) ou "O que voce quer fazer com esse codigo?" (brownfield)
+1. Perguntar "O que voce quer construir?"
 2. Fazer perguntas de acompanhamento para entender o projeto
 3. Opcionalmente pesquisar o ecossistema do dominio (stack, features, armadilhas)
 4. Definir requisitos interativamente, agrupados por categoria
 5. Gerar ROADMAP.md com fases, criterios de sucesso e rastreabilidade
 6. Criar PROJECT.md, STATE.md e config.json
 
-Ideal quando voce ja sabe o que quer fazer e quer o pipeline completo de cara. Funciona tanto para projetos novos (greenfield) quanto existentes (brownfield) — a deteccao e automatica.
+Ao final voce tera um `.plano/` completo pronto para o pipeline de fases.
 
-#### Mapeamento de codebase
-
-Ambos os caminhos se beneficiam do mapeamento profundo do codebase:
+#### Projeto existente (brownfield)
 
 ```
-/up:mapear-codigo
+/up:mapear-codigo         # Opcional, mas recomendado
+/up:novo-projeto          # Detecta brownfield automaticamente
 ```
 
-Produz 7 documentos em `.plano/codebase/`:
+Se voce tem codigo no diretorio, o UP detecta e adapta:
+- Carrega o mapeamento do codebase (se `/up:mapear-codigo` ja rodou)
+- Pergunta "O que voce quer **fazer** com esse codigo?" em vez de "O que voce quer construir?"
+- Infere requisitos **validados** do codebase existente (features que ja funcionam)
+- Separa seus novos objetivos como requisitos **ativos**
+- Pesquisa foca em tecnologias **novas**, nao nas que voce ja usa
+- Todo o pipeline downstream (discutir, planejar, executar) recebe contexto do codebase
+
+O `/up:mapear-codigo` produz 7 documentos em `.plano/codebase/`:
 
 | Documento | Conteudo |
 |-----------|----------|
@@ -124,7 +110,14 @@ Produz 7 documentos em `.plano/codebase/`:
 | TESTING.md | Infraestrutura de testes, cobertura |
 | CONCERNS.md | Divida tecnica, areas frageis, seguranca |
 
-Esses documentos alimentam automaticamente o restante do pipeline (discutir, planejar, executar).
+Esses documentos alimentam automaticamente o restante do pipeline.
+
+#### Reinicializando um projeto
+
+Se voce ja tem um `.plano/PROJECT.md` e roda `/up:novo-projeto` novamente, o UP oferece:
+- **Revisar e atualizar** — Atualizar com novos objetivos
+- **Recomecar do zero** — Recriar tudo
+- **Cancelar** — Manter como esta
 
 ### 2. O pipeline de fases
 
@@ -293,7 +286,143 @@ O UP:
 | Commit Docs | sim | Commitar documentos de planejamento automaticamente |
 | Auto-Advance | nao | Encadear estagios automaticamente |
 
-### 8. Manutencao
+### 8. Modo Builder
+
+Construa um projeto inteiro autonomamente. Voce da o briefing, responde perguntas criticas, e o UP faz tudo sozinho.
+
+```
+/up:modo-builder "Sistema financeiro pessoal com Supabase, auth, dashboard de gastos e metas"
+/up:modo-builder --light "Adicionar factory de usuarios com roles"
+```
+
+**Dois niveis:**
+- **Full (padrao):** Pipeline completo — pesquisa, polish, UX review, delivery
+- **Light (`--light`):** Pipeline enxuto — planeja, constroi, testa. ~50% menos tokens.
+
+O builder full passa por **5 estagios** automaticamente:
+
+1. **Intake** — Analisa briefing, pergunta so o critico (credenciais, APIs). Dashboard inicia em http://localhost:4040.
+2. **Arquitetura** — Pipeline de 3 agentes especializados + validacao:
+   - **Product Analyst** — Pesquisa concorrentes reais, define personas, lista features obrigatorias do mercado
+   - **System Designer** — Define modulos, roles, permissoes, schema de banco, rotas. Aplica 10 blueprints de producao + requisitos universais (70+ checks)
+   - **Architect** — Gera PROJECT.md, REQUIREMENTS.md (50-100 requisitos, 5 camadas), ROADMAP.md
+   - **Requirements Validator** — 13 checks automaticos. Se score < 75%: arquiteto refaz antes do build
+3. **Build** — Para cada fase com ciclo RARV (Reason → Act → Reflect → Verify):
+   - **Planejar** (Reason) — planejador cria planos executaveis
+   - **Executar** (Act) — executores especialistas (frontend/backend/database) com verificacao funcional por task (curl endpoints, Playwright em paginas). Cria dados de teste automaticamente.
+   - **Reflect** — Code Reviewer revisa contra production-requirements ANTES da verificacao
+   - **Verificar** (Verify) — verificador + teste E2E com Playwright
+   - **Regra 5** — Auto-corrige desalinhamento frontend↔backend (URL, payload, response shape)
+4. **Quality Gate Loop** — Score composto de 7 dimensoes (funcionalidade, blind validation, E2E, UX, responsividade, codigo, completude). Inclui:
+   - **Blind Validator** — testa como usuario final SEM ler codigo (20% do score)
+   - Melhorias de codigo (3 auditores)
+   - UX Tester (navegacao real, 6 dimensoes)
+   - Mobile First (responsividade sem quebrar desktop)
+   - Security Review (OWASP Top 10)
+   - QA Agent (testes automatizados)
+   - DevOps (Dockerfile, CI/CD, .env.example, seed data)
+   - Technical Writer (README, API docs, CHANGELOG)
+   - Corrige e re-avalia ate score >= 9.0/10 (max 5 ciclos)
+5. **Entrega** — DELIVERY.md com quality score, metricas, screenshots, testes pendentes de credenciais
+
+**Funciona em dois modos (deteccao automatica):**
+- **Greenfield** (sem codigo): cria tudo do zero
+- **Brownfield** (codigo existente): mapeia codebase, adiciona fases ao roadmap existente
+
+**Features do builder:**
+- **33 agentes especializados** trabalhando em pipeline
+- **Verificacao funcional por task** — cada task e testada em runtime (curl/Playwright) antes de commitar
+- **Crash recovery** — LOCK.md permite retomar de onde parou
+- **Reassessment** — re-avalia roadmap apos cada fase
+- **Capture de insights** — agentes salvam descobertas para triagem no final
+- **Dados de teste automaticos** — cria usuarios e seed data no banco
+- **Dashboard** — acompanhe em tempo real em http://localhost:4040
+
+**Modo Light (`--light`):**
+- Pula pesquisa, polish, UX tester, ideias, delivery, reassessment, captures
+- Mantém: planejar, executar, verificar, teste E2E com Playwright
+- Mini-scan do codebase (inline, sem agentes mapeadores)
+- Estrutura inline (sem agente arquiteto)
+- Ideal para features medias em projetos existentes
+
+**Defaults personalizaveis:**
+
+Crie `~/.claude/up/builder-defaults.md` com suas preferencias de stack, design e padroes. O builder usa como base para decisoes nao especificadas no briefing.
+
+### 9. UX Tester
+
+Navega o sistema como usuario real, avalia a experiencia e implementa melhorias automaticamente.
+
+```
+/up:ux-tester               # Navegar, avaliar e implementar melhorias
+/up:ux-tester --no-fix      # Apenas relatorio, sem implementar
+/up:ux-tester 3000          # Especificar porta
+```
+
+O UX tester abre o browser via Playwright e:
+1. Define **3 personas** (usuario novo, frequente, apressado/mobile)
+2. Navega cada fluxo como cada persona
+3. Avalia **6 dimensoes**: clareza, eficiencia, feedback, consistencia, acessibilidade, performance
+4. Gera relatorio com score por dimensao e issues priorizadas
+5. **Implementa melhorias automaticamente** — desde ajustes de texto ate componentes novos e reestruturacao de fluxo
+6. Verifica cada mudanca via Playwright e reverte se quebrar
+
+**Funciona standalone** em qualquer projeto, sem precisar de `/up:novo-projeto`. Tambem roda automaticamente dentro do modo builder.
+
+### 10. Mobile First
+
+Detecta o que quebra no mobile/tablet e corrige automaticamente sem mexer no desktop.
+
+```
+/up:mobile-first                          # Escanear e corrigir tudo
+/up:mobile-first --no-fix                 # Apenas relatorio
+/up:mobile-first --page /dashboard        # Apenas uma pagina
+```
+
+O agente:
+1. Abre cada pagina em **7 viewports** (de iPhone SE a monitor full HD)
+2. Detecta problemas: overflow, texto ilegivel, alvos de toque pequenos, grid quebrado, imagens distorcidas, navegacao que nao cabe
+3. Corrige com classes Tailwind responsivas, media queries ou componentes novos (hamburger, drawer)
+4. **Verifica desktop apos cada correcao** — se desktop mudou, reverte e tenta outra abordagem
+5. Gera relatorio com score de responsividade e screenshots comparativos
+
+**Funciona standalone** em qualquer projeto. Tambem roda automaticamente dentro do modo builder (Estagio 4).
+
+### 11. Clone Builder
+
+Clonar um app existente via Playwright — analisa, extrai PRD e recria com sua stack.
+
+```
+/up:clone-builder https://app.exemplo.com               # Clonar exatamente
+/up:clone-builder https://app.exemplo.com --improve      # Clonar e melhorar
+/up:clone-builder https://app.exemplo.com --inspiration  # Usar como referencia
+```
+
+O clone-builder:
+1. **Crawl** — Playwright navega todas paginas, screenshots, intercepta APIs, extrai forms
+2. **Design Extractor** — extrai cores, fontes, espacamento, componentes, layout
+3. **Feature Mapper** — mapeia modulos, features, roles, data model, fluxos
+4. **PRD Writer** — sintetiza em PRD completo e detalhado
+5. **Modo Builder** — recria com sua stack (o builder sabe que e clone e segue design/features do original)
+6. **Clone Verifier** — verifica fidelidade funcional + visual contra o original
+
+**3 modos:**
+- `--exact`: reproduzir o mais fiel possivel (default)
+- `--improve`: reproduzir + aplicar blueprints + melhorias
+- `--inspiration`: usar como referencia, builder tem liberdade
+
+### 12. Dashboard
+
+Monitorar o builder em tempo real no browser:
+
+```
+/up:dashboard           # Abre em http://localhost:4040
+/up:dashboard 8080      # Porta customizada
+```
+
+Mostra: progresso, fases, status atual, commits, reports gerados. Atualiza a cada 3 segundos. Servidor leve (Node.js puro, zero deps).
+
+### 13. Manutencao
 
 ```
 /up:saude              # Diagnostica integridade do .plano/
@@ -309,8 +438,12 @@ O UP:
 
 | Comando | Descricao |
 |---------|-----------|
-| `/up:iniciar` | Registrar projeto existente (leve, sem questionario) |
-| `/up:novo-projeto` | Inicializar projeto completo (questionario + requisitos + roadmap) |
+| `/up:modo-builder` | Construir projeto completo autonomamente (greenfield ou brownfield) |
+| `/up:ux-tester` | Navegar sistema como usuario real, avaliar UX e implementar melhorias |
+| `/up:mobile-first` | Tornar sistema responsivo para mobile/tablet sem quebrar desktop |
+| `/up:clone-builder` | Clonar app existente via Playwright e recriar com sua stack |
+| `/up:dashboard` | Dashboard visual de monitoramento do builder em tempo real |
+| `/up:novo-projeto` | Inicializar projeto (detecta greenfield/brownfield) |
 | `/up:mapear-codigo` | Analisar codebase existente com agentes paralelos |
 | `/up:retomar` | Restaurar contexto da sessao anterior |
 | `/up:discutir-fase N` | Coletar contexto por questionamento estruturado |
@@ -322,8 +455,6 @@ O UP:
 | `/up:adicionar-fase "desc"` | Adicionar fase ao final do roadmap |
 | `/up:remover-fase N` | Remover fase futura e renumerar |
 | `/up:adicionar-testes N` | Gerar testes para fase completa |
-| `/up:melhorias` | Auditoria completa (UX, performance, modernidade) |
-| `/up:ideias` | Sugestoes de features com pesquisa de mercado |
 | `/up:rapido "tarefa"` | Tarefa rapida com commits atomicos |
 | `/up:depurar` | Depuracao sistematica com metodo cientifico |
 | `/up:configurar` | Configurar opcoes do workflow |
@@ -334,6 +465,9 @@ O UP:
 ### Flags
 
 ```
+# modo-builder
+--light           Pipeline enxuto (~50% menos tokens). Planeja, constroi, testa.
+
 # planejar-fase
 --pesquisar       Forcar re-pesquisa mesmo com RESEARCH.md existente
 --sem-pesquisa    Pular pesquisa, ir direto ao planejamento
@@ -342,19 +476,31 @@ O UP:
 
 # executar-fase
 --gaps-only       Executar apenas planos de fechamento de gaps
+
+# ux-tester
+--no-fix          Apenas relatorio, nao implementar melhorias
+
+# mobile-first
+--no-fix          Apenas relatorio, nao corrigir
+--page /rota      Testar apenas uma pagina especifica
 ```
 
 ### Pipelines
 
+**Manual (fase a fase):**
 ```
-Leve (recomendado para projetos existentes):
-/up:iniciar → /up:planejar-fase N → /up:executar-fase N → /up:verificar-trabalho N
-
-Completo:
 /up:novo-projeto → /up:discutir-fase N → /up:planejar-fase N → /up:executar-fase N → /up:verificar-trabalho N
+                                                                                              │
+                                                                                       Gaps? ─┤
+                                                                                       Sim  → /up:planejar-fase N --gaps
+                                                                                       Nao  → Proxima fase
+```
 
-Ciclo de gaps:
-/up:verificar-trabalho N → Gaps? → /up:planejar-fase N --gaps → /up:executar-fase N --gaps-only → Re-verificar
+**Modo Builder (totalmente autonomo):**
+```
+/up:modo-builder "briefing" → Perguntas criticas → Pesquisa/Mapeamento → Arquitetura
+    → [Loop: Planejar → Executar → Verificar → E2E → Reassessment] por fase
+    → Melhorias (codigo) → UX Tester (navegacao) → Ideias → DELIVERY.md
 ```
 
 ## Estrutura do `.plano/`
@@ -381,20 +527,84 @@ Ciclo de gaps:
 │   └── ...
 ├── rapido/
 │   └── TASK-001.md         # Tarefa rapida executada
-└── debug/
-    ├── bug-login.md        # Sessao de debug ativa
-    └── resolved/           # Sessoes resolvidas
+├── debug/
+│   ├── bug-login.md        # Sessao de debug ativa
+│   └── resolved/           # Sessoes resolvidas
+├── melhorias/              # Auditoria de codigo (UX, performance, modernidade)
+│   └── RELATORIO.md
+├── ideias/                 # Sugestoes de features com ICE scoring
+│   └── RELATORIO.md
+├── ux-review/              # UX tester (navegacao real via Playwright)
+│   ├── UX-REPORT.md
+│   └── screenshots/
+├── e2e/                    # Testes E2E finais (modo builder)
+│   ├── E2E-REPORT.md
+│   ├── smoke/
+│   └── responsive/
+├── captures/               # Insights capturados durante build
+│   └── TRIAGE.md
+├── LOCK.md                 # Crash recovery (modo builder)
+├── BRIEFING.md             # Briefing do usuario (modo builder)
+└── DELIVERY.md             # Relatorio de entrega (modo builder)
 ```
 
 Todos esses arquivos sao texto puro (Markdown/JSON) e podem ser commitados no repositorio.
 
 ## Agentes
 
-O UP usa 8 agentes especializados que rodam como subprocessos:
+O UP usa 33 agentes especializados organizados por funcao:
+
+**Arquitetura (planejamento):**
+
+| Agente | Funcao |
+|--------|--------|
+| **up-product-analyst** | Pesquisa concorrentes, define personas, lista features do mercado |
+| **up-system-designer** | Define modulos, roles, schema, permissoes, aplica 10 blueprints |
+| **up-arquiteto** | Transforma analise + design em documentos executaveis |
+| **up-requirements-validator** | 13 checks automaticos nos requisitos antes do build |
+
+**Execucao (build):**
+
+| Agente | Funcao |
+|--------|--------|
+| **up-frontend-specialist** | Componentes com todos estados de UI, responsivo, a11y |
+| **up-backend-specialist** | API design, validacao, auth, rate limiting, paginacao |
+| **up-database-specialist** | Schema, migrations, RLS, indices, seed data, soft delete |
+| **up-executor** | Executor generico (quando plano e misto) |
+| **up-planejador** | Cria planos executaveis com pesquisa inline |
+
+**Qualidade (review + test):**
+
+| Agente | Funcao |
+|--------|--------|
+| **up-code-reviewer** | Reflect step: revisa contra production-requirements |
+| **up-blind-validator** | Testa como usuario final SEM ler codigo |
+| **up-security-reviewer** | OWASP Top 10, auth bypass, injection, secrets |
+| **up-qa-agent** | Escreve e roda testes, identifica gaps de cobertura |
+| **up-verificador** | Verificacao goal-backward de trabalho completado |
+
+**Producao (finalizacao):**
+
+| Agente | Funcao |
+|--------|--------|
+| **up-devops-agent** | Dockerfile, CI/CD, .env.example, seed data |
+| **up-technical-writer** | README, API docs, CHANGELOG, setup guide |
+
+**Clone:**
+
+| Agente | Funcao |
+|--------|--------|
+| **up-clone-crawler** | Navega app via Playwright, screenshots, intercepta APIs, extrai forms |
+| **up-clone-design-extractor** | Extrai design system: cores, fontes, espacamento, componentes |
+| **up-clone-feature-mapper** | Mapeia modulos, features, roles, data model, fluxos |
+| **up-clone-prd-writer** | Sintetiza analise em PRD completo para modo-builder |
+| **up-clone-verifier** | Verifica fidelidade funcional + visual contra original |
+
+**Pipeline e suporte:**
 
 | Agente | Funcao |
 |--------|--------|
-| **up-pesquisador-projeto** | Pesquisa de dominio e tecnologia para novos projetos |
+| **up-pesquisador-projeto** | Pesquisa de dominio e tecnologia |
 | **up-roteirista** | Cria ROADMAP.md com fases e criterios de sucesso |
 | **up-planejador** | Planeja fases com pesquisa inline e self-check |
 | **up-executor** | Executa planos com commits atomicos |