up-cc 0.1.6 → 0.2.1

package/README.md

@@ -0,0 +1,426 @@
+<p align="center">
+  <pre align="center">
+  ██╗   ██╗██████╗
+  ██║   ██║██╔══██╗
+  ██║   ██║██████╔╝
+  ██║   ██║██╔═══╝
+  ╚██████╔╝██║
+   ╚═════╝ ╚═╝</pre>
+</p>
+
+<h3 align="center">Desenvolvimento orientado a especificacao para Claude Code, Gemini CLI e OpenCode</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/up-cc"><img src="https://img.shields.io/npm/v/up-cc.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/up-cc"><img src="https://img.shields.io/npm/dm/up-cc.svg" alt="npm downloads"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/up-cc.svg" alt="license"></a>
+</p>
+
+---
+
+**UP** e um sistema de meta-prompting que transforma seu assistente de IA em um desenvolvedor estruturado. Em vez de pedir "faz X", voce descreve o projeto e o UP cuida do planejamento, execucao, verificacao e rastreamento — tudo via slash commands.
+
+Funciona com **Claude Code**, **Gemini CLI** e **OpenCode**.
+
+## Por que UP?
+
+Sem UP, voce pede algo ao assistente e torce pra dar certo. Com UP:
+
+- **Projetos sao divididos em fases** com roadmap, planos executaveis e criterios de aceite
+- **Cada fase passa por um pipeline**: discutir → planejar → executar → verificar
+- **Estado persiste entre sessoes** via arquivos em `.plano/` — sobrevive a `/clear` e troca de contexto
+- **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
+
+```bash
+npx up-cc@latest --claude --global    # Claude Code
+npx up-cc@latest --gemini --global    # Gemini CLI
+npx up-cc@latest --opencode --global  # OpenCode
+npx up-cc@latest --all --global       # Todos
+```
+
+Para instalar localmente no projeto (em vez de global):
+
+```bash
+npx up-cc@latest --claude --local
+```
+
+Desinstalar:
+
+```bash
+npx up-cc@latest --uninstall
+```
+
+Apos instalar, reinicie o Claude Code e digite `/up:ajuda` para ver todos os comandos.
+
+---
+
+## Manual de Uso
+
+### 1. Inicializando um projeto
+
+O UP funciona tanto para projetos novos (greenfield) quanto para codebases existentes (brownfield). A deteccao e automatica.
+
+#### Projeto novo (do zero)
+
+```
+/up:novo-projeto
+```
+
+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         # Opcional, mas recomendado
+/up:novo-projeto          # Detecta brownfield automaticamente
+```
+
+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:discutir-fase 1
+```
+
+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:planejar-fase 1
+```
+
+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
+
+Flags uteis:
+- `--pesquisar` — Forcar pesquisa profunda antes de planejar
+- `--sem-pesquisa` — Pular pesquisa, ir direto
+- `--gaps` — Replanejar a partir de lacunas do verificar-trabalho
+
+#### 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
+
+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 |
+| `/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 |
+| `/up:rapido "tarefa"` | Tarefa rapida com commits atomicos |
+| `/up:depurar` | Depuracao sistematica com metodo cientifico |
+| `/up:configurar` | Configurar opcoes do workflow |
+| `/up:atualizar` | Verificar e instalar atualizacoes |
+| `/up:saude` | Diagnosticar integridade do `.plano/` |
+| `/up:ajuda` | Referencia completa de comandos |
+
+### Flags
+
+```
+# planejar-fase
+--pesquisar       Forcar re-pesquisa mesmo com RESEARCH.md existente
+--sem-pesquisa    Pular pesquisa, ir direto ao planejamento
+--auto            Auto-detectar proxima fase nao planejada
+--gaps            Modo fechamento de gaps (le VERIFICATION.md)
+
+# executar-fase
+--gaps-only       Executar apenas planos de fechamento de gaps
+```
+
+### 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/`
+
+```
+.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
+│   │   ├── SUMMARY-001.md  # Resultado da execucao
+│   │   └── VERIFICATION.md # Resultado do UAT
+│   └── ...
+├── rapido/
+│   └── TASK-001.md         # Tarefa rapida executada
+└── debug/
+    ├── bug-login.md        # Sessao de debug ativa
+    └── resolved/           # Sessoes resolvidas
+```
+
+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:
+
+| Agente | Funcao |
+|--------|--------|
+| **up-pesquisador-projeto** | Pesquisa de dominio e tecnologia para novos projetos |
+| **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 |
+| **up-verificador** | Verificacao goal-backward de trabalho completado |
+| **up-mapeador-codigo** | Analisa codebases existentes em paralelo |
+| **up-depurador** | Investigacao de bugs com metodo cientifico |
+| **up-sintetizador** | Sintetiza pesquisa em documentos estruturados |
+
+## Hooks
+
+Dois hooks sao instalados automaticamente:
+
+- **up-statusline** — Barra de status abaixo do input mostrando modelo, diretorio e uso de contexto
+- **up-context-monitor** — Avisa quando o contexto esta ficando cheio (35% warning, 25% critico), sugerindo `/clear` + `/up:retomar`
+
+## Persistencia entre Sessoes
+
+O UP sobrevive a `/clear` e reinicializacoes do CLI:
+
+1. **Estado em disco** — `.plano/STATE.md` rastreia posicao, decisoes, bloqueios
+2. **Handoff** — `/up:pausar` cria `.continue-aqui.md` com contexto para retomada
+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
+
+## Compatibilidade
+
+| Runtime | Status | Formato |
+|---------|--------|---------|
+| Claude Code | Completo | Nativo (Markdown + YAML frontmatter) |
+| Gemini CLI | Completo | Convertido (TOML commands, YAML arrays) |
+| OpenCode | Completo | Convertido (object tools, hex colors) |
+
+Requisitos: Node.js >= 16.7.0
+
+## Atualizacao
+
+```
+/up:atualizar             # Verifica e instala de dentro do CLI
+npx up-cc@latest --claude --global  # Ou via terminal
+```
+
+## Licenca
+
+MIT

package/bin/up-tools.cjs

@@ -453,11 +453,25 @@ function cmdInitNovoProjeto(cwd, raw) {
     hasCode = files.trim().length > 0;
   } catch {}
 
+  // Check if codebase mapping exists
+  const hasCodebaseMap = pathExistsInternal(cwd, '.plano/codebase');
+  let codebaseFiles = [];
+  if (hasCodebaseMap) {
+    try {
+      const fs = require('fs');
+      codebaseFiles = fs.readdirSync(path.join(cwd, '.plano/codebase'))
+        .filter(f => f.endsWith('.md'))
+        .map(f => `.plano/codebase/${f}`);
+    } catch {}
+  }
+
   const result = {
     commit_docs: config.commit_docs,
     project_exists: pathExistsInternal(cwd, '.plano/PROJECT.md'),
     planning_exists: pathExistsInternal(cwd, '.plano'),
     has_existing_code: hasCode,
+    has_codebase_map: hasCodebaseMap,
+    codebase_files: codebaseFiles,
     has_git: pathExistsInternal(cwd, '.git'),
     project_path: '.plano/PROJECT.md',
   };

package/commands/ajuda.md

@@ -88,16 +88,21 @@ Sistema de desenvolvimento orientado a fases para projetos de software.
 
 ## Fluxos de Trabalho Comuns
 
-### Projeto com Codigo Existente (brownfield)
+### Projeto com Codigo Existente (mais comum)
 ```
-/up:mapear-codigo
-/up:novo-projeto
-/up:discutir-fase 1
+/up:mapear-codigo              # Analisa codebase (stack, arquitetura, concerns)
+/up:novo-projeto               # Detecta brownfield automaticamente
+/up:discutir-fase 1            # Discute no contexto do codigo existente
+/up:planejar-fase 1            # Planos respeitam convencoes do codebase
+/up:executar-fase 1
+/up:verificar-trabalho 1
 ```
+Dica: /up:novo-projeto detecta codigo existente e adapta as perguntas.
+O mapeamento do codebase alimenta todo o pipeline automaticamente.
 
 ### Novo Projeto (do zero)
 ```
-/up:novo-projeto
+/up:novo-projeto               # Detecta greenfield automaticamente
 /up:discutir-fase 1
 /up:planejar-fase 1
 /up:executar-fase 1

package/commands/novo-projeto.md

@@ -1,6 +1,6 @@
 ---
 name: up:novo-projeto
-description: Inicializar novo projeto com coleta de contexto e PROJECT.md
+description: Inicializar projeto (detecta greenfield/brownfield automaticamente)
 argument-hint: ""
 allowed-tools:
   - Read
@@ -15,11 +15,12 @@ allowed-tools:
   - mcp__context7__*
 ---
 <objective>
-Initialize a new project through structured context gathering and documentation.
+Inicializar projeto com coleta de contexto estruturada. Detecta automaticamente se e greenfield (sem codigo) ou brownfield (codigo existente) e adapta questionamento, pesquisa e requisitos.
 
-**Default flow:** Questioning -> Research -> Requirements -> Roadmap -> PROJECT.md
+**Greenfield:** Questioning → Research → Requirements → Roadmap → PROJECT.md
+**Brownfield:** Codebase map → Questioning adaptado → Requisitos inferidos + novos → Roadmap → PROJECT.md
 
-**Orchestrator role:** Guide user through project discovery questions, research domain and technologies, synthesize requirements, generate phased roadmap, create PROJECT.md with all gathered context.
+**Orchestrator role:** Detectar modo, carregar mapeamento do codebase (se brownfield), guiar questionamento adaptado, sintetizar requisitos, gerar roadmap com contexto completo.
 </objective>
 
 <execution_context>
@@ -30,10 +31,10 @@ Initialize a new project through structured context gathering and documentation.
 <context>
 $ARGUMENTS
 
-Project initialization collects context through interactive questioning before any planning or coding begins.
+Inicializacao coleta contexto por questionamento interativo. Se codigo existente for detectado, adapta o fluxo para brownfield: carrega mapeamento do codebase, infere requisitos validados, e pergunta sobre novos objetivos.
 </context>
 
 <process>
 Execute the novo-projeto workflow from @~/.claude/up/workflows/novo-projeto.md end-to-end.
-Preserve all workflow gates (questioning, research, requirements, roadmap generation, PROJECT.md creation).
+Preserve all workflow gates (mode detection, codebase loading, questioning, research, requirements, roadmap generation, PROJECT.md creation).
 </process>

package/package.json

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

package/templates/project.md

@@ -145,24 +145,38 @@ PROJECT.md evolves throughout the project lifecycle.
 
 <brownfield>
 
-For existing codebases:
-
-1. **Map codebase first** via `/up:mapear`
-
-2. **Infer Validated requirements** from existing code:
-   - What does the codebase actually do?
-   - What patterns are established?
-   - What's clearly working and relied upon?
-
-3. **Gather Active requirements** from user:
-   - Present inferred current state
-   - Ask what they want to build next
-
-4. **Initialize:**
-   - Validated = inferred from existing code
-   - Active = user's goals for this work
-   - Out of Scope = boundaries user specifies
-   - Context = includes current codebase state
+Para codebases existentes (brownfield):
+
+O workflow `/up:novo-projeto` detecta brownfield automaticamente e adapta o fluxo.
+
+1. **Mapear codebase** via `/up:mapear-codigo` (opcional mas recomendado)
+   - Produz 7 documentos em `.plano/codebase/`
+   - STACK.md, ARCHITECTURE.md, CONVENTIONS.md, CONCERNS.md, etc.
+
+2. **`/up:novo-projeto` detecta brownfield e:**
+   - Carrega documentos do mapeamento como contexto
+   - Pergunta "O que voce quer fazer com esse codigo?" (nao "O que voce quer construir?")
+   - Explora: o que funciona, o que causa dor, divida tecnica, retrocompatibilidade
+
+3. **Inferir requisitos Validados** do codebase existente:
+   - Features que ja funcionam em producao
+   - Padroes e convencoes estabelecidos
+   - Integrações e dependencias que devem ser preservadas
+
+4. **Coletar requisitos Ativos** do usuario:
+   - Apresentar estado atual inferido
+   - Perguntar objetivos: novas features, refatoracao, correcoes, migracoes
+
+5. **Inicializar PROJECT.md:**
+   - Validados = inferidos do codigo existente
+   - Ativos = objetivos do usuario para este trabalho
+   - Fora do Escopo = fronteiras definidas pelo usuario
+   - Contexto = referencia .plano/codebase/ com dados do mapeamento
+
+6. **Pipeline downstream usa codebase map:**
+   - `/up:discutir-fase` carrega ARCHITECTURE.md e CONVENTIONS.md para perguntas informadas
+   - `/up:planejar-fase` passa CONVENTIONS.md e CONCERNS.md ao planejador
+   - Roteirista prioriza divida tecnica antes de features dependentes
 
 </brownfield>
 

package/workflows/discutir-fase.md

@@ -85,6 +85,18 @@ Extrair:
 - **REQUIREMENTS.md** -- Criterios de aceitacao, restricoes
 - **STATE.md** -- Progresso atual, flags ou notas
 
+**Passo 1b: Ler mapeamento do codebase (se brownfield)**
+```bash
+ls .plano/codebase/*.md 2>/dev/null
+```
+
+Se `.plano/codebase/` existe (projeto brownfield):
+- Ler `ARCHITECTURE.md` -- entender estrutura do sistema para perguntas de design
+- Ler `CONVENTIONS.md` -- entender padroes existentes para alinhar discussao
+- Ler `CONCERNS.md` -- divida tecnica que pode afetar decisoes da fase
+
+**Uso:** Areas cinzentas devem considerar restricoes e padroes do codebase existente. Perguntas como "Essa fase vai mexer em que partes do sistema?" sao informadas pela arquitetura conhecida.
+
 **Passo 2: Ler todos CONTEXT.md de fases anteriores**
 ```bash
 find .plano/fases -name "*-CONTEXT.md" 2>/dev/null | sort

package/workflows/novo-projeto.md

@@ -1,5 +1,7 @@
 <purpose>
-Inicializar um novo projeto: questionamento, pesquisa (opcional), requisitos, roteiro. Este e o momento mais importante do projeto -- questionamento profundo aqui significa planos melhores, execucao melhor, resultados melhores.
+Inicializar projeto: questionamento, pesquisa (opcional), requisitos, roteiro. Detecta automaticamente se e greenfield (sem codigo) ou brownfield (codigo existente) e adapta o fluxo.
+
+Este e o momento mais importante do projeto -- questionamento profundo aqui significa planos melhores, execucao melhor, resultados melhores.
 </purpose>
 
 <process>
@@ -13,15 +15,31 @@ INIT=$(node "$HOME/.claude/up/bin/up-tools.cjs" init novo-projeto)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
-Parse JSON: `commit_docs`, `project_exists`, `planning_exists`, `has_existing_code`, `has_git`, `project_path`.
+Parse JSON: `commit_docs`, `project_exists`, `planning_exists`, `has_existing_code`, `has_codebase_map`, `codebase_files`, `has_git`, `project_path`.
+
+**Se `project_exists` = true:**
+
+Use AskUserQuestion:
+- header: "Projeto existente"
+- question: "Ja existe um PROJECT.md. O que voce quer fazer?"
+- options:
+  - "Revisar e atualizar" -- Atualizar projeto existente com novos objetivos
+  - "Recomecar do zero" -- Apagar e reinicializar (PROJECT.md sera recriado)
+  - "Cancelar" -- Manter como esta
 
-**Se `project_exists` = true:** Erro -- projeto ja inicializado. Use `/up:progresso`.
+Se "Revisar e atualizar": Ler PROJECT.md existente, pular para passo 2 com contexto carregado.
+Se "Recomecar do zero": Continuar normalmente (sobrescreve).
+Se "Cancelar": Sair. Sugerir `/up:progresso`.
 
 **Se `has_git` = false:** Inicializar git:
 ```bash
 git init
 ```
 
+**Determinar modo:**
+- `has_existing_code` = true OU `has_codebase_map` = true → **MODO BROWNFIELD**
+- Caso contrario → **MODO GREENFIELD**
+
 ## 2. Questionamento Profundo
 
 ```
@@ -30,6 +48,8 @@ git init
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
+### MODO GREENFIELD
+
 **Abrir a conversa:**
 
 Pergunte inline (freeform, NAO AskUserQuestion):
@@ -38,7 +58,53 @@ Pergunte inline (freeform, NAO AskUserQuestion):
 
 Espere a resposta. Isso da o contexto para perguntas inteligentes.
 
-**Seguir os fios:**
+### MODO BROWNFIELD
+
+**Carregar contexto do codebase:**
+
+Se `has_codebase_map` = true:
+```bash
+# Ler documentos do mapeamento
+cat .plano/codebase/STACK.md 2>/dev/null
+cat .plano/codebase/ARCHITECTURE.md 2>/dev/null
+cat .plano/codebase/CONCERNS.md 2>/dev/null
+```
+
+Se `has_codebase_map` = false (tem codigo mas nao mapeou):
+```bash
+# Mini-scan: detectar stack e estrutura
+ls package.json go.mod Cargo.toml requirements.txt pyproject.toml pom.xml build.gradle composer.json Gemfile 2>/dev/null
+ls -d src/ app/ lib/ cmd/ internal/ pages/ components/ 2>/dev/null | head -10
+```
+
+**Apresentar o que ja sabemos:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ UP > PROJETO EXISTENTE DETECTADO
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[Se mapeamento existe:]
+Stack: [de STACK.md]
+Arquitetura: [resumo de ARCHITECTURE.md]
+Preocupacoes: [de CONCERNS.md]
+
+[Se sem mapeamento:]
+Detectado: [stack inferido dos arquivos de config]
+Estrutura: [diretorios encontrados]
+
+Dica: /up:mapear-codigo produz analise mais detalhada
+```
+
+**Abrir a conversa (brownfield):**
+
+Pergunte inline (freeform, NAO AskUserQuestion):
+
+"Voce ja tem codigo rodando. O que voce quer fazer com ele? (novas features, refatoracao, correcoes, migracoes...)"
+
+Espere a resposta.
+
+### AMBOS OS MODOS — Seguir os fios
 
 Com base na resposta, faca perguntas de acompanhamento que aprofundem. Use AskUserQuestion com opcoes que investiguem o que mencionaram -- interpretacoes, esclarecimentos, exemplos concretos.
 
@@ -49,6 +115,12 @@ Continue seguindo fios. Cada resposta abre novos fios para explorar. Pergunte so
 - Como seria na pratica
 - O que ja esta decidido
 
+**Brownfield extra — pergunte tambem:**
+- O que funciona bem e NAO deve mudar
+- O que causa mais dor
+- Se ha divida tecnica urgente
+- Se ha restricoes de retrocompatibilidade
+
 Consulte `questioning.md` para tecnicas:
 - Desafie vaguidao
 - Torne o abstrato concreto
@@ -74,6 +146,8 @@ Loop ate "Criar PROJECT.md" selecionado.
 
 Sintetize todo o contexto em `.plano/PROJECT.md` usando o template de `templates/project.md`.
 
+### MODO GREENFIELD
+
 Inicialize requisitos como hipoteses:
 
 ```markdown
@@ -95,6 +169,51 @@ Inicialize requisitos como hipoteses:
 - [Exclusao 2] -- [por que]
 ```
 
+### MODO BROWNFIELD
+
+Inferir requisitos validados do codebase existente, separar objetivos novos:
+
+```markdown
+## Requisitos
+
+### Validados
+
+<!-- Inferidos do codebase existente -- ja funcionam em producao -->
+
+- [x] [Feature existente 1 inferida do codigo]
+- [x] [Feature existente 2 inferida do codigo]
+- [x] [Padrao estabelecido inferido do codigo]
+
+### Ativos
+
+<!-- Novos objetivos do usuario para este trabalho -->
+
+- [ ] [Novo objetivo 1]
+- [ ] [Novo objetivo 2]
+- [ ] [Novo objetivo 3]
+
+### Fora do Escopo
+
+- [Exclusao 1] -- [por que]
+- [Exclusao 2] -- [por que]
+```
+
+Se `has_codebase_map` = true, popular secao Contexto com dados do mapeamento:
+
+```markdown
+## Contexto
+
+**Codebase existente mapeado em:** .plano/codebase/
+
+- **Stack:** [de STACK.md]
+- **Arquitetura:** [de ARCHITECTURE.md]
+- **Convencoes:** Ver .plano/codebase/CONVENTIONS.md
+- **Divida tecnica:** [resumo de CONCERNS.md]
+- **Testes:** [resumo de TESTING.md]
+```
+
+### AMBOS OS MODOS
+
 **Decisoes-Chave:**
 
 Inicialize com decisoes tomadas durante questionamento:
@@ -179,6 +298,35 @@ node "$HOME/.claude/up/bin/up-tools.cjs" commit "chore: adicionar config do proj
 
 ## 5. Decisao de Pesquisa
 
+### MODO BROWNFIELD
+
+**Se `has_codebase_map` = true:**
+
+A pesquisa de stack/arquitetura ja foi feita pelo mapeamento. Oferecer pesquisa focada:
+
+Use AskUserQuestion:
+- header: "Pesquisa"
+- question: "O mapeamento do codebase ja cobriu stack e arquitetura. Quer pesquisar algo especifico?"
+- options:
+  - "Pesquisar novas tecnologias" -- Pesquisar apenas tecnologias/padroes NOVOS que voce quer adotar
+  - "Pular pesquisa" -- Conheco o que preciso, ir para requisitos
+
+**Se "Pesquisar novas tecnologias":** Pesquisa focada apenas no que e NOVO (nao re-pesquisar stack existente).
+
+**Se `has_codebase_map` = false:**
+
+Use AskUserQuestion:
+- header: "Pesquisa"
+- question: "Quer que eu analise o codebase antes de definir requisitos?"
+- options:
+  - "Mapear codebase (Recomendado)" -- Analise profunda com /up:mapear-codigo
+  - "Pesquisa leve" -- Pesquisa de ecossistema sem mapeamento completo
+  - "Pular" -- Conheco bem o projeto
+
+Se "Mapear codebase": Sugerir `/up:mapear-codigo` e depois retomar `/up:novo-projeto`. Sair.
+
+### MODO GREENFIELD
+
 Use AskUserQuestion:
 - header: "Pesquisa"
 - question: "Pesquisar o ecossistema do dominio antes de definir requisitos?"
@@ -336,6 +484,35 @@ Ler PROJECT.md e extrair:
 - Restricoes declaradas (orcamento, timeline, limitacoes tecnicas)
 - Quaisquer fronteiras de escopo explicitas
 
+### MODO BROWNFIELD
+
+**Carregar requisitos existentes do codebase:**
+
+Se `has_codebase_map` = true:
+- Ler `.plano/codebase/ARCHITECTURE.md` para features existentes
+- Ler `.plano/codebase/CONCERNS.md` para divida tecnica
+
+Apresentar o que ja existe como requisitos validados:
+
+```
+## O que ja existe (inferido do codebase)
+
+### Funcionalidades existentes
+- [Feature 1 detectada]
+- [Feature 2 detectada]
+- ...
+
+### Divida tecnica identificada
+- [Concern 1 de CONCERNS.md]
+- [Concern 2 de CONCERNS.md]
+```
+
+Pergunte: "Quais sao seus objetivos? (novas features, correcoes, refatoracao, migracoes)"
+
+Para cada objetivo, usar AskUserQuestion para escopar e priorizar.
+
+### MODO GREENFIELD
+
 **Se pesquisa existe:** Ler pesquisa/FEATURES.md e extrair categorias de features.
 
 **Apresentar features por categoria:**
@@ -363,6 +540,8 @@ Aqui estao as features para [dominio]:
 
 Pergunte: "Quais sao as principais coisas que usuarios precisam fazer?"
 
+### AMBOS OS MODOS
+
 **Escopar cada categoria:**
 
 Para cada categoria, use AskUserQuestion:
@@ -417,6 +596,8 @@ Task(prompt="
 - .plano/REQUIREMENTS.md (Requisitos v1)
 - .plano/pesquisa/SUMMARY.md (Achados de pesquisa - se existir)
 - .plano/config.json (Configuracoes de granularidade e modo)
+- .plano/codebase/CONCERNS.md (Divida tecnica - se existir, BROWNFIELD)
+- .plano/codebase/CONVENTIONS.md (Convencoes a seguir - se existir, BROWNFIELD)
 </files_to_read>
 
 </planning_context>
@@ -430,6 +611,11 @@ Criar roteiro:
 5. Escrever arquivos imediatamente (ROADMAP.md, STATE.md, atualizar REQUIREMENTS.md rastreabilidade)
 6. Retornar ROADMAP CREATED com resumo
 
+**Se projeto brownfield:**
+- Considerar divida tecnica de CONCERNS.md ao priorizar fases
+- Respeitar convencoes existentes de CONVENTIONS.md
+- Fases de refatoracao/correcao devem vir antes de features que dependem delas
+
 Escreva arquivos primeiro, depois retorne.
 </instructions>
 ", subagent_type="up-roteirista", description="Criar roteiro")
@@ -498,6 +684,8 @@ node "$HOME/.claude/up/bin/up-tools.cjs" commit "docs: criar roteiro ([N] fases)
 | Pesquisa       | `.plano/pesquisa/`        |
 | Requisitos     | `.plano/REQUIREMENTS.md`  |
 | Roteiro        | `.plano/ROADMAP.md`       |
+[Se brownfield:]
+| Codebase       | `.plano/codebase/`        |
 
 **[N] fases** | **[X] requisitos** | Pronto para construir
 
@@ -541,14 +729,17 @@ node "$HOME/.claude/up/bin/up-tools.cjs" commit "docs: criar roteiro ([N] fases)
 
 - [ ] .plano/ diretorio criado
 - [ ] Git repo inicializado
+- [ ] Modo detectado (greenfield vs brownfield)
+- [ ] Se brownfield: codebase map carregado (ou mini-scan feito)
+- [ ] Se brownfield: requisitos validados inferidos do codebase
 - [ ] Questionamento profundo completo (fios seguidos, nao apressado)
 - [ ] PROJECT.md captura contexto completo -> **committed**
 - [ ] config.json tem modo, granularidade, paralelizacao -> **committed**
-- [ ] Pesquisa completa (se selecionada) -- 4 agentes paralelos spawned -> **committed**
-- [ ] Requisitos reunidos (de pesquisa ou conversa)
+- [ ] Pesquisa completa (se selecionada) -- adaptada ao modo -> **committed**
+- [ ] Requisitos reunidos (de pesquisa, codebase ou conversa)
 - [ ] Usuario escopo cada categoria (v1/v2/fora do escopo)
 - [ ] REQUIREMENTS.md criado com REQ-IDs -> **committed**
-- [ ] up-roteirista spawned com contexto
+- [ ] up-roteirista spawned com contexto (inclui codebase docs se brownfield)
 - [ ] Arquivos do roteiro escritos imediatamente
 - [ ] Feedback do usuario incorporado (se houver)
 - [ ] ROADMAP.md criado com fases, mapeamentos de requisitos, criterios de sucesso

package/workflows/planejar-fase.md

@@ -100,6 +100,9 @@ Task(
 - {context_path} (DECISOES DO USUARIO de /up:discutir-fase)
 - {research_path} (Pesquisa Tecnica - se existir)
 - {verification_path} (Lacunas de Verificacao - se --gaps)
+- .plano/codebase/CONVENTIONS.md (Convencoes do codebase - se existir, BROWNFIELD)
+- .plano/codebase/CONCERNS.md (Divida tecnica - se existir, BROWNFIELD)
+- .plano/codebase/ARCHITECTURE.md (Arquitetura existente - se existir, BROWNFIELD)
 </files_to_read>
 
 **IDs de requisitos da fase (cada ID DEVE aparecer no campo `requirements` de um plano):** {phase_req_ids}
@@ -110,6 +113,12 @@ Se RESEARCH_INLINE=true:
 - Pesquisar o dominio antes de planejar
 - Usar Context7/docs oficiais para verificar versoes e APIs
 - Documentar achados de pesquisa no inicio de cada PLAN.md
+
+**Se arquivos de codebase existem (brownfield):**
+- Respeitar padroes e convencoes de CONVENTIONS.md nos planos
+- Considerar divida tecnica de CONCERNS.md ao definir tarefas
+- Alinhar planos com arquitetura existente de ARCHITECTURE.md
+- NAO recriar infraestrutura que ja existe
 </planning_context>
 
 <self_check>