@arvorco/relentless 0.1.0

package/src/tui/components/StoryGrid.tsx

@@ -0,0 +1,86 @@
+/**
+ * StoryGrid Component
+ *
+ * Visual grid showing all stories with status
+ */
+
+import React from "react";
+import { Box, Text } from "ink";
+import { colors, symbols } from "../theme.js";
+import type { Story } from "../types.js";
+
+interface StoryGridProps {
+  stories: Story[];
+  currentStoryId?: string;
+  columns?: number;
+}
+
+export function StoryGrid({
+  stories,
+  currentStoryId,
+  columns = 2,
+}: StoryGridProps): React.ReactElement {
+  // Split stories into columns
+  const rows: Story[][] = [];
+  const storiesPerColumn = Math.ceil(stories.length / columns);
+
+  for (let i = 0; i < storiesPerColumn; i++) {
+    const row: Story[] = [];
+    for (let col = 0; col < columns; col++) {
+      const idx = col * storiesPerColumn + i;
+      if (idx < stories.length) {
+        row.push(stories[idx]);
+      }
+    }
+    rows.push(row);
+  }
+
+  return (
+    <Box flexDirection="column" borderStyle="single" borderColor={colors.dim}>
+      <Box paddingX={1} borderBottom borderColor={colors.dim}>
+        <Text color={colors.dim} bold>
+          Stories
+        </Text>
+      </Box>
+      <Box flexDirection="column" paddingX={1} paddingY={0}>
+        {rows.map((row, rowIdx) => (
+          <Box key={rowIdx} flexDirection="row">
+            {row.map((story, colIdx) => {
+              const isCurrent = story.id === currentStoryId;
+              const symbol = isCurrent
+                ? symbols.inProgress
+                : story.passes
+                  ? symbols.complete
+                  : symbols.pending;
+              const symbolColor = isCurrent
+                ? colors.warning
+                : story.passes
+                  ? colors.success
+                  : colors.dim;
+
+              return (
+                <Box key={colIdx} width="50%">
+                  <Text color={symbolColor}>{symbol} </Text>
+                  <Text
+                    color={story.passes ? colors.success : isCurrent ? colors.warning : undefined}
+                    dimColor={story.passes}
+                  >
+                    {story.id.padEnd(8)}
+                  </Text>
+                  <Text
+                    color={colors.dim}
+                    dimColor={story.passes}
+                    strikethrough={story.passes}
+                    wrap="truncate"
+                  >
+                    {story.title.substring(0, 25)}
+                  </Text>
+                </Box>
+              );
+            })}
+          </Box>
+        ))}
+      </Box>
+    </Box>
+  );
+}

package/src/tui/hooks/useTUI.ts

@@ -0,0 +1,147 @@
+/**
+ * useTUI Hook
+ *
+ * Main state management hook for the TUI
+ */
+
+import { useState, useCallback } from "react";
+import type { TUIState, TUIActions, Story, AgentState } from "../types.js";
+import type { AgentName } from "../../agents/types.js";
+
+interface UseTUIOptions {
+  feature: string;
+  project: string;
+  branchName: string;
+  stories: Story[];
+  maxIterations: number;
+  agents: AgentState[];
+}
+
+interface UseTUIReturn {
+  state: TUIState;
+  actions: TUIActions;
+}
+
+export function useTUI(options: UseTUIOptions): UseTUIReturn {
+  const [state, setState] = useState<TUIState>({
+    feature: options.feature,
+    project: options.project,
+    branchName: options.branchName,
+    stories: options.stories,
+    iteration: 0,
+    maxIterations: options.maxIterations,
+    currentStory: null,
+    currentAgent: null,
+    agents: options.agents,
+    outputLines: [],
+    elapsedSeconds: 0,
+    isRunning: false,
+    isComplete: false,
+    error: undefined,
+  });
+
+  const addOutput = useCallback((line: string) => {
+    setState((prev) => ({
+      ...prev,
+      outputLines: [...prev.outputLines, line],
+    }));
+  }, []);
+
+  const clearOutput = useCallback(() => {
+    setState((prev) => ({
+      ...prev,
+      outputLines: [],
+    }));
+  }, []);
+
+  const setCurrentStory = useCallback((story: Story | null) => {
+    setState((prev) => ({
+      ...prev,
+      currentStory: story,
+    }));
+  }, []);
+
+  const setCurrentAgent = useCallback((agent: AgentState | null) => {
+    setState((prev) => ({
+      ...prev,
+      currentAgent: agent,
+      agents: prev.agents.map((a) => ({
+        ...a,
+        active: agent ? a.name === agent.name : false,
+      })),
+    }));
+  }, []);
+
+  const markAgentLimited = useCallback((name: AgentName, resetTime?: Date) => {
+    setState((prev) => ({
+      ...prev,
+      agents: prev.agents.map((a) =>
+        a.name === name ? { ...a, rateLimited: true, resetTime, active: false } : a
+      ),
+      currentAgent:
+        prev.currentAgent?.name === name
+          ? { ...prev.currentAgent, rateLimited: true, resetTime }
+          : prev.currentAgent,
+    }));
+  }, []);
+
+  const clearAgentLimit = useCallback((name: AgentName) => {
+    setState((prev) => ({
+      ...prev,
+      agents: prev.agents.map((a) =>
+        a.name === name ? { ...a, rateLimited: false, resetTime: undefined } : a
+      ),
+    }));
+  }, []);
+
+  const updateStory = useCallback((id: string, passes: boolean) => {
+    setState((prev) => ({
+      ...prev,
+      stories: prev.stories.map((s) => (s.id === id ? { ...s, passes } : s)),
+    }));
+  }, []);
+
+  const setIteration = useCallback((iteration: number) => {
+    setState((prev) => ({
+      ...prev,
+      iteration,
+    }));
+  }, []);
+
+  const setRunning = useCallback((isRunning: boolean) => {
+    setState((prev) => ({
+      ...prev,
+      isRunning,
+    }));
+  }, []);
+
+  const setComplete = useCallback((isComplete: boolean) => {
+    setState((prev) => ({
+      ...prev,
+      isComplete,
+    }));
+  }, []);
+
+  const setError = useCallback((error: string | undefined) => {
+    setState((prev) => ({
+      ...prev,
+      error,
+    }));
+  }, []);
+
+  const actions: TUIActions = {
+    addOutput,
+    clearOutput,
+    setCurrentStory,
+    setCurrentAgent,
+    markAgentLimited,
+    clearAgentLimit,
+    updateStory,
+    setIteration,
+    setRunning,
+    setComplete,
+    setError,
+  };
+
+  return { state, actions };
+}

package/src/tui/hooks/useTimer.ts

@@ -0,0 +1,51 @@
+/**
+ * useTimer Hook
+ *
+ * Tracks elapsed time for the current operation
+ */
+
+import { useState, useEffect, useCallback, useRef } from "react";
+
+interface UseTimerReturn {
+  seconds: number;
+  start: () => void;
+  stop: () => void;
+  reset: () => void;
+}
+
+export function useTimer(): UseTimerReturn {
+  const [seconds, setSeconds] = useState(0);
+  const [isRunning, setIsRunning] = useState(false);
+  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+
+  useEffect(() => {
+    if (isRunning) {
+      intervalRef.current = setInterval(() => {
+        setSeconds((s) => s + 1);
+      }, 1000);
+    } else if (intervalRef.current) {
+      clearInterval(intervalRef.current);
+      intervalRef.current = null;
+    }
+
+    return () => {
+      if (intervalRef.current) {
+        clearInterval(intervalRef.current);
+      }
+    };
+  }, [isRunning]);
+
+  const start = useCallback(() => {
+    setIsRunning(true);
+  }, []);
+
+  const stop = useCallback(() => {
+    setIsRunning(false);
+  }, []);
+
+  const reset = useCallback(() => {
+    setSeconds(0);
+  }, []);
+
+  return { seconds, start, stop, reset };
+}

package/src/tui/index.tsx

@@ -0,0 +1,17 @@
+/**
+ * TUI Module
+ *
+ * Beautiful terminal interface for Relentless
+ */
+
+export { App } from "./App.js";
+export { Header } from "./components/Header.js";
+export { ProgressBar } from "./components/ProgressBar.js";
+export { CurrentStory } from "./components/CurrentStory.js";
+export { AgentOutput } from "./components/AgentOutput.js";
+export { StoryGrid } from "./components/StoryGrid.js";
+export { AgentStatus } from "./components/AgentStatus.js";
+export { useTUI } from "./hooks/useTUI.js";
+export { useTimer } from "./hooks/useTimer.js";
+export * from "./types.js";
+export * from "./theme.js";

package/src/tui/theme.ts

@@ -0,0 +1,41 @@
+/**
+ * TUI Theme
+ *
+ * Colors, borders, and styling constants
+ */
+
+export const colors = {
+  primary: "cyan",
+  success: "green",
+  warning: "yellow",
+  error: "red",
+  dim: "gray",
+  accent: "magenta",
+} as const;
+
+export const symbols = {
+  complete: "✓",
+  pending: "○",
+  inProgress: "◉",
+  arrow: "→",
+  bullet: "•",
+  lightning: "⚡",
+  rocket: "🚀",
+  party: "🎉",
+  warning: "⚠️",
+  error: "❌",
+  clock: "⏳",
+} as const;
+
+export const borders = {
+  horizontal: "─",
+  vertical: "│",
+  topLeft: "┌",
+  topRight: "┐",
+  bottomLeft: "└",
+  bottomRight: "┘",
+  teeLeft: "├",
+  teeRight: "┤",
+  cross: "┼",
+  doubleLine: "═",
+} as const;

package/src/tui/types.ts

@@ -0,0 +1,77 @@
+/**
+ * TUI Types
+ *
+ * State and props types for the TUI components
+ */
+
+import type { AgentName } from "../agents/types";
+
+export interface Story {
+  id: string;
+  title: string;
+  passes: boolean;
+}
+
+export interface AgentState {
+  name: AgentName;
+  displayName: string;
+  active: boolean;
+  rateLimited: boolean;
+  resetTime?: Date;
+}
+
+export interface TUIState {
+  /** Feature name */
+  feature: string;
+  /** Project name */
+  project: string;
+  /** Branch name */
+  branchName: string;
+  /** All stories */
+  stories: Story[];
+  /** Current iteration */
+  iteration: number;
+  /** Maximum iterations */
+  maxIterations: number;
+  /** Current story being worked on */
+  currentStory: Story | null;
+  /** Current agent */
+  currentAgent: AgentState | null;
+  /** All agents with their states */
+  agents: AgentState[];
+  /** Agent output lines */
+  outputLines: string[];
+  /** Elapsed time in seconds */
+  elapsedSeconds: number;
+  /** Is running */
+  isRunning: boolean;
+  /** Is complete */
+  isComplete: boolean;
+  /** Error message if any */
+  error?: string;
+}
+
+export interface TUIActions {
+  /** Add output line */
+  addOutput: (line: string) => void;
+  /** Clear output */
+  clearOutput: () => void;
+  /** Set current story */
+  setCurrentStory: (story: Story | null) => void;
+  /** Set current agent */
+  setCurrentAgent: (agent: AgentState | null) => void;
+  /** Mark agent as rate limited */
+  markAgentLimited: (name: AgentName, resetTime?: Date) => void;
+  /** Clear agent rate limit */
+  clearAgentLimit: (name: AgentName) => void;
+  /** Update story status */
+  updateStory: (id: string, passes: boolean) => void;
+  /** Set iteration */
+  setIteration: (iteration: number) => void;
+  /** Set running state */
+  setRunning: (running: boolean) => void;
+  /** Set complete */
+  setComplete: (complete: boolean) => void;
+  /** Set error */
+  setError: (error: string | undefined) => void;
+}

package/templates/constitution.md

@@ -0,0 +1,228 @@
+# Project Constitution
+
+## Overview
+
+This document defines the governing principles, patterns, and constraints for this project. All agents and developers MUST follow these guidelines when working on the codebase.
+
+## Core Principles
+
+### Architecture
+
+**MUST** follow these architectural patterns:
+- Follow existing code structure and organization patterns
+- Keep modules focused and single-purpose
+- Use dependency injection where appropriate
+
+**SHOULD** consider these best practices:
+- Prefer composition over inheritance
+- Keep functions small and focused
+- Write self-documenting code
+
+### Code Quality
+
+**MUST** maintain these quality standards:
+- All commits MUST pass typecheck with 0 errors
+- All commits MUST pass lint with 0 warnings
+- All new features MUST include appropriate tests
+- All code MUST be formatted consistently
+
+**SHOULD** strive for:
+- High test coverage (aim for >80%)
+- Clear, descriptive variable and function names
+- Comprehensive error handling
+
+### Version Control
+
+**MUST** follow these Git practices:
+- Write clear, descriptive commit messages
+- Reference user story IDs in commits: `feat: [US-XXX] - Description`
+- Keep commits focused and atomic
+- Do not commit broken code
+
+**SHOULD** maintain:
+- Clean commit history
+- Meaningful branch names
+- Updated documentation with code changes
+
+## Technology Stack
+
+### Language & Runtime
+
+- **TypeScript** - Primary language
+- **Bun** - Runtime environment (not Node.js)
+- **Zod** - Schema validation
+
+### Key Libraries
+
+- Commander - CLI parsing
+- Chalk - Terminal formatting
+- Execa - Process execution
+
+## File Organization
+
+```
+project/
+├── bin/              # CLI entry points
+├── src/              # Source code
+│   ├── agents/       # Agent adapters
+│   ├── config/       # Configuration
+│   ├── execution/    # Orchestration
+│   ├── init/         # Project scaffolding
+│   └── prd/          # PRD handling
+├── templates/        # Template files
+├── skills/           # Agent skills
+└── relentless/       # Relentless workspace
+    ├── config.json
+    ├── prompt.md
+    └── features/
+```
+
+## Coding Standards
+
+### TypeScript
+
+**MUST** follow:
+- Use strict TypeScript mode
+- Avoid `any` type - use `unknown` or proper types
+- Export types alongside implementations
+- Use Zod schemas for runtime validation
+
+**SHOULD** prefer:
+- Interface for public APIs
+- Type for unions and intersections
+- Explicit return types on public functions
+
+### Error Handling
+
+**MUST** implement:
+- Descriptive error messages
+- Proper error types
+- Validation at system boundaries
+- Graceful degradation where appropriate
+
+**SHOULD** include:
+- Context in error messages
+- Recovery suggestions
+- Logging for debugging
+
+### Testing
+
+**MUST** test:
+- Core business logic
+- Edge cases and error conditions
+- Integration points
+- CLI commands
+
+**SHOULD** test:
+- Helper functions
+- Utilities
+- Type guards
+
+## Documentation
+
+**MUST** document:
+- Public APIs and interfaces
+- Complex algorithms or logic
+- Breaking changes in commits
+- Setup and installation steps
+
+**SHOULD** document:
+- Configuration options
+- Architecture decisions
+- Common workflows
+- Troubleshooting steps
+
+## Security
+
+**MUST** ensure:
+- No secrets committed to git
+- Proper input validation
+- Safe file system operations
+- Minimal permissions required
+
+**SHOULD** consider:
+- Rate limiting where appropriate
+- Audit logs for sensitive operations
+- Security updates for dependencies
+
+## Performance
+
+**MUST** maintain:
+- Fast startup time (<1s)
+- Responsive CLI commands
+- Efficient file operations
+- Minimal memory footprint
+
+**SHOULD** optimize:
+- Parallel operations where safe
+- Caching for repeated operations
+- Lazy loading of heavy modules
+
+## Constraints
+
+### Dependencies
+
+**MUST NOT**:
+- Add dependencies without justification
+- Include deprecated packages
+- Use packages with known security issues
+
+**SHOULD**:
+- Prefer built-in solutions over dependencies
+- Keep dependencies minimal and focused
+- Regularly update dependencies
+
+### Backwards Compatibility
+
+**MUST**:
+- Maintain compatibility with existing PRDs
+- Provide migration paths for breaking changes
+- Version configuration formats
+
+**SHOULD**:
+- Deprecate features before removal
+- Provide clear upgrade documentation
+- Support at least 2 major versions
+
+## Agent-Specific Guidelines
+
+### For All Agents
+
+**MUST**:
+- Read progress.txt before starting work
+- Work on ONE story per iteration
+- Update PRD after completing a story
+- Append learnings to progress.txt
+- Run all quality checks before committing
+
+**SHOULD**:
+- Review existing code before modifying
+- Follow established patterns
+- Ask questions when unclear
+- Document non-obvious decisions
+
+### Iteration Workflow
+
+1. Read PRD to find next incomplete story
+2. Read progress.txt for context and patterns
+3. Review relevant existing code
+4. Implement the single story
+5. Run typecheck and lint
+6. Run tests if applicable
+7. Commit with proper message format
+8. Update PRD passes: true
+9. Append to progress.txt
+10. Check if all stories complete
+
+## Review and Updates
+
+This constitution should be:
+- **Reviewed** at project milestones
+- **Updated** when patterns emerge
+- **Referenced** in code reviews
+- **Enforced** in CI/CD pipelines
+
+---
+
+Last Updated: YYYY-MM-DD
+Version: 1.0.0