@onion-ai/cli 1.0.0-beta.1

package/framework/commands/engineer/start.md

@@ -0,0 +1,254 @@
+---
+name: start
+description: |
+  Start feature development. Creates session and analyzes tasks.
+  Supports multiple task managers via TASK_MANAGER_PROVIDER.
+model: sonnet
+category: engineer
+tags: [development, workflow, session]
+version: '3.0.0'
+updated: '2025-11-24'
+---
+
+# Engineer Start
+
+This is the command to start developing a feature.
+
+## 🔧 Prerequisite: Detect Provider
+
+```typescript
+// Consult .claude/utils/task-manager/detector.md
+const config = detectProvider();
+const taskManager = getTaskManager();
+
+// If there's a task-id in the input, validate compatibility
+if (taskId) {
+  const validation = validateProviderMatch(taskId, config.provider);
+  if (!validation.valid) {
+    console.warn(validation.warning);
+    // Ask the user how to proceed
+  }
+}
+```
+
+## Configuration
+
+- If we're not on a feature branch, ask permission to create one
+- If we're on a feature branch that matches the feature name, we're ready
+- Make sure a folder exists at .claude/sessions/<feature-slug>
+- Ask the user for input for this session (you will receive one or more tasks to work on)
+
+## Analysis
+
+Analyze the tasks, parents and children if necessary, and build an initial understanding of what needs to be developed.
+
+### **📋 Analysis via Task Manager:**
+
+**IMPORTANT**: Use the abstraction to read tasks regardless of the provider:
+
+```typescript
+// Via abstraction - works for any provider (ClickUp, Asana, Linear)
+const task = await taskManager.getTask(taskId);
+const subtasks = await taskManager.getSubtasks(taskId);
+
+// Document in context.md
+console.log(`Provider: ${task.provider}`);
+console.log(`Task: ${task.name}`);
+console.log(`URL: ${task.url}`);
+```
+
+### **🎲 Story Points Validation (Optional but Recommended):**
+
+**CRITICAL:** Before starting development, validate if task has story points estimate:
+
+```typescript
+// Check if task has estimated story points
+const storyPoints = task.customFields?.find(
+  (f) => f.name === 'Story Points',
+)?.value;
+
+if (!storyPoints || storyPoints === 0) {
+  console.warn(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️ WARNING: TASK WITHOUT STORY POINTS ESTIMATE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Task: ${task.name}
+🎲 Story Points: Not estimated
+
+💡 RECOMMENDATIONS:
+∟ Estimate before starting development
+∟ Use: /product/estimate "${task.name}"
+∟ Or: @story-points-framework-specialist
+
+⚠️ Continuing without estimate may affect:
+   - Sprint planning
+   - Velocity tracking
+   - Delivery predictability
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  `);
+
+  // Ask the user if they want to estimate now
+  const shouldEstimate = await askUser(
+    'Do you want to estimate story points now? (y/n)',
+  );
+
+  if (shouldEstimate) {
+    // Invoke estimation agent
+    await invokeStoryPointsEstimation(task);
+  }
+} else if (storyPoints > 13) {
+  console.warn(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️ ALERT: TASK IDENTIFIED AS EPIC
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Task: ${task.name}
+🎲 Story Points: ${storyPoints} points
+
+💡 RECOMMENDATIONS:
+∟ Consider breaking into multiple smaller tasks
+∟ Use: /product/refine to detail requirements
+∟ Verify if it really needs to be a single task
+
+⚠️ Tasks > 13 points have:
+   - Higher margin of error in estimate
+   - Risk of not fitting in sprint
+   - Difficulty tracking progress
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  `);
+
+  // Ask the user if they want to continue
+  const shouldContinue = await askUser('Do you want to continue anyway? (y/n)');
+  if (!shouldContinue) {
+    console.log(
+      '💡 Suggestion: Use /product/refine to detail and break down the task',
+    );
+    return;
+  }
+} else {
+  console.log(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ ESTIMATE VALIDATION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Task: ${task.name}
+🎲 Story Points: ${storyPoints} points
+
+✅ Valid estimate for development
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  `);
+}
+```
+
+### **🔍 Incompatible ID Validation:**
+
+If the saved task-id is from a different provider than the configured one:
+
+```
+⚠️ INCOMPATIBILITY DETECTED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Task ID: "86adfe9eb"
+Detected provider: clickup
+Configured provider: asana
+
+💡 Suggested actions:
+   1. Change TASK_MANAGER_PROVIDER to 'clickup' in .env
+   2. Or clear the current session and create a new task
+   3. Run /meta/setup-integration to reconfigure
+```
+
+### **🔍 Analysis Questions:**
+
+Think carefully about what is being requested, make sure you understand exactly: - Why this is being built (context) - What is the expected outcome for this task? (objective) - How it should be built, only directionally, not in detail (approach) - If it requires the use of new APIs/tools, do you understand them? - How should it be tested? - What are the dependencies? - What are the constraints?
+
+After reflecting on these questions, formulate the 3-5 most important clarifications needed to complete the task. Ask these questions to the human, while also providing your understanding and suggestions.
+
+After getting the human's answers, consider whether you need to ask more questions. If so, ask more questions to the human.
+
+Once you have a good understanding of what is being built, save it to the file .claude/sessions/<feature-slug>/context.md and ask the human to review.
+
+If the human agrees with your understanding, you can proceed to the next step. Otherwise, continue iterating together until you get explicit approval to move forward.
+
+If something you discussed here affects what was written in the requirements, ask the human for permission to edit those requirements and make adjustments.
+
+## Architecture
+
+Given your understanding of what will be built, you will now proceed to develop the feature architecture.
+
+This is where you will put on your ultra-thinking hat and consider the best path to build the feature, also considering the patterns and best practices of this project.
+
+Your architecture document should include: - A high-level overview of the system (before and after the change) - Affected components and their relationships, dependencies - Patterns and best practices that will be maintained or introduced - External dependencies - Constraints and assumptions - Trade-offs and alternatives - List of main files to be edited/created
+
+Once you have a good understanding of what is being built, save it to the file .claude/sessions/<feature-slug>/architecture.md and ask the human to review.
+
+## 🔄 **Auto-Update Task Manager**
+
+This command **automatically updates** the task when it starts:
+
+### **✅ Automatic Updates ALWAYS:**
+
+```typescript
+// Via abstraction - works for any provider
+if (taskManager.isConfigured && taskId) {
+  // Update status
+  await taskManager.updateStatus(taskId, 'in_progress');
+
+  // Add start comment
+  await taskManager.addComment(
+    taskId,
+    `
+🚀 DEVELOPMENT STARTED
+
+━━━━━━━━━━━━━━━━━━━━━━━━
+
+🏗️ SESSION ACTIVATED:
+   ▶ Branch: feature/[slug]
+   ▶ Session: .claude/sessions/[slug]/
+   ▶ Provider: ${taskManager.provider}
+
+📋 IMPLEMENTATION PLAN:
+   ∟ Phase 1: [Description]
+   ∟ Phase N: [Description]
+
+━━━━━━━━━━━━━━━━━━━━━━━━
+
+⏰ Started: ${new Date().toISOString()}
+  `,
+  );
+}
+```
+
+### **📋 Task Identification:**
+
+1. **Context.md**: Reads task-id from the `.claude/sessions/[slug]/context.md` file
+2. **Task Manager**: Uses `taskManager.getTask(taskId)` for complete structure
+3. **🆕 PHASE-SUBTASK MAPPING**: Creates automatic phase→subtask mapping in context.md
+4. **ID Validation**: Verifies ID compatibility with configured provider
+5. **Not found**: Asks the user if they should link to a specific task
+
+### **🗺️ REQUIRED: Create Phase-Subtask Mapping**
+
+When subtasks exist, the system must **automatically**:
+
+1. **Detect subtasks** via `taskManager.getSubtasks(taskId)`
+2. **Correlate with phases** from plan.md (by order or name)
+3. **Save mapping** in context.md for use by `/engineer/work`
+4. **Validate correlation** and alert if there's a mismatch
+
+## Research
+
+If you're not sure how a specific library works, you can use Context7 and Perplexity to search for information about it. So, don't try to guess.
+
+## 🔗 References
+
+- Abstraction: `.claude/utils/task-manager/`
+- Detector: `.claude/utils/task-manager/detector.md`
+- Factory: `.claude/utils/task-manager/factory.md`
+
+<feature-slug>
+#$ARGUMENTS
+</feature-slug>

package/framework/commands/engineer/validate-phase-sync.md

@@ -0,0 +1,134 @@
+---
+name: validate-phase-sync
+description: Validar sincronização entre fases do plan.md e subtasks ClickUp.
+model: sonnet
+category: engineer
+tags: [validation, sync, clickup]
+version: '3.0.0'
+updated: '2025-11-24'
+---
+
+# 🔄 Validate Phase-Subtask Sync
+
+Validar e corrigir sincronização automática entre fases do plan.md e status das subtasks no ClickUp. Este comando identifica discrepâncias e corrige status desatualizados.
+
+## 🎯 Funcionalidades
+
+### Validação Automática de Status
+
+- Lê todas as fases do plan.md e identifica status atual (Completada ✅, Em Progresso ⏰, Não Iniciada ⏳)
+- Verifica status das subtasks correspondentes no ClickUp via Phase-Subtask Mapping
+- Identifica discrepâncias entre plan.md e ClickUp
+- Gera relatório de inconsistências encontradas
+
+### Correção Automática de Status
+
+- Atualiza automaticamente status das subtasks para refletir estado real das fases
+- Adiciona comentários retroativos nas subtasks com timestamp de correção
+- Documenta ações de correção realizadas
+- Valida integridade do mapeamento Phase→Subtask
+
+### Sistema de Alertas Proativo
+
+- Alerta quando mapeamento Phase-Subtask está ausente ou incompleto
+- Sugere criação de mapeamento quando detecta subtasks sem correlação
+- Identifica fases órfãs (sem subtask correspondente)
+- Reporta subtasks órfãs (sem fase correspondente)
+
+## 🚀 Como Usar
+
+```bash
+/engineer/validate-phase-sync
+```
+
+### Exemplos de Casos de Uso
+
+```bash
+/engineer/validate-phase-sync                    # Validação geral da sessão ativa
+/engineer/validate-phase-sync --fix-all         # Corrige todas inconsistências encontradas
+/engineer/validate-phase-sync --report-only     # Apenas relatório, não aplica correções
+```
+
+## 🤝 Integração ClickUp MCP
+
+### Operações Automáticas
+
+- **Leitura de Task**: Usa `get_task` com `subtasks=true` para estrutura completa
+- **Update de Status**: Aplica `update_task` nos subtasks com status correto
+- **Comentários de Correção**: Usa `create_task_comment` para documentar ajustes
+- **Validação de Integridade**: Verifica se mapeamento está correto e completo
+
+### Mapeamento Phase-Subtask
+
+Lê o mapeamento do arquivo `.claude/sessions/[slug]/context.md`:
+
+```markdown
+## 📋 Phase-Subtask Mapping
+
+- **Phase 1**: "Template Consolidation" → Subtask ID: [id-1]
+- **Phase 2**: "Feature Commands" → Subtask ID: [id-2]
+- **Phase 3**: "Release Commands" → Subtask ID: [id-3]
+```
+
+### Correções Aplicadas
+
+- Fases "Completada ✅" → Subtask status "done"
+- Fases "Em Progresso ⏰" → Subtask status "in progress"
+- Fases "Não Iniciada ⏳" → Subtask status "to do"
+
+## ⚙️ Processo de Validação
+
+1. **Detecta Sessão Ativa**: Identifica sessão em `.claude/sessions/`
+2. **Lê Context.md**: Carrega mapeamento Phase-Subtask e task ID principal
+3. **Analisa Plan.md**: Extrai status atual de todas as fases
+4. **Consulta ClickUp**: Obtém status atual das subtasks via ClickUp MCP
+5. **Identifica Discrepâncias**: Compara status plan.md vs ClickUp
+6. **Aplica Correções**: Atualiza status das subtasks conforme necessário
+7. **Documenta Ações**: Registra todas correções aplicadas
+
+## ⚠️ Resolução de Problemas
+
+### Problema: "Mapeamento Phase-Subtask não encontrado"
+
+**Solução**: Verificar se context.md contém seção "Phase-Subtask Mapping"
+
+```bash
+# Execute se necessário:
+/engineer/create-phase-mapping
+```
+
+### Problema: "Subtask não encontrada no ClickUp"
+
+**Solução**: IDs do mapeamento podem estar incorretos
+
+- Verificar IDs das subtasks no ClickUp
+- Atualizar mapeamento no context.md
+- Executar validação novamente
+
+### Problema: "Múltiplas fases para mesma subtask"
+
+**Solução**: Revisar estrutura do projeto
+
+- Uma subtask deve corresponder a uma fase específica
+- Considerar quebrar fase complexa em múltiplas fases
+
+## 💡 Integração com Workflow
+
+### Uso Recomendado
+
+- **Durante desenvolvimento**: Executar ao final de cada sessão de trabalho
+- **Antes de PRs**: Validar sincronização completa antes de `/engineer/pr`
+- **Após interrupções**: Garantir consistência após retomar trabalho
+- **Debugging**: Identificar problemas de tracking de progresso
+
+### Prevenção Automática
+
+Este comando corrige o problema identificado onde `/engineer/work` não atualizava automaticamente os status das subtasks. Para projetos futuros:
+
+1. `/engineer/start` deve criar o mapeamento automaticamente
+2. `/engineer/work` deve usar este mapeamento para updates automáticos
+3. Este comando serve como backup/validação do processo automático
+
+---
+
+**🎯 CRITICAL FIX: Este comando resolve a falha arquitetural onde fases completadas não atualizavam automaticamente o status das subtasks correspondentes, garantindo sincronização perfeita entre plan.md e ClickUp.**

package/framework/commands/engineer/warm-up.md

@@ -0,0 +1,20 @@
+---
+name: warm-up
+description: Prepare project context. Review README and docs.
+model: sonnet
+category: engineer
+tags: [warmup, context, preparation]
+version: '3.0.0'
+updated: '2025-11-24'
+---
+
+# Project Warm-up
+
+To prepare for this session, please:
+
+1 - Review the README.md at the root of this project. Also, keep a list of files in the docs/ folder in your context so you can refer to them later when needed.
+
+2 - Meta Specs
+
+- Review the index.md in the META SPECS of this project and memorize it so you know which files you can read later when needed.
+- Meta specs are located in the docs/meta-specs/ folder of the project

package/framework/commands/engineer/work.md

@@ -0,0 +1,155 @@
+---
+name: work
+description: |
+  Continue work on active feature. Read session and identify next phase.
+  Update progress via Task Manager abstraction.
+model: sonnet
+category: engineer
+tags: [development, workflow, session]
+version: '3.0.0'
+updated: '2025-11-24'
+---
+
+# Engineer Work
+
+We are currently working on a feature that is specified in the following folder:
+
+<folder>
+#$ARGUMENTS
+</folder>
+
+To work on this, you should:
+
+- Read all markdown files in the folder
+- Review the plan.md file and identify which Phase is currently in progress
+- Present the user with a plan to approach the next phase
+
+## 🔄 **Auto-Update Task Manager**
+
+This command **automatically updates** the task during development using the abstraction:
+
+```typescript
+// Detect provider and get adapter
+const config = detectProvider();
+const taskManager = getTaskManager();
+
+if (!taskManager.isConfigured) {
+  console.warn('⚠️ Offline mode - progress will not be synced');
+}
+```
+
+### **✅ Automatic Updates FOR EACH PHASE:**
+
+- **Progress comment** when phase is completed
+- **SUBTASK STATUS UPDATE** - Updates corresponding subtask status to "done"
+- **plan.md update** with status and decisions
+- **Estimated % progress** based on completed phases
+- **Activity timestamp** for temporal tracking
+
+### **🔗 CRITICAL: Phase→Subtask Mapping**
+
+**MANDATORY**: When a phase is completed, the system must:
+
+1. **Identify corresponding subtask** via mapping established in context.md
+2. **Update subtask status** to "done" automatically
+3. **Document completion** with timestamp and phase metrics
+
+### **💬 DUAL Comment Strategy:**
+
+When completing a phase, the system automatically:
+
+1. **Creates DETAILED comment on SUBTASK**
+2. **Creates SUMMARY comment on MAIN TASK**
+
+### **📋 Task Identification:**
+
+1. **Context.md**: Read task-id from session context file
+2. **Active session**: Automatically detect session in `.claude/sessions/`
+3. **🆕 PHASE-SUBTASK MAPPING**: Read mapping from context.md to correlate phases→subtasks
+
+### **🗺️ SUBTASK MAPPING STRUCTURE (context.md):**
+
+```markdown
+## 📋 Phase-Subtask Mapping
+
+- **Phase 1**: "Phase Name" → Subtask ID: [subtask-id-1]
+- **Phase 2**: "Phase Name" → Subtask ID: [subtask-id-2]
+```
+
+### **⚡ AUTOMATIC EXECUTION (Via Abstraction):**
+
+When a phase is marked as "Completed ✅" in plan.md, the system must **EXECUTE IN THIS ORDER**:
+
+```typescript
+// 1. Get task manager
+const taskManager = getTaskManager();
+
+if (taskManager.isConfigured) {
+  // 2. DETAILED comment on SUBTASK
+  await taskManager.addComment(
+    subtaskId,
+    `
+🔧 PHASE COMPLETED: ${phaseName}
+
+━━━━━━━━━━━━━━
+
+📁 FILES MODIFIED:
+${filesModified.map((f) => `   ∟ ${f}`).join('\n')}
+
+🔧 IMPLEMENTATIONS:
+${implementations.map((impl) => `   ▶ ${impl}`).join('\n')}
+
+💡 TECHNICAL DECISIONS:
+${decisions.map((d) => `   ∟ ${d}`).join('\n')}
+
+🚀 NEXT STEPS:
+   ∟ ${nextPhase}
+
+━━━━━━━━━━━━━━
+
+⏰ Completed: ${timestamp} | 🎯 Status: Done
+  `,
+  );
+
+  // 3. Update SUBTASK STATUS
+  await taskManager.updateStatus(subtaskId, 'done');
+
+  // 4. SUMMARY comment on MAIN TASK
+  await taskManager.addComment(
+    mainTaskId,
+    `
+📝 PROGRESS: Phase ${phaseNum}/${totalPhases} Completed
+
+✅ ${phaseName} - Completed
+   ∟ Subtask: #${subtaskId}
+   ∟ Details: See comment on subtask
+
+🎯 Next: Phase ${phaseNum + 1}/${totalPhases} - ${nextPhaseName}
+
+⏰ ${timestamp}
+  `,
+  );
+}
+```
+
+## Important:
+
+When you develop the code for the current phase, use the development, code-review, and test sub-agents when appropriate to preserve as much of your context as possible.
+
+Every time you complete a phase of the plan:
+
+- **AUTO-UPDATE**: Add progress comment via abstraction
+- **TRACKING**: Check checkboxes in the description corresponding to completed criteria
+- Pause and ask the user to validate your code.
+- Make necessary changes until approved
+- Update the corresponding phase in the plan.md file marking what was done and adding helpful comments for the developer who will approach the next phases, especially about questions, decisions, etc.
+- Only start the next phase after the user agrees that you should begin.
+
+## 🔗 References
+
+- Abstraction: `.claude/utils/task-manager/`
+- Detector: `.claude/utils/task-manager/detector.md`
+- Factory: `.claude/utils/task-manager/factory.md`
+- Comment patterns: `common/prompts/clickup-patterns.md`
+
+Now, review the current development phase and provide the user with a plan on how to approach it.

package/framework/commands/f/company-context-extractor.md

@@ -0,0 +1,93 @@
+---
+name: company-context-extractor
+description: Extract structured company context from transcripts
+model: opus
+category: general
+tags: [company-context-extractor, context, preparation]
+version: "1.0.0"
+updated: "2025-12-30"
+---
+
+# Company Context Extractor
+
+You are processing transcripts to extract a structured company context document. This document serves as the foundation for all downstream agents and workflows.
+
+## Input
+The user will provide one or more transcripts, documents and/or other resources. These may be:
+- Sales/discovery call recordings
+- Meeting notes
+- Email threads
+- Any other business communication or document
+
+## Your Task
+Extract information from the provided documents and output a structured context document following the EXACT schema below. Do not deviate from this structure.
+
+## Rules
+1. **Stick to the schema** — Do not add sections, remove sections, or rename fields
+2. **Use "Unknown" or "Not mentioned"** — If information is not present in the transcripts, explicitly state this. Never invent or assume.
+3. **Preserve uncertainty** — If something is ambiguous, note it in Open Questions
+4. **Extract verbatim quotes** — The Raw Quotes section must contain actual quotes from the transcript, not paraphrases
+5. **Be concise** — Each field should be 1-3 sentences max unless it's a list
+
+---
+
+## Output Schema (use exactly this format)
+
+```
+## Company Identity
+- **Name:** [company name]
+- **Website:** [URL if mentioned, otherwise "Not mentioned"]
+- **Industry/Vertical:** [their market/sector]
+- **Stage:** [Seed / Series A / Series B / Growth / Enterprise / Unknown]
+- **Team Size:** [number or range if mentioned, otherwise "Not mentioned"]
+- **Geography:** [HQ location or primary markets]
+
+## Core Business
+- **One-liner:** [what they do in one sentence]
+- **Problem Statement:** [what pain point or challenge they address]
+- **Solution:** [how they solve it — their product/service]
+- **Target Customer:** [who they sell to — be specific]
+- **Business Model:** [SaaS / Services / Marketplace / Hardware / Other — how they monetize]
+
+## Key People
+[For each person mentioned:]
+- **[Name]** — [Role/Title] — [Any notable context: decision maker, champion, technical lead, etc.]
+
+## Current Situation
+- **Why they're engaging:** [the trigger, need, or initiative driving this conversation]
+- **Timeline:** [any deadlines, urgency, or timing mentioned]
+- **Decision Process:** [who decides, approval process, stakeholders involved]
+- **Budget Signals:** [any budget mentions, constraints, or purchasing context]
+
+## Product/Technical Context
+- **Current Tools:** [what they currently use for this problem]
+- **Integrations Needed:** [systems they need to connect with]
+- **Technical Constraints:** [any limitations, requirements, or blockers mentioned]
+
+## Open Questions
+[List 3-7 questions that remain unanswered or unclear from the transcripts. These flag gaps for follow-up.]
+- [Question 1]
+- [Question 2]
+- [Question 3]
+
+## Raw Quotes
+[Extract 3-5 verbatim quotes that capture their intent, pain points, or priorities. Include speaker attribution if known.]
+> "[Exact quote]" — [Speaker if known]
+```
+
+---
+
+## Processing Instructions
+
+Output the filled schema directly to `docs/company-context.md`. No preamble, no commentary, no "here's what I found" — just write the structured document to the file.
+
+
+## Processing Multiple Documents
+
+If multiple documents are provided:
+1. Synthesize information across all transcripts
+2. Note conflicts or evolution (e.g., "Initially mentioned X, later clarified as Y")
+3. Use the most recent information as primary, note earlier context if relevant
+4. In Open Questions, flag any contradictions that need resolution
+
+$ARGUMENTS