ganbatte-os 0.2.1

package/manifests/gos-install-manifest.json

@@ -0,0 +1,46 @@
+{
+  "version": "0.2.0",
+  "runtime": "gos-design-delivery",
+  "preserveUserContent": [
+    "packages/",
+    "data/sprints/",
+    "data/clients/",
+    ".gos-local/",
+    "config.json"
+  ],
+  "frameworkManaged": [
+    "agents/",
+    "skills/",
+    "squads/",
+    "templates/",
+    "prompts/",
+    "integrations/",
+    "scripts/",
+    "manifests/",
+    "docs/",
+    "playbooks/",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "GEMINI.md"
+  ],
+  "requiredPaths": [
+    "agents/profiles/index.json",
+    "skills/registry.json",
+    "manifests/g-os-runtime-manifest.json",
+    "scripts/cli/gos-cli.js",
+    "scripts/integrations/setup-ide-adapters.js",
+    "scripts/integrations/check-ide-compat.js",
+    "AGENTS.md",
+    "CLAUDE.md"
+  ],
+  "gitignoreEntries": [
+    ".gos-local/",
+    ".temp/",
+    ".backups/",
+    "packages/*/figma-make/",
+    "packages/*/node_modules/",
+    ".env",
+    ".env.local",
+    ".env.*.local"
+  ]
+}

package/opencode.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [
+    "AGENTS.md",
+    "CLAUDE.md"
+  ]
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "ganbatte-os",
+  "version": "0.2.1",
+  "description": "Framework operacional para design-to-code, squads de entrega e sprint sync com ClickUp.",
+  "bin": {
+    "ganbatte-os": "scripts/cli/gos-cli.js",
+    "gos": "scripts/cli/gos-cli.js"
+  },
+  "scripts": {
+    "ganbatte-os:init": "node scripts/cli/gos-cli.js init",
+    "ganbatte-os:update": "node scripts/cli/gos-cli.js update",
+    "ganbatte-os:doctor": "node scripts/cli/gos-cli.js doctor",
+    "ganbatte-os:version": "node scripts/cli/gos-cli.js version",
+    "gos:init": "node scripts/cli/gos-cli.js init",
+    "gos:update": "node scripts/cli/gos-cli.js update",
+    "gos:doctor": "node scripts/cli/gos-cli.js doctor",
+    "gos:version": "node scripts/cli/gos-cli.js version",
+    "clickup": "node scripts/tools/clickup.js",
+    "sync:ides": "node scripts/integrations/setup-ide-adapters.js",
+    "check:ides": "node scripts/integrations/check-ide-compat.js",
+    "doctor": "node scripts/cli/gos-cli.js doctor"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adrianomorais-ganbatte/g-os.git"
+  },
+  "license": "MIT",
+  "author": "Adriano Morais",
+  "files": [
+    "agents/",
+    "skills/",
+    "squads/",
+    "scripts/",
+    "manifests/",
+    "docs/",
+    "integrations/",
+    "templates/",
+    "prompts/",
+    "rules/",
+    "playbooks/",
+    "config.json",
+    "opencode.json",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "GEMINI.md",
+    "README.md"
+  ]
+}

package/playbooks/feature-development-playbook.md

@@ -0,0 +1,239 @@
+# Feature Development Playbook
+
+**Purpose:** Desenvolvimento guiado de features com exploracao profunda do codebase, perguntas de clarificacao, design de arquitetura com multiplas opcoes, implementacao e revisao de qualidade -- tudo usando agentes paralelos para velocidade.
+
+**Success Criteria:**
+- Feature entendida completamente antes de codar
+- Codebase explorado com agentes paralelos
+- Todas as ambiguidades resolvidas com o usuario
+- Arquitetura desenhada com trade-offs claros
+- Implementacao seguindo patterns do projeto
+- Revisao de qualidade com multiplas perspectivas
+- Resumo documentado do que foi feito
+
+---
+
+## Overview
+
+This playbook implements a 7-phase feature development workflow that uses parallel agents at key stages to maximize throughput while maintaining quality. The human stays in the loop at every decision point.
+
+**Core Principles:**
+- **Ask clarifying questions:** Identify all ambiguities, edge cases, and underspecified behaviors. Ask specific, concrete questions rather than making assumptions. Wait for user answers before proceeding.
+- **Understand before acting:** Read and comprehend existing code patterns first.
+- **Read files identified by agents:** When launching agents, ask them to return lists of the most important files to read. After agents complete, read those files to build detailed context.
+- **Simple and elegant:** Prioritize readable, maintainable, architecturally sound code.
+- **Use TodoWrite:** Track all progress throughout.
+
+---
+
+## Phase 1: Discovery
+
+**Goal:** Understand what needs to be built.
+
+**Input:** Feature description from user (or `$ARGUMENTS`).
+
+**Actions:**
+1. Create TodoWrite with all 7 phases
+2. If the feature is unclear, ask the user:
+   - What problem are they solving?
+   - What should the feature do?
+   - Any constraints or requirements?
+3. Summarize your understanding and confirm with the user before proceeding
+
+**Exit criteria:** Clear, confirmed understanding of what needs to be built.
+
+---
+
+## Phase 2: Codebase Exploration (parallel agents)
+
+**Goal:** Understand relevant existing code and patterns at both high and low levels.
+
+**Actions:**
+1. Launch 2-3 code-explorer agents in parallel. Each agent should:
+   - Trace through the code comprehensively and focus on getting a thorough understanding of abstractions, architecture, and flow of control
+   - Target a different aspect of the codebase
+   - Return a list of 5-10 key files to read
+
+   **Example agent prompts:**
+   - "Find features similar to [feature] and trace through their implementation comprehensively"
+   - "Map the architecture and abstractions for [feature area], tracing through the code comprehensively"
+   - "Analyze the current implementation of [existing feature/area], tracing through the code comprehensively"
+   - "Identify UI patterns, testing approaches, or extension points relevant to [feature]"
+
+2. Once agents return, read ALL files identified by agents to build deep understanding
+3. Present comprehensive summary of findings and patterns discovered to the user
+
+**Exit criteria:** Deep understanding of codebase patterns, conventions, and relevant code.
+
+---
+
+## Phase 3: Clarifying Questions
+
+**Goal:** Fill in gaps and resolve ALL ambiguities before designing.
+
+**CRITICAL: This is one of the most important phases. DO NOT SKIP.**
+
+**Actions:**
+1. Review the codebase findings and original feature request together
+2. Identify underspecified aspects:
+   - Edge cases and error handling
+   - Integration points with existing code
+   - Scope boundaries (what is IN and OUT)
+   - Design preferences (UI/UX, API shape)
+   - Backward compatibility requirements
+   - Performance needs and constraints
+3. **Present all questions to the user in a clear, organized list**
+4. **Wait for answers before proceeding to architecture design**
+
+If the user says "whatever you think is best", provide your recommendation and get explicit confirmation.
+
+**Exit criteria:** All ambiguities resolved. No assumptions remaining.
+
+---
+
+## Phase 4: Architecture Design (parallel agents)
+
+**Goal:** Design multiple implementation approaches with different trade-offs.
+
+**Actions:**
+1. Launch 2-3 code-architect agents in parallel, each with a different focus:
+   - **Minimal changes:** Smallest change, maximum reuse of existing code
+   - **Clean architecture:** Maintainability, elegant abstractions, future-proof
+   - **Pragmatic balance:** Speed + quality, best fit for the specific context
+
+2. Review all approaches and form your opinion on which fits best for this specific task. Consider:
+   - Is this a small fix or a large feature?
+   - How urgent is it?
+   - How complex is the domain?
+   - What is the team context?
+
+3. Present to user:
+   - Brief summary of each approach
+   - Trade-offs comparison (table format works well)
+   - **Your recommendation with reasoning**
+   - Concrete implementation differences (what files, what patterns)
+
+4. **Ask user which approach they prefer**
+
+**Exit criteria:** Architecture approach chosen and approved by user.
+
+---
+
+## Phase 4.1: Guias Frontend/UX (quando houver UI/React/RN)
+
+**Goal:** Travar padrões de performance e UX antes de codar.**
+
+- Consulte skills de apoio:
+  - `react-best-practices` — evitar waterfalls, reduzir bundle, otimizar rendering (React/Next).
+  - `composition-patterns` — arquitetura de componentes, evitar props booleanas, compound components.
+  - `web-design-guidelines` — checklist de UI/acessibilidade via Web Interface Guidelines.
+  - `react-native-skills` — listas/animações/navegação em RN/Expo.
+- Registre no plano quais guias serão aplicados e onde (componentes/rotas/telas).
+
+**Exit criteria:** Padrões de UI/perf selecionados e anotados.
+
+---
+
+## Phase 5: Implementation
+
+**Goal:** Build the feature.
+
+**DO NOT START WITHOUT USER APPROVAL of the chosen architecture.**
+
+**Actions:**
+1. Wait for explicit user approval
+2. Read all relevant files identified in previous phases
+3. Implement following the chosen architecture
+4. Follow codebase conventions strictly (check CLAUDE.md, existing patterns)
+5. Write clean, well-documented code
+6. Update TodoWrite as you progress
+7. Use TDD patterns where applicable (see `tdd` skill)
+
+**For complex implementations:** Consider using `subagent-driven-development` skill to dispatch fresh subagents per task with two-stage review.
+
+**Exit criteria:** Feature implemented, all planned files created/modified.
+
+---
+
+## Phase 6: Quality Review (parallel agents)
+
+**Goal:** Ensure code is simple, DRY, elegant, easy to read, and functionally correct.
+
+**Actions:**
+1. Launch 3 code-reviewer agents in parallel with different focuses:
+   - **Simplicity/DRY/Elegance:** Is the code clean? Any duplication? Could it be simpler?
+   - **Bugs/Functional correctness:** Will it work? Edge cases handled? Error handling complete?
+   - **Project conventions/Abstractions:** Does it follow existing patterns? Are abstractions appropriate?
+
+2. Consolidate findings and identify highest severity issues
+3. **Present findings to user and ask what they want to do:**
+   - Fix now
+   - Fix later (create follow-up task)
+   - Proceed as-is (acknowledge known limitations)
+
+4. Address issues based on user decision
+
+**For deeper verification:** Use `verification-patterns` skill to verify implementations are real, not stubs.
+
+**Exit criteria:** Code reviewed from multiple perspectives, issues addressed per user decision.
+
+---
+
+## Phase 7: Summary
+
+**Goal:** Document what was accomplished.
+
+**Actions:**
+1. Mark all TodoWrite items complete
+2. Present summary:
+   - **What was built:** Feature description and scope
+   - **Key decisions made:** Architecture choices, trade-offs accepted
+   - **Files modified:** List of all created/modified files with brief description
+   - **Suggested next steps:** Testing, deployment, follow-up tasks, known limitations
+   - Se deploy para Vercel for solicitado: apontar skill `deploy-to-vercel` e default preview (prod só se pedido)
+
+**Exit criteria:** User has clear picture of what was done and what comes next.
+
+---
+
+## Escalation Points
+
+| Situation | Action |
+|-----------|--------|
+| Feature requirements unclear after Phase 1 | Ask user for more context, do not proceed |
+| Codebase too complex to understand | Break into smaller exploration agents, ask user for guidance |
+| Too many ambiguities in Phase 3 | Prioritize questions, ask in batches |
+| No architecture approach fits well | Discuss constraints with user, consider hybrid approach |
+| Implementation blocked by dependency | Report to user, suggest workaround or pause |
+| Quality review finds critical issues | Fix before proceeding, do not skip |
+
+---
+
+## Model Guidance
+
+| Phase | Recommended Model |
+|-------|-------------------|
+| Phase 1: Discovery | sonnet |
+| Phase 2: Code explorer agents | sonnet |
+| Phase 3: Clarifying questions | sonnet |
+| Phase 4: Architect agents | sonnet or opus for complex domains |
+| Phase 5: Implementation | sonnet (or subagent-driven-development) |
+| Phase 6: Reviewer agents | sonnet (simplicity, conventions) + opus (bugs) |
+| Phase 7: Summary | sonnet |
+
+---
+
+## Related Skills and Playbooks
+
+- **writing-plans** -- Create implementation plan before Phase 5
+- **subagent-driven-development** -- Execute Phase 5 with fresh subagents and two-stage review
+- **tdd** -- Test-driven development patterns for Phase 5
+- **verification-patterns** -- Verify implementations in Phase 6
+- **verification-before-completion** -- Final validation before Phase 7
+- **dispatching-parallel-agents** -- General pattern for Phases 2, 4, 6
+- **dev-implementation-playbook** -- More structured playbook for story-based development
+
+---
+
+*Version:* 1.0
+*Created:* 2026-03-11

package/playbooks/sprint-planner-playbook.md

@@ -0,0 +1,127 @@
+# Sprint Planner — Playbook Operacional
+
+> Guia a execucao completa do sprint-planner: do input ate sprint montada com PRD, ADR, roadmap e tasks.
+
+## Objetivo
+
+Transformar qualquer input (caminho de projeto, design Figma, transcricao, documento)
+em um pacote completo de sprint com artefatos prontos para execucao.
+
+## Pre-requisitos
+
+- [ ] Input disponivel (caminho de projeto, design, transcricao ou descricao)
+- [ ] Acesso ao projeto/codebase (se for project-path)
+- [ ] Usuario disponivel para loops de discovery (15-30 min)
+- [ ] Branch correta (`dev` para framework, feature branch para projetos)
+
+## Step 1 — Triage do Input (5 min)
+
+- [ ] Classificar tipo: project-path | design | transcription | document | free-text | mixed
+- [ ] Se project-path: executar `/project-brief <path>` para contexto
+- [ ] Se design: analise visual — extrair telas, fluxos, componentes
+- [ ] Se transcription: extrair requisitos, fluxos, restricoes, decisoes
+- [ ] Se document: ler, sumarizar, identificar gaps
+- [ ] Gerar `input-analysis.md`
+- [ ] Apresentar resumo ao usuario
+
+## Step 2 — Discovery Loops (15-30 min)
+
+- [ ] Loop 1: Contexto e Objetivo (SCQA + Analise de Premissas)
+- [ ] Loop 2: Usuarios e Escopo (Task-Oriented Thought + Brainstorming)
+- [ ] Loop 3: Fluxos e Regras (Verificacao de Consistencia)
+- [ ] Loop 4 (se necessario): Dados e Restricoes (ReAct + Feynman)
+- [ ] Avaliar clarity checklist (>= 70%?)
+- [ ] Se < 70% apos 4 loops: consolidar e sinalizar gaps
+
+## Step 3 — PRD (20-30 min)
+
+- [ ] Gerar `sprint-planner/<slug>/PRD.md`
+- [ ] Escopo IN/OUT explicito
+- [ ] Criterios de aceite verificaveis (Given/When/Then)
+- [ ] Decisoes menores embedded (contexto, opcoes, escolha)
+- [ ] **GATE: Usuario aprova PRD**
+
+## Step 4 — Arquitetura & Schema (15-30 min)
+
+- [ ] Identificar decisoes arquiteturais significativas
+- [ ] Gerar `ADR-NNN.md` para cada decisao com 3+ opcoes e trade-offs
+- [ ] Se projeto envolve banco: gerar `schema.dbml`
+- [ ] Se projeto envolve APIs: listar endpoints com contratos
+- [ ] **GATE: Usuario aprova ADRs e schema**
+
+## Step 5 — Roadmap (10 min)
+
+- [ ] Classificar complexidade: simples | medio | complexo
+- [ ] Gerar `ROADMAP.md` com fases, duracoes e entregaveis
+- [ ] Validar: soma duracoes <= total + 20% margem
+- [ ] Validar: cada fase tem pelo menos 1 entregavel concreto
+- [ ] **GATE: Fases e prazos validados**
+
+## Step 6 — Task Decomposition (15-20 min)
+
+- [ ] Executar `/plan-to-tasks` no PRD
+- [ ] Validar: cada task max 1 dia, DoD mensuravel
+- [ ] User stories em Given/When/Then
+- [ ] Complexidade scoring (1-25) por story
+- [ ] Ordenar por dependencias
+
+## Step 7 — Setup Tasks (10 min)
+
+- [ ] Detectar necessidades: contas, credenciais, infra, repos
+- [ ] Gerar tasks P0 com area devops/general
+- [ ] Incluir instrucoes passo-a-passo
+- [ ] Vincular como pre-requisitos das tasks de dev
+
+## Step 8 — Sprint Assembly (10 min)
+
+- [ ] Gerar `SPRINT-OVERVIEW.md` consolidando tudo
+- [ ] Registrar decisoes no `memory/decision-log.json`
+- [ ] Apresentar resumo final ao usuario
+- [ ] Indicar proximos passos (qual skill usar para executar)
+
+## Armadilhas Comuns
+
+| Armadilha | Sintoma | Solucao |
+|-----------|---------|---------|
+| Discovery infinito | Mais de 5 loops sem convergir | Consolidar o que tem, sinalizar gaps |
+| Scope creep no PRD | PRD com 20+ tasks | Dividir em 2+ sprints |
+| ADR para tudo | ADR para decisoes triviais | Embedded no PRD se < 3 opcoes |
+| Schema sem RLS | Tabelas sem politicas de seguranca | Sempre incluir nota sobre RLS |
+| Setup esquecido | Dev trava por falta de credencial | Phase 6 existe para isso |
+| Pular gates | Avancar sem aprovacao | Cada fase TEM que ter aprovacao |
+
+## Tempo Estimado
+
+| Complexidade | Tempo total |
+|-------------|-------------|
+| Simples (escopo claro, 3-5 tasks) | 45-60 min |
+| Medio (ambiguidade moderada, 5-15 tasks) | 60-90 min |
+| Complexo (multi-dominio, 15+ tasks) | 90-150 min |
+
+## Continuacao
+
+Apos sprint-planner concluir, o usuario escolhe como executar:
+
+| Objetivo | Comando |
+|----------|---------|
+| Executar spec-driven (completo) | `/sdd sprint-planner/<slug>/PRD.md` |
+| Orquestrar execucao (composicao) | `/compose TASK-YYYYMM-001` |
+| Refinar backlog | `@sm` ou `@po` |
+| Frontend direto | `/fe` com tasks geradas |
+| Backend direto | `/be` com tasks geradas |
+
+## Referencias
+
+- `skills/sprint-planner/SKILL.md` — skill completa
+- `templates/adr-tmpl.yaml` — template ADR
+- `playbooks/story-creation-playbook.md` — formato de stories
+- `playbooks/gsd-agent-decomposition-playbook.md` — padrao de handoff por artefatos
+- `skills/sdd/SKILL.md` — para continuacao com execucao
+- `skills/plan-to-tasks/SKILL.md` — decomposicao em tasks
+
+## Cadencia Sugerida
+
+- Ao iniciar qualquer projeto novo (greenfield)
+- Ao receber novo escopo ou fase de projeto existente (brownfield)
+- Quando receber designs Figma ou transcricoes de reuniao para planejar
+- Antes de sprints que envolvem multiplos dominios (FE + BE + infra)

package/playbooks/squad-pipeline-runner.md

@@ -0,0 +1,196 @@
+# Squad Pipeline Runner Playbook
+
+**Purpose:** Executar pipelines de squad sequencialmente, gerenciando estado, outputs e quality gates entre steps.
+
+**When to Use:** Executando uma squad via `squads:run` ou manualmente seguindo um `pipeline.yaml`.
+
+---
+
+## Visao Geral
+
+Uma squad e um conjunto de agentes organizados em um pipeline sequencial. Cada step executa um agente com inputs definidos e produz outputs que alimentam o proximo step.
+
+```
+[Step 1: Pesquisa] → [Step 2: Copy] → [Step 3: Review] → [Step 4: Imagem] → [Step 5: Publicacao]
+```
+
+---
+
+## Estrutura do Pipeline
+
+### pipeline.yaml
+
+```yaml
+squad: linkedin-content
+version: "1.0"
+description: "Pipeline para criacao de posts LinkedIn"
+
+defaults:
+  model_tier: sonnet
+  output_dir: output/
+
+steps:
+  - name: pesquisar
+    agent: pesquisador
+    type: subagent
+    input: data/brief.md
+    output: data/pesquisa.md
+    model_tier: haiku
+
+  - name: gerar-copy
+    agent: copywriter
+    type: subagent
+    input: data/pesquisa.md
+    output: data/copy.md
+    model_tier: sonnet
+    veto_conditions:
+      - "Caption entre 500 e 2200 caracteres"
+      - "Pelo menos 1 CTA explicito"
+      - "3 a 8 hashtags"
+
+  - name: revisar
+    agent: revisor
+    type: subagent
+    input: data/copy.md
+    output: data/review.md
+    on_reject: gerar-copy
+    model_tier: sonnet
+
+  - name: criar-imagem
+    agent: designer
+    type: subagent
+    input: data/copy.md
+    output: output/slides/
+    model_tier: sonnet
+
+  - name: publicar
+    agent: publisher
+    type: checkpoint
+    input:
+      - data/copy.md
+      - output/slides/
+    output: output/publish-result.json
+```
+
+### Tipos de step
+
+| Tipo | Comportamento |
+|------|--------------|
+| `subagent` | Despacha agente autonomo. Espera conclusao. Coleta output. |
+| `inline` | Executa no contexto atual (sem subagente). Util para transformacoes simples. |
+| `checkpoint` | Pausa e pede confirmacao do usuario antes de prosseguir. Obrigatorio antes de publicacao. |
+
+---
+
+## Workflow de Execucao
+
+### Fase 1: Inicializacao
+
+1. Validar que `pipeline.yaml` existe e e valido
+2. Gerar `run_id` unico (formato: `YYYYMMDD-HHMMSS-randomhex`)
+3. Criar `state.json` com status inicial:
+   ```json
+   {
+     "run_id": "20260313-143000-a1b2c3",
+     "squad": "linkedin-content",
+     "status": "running",
+     "current_step": 0,
+     "steps": [
+       { "name": "pesquisar", "status": "pending" },
+       { "name": "gerar-copy", "status": "pending" },
+       { "name": "revisar", "status": "pending" },
+       { "name": "criar-imagem", "status": "pending" },
+       { "name": "publicar", "status": "pending" }
+     ],
+     "started_at": "2026-03-13T14:30:00Z"
+   }
+   ```
+4. Resolver paths de input/output relativos ao diretorio da squad
+
+### Fase 2: Execucao sequencial
+
+Para cada step no pipeline:
+
+1. **Pre-check**: Verificar que o input existe
+2. **Carregar agente**: Ler o agent profile do step
+3. **Montar contexto**: Combinar agent profile + input + libraries relevantes
+4. **Executar**:
+   - `subagent`: Despachar via Agent tool com prompt montado
+   - `inline`: Executar diretamente no contexto atual
+   - `checkpoint`: Apresentar preview ao usuario e aguardar confirmacao
+5. **Coletar output**: Salvar no path definido
+6. **Avaliar veto conditions** (se definidas — ver `rules/veto-conditions.md`):
+   - Todas passam: prosseguir
+   - Alguma falha: re-executar (max 2x), depois escalar
+7. **Atualizar state.json**: Marcar step como `completed` ou `failed`
+
+### Fase 3: Review loops
+
+Quando um step de review emite `REJECT`:
+
+1. Verificar campo `on_reject` do step
+2. Se definido: voltar ao step indicado e re-executar com o feedback do review
+3. Se nao definido: escalar ao usuario
+4. Max 3 ciclos de revisao no mesmo step (depois escalar)
+
+### Fase 4: Finalizacao
+
+1. Atualizar `state.json` com status final (`completed` | `failed` | `cancelled`)
+2. Registrar `finished_at` e duracao
+3. Copiar outputs finais para `output/{run_id}/`
+4. Apresentar resumo ao usuario:
+   ```
+   SQUAD RUN COMPLETE
+   Squad: linkedin-content
+   Run ID: 20260313-143000-a1b2c3
+   Steps: 5/5 completed
+   Duration: 4m 32s
+   Outputs:
+     - data/copy.md (1,847 chars)
+     - output/slides/ (7 images)
+     - output/publish-result.json
+   ```
+
+---
+
+## State Management
+
+O `state.json` e a fonte de verdade do estado da execucao. Permite:
+
+- **Retomada**: Se o pipeline for interrompido, pode ser retomado do ultimo step concluido
+- **Auditoria**: Historico completo de execucao com timestamps
+- **Debugging**: Identificar qual step falhou e por que
+
+### Status por step
+
+| Status | Significado |
+|--------|------------|
+| `pending` | Ainda nao executado |
+| `running` | Em execucao |
+| `completed` | Concluido com sucesso |
+| `failed` | Falhou (apos retries e escalacao) |
+| `skipped` | Pulado pelo usuario |
+| `retrying` | Re-executando apos veto condition |
+
+---
+
+## Regras Criticas
+
+1. **Nunca pular checkpoint antes de publicacao.** Steps do tipo `checkpoint` sao obrigatorios. O usuario deve confirmar antes de qualquer acao irreversivel.
+2. **Nunca executar steps em paralelo.** O pipeline e sequencial por design. Cada step depende do output do anterior.
+3. **Sempre salvar state.json apos cada step.** Se o processo for interrompido, o estado deve refletir o ultimo step concluido.
+4. **Respeitar model_tier do step.** Se o step define `model_tier: haiku`, usar haiku. Nao fazer upgrade automatico (exceto em re-execucao por veto condition).
+5. **Inputs devem existir.** Se o input de um step nao existe, falhar imediatamente em vez de tentar executar sem contexto.
+6. **Outputs sao imutaveis por run.** Cada execucao gera outputs em `output/{run_id}/`. Nao sobrescrever runs anteriores.
+
+---
+
+## Troubleshooting
+
+| Problema | Causa provavel | Solucao |
+|----------|---------------|---------|
+| Step falha sem mensagem | Input nao existe | Verificar output do step anterior |
+| Loop infinito de review | `on_reject` aponta para step errado | Verificar `on_reject` no pipeline.yaml |
+| Veto condition sempre falha | Condicao impossivel ou modelo inadequado | Revisar condicoes ou usar model_tier superior |
+| State.json corrompido | Interrupcao durante escrita | Deletar state.json e re-executar do inicio |
+| Checkpoint nao aparece | Step nao e tipo `checkpoint` | Mudar type para `checkpoint` |