up-cc 0.1.6 → 0.2.0

package/README.md

@@ -0,0 +1,274 @@
+<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
+
+## 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.
+
+## Inicio Rapido
+
+### Novo projeto (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
+```
+
+### 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
+```
+
+### Continuar trabalho
+
+```
+/up:retomar               # Restaura contexto da sessao anterior
+/up:progresso             # Status e proxima acao recomendada
+```
+
+### Tarefa rapida
+
+```
+/up:rapido "Corrigir bug no login"   # Executa com garantias UP
+```
+
+## Comandos
+
+### Inicializacao
+
+| 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 |
+
+### Pipeline de Fase
+
+| Comando | Descricao |
+|---------|-----------|
+| `/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 |
+| `/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 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
+```
+
+## 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
+├── 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
+│   └── ...
+└── 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
+
+## 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 |
+|---------|--------|---------|
+| 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.0",
   "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>