diff --git a/README.md b/README.md index 3484850..92aea5a 100644 --- a/README.md +++ b/README.md @@ -1,113 +1,133 @@ -# Qwen-CLI Sub-Agents +# Next.js AI Agent Development Team -A collection of specialized AI assistants designed to work with Qwen-CLI for various development tasks. Each agent is tailored for specific domains and technologies, providing expert-level guidance and code generation. +Welcome to the AI Agent Development Team repository. This project provides a structured framework for building full-stack Next.js applications using a team of specialized AI agents, led by a master orchestrator named `QWEN`. -## Available Agents +This system is designed to transform a high-level project idea into a complete, production-ready application through a methodical, plan-driven, and interactive process. -### 1. Animation + Motion Assistant -- **File**: `Animation-Assistant.md` -- **Focus**: React/Next.js animations, motion design, and micro-interactions -- **Technologies**: Framer Motion, shadcn/ui, Tailwind CSS, CSS animations -- **Specialties**: - - Advanced animation libraries integration - - Performance optimization for 60fps animations - - Accessibility-focused motion design - - Responsive and adaptive animations +## Meet the Team -### 2. Component Builder Assistant -- **File**: `Component-Builder-Assistant.md` -- **Focus**: Building reusable UI components with best practices -- **Technologies**: React, shadcn/ui, Tailwind CSS, TypeScript -- **Specialties**: - - Component architecture and design patterns - - Reusable component creation - - TypeScript type safety - - Accessibility compliance +The team consists of one orchestrator and several specialist agents, each with a distinct role. -### 3. Dashboard Master -- **File**: `Dashboard-Master.md` -- **Focus**: Data visualization and dashboard development -- **Technologies**: React, Next.js, Chart.js, D3.js, shadcn/ui -- **Specialties**: - - Complex data visualizations - - Dashboard layouts and organization - - Real-time data integration - - Performance optimization for dashboards +| Icon | Agent Name | Role & Responsibilities | +| :--: | ------------------------------- | ------------------------------------------------------------ | +| 🏛️ | **QWEN** | **Project Architect & Orchestrator.** Analyzes requirements, designs the architecture and data schema, and creates a sequential execution plan. It delegates all implementation tasks to the specialists. | +| 🗃️ | **Supabase-Engineer** | **Backend & Database Specialist.** Handles all database schema implementation, authentication, Row Level Security (RLS) policies, and file storage logic using Supabase. | +| 💻 | **Nextjs-Developer** | **Core Frontend Specialist.** Implements frontend logic, state management, and form handling with Server Actions. Connects the UI to the backend services. | +| 🎨 | **Component-Builder-Assistant** | **UI Specialist.** Creates pure, reusable, and logic-less `shadcn/ui` components based on design specifications from the orchestrator. | +| 💳 | **Payment-Integration-Specialist**| **Payments Specialist.** Implements all Stripe payment flows, subscription logic, pricing tables, and secure webhook handling. | +| 📊 | **Dashboard-Master** | **Data Visualization Specialist.** Builds complex data tables, charts, and interactive dashboards using TanStack Table and Recharts. | +| ✨ | **Animation-Assistant** | **Motion Specialist.** Implements UI animations, transitions, and micro-interactions using Framer Motion to enhance the user experience. | +| 📡 | **Nextjs-Realtime-Developer** | **Real-time Specialist.** Implements real-time features using WebSockets or Server-Sent Events (SSE) for chat, notifications, and live updates. | -### 4. Next.js Developer -- **File**: `Nextjs-Developer.md` -- **Focus**: Full Next.js 15 development with modern frontend practices -- **Technologies**: Next.js 15, React, TypeScript, Tailwind CSS, shadcn/ui -- **Specialties**: - - App Router architecture - - Server Components and Client Components - - AI SDK v5 integration - - Modern UI/UX implementation +## The Development Workflow -### 5. Next.js Forms Developer -- **File**: `Nextjs-Forms-Developer.md` -- **Focus**: Form handling and validation in Next.js applications -- **Technologies**: Next.js 15, React Hook Form, Zod, shadcn/ui -- **Specialties**: - - Form validation and error handling - - Complex form architectures - - Dynamic forms and conditional fields - - Integration with backend services +The entire development process is managed by `QWEN` and follows a strict, interactive workflow. This ensures that a solid plan is in place before any code is written. -### 6. Next.js Realtime Developer -- **File**: `Nextjs-Realtime-Developer.md` -- **Focus**: Real-time features and collaborative applications -- **Technologies**: Next.js 15, Supabase Realtime, shadcn/ui, WebSockets -- **Specialties**: - - Real-time data synchronization - - Collaborative features implementation - - Live updates and notifications - - Connection management +### Workflow Diagram -### 7. Payment Integration Specialist -- **File**: `Payment-Integration-Specialist.md` -- **Focus**: Secure payment processing and integration -- **Technologies**: Stripe, PayPal, React, Next.js, TypeScript -- **Specialties**: - - Payment gateway integration - - Security best practices - - Subscription management - - Fraud prevention +```mermaid +graph TD + A[Start: User has Project Idea] --> B{Interact with QWEN}; + B --> C[/plan command]; + C --> D[QWEN asks clarifying questions]; + D --> E[QWEN generates full Execution Plan
(Architecture, Schema, Task List)]; + E --> F{Plan Refinement
(Advanced Elicitation)}; + F -- Revise --> E; + F -- Approve --> G; + G[/start command] --> H[QWEN delegates Task 1
to a Specialist Agent]; + H --> I[Specialist generates output (code, etc.)]; + I --> J{User provides output back to QWEN}; + J --> K{All tasks complete?}; + K -- No --> H_Next[QWEN delegates next Task]; + H_Next --> I; + K -- Yes --> L[End: Project Complete]; -### 8. Supabase Engineer -- **File**: `Supabase-Engineer.md` -- **Focus**: Full-stack development with Supabase ecosystem -- **Technologies**: Supabase (Auth, Database, Realtime, Storage), shadcn/ui, Next.js 15 -- **Specialties**: - - Supabase authentication and authorization - - Real-time features with Supabase - - Database design and RLS policies - - File storage and management + subgraph "Phase 1: Planning" + direction LR + A; B; C; D; + end -## How to Use + subgraph "Phase 2: Refinement" + direction LR + E; F; + end -Each agent is designed to be used with Qwen-CLI. To use a specific agent: + subgraph "Phase 3: Execution" + direction TB + G; H; I; J; K; L; H_Next; + end +```` -1. Navigate to the repository directory -2. Launch Qwen-CLI with the specific agent file: - ```bash - qwen-cli --agent Animation-Assistant.md - ``` -3. Or specify the agent by name: - ```bash - qwen-cli --agent "Animation + Motion Assistant" - ``` +## Usage Guide + +This guide is broken into two parts: first, understanding the conceptual process, and second, the practical commands for implementing it. + +### 1\. The Conceptual Workflow + +The entire project lifecycle is a structured conversation with the `QWEN` orchestrator. + +#### **Phase 1: Planning & Architecture (`/plan`)** + +1. Start a conversation with the `QWEN` agent and provide a high-level project goal. +2. Issue the `/plan` command. +3. `QWEN` enters an interactive loop, asking probing questions to fully understand the requirements and resolve all ambiguities. +4. Once all information is gathered, `QWEN` generates a complete **Execution Plan**, which includes the system architecture, the full database schema, and a sequential list of tasks with detailed prompts for the specialist agents. + +#### **Phase 2: Plan Refinement (Advanced Elicitation)** + +1. After presenting the plan, `QWEN` immediately stops and offers a numbered list of "elicitation" options. +2. This allows you to challenge, critique, and refine the plan from various angles (e.g., "Stress-test the data schema," "Critique the tech stack"). +3. This collaborative loop continues until you are fully satisfied with the blueprint and approve it for execution. + +#### **Phase 3: Execution & Delegation (`/start`)** + +1. Issue the `/start` command to begin development. +2. `QWEN` delegates **Task 1** by providing the exact prompt for the appropriate specialist. +3. Take that prompt to the specified specialist agent (in a new chat session) to get the implementation code. +4. Bring the specialist's output back to `QWEN`. +5. `QWEN` acknowledges completion and delegates the next task in the sequence. This cycle repeats until the project is finished. + +### 2\. Practical Implementation with Qwen-CLI + +The conceptual workflow described above is put into practice using `qwen-cli`. + +1. **Start with the Orchestrator:** To begin the planning phase, launch the orchestrator: + ```bash + qwen-cli --agent QWEN.md + ``` +2. **Follow the Workflow:** Engage with `QWEN` using the `/plan` and `/start` commands as described above. +3. **Delegate to Specialists:** When `QWEN` provides a task prompt for a specialist (e.g., `Supabase-Engineer`), open a **new terminal window** and run the specialist agent: + ```bash + # Example for the Supabase specialist + qwen-cli --agent Supabase-Engineer.md + ``` +4. **Return and Continue:** Paste the task prompt from `QWEN` into the specialist's CLI session. Once you receive the output, copy it and paste it back into the `QWEN` session to proceed to the next task. + +Following this structured process and using separate terminal sessions for each agent will yield the best results. + +## Agent Prompt Files + +This repository contains the master prompts for each agent: + + * `QWEN.md` + * `Component-Builder-Assistant.md` + * `Dashboard-Master.md` + * `Animation-Assistant.md` + * `Nextjs-Developer.md` + * `Nextjs-Realtime-Developer.md` + * `Payment-Integration-Specialist.md` + * `Supabase-Engineer.md` ## Contributing -Contributions are welcome! To add a new agent: +Contributions are welcome\! To add a new agent: -1. Create a new markdown file following the existing pattern -2. Include the YAML frontmatter with `name`, `description`, and `color` -3. Add a detailed description of the agent's responsibilities and specialties -4. Include technology stack focus and implementation rules -5. Submit a pull request +1. Create a new markdown file following the existing pattern. +2. Include the YAML frontmatter with `name`, `description`, and `color`. +3. Add a detailed description of the agent's responsibilities and specialties. +4. Include technology stack focus and implementation rules. +5. Submit a pull request. ## License -This project is licensed under the MIT License - see the LICENSE file for details. +This project is licensed under the MIT License - see the LICENSE file for details. \ No newline at end of file