up-cc 0.1.0

package/workflows/discutir-fase.md

@@ -0,0 +1,324 @@
+<purpose>
+Extrair decisoes de implementacao que agentes downstream precisam. Analisar a fase para identificar areas cinzentas, deixar o usuario escolher o que discutir, entao aprofundar em cada area selecionada ate ficar satisfeito.
+
+Voce e um parceiro de pensamento, nao um entrevistador. O usuario e o visionario -- voce e o construtor. Seu trabalho e capturar decisoes que guiarao pesquisa e planejamento.
+</purpose>
+
+<scope_guardrail>
+**CRITICO: Sem inflacao de escopo.**
+
+O limite da fase vem do ROADMAP.md e e FIXO. Discussao esclarece COMO implementar o que esta no escopo, nunca SE adicionar novas capacidades.
+
+**Permitido (esclarecer ambiguidade):**
+- "Como posts devem ser exibidos?" (layout, densidade, info mostrada)
+- "O que acontece no estado vazio?" (dentro da feature)
+
+**Nao permitido (inflacao de escopo):**
+- "Devemos tambem adicionar comentarios?" (nova capacidade)
+- "E sobre busca/filtragem?" (nova capacidade)
+
+**Quando usuario sugere inflacao de escopo:**
+```
+"[Feature X] seria uma nova capacidade -- e uma fase propria.
+Quer que eu anote para o backlog do roteiro?
+
+Por agora, vamos focar em [dominio da fase]."
+```
+
+Capturar a ideia em secao "Ideias Adiadas". Nao perca, nao atue sobre ela.
+</scope_guardrail>
+
+<process>
+
+<step name="initialize" priority="first">
+Numero da fase do argumento (obrigatorio).
+
+```bash
+INIT=$(node "$HOME/.claude/up/bin/up-tools.cjs" init phase-op "${PHASE}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse JSON: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `plan_count`, `roadmap_exists`, `planning_exists`.
+
+**Se `phase_found` = false:**
+```
+Fase [X] nao encontrada no roteiro.
+
+Use /up:progresso para ver fases disponiveis.
+```
+Sair do workflow.
+
+**Se `phase_found` = true:** Continuar para check_existing.
+</step>
+
+<step name="check_existing">
+Verificar se CONTEXT.md ja existe usando `has_context` do init.
+
+**Se existe:**
+Use AskUserQuestion:
+- header: "Contexto"
+- question: "Fase [X] ja tem contexto. O que voce quer fazer?"
+- options:
+  - "Atualizar" -- Revisar e atualizar contexto existente
+  - "Ver" -- Mostrar o que tem la
+  - "Pular" -- Usar contexto existente como esta
+
+Se "Atualizar": Carregar existente, continuar para analyze_phase
+Se "Ver": Exibir CONTEXT.md, depois oferecer atualizar/pular
+Se "Pular": Sair do workflow
+
+**Se nao existe:** Continuar para load_prior_context.
+</step>
+
+<step name="load_prior_context">
+Ler contexto de nivel de projeto e de fases anteriores para evitar re-perguntar questoes ja decididas.
+
+**Passo 1: Ler arquivos do projeto**
+```bash
+cat .plano/PROJECT.md 2>/dev/null
+cat .plano/REQUIREMENTS.md 2>/dev/null
+cat .plano/STATE.md 2>/dev/null
+```
+
+Extrair:
+- **PROJECT.md** -- Visao, principios, nao-negociaveis, preferencias do usuario
+- **REQUIREMENTS.md** -- Criterios de aceitacao, restricoes
+- **STATE.md** -- Progresso atual, flags ou notas
+
+**Passo 2: Ler todos CONTEXT.md de fases anteriores**
+```bash
+find .plano/fases -name "*-CONTEXT.md" 2>/dev/null | sort
+```
+
+Para cada CONTEXT.md onde numero da fase < fase atual:
+- Ler secao `<decisions>` -- sao preferencias travadas
+- Ler `<specifics>` -- referencias particulares ou momentos "quero como X"
+- Notar padroes
+
+**Passo 3: Construir contexto interno `<prior_decisions>`**
+
+**Uso nos passos seguintes:**
+- `analyze_phase`: Pular areas cinzentas ja decididas
+- `present_gray_areas`: Anotar opcoes com decisoes anteriores
+- `discuss_areas`: Pre-preencher respostas ou sinalizar conflitos
+</step>
+
+<step name="analyze_phase">
+Analisar a fase para identificar areas cinzentas que valem discussao.
+
+**Ler descricao da fase do ROADMAP.md e determinar:**
+
+1. **Limite do dominio** -- Qual capacidade essa fase entrega? Declarar claramente.
+
+2. **Verificar decisoes anteriores** -- Antes de gerar areas cinzentas, verificar se ja foram decididas.
+
+3. **Areas cinzentas por categoria** -- Para cada categoria relevante, identificar 1-2 ambiguidades especificas que mudariam implementacao.
+
+4. **Avaliacao de pulo** -- Se nao ha areas cinzentas significativas (infraestrutura pura, implementacao clara, ou tudo ja decidido), a fase pode nao precisar de discussao.
+</step>
+
+<step name="present_gray_areas">
+Apresentar limite do dominio, decisoes anteriores e areas cinzentas ao usuario.
+
+**Primeiro, declarar limite e decisoes anteriores que se aplicam:**
+```
+Fase [X]: [Nome]
+Dominio: [O que esta fase entrega -- da sua analise]
+
+Vamos esclarecer COMO implementar isso.
+(Novas capacidades pertencem a outras fases.)
+
+[Se decisoes anteriores se aplicam:]
+**Herdado de fases anteriores:**
+- [Decisao da Fase N que se aplica aqui]
+```
+
+**Usar AskUserQuestion (multiSelect: true):**
+- header: "Discutir"
+- question: "Quais areas voce quer discutir para [nome da fase]?"
+- options: Gerar 3-4 areas cinzentas especificas da fase
+
+**NAO incluir opcao "pular" ou "voce decide".** Usuario executou este comando para discutir.
+</step>
+
+<step name="discuss_areas">
+Para cada area selecionada, conduzir loop de discussao focada.
+
+**Filosofia: 4 perguntas, depois verificar.**
+
+**Para cada area:**
+
+1. **Anunciar a area:**
+   ```
+   Vamos falar sobre [Area].
+   ```
+
+2. **Perguntar 4 questoes usando AskUserQuestion:**
+   - header: "[Area]" (max 12 chars)
+   - question: Decisao especifica para esta area
+   - options: 2-3 escolhas concretas, com escolha recomendada destacada
+   - Incluir "Voce decide" como opcao quando razoavel
+
+3. **Apos 4 perguntas, verificar:**
+   - header: "[Area]" (max 12 chars)
+   - question: "Mais perguntas sobre [area], ou ir para proxima?"
+   - options: "Mais perguntas" / "Proxima area"
+
+4. **Apos todas areas selecionadas completarem:**
+   - Resumir o que foi capturado
+   - AskUserQuestion:
+     - header: "Pronto"
+     - question: "Discutimos [listar areas]. Quais areas cinzentas permanecem?"
+     - options: "Explorar mais areas" / "Pronto para contexto"
+   - Se "Explorar mais": identificar 2-4 areas adicionais, voltar ao loop
+   - Se "Pronto para contexto": Prosseguir para write_context
+
+**Tratamento de inflacao de escopo:**
+Se usuario mencionar algo fora do dominio da fase:
+```
+"[Feature] parece uma nova capacidade -- pertence a propria fase.
+Vou anotar como ideia adiada.
+
+Voltando para [area atual]: [retornar a pergunta atual]"
+```
+</step>
+
+<step name="write_context">
+Criar CONTEXT.md capturando decisoes tomadas.
+
+Usar valores do init: `phase_dir`, `phase_slug`, `padded_phase`.
+
+Se `phase_dir` e null:
+```bash
+mkdir -p ".plano/fases/${padded_phase}-${phase_slug}"
+```
+
+**Local do arquivo:** `${phase_dir}/${padded_phase}-CONTEXT.md`
+
+```markdown
+# Fase [X]: [Nome] - Contexto
+
+**Reunido:** [data]
+**Status:** Pronto para planejamento
+
+<domain>
+## Limite da Fase
+
+[Declaracao clara do que esta fase entrega -- a ancora de escopo]
+
+</domain>
+
+<decisions>
+## Decisoes de Implementacao
+
+### [Categoria 1 discutida]
+- [Decisao ou preferencia capturada]
+
+### [Categoria 2 discutida]
+- [Decisao ou preferencia capturada]
+
+### Criterio do Claude
+[Areas onde usuario disse "voce decide"]
+
+</decisions>
+
+<specifics>
+## Ideias Especificas
+
+[Referencias particulares, exemplos, ou momentos "quero como X"]
+
+[Se nenhum: "Sem requisitos especificos -- aberto a abordagens padrao"]
+
+</specifics>
+
+<deferred>
+## Ideias Adiadas
+
+[Ideias que surgiram mas pertencem a outras fases.]
+
+[Se nenhuma: "Nenhuma -- discussao manteve-se no escopo da fase"]
+
+</deferred>
+
+---
+
+*Fase: XX-nome*
+*Contexto reunido: [data]*
+```
+
+Escrever arquivo.
+</step>
+
+<step name="confirm_creation">
+Apresentar resumo e proximos passos:
+
+```
+Criado: .plano/fases/${PADDED_PHASE}-${SLUG}/${PADDED_PHASE}-CONTEXT.md
+
+## Decisoes Capturadas
+
+### [Categoria]
+- [Decisao-chave]
+
+[Se ideias adiadas existem:]
+## Anotado para Depois
+- [Ideia adiada] -- fase futura
+
+---
+
+## Proximo
+
+**Fase ${PHASE}: [Nome]** -- [Objetivo do ROADMAP.md]
+
+`/up:planejar-fase ${PHASE}`
+
+<sub>`/clear` primeiro -> janela de contexto limpa</sub>
+
+---
+
+**Tambem disponivel:**
+- Revisar/editar CONTEXT.md antes de continuar
+
+---
+```
+</step>
+
+<step name="git_commit">
+Commit do contexto da fase:
+
+```bash
+node "$HOME/.claude/up/bin/up-tools.cjs" commit "docs(${padded_phase}): capturar contexto da fase" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
+```
+</step>
+
+<step name="update_state">
+Atualizar STATE.md com info da sessao:
+
+```bash
+node "$HOME/.claude/up/bin/up-tools.cjs" state record-session \
+  --stopped-at "Fase ${PHASE} contexto reunido" \
+  --resume-file "${phase_dir}/${padded_phase}-CONTEXT.md"
+```
+
+Commit STATE.md:
+
+```bash
+node "$HOME/.claude/up/bin/up-tools.cjs" commit "docs(state): registrar sessao de contexto fase ${PHASE}" --files .plano/STATE.md
+```
+</step>
+
+</process>
+
+<success_criteria>
+- Fase validada contra roteiro
+- Contexto anterior carregado (PROJECT.md, REQUIREMENTS.md, STATE.md, CONTEXT.md anteriores)
+- Questoes ja decididas nao re-perguntadas
+- Areas cinzentas identificadas com analise inteligente
+- Usuario selecionou quais areas discutir
+- Cada area explorada ate usuario ficar satisfeito
+- Inflacao de escopo redirecionada para ideias adiadas
+- CONTEXT.md captura decisoes reais, nao visao vaga
+- Ideias adiadas preservadas para fases futuras
+- STATE.md atualizado com info da sessao
+- Usuario sabe proximos passos
+</success_criteria>

package/workflows/executar-fase.md

@@ -0,0 +1,277 @@
+<purpose>
+Executar todos os planos em uma fase usando execucao paralela baseada em waves. Orquestrador fica enxuto -- delega execucao de planos a subagentes.
+</purpose>
+
+<core_principle>
+Orquestrador coordena, nao executa. Cada subagente carrega o contexto completo de execute-plan. Orquestrador: descobrir planos -> analisar deps -> agrupar waves -> spawn agentes -> tratar checkpoints -> coletar resultados.
+</core_principle>
+
+<process>
+
+<step name="initialize" priority="first">
+Carregar contexto:
+
+```bash
+INIT=$(node "$HOME/.claude/up/bin/up-tools.cjs" init execute-phase "${PHASE_ARG}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse JSON: `executor_model`, `verifier_model`, `commit_docs`, `parallelization`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`, `phase_req_ids`.
+
+**Se `phase_found` = false:** Erro -- diretorio da fase nao encontrado.
+**Se `plan_count` = 0:** Erro -- sem planos encontrados na fase.
+
+Quando `parallelization` = false, planos dentro de uma wave executam sequencialmente.
+</step>
+
+<step name="validate_phase">
+Do init JSON: `phase_dir`, `plan_count`, `incomplete_count`.
+
+Reportar: "Encontrados {plan_count} planos em {phase_dir} ({incomplete_count} incompletos)"
+</step>
+
+<step name="discover_and_group_plans">
+Carregar inventario de planos com agrupamento por wave:
+
+```bash
+PLAN_INDEX=$(node "$HOME/.claude/up/bin/up-tools.cjs" phase-plan-index "${PHASE_NUMBER}")
+```
+
+Parse JSON: `phase`, `plans[]` (cada com `id`, `wave`, `autonomous`, `objective`, `files_modified`, `task_count`, `has_summary`), `waves`, `incomplete`, `has_checkpoints`.
+
+**Filtrar:** Pular planos onde `has_summary: true`. Se todos filtrados: "Sem planos incompletos" -> sair.
+
+Reportar:
+```
+## Plano de Execucao
+
+**Fase {X}: {Nome}** -- {total_plans} planos em {wave_count} waves
+
+| Wave | Planos | O que constroi |
+|------|--------|----------------|
+| 1 | 01-01, 01-02 | {dos objetivos dos planos, 3-8 palavras} |
+| 2 | 01-03 | ... |
+```
+</step>
+
+<step name="execute_waves">
+Executar cada wave em sequencia. Dentro de uma wave: paralelo se `PARALLELIZATION=true`, sequencial se `false`.
+
+**Para cada wave:**
+
+1. **Descrever o que esta sendo construido (ANTES do spawn):**
+
+   Ler `<objective>` de cada plano. Extrair o que esta sendo construido e por que.
+
+   ```
+   ---
+   ## Wave {N}
+
+   **{Plan ID}: {Nome do Plano}**
+   {2-3 sentencas: o que isso constroi, abordagem tecnica, por que importa}
+
+   Spawning {count} agente(s)...
+   ---
+   ```
+
+2. **Spawn agentes executores:**
+
+   Passar apenas caminhos -- executores leem arquivos eles mesmos com contexto limpo de 200k.
+
+   ```
+   Task(
+     subagent_type="up-executor",
+     prompt="
+       <objective>
+       Executar plano {plan_number} da fase {phase_number}-{phase_name}.
+       Commitar cada tarefa atomicamente. Criar SUMMARY.md. Atualizar STATE.md e ROADMAP.md.
+       </objective>
+
+       <execution_context>
+       @~/.claude/up/workflows/executar-plano.md
+       @~/.claude/up/references/checkpoints.md
+       </execution_context>
+
+       <files_to_read>
+       Ler estes arquivos no inicio da execucao usando a ferramenta Read:
+       - {phase_dir}/{plan_file} (Plano)
+       - .plano/STATE.md (Estado)
+       - .plano/config.json (Config, se existir)
+       - ./CLAUDE.md (Instrucoes do projeto, se existir)
+       </files_to_read>
+
+       <success_criteria>
+       - [ ] Todas tarefas executadas
+       - [ ] Cada tarefa committed individualmente
+       - [ ] SUMMARY.md criado no diretorio do plano
+       - [ ] STATE.md atualizado com posicao e decisoes
+       - [ ] ROADMAP.md atualizado com progresso do plano (via `roadmap update-plan-progress`)
+       </success_criteria>
+     "
+   )
+   ```
+
+3. **Esperar todos agentes na wave completarem.**
+
+4. **Reportar conclusao -- spot-check claims primeiro:**
+
+   Para cada SUMMARY.md:
+   - Verificar que primeiros 2 arquivos de `key-files.created` existem no disco
+   - Verificar `git log --oneline --all --grep="{phase}-{plan}"` retorna >= 1 commit
+   - Verificar marcador `## Self-Check: FAILED`
+
+   Se algum spot-check falhar: reportar qual plano falhou, perguntar "Tentar novamente?" ou "Continuar com waves restantes?"
+
+   Se passar:
+   ```
+   ---
+   ## Wave {N} Completa
+
+   **{Plan ID}: {Nome do Plano}**
+   {O que foi construido -- do SUMMARY.md}
+
+   {Se mais waves: o que isso habilita para proxima wave}
+   ---
+   ```
+
+5. **Tratar falhas:**
+   Para falhas reais: reportar qual plano falhou -> perguntar "Continuar?" ou "Parar?" -> se continuar, planos dependentes podem tambem falhar.
+
+6. **Prosseguir para proxima wave.**
+</step>
+
+<step name="aggregate_results">
+Apos todas waves:
+
+```markdown
+## Fase {X}: {Nome} Execucao Completa
+
+**Waves:** {N} | **Planos:** {M}/{total} completos
+
+| Wave | Planos | Status |
+|------|--------|--------|
+| 1 | plano-01, plano-02 | Completo |
+| 2 | plano-03 | Completo |
+
+### Detalhes dos Planos
+1. **03-01**: [resumo do SUMMARY.md]
+2. **03-02**: [resumo do SUMMARY.md]
+
+### Problemas Encontrados
+[Agregado dos SUMMARYs, ou "Nenhum"]
+```
+</step>
+
+<step name="verify_phase_goal">
+Verificar que fase atingiu seu OBJETIVO, nao apenas completou tarefas.
+
+```
+Task(
+  prompt="Verificar atingimento do objetivo da fase {phase_number}.
+Diretorio da fase: {phase_dir}
+Objetivo da fase: {goal do ROADMAP.md}
+IDs de requisitos da fase: {phase_req_ids}
+Verificar must_haves contra codebase real.
+Cross-referenciar IDs de requisitos do frontmatter do PLAN contra REQUIREMENTS.md.
+Criar VERIFICATION.md.",
+  subagent_type="up-verificador"
+)
+```
+
+Ler status:
+```bash
+grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' '
+```
+
+| Status | Acao |
+|--------|------|
+| `passed` | -> update_roadmap |
+| `human_needed` | Apresentar itens para teste humano, obter aprovacao |
+| `gaps_found` | Apresentar resumo de lacunas, oferecer `/up:planejar-fase {fase} --gaps` |
+</step>
+
+<step name="update_roadmap">
+**Marcar fase completa e atualizar todos arquivos de rastreamento:**
+
+```bash
+COMPLETION=$(node "$HOME/.claude/up/bin/up-tools.cjs" phase complete "${PHASE_NUMBER}")
+```
+
+O CLI trata:
+- Marcar checkbox da fase `[x]` com data de conclusao
+- Atualizar tabela de Progresso
+- Avancar STATE.md para proxima fase
+- Atualizar rastreabilidade do REQUIREMENTS.md
+
+Extrair do resultado: `next_phase`, `next_phase_name`, `is_last_phase`.
+
+```bash
+node "$HOME/.claude/up/bin/up-tools.cjs" commit "docs(fase-{X}): completar execucao da fase" --files .plano/ROADMAP.md .plano/STATE.md .plano/REQUIREMENTS.md {phase_dir}/*-VERIFICATION.md
+```
+</step>
+
+<step name="offer_next">
+
+**Se verificacao passou:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ UP > FASE {X} COMPLETA
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Fase {X}: {Nome}** -- todos planos executados e verificados
+
+───────────────────────────────────────────────────────────────
+
+## Proximo
+
+**Fase {X+1}: {Nome}** -- [Objetivo do ROADMAP.md]
+
+/up:discutir-fase {X+1} -- reunir contexto e esclarecer abordagem
+
+<sub>/clear primeiro -> janela de contexto limpa</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Tambem disponivel:**
+- /up:planejar-fase {X+1} -- pular discussao, planejar diretamente
+- /up:verificar-trabalho {X} -- teste de aceitacao do usuario
+
+───────────────────────────────────────────────────────────────
+```
+
+**Se lacunas encontradas:**
+
+```
+## Lacunas Encontradas na Fase {X}: {Nome}
+
+**Score:** {N}/{M} must-haves verificados
+**Relatorio:** {phase_dir}/{phase_num}-VERIFICATION.md
+
+### O que Falta
+{Resumo das lacunas}
+
+---
+## Proximo
+
+`/up:planejar-fase {X} --gaps`
+
+<sub>`/clear` primeiro -> janela de contexto limpa</sub>
+```
+</step>
+
+</process>
+
+<context_efficiency>
+Orquestrador: ~10-15% contexto. Subagentes: 200k limpo cada. Sem polling (Task bloqueia). Sem vazamento de contexto.
+</context_efficiency>
+
+<failure_handling>
+- **Agente falha no meio do plano:** SUMMARY.md faltando -> reportar, perguntar usuario como prosseguir
+- **Cadeia de dependencia quebra:** Wave 1 falha -> dependentes da Wave 2 provavelmente falham -> usuario escolhe tentar ou pular
+- **Todos agentes na wave falham:** Problema sistemico -> parar, reportar para investigacao
+</failure_handling>
+
+<resumption>
+Re-executar `/up:executar-fase {fase}` -> discover_plans encontra SUMMARYs completos -> pula -> resume do primeiro plano incompleto -> continua execucao por wave.
+</resumption>