chargefy-js 1.0.0

package/.claude/MULTI_AGENT_WORKFLOW.md

@@ -0,0 +1,557 @@
+# Multi-Agent Workflow for Chargefy SDK Development
+
+This document describes how to use the specialized agents to efficiently develop the Chargefy SDK based on the Polar SDK architecture.
+
+## 🤖 Available Agents
+
+### 1. Backend Engineer (`/.claude/agents/backend-engineer.md`)
+**Specialization**: Core SDK implementation, architecture, TypeScript development
+
+**Use for**:
+- Implementing core infrastructure (HTTP client, types, models)
+- Creating service classes and standalone functions
+- Setting up build configuration
+- Implementing webhook validation
+- Refactoring and optimization
+
+**Key capabilities**:
+- Deep understanding of Polar SDK patterns
+- TypeScript strict mode expertise
+- Functional programming with Result types
+- Zod schema implementation
+
+---
+
+### 2. QA Engineer (`/.claude/agents/qa-engineer.md`)
+**Specialization**: Testing, quality assurance, CI/CD automation
+
+**Use for**:
+- Creating test strategies and test suites
+- Writing unit, integration, and e2e tests
+- Setting up CI/CD pipelines
+- Performance testing and benchmarking
+- Code coverage analysis
+- Bug reporting and validation
+
+**Key capabilities**:
+- Jest/Vitest expertise
+- AAA testing pattern
+- Mock strategies
+- Webhook testing
+- Coverage reporting
+
+---
+
+### 3. Product Manager (`/.claude/agents/product-manager.md`)
+**Specialization**: Requirements, DX, API design, competitive analysis
+
+**Use for**:
+- Defining feature requirements
+- Reviewing developer experience
+- API design validation
+- Competitive analysis
+- Release planning and roadmaps
+- Quality gate reviews
+
+**Key capabilities**:
+- DX evaluation frameworks
+- Feature prioritization
+- API design patterns
+- Market research
+- Stakeholder communication
+
+---
+
+## 🔄 Workflow Patterns
+
+### Pattern 1: Sequential Implementation (Single Feature)
+
+**Use when**: Implementing a specific feature from start to finish
+
+```mermaid
+graph LR
+    PM[PM: Define Requirements] --> BE[Backend: Implement]
+    BE --> QA[QA: Test]
+    QA --> PM2[PM: Validate DX]
+    PM2 --> Done[Feature Complete]
+```
+
+**Example**: Implementing the Customers service
+
+```bash
+# Step 1: Product Manager defines requirements
+claude --agent product-manager "Define requirements for Customers service API including create, list, get, update, delete operations"
+
+# Step 2: Backend Engineer implements
+claude --agent backend-engineer "Implement the Customers service with all CRUD operations following Polar SDK patterns"
+
+# Step 3: QA Engineer tests
+claude --agent qa-engineer "Create comprehensive tests for the Customers service including unit and integration tests"
+
+# Step 4: Product Manager validates
+claude --agent product-manager "Review Customers service implementation for DX and completeness"
+```
+
+---
+
+### Pattern 2: Parallel Exploration (Research Phase)
+
+**Use when**: Starting a new phase and need research from multiple angles
+
+```mermaid
+graph TD
+    Start[Start Research] --> PM[PM: Market Analysis]
+    Start --> BE[Backend: Technical Analysis]
+    Start --> QA[QA: Test Strategy]
+    PM --> Sync[Sync Meeting]
+    BE --> Sync
+    QA --> Sync
+    Sync --> Plan[Create Plan]
+```
+
+**Example**: Beginning SDK development
+
+```bash
+# Run all three agents in parallel (single call with multiple agents)
+claude \
+  --agent product-manager "Research competitor SDKs and define feature priorities" \
+  --agent backend-engineer "Analyze Polar SDK architecture and create implementation plan" \
+  --agent qa-engineer "Define test strategy and setup test infrastructure" \
+  --parallel
+```
+
+**Best Practice**: Use `--parallel` flag to run 3+ agents simultaneously following Anthropic's best practices for multi-agent systems.
+
+---
+
+### Pattern 3: Iterative Development (Full Feature)
+
+**Use when**: Building a complete feature with feedback loops
+
+```mermaid
+graph TD
+    PM1[PM: Requirements] --> BE1[Backend: Core Implementation]
+    BE1 --> QA1[QA: Unit Tests]
+    QA1 --> BE2[Backend: Fix Issues]
+    BE2 --> QA2[QA: Integration Tests]
+    QA2 --> PM2[PM: DX Review]
+    PM2 --> Refine{Needs Refinement?}
+    Refine -->|Yes| BE3[Backend: Refactor]
+    Refine -->|No| Complete[Feature Complete]
+    BE3 --> QA3[QA: Regression Tests]
+    QA3 --> PM2
+```
+
+**Example**: Implementing Subscriptions with full lifecycle
+
+```bash
+# Phase 1: Requirements
+claude --agent product-manager "Define complete requirements for Subscriptions service"
+
+# Phase 2: Initial Implementation
+claude --agent backend-engineer "Implement Subscriptions core functionality"
+
+# Phase 3: Initial Testing
+claude --agent qa-engineer "Create unit tests for Subscriptions service"
+
+# Phase 4: Fix Issues (if any found)
+claude --agent backend-engineer "Fix issues found in testing: [list issues]"
+
+# Phase 5: Integration Testing
+claude --agent qa-engineer "Create integration tests for Subscriptions including pagination and error cases"
+
+# Phase 6: DX Review
+claude --agent product-manager "Review Subscriptions API for developer experience"
+
+# Phase 7: Refinement (if needed)
+# ... repeat as needed ...
+```
+
+---
+
+### Pattern 4: Review & Release (Quality Gates)
+
+**Use when**: Preparing for a release
+
+```mermaid
+graph LR
+    Start[Release Prep] --> QA[QA: Test Report]
+    Start --> PM[PM: Feature Review]
+    Start --> BE[Backend: Code Review]
+    QA --> Gate{Quality Gates Pass?}
+    PM --> Gate
+    BE --> Gate
+    Gate -->|Yes| Release[Approve Release]
+    Gate -->|No| Fix[Create Fix List]
+    Fix --> Iterate[Iterate]
+```
+
+**Example**: Pre-release validation
+
+```bash
+# Run architecture review
+claude --agent product-manager --prompt .claude/prompts/sdk-architecture-review.md
+
+# Run API compliance check
+claude --agent product-manager --prompt .claude/prompts/api-compliance-check.md
+
+# Get QA report
+claude --agent qa-engineer "Generate comprehensive test report with coverage and quality metrics"
+
+# Get technical review
+claude --agent backend-engineer "Review codebase for technical debt and optimization opportunities"
+```
+
+---
+
+## 📊 Decision Matrix: Which Agent to Use?
+
+| Task | Agent | Why |
+|------|-------|-----|
+| "What features should we build?" | Product Manager | Requirements & prioritization |
+| "How should we implement X?" | Backend Engineer | Technical architecture |
+| "Is the code quality good?" | QA Engineer | Testing & validation |
+| "Does this API make sense?" | Product Manager | DX evaluation |
+| "How do I test webhooks?" | QA Engineer | Testing expertise |
+| "Should we use pattern X or Y?" | Backend Engineer | Technical decisions |
+| "Are we ready to release?" | All (parallel) | Quality gates |
+| "How does Stripe do this?" | Product Manager | Competitive analysis |
+| "Why is this test failing?" | QA Engineer | Debugging tests |
+| "Is this code type-safe?" | Backend Engineer | TypeScript expertise |
+
+---
+
+## 🎯 Example Workflows
+
+### Workflow 1: SDK Bootstrap (Day 1)
+
+**Goal**: Set up project foundation
+
+```bash
+# 1. Parallel research (Anthropic best practice: 3 agents at start)
+claude --parallel \
+  --agent product-manager "Define MVP feature set and success criteria" \
+  --agent backend-engineer "Analyze Polar SDK and create migration plan" \
+  --agent qa-engineer "Define test strategy and select testing framework"
+
+# 2. Backend sets up infrastructure
+claude --agent backend-engineer "Set up project structure with tsconfig, package.json, and core directories"
+
+# 3. QA sets up testing
+claude --agent qa-engineer "Configure Jest and create initial test structure"
+
+# 4. PM validates setup
+claude --agent product-manager "Review project setup and validate against requirements"
+```
+
+---
+
+### Workflow 2: Implement Core Services (Week 1-2)
+
+**Goal**: Implement essential services
+
+```bash
+# Service 1: Customers (P0)
+claude --agent product-manager "Define requirements for Customers service"
+claude --agent backend-engineer "Implement Customers service"
+claude --agent qa-engineer "Test Customers service"
+
+# Service 2: Subscriptions (P0)
+claude --agent backend-engineer "Implement Subscriptions service"
+claude --agent qa-engineer "Test Subscriptions service"
+
+# Service 3: Payments (P0)
+claude --agent backend-engineer "Implement Payments service"
+claude --agent qa-engineer "Test Payments service"
+
+# Review
+claude --agent product-manager "Review all P0 services for completeness"
+```
+
+---
+
+### Workflow 3: Webhook Implementation (Day X)
+
+**Goal**: Complete webhook support
+
+```bash
+# 1. Requirements
+claude --agent product-manager "Define all webhook event types and validation requirements"
+
+# 2. Implementation
+claude --agent backend-engineer "Implement webhook validation with standardwebhooks and Zod schemas"
+
+# 3. Testing
+claude --agent qa-engineer "Create comprehensive webhook tests including signature verification"
+
+# 4. Validation
+claude --agent product-manager "Validate webhook API matches industry standards"
+```
+
+---
+
+### Workflow 4: Pre-Release Checklist (Release Day)
+
+**Goal**: Validate release readiness
+
+```bash
+# 1. Run automated reviews (parallel)
+claude --parallel \
+  --agent product-manager --prompt .claude/prompts/sdk-architecture-review.md \
+  --agent qa-engineer "Generate test coverage and quality report" \
+  --agent backend-engineer "Run TypeScript compiler and linter"
+
+# 2. API compliance check
+claude --agent product-manager --prompt .claude/prompts/api-compliance-check.md
+
+# 3. Final validation
+claude --agent product-manager "Create go/no-go recommendation for release based on all reports"
+```
+
+---
+
+## 💡 Best Practices
+
+### 1. Use Parallel Agents for Research
+Following Anthropic's multi-agent best practices:
+- Start complex tasks with 3+ agents in parallel
+- Each agent explores different aspects simultaneously
+- Expect ~15x token consumption vs. regular chat (normal for quality)
+
+```bash
+# ✅ Good: Parallel research
+claude --parallel \
+  --agent product-manager "Research competitors" \
+  --agent backend-engineer "Analyze architecture" \
+  --agent qa-engineer "Define test strategy"
+
+# ❌ Bad: Sequential when parallel is better
+claude --agent product-manager "Research competitors"
+# ... wait ...
+claude --agent backend-engineer "Analyze architecture"
+# ... wait ...
+```
+
+### 2. Detailed Task Descriptions
+Each agent call should include:
+- Clear objective
+- Expected output format
+- Tools/sources to use
+- Task boundaries
+
+```bash
+# ✅ Good: Detailed task
+claude --agent backend-engineer "Implement the Customers service in src/sdk/customers.ts following the Polar SDK pattern from polar-js-main/src/sdk/customers.ts. Include all CRUD operations (create, list, get, update, delete) with proper type safety and JSDoc comments."
+
+# ❌ Bad: Vague task
+claude --agent backend-engineer "Make customers work"
+```
+
+### 3. Scale Effort to Complexity
+- Simple fact check: 1 agent, 3-10 tool calls
+- Feature implementation: 2-4 agents, 10-15 calls each
+- Complex architecture: 10+ agents, clear divisions
+
+### 4. Context Isolation
+- Each agent maintains its own context
+- Main orchestrator (you) maintains global state
+- Agents communicate through you, not directly
+
+### 5. Iterative Feedback
+- Implement → Test → Review → Refine
+- Don't wait for perfection; iterate
+- Each cycle improves quality
+
+---
+
+## 🚨 Common Pitfalls
+
+### ❌ Anti-Pattern 1: Wrong Agent for Task
+```bash
+# Bad: QA implementing features
+claude --agent qa-engineer "Implement the Payments service"
+
+# Good: Backend implements, QA tests
+claude --agent backend-engineer "Implement the Payments service"
+claude --agent qa-engineer "Test the Payments service"
+```
+
+### ❌ Anti-Pattern 2: Skipping Testing
+```bash
+# Bad: Implement without testing
+claude --agent backend-engineer "Implement all services"
+# Ship it!
+
+# Good: Implement with testing
+claude --agent backend-engineer "Implement Customers service"
+claude --agent qa-engineer "Test Customers service"
+# ... repeat for each service ...
+```
+
+### ❌ Anti-Pattern 3: No Requirements
+```bash
+# Bad: Start coding without plan
+claude --agent backend-engineer "Start building SDK"
+
+# Good: Plan first
+claude --agent product-manager "Define MVP requirements"
+claude --agent backend-engineer "Implement based on requirements"
+```
+
+### ❌ Anti-Pattern 4: No Validation
+```bash
+# Bad: Implement and assume it's good
+claude --agent backend-engineer "Implement feature X"
+# Done!
+
+# Good: Validate DX
+claude --agent backend-engineer "Implement feature X"
+claude --agent product-manager "Review feature X for DX"
+```
+
+---
+
+## 📈 Success Metrics
+
+Track these metrics to measure multi-agent effectiveness:
+
+### Velocity Metrics
+- Features implemented per week
+- Test coverage growth
+- Documentation completeness
+
+### Quality Metrics
+- Bugs found by QA vs. production
+- Time to fix issues
+- Test pass rate
+
+### DX Metrics
+- Time to first success (TTFS)
+- API intuitiveness score
+- Documentation clarity
+
+### Process Metrics
+- Agent handoff efficiency
+- Rework rate (how often features need changes)
+- Parallel vs. sequential work ratio
+
+---
+
+## 🔧 Tools Integration
+
+### Context7 Integration
+All agents can use Context7 to fetch up-to-date documentation:
+
+```bash
+# Example: Get latest TypeScript docs
+claude --agent backend-engineer "Use Context7 to fetch latest TypeScript strict mode best practices"
+
+# Example: Get testing framework docs
+claude --agent qa-engineer "Use Context7 to get Jest documentation for async testing"
+```
+
+### WebSearch Integration
+Agents can search for current best practices:
+
+```bash
+# Example: Research patterns
+claude --agent product-manager "Use WebSearch to research SDK DX best practices 2025"
+
+# Example: Competitor analysis
+claude --agent product-manager "Use WebSearch to find Stripe SDK documentation and patterns"
+```
+
+---
+
+## 📚 Quick Reference
+
+### Starting a New Feature
+```bash
+PM → Define requirements
+Backend → Implement
+QA → Test
+PM → Validate DX
+```
+
+### Debugging an Issue
+```bash
+QA → Reproduce and report
+Backend → Fix
+QA → Verify fix
+```
+
+### Release Preparation
+```bash
+Parallel: PM (review) + QA (report) + Backend (audit)
+→ PM: Go/No-go decision
+```
+
+### Research Task
+```bash
+Parallel: PM + Backend + QA (all research different angles)
+→ Synthesize findings
+→ Create plan
+```
+
+---
+
+## 🎓 Learning Resources
+
+### Anthropic Multi-Agent Best Practices
+- [How we built our multi-agent research system](https://www.anthropic.com/engineering/multi-agent-research-system)
+- Use parallel agents for breadth-first queries
+- Scale effort to query complexity
+- Detailed task descriptions essential
+
+### SDK Development
+- Polar SDK reference: `polar-js-main/`
+- TypeScript best practices: Use Context7
+- Testing patterns: Use WebSearch for "SDK testing best practices 2025"
+
+### Workflow Optimization
+- Use parallel agents when tasks are independent
+- Iterate quickly with feedback loops
+- Maintain clear agent boundaries
+- Document decisions and rationale
+
+---
+
+## 🆘 Troubleshooting
+
+**Q: Which agent should I use for X?**
+A: Check the Decision Matrix table above.
+
+**Q: Should I run agents in parallel?**
+A: Yes, for research tasks or independent work. No, for dependent tasks.
+
+**Q: How do I handle conflicting recommendations?**
+A: You (orchestrator) make the final decision based on project priorities.
+
+**Q: Agent seems confused about context?**
+A: Provide more detailed task description with clear boundaries.
+
+**Q: Tests are failing after implementation?**
+A: Normal! Have QA report issues → Backend fixes → QA verifies. Iterate.
+
+**Q: How many iterations are normal?**
+A: 2-3 cycles for most features. Complex features may need 5+.
+
+---
+
+## 📞 Support
+
+For issues with:
+- **Agent behavior**: Review agent configuration in `.claude/agents/`
+- **Workflow patterns**: Consult this document
+- **Technical implementation**: Check Polar SDK reference
+- **Testing strategies**: Check QA agent documentation
+
+---
+
+## Version History
+
+- **v1.0.0** (2025-11-10): Initial multi-agent workflow documentation
+  - 3 specialized agents (Backend, QA, PM)
+  - 4 workflow patterns
+  - 2 auxiliary prompts
+  - Best practices from Anthropic