@arvorco/relentless 0.1.0

package/src/agents/types.ts

@@ -0,0 +1,101 @@
+/**
+ * Relentless Agent Adapter Types
+ *
+ * Defines the interface that all AI coding agents must implement
+ * to work with the Relentless orchestrator.
+ */
+
+export type AgentName = "claude" | "amp" | "opencode" | "codex" | "droid" | "gemini";
+
+export interface InvokeOptions {
+  /** Working directory for the agent */
+  workingDirectory?: string;
+  /** Timeout in milliseconds */
+  timeout?: number;
+  /** Model to use (agent-specific) */
+  model?: string;
+  /** Skip all permission prompts */
+  dangerouslyAllowAll?: boolean;
+}
+
+/**
+ * Rate limit detection result
+ */
+export interface RateLimitInfo {
+  /** Whether the agent is rate limited */
+  limited: boolean;
+  /** When the rate limit resets (if known) */
+  resetTime?: Date;
+  /** Raw error message */
+  message?: string;
+}
+
+export interface AgentResult {
+  /** Raw output from the agent */
+  output: string;
+  /** Exit code of the process */
+  exitCode: number;
+  /** Whether the agent signaled completion */
+  isComplete: boolean;
+  /** Duration in milliseconds */
+  duration: number;
+  /** Whether the agent hit rate limits */
+  rateLimited?: boolean;
+  /** When the rate limit resets */
+  resetTime?: Date;
+}
+
+export interface AgentAdapter {
+  /** Agent identifier */
+  name: AgentName;
+
+  /** Human-readable display name */
+  displayName: string;
+
+  /** Check if the agent is installed on this system */
+  isInstalled(): Promise<boolean>;
+
+  /** Get the path to the agent executable */
+  getExecutablePath(): Promise<string | null>;
+
+  /** Invoke the agent with a prompt */
+  invoke(prompt: string, options?: InvokeOptions): Promise<AgentResult>;
+
+  /** Invoke the agent with streaming output */
+  invokeStream?(
+    prompt: string,
+    options?: InvokeOptions
+  ): AsyncGenerator<string, AgentResult, unknown>;
+
+  /** Detect if the output indicates completion */
+  detectCompletion(output: string): boolean;
+
+  /** Detect if the output indicates rate limiting */
+  detectRateLimit(output: string): RateLimitInfo;
+
+  /** Whether this agent supports skills/plugins */
+  hasSkillSupport: boolean;
+
+  /** Command to install skills for this agent (if supported) */
+  skillInstallCommand?: string;
+
+  /** Install skills to the agent (if supported) */
+  installSkills?(projectPath: string): Promise<void>;
+}
+
+/**
+ * Story types for smart routing
+ */
+export type StoryType = "database" | "ui" | "api" | "test" | "refactor" | "docs" | "general";
+
+/**
+ * Agent specializations for smart routing
+ */
+export const AGENT_SPECIALIZATIONS: Record<AgentName, StoryType[]> = {
+  claude: ["database", "refactor", "api", "general"],
+  amp: ["ui", "test", "general"],
+  opencode: ["api", "general"],
+  codex: ["api", "database", "general"],
+  droid: ["refactor", "test", "general"],
+  gemini: ["docs", "general"],
+};

package/src/config/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Configuration Module
+ *
+ * Re-exports configuration types and functions
+ */
+
+export * from "./schema";
+export * from "./loader";

package/src/config/loader.ts

@@ -0,0 +1,237 @@
+/**
+ * Configuration Loader
+ *
+ * Loads and validates relentless/config.json and constitution.md
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { RelentlessConfigSchema, DEFAULT_CONFIG, type RelentlessConfig } from "./schema";
+
+const CONFIG_FILENAME = "config.json";
+const CONSTITUTION_FILENAME = "constitution.md";
+const RELENTLESS_DIR = "relentless";
+
+/**
+ * Find the relentless directory in the current or parent directories
+ */
+export function findRelentlessDir(startDir: string = process.cwd()): string | null {
+  let dir = startDir;
+
+  while (dir !== "/") {
+    const relentlessPath = join(dir, RELENTLESS_DIR);
+    if (existsSync(relentlessPath)) {
+      return relentlessPath;
+    }
+    dir = join(dir, "..");
+  }
+
+  return null;
+}
+
+/**
+ * Find the config file in the relentless directory
+ */
+export function findConfigFile(startDir: string = process.cwd()): string | null {
+  const relentlessDir = findRelentlessDir(startDir);
+  if (!relentlessDir) {
+    return null;
+  }
+
+  const configPath = join(relentlessDir, CONFIG_FILENAME);
+  if (existsSync(configPath)) {
+    return configPath;
+  }
+
+  return null;
+}
+
+/**
+ * Load configuration from file
+ */
+export async function loadConfig(configPath?: string): Promise<RelentlessConfig> {
+  const path = configPath ?? findConfigFile();
+
+  if (!path) {
+    console.warn(`No relentless/${CONFIG_FILENAME} found, using defaults`);
+    return DEFAULT_CONFIG;
+  }
+
+  try {
+    const content = await Bun.file(path).text();
+    const json = JSON.parse(content);
+    const validated = RelentlessConfigSchema.parse(json);
+    return validated;
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`Invalid JSON in ${path}: ${error.message}`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Save configuration to file
+ */
+export async function saveConfig(
+  config: RelentlessConfig,
+  path: string = join(process.cwd(), RELENTLESS_DIR, CONFIG_FILENAME)
+): Promise<void> {
+  const validated = RelentlessConfigSchema.parse(config);
+  const content = JSON.stringify(validated, null, 2);
+  await Bun.write(path, content);
+}
+
+/**
+ * Create a default configuration file
+ */
+export async function createDefaultConfig(
+  dir: string = process.cwd()
+): Promise<string> {
+  const path = join(dir, RELENTLESS_DIR, CONFIG_FILENAME);
+  await saveConfig(DEFAULT_CONFIG, path);
+  return path;
+}
+
+/**
+ * Find the constitution file in the relentless directory
+ */
+export function findConstitutionFile(startDir: string = process.cwd()): string | null {
+  const relentlessDir = findRelentlessDir(startDir);
+  if (!relentlessDir) {
+    return null;
+  }
+
+  const constitutionPath = join(relentlessDir, CONSTITUTION_FILENAME);
+  if (existsSync(constitutionPath)) {
+    return constitutionPath;
+  }
+
+  return null;
+}
+
+/**
+ * Constitution principle level
+ */
+export type PrincipleLevel = "MUST" | "SHOULD";
+
+/**
+ * Parsed constitution principle
+ */
+export interface Principle {
+  level: PrincipleLevel;
+  text: string;
+  section: string;
+}
+
+/**
+ * Parsed constitution
+ */
+export interface Constitution {
+  raw: string;
+  principles: Principle[];
+  sections: string[];
+}
+
+/**
+ * Parse constitution markdown to extract MUST/SHOULD principles
+ */
+export function parseConstitution(content: string): Constitution {
+  const principles: Principle[] = [];
+  const sections = new Set<string>();
+
+  let currentSection = "";
+  const lines = content.split("\n");
+
+  for (const line of lines) {
+    // Track current section
+    if (line.startsWith("## ")) {
+      currentSection = line.replace("## ", "").trim();
+      sections.add(currentSection);
+    } else if (line.startsWith("### ")) {
+      currentSection = line.replace("### ", "").trim();
+      sections.add(currentSection);
+    }
+
+    // Extract MUST principles
+    const mustMatch = line.match(/\*\*MUST\*\*\s+(.+)/);
+    if (mustMatch) {
+      principles.push({
+        level: "MUST",
+        text: mustMatch[1].trim(),
+        section: currentSection,
+      });
+    }
+
+    // Extract SHOULD principles
+    const shouldMatch = line.match(/\*\*SHOULD\*\*\s+(.+)/);
+    if (shouldMatch) {
+      principles.push({
+        level: "SHOULD",
+        text: shouldMatch[1].trim(),
+        section: currentSection,
+      });
+    }
+  }
+
+  return {
+    raw: content,
+    principles,
+    sections: Array.from(sections),
+  };
+}
+
+/**
+ * Load constitution from file
+ */
+export async function loadConstitution(constitutionPath?: string): Promise<Constitution | null> {
+  const path = constitutionPath ?? findConstitutionFile();
+
+  if (!path || !existsSync(path)) {
+    return null;
+  }
+
+  try {
+    const content = await Bun.file(path).text();
+    return parseConstitution(content);
+  } catch (error) {
+    console.warn(`Failed to load constitution: ${error}`);
+    return null;
+  }
+}
+
+/**
+ * Validate constitution format
+ */
+export function validateConstitution(constitution: Constitution): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  // Check that we have at least some principles
+  if (constitution.principles.length === 0) {
+    errors.push("Constitution has no MUST or SHOULD principles defined");
+  }
+
+  // Check that we have both MUST and SHOULD principles
+  const hasMust = constitution.principles.some(p => p.level === "MUST");
+  const hasShould = constitution.principles.some(p => p.level === "SHOULD");
+
+  if (!hasMust) {
+    errors.push("Constitution has no MUST principles (required directives)");
+  }
+
+  if (!hasShould) {
+    errors.push("Constitution has no SHOULD principles (recommended guidelines)");
+  }
+
+  // Check for empty principle text
+  for (const principle of constitution.principles) {
+    if (!principle.text || principle.text.trim().length === 0) {
+      errors.push(`Empty ${principle.level} principle in section: ${principle.section}`);
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}

package/src/config/schema.ts

@@ -0,0 +1,115 @@
+/**
+ * Relentless Configuration Schema
+ *
+ * Defines the structure and validation for relentless.config.json
+ */
+
+import { z } from "zod";
+// Agent and story types defined inline in Zod schemas below
+
+/**
+ * Agent-specific configuration
+ */
+export const AgentConfigSchema = z.object({
+  model: z.string().optional(),
+  dangerouslyAllowAll: z.boolean().default(true),
+});
+
+export type AgentConfig = z.infer<typeof AgentConfigSchema>;
+
+/**
+ * Routing rule for smart agent selection
+ */
+export const RoutingRuleSchema = z.object({
+  storyType: z.enum(["database", "ui", "api", "test", "refactor", "docs", "general"]),
+  agent: z.enum(["claude", "amp", "opencode", "codex", "droid", "gemini"]),
+});
+
+export type RoutingRule = z.infer<typeof RoutingRuleSchema>;
+
+/**
+ * Fallback configuration for automatic agent switching
+ */
+export const FallbackConfigSchema = z.object({
+  /** Enable automatic fallback when rate limited */
+  enabled: z.boolean().default(true),
+  /** Priority order for agents (first = preferred) */
+  priority: z.array(z.enum(["claude", "amp", "opencode", "codex", "droid", "gemini"]))
+    .default(["claude", "codex", "amp", "opencode", "gemini"]),
+  /** Automatically switch back when limits reset */
+  autoRecovery: z.boolean().default(true),
+  /** Delay (ms) before trying fallback agent */
+  retryDelay: z.number().int().nonnegative().default(2000),
+});
+
+export type FallbackConfig = z.infer<typeof FallbackConfigSchema>;
+
+/**
+ * Execution configuration
+ */
+export const ExecutionConfigSchema = z.object({
+  maxIterations: z.number().int().positive().default(20),
+  iterationDelay: z.number().int().nonnegative().default(2000),
+  timeout: z.number().int().positive().default(600000), // 10 minutes
+});
+
+export type ExecutionConfig = z.infer<typeof ExecutionConfigSchema>;
+
+/**
+ * Routing configuration
+ */
+export const RoutingConfigSchema = z.object({
+  rules: z.array(RoutingRuleSchema).default([]),
+  default: z.enum(["claude", "amp", "opencode", "codex", "droid", "gemini"]).default("claude"),
+});
+
+export type RoutingConfig = z.infer<typeof RoutingConfigSchema>;
+
+/**
+ * Complete Relentless configuration
+ */
+export const RelentlessConfigSchema = z.object({
+  defaultAgent: z.enum(["claude", "amp", "opencode", "codex", "droid", "gemini"]).default("claude"),
+  agents: z.record(
+    z.enum(["claude", "amp", "opencode", "codex", "droid", "gemini"]),
+    AgentConfigSchema
+  ).default({}),
+  routing: RoutingConfigSchema.default({}),
+  fallback: FallbackConfigSchema.default({}),
+  execution: ExecutionConfigSchema.default({}),
+  prompt: z.object({
+    path: z.string().default("prompt.md"),
+  }).default({}),
+});
+
+export type RelentlessConfig = z.infer<typeof RelentlessConfigSchema>;
+
+/**
+ * Default configuration
+ */
+export const DEFAULT_CONFIG: RelentlessConfig = {
+  defaultAgent: "claude",
+  agents: {
+    claude: { dangerouslyAllowAll: true },
+    amp: { dangerouslyAllowAll: true },
+    gemini: { dangerouslyAllowAll: true },
+  },
+  routing: {
+    rules: [],
+    default: "claude",
+  },
+  fallback: {
+    enabled: true,
+    priority: ["claude", "codex", "amp", "opencode", "gemini"],
+    autoRecovery: true,
+    retryDelay: 2000,
+  },
+  execution: {
+    maxIterations: 20,
+    iterationDelay: 2000,
+    timeout: 600000,
+  },
+  prompt: {
+    path: "prompt.md",
+  },
+};

package/src/execution/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Execution Module
+ *
+ * Re-exports execution-related functions
+ */
+
+export * from "./runner";
+export * from "./router";

package/src/execution/router.ts

@@ -0,0 +1,49 @@
+/**
+ * Smart Agent Router
+ *
+ * Routes stories to the best-suited agent based on story type
+ */
+
+import type { AgentName, StoryType } from "../agents/types";
+import { AGENT_SPECIALIZATIONS } from "../agents/types";
+import type { RoutingConfig } from "../config/schema";
+import { inferStoryType, type UserStory } from "../prd/types";
+
+/**
+ * Route a story to the best agent
+ */
+export function routeStory(story: UserStory, routing: RoutingConfig): AgentName {
+  const storyType = inferStoryType(story) as StoryType;
+
+  // Check explicit routing rules first
+  const rule = routing.rules.find((r) => r.storyType === storyType);
+  if (rule) {
+    return rule.agent;
+  }
+
+  // Find best agent based on specializations
+  const scores = Object.entries(AGENT_SPECIALIZATIONS).map(([agent, specializations]) => {
+    const score = specializations.includes(storyType) ? 2 : 0;
+    const generalScore = specializations.includes("general") ? 1 : 0;
+    return { agent: agent as AgentName, score: score + generalScore };
+  });
+
+  // Sort by score descending
+  scores.sort((a, b) => b.score - a.score);
+
+  // If no good match, use default
+  if (scores[0].score === 0) {
+    return routing.default;
+  }
+
+  return scores[0].agent;
+}
+
+/**
+ * Get recommended agent for a story type
+ */
+export function getRecommendedAgent(storyType: StoryType): AgentName[] {
+  return Object.entries(AGENT_SPECIALIZATIONS)
+    .filter(([, specializations]) => specializations.includes(storyType))
+    .map(([agent]) => agent as AgentName);
+}