@od-oneapp/ai-platform 0.1.0

package/src/tools/superpowers/schemas/index.ts

@@ -0,0 +1,701 @@
+/**
+ * @fileoverview Superpowers Schemas - Zod schemas for all 20 obra/superpowers skills
+ * @module @od-oneapp/ai-platform/superpowers/schemas
+ */
+
+import { z } from 'zod';
+
+// ============================================================================
+// PLANNING SCHEMAS
+// ============================================================================
+
+export const BrainstormOutputSchema = z.object({
+  analysis: z.object({
+    ambiguityScore: z.number().min(1).max(10).describe('10 is very vague, 1 is crystal clear'),
+    missingContext: z.array(z.string()).describe('List of critical information not provided'),
+    assumptions: z.array(z.string()).describe('Assumptions being made based on limited info'),
+  }),
+  clarifyingQuestions: z
+    .array(
+      z.object({
+        question: z.string(),
+        priority: z.enum(['critical', 'important', 'nice-to-have']),
+        context: z.string().describe('Why this question matters'),
+      }),
+    )
+    .describe('Top 3-5 questions to ask the user immediately'),
+  edgeCases: z
+    .array(
+      z.object({
+        scenario: z.string(),
+        risk: z.enum(['low', 'medium', 'high']),
+        mitigation: z.string().optional(),
+      }),
+    )
+    .describe('Potential failure modes or unhandled states'),
+  approaches: z
+    .array(
+      z.object({
+        name: z.string(),
+        description: z.string(),
+        pros: z.array(z.string()),
+        cons: z.array(z.string()),
+        techStackRecommendation: z.string().optional(),
+        estimatedComplexity: z.enum(['simple', 'moderate', 'complex']),
+      }),
+    )
+    .describe('Proposed solutions with trade-offs'),
+});
+
+export const PlanOutputSchema = z.object({
+  summary: z.string().describe('Executive summary of the approach'),
+  riskAnalysis: z
+    .array(
+      z.object({
+        risk: z.string(),
+        severity: z.enum(['low', 'medium', 'high', 'critical']),
+        mitigation: z.string(),
+      }),
+    )
+    .describe('Potential pitfalls or breaking changes'),
+  dependencies: z
+    .array(
+      z.object({
+        name: z.string(),
+        type: z.enum(['package', 'service', 'api', 'database', 'file']),
+        status: z.enum(['exists', 'needs-creation', 'needs-modification']),
+      }),
+    )
+    .describe('Required dependencies and their status'),
+  steps: z.array(
+    z.object({
+      order: z.number(),
+      title: z.string(),
+      filePaths: z.array(z.string()).describe('Files that will be created or modified'),
+      actionType: z.enum(['create', 'modify', 'delete', 'refactor', 'test', 'configure']),
+      description: z.string(),
+      verificationCmd: z
+        .string()
+        .describe("Shell command to verify this specific step (e.g., 'npm test -- spec')"),
+      blockedBy: z.array(z.number()).optional().describe('Step numbers that must complete first'),
+    }),
+  ),
+  rollbackPlan: z.string().optional().describe('How to revert if something goes wrong'),
+});
+
+export const DesignReviewOutputSchema = z.object({
+  adheresToConventions: z.boolean(),
+  conventionViolations: z.array(
+    z.object({
+      convention: z.string(),
+      violation: z.string(),
+      severity: z.enum(['minor', 'moderate', 'severe']),
+      suggestion: z.string(),
+    }),
+  ),
+  architecturalConcerns: z.array(
+    z.object({
+      concern: z.string(),
+      impact: z.enum(['low', 'medium', 'high']),
+      recommendation: z.string(),
+    }),
+  ),
+  compatibility: z.object({
+    backwardsCompatible: z.boolean(),
+    breakingChanges: z.array(z.string()),
+    migrationRequired: z.boolean(),
+    migrationSteps: z.array(z.string()).optional(),
+  }),
+  recommendations: z.array(z.string()),
+  approval: z.enum(['approved', 'approved-with-changes', 'rejected']),
+});
+
+// ============================================================================
+// QUALITY SCHEMAS
+// ============================================================================
+
+export const TDDOutputSchema = z.object({
+  phase: z.enum(['write-test', 'run-test', 'implement', 'refactor', 'complete']),
+  testFile: z
+    .object({
+      path: z.string(),
+      content: z.string(),
+      description: z.string(),
+    })
+    .optional(),
+  implementation: z
+    .object({
+      path: z.string(),
+      content: z.string(),
+      description: z.string(),
+    })
+    .optional(),
+  testResult: z
+    .object({
+      passed: z.boolean(),
+      output: z.string(),
+      failureReason: z.string().optional(),
+    })
+    .optional(),
+  iteration: z.number().describe('Current TDD iteration'),
+  nextAction: z.string().describe('What should happen next'),
+  confidence: z.number().min(0).max(1).describe('Confidence in the implementation'),
+});
+
+export const CodeReviewOutputSchema = z.object({
+  summary: z.object({
+    overallScore: z.number().min(0).max(100),
+    recommendation: z.enum(['approve', 'request-changes', 'needs-discussion']),
+    reviewerConfidence: z.number().min(0).max(1),
+  }),
+  categories: z.object({
+    security: z.object({
+      score: z.number().min(0).max(100),
+      issues: z.array(
+        z.object({
+          severity: z.enum(['info', 'warning', 'error', 'critical']),
+          line: z.number().optional(),
+          message: z.string(),
+          suggestion: z.string().optional(),
+        }),
+      ),
+    }),
+    performance: z.object({
+      score: z.number().min(0).max(100),
+      issues: z.array(
+        z.object({
+          severity: z.enum(['info', 'warning', 'error']),
+          line: z.number().optional(),
+          message: z.string(),
+          suggestion: z.string().optional(),
+        }),
+      ),
+    }),
+    maintainability: z.object({
+      score: z.number().min(0).max(100),
+      issues: z.array(
+        z.object({
+          severity: z.enum(['info', 'warning', 'error']),
+          line: z.number().optional(),
+          message: z.string(),
+          suggestion: z.string().optional(),
+        }),
+      ),
+    }),
+    testCoverage: z.object({
+      score: z.number().min(0).max(100),
+      missingTests: z.array(z.string()),
+    }),
+  }),
+  antiPatterns: z.array(
+    z.object({
+      name: z.string(),
+      location: z.string(),
+      description: z.string(),
+      suggestedFix: z.string(),
+    }),
+  ),
+  positives: z.array(z.string()).describe('Good practices observed in the code'),
+});
+
+export const AntiPatternOutputSchema = z.object({
+  detected: z.boolean(),
+  patterns: z.array(
+    z.object({
+      name: z.string(),
+      severity: z.enum(['minor', 'moderate', 'severe']),
+      location: z.object({
+        file: z.string(),
+        line: z.number().optional(),
+        snippet: z.string().optional(),
+      }),
+      description: z.string(),
+      why: z.string().describe('Why this is problematic'),
+      fix: z.string().describe('How to fix it'),
+      category: z.enum([
+        'hardcoding',
+        'error-swallowing',
+        'magic-numbers',
+        'god-object',
+        'over-engineering',
+        'premature-optimization',
+        'copy-paste',
+        'security',
+        'other',
+      ]),
+    }),
+  ),
+  score: z.number().min(0).max(100).describe('Code quality score (100 = no anti-patterns)'),
+});
+
+// ============================================================================
+// DEBUGGING SCHEMAS
+// ============================================================================
+
+export const SystematicDebuggingOutputSchema = z.object({
+  phase: z.enum(['investigation', 'pattern-analysis', 'hypothesis-testing', 'implementation']),
+  investigation: z.object({
+    errorMessages: z.array(z.string()).describe('Error messages and stack traces analyzed'),
+    reproductionSteps: z.array(z.string()).describe('Steps to consistently reproduce the issue'),
+    recentChanges: z.array(z.string()).describe('Recent commits or changes that might be related'),
+    dataFlowTrace: z.string().describe('Trace of data flow backward to failure point'),
+    failurePoint: z.string().describe('Identified location where failure occurs'),
+    rootCauseHypothesis: z.string().describe('Initial hypothesis about WHY it failed'),
+  }),
+  patternAnalysis: z
+    .object({
+      workingCodeExamples: z.array(z.string()).describe('Similar working code found in codebase'),
+      differences: z.array(z.string()).describe('Key differences between working and broken code'),
+      missingDependencies: z.array(z.string()).describe('Dependencies or assumptions not met'),
+    })
+    .optional(),
+  hypothesis: z
+    .object({
+      statement: z.string().describe('Single, specific hypothesis'),
+      testPlan: z.string().describe('Minimal test to verify hypothesis'),
+      result: z.enum(['confirmed', 'rejected', 'inconclusive']).optional(),
+      iterations: z.number().describe('Number of hypothesis iterations'),
+    })
+    .optional(),
+  fix: z
+    .object({
+      testCase: z.string().describe('Automated failing test case'),
+      implementation: z.string().describe('Single targeted fix'),
+      verification: z.string().describe('How fix was verified'),
+    })
+    .optional(),
+  confidence: z.number().min(0).max(1).describe('Confidence in root cause identification'),
+  redFlags: z.array(z.string()).describe('Warning signs that investigation is going wrong'),
+});
+
+export const RootCauseTracingOutputSchema = z.object({
+  symptom: z.string().describe('The observed symptom or error'),
+  traceSteps: z.array(
+    z.object({
+      layer: z.string().describe('System layer (UI, API, DB, etc.)'),
+      component: z.string().describe('Specific component examined'),
+      finding: z.string().describe('What was found at this layer'),
+      isRootCause: z.boolean(),
+    }),
+  ),
+  rootCause: z.object({
+    location: z.string().describe('File and line where root cause exists'),
+    description: z.string().describe('What is actually wrong'),
+    category: z.enum([
+      'logic-error',
+      'data-corruption',
+      'race-condition',
+      'missing-validation',
+      'configuration',
+      'dependency',
+      'resource-exhaustion',
+      'other',
+    ]),
+  }),
+  contributingFactors: z.array(z.string()).describe('Other factors that enabled this bug'),
+  preventionRecommendations: z.array(z.string()).describe('How to prevent similar issues'),
+});
+
+export const DefenseInDepthOutputSchema = z.object({
+  layers: z.array(
+    z.object({
+      name: z.string().describe('Defense layer name'),
+      type: z.enum([
+        'input-validation',
+        'authentication',
+        'authorization',
+        'encryption',
+        'logging',
+        'rate-limiting',
+        'error-handling',
+        'backup',
+      ]),
+      status: z.enum(['present', 'missing', 'partial']),
+      strength: z.enum(['strong', 'adequate', 'weak']),
+      recommendations: z.array(z.string()),
+    }),
+  ),
+  overallScore: z.number().min(0).max(100),
+  criticalGaps: z.array(z.string()).describe('Security gaps that must be addressed'),
+  redundancyAnalysis: z.object({
+    hasRedundancy: z.boolean(),
+    singlePointsOfFailure: z.array(z.string()),
+  }),
+  gaps: z.array(
+    z.object({
+      name: z.string(),
+      severity: z.enum(['low', 'medium', 'high', 'critical']),
+      recommendation: z.string(),
+    }),
+  ),
+  recommendations: z.array(z.string()),
+});
+
+export const AsyncPatternsOutputSchema = z.object({
+  asyncOperations: z.array(
+    z.object({
+      description: z.string(),
+      type: z.enum(['network', 'timer', 'animation', 'state-change', 'dom-update', 'file-io']),
+      waitStrategy: z.enum(['polling', 'event-listener', 'promise', 'callback', 'observable']),
+      condition: z.string().describe('What condition to wait for'),
+      timeout: z.number().describe('Recommended timeout in ms'),
+      fallback: z.string().describe('What to do if timeout occurs'),
+    }),
+  ),
+  raceConditions: z.array(
+    z.object({
+      description: z.string(),
+      location: z.string(),
+      fix: z.string(),
+    }),
+  ),
+  antiPatterns: z.array(
+    z.object({
+      pattern: z.string(),
+      location: z.string(),
+      betterApproach: z.string(),
+    }),
+  ),
+  recommendations: z.array(z.string()),
+});
+
+// ============================================================================
+// WORKFLOW SCHEMAS
+// ============================================================================
+
+export const PlanExecutionOutputSchema = z.object({
+  planId: z.string().describe('Reference to the plan being executed'),
+  currentStep: z.number(),
+  totalSteps: z.number(),
+  status: z.enum(['in-progress', 'checkpoint', 'blocked', 'completed', 'failed']),
+  executedSteps: z.array(
+    z.object({
+      stepNumber: z.number(),
+      title: z.string(),
+      status: z.enum(['completed', 'skipped', 'failed']),
+      output: z.string().optional(),
+      verificationResult: z.string().optional(),
+      duration: z.number().optional().describe('Time taken in ms'),
+    }),
+  ),
+  checkpoint: z
+    .object({
+      reason: z.string().describe('Why human review is needed'),
+      question: z.string().describe('Specific question for the human'),
+      options: z.array(z.string()).describe('Available choices'),
+    })
+    .optional(),
+  blockers: z.array(z.string()).optional(),
+  nextAction: z.string().describe('What will happen next'),
+});
+
+export const AgentDispatchOutputSchema = z.object({
+  taskDecomposition: z.array(
+    z.object({
+      taskId: z.string(),
+      description: z.string(),
+      dependencies: z.array(z.string()).describe('Task IDs this depends on'),
+      estimatedDuration: z.string(),
+      agentType: z.enum(['brainstorm', 'plan', 'implement', 'test', 'review', 'document']),
+    }),
+  ),
+  parallelGroups: z.array(
+    z.object({
+      groupId: z.string(),
+      tasks: z.array(z.string()).describe('Task IDs that can run in parallel'),
+      completionCondition: z.enum(['all', 'any', 'majority']),
+    }),
+  ),
+  executionOrder: z.array(z.string()).describe('Group IDs in execution order'),
+  coordinationStrategy: z.enum(['fork-join', 'pipeline', 'scatter-gather', 'choreography']),
+  mergeStrategy: z.string().describe('How to combine results from parallel tasks'),
+});
+
+export const SubagentDevOutputSchema = z.object({
+  phase: z.enum(['setup', 'iteration', 'quality-gate', 'integration', 'complete']),
+  status: z.enum(['pending', 'running', 'success', 'failed']),
+  iteration: z.object({
+    number: z.number(),
+    objective: z.string(),
+    agentAssignments: z.array(
+      z.object({
+        agentId: z.string(),
+        role: z.string(),
+        task: z.string(),
+        status: z.enum(['pending', 'running', 'completed', 'failed']),
+      }),
+    ),
+  }),
+  qualityGates: z.array(
+    z.object({
+      name: z.string(),
+      criteria: z.string(),
+      passed: z.boolean().optional(),
+      blockers: z.array(z.string()).optional(),
+    }),
+  ),
+  artifacts: z.array(
+    z.object({
+      type: z.enum(['code', 'test', 'documentation', 'config']),
+      path: z.string(),
+      status: z.enum(['created', 'modified', 'verified']),
+    }),
+  ),
+  nextIteration: z.string().optional().describe('What the next iteration will focus on'),
+});
+
+// ============================================================================
+// CODE REVIEW SCHEMAS
+// ============================================================================
+
+export const CodeReviewResponseOutputSchema = z.object({
+  reviewId: z.string(),
+  allAddressed: z.boolean(),
+  updatedCode: z.string().optional(),
+  feedbackItems: z.array(
+    z.object({
+      id: z.string(),
+      type: z.enum(['bug', 'suggestion', 'question', 'nitpick', 'praise']),
+      severity: z.enum(['critical', 'major', 'minor', 'trivial']),
+      comment: z.string(),
+      file: z.string().optional(),
+      line: z.number().optional(),
+      response: z
+        .object({
+          action: z.enum(['accepted', 'rejected', 'discussed', 'deferred']),
+          explanation: z.string(),
+          implementation: z.string().optional().describe('How it was addressed'),
+        })
+        .optional(),
+    }),
+  ),
+  summary: z.object({
+    totalItems: z.number(),
+    addressed: z.number(),
+    deferred: z.number(),
+    rejected: z.number(),
+  }),
+  followUpQuestions: z.array(z.string()).describe('Questions to ask the reviewer'),
+});
+
+// ============================================================================
+// GIT SCHEMAS
+// ============================================================================
+
+export const CommitAnalysisOutputSchema = z.object({
+  type: z.enum(['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore', 'perf', 'ci']),
+  scope: z.string().optional().describe('Component or area affected'),
+  subject: z.string().describe('Short description (imperative mood, max 50 chars)'),
+  body: z.string().optional().describe('Detailed explanation of the why'),
+  breakingChange: z
+    .object({
+      isBreaking: z.boolean(),
+      description: z.string().optional(),
+    })
+    .optional(),
+  fullMessage: z.string().describe('Complete formatted commit message'),
+  confidence: z.number().min(0).max(1),
+  relatedIssues: z.array(z.string()).optional(),
+});
+
+export const WorktreeOutputSchema = z.object({
+  action: z.enum(['create', 'list', 'remove', 'switch']),
+  worktree: z
+    .object({
+      path: z.string(),
+      branch: z.string(),
+      baseBranch: z.string().optional(),
+      isClean: z.boolean(),
+    })
+    .optional(),
+  setup: z
+    .object({
+      projectType: z.enum(['nodejs', 'python', 'rust', 'go', 'java', 'other']),
+      dependenciesInstalled: z.boolean(),
+      testsRun: z.boolean(),
+      testsPassed: z.boolean().optional(),
+      baselineEstablished: z.boolean(),
+    })
+    .optional(),
+  safetyChecks: z.object({
+    gitignoreVerified: z.boolean(),
+    noUncommittedChanges: z.boolean(),
+    branchNameValid: z.boolean(),
+  }),
+  existingWorktrees: z
+    .array(
+      z.object({
+        path: z.string(),
+        branch: z.string(),
+        isLocked: z.boolean(),
+      }),
+    )
+    .optional(),
+});
+
+export const BranchFinishOutputSchema = z.object({
+  branch: z.string(),
+  status: z.enum([
+    'ready', // All checks passed, ready for next step
+    'ready-to-merge', // Ready to merge into target branch
+    'ready-for-pr', // Ready to create pull request
+    'needs-work', // Requires fixes before proceeding
+    'merged', // Already merged
+    'abandoned', // Branch abandoned
+  ]),
+  preFlightChecks: z.array(
+    z.object({
+      check: z.string(),
+      passed: z.boolean(),
+      details: z.string().optional(),
+    }),
+  ),
+  mergeStrategy: z
+    .object({
+      recommendation: z.enum(['merge', 'squash', 'rebase']),
+      reason: z.string(),
+      targetBranch: z.string(),
+    })
+    .optional(),
+  prDetails: z
+    .object({
+      title: z.string(),
+      body: z.string(),
+      labels: z.array(z.string()),
+      reviewers: z.array(z.string()).optional(),
+    })
+    .optional(),
+  cleanup: z.object({
+    localBranchDeleted: z.boolean(),
+    remoteBranchDeleted: z.boolean(),
+    worktreeRemoved: z.boolean().optional(),
+  }),
+});
+
+// ============================================================================
+// META SCHEMAS
+// ============================================================================
+
+export const SkillWriteOutputSchema = z.object({
+  skillName: z.string(),
+  implementation: z.string().optional(),
+  skillDefinition: z.object({
+    purpose: z.string().describe('What problem this skill solves'),
+    corePrinciple: z.string().describe('The key rule that guides this skill'),
+    phases: z.array(
+      z.object({
+        name: z.string(),
+        activities: z.array(z.string()),
+        successCriterion: z.string(),
+      }),
+    ),
+    redFlags: z.array(z.string()).describe('Warning signs of misuse'),
+    integrationPoints: z.object({
+      calledBy: z.array(z.string()),
+      pairsWith: z.array(z.string()),
+    }),
+  }),
+  outputSchema: z.string().describe('Zod schema definition for this skill'),
+  systemPrompt: z.string().describe('System prompt for this skill'),
+  exampleUsage: z.string(),
+});
+
+export const SkillTestOutputSchema = z.object({
+  skillName: z.string(),
+  passRate: z.number().min(0).max(1),
+  testCases: z.array(
+    z.object({
+      name: z.string(),
+      input: z.string(),
+      expectedBehavior: z.string(),
+      actualResult: z.string().optional(),
+      passed: z.boolean().optional(),
+    }),
+  ),
+  edgeCases: z.array(
+    z.object({
+      scenario: z.string(),
+      handled: z.boolean(),
+      notes: z.string().optional(),
+    }),
+  ),
+  qualityMetrics: z.object({
+    completeness: z.number().min(0).max(100),
+    clarity: z.number().min(0).max(100),
+    robustness: z.number().min(0).max(100),
+  }),
+  recommendations: z.array(z.string()),
+});
+
+export const SkillShareOutputSchema = z.object({
+  skillName: z.string(),
+  exportFormat: z.enum(['markdown', 'json', 'yaml']),
+  documentation: z.object({
+    overview: z.string(),
+    quickStart: z.string(),
+    fullDocumentation: z.string(),
+    examples: z.array(z.string()),
+  }),
+  compatibility: z.object({
+    platforms: z.array(z.enum(['claude-code', 'cursor', 'windsurf', 'other'])),
+    version: z.string(),
+    dependencies: z.array(z.string()),
+  }),
+  distribution: z.object({
+    method: z.enum(['git', 'npm', 'manual', 'marketplace']),
+    location: z.string(),
+    installInstructions: z.string(),
+  }),
+});
+
+export const SuperpowersIntroOutputSchema = z.object({
+  availableSuperpowers: z.array(
+    z.object({
+      name: z.string(),
+      category: z.enum(['planning', 'debugging', 'quality', 'git', 'workflow', 'meta']),
+      description: z.string(),
+      whenToUse: z.string(),
+    }),
+  ),
+  recommendedWorkflow: z.array(
+    z.object({
+      step: z.number(),
+      superpower: z.string(),
+      purpose: z.string(),
+    }),
+  ),
+  corePrinciples: z.array(z.string()),
+  antiPatterns: z.array(
+    z.object({
+      pattern: z.string(),
+      why: z.string(),
+      instead: z.string(),
+    }),
+  ),
+});
+
+// ============================================================================
+// TYPE EXPORTS
+// ============================================================================
+
+export type BrainstormOutput = z.infer<typeof BrainstormOutputSchema>;
+export type PlanOutput = z.infer<typeof PlanOutputSchema>;
+export type DesignReviewOutput = z.infer<typeof DesignReviewOutputSchema>;
+export type TDDOutput = z.infer<typeof TDDOutputSchema>;
+export type CodeReviewOutput = z.infer<typeof CodeReviewOutputSchema>;
+export type AntiPatternOutput = z.infer<typeof AntiPatternOutputSchema>;
+export type SystematicDebuggingOutput = z.infer<typeof SystematicDebuggingOutputSchema>;
+export type RootCauseTracingOutput = z.infer<typeof RootCauseTracingOutputSchema>;
+export type DefenseInDepthOutput = z.infer<typeof DefenseInDepthOutputSchema>;
+export type AsyncPatternsOutput = z.infer<typeof AsyncPatternsOutputSchema>;
+export type PlanExecutionOutput = z.infer<typeof PlanExecutionOutputSchema>;
+export type AgentDispatchOutput = z.infer<typeof AgentDispatchOutputSchema>;
+export type SubagentDevOutput = z.infer<typeof SubagentDevOutputSchema>;
+export type CodeReviewResponseOutput = z.infer<typeof CodeReviewResponseOutputSchema>;
+export type CommitAnalysisOutput = z.infer<typeof CommitAnalysisOutputSchema>;
+export type WorktreeOutput = z.infer<typeof WorktreeOutputSchema>;
+export type BranchFinishOutput = z.infer<typeof BranchFinishOutputSchema>;
+export type SkillWriteOutput = z.infer<typeof SkillWriteOutputSchema>;
+export type SkillTestOutput = z.infer<typeof SkillTestOutputSchema>;
+export type SkillShareOutput = z.infer<typeof SkillShareOutputSchema>;
+export type SuperpowersIntroOutput = z.infer<typeof SuperpowersIntroOutputSchema>;