Skip to content

Latest commit

 

History

History
172 lines (148 loc) · 9.26 KB

CLAUDE.md

File metadata and controls

172 lines (148 loc) · 9.26 KB

Claude Code Instructions for SCTY-OS Ops Dashboard

Project Context

SCTY-OS is an Agent-Driven Dynamic Operations Dashboard built with CopilotKit + Agno. This system helps founders and operators analyze their operational flywheel (Experiments → Products → Clients → Market), identify bottlenecks, and optimize business performance through AI-powered insights and actionable recommendations.

Development Philosophy

  • Operations-first design: Built specifically for operational flywheel analysis and optimization
  • AI-driven insights: Intelligent bottleneck detection and recommendation generation
  • Interactive dashboard: Real-time visualization of system state and metrics
  • Actionable intelligence: Concrete, prioritized recommendations for operational improvements
  • State-driven analysis: YAML/JSON input for flexible operational data modeling

Key Architecture Components

  • Next.js App Router: File-based routing with app directory structure
  • CopilotKit Integration: React components and runtime for AI agent communication
  • Agno Agent Framework: Python-based ops analysis agent with operational tools
  • Operations Agent: Specialized agent for flywheel analysis, bottleneck detection, and action generation
  • Three-Panel Dashboard: Actions Panel, System Visualization, and AI Chat Interface
  • uv Python Environment: Python dependency management with uv for faster installs
  • Concurrent Servers: UI (port 3000) and agent (port 8000) with proper coordination

Important Files & Structure

src/
├── app/
│   ├── api/
│   │   └── copilotkit/      # CopilotKit API integration
│   │       └── route.ts     # API route for agent communication
│   ├── globals.css          # Global Tailwind styles with flywheel animations
│   ├── layout.tsx           # Root layout with CopilotKit providers
│   └── page.tsx             # Main ops dashboard with three-panel layout
├── components/
│   ├── dashboard/           # Dashboard-specific components
│   │   ├── ActionsPanel.tsx # Actions and recommendations panel
│   │   ├── FlywheelVisualization.tsx # Modern flywheel visualization component
│   │   └── SystemVisualization.tsx # Legacy visualization (deprecated)
│   └── tool.tsx             # Custom tool components
agent/
├── agent.py                 # Ops analysis agent with operational tools
├── requirements.txt         # Python dependencies
└── README.md                # Agent documentation and architecture
example-state.yaml           # Example operational state data
package.json                 # Node.js dependencies and scripts
.env.local                   # OpenAI API key configuration

Code Standards & Patterns

  • Prefer editing existing files over creating new ones
  • Follow CopilotKit patterns for agent integration and UI components
  • Use TypeScript for all frontend components with proper prop typing
  • Operations data modeling: Use Pydantic models for structured operational state
  • Standard Python deps: Use pip install for Python dependency management
  • No comments unless explicitly requested by user
  • Dashboard consistency: Maintain three-panel layout and operational color schemes
  • SSR-safe components: Use dynamic imports for client-only components to prevent hydration errors
  • Responsive design: Ensure all components work across different screen sizes

Development Guidelines

  • Agent integration: Use CopilotKit hooks and components for operational data updates
  • Tool development: Follow Agno patterns for operational analysis and recommendation tools
  • State management: Handle YAML/JSON operational state parsing and validation
  • Dashboard design: Maintain Actions Panel, FlywheelVisualization, and Chat interface consistency
  • Server coordination: Ensure both UI and agent servers start properly with concurrent command
  • Error handling: Implement proper error boundaries for agent connection and data parsing issues
  • Hydration prevention: Use dynamic imports for CopilotKit components to avoid SSR mismatches
  • Performance: Optimize visualization rendering with React.memo and useCallback

Development Workflow

  1. Start concurrent servers using pnpm dev for both UI and agent (troubleshooting may be needed)
  2. Develop operational tools in agent/agent.py following Agno patterns
  3. Create dashboard components in src/components/dashboard/ using CopilotKit integration
  4. Test agent communication through the operational analysis chat interface
  5. Verify functionality with example operational state data (example-state.yaml)

Current Technical Context

  • Agent Framework: Agno with OpenAI GPT-4o model integration
  • Operations Tools: Custom operational analysis tools for flywheel optimization
  • UI Framework: Next.js 15 with React 19 and TypeScript
  • Dashboard Components: Three-panel layout with Actions, FlywheelVisualization, and Chat
  • State Format: YAML/JSON for operational data input and analysis
  • Python Environment: Standard pip-managed dependencies
  • Development Environment: Concurrent servers (UI:3000, Agent:8000) with proper coordination
  • Visualization: Modern circular flywheel layout with animations and health indicators
  • Error Prevention: SSR-safe dynamic imports and proper React error boundaries

Key Patterns Established

  • CopilotKit integration handles operational data updates and agent communication
  • Ops agent pattern with specialized operational analysis tools and instructions
  • Three-panel dashboard for Actions, System Visualization, and Agent Chat
  • State-driven analysis using YAML/JSON operational data modeling
  • Server coordination pattern requiring careful startup sequencing

Common Commands

# Run both UI and agent servers concurrently (may require troubleshooting)
pnpm dev

# Run with debug logging
pnpm dev:debug

# Install Python agent dependencies
pnpm install:agent

# Run only the UI server
pnpm dev:ui

# Run only the agent server
pnpm dev:agent

# Build for production
pnpm build

# Lint codebase
pnpm lint

Current Focus

Operational flywheel optimization - helping founders and operators systematically analyze and improve their business operations. The system focuses on identifying bottlenecks in the Experiments → Products → Clients → Market flow and generating actionable recommendations for performance improvement.

Agent & Component Development

When creating new operational tools:

  • Follow Agno framework patterns for tool definition
  • Use descriptive names that reflect operational analysis capabilities
  • Include proper error handling for state parsing and analysis
  • Test tools with example operational data (example-state.yaml)
  • Consider extensibility for different operational models

When creating dashboard components:

  • Use CopilotKit hooks for real-time operational data updates
  • Maintain three-panel layout consistency (Actions, FlywheelVisualization, Chat)
  • Include responsive design for different screen sizes with proper breakpoints
  • Design components specifically for operational flywheel data visualization
  • Follow established patterns for action display and system visualization
  • Use FlywheelVisualization component for operational flow display
  • Implement proper TypeScript interfaces for all props and state
  • Add hover effects and animations for better user experience
  • Include loading states and error boundaries for robust UX

Operational Analysis Patterns

Core Analysis Categories:

  • Bottleneck Detection: Identify low conversion rates and stalled flows
  • Growth Opportunities: Find areas for expansion and optimization
  • Action Generation: Create specific, prioritized recommendations
  • Health Monitoring: Track system-wide operational health metrics
  • State Validation: Parse and validate operational data inputs
  • Visualization Support: Generate structured data for FlywheelVisualization component with proper node positioning and edge styling

Operational Model Extensions:

  • Different flywheel structures: Adapt to various business operational models
  • Custom metrics: Support industry-specific operational indicators
  • Integration hooks: Connect with external operational data sources
  • Action automation: Execute approved operational changes automatically
  • Real-time optimization: Continuous operational monitoring and improvement

Development Troubleshooting

Common Server Coordination Issues:

  • UI and agent servers may not start simultaneously
  • Port conflicts between UI (3000) and agent (8000)
  • Python environment issues with dependency management
  • CopilotKit connection problems requiring server restart sequence

Dashboard Rendering Issues:

  • React hydration errors from CopilotKit SSR mismatches (use dynamic imports)
  • Empty visualization panels when agent communication fails
  • TypeScript errors from improper interface definitions
  • Animation/CSS issues requiring proper Tailwind configuration

Agent Communication Problems:

  • Dashboard not updating after YAML input (check message parsing logic)
  • Duplicate action registration errors (consolidate CopilotKit actions)
  • Message format issues between agent and frontend
  • Browser console errors preventing proper data flow