opencode-athena 0.1.1 → 0.2.0

package/dist/index.js

@@ -2,7 +2,7 @@ import { homedir, platform } from 'os';
 import { tool } from '@opencode-ai/plugin';
 import { join, dirname } from 'path';
 import { existsSync } from 'fs';
-import { readFile, mkdir, writeFile, rm } from 'fs/promises';
+import { readFile, mkdir, writeFile, readdir, rm } from 'fs/promises';
 import { parse, stringify } from 'yaml';
 import { z } from 'zod';
 
@@ -764,6 +764,359 @@ When implemented, this tool will:
     }
   });
 }
+function createReviewStoryTool(ctx, config) {
+  return tool({
+    description: `Run a party review on BMAD stories to find security, logic, best practice, and performance gaps.
+
+This command generates a comprehensive review document BEFORE development starts, catching issues when they're cheap to fix (in markdown, not code).
+
+The command is smart about argument types:
+- Epic: "2", "epic-2" \u2192 Reviews all stories in the epic
+- Story: "2.3", "story-2-3" \u2192 Deep dive on a single story  
+- Path: "docs/stories/story-2-3.md" \u2192 Review specific file
+- Flag: --thorough \u2192 Force advanced model (ignores complexity detection)
+
+Returns:
+- Review document path (saved to docs/reviews/)
+- Structured findings by severity and category
+- Recommendations for next steps
+
+Use this tool after story creation but before development to improve story quality.`,
+    args: {
+      identifier: tool.schema.string().describe("Epic number (e.g., '2'), Story ID (e.g., '2.3'), or file path. Required."),
+      thorough: tool.schema.boolean().optional().describe("Force advanced model for review (default: auto-detect based on complexity)")
+    },
+    async execute(args) {
+      const result = await executePartyReview(ctx, config, args.identifier, args.thorough);
+      return JSON.stringify(result, null, 2);
+    }
+  });
+}
+async function executePartyReview(ctx, config, identifier, forceAdvancedModel) {
+  const paths = await getBmadPaths(ctx.directory);
+  if (!paths.bmadDir) {
+    return {
+      success: false,
+      scope: "story",
+      identifier,
+      error: "No BMAD directory found",
+      suggestion: "Run 'npx bmad-method@alpha install' to set up BMAD in this project."
+    };
+  }
+  const scope = detectReviewScope(identifier);
+  const reviewsDir = join(paths.bmadDir, "reviews");
+  await ensureReviewsDirectory(reviewsDir);
+  if (scope === "epic") {
+    return await executeEpicReview(ctx, config, paths, identifier, reviewsDir, forceAdvancedModel);
+  }
+  return await executeStoryReview(ctx, config, paths, identifier, reviewsDir, forceAdvancedModel);
+}
+function detectReviewScope(identifier) {
+  const isFilePath = identifier.includes("/") || identifier.endsWith(".md");
+  if (isFilePath) {
+    return "story";
+  }
+  const cleanId = identifier.replace(/^(epic|story)-/, "");
+  const isEpic = !cleanId.includes(".") && !cleanId.includes("-");
+  return isEpic ? "epic" : "story";
+}
+async function ensureReviewsDirectory(reviewsDir) {
+  if (!existsSync(reviewsDir)) {
+    await mkdir(reviewsDir, { recursive: true });
+  }
+}
+async function executeEpicReview(_ctx, config, paths, identifier, reviewsDir, forceAdvancedModel) {
+  const epicNumber = identifier.replace(/^epic-/, "");
+  const stories = await findStoriesInEpic(paths.storiesDir, epicNumber);
+  if (stories.length === 0) {
+    return {
+      success: false,
+      scope: "epic",
+      identifier,
+      error: `No stories found for Epic ${epicNumber}`,
+      suggestion: `Check that story files exist in ${paths.storiesDir} with format story-${epicNumber}-*.md`
+    };
+  }
+  const storyContents = await Promise.all(
+    stories.map(async (storyId) => ({
+      id: storyId,
+      content: await loadStoryFile2(paths.storiesDir, storyId)
+    }))
+  );
+  const architectureContent = await loadArchitecture(paths.architecture);
+  const selectedModel = forceAdvancedModel ? config.models.oracle : config.models.oracle;
+  const oraclePrompt = buildEpicReviewPrompt(epicNumber, storyContents, architectureContent);
+  return {
+    success: true,
+    scope: "epic",
+    identifier: epicNumber,
+    oraclePrompt,
+    storiesContent: storyContents,
+    architectureContent,
+    selectedModel,
+    reviewsDir
+  };
+}
+async function executeStoryReview(_ctx, config, paths, identifier, reviewsDir, forceAdvancedModel) {
+  const storyId = normalizeStoryId(identifier);
+  const storyContent = await loadStoryFile2(paths.storiesDir, storyId);
+  if (!storyContent) {
+    return {
+      success: false,
+      scope: "story",
+      identifier: storyId,
+      error: `Story ${storyId} not found`,
+      suggestion: `Check that the story file exists at ${paths.storiesDir}/story-${storyId.replace(".", "-")}.md`
+    };
+  }
+  const existingReviews = await findExistingReviews(reviewsDir, storyId);
+  const epicReview = existingReviews.find((r) => r.type === "epic");
+  const architectureContent = await loadArchitecture(paths.architecture);
+  const complexity = await analyzeStoryComplexity(storyContent);
+  const selectedModel = forceAdvancedModel ? config.models.oracle : selectReviewModel(config, complexity);
+  const oraclePrompt = buildFocusedReviewPrompt(
+    storyId,
+    storyContent,
+    architectureContent,
+    epicReview
+  );
+  return {
+    success: true,
+    scope: "story",
+    identifier: storyId,
+    oraclePrompt,
+    storiesContent: [{ id: storyId, content: storyContent }],
+    architectureContent,
+    existingReviews,
+    complexity,
+    selectedModel,
+    reviewsDir
+  };
+}
+async function findStoriesInEpic(storiesDir, epicNumber) {
+  if (!existsSync(storiesDir)) {
+    return [];
+  }
+  const files = await readdir(storiesDir);
+  const storyPattern = new RegExp(`^story-${epicNumber}-(\\d+)\\.md$`);
+  const stories = [];
+  for (const file of files) {
+    const match = file.match(storyPattern);
+    if (match) {
+      const storyNumber = match[1];
+      stories.push(`${epicNumber}.${storyNumber}`);
+    }
+  }
+  return stories.sort();
+}
+async function loadStoryFile2(storiesDir, storyId) {
+  const filename = `story-${storyId.replace(".", "-")}.md`;
+  const filePath = join(storiesDir, filename);
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  return await readFile(filePath, "utf-8");
+}
+async function loadArchitecture(architectureFile) {
+  if (!existsSync(architectureFile)) {
+    return "";
+  }
+  return await readFile(architectureFile, "utf-8");
+}
+function normalizeStoryId(identifier) {
+  if (identifier.includes("/")) {
+    const filename = identifier.split("/").pop() || "";
+    const match = filename.match(/story-(\d+)-(\d+)\.md/);
+    if (match) {
+      return `${match[1]}.${match[2]}`;
+    }
+  }
+  return identifier.replace(/^story-/, "").replace("-", ".");
+}
+async function findExistingReviews(reviewsDir, storyId) {
+  if (!existsSync(reviewsDir)) {
+    return [];
+  }
+  const files = await readdir(reviewsDir);
+  const reviews = [];
+  const [epicNum] = storyId.split(".");
+  for (const file of files) {
+    if (file.startsWith(`party-review-epic-${epicNum}-`)) {
+      const filePath = join(reviewsDir, file);
+      const match = file.match(/(\d{4}-\d{2}-\d{2})/);
+      reviews.push({
+        type: "epic",
+        filePath,
+        date: match ? match[1] : "",
+        findingsCount: 0,
+        acceptedCount: 0,
+        deferredCount: 0,
+        rejectedCount: 0
+      });
+    }
+  }
+  return reviews;
+}
+async function analyzeStoryComplexity(storyContent) {
+  const acMatches = storyContent.match(/^- /gm) || [];
+  const acceptanceCriteriaCount = acMatches.length;
+  const securityKeywords = /\b(auth|login|password|token|secret|encrypt|permission|role|access)\b/i;
+  const hasSecurityConcerns = securityKeywords.test(storyContent);
+  const dataKeywords = /\b(database|schema|migration|model|table|collection)\b/i;
+  const hasDataModelChanges = dataKeywords.test(storyContent);
+  const apiKeywords = /\b(api|endpoint|route|controller|handler)\b/i;
+  const hasApiChanges = apiKeywords.test(storyContent);
+  const crudPattern = /\b(create|read|update|delete|get|post|put|patch|list)\b/gi;
+  const crudMatches = storyContent.match(crudPattern) || [];
+  const isCrudOnly = crudMatches.length > 0 && !hasSecurityConcerns && !hasDataModelChanges;
+  const isSimple = acceptanceCriteriaCount < 5 && !hasSecurityConcerns && !hasDataModelChanges && isCrudOnly;
+  return {
+    isSimple,
+    reason: isSimple ? `Simple story: ${acceptanceCriteriaCount} ACs, CRUD-only, no security/data concerns` : `Complex story: ${acceptanceCriteriaCount} ACs, security=${hasSecurityConcerns}, data=${hasDataModelChanges}, API=${hasApiChanges}`,
+    recommendedModel: isSimple ? "anthropic/claude-3-5-haiku-20241022" : "openai/gpt-5.2",
+    factors: {
+      acceptanceCriteriaCount,
+      hasSecurityConcerns,
+      hasDataModelChanges,
+      hasApiChanges,
+      isCrudOnly
+    }
+  };
+}
+function selectReviewModel(config, complexity) {
+  return complexity.isSimple ? "anthropic/claude-3-5-haiku-20241022" : config.models.oracle;
+}
+function buildEpicReviewPrompt(epicNumber, storyContents, architectureContent) {
+  const storiesText = storyContents.map((s) => `## Story ${s.id}
+
+${s.content || "(empty)"}`).join("\n\n---\n\n");
+  return `You are a security, logic, and performance expert conducting a "party review" of BMAD stories BEFORE development begins.
+
+**Your Role**: Find issues while they're cheap to fix (in markdown, not code).
+
+**Focus Areas**:
+1. \u{1F512} **Security Gaps**: Missing auth/authorization, input validation, data exposure risks, credential handling
+2. \u{1F9E0} **Logic Gaps**: Edge cases not covered, error scenarios missing, validation rules incomplete, race conditions
+3. \u2728 **Best Practice Flaws**: Anti-patterns in requirements, testing strategy gaps, accessibility concerns, unclear specifications
+4. \u26A1 **Performance Issues**: Potential N+1 queries, missing caching strategy, large data handling not addressed, client-side bundle concerns
+
+**Scope**: Epic ${epicNumber} - Review ALL stories for issues AND cross-story patterns
+
+**Architecture Context**:
+${architectureContent || "(No architecture documented)"}
+
+**Stories to Review**:
+${storiesText}
+
+**Output Format** (JSON):
+{
+  "summary": {
+    "totalIssues": number,
+    "highSeverity": number,
+    "mediumSeverity": number,
+    "lowSeverity": number,
+    "recommendation": "string"
+  },
+  "storyFindings": [
+    {
+      "storyId": "string",
+      "title": "string",
+      "findings": {
+        "security": [
+          {
+            "id": "unique-id",
+            "severity": "high" | "medium" | "low",
+            "title": "Brief title",
+            "description": "What's wrong",
+            "impact": "Why it matters",
+            "suggestion": "How to fix"
+          }
+        ],
+        "logic": [...],
+        "bestPractices": [...],
+        "performance": [...]
+      }
+    }
+  ],
+  "crossStoryIssues": [
+    {
+      "id": "unique-id",
+      "category": "security" | "logic" | "bestPractices" | "performance",
+      "severity": "high" | "medium" | "low",
+      "title": "Pattern or issue across multiple stories",
+      "description": "Details",
+      "affectedStories": ["2.1", "2.3"],
+      "suggestion": "How to address"
+    }
+  ]
+}
+
+**Instructions**:
+- Be thorough but practical
+- Prioritize high-impact issues
+- Provide actionable suggestions
+- Consider the architecture constraints
+- Flag missing requirements as logic gaps
+- Look for inconsistencies across stories`;
+}
+function buildFocusedReviewPrompt(storyId, storyContent, architectureContent, epicReview) {
+  const epicContext = epicReview ? `
+
+**Previous Epic Review**: An epic-level review was conducted on ${epicReview.date}. This focused review should find NEW issues not caught in the broader epic review.` : "";
+  return `You are a security, logic, and performance expert conducting a DEEP DIVE "party review" of a single BMAD story BEFORE development begins.
+
+**Your Role**: Find issues while they're cheap to fix (in markdown, not code). This is a FOCUSED review, so be more thorough than a broad epic review.
+
+**Focus Areas**:
+1. \u{1F512} **Security Gaps**: Missing auth/authorization, input validation, data exposure risks, credential handling, session management
+2. \u{1F9E0} **Logic Gaps**: Edge cases not covered, error scenarios missing, validation rules incomplete, race conditions, state management
+3. \u2728 **Best Practice Flaws**: Anti-patterns in requirements, testing strategy gaps, accessibility concerns, unclear specifications, maintainability
+4. \u26A1 **Performance Issues**: Potential N+1 queries, missing caching strategy, large data handling, client-side bundle size, database indexes${epicContext}
+
+**Story**: ${storyId}
+
+**Architecture Context**:
+${architectureContent || "(No architecture documented)"}
+
+**Story Content**:
+${storyContent}
+
+**Output Format** (JSON):
+{
+  "summary": {
+    "totalIssues": number,
+    "highSeverity": number,
+    "mediumSeverity": number,
+    "lowSeverity": number,
+    "recommendation": "string"
+  },
+  "findings": {
+    "security": [
+      {
+        "id": "unique-id",
+        "severity": "high" | "medium" | "low",
+        "title": "Brief title",
+        "description": "What's wrong",
+        "impact": "Why it matters",
+        "suggestion": "How to fix (be specific)"
+      }
+    ],
+    "logic": [...],
+    "bestPractices": [...],
+    "performance": [...]
+  }
+}
+
+**Instructions**:
+- Be EXTREMELY thorough - this is a deep dive
+- Think like an adversarial tester trying to break the implementation
+- Question every assumption in the requirements
+- Look for vague or incomplete acceptance criteria
+- Consider security implications of every data flow
+- Flag missing error handling scenarios
+- Identify performance bottlenecks before they're coded
+- Provide highly specific, actionable suggestions`;
+}
 function createUpdateStatusTool(ctx, tracker, config) {
   return tool({
     description: `Update the BMAD sprint status for a story.
@@ -884,7 +1237,8 @@ function createTools(ctx, tracker, config) {
     athena_update_status: createUpdateStatusTool(ctx, tracker, config),
     athena_get_context: createGetContextTool(tracker),
     athena_parallel: createParallelTool(),
-    athena_config: createConfigTool(config)
+    athena_config: createConfigTool(config),
+    athena_review_story: createReviewStoryTool(ctx, config)
   };
 }
 var StoryTracker = class {