up-cc 0.2.0 → 0.2.2

package/README.md

@@ -32,6 +32,7 @@ Sem UP, voce pede algo ao assistente e torce pra dar certo. Com UP:
 - **Commits atomicos** rastreiam cada mudanca com mensagens descritivas
 - **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)
 
 ## Instalacao
 
@@ -56,72 +57,261 @@ npx up-cc@latest --uninstall
 
 Apos instalar, reinicie o Claude Code e digite `/up:ajuda` para ver todos os comandos.
 
-## Inicio Rapido
+---
+
+## Manual de Uso
+
+### 1. Inicializando um projeto
+
+O UP funciona tanto para projetos novos (greenfield) quanto para codebases existentes (brownfield). A deteccao e automatica.
 
-### Novo projeto (do zero)
+#### Projeto novo (do zero)
 
 ```
-/up:novo-projeto          # Coleta contexto, cria PROJECT.md e ROADMAP.md
-/up:discutir-fase 1       # Discute requisitos da fase 1
-/up:planejar-fase 1       # Cria planos executaveis
-/up:executar-fase 1       # Executa com commits atomicos
-/up:verificar-trabalho 1  # UAT conversacional
+/up:novo-projeto
 ```
 
-### Projeto existente (brownfield)
+O UP vai:
+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
+
+Ao final voce tera um `.plano/` completo pronto para o pipeline de fases.
+
+#### Projeto existente (brownfield)
 
 ```
-/up:mapear-codigo         # Analisa codebase com agentes paralelos
-/up:novo-projeto          # Cria PROJECT.md baseado no mapeamento
-/up:discutir-fase 1       # Continua normalmente
+/up:mapear-codigo         # Opcional, mas recomendado
+/up:novo-projeto          # Detecta brownfield automaticamente
 ```
 
-### Continuar trabalho
+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 |
+|-----------|----------|
+| STACK.md | Tecnologias, frameworks, dependencias |
+| ARCHITECTURE.md | Design do sistema, fluxo de dados, padroes |
+| STRUCTURE.md | Organizacao de diretorios e arquivos |
+| CONVENTIONS.md | Estilo de codigo, nomeacao, padroes de erro |
+| INTEGRATIONS.md | APIs externas, banco de dados, autenticacao |
+| TESTING.md | Infraestrutura de testes, cobertura |
+| CONCERNS.md | Divida tecnica, areas frageis, seguranca |
+
+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
+
+Cada fase do roadmap passa por um pipeline de 4 etapas. Voce controla o ritmo — cada etapa e um comando separado.
+
+#### Etapa 1: Discutir (`/up:discutir-fase N`)
 
 ```
-/up:retomar               # Restaura contexto da sessao anterior
-/up:progresso             # Status e proxima acao recomendada
+/up:discutir-fase 1
 ```
 
-### Tarefa rapida
+O UP analisa a fase e identifica **areas cinzentas** — ambiguidades que mudariam a implementacao. Voce escolhe quais discutir.
+
+- Perguntas sao adaptadas ao que ja foi decidido em fases anteriores
+- Se o projeto e brownfield, carrega ARCHITECTURE.md e CONVENTIONS.md para perguntas informadas
+- Ideias fora do escopo sao anotadas como "adiadas", nao perdidas
+- Resultado: `CONTEXT.md` com decisoes capturadas
+
+**Quando pular:** Se a fase e infraestrutura pura ou a implementacao e obvia, voce pode ir direto para planejar.
+
+#### Etapa 2: Planejar (`/up:planejar-fase N`)
 
 ```
-/up:rapido "Corrigir bug no login"   # Executa com garantias UP
+/up:planejar-fase 1
 ```
 
-## Comandos
+Spawna o agente **up-planejador** que:
+- Le CONTEXT.md, ROADMAP.md, REQUIREMENTS.md e codebase docs
+- Faz pesquisa inline se necessario (busca docs, verifica APIs)
+- Cria PLAN-001.md, PLAN-002.md, etc. com tarefas especificas
+- Auto-verifica: cobertura de requisitos, dependencias, waves de execucao
+- Resultado: Planos executaveis prontos
 
-### Inicializacao
+Flags uteis:
+- `--pesquisar` — Forcar pesquisa profunda antes de planejar
+- `--sem-pesquisa` — Pular pesquisa, ir direto
+- `--gaps` — Replanejar a partir de lacunas do verificar-trabalho
 
-| Comando | Descricao |
-|---------|-----------|
-| `/up:novo-projeto` | Inicializar projeto com coleta de contexto interativa |
-| `/up:mapear-codigo` | Analisar codebase existente com agentes paralelos |
-| `/up:retomar` | Restaurar contexto da sessao anterior |
+#### Etapa 3: Executar (`/up:executar-fase N`)
+
+```
+/up:executar-fase 1
+```
+
+Spawna agentes **up-executor** que:
+- Executam planos organizados em **waves** (planos independentes rodam em paralelo)
+- Cada plano produz commits atomicos com mensagens descritivas
+- Resultado: Codigo implementado e commitado, SUMMARY.md criado
+
+#### Etapa 4: Verificar (`/up:verificar-trabalho N`)
+
+```
+/up:verificar-trabalho 1
+```
+
+Verificacao goal-backward (parte do resultado desejado e volta):
+- Testa se os criterios de sucesso da fase foram atingidos
+- Se encontra gaps: gera VERIFICATION.md com detalhes
+- Resultado: Fase aprovada ou lista de gaps para corrigir
+
+#### Ciclo de correcao de gaps
+
+Se a verificacao encontrou problemas:
+
+```
+/up:planejar-fase 1 --gaps     # Cria planos de correcao baseados no VERIFICATION.md
+/up:executar-fase 1 --gaps-only # Executa apenas os planos de correcao
+/up:verificar-trabalho 1        # Re-verifica
+```
+
+### 3. Gerenciamento do projeto
+
+#### Ver progresso
+
+```
+/up:progresso
+```
+
+Mostra dashboard com: fase atual, porcentagem de conclusao, bloqueios, e sugere o proximo comando a rodar.
+
+#### Pausar e retomar
+
+```
+/up:pausar          # Cria .continue-aqui.md com contexto completo
+```
+
+Na proxima sessao (ou apos `/clear`):
+
+```
+/up:retomar          # Le .continue-aqui.md e STATE.md, restaura tudo
+```
+
+O UP foi desenhado para sobreviver a `/clear`. Todo estado fica em disco no `.plano/`.
+
+#### Adicionar e remover fases
+
+```
+/up:adicionar-fase "Implementar sistema de notificacoes"   # Adiciona ao final
+/up:remover-fase 5                                          # Remove e renumera
+```
+
+Apenas fases futuras (nao iniciadas) podem ser removidas.
+
+### 4. Tarefas rapidas
+
+Para tarefas pequenas que nao justificam uma fase inteira:
+
+```
+/up:rapido "Corrigir bug no formulario de login"
+/up:rapido "Adicionar favicon"
+/up:rapido "Atualizar dependencias"
+```
+
+O `/up:rapido` faz o mesmo pipeline simplificado:
+- Planeja e executa em um unico fluxo
+- Commits atomicos com rastreamento
+- Tarefas ficam em `.plano/rapido/TASK-NNN.md`
+- Nao afeta ROADMAP.md — e separado das fases
+
+### 5. Depuracao
 
-### Pipeline de Fase
+Para bugs complexos que precisam de investigacao sistematica:
+
+```
+/up:depurar "Botao de salvar nao funciona na pagina de perfil"
+```
+
+O depurador:
+- Coleta sintomas (comportamento esperado, real, erros, reproducao)
+- Spawna agente **up-depurador** que investiga com metodo cientifico
+- Forma hipoteses falsificaveis, testa uma de cada vez
+- Mantém sessao persistente em `.plano/debug/` (sobrevive a `/clear`)
+- Ao encontrar a causa raiz, oferece corrigir automaticamente
+
+Sessoes ativas podem ser retomadas:
+
+```
+/up:depurar                    # Sem argumento: lista sessoes ativas
+```
+
+### 6. Testes
+
+Apos completar uma fase, gerar testes automaticamente:
+
+```
+/up:adicionar-testes 1
+```
+
+O UP:
+- Analisa todos os arquivos modificados pela fase
+- Classifica cada um: unitario (TDD), E2E (browser) ou pular
+- Apresenta classificacao para aprovacao
+- Gera testes seguindo convencoes do projeto
+- Reporta: passando, falhando, gaps de cobertura, bugs descobertos
+
+### 7. Configuracao
+
+```
+/up:configurar
+```
+
+| Opcao | Default | Descricao |
+|-------|---------|-----------|
+| Modo | solo | `solo` (commits diretos) ou `time` (branches por fase) |
+| Paralelizacao | sim | Agentes rodam em paralelo quando independentes |
+| Commit Docs | sim | Commitar documentos de planejamento automaticamente |
+| Auto-Advance | nao | Encadear estagios automaticamente |
+
+### 8. Manutencao
+
+```
+/up:saude              # Diagnostica integridade do .plano/
+/up:saude --reparar    # Corrige problemas automaticamente
+/up:atualizar          # Verifica e instala atualizacoes do UP
+```
+
+---
+
+## Referencia Rapida
+
+### Comandos
 
 | Comando | Descricao |
 |---------|-----------|
+| `/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 |
 | `/up:planejar-fase N` | Criar planos executaveis com pesquisa e self-check |
 | `/up:executar-fase N` | Executar planos com paralelizacao por ondas |
 | `/up:verificar-trabalho N` | Validar features via UAT conversacional |
-
-### Gerenciamento
-
-| Comando | Descricao |
-|---------|-----------|
 | `/up:progresso` | Dashboard de status e proxima acao |
 | `/up:pausar` | Criar arquivo de handoff `.continue-aqui.md` |
 | `/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 |
-
-### Utilitarios
-
-| Comando | Descricao |
-|---------|-----------|
 | `/up:rapido "tarefa"` | Tarefa rapida com commits atomicos |
 | `/up:depurar` | Depuracao sistematica com metodo cientifico |
 | `/up:configurar` | Configurar opcoes do workflow |
@@ -142,63 +332,40 @@ Apos instalar, reinicie o Claude Code e digite `/up:ajuda` para ver todos os com
 --gaps-only       Executar apenas planos de fechamento de gaps
 ```
 
-## Pipeline de Desenvolvimento
-
-```
-                    ┌──────────────────────────────────────────┐
-                    │              /up:novo-projeto             │
-                    │    Coleta contexto → PROJECT.md + ROADMAP │
-                    └────────────────┬─────────────────────────┘
-                                     │
-                    ┌────────────────▼─────────────────────────┐
-                    │            /up:discutir-fase N            │
-                    │     Questionamento → CONTEXT.md           │
-                    └────────────────┬─────────────────────────┘
-                                     │
-                    ┌────────────────▼─────────────────────────┐
-                    │           /up:planejar-fase N             │
-                    │   Pesquisa + Planejamento → PLAN-NNN.md   │
-                    └────────────────┬─────────────────────────┘
-                                     │
-                    ┌────────────────▼─────────────────────────┐
-                    │           /up:executar-fase N             │
-                    │   Execucao paralela → Commits atomicos    │
-                    └────────────────┬─────────────────────────┘
-                                     │
-                    ┌────────────────▼─────────────────────────┐
-                    │        /up:verificar-trabalho N           │
-                    │     UAT conversacional → VERIFICATION.md  │
-                    └────────────────┬─────────────────────────┘
-                                     │
-                              Gaps encontrados?
-                              ├── Sim → /up:planejar-fase N --gaps
-                              └── Nao → Proxima fase
+### Pipeline
+
+```
+/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
 ```
 
 ## Estrutura do `.plano/`
 
-O UP cria e mantém um diretorio `.plano/` na raiz do projeto:
-
 ```
 .plano/
 ├── PROJECT.md              # O que e o projeto, requisitos, decisoes
 ├── ROADMAP.md              # Todas as fases com status
 ├── STATE.md                # Posicao atual, progresso, continuidade
 ├── config.json             # Configuracoes do workflow
+├── codebase/               # Mapeamento do codebase (brownfield)
+│   ├── STACK.md
+│   ├── ARCHITECTURE.md
+│   ├── CONVENTIONS.md
+│   ├── CONCERNS.md
+│   └── ...
 ├── fases/
 │   ├── 01-autenticacao/
 │   │   ├── CONTEXT.md      # Contexto coletado na discussao
 │   │   ├── RESEARCH.md     # Pesquisa de dominio/tecnologia
 │   │   ├── PLAN-001.md     # Plano executavel
-│   │   ├── PLAN-002.md     # Outro plano (se necessario)
 │   │   ├── SUMMARY-001.md  # Resultado da execucao
 │   │   └── VERIFICATION.md # Resultado do UAT
-│   ├── 02-dashboard/
-│   │   └── ...
 │   └── ...
 ├── rapido/
-│   ├── TASK-001.md         # Tarefa rapida executada
-│   └── ...
+│   └── TASK-001.md         # Tarefa rapida executada
 └── debug/
     ├── bug-login.md        # Sessao de debug ativa
     └── resolved/           # Sessoes resolvidas
@@ -237,21 +404,6 @@ O UP sobrevive a `/clear` e reinicializacoes do CLI:
 3. **Retomada** — `/up:retomar` le os arquivos de estado e restaura o contexto completo
 4. **Debug persistente** — Sessoes de debug em `.plano/debug/` sobrevivem entre conversas
 
-## Configuracao
-
-```
-/up:configurar
-```
-
-Opcoes disponiveis:
-
-| Opcao | Default | Descricao |
-|-------|---------|-----------|
-| Modo | solo | `solo` (commits diretos) ou `time` (branches por fase) |
-| Paralelizacao | sim | Agentes rodam em paralelo quando independentes |
-| Commit Docs | sim | Commitar documentos de planejamento automaticamente |
-| Auto-Advance | nao | Encadear estagios automaticamente |
-
 ## Compatibilidade
 
 | Runtime | Status | Formato |

package/agents/up-roteirista.md

@@ -272,6 +272,17 @@ Se research/SUMMARY.md fornecido:
 - Note flags de pesquisa
 - Use como input, nao mandato
 
+## Passo 3.5: Identificar Funcionalidades Existentes (Brownfield)
+Se codebase docs existem (.plano/codebase/ARCHITECTURE.md, STACK.md):
+1. Ler ARCHITECTURE.md e extrair funcionalidades ja implementadas
+2. Agrupar funcionalidades em fases macro por dominio (3-6 max)
+3. Criar fases existentes com:
+   - Status: checkbox marcado `[x]`
+   - Sufixo: `- Existente`
+   - Sem criterios de sucesso (nao foram planejados/executados via UP)
+   - Sem requisitos mapeados (sao requisitos validados, nao ativos)
+4. Numerar fases novas APOS as existentes
+
 ## Passo 4: Identificar Fases
 Aplique metodologia de identificacao de fases:
 1. Agrupe requisitos por fronteiras naturais de entrega
@@ -355,6 +366,74 @@ Se feedback de revisao fornecido:
 ```
 </structured_returns>
 
+<brownfield_phases>
+
+## Fases Existentes (Brownfield)
+
+Quando o projeto e brownfield (codebase existente), o roteiro deve comecar com fases que representam o que JA EXISTE. Estas fases nao foram planejadas/executadas via UP — elas representam funcionalidades ja implementadas.
+
+### Regras
+
+1. **Agrupar por dominio, nao por feature individual** — Max 3-6 fases existentes
+2. **Status "Existente"** — Diferente de "Complete" (nunca foi planejado/executado via UP)
+3. **Checkbox marcado** `[x]` — Visualmente indica que ja esta pronto
+4. **Sem criterios de sucesso** — Nao foram derivados via goal-backward
+5. **Sem planos** — Nao foram planejados
+6. **Fases novas vem APOS** — Numeracao continua das existentes
+
+### Exemplo
+
+```markdown
+## Fases
+
+- [x] **Fase 1: Autenticacao e usuarios** - Existente
+- [x] **Fase 2: Chat e atendimento** - Existente
+- [x] **Fase 3: Dashboard e metricas** - Existente
+- [ ] **Fase 4: Filtro de usuarios no chat** - Nova feature
+- [ ] **Fase 5: Relatorios avancados** - Nova feature
+
+## Detalhes das Fases
+
+### Fase 1: Autenticacao e usuarios
+**Status**: Existente
+**Funcionalidades**: Login, cadastro, perfis, permissoes
+**Planos**: N/A (pre-existente)
+
+### Fase 2: Chat e atendimento
+**Status**: Existente
+**Funcionalidades**: Chat em tempo real, filas de atendimento, historico
+**Planos**: N/A (pre-existente)
+
+### Fase 3: Dashboard e metricas
+**Status**: Existente
+**Funcionalidades**: Dashboard principal, metricas de atendimento
+**Planos**: N/A (pre-existente)
+
+### Fase 4: Filtro de usuarios no chat
+**Objetivo**: Permitir filtrar usuarios por criterios no chat
+**Depende de**: Fase 2
+**Requisitos**: CHAT-01, CHAT-02
+**Criterios de Sucesso** (o que deve ser VERDADE):
+  1. Atendente pode filtrar usuarios por nome, email ou status
+  2. Filtros persistem entre sessoes
+**Planos**: TBD
+```
+
+### Na Tabela de Progresso
+
+Fases existentes aparecem como completas sem planos:
+
+```markdown
+| Fase | Planos Completos | Status | Completado |
+|------|-----------------|--------|------------|
+| 1. Autenticacao e usuarios | N/A | Existente | Pre-existente |
+| 2. Chat e atendimento | N/A | Existente | Pre-existente |
+| 3. Dashboard e metricas | N/A | Existente | Pre-existente |
+| 4. Filtro de usuarios no chat | 0/2 | Nao iniciado | - |
+```
+
+</brownfield_phases>
+
 <anti_patterns>
 
 **Nao imponha estrutura arbitraria:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "up-cc",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Simplified spec-driven development for Claude Code, Gemini and OpenCode.",
   "bin": {
     "up-cc": "bin/install.js"

package/templates/roadmap.md

@@ -127,5 +127,45 @@ Phases execute in numeric order: 2 -> 2.1 -> 2.2 -> 3 -> 3.1 -> 4
 - `Not started` - Haven't begun
 - `In progress` - Currently working
 - `Complete` - Done (add completion date)
+- `Existing` - Pre-existing functionality (brownfield only, never planned/executed via UP)
 - `Deferred` - Pushed to later (with reason)
 </status_values>
+
+<brownfield_example>
+For brownfield projects, existing functionality is grouped into completed phases before new work:
+
+```markdown
+## Phases
+
+- [x] **Phase 1: Authentication and users** - Existing
+- [x] **Phase 2: Core content** - Existing
+- [ ] **Phase 3: New feature** - [One-line description]
+
+## Phase Details
+
+### Phase 1: Authentication and users
+**Status**: Existing
+**Features**: Login, registration, profiles, permissions
+**Plans**: N/A (pre-existing)
+
+### Phase 2: Core content
+**Status**: Existing
+**Features**: CRUD operations, search, categories
+**Plans**: N/A (pre-existing)
+
+### Phase 3: New feature
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 2
+**Requirements**: [REQ-01, REQ-02]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+**Plans**: TBD
+```
+
+Guidelines for existing phases:
+- Group by domain, not individual features (max 3-6 existing phases)
+- No success criteria (not derived via goal-backward)
+- No plans (not planned/executed via UP)
+- New phases numbered after existing ones
+- Progress table shows "Existing" status and "N/A" for plans
+</brownfield_example>

package/workflows/novo-projeto.md

@@ -612,7 +612,11 @@ Criar roteiro:
 6. Retornar ROADMAP CREATED com resumo
 
 **Se projeto brownfield:**
-- Considerar divida tecnica de CONCERNS.md ao priorizar fases
+- Ler .plano/codebase/ARCHITECTURE.md e .plano/codebase/STACK.md para entender o que ja existe
+- Agrupar funcionalidades existentes em fases macro concluidas (max 3-6 fases, por dominio)
+- Fases existentes usam checkbox marcado [x], status "Existente", sem criterios de sucesso, sem planos
+- Numerar fases NOVAS apos as existentes (ex: se 3 fases existentes, nova fase comeca em 4)
+- Considerar divida tecnica de CONCERNS.md ao priorizar fases novas
 - Respeitar convencoes existentes de CONVENTIONS.md
 - Fases de refatoracao/correcao devem vir antes de features que dependem delas