proagents 1.0.0

package/proagents/examples/web-frontend-react/README.md

@@ -0,0 +1,125 @@
+# Web Frontend React Example
+
+Complete walkthrough of ProAgents workflow for a React web application.
+
+---
+
+## Overview
+
+This example demonstrates how to use ProAgents to build features in a React single-page application. It covers the full development lifecycle from requirements to deployment.
+
+---
+
+## Project Type
+
+- **Framework:** React 18+
+- **Language:** TypeScript
+- **Styling:** Tailwind CSS
+- **State Management:** Zustand
+- **Testing:** Vitest + React Testing Library
+
+---
+
+## Files in This Example
+
+| File | Description |
+|------|-------------|
+| [workflow-example.md](./workflow-example.md) | Step-by-step workflow phases |
+| [complete-conversation.md](./complete-conversation.md) | Full AI conversation example |
+| [proagents.config.yaml](./proagents.config.yaml) | Project-specific configuration |
+
+---
+
+## What You'll Learn
+
+### 1. Project Analysis
+- How ProAgents analyzes React component structure
+- Pattern recognition for hooks, context, and state
+- Identifying existing UI component libraries
+
+### 2. UI Design Integration
+- Converting Figma designs to React components
+- Design token extraction and application
+- Component specification from wireframes
+
+### 3. Implementation
+- Following existing project conventions
+- Creating reusable components
+- State management patterns
+- TypeScript type safety
+
+### 4. Testing
+- Unit tests for components and hooks
+- Integration tests for user flows
+- Accessibility testing
+
+---
+
+## Quick Start
+
+```bash
+# Copy configuration to your React project
+cp proagents.config.yaml /path/to/your/react-project/
+
+# Start a new feature
+proagents feature start "Add user profile page"
+```
+
+---
+
+## Example Feature: User Dashboard
+
+The complete-conversation.md shows building a user dashboard with:
+- Dashboard layout component
+- Stats widgets
+- Recent activity feed
+- User preferences panel
+
+---
+
+## Key Patterns Demonstrated
+
+### Component Structure
+```
+src/
+├── components/
+│   ├── ui/           # Reusable UI components
+│   ├── features/     # Feature-specific components
+│   └── layouts/      # Page layouts
+├── hooks/            # Custom hooks
+├── stores/           # Zustand stores
+└── types/            # TypeScript types
+```
+
+### Testing Approach
+- Component tests with React Testing Library
+- Hook tests with renderHook
+- Integration tests for user journeys
+- 80% coverage target
+
+---
+
+## Configuration Highlights
+
+```yaml
+# From proagents.config.yaml
+project:
+  type: "web-frontend"
+  framework: "react"
+
+testing:
+  framework: "vitest"
+  coverage_threshold: 80
+
+checkpoints:
+  after_design: true      # Review UI before coding
+  before_deployment: true # Final review
+```
+
+---
+
+## Related Resources
+
+- [React Scaffolding Template](../../scaffolding/react/)
+- [UI Design Integration](../../ui-integration/)
+- [Testing Standards](../../testing-standards/)

package/proagents/examples/web-frontend-react/complete-conversation.md

@@ -0,0 +1,556 @@
+# Complete Conversation Example: React Feature
+
+An example of the actual AI-user conversation when building a feature.
+
+---
+
+## Starting Point
+
+**User has:** Existing React + TypeScript project with React Query and Tailwind.
+
+**Goal:** Add a notifications system with real-time updates.
+
+---
+
+## The Conversation
+
+### User Initiates
+
+```
+User: I need to add a notifications feature to my app. Users should see
+their notifications in a dropdown, mark them as read, and get real-time
+updates when new notifications arrive.
+```
+
+### AI Response: Initialization
+
+```
+AI: I'll help you build a notifications feature. Let me start by analyzing
+your codebase to understand the existing patterns.
+
+Creating feature branch: feature/notifications
+
+[Running Analysis...]
+
+──────────────────────────────────────────────────────────
+Codebase Analysis Complete
+──────────────────────────────────────────────────────────
+
+Tech Stack Detected:
+• React 18.2 + TypeScript 5.0
+• React Query 4.x (TanStack Query)
+• React Router 6.x
+• Tailwind CSS 3.x
+• Socket.io-client (for real-time)
+
+Existing Patterns Found:
+• Feature-based folder structure (src/features/*)
+• Custom hooks pattern (useAuth, useApi)
+• Centralized API client (src/services/apiClient.ts)
+• Toast notifications for feedback (using react-hot-toast)
+
+Relevant Existing Code:
+• WebSocket setup: src/services/socket.ts
+• User type: src/types/User.ts
+• Auth context: src/features/auth/AuthContext.tsx
+• Dropdown component: src/components/common/Dropdown.tsx
+
+Do you want me to proceed with requirements gathering, or would you like
+to modify any checkpoints for this feature?
+```
+
+### User Confirms
+
+```
+User: Looks good. Let's proceed.
+```
+
+### AI: Requirements Phase
+
+```
+AI: Based on your request, here are the requirements I've captured:
+
+──────────────────────────────────────────────────────────
+Feature Requirements: Notifications System
+──────────────────────────────────────────────────────────
+
+User Stories:
+1. As a user, I want to see a notification bell with unread count
+2. As a user, I want to view my notifications in a dropdown
+3. As a user, I want to mark notifications as read
+4. As a user, I want to receive real-time notification updates
+5. As a user, I want to click a notification to navigate to related content
+
+Functional Requirements:
+┌─────────────────────────────────────────────────────────┐
+│ • Display notification bell icon in header              │
+│ • Show unread notification count badge                  │
+│ • Dropdown list with notification items                 │
+│ • Mark single notification as read                      │
+│ • Mark all notifications as read                        │
+│ • Real-time updates via WebSocket                       │
+│ • Link notifications to related resources               │
+│ • Notification types: info, success, warning, error     │
+│ • Maximum 50 notifications in dropdown (paginated)      │
+└─────────────────────────────────────────────────────────┘
+
+Technical Requirements:
+• Use existing WebSocket infrastructure (socket.ts)
+• Follow React Query patterns for data fetching
+• Use existing Dropdown component as base
+• Add notification event types to socket listeners
+
+API Endpoints Needed:
+• GET  /api/notifications         - List notifications
+• POST /api/notifications/:id/read - Mark as read
+• POST /api/notifications/read-all - Mark all as read
+
+I have a few clarifying questions:
+
+1. Should notifications persist after being read, or be removed?
+   [ ] Keep for 30 days  [ ] Remove after reading  [ ] User preference
+
+2. What notification types are needed?
+   [ ] Comments  [ ] Mentions  [ ] Task updates  [ ] System alerts
+
+3. Should there be a "View all" page, or just the dropdown?
+   [ ] Dropdown only  [ ] Dropdown + Full page
+```
+
+### User Answers
+
+```
+User:
+1. Keep for 30 days
+2. All of those types
+3. Dropdown + Full page for viewing history
+```
+
+### AI: UI Design Phase
+
+```
+AI: Let me create the UI specification based on your existing design patterns.
+
+──────────────────────────────────────────────────────────
+UI Design Specification
+──────────────────────────────────────────────────────────
+
+1. Notification Bell (Header)
+┌─────────────────────────────────────────────────────────┐
+│  Before existing user menu:                             │
+│                                                         │
+│     🔔                                                  │
+│    (3)  ← Red badge showing unread count               │
+│                                                         │
+│  States:                                                │
+│  • No notifications: bell outline, no badge             │
+│  • Has unread: bell filled, red badge with count       │
+│  • Badge max: "9+" for counts > 9                      │
+└─────────────────────────────────────────────────────────┘
+
+2. Notification Dropdown
+┌─────────────────────────────────────────────────────────┐
+│ Notifications                    Mark all read ──────── │
+├─────────────────────────────────────────────────────────┤
+│ ┌─────────────────────────────────────────────────────┐ │
+│ │ 💬 John commented on your task          2 min ago │ │
+│ │    "Looks great! Let me review..."                  │ │
+│ └─────────────────────────────────────────────────────┘ │
+│ ┌─────────────────────────────────────────────────────┐ │
+│ │ 📋 Task "Deploy API" was completed      1 hour ago │ │
+│ │    Marked complete by Sarah                         │ │
+│ └─────────────────────────────────────────────────────┘ │
+│ ┌─────────────────────────────────────────────────────┐ │
+│ │ @  You were mentioned in #general       3 hours ago│ │
+│ │    @you check out this feature...                   │ │
+│ └─────────────────────────────────────────────────────┘ │
+├─────────────────────────────────────────────────────────┤
+│               View all notifications →                  │
+└─────────────────────────────────────────────────────────┘
+
+Visual States:
+• Unread: bg-blue-50, left blue border
+• Read: bg-white, no border
+• Hover: bg-gray-50
+
+3. Full Notifications Page
+┌─────────────────────────────────────────────────────────┐
+│ Notifications                                           │
+│                                                         │
+│ Filter: [All ▼] [Unread only □]        Mark all read   │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│ Today                                                   │
+│ ───────────────────────────────────────                │
+│ • Notification item 1                                  │
+│ • Notification item 2                                  │
+│                                                         │
+│ Yesterday                                               │
+│ ───────────────────────────────────────                │
+│ • Notification item 3                                  │
+│                                                         │
+│ Older                                                   │
+│ ───────────────────────────────────────                │
+│ • Notification item 4                                  │
+│                                                         │
+│ [Load more]                                            │
+└─────────────────────────────────────────────────────────┘
+
+Does this match your vision? Any changes needed before I plan the
+implementation?
+```
+
+### User Approves
+
+```
+User: Perfect, that's exactly what I want. Proceed with implementation.
+```
+
+### AI: Implementation Planning
+
+```
+AI: Here's the implementation plan:
+
+──────────────────────────────────────────────────────────
+Implementation Plan
+──────────────────────────────────────────────────────────
+
+Files to Create:
+src/features/notifications/
+├── index.ts                      # Public exports
+├── types.ts                      # Notification types
+├── components/
+│   ├── NotificationBell.tsx      # Bell icon with badge
+│   ├── NotificationDropdown.tsx  # Dropdown container
+│   ├── NotificationItem.tsx      # Single notification
+│   ├── NotificationList.tsx      # List of notifications
+│   └── NotificationFilters.tsx   # Filter controls
+├── hooks/
+│   ├── useNotifications.ts       # Fetch notifications
+│   ├── useMarkAsRead.ts          # Mark read mutation
+│   ├── useNotificationSocket.ts  # Real-time listener
+│   └── useUnreadCount.ts         # Unread count
+├── pages/
+│   └── NotificationsPage.tsx     # Full page view
+└── services/
+    └── notificationsApi.ts       # API functions
+
+Files to Modify:
+• src/components/layout/Header.tsx  # Add bell icon
+• src/services/socket.ts            # Add notification events
+• src/App.tsx                       # Add notifications route
+• src/types/index.ts                # Export notification types
+
+Implementation Order:
+1. types.ts - Define notification interfaces
+2. notificationsApi.ts - API functions
+3. socket.ts - Add event listeners
+4. useNotifications.ts, useMarkAsRead.ts - Data hooks
+5. useNotificationSocket.ts - Real-time hook
+6. NotificationItem.tsx - Individual notification
+7. NotificationList.tsx - List component
+8. NotificationDropdown.tsx - Dropdown with list
+9. NotificationBell.tsx - Bell with badge
+10. Header.tsx - Integrate bell
+11. NotificationFilters.tsx - Filter controls
+12. NotificationsPage.tsx - Full page
+13. App.tsx - Add route
+14. Tests
+
+Estimated complexity: Medium
+Files affected: 14 new, 4 modified
+
+Starting implementation now...
+```
+
+### AI: Implementation (Abbreviated)
+
+```
+AI: Creating the notification system...
+
+✓ Created types.ts
+──────────────────────────────────────────────────────────
+// src/features/notifications/types.ts
+
+export type NotificationType =
+  | 'comment'
+  | 'mention'
+  | 'task_update'
+  | 'system';
+
+export interface Notification {
+  id: string;
+  type: NotificationType;
+  title: string;
+  message: string;
+  read: boolean;
+  createdAt: string;
+  link?: string;
+  actor?: {
+    id: string;
+    name: string;
+    avatarUrl?: string;
+  };
+}
+
+export interface NotificationsResponse {
+  notifications: Notification[];
+  total: number;
+  unreadCount: number;
+}
+──────────────────────────────────────────────────────────
+
+✓ Created notificationsApi.ts
+✓ Updated socket.ts with notification events
+✓ Created useNotifications.ts
+✓ Created useMarkAsRead.ts
+✓ Created useNotificationSocket.ts
+
+Creating components...
+
+✓ Created NotificationItem.tsx
+──────────────────────────────────────────────────────────
+// src/features/notifications/components/NotificationItem.tsx
+
+interface NotificationItemProps {
+  notification: Notification;
+  onMarkAsRead: (id: string) => void;
+}
+
+export const NotificationItem: FC<NotificationItemProps> = ({
+  notification,
+  onMarkAsRead,
+}) => {
+  const navigate = useNavigate();
+
+  const handleClick = () => {
+    if (!notification.read) {
+      onMarkAsRead(notification.id);
+    }
+    if (notification.link) {
+      navigate(notification.link);
+    }
+  };
+
+  const icon = getNotificationIcon(notification.type);
+
+  return (
+    <button
+      onClick={handleClick}
+      className={cn(
+        'w-full text-left p-3 flex gap-3 hover:bg-gray-50 transition',
+        !notification.read && 'bg-blue-50 border-l-2 border-blue-500'
+      )}
+    >
+      <span className="text-lg">{icon}</span>
+      <div className="flex-1 min-w-0">
+        <p className="font-medium text-gray-900 truncate">
+          {notification.title}
+        </p>
+        <p className="text-sm text-gray-600 truncate">
+          {notification.message}
+        </p>
+        <p className="text-xs text-gray-400 mt-1">
+          {formatRelativeTime(notification.createdAt)}
+        </p>
+      </div>
+    </button>
+  );
+};
+──────────────────────────────────────────────────────────
+
+✓ Created NotificationList.tsx
+✓ Created NotificationDropdown.tsx
+✓ Created NotificationBell.tsx
+
+✓ Updated Header.tsx
+──────────────────────────────────────────────────────────
+// Added to header before user menu:
+
+<NotificationBell />
+──────────────────────────────────────────────────────────
+
+✓ Created NotificationsPage.tsx
+✓ Updated App.tsx with route
+
+Implementation complete. Running tests...
+```
+
+### AI: Testing Phase
+
+```
+AI: Running tests for the notifications feature...
+
+──────────────────────────────────────────────────────────
+Test Results
+──────────────────────────────────────────────────────────
+
+Unit Tests:
+✓ NotificationItem renders correctly (32ms)
+✓ NotificationItem shows unread state (28ms)
+✓ NotificationItem calls onMarkAsRead on click (45ms)
+✓ NotificationBell shows badge with count (38ms)
+✓ NotificationBell hides badge when count is 0 (35ms)
+✓ NotificationDropdown shows notifications (52ms)
+✓ NotificationDropdown handles mark all read (48ms)
+✓ useNotifications fetches data correctly (42ms)
+✓ useMarkAsRead invalidates cache on success (55ms)
+
+Integration Tests:
+✓ Full notification flow works end-to-end (234ms)
+✓ Real-time updates appear in dropdown (312ms)
+
+Coverage Report:
+• Statements: 94%
+• Branches: 88%
+• Functions: 92%
+• Lines: 94%
+
+All 11 tests passed.
+```
+
+### AI: Code Review
+
+```
+AI: Running code review...
+
+──────────────────────────────────────────────────────────
+Code Review Results
+──────────────────────────────────────────────────────────
+
+✅ Follows project conventions
+   • Feature-based structure ✓
+   • TypeScript strict mode ✓
+   • React Query patterns ✓
+   • Tailwind styling ✓
+
+✅ No security issues detected
+   • No XSS vulnerabilities
+   • Proper input sanitization
+   • WebSocket events validated
+
+✅ Accessibility
+   • Proper ARIA labels
+   • Keyboard navigation works
+   • Focus management correct
+
+✅ Performance
+   • No unnecessary re-renders
+   • Proper memoization
+   • Efficient socket handling
+
+⚠️ Suggestions (non-blocking):
+   • Consider adding error boundary for dropdown
+   • Could add skeleton loading state
+
+Ready for deployment.
+```
+
+### AI: Final Summary
+
+```
+AI: Feature implementation complete!
+
+──────────────────────────────────────────────────────────
+Notifications Feature Summary
+──────────────────────────────────────────────────────────
+
+Created Files: 14
+├── src/features/notifications/
+│   ├── index.ts
+│   ├── types.ts
+│   ├── components/
+│   │   ├── NotificationBell.tsx
+│   │   ├── NotificationDropdown.tsx
+│   │   ├── NotificationItem.tsx
+│   │   ├── NotificationList.tsx
+│   │   └── NotificationFilters.tsx
+│   ├── hooks/
+│   │   ├── useNotifications.ts
+│   │   ├── useMarkAsRead.ts
+│   │   ├── useNotificationSocket.ts
+│   │   └── useUnreadCount.ts
+│   ├── pages/
+│   │   └── NotificationsPage.tsx
+│   └── services/
+│       └── notificationsApi.ts
+
+Modified Files: 4
+├── src/components/layout/Header.tsx
+├── src/services/socket.ts
+├── src/App.tsx
+└── src/types/index.ts
+
+Test Coverage: 94%
+
+Ready to commit and create PR?
+```
+
+### User Confirms Commit
+
+```
+User: Yes, commit and create the PR.
+```
+
+### AI: Git Operations
+
+```
+AI: Creating commit and pull request...
+
+──────────────────────────────────────────────────────────
+Git Operations
+──────────────────────────────────────────────────────────
+
+$ git add .
+$ git commit -m "feat(notifications): add notifications system
+
+- Add notification bell with unread count badge
+- Add notification dropdown with real-time updates
+- Add mark as read functionality
+- Add full notifications page with filters
+- Integrate WebSocket for real-time notifications
+- Add comprehensive tests (94% coverage)
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
+
+$ git push origin feature/notifications
+
+Pull request created:
+https://github.com/user/app/pull/142
+
+PR Title: feat(notifications): add notifications system
+
+PR Description:
+## Summary
+- Adds notification bell icon in header with unread count
+- Dropdown showing recent notifications
+- Full notifications page with filtering
+- Real-time updates via WebSocket
+- Mark as read functionality
+
+## Test Plan
+- [x] Unit tests (11 passing)
+- [x] Manual testing of dropdown
+- [x] Real-time updates verified
+- [x] Mobile responsive checked
+
+🤖 Generated with Claude Code
+
+──────────────────────────────────────────────────────────
+
+Feature complete! The PR is ready for review.
+```
+
+---
+
+## Key Takeaways
+
+This conversation demonstrated:
+
+1. **Automatic Analysis** - AI analyzed existing patterns before suggesting implementation
+2. **Clarifying Questions** - AI asked specific questions when requirements were ambiguous
+3. **Visual Design** - ASCII wireframes for approval before coding
+4. **Incremental Progress** - User saw progress at each step
+5. **Following Patterns** - Used existing project conventions throughout
+6. **Complete Testing** - Tests written and run automatically
+7. **Clean Commits** - Proper commit message with description