@poolzin/pool-bot 2026.3.13 → 2026.3.15

package/extensions/agency-agents/README.md

@@ -0,0 +1,301 @@
+# Agency Agents Extension for PoolBot
+
+AI specialist agents for software engineering tasks. Register domain-specific agents (Frontend, Backend, DevOps, etc.) and orchestrate complex multi-agent workflows with collaboration, messaging, and review capabilities.
+
+## Features
+
+- **Specialist Agents**: Pre-configured agents for different engineering domains
+- **Task Management**: Create, assign, and track tasks with dependencies
+- **Multi-Agent Collaboration**: Form teams with lead agents and participants
+- **Workflow Orchestration**: Define step-by-step workflows with dependencies
+- **Agent Messaging**: Inter-agent communication for coordination
+- **Code Review**: Structured review process with approval workflows
+- **System Prompts**: Auto-generated prompts for LLM integration
+
+## Installation
+
+```bash
+# Install as PoolBot extension
+poolbot extension install @poolbot/agency-agents
+
+# Or manual installation
+cd extensions/agency-agents
+pnpm install
+pnpm build
+```
+
+## Configuration
+
+```json
+{
+  "agencyAgents": {
+    "agents": [
+      {
+        "name": "FrontendDev",
+        "description": "Frontend development specialist",
+        "category": "engineering",
+        "color": "#3b82f6",
+        "content": "Expert in React, Vue, and modern CSS...",
+        "capabilities": ["react", "vue", "css", "typescript"],
+        "tools": ["code_editor", "browser", "git"]
+      },
+      {
+        "name": "BackendDev",
+        "description": "Backend development specialist",
+        "category": "engineering",
+        "color": "#10b981",
+        "content": "Expert in Node.js, Python, and databases...",
+        "capabilities": ["nodejs", "python", "postgresql", "redis"],
+        "tools": ["code_editor", "database", "api_tester"]
+      }
+    ]
+  }
+}
+```
+
+## Usage
+
+### Initialize Service
+
+```typescript
+import { AgencyAgentsService } from '@poolbot/agency-agents'
+
+const service = new AgencyAgentsService(config)
+```
+
+### Register Agents
+
+```typescript
+service.registerAgent({
+  name: 'DevOpsEngineer',
+  description: 'DevOps and infrastructure specialist',
+  category: 'engineering',
+  color: '#f59e0b',
+  content: 'Expert in Docker, Kubernetes, and CI/CD...',
+  capabilities: ['docker', 'kubernetes', 'terraform', 'aws'],
+  tools: ['terminal', 'docker', 'kubectl']
+})
+```
+
+### Task Management
+
+```typescript
+// Create a task
+const task = service.createTask(
+  'FrontendDev',
+  'Build login page component',
+  'Create a responsive login form with email and password fields'
+)
+
+// Update task status
+service.updateTaskStatus(task.id, 'in_progress')
+service.updateTaskStatus(task.id, 'completed', 'Login component built successfully')
+
+// Get task details
+const taskDetails = service.getTask(task.id)
+
+// List all tasks
+const allTasks = service.listTasks()
+
+// Filter by agent or status
+const frontendTasks = service.listTasks('FrontendDev')
+const pendingTasks = service.listTasks(undefined, 'pending')
+```
+
+### Agent Collaboration
+
+```typescript
+// Create a collaboration
+const collab = service.createCollaboration(
+  'E-commerce Feature',
+  'Build shopping cart functionality',
+  'FrontendDev',
+  ['BackendDev', 'UXDesigner']
+)
+
+// Add tasks to collaboration
+const task1 = service.createTask('FrontendDev', 'Build cart UI', undefined, collab.id)
+const task2 = service.createTask('BackendDev', 'Build cart API', undefined, collab.id)
+
+// Update collaboration status
+service.updateCollaborationStatus(collab.id, 'active')
+
+// List collaborations
+const activeCollabs = service.listCollaborations('active')
+```
+
+### Agent Messaging
+
+```typescript
+// Send message between agents
+service.sendMessage(
+  'FrontendDev',
+  'BackendDev',
+  collab.id,
+  'What is the API endpoint for adding items to cart?',
+  'request'
+)
+
+// Get messages for collaboration
+const messages = service.getMessagesForCollaboration(collab.id)
+```
+
+### Code Review
+
+```typescript
+// Create a review
+service.createReview(
+  task.id,
+  'SeniorDev',
+  'FrontendDev',
+  'Code looks good but needs error handling',
+  'changes_requested',
+  ['Add try-catch block', 'Validate input parameters']
+)
+
+// Approve review
+service.approveReview(review.id)
+
+// Get reviews for task
+const reviews = service.getReviewsForTask(task.id)
+```
+
+### Workflow Orchestration
+
+```typescript
+// Create a workflow
+const workflow = service.createWorkflow(
+  'Feature Development',
+  'Complete feature development workflow',
+  'engineering'
+)
+
+// Add steps
+const step1 = service.addWorkflowStep(
+  workflow.id,
+  'Design API',
+  'Design the API endpoints',
+  'BackendDev',
+  'Create OpenAPI spec',
+  []
+)
+
+const step2 = service.addWorkflowStep(
+  workflow.id,
+  'Implement API',
+  'Build the backend API',
+  'BackendDev',
+  'Implement endpoints',
+  [step1.id]
+)
+
+// Execute workflow
+await service.executeWorkflow(workflow.id)
+```
+
+### System Prompt Generation
+
+```typescript
+// Generate system prompt for agent
+const prompt = service.generateSystemPrompt('FrontendDev')
+console.log(prompt)
+// Output: "You are FrontendDev, a Frontend development specialist..."
+```
+
+## Data Types
+
+### AgencyAgent
+
+```typescript
+interface AgencyAgent {
+  name: string
+  description: string
+  color?: string
+  category: string
+  content: string
+  capabilities: string[]
+  tools?: string[]
+}
+```
+
+### AgentTask
+
+```typescript
+interface AgentTask {
+  id: string
+  agentName: string
+  task: string
+  context?: string
+  status: 'pending' | 'in_progress' | 'completed' | 'failed' | 'reviewing'
+  output?: string
+  createdAt: Date
+  updatedAt: Date
+  parentTaskId?: string
+  subtasks?: string[]
+  dependencies?: string[]
+}
+```
+
+### AgentCollaboration
+
+```typescript
+interface AgentCollaboration {
+  id: string
+  name: string
+  description: string
+  leadAgent: string
+  participatingAgents: string[]
+  tasks: AgentTask[]
+  status: 'planning' | 'active' | 'completed' | 'paused'
+  createdAt: Date
+  updatedAt: Date
+}
+```
+
+## Testing
+
+```bash
+# Run all tests
+pnpm test
+
+# Watch mode
+pnpm test:watch
+
+# Coverage
+pnpm test:coverage
+```
+
+## API Reference
+
+### AgencyAgentsService
+
+| Method | Description |
+|--------|-------------|
+| `registerAgent(agent)` | Register a new agent |
+| `unregisterAgent(name)` | Remove an agent |
+| `getAgent(name)` | Get agent by name |
+| `listAgents()` | List all registered agents |
+| `findAgentsByCapability(cap)` | Find agents by capability |
+| `matchAgentToTask(task)` | Find best agent for task |
+| `createTask(agent, task, context, parentId)` | Create a task |
+| `getTask(id)` | Get task by ID |
+| `updateTaskStatus(id, status, output)` | Update task status |
+| `listTasks(agent?, status?)` | List tasks with filters |
+| `createCollaboration(name, desc, lead, participants)` | Create collaboration |
+| `getCollaboration(id)` | Get collaboration by ID |
+| `updateCollaborationStatus(id, status)` | Update collaboration status |
+| `listCollaborations(status?)` | List collaborations |
+| `sendMessage(from, to, collabId, content, type)` | Send agent message |
+| `getMessagesForCollaboration(id)` | Get collaboration messages |
+| `createReview(taskId, reviewer, reviewee, feedback, status, suggestions?)` | Create review |
+| `approveReview(id)` | Approve a review |
+| `getReviewsForTask(id)` | Get reviews for task |
+| `createWorkflow(name, desc, category)` | Create workflow |
+| `addWorkflowStep(flowId, name, desc, agent, task, deps)` | Add workflow step |
+| `executeWorkflow(id)` | Execute workflow |
+| `generateSystemPrompt(agentName)` | Generate system prompt |
+| `getStatistics()` | Get service statistics |
+
+## License
+
+MIT

package/extensions/agency-agents/agents/CONTRIBUTING.md

@@ -0,0 +1,353 @@
+# 🤝 Contributing to The Agency
+
+First off, thank you for considering contributing to The Agency! It's people like you who make this collection of AI agents better for everyone.
+
+## 📋 Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [How Can I Contribute?](#how-can-i-contribute)
+- [Agent Design Guidelines](#agent-design-guidelines)
+- [Pull Request Process](#pull-request-process)
+- [Style Guide](#style-guide)
+- [Community](#community)
+
+---
+
+## 📜 Code of Conduct
+
+This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code:
+
+- **Be Respectful**: Treat everyone with respect. Healthy debate is encouraged, but personal attacks are not tolerated.
+- **Be Inclusive**: Welcome and support people of all backgrounds and identities.
+- **Be Collaborative**: What we create together is better than what we create alone.
+- **Be Professional**: Keep discussions focused on improving the agents and the community.
+
+---
+
+## 🎯 How Can I Contribute?
+
+### 1. Create a New Agent
+
+Have an idea for a specialized agent? Great! Here's how to add one:
+
+1. **Fork the repository**
+2. **Choose the appropriate category** (or propose a new one):
+   - `engineering/` - Software development specialists
+   - `design/` - UX/UI and creative specialists
+   - `marketing/` - Growth and marketing specialists
+   - `product/` - Product management specialists
+   - `project-management/` - PM and coordination specialists
+   - `testing/` - QA and testing specialists
+   - `support/` - Operations and support specialists
+   - `spatial-computing/` - AR/VR/XR specialists
+   - `specialized/` - Unique specialists that don't fit elsewhere
+
+3. **Create your agent file** following the template below
+4. **Test your agent** in real scenarios
+5. **Submit a Pull Request** with your agent
+
+### 2. Improve Existing Agents
+
+Found a way to make an agent better? Contributions welcome:
+
+- Add real-world examples and use cases
+- Enhance code samples with modern patterns
+- Update workflows based on new best practices
+- Add success metrics and benchmarks
+- Fix typos, improve clarity, enhance documentation
+
+### 3. Share Success Stories
+
+Used these agents successfully? Share your story:
+
+- Post in [GitHub Discussions](https://github.com/msitarzewski/agency-agents/discussions)
+- Add a case study to the README
+- Write a blog post and link it
+- Create a video tutorial
+
+### 4. Report Issues
+
+Found a problem? Let us know:
+
+- Check if the issue already exists
+- Provide clear reproduction steps
+- Include context about your use case
+- Suggest potential solutions if you have ideas
+
+---
+
+## 🎨 Agent Design Guidelines
+
+### Agent File Structure
+
+Every agent should follow this structure:
+
+```markdown
+---
+name: Agent Name
+description: One-line description of the agent's specialty and focus
+color: colorname or "#hexcode"
+---
+
+# Agent Name
+
+## 🧠 Your Identity & Memory
+- **Role**: Clear role description
+- **Personality**: Personality traits and communication style
+- **Memory**: What the agent remembers and learns
+- **Experience**: Domain expertise and perspective
+
+## 🎯 Your Core Mission
+- Primary responsibility 1 with clear deliverables
+- Primary responsibility 2 with clear deliverables
+- Primary responsibility 3 with clear deliverables
+- **Default requirement**: Always-on best practices
+
+## 🚨 Critical Rules You Must Follow
+Domain-specific rules and constraints that define the agent's approach
+
+## 📋 Your Technical Deliverables
+Concrete examples of what the agent produces:
+- Code samples
+- Templates
+- Frameworks
+- Documents
+
+## 🔄 Your Workflow Process
+Step-by-step process the agent follows:
+1. Phase 1: Discovery and research
+2. Phase 2: Planning and strategy
+3. Phase 3: Execution and implementation
+4. Phase 4: Review and optimization
+
+## 💭 Your Communication Style
+- How the agent communicates
+- Example phrases and patterns
+- Tone and approach
+
+## 🔄 Learning & Memory
+What the agent learns from:
+- Successful patterns
+- Failed approaches
+- User feedback
+- Domain evolution
+
+## 🎯 Your Success Metrics
+Measurable outcomes:
+- Quantitative metrics (with numbers)
+- Qualitative indicators
+- Performance benchmarks
+
+## 🚀 Advanced Capabilities
+Advanced techniques and approaches the agent masters
+```
+
+### Agent Design Principles
+
+1. **🎭 Strong Personality**
+   - Give the agent a distinct voice and character
+   - Not "I am a helpful assistant" - be specific and memorable
+   - Example: "I default to finding 3-5 issues and require visual proof" (Evidence Collector)
+
+2. **📋 Clear Deliverables**
+   - Provide concrete code examples
+   - Include templates and frameworks
+   - Show real outputs, not vague descriptions
+
+3. **✅ Success Metrics**
+   - Include specific, measurable metrics
+   - Example: "Page load times under 3 seconds on 3G"
+   - Example: "10,000+ combined karma across accounts"
+
+4. **🔄 Proven Workflows**
+   - Step-by-step processes
+   - Real-world tested approaches
+   - Not theoretical - battle-tested
+
+5. **💡 Learning Memory**
+   - What patterns the agent recognizes
+   - How it improves over time
+   - What it remembers between sessions
+
+### What Makes a Great Agent?
+
+**Great agents have**:
+- ✅ Narrow, deep specialization
+- ✅ Distinct personality and voice
+- ✅ Concrete code/template examples
+- ✅ Measurable success metrics
+- ✅ Step-by-step workflows
+- ✅ Real-world testing and iteration
+
+**Avoid**:
+- ❌ Generic "helpful assistant" personality
+- ❌ Vague "I will help you with..." descriptions
+- ❌ No code examples or deliverables
+- ❌ Overly broad scope (jack of all trades)
+- ❌ Untested theoretical approaches
+
+---
+
+## 🔄 Pull Request Process
+
+### Before Submitting
+
+1. **Test Your Agent**: Use it in real scenarios, iterate on feedback
+2. **Follow the Template**: Match the structure of existing agents
+3. **Add Examples**: Include at least 2-3 code/template examples
+4. **Define Metrics**: Include specific, measurable success criteria
+5. **Proofread**: Check for typos, formatting issues, clarity
+
+### Submitting Your PR
+
+1. **Fork** the repository
+2. **Create a branch**: `git checkout -b add-agent-name`
+3. **Make your changes**: Add your agent file(s)
+4. **Commit**: `git commit -m "Add [Agent Name] specialist"`
+5. **Push**: `git push origin add-agent-name`
+6. **Open a Pull Request** with:
+   - Clear title: "Add [Agent Name] - [Category]"
+   - Description of what the agent does
+   - Why this agent is needed (use case)
+   - Any testing you've done
+
+### PR Review Process
+
+1. **Community Review**: Other contributors may provide feedback
+2. **Iteration**: Address feedback and make improvements
+3. **Approval**: Maintainers will approve when ready
+4. **Merge**: Your contribution becomes part of The Agency!
+
+### PR Template
+
+```markdown
+## Agent Information
+**Agent Name**: [Name]
+**Category**: [engineering/design/marketing/etc.]
+**Specialty**: [One-line description]
+
+## Motivation
+[Why is this agent needed? What gap does it fill?]
+
+## Testing
+[How have you tested this agent? Real-world use cases?]
+
+## Checklist
+- [ ] Follows agent template structure
+- [ ] Includes personality and voice
+- [ ] Has concrete code/template examples
+- [ ] Defines success metrics
+- [ ] Includes step-by-step workflow
+- [ ] Proofread and formatted correctly
+- [ ] Tested in real scenarios
+```
+
+---
+
+## 📐 Style Guide
+
+### Writing Style
+
+- **Be specific**: "Reduce page load by 60%" not "Make it faster"
+- **Be concrete**: "Create React components with TypeScript" not "Build UIs"
+- **Be memorable**: Give agents personality, not generic corporate speak
+- **Be practical**: Include real code, not pseudo-code
+
+### Formatting
+
+- Use **Markdown formatting** consistently
+- Include **emojis** for section headers (makes scanning easier)
+- Use **code blocks** for all code examples with proper syntax highlighting
+- Use **tables** for comparing options or showing metrics
+- Use **bold** for emphasis, `code` for technical terms
+
+### Code Examples
+
+```markdown
+## Example Code Block
+
+\`\`\`typescript
+// Always include:
+// 1. Language specification for syntax highlighting
+// 2. Comments explaining key concepts
+// 3. Real, runnable code (not pseudo-code)
+// 4. Modern best practices
+
+interface AgentExample {
+  name: string;
+  specialty: string;
+  deliverables: string[];
+}
+\`\`\`
+```
+
+### Tone
+
+- **Professional but approachable**: Not overly formal or casual
+- **Confident but not arrogant**: "Here's the best approach" not "Maybe you could try..."
+- **Helpful but not hand-holding**: Assume competence, provide depth
+- **Personality-driven**: Each agent should have a unique voice
+
+---
+
+## 🌟 Recognition
+
+Contributors who make significant contributions will be:
+
+- Listed in the README acknowledgments section
+- Highlighted in release notes
+- Featured in "Agent of the Week" showcases (if applicable)
+- Given credit in the agent file itself
+
+---
+
+## 🤔 Questions?
+
+- **General Questions**: [GitHub Discussions](https://github.com/msitarzewski/agency-agents/discussions)
+- **Bug Reports**: [GitHub Issues](https://github.com/msitarzewski/agency-agents/issues)
+- **Feature Requests**: [GitHub Issues](https://github.com/msitarzewski/agency-agents/issues)
+- **Community Chat**: [Join our discussions](https://github.com/msitarzewski/agency-agents/discussions)
+
+---
+
+## 📚 Resources
+
+### For New Contributors
+
+- [README.md](README.md) - Overview and agent catalog
+- [Example: Frontend Developer](engineering/engineering-frontend-developer.md) - Well-structured agent example
+- [Example: Reddit Community Builder](marketing/marketing-reddit-community-builder.md) - Great personality example
+- [Example: Whimsy Injector](design/design-whimsy-injector.md) - Creative specialist example
+
+### For Agent Design
+
+- Read existing agents for inspiration
+- Study the patterns that work well
+- Test your agents in real scenarios
+- Iterate based on feedback
+
+---
+
+## 🎉 Thank You!
+
+Your contributions make The Agency better for everyone. Whether you're:
+
+- Adding a new agent
+- Improving documentation
+- Fixing bugs
+- Sharing success stories
+- Helping other contributors
+
+**You're making a difference. Thank you!**
+
+---
+
+<div align="center">
+
+**Questions? Ideas? Feedback?**
+
+[Open an Issue](https://github.com/msitarzewski/agency-agents/issues) • [Start a Discussion](https://github.com/msitarzewski/agency-agents/discussions) • [Submit a PR](https://github.com/msitarzewski/agency-agents/pulls)
+
+Made with ❤️ by the community
+
+</div>