up-cc 0.2.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +239 -87
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -32,6 +32,7 @@ Sem UP, voce pede algo ao assistente e torce pra dar certo. Com UP:
|
|
|
32
32
|
- **Commits atomicos** rastreiam cada mudanca com mensagens descritivas
|
|
33
33
|
- **Agentes especializados** rodam em paralelo para pesquisa, planejamento, execucao e verificacao
|
|
34
34
|
- **Tarefas rapidas** tem o mesmo rigor sem a cerimonia completa
|
|
35
|
+
- **Detecta projetos existentes** e adapta o fluxo automaticamente (brownfield)
|
|
35
36
|
|
|
36
37
|
## Instalacao
|
|
37
38
|
|
|
@@ -56,72 +57,261 @@ npx up-cc@latest --uninstall
|
|
|
56
57
|
|
|
57
58
|
Apos instalar, reinicie o Claude Code e digite `/up:ajuda` para ver todos os comandos.
|
|
58
59
|
|
|
59
|
-
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## Manual de Uso
|
|
63
|
+
|
|
64
|
+
### 1. Inicializando um projeto
|
|
65
|
+
|
|
66
|
+
O UP funciona tanto para projetos novos (greenfield) quanto para codebases existentes (brownfield). A deteccao e automatica.
|
|
60
67
|
|
|
61
|
-
|
|
68
|
+
#### Projeto novo (do zero)
|
|
62
69
|
|
|
63
70
|
```
|
|
64
|
-
/up:novo-projeto
|
|
65
|
-
/up:discutir-fase 1 # Discute requisitos da fase 1
|
|
66
|
-
/up:planejar-fase 1 # Cria planos executaveis
|
|
67
|
-
/up:executar-fase 1 # Executa com commits atomicos
|
|
68
|
-
/up:verificar-trabalho 1 # UAT conversacional
|
|
71
|
+
/up:novo-projeto
|
|
69
72
|
```
|
|
70
73
|
|
|
71
|
-
|
|
74
|
+
O UP vai:
|
|
75
|
+
1. Perguntar "O que voce quer construir?"
|
|
76
|
+
2. Fazer perguntas de acompanhamento para entender o projeto
|
|
77
|
+
3. Opcionalmente pesquisar o ecossistema do dominio (stack, features, armadilhas)
|
|
78
|
+
4. Definir requisitos interativamente, agrupados por categoria
|
|
79
|
+
5. Gerar ROADMAP.md com fases, criterios de sucesso e rastreabilidade
|
|
80
|
+
6. Criar PROJECT.md, STATE.md e config.json
|
|
81
|
+
|
|
82
|
+
Ao final voce tera um `.plano/` completo pronto para o pipeline de fases.
|
|
83
|
+
|
|
84
|
+
#### Projeto existente (brownfield)
|
|
72
85
|
|
|
73
86
|
```
|
|
74
|
-
/up:mapear-codigo #
|
|
75
|
-
/up:novo-projeto #
|
|
76
|
-
/up:discutir-fase 1 # Continua normalmente
|
|
87
|
+
/up:mapear-codigo # Opcional, mas recomendado
|
|
88
|
+
/up:novo-projeto # Detecta brownfield automaticamente
|
|
77
89
|
```
|
|
78
90
|
|
|
79
|
-
|
|
91
|
+
Se voce tem codigo no diretorio, o UP detecta e adapta:
|
|
92
|
+
- Carrega o mapeamento do codebase (se `/up:mapear-codigo` ja rodou)
|
|
93
|
+
- Pergunta "O que voce quer **fazer** com esse codigo?" em vez de "O que voce quer construir?"
|
|
94
|
+
- Infere requisitos **validados** do codebase existente (features que ja funcionam)
|
|
95
|
+
- Separa seus novos objetivos como requisitos **ativos**
|
|
96
|
+
- Pesquisa foca em tecnologias **novas**, nao nas que voce ja usa
|
|
97
|
+
- Todo o pipeline downstream (discutir, planejar, executar) recebe contexto do codebase
|
|
98
|
+
|
|
99
|
+
O `/up:mapear-codigo` produz 7 documentos em `.plano/codebase/`:
|
|
100
|
+
|
|
101
|
+
| Documento | Conteudo |
|
|
102
|
+
|-----------|----------|
|
|
103
|
+
| STACK.md | Tecnologias, frameworks, dependencias |
|
|
104
|
+
| ARCHITECTURE.md | Design do sistema, fluxo de dados, padroes |
|
|
105
|
+
| STRUCTURE.md | Organizacao de diretorios e arquivos |
|
|
106
|
+
| CONVENTIONS.md | Estilo de codigo, nomeacao, padroes de erro |
|
|
107
|
+
| INTEGRATIONS.md | APIs externas, banco de dados, autenticacao |
|
|
108
|
+
| TESTING.md | Infraestrutura de testes, cobertura |
|
|
109
|
+
| CONCERNS.md | Divida tecnica, areas frageis, seguranca |
|
|
110
|
+
|
|
111
|
+
Esses documentos alimentam automaticamente o restante do pipeline.
|
|
112
|
+
|
|
113
|
+
#### Reinicializando um projeto
|
|
114
|
+
|
|
115
|
+
Se voce ja tem um `.plano/PROJECT.md` e roda `/up:novo-projeto` novamente, o UP oferece:
|
|
116
|
+
- **Revisar e atualizar** — Atualizar com novos objetivos
|
|
117
|
+
- **Recomecar do zero** — Recriar tudo
|
|
118
|
+
- **Cancelar** — Manter como esta
|
|
119
|
+
|
|
120
|
+
### 2. O pipeline de fases
|
|
121
|
+
|
|
122
|
+
Cada fase do roadmap passa por um pipeline de 4 etapas. Voce controla o ritmo — cada etapa e um comando separado.
|
|
123
|
+
|
|
124
|
+
#### Etapa 1: Discutir (`/up:discutir-fase N`)
|
|
80
125
|
|
|
81
126
|
```
|
|
82
|
-
/up:
|
|
83
|
-
/up:progresso # Status e proxima acao recomendada
|
|
127
|
+
/up:discutir-fase 1
|
|
84
128
|
```
|
|
85
129
|
|
|
86
|
-
|
|
130
|
+
O UP analisa a fase e identifica **areas cinzentas** — ambiguidades que mudariam a implementacao. Voce escolhe quais discutir.
|
|
131
|
+
|
|
132
|
+
- Perguntas sao adaptadas ao que ja foi decidido em fases anteriores
|
|
133
|
+
- Se o projeto e brownfield, carrega ARCHITECTURE.md e CONVENTIONS.md para perguntas informadas
|
|
134
|
+
- Ideias fora do escopo sao anotadas como "adiadas", nao perdidas
|
|
135
|
+
- Resultado: `CONTEXT.md` com decisoes capturadas
|
|
136
|
+
|
|
137
|
+
**Quando pular:** Se a fase e infraestrutura pura ou a implementacao e obvia, voce pode ir direto para planejar.
|
|
138
|
+
|
|
139
|
+
#### Etapa 2: Planejar (`/up:planejar-fase N`)
|
|
87
140
|
|
|
88
141
|
```
|
|
89
|
-
/up:
|
|
142
|
+
/up:planejar-fase 1
|
|
90
143
|
```
|
|
91
144
|
|
|
92
|
-
|
|
145
|
+
Spawna o agente **up-planejador** que:
|
|
146
|
+
- Le CONTEXT.md, ROADMAP.md, REQUIREMENTS.md e codebase docs
|
|
147
|
+
- Faz pesquisa inline se necessario (busca docs, verifica APIs)
|
|
148
|
+
- Cria PLAN-001.md, PLAN-002.md, etc. com tarefas especificas
|
|
149
|
+
- Auto-verifica: cobertura de requisitos, dependencias, waves de execucao
|
|
150
|
+
- Resultado: Planos executaveis prontos
|
|
93
151
|
|
|
94
|
-
|
|
152
|
+
Flags uteis:
|
|
153
|
+
- `--pesquisar` — Forcar pesquisa profunda antes de planejar
|
|
154
|
+
- `--sem-pesquisa` — Pular pesquisa, ir direto
|
|
155
|
+
- `--gaps` — Replanejar a partir de lacunas do verificar-trabalho
|
|
95
156
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
157
|
+
#### Etapa 3: Executar (`/up:executar-fase N`)
|
|
158
|
+
|
|
159
|
+
```
|
|
160
|
+
/up:executar-fase 1
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
Spawna agentes **up-executor** que:
|
|
164
|
+
- Executam planos organizados em **waves** (planos independentes rodam em paralelo)
|
|
165
|
+
- Cada plano produz commits atomicos com mensagens descritivas
|
|
166
|
+
- Resultado: Codigo implementado e commitado, SUMMARY.md criado
|
|
167
|
+
|
|
168
|
+
#### Etapa 4: Verificar (`/up:verificar-trabalho N`)
|
|
169
|
+
|
|
170
|
+
```
|
|
171
|
+
/up:verificar-trabalho 1
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Verificacao goal-backward (parte do resultado desejado e volta):
|
|
175
|
+
- Testa se os criterios de sucesso da fase foram atingidos
|
|
176
|
+
- Se encontra gaps: gera VERIFICATION.md com detalhes
|
|
177
|
+
- Resultado: Fase aprovada ou lista de gaps para corrigir
|
|
178
|
+
|
|
179
|
+
#### Ciclo de correcao de gaps
|
|
180
|
+
|
|
181
|
+
Se a verificacao encontrou problemas:
|
|
182
|
+
|
|
183
|
+
```
|
|
184
|
+
/up:planejar-fase 1 --gaps # Cria planos de correcao baseados no VERIFICATION.md
|
|
185
|
+
/up:executar-fase 1 --gaps-only # Executa apenas os planos de correcao
|
|
186
|
+
/up:verificar-trabalho 1 # Re-verifica
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
### 3. Gerenciamento do projeto
|
|
190
|
+
|
|
191
|
+
#### Ver progresso
|
|
192
|
+
|
|
193
|
+
```
|
|
194
|
+
/up:progresso
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
Mostra dashboard com: fase atual, porcentagem de conclusao, bloqueios, e sugere o proximo comando a rodar.
|
|
198
|
+
|
|
199
|
+
#### Pausar e retomar
|
|
200
|
+
|
|
201
|
+
```
|
|
202
|
+
/up:pausar # Cria .continue-aqui.md com contexto completo
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
Na proxima sessao (ou apos `/clear`):
|
|
206
|
+
|
|
207
|
+
```
|
|
208
|
+
/up:retomar # Le .continue-aqui.md e STATE.md, restaura tudo
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
O UP foi desenhado para sobreviver a `/clear`. Todo estado fica em disco no `.plano/`.
|
|
212
|
+
|
|
213
|
+
#### Adicionar e remover fases
|
|
214
|
+
|
|
215
|
+
```
|
|
216
|
+
/up:adicionar-fase "Implementar sistema de notificacoes" # Adiciona ao final
|
|
217
|
+
/up:remover-fase 5 # Remove e renumera
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
Apenas fases futuras (nao iniciadas) podem ser removidas.
|
|
221
|
+
|
|
222
|
+
### 4. Tarefas rapidas
|
|
223
|
+
|
|
224
|
+
Para tarefas pequenas que nao justificam uma fase inteira:
|
|
225
|
+
|
|
226
|
+
```
|
|
227
|
+
/up:rapido "Corrigir bug no formulario de login"
|
|
228
|
+
/up:rapido "Adicionar favicon"
|
|
229
|
+
/up:rapido "Atualizar dependencias"
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
O `/up:rapido` faz o mesmo pipeline simplificado:
|
|
233
|
+
- Planeja e executa em um unico fluxo
|
|
234
|
+
- Commits atomicos com rastreamento
|
|
235
|
+
- Tarefas ficam em `.plano/rapido/TASK-NNN.md`
|
|
236
|
+
- Nao afeta ROADMAP.md — e separado das fases
|
|
237
|
+
|
|
238
|
+
### 5. Depuracao
|
|
101
239
|
|
|
102
|
-
|
|
240
|
+
Para bugs complexos que precisam de investigacao sistematica:
|
|
241
|
+
|
|
242
|
+
```
|
|
243
|
+
/up:depurar "Botao de salvar nao funciona na pagina de perfil"
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
O depurador:
|
|
247
|
+
- Coleta sintomas (comportamento esperado, real, erros, reproducao)
|
|
248
|
+
- Spawna agente **up-depurador** que investiga com metodo cientifico
|
|
249
|
+
- Forma hipoteses falsificaveis, testa uma de cada vez
|
|
250
|
+
- Mantém sessao persistente em `.plano/debug/` (sobrevive a `/clear`)
|
|
251
|
+
- Ao encontrar a causa raiz, oferece corrigir automaticamente
|
|
252
|
+
|
|
253
|
+
Sessoes ativas podem ser retomadas:
|
|
254
|
+
|
|
255
|
+
```
|
|
256
|
+
/up:depurar # Sem argumento: lista sessoes ativas
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
### 6. Testes
|
|
260
|
+
|
|
261
|
+
Apos completar uma fase, gerar testes automaticamente:
|
|
262
|
+
|
|
263
|
+
```
|
|
264
|
+
/up:adicionar-testes 1
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
O UP:
|
|
268
|
+
- Analisa todos os arquivos modificados pela fase
|
|
269
|
+
- Classifica cada um: unitario (TDD), E2E (browser) ou pular
|
|
270
|
+
- Apresenta classificacao para aprovacao
|
|
271
|
+
- Gera testes seguindo convencoes do projeto
|
|
272
|
+
- Reporta: passando, falhando, gaps de cobertura, bugs descobertos
|
|
273
|
+
|
|
274
|
+
### 7. Configuracao
|
|
275
|
+
|
|
276
|
+
```
|
|
277
|
+
/up:configurar
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
| Opcao | Default | Descricao |
|
|
281
|
+
|-------|---------|-----------|
|
|
282
|
+
| Modo | solo | `solo` (commits diretos) ou `time` (branches por fase) |
|
|
283
|
+
| Paralelizacao | sim | Agentes rodam em paralelo quando independentes |
|
|
284
|
+
| Commit Docs | sim | Commitar documentos de planejamento automaticamente |
|
|
285
|
+
| Auto-Advance | nao | Encadear estagios automaticamente |
|
|
286
|
+
|
|
287
|
+
### 8. Manutencao
|
|
288
|
+
|
|
289
|
+
```
|
|
290
|
+
/up:saude # Diagnostica integridade do .plano/
|
|
291
|
+
/up:saude --reparar # Corrige problemas automaticamente
|
|
292
|
+
/up:atualizar # Verifica e instala atualizacoes do UP
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
---
|
|
296
|
+
|
|
297
|
+
## Referencia Rapida
|
|
298
|
+
|
|
299
|
+
### Comandos
|
|
103
300
|
|
|
104
301
|
| Comando | Descricao |
|
|
105
302
|
|---------|-----------|
|
|
303
|
+
| `/up:novo-projeto` | Inicializar projeto (detecta greenfield/brownfield) |
|
|
304
|
+
| `/up:mapear-codigo` | Analisar codebase existente com agentes paralelos |
|
|
305
|
+
| `/up:retomar` | Restaurar contexto da sessao anterior |
|
|
106
306
|
| `/up:discutir-fase N` | Coletar contexto por questionamento estruturado |
|
|
107
307
|
| `/up:planejar-fase N` | Criar planos executaveis com pesquisa e self-check |
|
|
108
308
|
| `/up:executar-fase N` | Executar planos com paralelizacao por ondas |
|
|
109
309
|
| `/up:verificar-trabalho N` | Validar features via UAT conversacional |
|
|
110
|
-
|
|
111
|
-
### Gerenciamento
|
|
112
|
-
|
|
113
|
-
| Comando | Descricao |
|
|
114
|
-
|---------|-----------|
|
|
115
310
|
| `/up:progresso` | Dashboard de status e proxima acao |
|
|
116
311
|
| `/up:pausar` | Criar arquivo de handoff `.continue-aqui.md` |
|
|
117
312
|
| `/up:adicionar-fase "desc"` | Adicionar fase ao final do roadmap |
|
|
118
313
|
| `/up:remover-fase N` | Remover fase futura e renumerar |
|
|
119
314
|
| `/up:adicionar-testes N` | Gerar testes para fase completa |
|
|
120
|
-
|
|
121
|
-
### Utilitarios
|
|
122
|
-
|
|
123
|
-
| Comando | Descricao |
|
|
124
|
-
|---------|-----------|
|
|
125
315
|
| `/up:rapido "tarefa"` | Tarefa rapida com commits atomicos |
|
|
126
316
|
| `/up:depurar` | Depuracao sistematica com metodo cientifico |
|
|
127
317
|
| `/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
|
|
|
142
332
|
--gaps-only Executar apenas planos de fechamento de gaps
|
|
143
333
|
```
|
|
144
334
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
```
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
┌────────────────▼─────────────────────────┐
|
|
154
|
-
│ /up:discutir-fase N │
|
|
155
|
-
│ Questionamento → CONTEXT.md │
|
|
156
|
-
└────────────────┬─────────────────────────┘
|
|
157
|
-
│
|
|
158
|
-
┌────────────────▼─────────────────────────┐
|
|
159
|
-
│ /up:planejar-fase N │
|
|
160
|
-
│ Pesquisa + Planejamento → PLAN-NNN.md │
|
|
161
|
-
└────────────────┬─────────────────────────┘
|
|
162
|
-
│
|
|
163
|
-
┌────────────────▼─────────────────────────┐
|
|
164
|
-
│ /up:executar-fase N │
|
|
165
|
-
│ Execucao paralela → Commits atomicos │
|
|
166
|
-
└────────────────┬─────────────────────────┘
|
|
167
|
-
│
|
|
168
|
-
┌────────────────▼─────────────────────────┐
|
|
169
|
-
│ /up:verificar-trabalho N │
|
|
170
|
-
│ UAT conversacional → VERIFICATION.md │
|
|
171
|
-
└────────────────┬─────────────────────────┘
|
|
172
|
-
│
|
|
173
|
-
Gaps encontrados?
|
|
174
|
-
├── Sim → /up:planejar-fase N --gaps
|
|
175
|
-
└── Nao → Proxima fase
|
|
335
|
+
### Pipeline
|
|
336
|
+
|
|
337
|
+
```
|
|
338
|
+
/up:novo-projeto → /up:discutir-fase N → /up:planejar-fase N → /up:executar-fase N → /up:verificar-trabalho N
|
|
339
|
+
│
|
|
340
|
+
Gaps? ─┤
|
|
341
|
+
Sim → /up:planejar-fase N --gaps
|
|
342
|
+
Nao → Proxima fase
|
|
176
343
|
```
|
|
177
344
|
|
|
178
345
|
## Estrutura do `.plano/`
|
|
179
346
|
|
|
180
|
-
O UP cria e mantém um diretorio `.plano/` na raiz do projeto:
|
|
181
|
-
|
|
182
347
|
```
|
|
183
348
|
.plano/
|
|
184
349
|
├── PROJECT.md # O que e o projeto, requisitos, decisoes
|
|
185
350
|
├── ROADMAP.md # Todas as fases com status
|
|
186
351
|
├── STATE.md # Posicao atual, progresso, continuidade
|
|
187
352
|
├── config.json # Configuracoes do workflow
|
|
353
|
+
├── codebase/ # Mapeamento do codebase (brownfield)
|
|
354
|
+
│ ├── STACK.md
|
|
355
|
+
│ ├── ARCHITECTURE.md
|
|
356
|
+
│ ├── CONVENTIONS.md
|
|
357
|
+
│ ├── CONCERNS.md
|
|
358
|
+
│ └── ...
|
|
188
359
|
├── fases/
|
|
189
360
|
│ ├── 01-autenticacao/
|
|
190
361
|
│ │ ├── CONTEXT.md # Contexto coletado na discussao
|
|
191
362
|
│ │ ├── RESEARCH.md # Pesquisa de dominio/tecnologia
|
|
192
363
|
│ │ ├── PLAN-001.md # Plano executavel
|
|
193
|
-
│ │ ├── PLAN-002.md # Outro plano (se necessario)
|
|
194
364
|
│ │ ├── SUMMARY-001.md # Resultado da execucao
|
|
195
365
|
│ │ └── VERIFICATION.md # Resultado do UAT
|
|
196
|
-
│ ├── 02-dashboard/
|
|
197
|
-
│ │ └── ...
|
|
198
366
|
│ └── ...
|
|
199
367
|
├── rapido/
|
|
200
|
-
│
|
|
201
|
-
│ └── ...
|
|
368
|
+
│ └── TASK-001.md # Tarefa rapida executada
|
|
202
369
|
└── debug/
|
|
203
370
|
├── bug-login.md # Sessao de debug ativa
|
|
204
371
|
└── resolved/ # Sessoes resolvidas
|
|
@@ -237,21 +404,6 @@ O UP sobrevive a `/clear` e reinicializacoes do CLI:
|
|
|
237
404
|
3. **Retomada** — `/up:retomar` le os arquivos de estado e restaura o contexto completo
|
|
238
405
|
4. **Debug persistente** — Sessoes de debug em `.plano/debug/` sobrevivem entre conversas
|
|
239
406
|
|
|
240
|
-
## Configuracao
|
|
241
|
-
|
|
242
|
-
```
|
|
243
|
-
/up:configurar
|
|
244
|
-
```
|
|
245
|
-
|
|
246
|
-
Opcoes disponiveis:
|
|
247
|
-
|
|
248
|
-
| Opcao | Default | Descricao |
|
|
249
|
-
|-------|---------|-----------|
|
|
250
|
-
| Modo | solo | `solo` (commits diretos) ou `time` (branches por fase) |
|
|
251
|
-
| Paralelizacao | sim | Agentes rodam em paralelo quando independentes |
|
|
252
|
-
| Commit Docs | sim | Commitar documentos de planejamento automaticamente |
|
|
253
|
-
| Auto-Advance | nao | Encadear estagios automaticamente |
|
|
254
|
-
|
|
255
407
|
## Compatibilidade
|
|
256
408
|
|
|
257
409
|
| Runtime | Status | Formato |
|