supipowers 0.2.6 → 0.3.0

package/src/planning/plan-writer-prompt.ts

@@ -0,0 +1,173 @@
+import { buildPlanReviewerPrompt } from "./plan-reviewer.js";
+
+export interface PlanWriterOptions {
+  specPath: string;
+}
+
+/**
+ * Build the plan writing prompt that guides the agent through creating
+ * a comprehensive implementation plan from an approved spec.
+ *
+ * Follows superpowers' writing-plans skill:
+ * - Scope check
+ * - File structure mapping
+ * - Bite-sized tasks with TDD steps
+ * - Plan review loop per chunk
+ * - Execution handoff
+ */
+export function buildPlanWriterPrompt(options: PlanWriterOptions): string {
+  const { specPath } = options;
+
+  const sections: string[] = [
+    "You are writing a comprehensive implementation plan from an approved design spec.",
+    "",
+    `**Spec document:** ${specPath}`,
+    "",
+    "Write the plan assuming the implementing engineer has zero context for this codebase.",
+    "Document everything they need: which files to touch, complete code, testing, exact commands.",
+    "Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.",
+    "",
+
+    // ── Scope Check ──────────────────────────────────────────────
+    "## Scope Check",
+    "",
+    "If the spec covers multiple independent subsystems, suggest breaking into separate plans.",
+    "Each plan should produce working, testable software on its own.",
+    "",
+
+    // ── File Structure ───────────────────────────────────────────
+    "## Step 1: Map file structure",
+    "",
+    "Before defining tasks, map out which files will be created or modified and what each one is responsible for.",
+    "This is where decomposition decisions get locked in.",
+    "",
+    "- Each file should have one clear responsibility with a well-defined interface",
+    "- Prefer smaller, focused files over large ones that do too much",
+    "- Files that change together should live together — split by responsibility, not by technical layer",
+    "- In existing codebases, follow established patterns",
+    "",
+
+    // ── Plan Header ──────────────────────────────────────────────
+    "## Step 2: Write Plan Document",
+    "",
+    "Every plan MUST start with this header:",
+    "",
+    "```markdown",
+    "# [Feature Name] Implementation Plan",
+    "",
+    "**Goal:** [One sentence describing what this builds]",
+    "",
+    "**Architecture:** [2-3 sentences about approach]",
+    "",
+    "**Tech Stack:** [Key technologies/libraries]",
+    "",
+    "---",
+    "```",
+    "",
+
+    // ── Task Granularity ─────────────────────────────────────────
+    "## Step 3: Define Bite-Sized Tasks",
+    "",
+    "Each step is one action (2-5 minutes):",
+    "- Write the failing test — one step",
+    "- Run it to verify it fails — one step",
+    "- Write minimal implementation — one step",
+    "- Run tests to verify it passes — one step",
+    "- Commit — one step",
+    "",
+
+    // ── Task Structure ───────────────────────────────────────────
+    "### Task Structure Template",
+    "",
+    "````markdown",
+    "### Task N: [Component Name]",
+    "",
+    "**Files:**",
+    "- Create: `exact/path/to/file.ts`",
+    "- Modify: `exact/path/to/existing.ts:123-145`",
+    "- Test: `tests/exact/path/to/test.ts`",
+    "",
+    "- [ ] **Step 1: Write the failing test**",
+    "",
+    "```typescript",
+    "test('specific behavior', () => {",
+    "  const result = myFunction(input);",
+    "  expect(result).toBe(expected);",
+    "});",
+    "```",
+    "",
+    "- [ ] **Step 2: Run test to verify it fails**",
+    "",
+    "Run: `npx vitest run tests/path/test.ts`",
+    'Expected: FAIL with "myFunction is not defined"',
+    "",
+    "- [ ] **Step 3: Write minimal implementation**",
+    "",
+    "```typescript",
+    "export function myFunction(input: string): string {",
+    "  return expected;",
+    "}",
+    "```",
+    "",
+    "- [ ] **Step 4: Run test to verify it passes**",
+    "",
+    "Run: `npx vitest run tests/path/test.ts`",
+    "Expected: PASS",
+    "",
+    "- [ ] **Step 5: Commit**",
+    "",
+    "```bash",
+    "git add tests/path/test.ts src/path/file.ts",
+    'git commit -m "feat: add specific feature"',
+    "```",
+    "````",
+    "",
+
+    // ── Remember ─────────────────────────────────────────────────
+    "### Requirements",
+    "",
+    "- Exact file paths always",
+    "- Complete code in plan (not 'add validation' — show the actual code)",
+    "- Exact commands with expected output",
+    "- DRY, YAGNI, TDD, frequent commits",
+    "",
+
+    // ── Plan Review Loop ─────────────────────────────────────────
+    "## Step 4: plan review loop",
+    "",
+    "After completing each chunk of the plan, dispatch a plan-document-reviewer sub-agent.",
+    "",
+    "Use `## Chunk N: <name>` headings to delimit chunks. Each chunk should be under 1000 lines and logically self-contained.",
+    "",
+    "1. Dispatch the reviewer with this prompt:",
+    "",
+    "```",
+    buildPlanReviewerPrompt("<plan-file-path>", specPath, 1),
+    "```",
+    "",
+    "(Replace `<plan-file-path>` with actual path and adjust Chunk number.)",
+    "",
+    "2. If **Issues Found**: fix the issues, re-dispatch the reviewer",
+    "3. Repeat until **Approved** (max 5 iterations, then surface to human for guidance)",
+    "4. Proceed to next chunk or execution handoff",
+    "",
+
+    // ── Save Location ────────────────────────────────────────────
+    "## Step 5: Save Plan",
+    "",
+    "Save the plan to `.omp/supipowers/plans/YYYY-MM-DD-<feature-name>.md`",
+    "",
+
+    // ── Execution Handoff ────────────────────────────────────────
+    "## Step 6: Execution Handoff",
+    "",
+    "After saving the plan, ask:",
+    "",
+    '> "Plan complete and saved to `<path>`. Ready to execute?"',
+    "",
+    "Wait for user confirmation before proceeding to execution.",
+    "",
+  ];
+
+  return sections.join("\n");
+}

package/src/planning/prompt-builder.ts

@@ -0,0 +1,178 @@
+import { buildSpecReviewerPrompt } from "./spec-reviewer.js";
+import { buildPlanWriterPrompt } from "./plan-writer-prompt.js";
+
+export interface PlanningPromptOptions {
+  topic?: string;
+  skillContent?: string;
+}
+
+/**
+ * Build the comprehensive planning prompt that encodes the full brainstorming flow.
+ * This is the steering prompt sent to the agent when `/supi:plan` runs.
+ *
+ * Follows superpowers' brainstorming skill flow:
+ * 1. Explore project context
+ * 2. Ask clarifying questions (one at a time)
+ * 3. Propose 2-3 approaches with trade-offs
+ * 4. Present design section by section
+ * 5. Write design doc to docs/supipowers/specs/
+ * 6. Spec review loop (dispatch reviewer sub-agent)
+ * 7. User review gate
+ * 8. Handoff to implementation plan
+ */
+export function buildPlanningPrompt(options: PlanningPromptOptions): string {
+  const { topic, skillContent } = options;
+
+  const sections: string[] = [
+    "You are starting a collaborative planning session with the user.",
+    "Follow this process step by step. Do NOT skip phases or combine them.",
+    "",
+
+    // ── Phase 1: Context ─────────────────────────────────────────
+    "## Phase 1: Explore project context",
+    "",
+    "Before asking questions, understand the current project context:",
+    "- Check files, docs, recent commits",
+    "- Understand existing architecture and patterns",
+    "- Assess scope: if the request describes multiple independent subsystems, flag it immediately and help decompose into sub-projects before proceeding",
+    "",
+
+    // ── Topic ────────────────────────────────────────────────────
+    topic
+      ? `The user wants to plan: ${topic}`
+      : "Ask the user what they want to build or accomplish.",
+    "",
+
+    // ── Phase 2: Clarify ─────────────────────────────────────────
+    "## Phase 2: Ask Clarifying Questions",
+    "",
+    "- Ask one question at a time — never overwhelm with multiple questions",
+    "- Prefer **multiple choice** questions when possible, but open-ended is fine too",
+    "- Focus on: purpose, constraints, success criteria",
+    "- If a topic needs more exploration, break it into multiple questions",
+    "- Continue until you have enough clarity to propose approaches",
+    "",
+
+    // ── Phase 3: Approaches ──────────────────────────────────────
+    "## Phase 3: Propose 2-3 Approaches",
+    "",
+    "- Present 2-3 different approaches with trade-offs",
+    "- Lead with your recommended option and explain why",
+    "- Present options conversationally with your recommendation and reasoning",
+    "- Wait for the user to choose before proceeding",
+    "",
+
+    // ── Phase 4: Design ──────────────────────────────────────────
+    "## Phase 4: Present Design",
+    "",
+    "Once aligned on approach, present the design:",
+    "- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced",
+    "- Cover: architecture, components, data flow, error handling, testing",
+    "- Ask after each section whether it looks right so far",
+    "- Design for isolation and clarity: smaller units with clear boundaries",
+    "- Apply YAGNI ruthlessly — remove unnecessary features",
+    "- Be ready to go back and clarify if something doesn't make sense",
+    "",
+
+    // ── Phase 5: Write Spec ──────────────────────────────────────
+    "## Phase 5: Write Design Doc",
+    "",
+    "Once the user approves the design:",
+    "- Write the validated design doc to `docs/supipowers/specs/YYYY-MM-DD-<topic>-design.md`",
+    "- Use clear, concise writing",
+    "- Commit the design document to git",
+    "",
+
+    // ── Phase 6: Spec Review Loop ────────────────────────────────
+    "## Phase 6: Spec Review Loop",
+    "",
+    "After writing the design doc, dispatch a spec-document-reviewer sub-agent to verify it:",
+    "",
+    "1. Dispatch the reviewer with this prompt:",
+    "",
+    "```",
+    buildSpecReviewerPrompt("<path-to-spec-file>"),
+    "```",
+    "",
+    "(Replace `<path-to-spec-file>` with the actual spec path.)",
+    "",
+    "2. If **Issues Found**: fix the issues, re-dispatch the reviewer",
+    "3. Repeat until **Approved** (max 5 iterations, then surface to human for guidance)",
+    "",
+
+    // ── Phase 7: User Gate ───────────────────────────────────────
+    "## Phase 7: User Review Gate",
+    "",
+    "After the spec review loop passes:",
+    "",
+    "After the spec review loop passes, ask the user to review the spec before proceeding:",
+    "",
+    '> "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."',
+    "",
+    "Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.",
+    "",
+
+    // ── Phase 8: Handoff ─────────────────────────────────────────
+    "## Phase 8: Transition to Implementation Plan",
+    "",
+    "Once the user approves the spec, write a comprehensive implementation plan.",
+    "Follow these plan writing instructions:",
+    "",
+    buildPlanWriterPrompt({ specPath: "<path-to-approved-spec>" }),
+    "",
+    "(Replace `<path-to-approved-spec>` with the actual spec file path from Phase 5.)",
+    "",
+
+    // ── Principles ───────────────────────────────────────────────
+    "## Key Principles",
+    "",
+    "- **One question at a time** — Don't overwhelm with multiple questions",
+    "- **Multiple choice preferred** — Easier to answer than open-ended when possible",
+    "- **YAGNI ruthlessly** — Remove unnecessary features from all designs",
+    "- **Explore alternatives** — Always propose 2-3 approaches before settling",
+    "- **Incremental validation** — Present design, get approval before moving on",
+    "- **Decompose large scope** — If the request covers multiple independent subsystems, decompose into sub-projects first",
+    "- **Design for isolation** — Smaller units with clear boundaries and well-defined interfaces",
+    "",
+  ];
+
+  if (skillContent) {
+    sections.push(
+      "## Additional Planning Guidelines",
+      "",
+      skillContent,
+      "",
+    );
+  }
+
+  return sections.join("\n");
+}
+
+/**
+ * Build the quick plan prompt that skips brainstorming.
+ * Used when `/supi:plan --quick <description>` is invoked.
+ */
+export function buildQuickPlanPrompt(description: string, skillContent?: string): string {
+  const sections: string[] = [
+    "Generate a concise implementation plan for the following task.",
+    "Skip brainstorming — go straight to task breakdown.",
+    "",
+    `Task: ${description}`,
+    "",
+    "Format the plan as markdown with YAML frontmatter (name, created, tags).",
+    "Each task should have: name, [parallel-safe] or [sequential] annotation,",
+    "**files**, **criteria**, and **complexity** (small/medium/large).",
+    "",
+    "After generating the plan, save it and confirm with the user.",
+  ];
+
+  if (skillContent) {
+    sections.push(
+      "",
+      "Follow these planning guidelines:",
+      skillContent,
+    );
+  }
+
+  return sections.join("\n");
+}

package/src/planning/spec-reviewer.ts

@@ -0,0 +1,43 @@
+/**
+ * Build the prompt for dispatching a spec document reviewer sub-agent.
+ * Follows the same pattern as superpowers' spec-document-reviewer-prompt.md.
+ */
+export function buildSpecReviewerPrompt(specFilePath: string): string {
+  return [
+    "You are a spec-document-reviewer. Verify this spec is complete and ready for planning.",
+    "",
+    `**Spec to review:** ${specFilePath}`,
+    "",
+    "## What to Check",
+    "",
+    "| Category | What to Look For |",
+    "|----------|------------------|",
+    "| Completeness | TODO markers, placeholders, \"TBD\", incomplete sections |",
+    "| Coverage | Missing error handling, edge cases, integration points |",
+    "| Consistency | Internal contradictions, conflicting requirements |",
+    "| Clarity | Ambiguous requirements that could be interpreted multiple ways |",
+    "| YAGNI | Unrequested features, over-engineering, gold-plating |",
+    "| Scope | Focused enough for a single plan — not covering multiple independent subsystems |",
+    "| Architecture | Units with clear boundaries, well-defined interfaces, independently understandable and testable |",
+    "",
+    "## Critical",
+    "",
+    "Look especially hard for:",
+    "- Any TODO markers or placeholder text",
+    '- Sections saying "to be defined later" or "will spec when X is done"',
+    "- Sections noticeably less detailed than others",
+    "- Units that lack clear boundaries or interfaces",
+    "",
+    "## Output Format",
+    "",
+    "## Spec Review",
+    "",
+    "**Status:** Approved | Issues Found",
+    "",
+    "**Issues (if any):**",
+    "- [Section X]: [specific issue] — [why it matters]",
+    "",
+    "**Recommendations (advisory):**",
+    "- [suggestions that don't block approval]",
+  ].join("\n");
+}

package/src/qa/phases/discovery.ts

@@ -0,0 +1,34 @@
+import type { DetectedFramework } from "../detector.js";
+
+export function buildDiscoveryPrompt(framework: DetectedFramework, cwd: string): string {
+  const sections: string[] = [
+    "# QA Phase: Test Discovery",
+    "",
+    `Project: ${cwd}`,
+    `Test framework: ${framework.name} (command: \`${framework.command}\`)`,
+    "",
+    "## Task",
+    "",
+    "Scan the project for all test files and enumerate every individual test case.",
+    "",
+    "1. Find all test files matching the framework's conventions",
+    "2. Parse each file to extract individual test/it/describe blocks",
+    "3. Classify each test with tags (unit, integration, e2e) based on file path or naming",
+    "",
+    "## Expected Output",
+    "",
+    "Write a JSON array to the QA session ledger's `tests` field. Each entry:",
+    "",
+    "```json",
+    '[{ "id": "<filePath>:<testName>", "filePath": "relative/path.test.ts", "testName": "test name", "suiteName": "describe block", "tags": ["unit"] }]',
+    "```",
+    "",
+    "The `id` must be deterministic: use `filePath:testName` so it stays stable across sessions.",
+    "",
+    "## After Completion",
+    "",
+    "Update the QA session ledger with the discovered tests, mark the discovery phase as completed, then invoke `/supi:qa` to continue to the next phase.",
+  ];
+
+  return sections.join("\n");
+}

package/src/qa/phases/execution.ts

@@ -0,0 +1,65 @@
+import type { QaSessionLedger, QaTestCase } from "../../types.js";
+
+export interface ExecutionOptions {
+  failedOnly: true;
+  failedTests: QaTestCase[];
+}
+
+export function buildExecutionPrompt(
+  ledger: QaSessionLedger,
+  options?: ExecutionOptions
+): string {
+  const isRetry = options?.failedOnly === true;
+  const targetTests = isRetry ? options.failedTests : ledger.tests;
+
+  const testList = targetTests
+    .map((t) => `- ${t.id}: ${t.testName} (${t.filePath})`)
+    .join("\n");
+
+  const sections: string[] = [
+    "# QA Phase: Test Execution",
+    "",
+    `Framework: ${ledger.framework}`,
+  ];
+
+  if (isRetry) {
+    sections.push(
+      "",
+      `## Re-running ${targetTests.length} failed test(s)`,
+      "",
+      "Run ONLY the following failed tests:",
+      "",
+      testList,
+    );
+  } else {
+    sections.push(
+      "",
+      `## Running all ${targetTests.length} test(s)`,
+      "",
+      testList,
+    );
+  }
+
+  sections.push(
+    "",
+    "## Instructions",
+    "",
+    "1. Run the tests using the framework's CLI",
+    "2. Collect per-test results: pass, fail, or skip",
+    "3. For failures, capture the error message",
+    "",
+    "## Expected Output",
+    "",
+    "Write a JSON array to the QA session ledger's `results` field:",
+    "",
+    "```json",
+    '[{ "testId": "file.test.ts:test name", "status": "pass|fail|skip", "duration": 123, "error": "only if failed" }]',
+    "```",
+    "",
+    "## After Completion",
+    "",
+    "Update the QA session ledger with results, mark the execution phase as completed, then invoke `/supi:qa` to continue to the next phase.",
+  );
+
+  return sections.join("\n");
+}

package/src/qa/phases/matrix.ts

@@ -0,0 +1,41 @@
+import type { QaSessionLedger } from "../../types.js";
+
+export function buildMatrixPrompt(ledger: QaSessionLedger): string {
+  const testSummary = ledger.tests
+    .map((t) => `- ${t.id}: ${t.testName} (${t.filePath})${t.tags ? ` [${t.tags.join(", ")}]` : ""}`)
+    .join("\n");
+
+  const sections: string[] = [
+    "# QA Phase: Traceability Matrix",
+    "",
+    `Framework: ${ledger.framework}`,
+    `Discovered tests: ${ledger.tests.length}`,
+    "",
+    "## Discovered Tests",
+    "",
+    testSummary,
+    "",
+    "## Task",
+    "",
+    "Build a traceability matrix that maps requirements to test cases and platforms.",
+    "",
+    "1. Read the project's README, PR descriptions, code comments, and doc files to identify requirements",
+    "2. Map each requirement to the test case IDs that cover it",
+    "3. Identify target platforms (node, browser, CI) from project config",
+    "4. Assess coverage: full (all paths tested), partial (some paths), none (no tests)",
+    "",
+    "## Expected Output",
+    "",
+    "Write a JSON array to the QA session ledger's `matrix` field:",
+    "",
+    "```json",
+    '[{ "requirement": "User login validates email format", "testIds": ["auth.test.ts:validates email"], "platforms": ["node"], "coverage": "full" }]',
+    "```",
+    "",
+    "## After Completion",
+    "",
+    "Update the QA session ledger with the matrix, mark the matrix phase as completed, then invoke `/supi:qa` to continue to the next phase.",
+  ];
+
+  return sections.join("\n");
+}

package/src/qa/phases/reporting.ts

@@ -0,0 +1,71 @@
+import type { QaSessionLedger } from "../../types.js";
+
+export function buildReportingPrompt(ledger: QaSessionLedger): string {
+  const passed = ledger.results.filter((r) => r.status === "pass").length;
+  const failed = ledger.results.filter((r) => r.status === "fail").length;
+  const skipped = ledger.results.filter((r) => r.status === "skip").length;
+  const total = ledger.results.length;
+
+  const failedList = ledger.results
+    .filter((r) => r.status === "fail")
+    .map((r) => {
+      const test = ledger.tests.find((t) => t.id === r.testId);
+      return `- ${test?.testName ?? r.testId}: ${r.error ?? "no error captured"}`;
+    })
+    .join("\n");
+
+  const matrixSummary = ledger.matrix.length > 0
+    ? ledger.matrix
+        .map((m) => `- ${m.requirement}: ${m.coverage} coverage (${m.testIds.length} tests)`)
+        .join("\n")
+    : "No traceability matrix available.";
+
+  const sections: string[] = [
+    "# QA Phase: Reporting",
+    "",
+    `Framework: ${ledger.framework}`,
+    `Session: ${ledger.id}`,
+    "",
+    "## Execution Summary",
+    "",
+    `- Total: ${total}`,
+    `- Passed: ${passed}`,
+    `- Failed: ${failed}`,
+    `- Skipped: ${skipped}`,
+    `- Pass rate: ${total > 0 ? Math.round((passed / total) * 100) : 0}%`,
+    "",
+  ];
+
+  if (failed > 0) {
+    sections.push("## Failed Tests", "", failedList, "");
+  }
+
+  sections.push(
+    "## Traceability Matrix",
+    "",
+    matrixSummary,
+    "",
+    "## Task",
+    "",
+    "Analyze the test results and traceability matrix above. Produce a QA report summary that includes:",
+    "",
+    "1. Overall assessment of test health",
+    "2. Coverage gaps identified from the matrix",
+    "3. Recommendations for improving coverage",
+    "4. Risk areas where failures cluster",
+    "",
+    "## Expected Output",
+    "",
+    "Write a JSON object to the QA session ledger's `report` field:",
+    "",
+    "```json",
+    `{ "generatedAt": "ISO timestamp", "total": ${total}, "passed": ${passed}, "failed": ${failed}, "skipped": ${skipped}, "passRate": ${total > 0 ? Math.round((passed / total) * 100) : 0}, "failedTests": [...], "coverageSummary": "free-text analysis" }`,
+    "```",
+    "",
+    "## After Completion",
+    "",
+    "Update the QA session ledger with the report, mark the reporting phase as completed. The QA pipeline is now complete.",
+  );
+
+  return sections.join("\n");
+}