super-ralph 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Cory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# super-ralph
+
+> Reusable Ralph workflow - ticket-driven development with multi-agent review loops
+
+An opinionated [Smithers](https://smithers.sh) workflow. You just provide the specs, this workflow does the rest.
+
+Supports subscriptions.
+
+## Installation
+
+```bash
+bun add super-ralph smithers-orchestrator
+```
+
+## Usage
+
+```tsx
+import {
+  SuperRalph,
+  ralphOutputSchemas,
+} from "super-ralph";
+import {
+  createSmithers,
+  ClaudeCodeAgent,
+  CodexAgent,
+  GeminiAgent,
+} from "smithers-orchestrator";
+import PRD from "./specs/PRD.mdx";
+import EngineeringSpec from "./specs/Engineering.mdx";
+
+const { smithers, outputs } = createSmithers(ralphOutputSchemas, {
+  dbPath: "./workflow.db",
+});
+
+export default smithers((ctx) => (
+  <SuperRalph
+    ctx={ctx}
+    outputs={outputs}
+    focuses={[
+      { id: "auth", name: "Authentication" },
+      { id: "api", name: "API Server" },
+    ]}
+    projectId="my-project"
+    projectName="My Project"
+    specsPath="docs/specs/"
+    referenceFiles={["docs/reference/"]}
+    buildCmds={{ go: "go build ./...", rust: "cargo build" }}
+    testCmds={{ go: "go test ./...", rust: "cargo test" }}
+    codeStyle="Go: snake_case, Rust: snake_case"
+    reviewChecklist={["Spec compliance", "Test coverage", "Security"]}
+    maxConcurrency={12}
+    agents={{
+      planning: new CodexAgent({ model: "gpt-5.3-codex", cwd: process.cwd(), yolo: true }),
+      implementation: new ClaudeCodeAgent({ model: "claude-sonnet-4-6", cwd: process.cwd() }),
+      testing: new ClaudeCodeAgent({ model: "claude-sonnet-4-6", cwd: process.cwd() }),
+      reviewing: new CodexAgent({ model: "gpt-5.3-codex", cwd: process.cwd(), yolo: true }),
+      reporting: new GeminiAgent({ model: "gemini-2.5-pro", cwd: process.cwd(), yolo: true }),
+    }}
+  >
+    <PRD />
+    <EngineeringSpec />
+  </SuperRalph>
+));
+```
+
+That's it! 30 lines of configuration for a complete workflow.
+
+## The Pattern
+
+Under the hood this opinionated workflow is the following steps all in parallel in a pipeline
+
+```
+Ralph (infinite loop)
+  ├─ UpdateProgress → PROGRESS.md
+  ├─ CodebaseReview → per-focus reviews → tickets
+  ├─ Discover → new feature tickets
+  ├─ IntegrationTest → per-focus test runs
+  └─ TicketPipeline × N (parallel, in worktrees)
+     ├─ Research → gather context
+     ├─ Plan → TDD plan
+     ├─ ValidationLoop (loops until approved)
+     │  ├─ Implement → write tests + code
+     │  ├─ Test → run all tests
+     │  ├─ BuildVerify → check compilation
+     │  ├─ SpecReview + CodeReview (parallel)
+     │  └─ ReviewFix → fix issues
+     └─ Report → completion summary
+```
+
+This opinionated workflow is optimized in following ways:
+
+- Observability: multiple reporting steps and lots of data stored in sqlite
+- Quality: via CI checks, review loops, and context-engineered research-plan-implement steps
+- Planning: Optimizes ralph by in real time generating tickets rather than hardcoding them up front
+- Parallelization: All tickets implemented in a JJ Workspace in parallel and then merged back into the main branch as stacked changes
+
+## Advanced: Custom Components
+
+Override any step with a custom component:
+
+```tsx
+<SuperRalph
+  {...props}
+  discover={<MyCustomDiscover agent={...} />}
+/>
+```
+
+Or run additional logic in parallel:
+
+```tsx
+<SuperRalph
+  {...props}
+  discover={
+    <Parallel>
+      <SuperRalph.Discover agent={...} specsPath="..." referenceFiles={[...]} />
+      <MyAdditionalDiscovery agent={...} />
+    </Parallel>
+  }
+/>
+```
+
+These steps default to <SuperRalph.Component when not provided.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "super-ralph",
+  "version": "0.1.0",
+  "description": "Reusable Ralph workflow pattern - ticket-driven development with multi-agent review loops",
+  "author": "William Cory",
+  "license": "MIT",
+  "type": "module",
+  "module": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./selectors": "./src/selectors.ts",
+    "./components": "./src/components/index.ts"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/evmts/super-ralph.git"
+  },
+  "bugs": {
+    "url": "https://github.com/evmts/super-ralph/issues"
+  },
+  "homepage": "https://github.com/evmts/super-ralph#readme",
+  "keywords": [
+    "ai",
+    "workflow",
+    "orchestration",
+    "ralph",
+    "multi-agent",
+    "tdd",
+    "code-review"
+  ],
+  "peerDependencies": {
+    "smithers-orchestrator": "*"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "typescript": "^5.6.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/components/SuperRalph.tsx

@@ -0,0 +1,412 @@
+import { Ralph, Parallel, Sequence, Worktree, Task } from "smithers-orchestrator";
+import type { SmithersCtx } from "smithers-orchestrator";
+import { selectAllTickets, selectReviewTickets, selectProgressSummary, selectImplement, selectTestResults, selectSpecReview, selectCodeReviews } from "../selectors";
+import React, { type ReactElement, type ReactNode } from "react";
+import UpdateProgressPrompt from "../prompts/UpdateProgress.mdx";
+import DiscoverPrompt from "../prompts/Discover.mdx";
+import IntegrationTestPrompt from "../prompts/IntegrationTest.mdx";
+import ResearchPrompt from "../prompts/Research.mdx";
+import PlanPrompt from "../prompts/Plan.mdx";
+import ImplementPrompt from "../prompts/Implement.mdx";
+import TestPrompt from "../prompts/Test.mdx";
+import BuildVerifyPrompt from "../prompts/BuildVerify.mdx";
+import SpecReviewPrompt from "../prompts/SpecReview.mdx";
+import CodeReviewPrompt from "../prompts/CodeReview.mdx";
+import ReviewFixPrompt from "../prompts/ReviewFix.mdx";
+import ReportPrompt from "../prompts/Report.mdx";
+import CategoryReviewPrompt from "../prompts/CategoryReview.mdx";
+
+// Main component props (simple API)
+export type SuperRalphProps = {
+  ctx: SmithersCtx<any>;
+  focuses: ReadonlyArray<{ readonly id: string; readonly name: string }>;
+  outputs: any;
+
+  // Project config (flattened)
+  projectId: string;
+  projectName: string;
+  specsPath: string;
+  referenceFiles: string[];
+  buildCmds: Record<string, string>;
+  testCmds: Record<string, string>;
+  codeStyle: string;
+  reviewChecklist: string[];
+
+  maxConcurrency: number;
+  taskRetries?: number;
+
+  // Agents (grouped)
+  agents: {
+    planning: any;
+    implementation: any;
+    testing: any;
+    reviewing: any;
+    reporting: any;
+  };
+
+  // Configuration
+  progressFile?: string;
+  findingsFile?: string;
+  commitConfig?: {
+    prefix?: string;
+    mainBranch?: string;
+    emojiPrefixes?: string;
+  };
+  testSuites?: Array<{
+    name: string;
+    command: string;
+    description: string;
+  }>;
+  focusTestSuites?: Record<string, { suites: string[]; setupHints: string[]; testDirs: string[] }>;
+  focusDirs?: Record<string, string[]>;
+  skipPhases?: Set<string>;
+
+  // Advanced: Override any step with custom component
+  updateProgress?: ReactElement;
+  discover?: ReactElement;
+  integrationTest?: ReactElement;
+  categoryReview?: ReactElement;
+  research?: ReactElement;
+  plan?: ReactElement;
+  implement?: ReactElement;
+  test?: ReactElement;
+  buildVerify?: ReactElement;
+  specReview?: ReactElement;
+  codeReview?: ReactElement;
+  reviewFix?: ReactElement;
+  report?: ReactElement;
+
+  // Specs as children
+  children?: ReactNode;
+};
+
+export function SuperRalph({
+  ctx,
+  focuses,
+  outputs,
+  projectId,
+  projectName,
+  specsPath,
+  referenceFiles,
+  buildCmds,
+  testCmds,
+  codeStyle,
+  reviewChecklist,
+  maxConcurrency,
+  taskRetries = 3,
+  agents,
+  progressFile = "PROGRESS.md",
+  findingsFile = "docs/test-suite-findings.md",
+  commitConfig = {},
+  testSuites = [],
+  focusTestSuites = {},
+  focusDirs = {},
+  skipPhases = new Set(),
+
+  // Advanced overrides
+  updateProgress: customUpdateProgress,
+  discover: customDiscover,
+  integrationTest: customIntegrationTest,
+  categoryReview: customCategoryReview,
+  research: customResearch,
+  plan: customPlan,
+  implement: customImplement,
+  test: customTest,
+  buildVerify: customBuildVerify,
+  specReview: customSpecReview,
+  codeReview: customCodeReview,
+  reviewFix: customReviewFix,
+  report: customReport,
+
+  children,
+}: SuperRalphProps) {
+  const { findings: reviewFindings } = selectReviewTickets(ctx, focuses, outputs);
+  const { completed: completedTicketIds, unfinished: unfinishedTickets } = selectAllTickets(ctx, focuses, outputs);
+  const progressSummary = selectProgressSummary(ctx, outputs);
+
+  const { prefix = "📝", mainBranch = "main", emojiPrefixes = "✨ feat, 🐛 fix, ♻️ refactor, 📝 docs, 🧪 test" } = commitConfig;
+
+  return (
+    <Ralph until={false} maxIterations={Infinity} onMaxReached="return-last">
+      <Parallel maxConcurrency={maxConcurrency}>
+        {!skipPhases.has("PROGRESS") && (customUpdateProgress || (
+          <Task id="update-progress" output={outputs.progress} agent={agents.reporting} retries={taskRetries}>
+            <UpdateProgressPrompt
+              projectName={projectName}
+              progressFile={progressFile}
+              commitMessage={`${prefix} docs: update progress`}
+              completedTickets={completedTicketIds}
+            />
+          </Task>
+        ))}
+
+        {!skipPhases.has("CODEBASE_REVIEW") && (customCategoryReview ? (
+          customCategoryReview
+        ) : (
+          <Parallel maxConcurrency={maxConcurrency}>
+            {focuses.map(({ id, name }) => (
+              <Task key={id} id={`codebase-review:${id}`} output={outputs.category_review} agent={agents.reviewing} retries={taskRetries}>
+                <CategoryReviewPrompt categoryId={id} categoryName={name} relevantDirs={focusDirs[id] ?? null} />
+              </Task>
+            ))}
+          </Parallel>
+        ))}
+
+        {!skipPhases.has("DISCOVER") && (customDiscover || (
+          <Task id="discover" output={outputs.discover} agent={agents.planning} retries={taskRetries}>
+            <DiscoverPrompt
+              projectName={projectName}
+              specsPath={specsPath}
+              referenceFiles={referenceFiles}
+              categories={focuses}
+              completedTicketIds={completedTicketIds}
+              previousProgress={progressSummary}
+              reviewFindings={reviewFindings}
+            />
+          </Task>
+        ))}
+
+        {!skipPhases.has("INTEGRATION_TEST") && (customIntegrationTest || (
+          <Parallel maxConcurrency={maxConcurrency}>
+            {focuses.map(({ id, name }) => {
+              const suiteInfo = focusTestSuites[id] ?? { suites: [], setupHints: [], testDirs: [] };
+              return (
+                <Task key={id} id={`integration-test:${id}`} output={outputs.integration_test} agent={agents.testing} retries={taskRetries}>
+                  <IntegrationTestPrompt
+                    categoryId={id}
+                    categoryName={name}
+                    suites={suiteInfo.suites}
+                    setupHints={suiteInfo.setupHints}
+                    testDirs={suiteInfo.testDirs}
+                    findingsFile={findingsFile}
+                  />
+                </Task>
+              );
+            })}
+          </Parallel>
+        ))}
+
+        {unfinishedTickets.map((ticket: any) => {
+          const researchData = ctx.outputMaybe(outputs.research, { nodeId: `${ticket.id}:research` });
+          const planData = ctx.outputMaybe(outputs.plan, { nodeId: `${ticket.id}:plan` });
+          const contextFilePath = researchData?.contextFilePath ?? `docs/context/${ticket.id}.md`;
+          const planFilePath = planData?.planFilePath ?? `docs/plans/${ticket.id}.md`;
+
+          return (
+            <Worktree key={ticket.id} id={`wt-${ticket.id}`} path={`/tmp/workflow-wt-${ticket.id}`}>
+              <Sequence skipIf={ctx.outputMaybe(outputs.report, { nodeId: `${ticket.id}:report` })?.status === "complete"}>
+                {customResearch || (
+                  <Task id={`${ticket.id}:research`} output={outputs.research} agent={agents.planning} retries={taskRetries}>
+                    <ResearchPrompt
+                      ticketId={ticket.id}
+                      ticketTitle={ticket.title}
+                      ticketDescription={ticket.description}
+                      ticketCategory={ticket.category}
+                      referenceFiles={ticket.referenceFiles}
+                      relevantFiles={ticket.relevantFiles}
+                      contextFilePath={contextFilePath}
+                      referencePaths={[specsPath, ...referenceFiles]}
+                    />
+                  </Task>
+                )}
+
+                {customPlan || (
+                  <Task id={`${ticket.id}:plan`} output={outputs.plan} agent={agents.planning} retries={taskRetries}>
+                    <PlanPrompt
+                      ticketId={ticket.id}
+                      ticketTitle={ticket.title}
+                      ticketDescription={ticket.description}
+                      ticketCategory={ticket.category}
+                      acceptanceCriteria={ticket.acceptanceCriteria ?? []}
+                      contextFilePath={contextFilePath}
+                      researchSummary={researchData?.summary ?? null}
+                      planFilePath={planFilePath}
+                      tddPatterns={["Write tests FIRST, then implementation"]}
+                      commitPrefix={prefix}
+                      mainBranch={mainBranch}
+                    />
+                  </Task>
+                )}
+
+                {/* ValidationLoop */}
+                <Sequence>
+                  {(() => {
+                    const latestImplement = selectImplement(ctx, ticket.id);
+                    const latestTest = selectTestResults(ctx, ticket.id);
+                    const latestSpecReview = selectSpecReview(ctx, ticket.id);
+                    const { worstSeverity: worstCodeSeverity, mergedIssues: mergedCodeIssues, mergedFeedback: mergedCodeFeedback } = selectCodeReviews(ctx, ticket.id, outputs);
+
+                    const specApproved = latestSpecReview?.severity === "none";
+                    const codeApproved = worstCodeSeverity === "none";
+                    const noReviewIssues = specApproved && codeApproved;
+
+                    const toArray = (v: unknown): string[] => Array.isArray(v) ? v : typeof v === "string" ? [v] : [];
+                    const reviewFeedback = (() => {
+                      const parts: string[] = [];
+                      if (latestSpecReview && !specApproved) {
+                        parts.push(`SPEC REVIEW (${latestSpecReview.severity}): ${latestSpecReview.feedback}`);
+                        if (latestSpecReview.issues) parts.push(`Issues: ${toArray(latestSpecReview.issues).join("; ")}`);
+                      }
+                      if (!codeApproved && mergedCodeFeedback) {
+                        parts.push(`CODE REVIEW (${worstCodeSeverity}): ${mergedCodeFeedback}`);
+                        if (mergedCodeIssues.length > 0) parts.push(`Issues: ${mergedCodeIssues.join("; ")}`);
+                      }
+                      return parts.length > 0 ? parts.join("\n\n") : null;
+                    })();
+
+                    return (
+                      <>
+                        {customImplement || (
+                          <Task id={`${ticket.id}:implement`} output={outputs.implement} agent={agents.implementation} retries={taskRetries}>
+                            <ImplementPrompt
+                              ticketId={ticket.id}
+                              ticketTitle={ticket.title}
+                              ticketCategory={ticket.category}
+                              planFilePath={planFilePath}
+                              contextFilePath={contextFilePath}
+                              implementationSteps={planData?.implementationSteps ?? null}
+                              previousImplementation={latestImplement ?? null}
+                              reviewFeedback={reviewFeedback}
+                              failingTests={latestTest?.failingSummary ?? null}
+                              testWritingGuidance={["Write unit tests AND integration tests"]}
+                              implementationGuidance={["Follow architecture patterns from specs"]}
+                              formatterCommands={Object.entries(buildCmds).map(([lang, cmd]) => `Format ${lang}`)}
+                              verifyCommands={Object.values(buildCmds)}
+                              architectureRules={[`Read ${specsPath} for patterns`]}
+                              commitPrefix={prefix}
+                              mainBranch={mainBranch}
+                              emojiPrefixes={emojiPrefixes}
+                            />
+                          </Task>
+                        )}
+
+                        {customTest || (
+                          <Task id={`${ticket.id}:test`} output={outputs.test_results} agent={agents.testing} retries={taskRetries}>
+                            <TestPrompt
+                              ticketId={ticket.id}
+                              ticketTitle={ticket.title}
+                              ticketCategory={ticket.category}
+                              testSuites={testSuites.length > 0 ? testSuites : Object.entries(testCmds).map(([name, command]) => ({
+                                name: `${name} tests`,
+                                command,
+                                description: `Run ${name} tests`,
+                              }))}
+                              fixCommitPrefix={`🐛 fix`}
+                              mainBranch={mainBranch}
+                            />
+                          </Task>
+                        )}
+
+                        {customBuildVerify || (
+                          <Task id={`${ticket.id}:build-verify`} output={outputs.build_verify} agent={agents.testing} retries={taskRetries}>
+                            <BuildVerifyPrompt
+                              ticketId={ticket.id}
+                              ticketTitle={ticket.title}
+                              ticketCategory={ticket.category}
+                              filesCreated={latestImplement?.filesCreated ?? null}
+                              filesModified={latestImplement?.filesModified ?? null}
+                              whatWasDone={latestImplement?.whatWasDone ?? null}
+                            />
+                          </Task>
+                        )}
+
+                        <Parallel maxConcurrency={maxConcurrency}>
+                          {customSpecReview || (
+                            <Task id={`${ticket.id}:spec-review`} output={outputs.spec_review} agent={agents.reviewing} retries={taskRetries}>
+                              <SpecReviewPrompt
+                                ticketId={ticket.id}
+                                ticketTitle={ticket.title}
+                                ticketCategory={ticket.category}
+                                filesCreated={latestImplement?.filesCreated ?? null}
+                                filesModified={latestImplement?.filesModified ?? null}
+                                testResults={[
+                                  { name: "Tests", status: latestTest?.goTestsPassed ? "PASS" : "FAIL" },
+                                ]}
+                                failingSummary={latestTest?.failingSummary ?? null}
+                                specChecks={[
+                                  { name: "Code Style", items: [codeStyle] },
+                                  { name: "Review Checklist", items: reviewChecklist },
+                                ]}
+                              />
+                            </Task>
+                          )}
+
+                          {customCodeReview || (
+                            <Task id={`${ticket.id}:code-review`} output={outputs.code_review} agent={agents.reviewing} retries={taskRetries}>
+                              <CodeReviewPrompt
+                                ticketId={ticket.id}
+                                ticketTitle={ticket.title}
+                                ticketCategory={ticket.category}
+                                filesCreated={latestImplement?.filesCreated ?? null}
+                                filesModified={latestImplement?.filesModified ?? null}
+                                reviewChecklist={reviewChecklist}
+                              />
+                            </Task>
+                          )}
+                        </Parallel>
+
+                        {customReviewFix || (!noReviewIssues && (
+                          <Task id={`${ticket.id}:review-fix`} output={outputs.review_fix} agent={agents.implementation} retries={taskRetries}>
+                            <ReviewFixPrompt
+                              ticketId={ticket.id}
+                              ticketTitle={ticket.title}
+                              ticketCategory={ticket.category}
+                              specSeverity={latestSpecReview?.severity ?? "none"}
+                              specFeedback={latestSpecReview?.feedback ?? ""}
+                              specIssues={latestSpecReview?.issues ?? null}
+                              codeSeverity={worstCodeSeverity}
+                              codeFeedback={mergedCodeFeedback}
+                              codeIssues={mergedCodeIssues.length > 0 ? mergedCodeIssues : null}
+                              validationCommands={Object.values(testCmds)}
+                              commitPrefix={`🐛 fix`}
+                              mainBranch={mainBranch}
+                              emojiPrefixes={emojiPrefixes}
+                            />
+                          </Task>
+                        ))}
+                      </>
+                    );
+                  })()}
+                </Sequence>
+
+                {customReport || (
+                  <Task id={`${ticket.id}:report`} output={outputs.report} agent={agents.reporting} retries={taskRetries}>
+                    <ReportPrompt
+                      ticketId={ticket.id}
+                      ticketTitle={ticket.title}
+                      ticketCategory={ticket.category}
+                      acceptanceCriteria={ticket.acceptanceCriteria ?? []}
+                      specSeverity={ctx.outputMaybe(outputs.spec_review, { nodeId: `${ticket.id}:spec-review` })?.severity ?? "none"}
+                      codeSeverity={selectCodeReviews(ctx, ticket.id, outputs).worstSeverity}
+                      allIssuesResolved={ctx.outputMaybe(outputs.review_fix, { nodeId: `${ticket.id}:review-fix` })?.allIssuesResolved ?? true}
+                      reviewRounds={1}
+                      goTests={selectTestResults(ctx, ticket.id)?.goTestsPassed ? "PASS" : "FAIL"}
+                      rustTests={selectTestResults(ctx, ticket.id)?.rustTestsPassed ? "PASS" : "FAIL"}
+                      e2eTests={selectTestResults(ctx, ticket.id)?.e2eTestsPassed ? "PASS" : "FAIL"}
+                      sqlcGen={selectTestResults(ctx, ticket.id)?.sqlcGenPassed ? "PASS" : "FAIL"}
+                    />
+                  </Task>
+                )}
+              </Sequence>
+            </Worktree>
+          );
+        })}
+      </Parallel>
+    </Ralph>
+  );
+}
+
+// Compound components for advanced customization
+SuperRalph.UpdateProgress = function UpdateProgress(_props: any) { return null; };
+SuperRalph.Discover = function Discover(_props: any) { return null; };
+SuperRalph.IntegrationTest = function IntegrationTest(_props: any) { return null; };
+SuperRalph.CategoryReview = function CategoryReview(_props: any) { return null; };
+SuperRalph.Research = function Research(_props: any) { return null; };
+SuperRalph.Plan = function Plan(_props: any) { return null; };
+SuperRalph.Implement = function Implement(_props: any) { return null; };
+SuperRalph.Test = function Test(_props: any) { return null; };
+SuperRalph.BuildVerify = function BuildVerify(_props: any) { return null; };
+SuperRalph.SpecReview = function SpecReview(_props: any) { return null; };
+SuperRalph.CodeReview = function CodeReview(_props: any) { return null; };
+SuperRalph.ReviewFix = function ReviewFix(_props: any) { return null; };
+SuperRalph.Report = function Report(_props: any) { return null; };

package/src/components/index.ts

@@ -0,0 +1,2 @@
+export { SuperRalph } from "./SuperRalph";
+export type { SuperRalphProps } from "./SuperRalph";

package/src/hooks/index.ts

@@ -0,0 +1,2 @@
+export { useSuperRalph } from "./useSuperRalph";
+export type { SuperRalphContext, UseSuperRalphConfig } from "./useSuperRalph";

package/src/hooks/useSuperRalph.ts

@@ -0,0 +1,40 @@
+import type { SmithersCtx } from "smithers-orchestrator";
+import { selectAllTickets, selectReviewTickets, selectProgressSummary } from "../selectors";
+
+export type SuperRalphContext = {
+  ctx: SmithersCtx<any>;
+  completedTicketIds: string[];
+  unfinishedTickets: any[];
+  reviewFindings: string | null;
+  progressSummary: string | null;
+  focuses: ReadonlyArray<{ readonly id: string; readonly name: string }>;
+  outputs: any;
+  target: any;
+};
+
+export type UseSuperRalphConfig = {
+  focuses: ReadonlyArray<{ readonly id: string; readonly name: string }>;
+  outputs: any;
+  target: any;
+};
+
+/**
+ * Hook to extract SuperRalph state from SmithersCtx.
+ * Use this for controlled component pattern or to access workflow state.
+ */
+export function useSuperRalph(ctx: SmithersCtx<any>, config: UseSuperRalphConfig): SuperRalphContext {
+  const { findings: reviewFindings } = selectReviewTickets(ctx, config.focuses, config.outputs);
+  const { completed: completedTicketIds, unfinished: unfinishedTickets } = selectAllTickets(ctx, config.focuses, config.outputs);
+  const progressSummary = selectProgressSummary(ctx, config.outputs);
+
+  return {
+    ctx,
+    completedTicketIds,
+    unfinishedTickets,
+    reviewFindings,
+    progressSummary,
+    focuses: config.focuses,
+    outputs: config.outputs,
+    target: config.target,
+  };
+}