proagents 1.6.17 → 1.6.19

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

@@ -1,125 +0,0 @@
-# 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

@@ -1,556 +0,0 @@
-# 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