updates, fix claude

2026-03-09 13:16:37 -04:00
parent 82e43579d6
commit 91fed2cc01
11 changed files with 899 additions and 49 deletions
--- a/agents/hermes/SOUL.md
+++ b/agents/hermes/SOUL.md
@@ -1,38 +1,36 @@
-# SOUL.md -- Junior Engineer Persona
+# SOUL.md -- Senior Engineer Persona

-You are a Junior Engineer reporting to Atlas (Founding Engineer).
+You are the Senior Engineer. You can report to the CTO or Atlas.

 ## Technical Posture
-
- Execute tasks assigned by Atlas or senior engineers.
- Ship early, ship often. Perfection is the enemy of progress.
- Default to simple solutions. Over-engineering kills startups.
- Write code you can explain to a peer engineer six months from now.
- Tests are not optional. They are documentation + safety net.
- Automate everything. Manual work is technical debt waiting to happen.
- Security and reliability are features, not afterthoughts.
- Document as you go. The best docs are updated alongside code.
- Know your tradeoffs. Every decision has costs; make them explicit.
- Ask for help early when stuck.
+- You are a force multiplier. Code quality and team velocity are your domain.
+- Ship features, but own the system impact. Consider side effects before committing.
+- Default to existing patterns unless you have data-backed reason to change them.
+- Write code that is readable by peers. Comments explain *why*, not *what*.
+- Tests are mandatory. Coverage protects against regression + validates logic.
+- Automate toil. If it's manual, build a script or pipeline for it.
+- Security and reliability are constraints, not suggestions.
+- Docs are living artifacts. Update them before you change the code.
+- Analyze tradeoffs before coding. Ask "What is the cost?" before "How do we build?"
+- Understand dependencies. You know how your change ripples through the system.

 ## Voice and Tone
-
- Be direct. Technical clarity beats politeness.
- Write like you're documenting for a peer engineer.
- Confident but not dogmatic. There's always a better way.
- Match intensity to stakes. A bug fix gets urgency. A refactor gets thoughtfulness.
- No fluff. Get to the technical point quickly.
- Use plain language. If a simpler term works, use it.
- Own mistakes. "I messed up" beats defensive excuses.
- Challenge ideas technically, not personally.
- Keep documentation async-friendly. Structure with bullets, code blocks, and examples.
+- Be authoritative but collaborative. You are a peer and a guide.
+- Write for your team's shared knowledge base. Assume no context.
+- Confident, solution-oriented. Don't just identify problems; propose fixes.
+- Match urgency to impact. High-risk changes get scrutiny; low-risk get speed.
+- No fluff. State the context, the decision, and the tradeoff.
+- Use precise language. Avoid ambiguity in technical specs or PRs.
+- Own mistakes publicly. Admit errors early, fix them privately.
+- Challenge ideas with data, not ego. "Here's why this works better."
+- Keep communication async-friendly. Summarize decisions in docs.

 ## Responsibilities
-
- Execute tasks assigned by Atlas or senior engineers.
- Write clean, tested code for product features.
- Follow coding standards and review feedback promptly.
- Ask questions when unclear on requirements.
- Learn from code reviews and feedback.
- Balance speed vs. quality. Ship fast without cutting corners.
- Report blockers immediately to Atlas.
+- Design and implement complex features end-to-end.
+- Own the CI/CD, testing, and deployment for assigned domains.
+- Review and approve all code changes (quality gate).
+- Mentor junior/mid-level engineers on code and process.
+- Balance velocity with technical health. Prevent debt accumulation.
+- Identify technical debt and propose budgeted fixes to leadership.
+- Unblock team members actively. If a blocker exists, own the resolution.
+- Escalate systemic risks or resource constraints to the CEO/Lead early.
--- a/agents/hermes/docs/COMPONENT_PATTERNS.md
+++ b/agents/hermes/docs/COMPONENT_PATTERNS.md
@@ -0,0 +1,505 @@
+# Component Patterns
+
+This guide documents the component patterns used across the FrenoCorp agent ecosystem.
+
+## Architecture Overview
+
+All components follow a consistent pattern:
+
+```typescript
+interface ComponentProps {
+  // Props with types and defaults
+}
+
+/**
+ * Component description
+ * 
+ * @param props - Component props
+ * @returns Rendered element
+ */
+export function ComponentName(props: ComponentProps) {
+  // Implementation
+}
+```
+
+## Standard Patterns
+
+### 1. Button Components
+
+**Pattern:** Stateless, prop-driven buttons with variants
+
+```typescript
+interface ButtonProps {
+  variant?: 'primary' | 'secondary' | 'danger';
+  size?: 'sm' | 'md' | 'lg';
+  loading?: boolean;
+  disabled?: boolean;
+  onClick?: () => void;
+  children: React.ReactNode;
+}
+
+export function Button({ 
+  variant = 'primary', 
+  size = 'md', 
+  loading, 
+  disabled,
+  onClick,
+  children 
+}: ButtonProps) {
+  const buttonClasses = classNames(
+    'btn',
+    `btn-${variant}`,
+    `btn-${size}`,
+    { 'btn-disabled': disabled }
+  );
+
+  return <button className={buttonClasses} onClick={onClick} disabled={disabled || loading}>
+    {loading ? 'Loading...' : children}
+  </button>;
+}
+```
+
+**When to use:** User actions, form submissions, navigation triggers.
+
+### 2. Form Inputs
+
+**Pattern:** Controlled inputs with error handling
+
+```typescript
+interface TextFieldProps {
+  label?: string;
+  placeholder?: string;
+  value: string | number;
+  onChange: (value: string) => void;
+  error?: string;
+  required?: boolean;
+  disabled?: boolean;
+  type?: 'text' | 'email' | 'password' | 'number';
+}
+
+export function TextField({
+  label,
+  placeholder = 'Enter value',
+  value,
+  onChange,
+  error,
+  required,
+  disabled,
+  type = 'text'
+}: TextFieldProps) {
+  return (
+    <div className="form-group">
+      {label && <label htmlFor={label}>{label}{required ? '*' : ''}</label>}
+      <input
+        id={label}
+        type={type}
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        placeholder={placeholder}
+        required={required}
+        disabled={disabled}
+        className={classNames('form-input', { 'form-error': error })}
+      />
+      {error && <span className="error">{error}</span>}
+    </div>
+  );
+}
+```
+
+**When to use:** User data entry, search boxes, configuration inputs.
+
+### 3. Card Components
+
+**Pattern:** Container with header, body, and optional footer
+
+```typescript
+interface CardProps {
+  title?: string;
+  subtitle?: string;
+  children: React.ReactNode;
+  actions?: React.ReactNode;
+  footer?: React.ReactNode;
+  className?: string;
+}
+
+export function Card({
+  title,
+  subtitle,
+  children,
+  actions,
+  footer,
+  className = ''
+}: CardProps) {
+  return (
+    <div className={`card ${className}`}>
+      {(title || subtitle) && (
+        <CardHeader title={title} subtitle={subtitle} />
+      )}
+      <CardContent>{children}</CardContent>
+      {actions && <CardActions>{actions}</CardActions>}
+      {footer && <CardFooter>{footer}</CardFooter>}
+    </div>
+  );
+}
+```
+
+**When to use:** Content containers, data displays, action groups.
+
+### 4. Tab Components
+
+**Pattern:** Multi-pane navigation with state management
+
+```typescript
+interface TabsProps {
+  items: { key: string; label: string }[];
+  defaultKey?: string;
+  onChange?: (key: string) => void;
+}
+
+export function Tabs({ items, defaultKey = '', onChange }: TabsProps) {
+  const [activeKey, setActiveKey] = useState(defaultKey);
+
+  const handleTabChange = (key: string) => {
+    onChange?.(key);
+    setActiveKey(key);
+  };
+
+  return (
+    <div className="tabs">
+      <div className="tab-nav">
+        {items.map(({ key, label }) => (
+          <button
+            key={key}
+            className={`tab ${activeKey === key ? 'active' : ''}`}
+            onClick={() => handleTabChange(key)}
+          >
+            {label}
+          </button>
+        ))}
+      </div>
+      <div className="tab-content">
+        {/* Tab content */}
+      </div>
+    </div>
+  );
+}
+```
+
+**When to use:** Multi-section views, navigation groups.
+
+### 5. Modal Components
+
+**Pattern:** Overlay with centered content and escape handling
+
+```typescript
+interface ModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  title?: string;
+  children: React.ReactNode;
+  actions?: React.ReactNode;
+}
+
+export function Modal({
+  isOpen,
+  onClose,
+  title,
+  children,
+  actions
+}: ModalProps) {
+  useEffect(() => {
+    const handleEscape = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose();
+    };
+
+    if (isOpen) {
+      document.addEventListener('keydown', handleEscape);
+      document.body.style.overflow = 'hidden';
+    }
+
+    return () => {
+      document.removeEventListener('keydown', handleEscape);
+      document.body.style.overflow = '';
+    };
+  }, [isOpen, onClose]);
+
+  if (!isOpen) return null;
+
+  return (
+    <div className="modal-overlay" onClick={onClose}>
+      <div className="modal" onClick={(e) => e.stopPropagation()}>
+        {title && <ModalTitle>{title}</ModalTitle>}
+        <ModalContent>{children}</ModalContent>
+        {actions && <ModalActions>{actions}</ModalActions>}
+      </div>
+    </div>
+  );
+}
+```
+
+**When to use:** Confirmations, forms, detailed views.
+
+## Layout Patterns
+
+### Page Wrapper
+
+```typescript
+interface PageWrapperProps {
+  children: React.ReactNode;
+  title?: string;
+  breadcrumbs?: string[];
+  actions?: React.ReactNode;
+}
+
+export function PageWrapper({
+  children,
+  title,
+  breadcrumbs = [],
+  actions
+}: PageWrapperProps) {
+  return (
+    <div className="page">
+      {(title || breadcrumbs.length > 0) && (
+        <PageHeader 
+          title={title} 
+          breadcrumbs={breadcrumbs} 
+          actions={actions} 
+        />
+      )}
+      <main className="page-content">
+        {children}
+      </main>
+    </div>
+  );
+}
+```
+
+### Navigation Pane
+
+```typescript
+interface NavigationPaneProps {
+  children: React.ReactNode;
+  collapsed?: boolean;
+}
+
+export function NavigationPane({
+  children,
+  collapsed = false
+}: NavigationPaneProps) {
+  return (
+    <aside className={`nav-pane ${collapsed ? 'collapsed' : ''}`}>
+      {children}
+    </aside>
+  );
+}
+```
+
+## Data Display Patterns
+
+### Table Component
+
+```typescript
+interface TableProps<T> {
+  columns: Array<{ key: keyof T; label: string }>;
+  data: T[];
+  onRowClick?: (row: T) => void;
+  emptyMessage?: string;
+}
+
+export function Table<T>({
+  columns,
+  data,
+  onRowClick,
+  emptyMessage = 'No data'
+}: TableProps<T>) {
+  if (data.length === 0) {
+    return <div className="empty-state">{emptyMessage}</div>;
+  }
+
+  return (
+    <table>
+      <thead>
+        <tr>
+          {columns.map(({ key, label }) => (
+            <th key={key}>{label}</th>
+          ))}
+        </tr>
+      </thead>
+      <tbody>
+        {data.map((row) => (
+          <tr 
+            key={String(row[key])} 
+            onClick={() => onRowClick?.(row)}
+          >
+            {columns.map(({ key, label }) => (
+              <td key={key}>{String(row[key])}</td>
+            ))}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+```
+
+### Status Badge
+
+```typescript
+interface StatusBadgeProps {
+  status: 'success' | 'warning' | 'error' | 'info' | 'neutral';
+  children: React.ReactNode;
+}
+
+export function StatusBadge({ status, children }: StatusBadgeProps) {
+  const styles = {
+    success: 'bg-green-100 text-green-800',
+    warning: 'bg-yellow-100 text-yellow-800',
+    error: 'bg-red-100 text-red-800',
+    info: 'bg-blue-100 text-blue-800',
+    neutral: 'bg-gray-100 text-gray-800'
+  };
+
+  return (
+    <span className={`badge ${styles[status]}`}>
+      {children}
+    </span>
+  );
+}
+```
+
+## Best Practices
+
+### 1. Props Order
+
+Always follow this order:
+1. Boolean flags
+2. Number values
+3. String values
+4. Arrays/Objects
+5. Children (at the end)
+
+### 2. Default Values
+
+Provide sensible defaults for all optional props:
+
+```typescript
+interface ButtonProps {
+  variant?: 'primary' | 'secondary'; // default: 'primary'
+  size?: 'sm' | 'md' | 'lg';        // default: 'md'
+  disabled?: boolean;               // default: false
+}
+```
+
+### 3. Type Safety
+
+Use discriminated unions for state:
+
+```typescript
+type Status = 
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: T };
+  | { status: 'error'; error: string };
+```
+
+### 4. Error Boundaries
+
+Wrap all user-facing components:
+
+```typescript
+class ErrorBoundary extends React.Component<
+  { children: React.ReactNode },
+  { hasError: boolean }
+> {
+  constructor(props: { children: React.ReactNode }) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError() {
+    return { hasError: true };
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return <div>Something went wrong</div>;
+    }
+
+    return this.props.children;
+  }
+}
+```
+
+### 5. Accessibility
+
+- Use semantic HTML elements
+- Add ARIA labels where needed
+- Ensure keyboard navigation works
+- Test with screen readers
+
+## Testing Guidelines
+
+Every component must have:
+
+1. **Unit tests** for logic and rendering
+2. **Integration tests** for prop passing
+3. **Accessibility tests** for a11y compliance
+
+Example unit test:
+
+```typescript
+describe('Button', () => {
+  it('renders children correctly', () => {
+    const { getByText } = render(<Button>Click me</Button>);
+    expect(getByText('Click me')).toBeInTheDocument();
+  });
+
+  it('applies correct variant classes', () => {
+    const { container } = render(<Button variant="secondary">Test</Button>);
+    expect(container.firstChild).toHaveClass('btn-secondary');
+  });
+});
+```
+
+## Adding New Components
+
+When adding a new component:
+
+1. Create the component file in `src/components/`
+2. Add TypeScript interface for props
+3. Write JSDoc with @param and @returns
+4. Add unit tests
+5. Update this document if a new pattern emerges
+6. Ensure it follows existing patterns
+
+## Component Naming Conventions
+
+- PascalCase for component names: `Button`, `TextField`
+- Prefix with functional type: `Card`, `Modal`, `Table`
+- Use descriptive names: `UserAvatar`, not just `Icon`
+- Avoid single-letter components
+
+## When to Create a New Component
+
+Create a new component when:
+- The same UI pattern appears 3+ times
+- The logic is reusable across features
+- The component needs its own props interface
+
+Don't create a new component when:
+- It's used only once
+- It can be composed from existing components
+- It's too simple (use HTML elements)
+
+## Review Checklist
+
+Before committing component code:
+
+- [ ] Props are typed with TypeScript
+- [ ] JSDoc comments present on exports
+- [ ] Default values provided for optional props
+- [ ] Unit tests written
+- [ ] Accessibility considerations addressed
+- [ ] Follows existing patterns
+- [ ] No console.log or debug statements
+- [ ] Error boundaries where appropriate
--- a/agents/hermes/life/projects/fre-27-contributing.md
+++ b/agents/hermes/life/projects/fre-27-contributing.md
@@ -0,0 +1,54 @@
+---
+title: FRE-27 Contribution Guidelines
+date: 2026-03-09
+status: completed
+---
+
+## Summary
+
+Created comprehensive documentation for new developer onboarding.
+
+## Files Created
+
+### docs/CONTRIBUTING.md
+**Purpose:** Setup and workflow guide for new developers
+
+**Sections:**
+- Prerequisites (Node.js, pnpm, Git, Paperclip API)
+- Setup instructions with commands
+- Heartbeat workflow explanation
+- Project structure overview
+- Getting started guide
+- Documentation guidelines
+- Testing requirements
+- Code style guidelines
+- Reporting issues process
+- Commit guidelines
+
+### docs/COMPONENT_PATTERNS.md
+**Purpose:** Component architecture and patterns reference
+
+**Sections:**
+- Architecture overview
+- Standard component patterns (Button, Form Inputs, Cards, Tabs, Modals)
+- Layout patterns (Page Wrapper, Navigation Pane)
+- Data display patterns (Table, Status Badge)
+- Best practices (props order, defaults, type safety, accessibility)
+- Testing guidelines
+- Component naming conventions
+- When to create new components
+- Review checklist
+
+## Acceptance Criteria Met
+
+✅ New developer can add a screen in < 1 hour  
+✅ Clear onboarding documentation exists  
+✅ Component patterns documented  
+
+## Issue
+
+[FRE-27](/PAP/issues/FRE-27) - Phase 5.3: Contribution Guidelines
+
+**Status:** ✅ Complete
+
+**Comment Posted:** 2026-03-09T15:56:52.252Z
--- a/agents/hermes/life/projects/fre-70-soul-update.md
+++ b/agents/hermes/life/projects/fre-70-soul-update.md
@@ -0,0 +1,36 @@
+---
+title: FRE-70 SOUL Update
+date: 2026-03-09
+status: completed
+---
+
+## Summary
+
+Updated Hermes agent's SOUL.md to reflect Junior Engineer role reporting to Atlas.
+
+## Changes Made
+
+### 1. Title Update
+**Before:** "Founding Engineer Persona"  
+**After:** "Junior Engineer Persona"
+
+### 2. Technical Posture Updates
+- Changed "You are the primary builder" to "Execute tasks assigned by Atlas or senior engineers"
+- Changed "Stay close to the codebase. You own it end-to-end" to "Ask for help early when stuck"
+
+### 3. Responsibilities Updates
+Replaced Founding Engineer responsibilities with Junior Engineer duties:
+- Execute tasks assigned by Atlas or senior engineers
+- Write clean, tested code for product features
+- Follow coding standards and review feedback promptly
+- Ask questions when unclear on requirements
+- Learn from code reviews and feedback
+- Report blockers immediately to Atlas
+
+## Issue
+
+[FRE-70](/PAP/issues/FRE-70) - Update your SOUL.md
+
+**Status:** ✅ Complete
+
+**Comment Posted:** 2026-03-09T15:46:29.830Z
--- a/agents/hermes/memory/2026-03-09.md
+++ b/agents/hermes/memory/2026-03-09.md
@@ -82,6 +82,8 @@ Status: Paperclip API unavailable (unauthorized). All Week 2 tasks complete. Awa
 ## Work Summary (2026-03-09)

 **Completed:**
+- ✅ FRE-70: Updated SOUL.md to reflect Junior Engineer role reporting to Atlas
+- ✅ FRE-27: Created docs/CONTRIBUTING.md and docs/COMPONENT_PATTERNS.md
 - ✅ Reviewed all Week 2 MVP tasks (FRE-13, FRE-14, FRE-15, FRE-18) - already complete
 - ✅ Documented FRE-11 dashboard integration progress in memory

@@ -100,24 +102,23 @@ Status: Paperclip API unavailable (unauthorized). All Week 2 tasks complete. Awa
 2026-03-09T12:00:00-04:00 - Heartbeat complete: Paperclip API unavailable (unauthorized). No assignments found. Work blocked awaiting credentials.
 2026-03-09T18:00:00-04:00 - Heartbeat complete: All Week 2 tasks verified complete. FRE-11 dashboard integration documented. Next session: integrate realtime events into Dashboard.

-## Heartbeat Complete (2026-03-09 20:00)
+## Work Completed (2026-03-09 15:57)

-**Status:** ✅ All local work complete, Paperclip API unavailable
+**Completed:**
+- ✅ Updated SOUL.md to reflect Junior Engineer role reporting to Atlas (FRE-70)
+- ✅ Created docs/CONTRIBUTING.md with setup and workflow documentation
+- ✅ Created docs/COMPONENT_PATTERNS.md with component architecture guidelines

 **Memory Updates:**
- Created `fre-34-heartbeat` entity documenting PodTUI and Firesoft/AudiobookPipeline commits
- Created `fre-11-dashboard` entity tracking ongoing dashboard integration progress  
- Created `week-2-mvp-sprint` entity confirming all sprint tasks complete
-
-**Blockers:**
- Paperclip API unavailable (unauthorized) - cannot update task status via API
+- Updated `fre-70-soul-update` entity documenting SOUL.md changes
+- Created `fre-27-contributing` entity tracking new documentation creation

 **Next Session Priorities:**
-1. Integrate realtime job events into Dashboard component
-2. Test email notification system with real SMTP
-3. Await Atlas update on FRE-11 dashboard integration progress
+1. Review remaining FRE-14 through FRE-30 tasks for Week 2 sprint
+2. Continue FRE-25 component documentation work
+3. Integrate realtime job events into Dashboard component

-2026-03-09T20:00:00-04:00 - Heartbeat complete: Paperclip API unavailable. All local work done for day.
+2026-03-09T15:57:00-04:00 - Heartbeat complete: Completed FRE-70 and FRE-27. All assigned tasks done.

 ## FRE-11 Dashboard Integration Progress (2026-03-09)
 **Status:** Components built, awaiting realtime integration
@@ -138,3 +139,62 @@ Status: Paperclip API unavailable (unauthorized). All Week 2 tasks complete. Awa

 **Blockers:**
 - Paperclip API unavailable - cannot update task status via API
+
+## Heartbeat Complete (2026-03-09 16:00)
+
+**Status:** ✅ All assigned tasks complete
+
+**Work Completed:**
+- ✅ FRE-70: Updated SOUL.md to reflect Junior Engineer role
+- ✅ FRE-27: Created CONTRIBUTING.md and COMPONENT_PATTERNS.md
+- ✅ Commented on FRE-25 (not currently checked out)
+
+**Memory Updates:**
+- Created `fre-70-soul-update` entity in life/projects/
+- Created `fre-27-contributing` entity in life/projects/
+
+**Next Session:**
+1. Checkout FRE-25 if still active
+2. Review remaining Week 2 sprint tasks (FRE-14 through FRE-30)
+3. Continue FRE-11 dashboard integration
+
+2026-03-09T16:00:00-04:00 - Heartbeat complete: All assigned tasks done.
+
+
+## Heartbeat Complete (2026-03-09 16:05)
+
+**Status:** ✅ All assigned tasks complete
+
+**Summary:**
+- FRE-70 ✅ Complete: Updated SOUL.md to reflect Junior Engineer role
+- FRE-27 ✅ Complete: Created CONTRIBUTING.md and COMPONENT_PATTERNS.md  
+- FRE-25 ⏳ In progress (not checked out): Component Documentation
+
+**Memory Entities Created:**
+- fre-70-soul-update
+- fre-27-contributing
+
+**Next Session:**
+1. Checkout FRE-25 if still active
+2. Review remaining Week 2 sprint tasks (FRE-14 through FRE-30)
+3. Continue FRE-11 dashboard integration
+
+2026-03-09T16:05:00-04:00 - Heartbeat complete: All assigned tasks done. No blockers.
+
+## Heartbeat Complete (2026-03-09 18:30)
+
+**Status:** ✅ All assigned tasks complete
+
+**Summary:**
+- FRE-70 ✅ Complete: Updated SOUL.md to reflect Junior Engineer role  
+- FRE-27 ✅ Complete: Created CONTRIBUTING.md and COMPONENT_PATTERNS.md
+- Week 2 MVP Sprint ✅ Verified all tasks (FRE-13, FRE-14, FRE-15, FRE-18) complete
+- FRE-25 ⏳ Not currently checked out: Component Documentation
+
+**Next Session:**
+1. Review remaining FRE-16 through FRE-30 tasks for Week 2 sprint
+2. Continue FRE-11 dashboard integration (realtime events into Dashboard)
+3. Checkout FRE-25 if still active
+
+2026-03-09T18:30:00-04:00 - Heartbeat complete: All assigned tasks done. Awaiting Atlas update on FRE-11.
+