proagents 1.0.0

package/proagents/getting-started/prompt-engineering.md

@@ -0,0 +1,478 @@
+# Prompt Engineering Best Practices
+
+Guide to writing effective prompts for AI-assisted development with ProAgents.
+
+---
+
+## Overview
+
+Effective prompts lead to better AI assistance. This guide covers best practices for communicating with AI during development workflows.
+
+---
+
+## Core Principles
+
+### 1. Be Specific
+
+**Bad:**
+```
+Make this better
+```
+
+**Good:**
+```
+Refactor this function to:
+- Extract the validation logic into a separate function
+- Add error handling for null inputs
+- Use early returns instead of nested if statements
+```
+
+### 2. Provide Context
+
+**Bad:**
+```
+Fix the bug
+```
+
+**Good:**
+```
+Fix the login bug:
+- Error: "Cannot read property 'email' of undefined"
+- Occurs when: User submits empty form
+- Expected: Show validation error
+- File: src/components/LoginForm.tsx:45
+```
+
+### 3. Specify Constraints
+
+**Bad:**
+```
+Add authentication
+```
+
+**Good:**
+```
+Add authentication:
+- Use NextAuth.js (already installed)
+- Support Google and GitHub providers
+- Store sessions in database (Prisma)
+- Follow existing auth patterns in src/lib/auth.ts
+```
+
+### 4. Request Incrementally
+
+**Bad:**
+```
+Build a complete e-commerce system with cart, checkout, inventory, orders, shipping, and returns
+```
+
+**Good:**
+```
+Let's build the e-commerce system incrementally:
+1. First: Add product catalog display
+2. Then: Add to cart functionality
+3. Next: Checkout flow
+(Continue step by step)
+```
+
+---
+
+## Prompt Templates
+
+### Feature Request
+
+```markdown
+## Feature: [Name]
+
+### Description
+[What should this feature do?]
+
+### User Story
+As a [user type], I want [action] so that [benefit]
+
+### Acceptance Criteria
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+
+### Constraints
+- Must use: [existing patterns/libraries]
+- Must not: [restrictions]
+- Performance: [requirements]
+
+### Examples
+[Provide examples of expected behavior]
+```
+
+### Bug Fix Request
+
+```markdown
+## Bug: [Title]
+
+### Current Behavior
+[What's happening now?]
+
+### Expected Behavior
+[What should happen?]
+
+### Steps to Reproduce
+1. [Step 1]
+2. [Step 2]
+
+### Error Details
+- Error message: [message]
+- Stack trace: [if available]
+- Location: [file:line]
+
+### Environment
+- Browser/Node: [version]
+- OS: [os]
+```
+
+### Code Review Request
+
+```markdown
+## Review Request
+
+### Changes
+[Brief description of changes]
+
+### Files Modified
+- [file1]: [what changed]
+- [file2]: [what changed]
+
+### Areas to Focus
+- [ ] Logic correctness
+- [ ] Error handling
+- [ ] Performance
+- [ ] Security
+
+### Questions
+[Specific questions for reviewer]
+```
+
+### Refactoring Request
+
+```markdown
+## Refactor: [Component/Function]
+
+### Current Issues
+- [Issue 1]
+- [Issue 2]
+
+### Goals
+- [Goal 1]
+- [Goal 2]
+
+### Constraints
+- Must maintain: [backward compatibility]
+- Must not: [break existing tests]
+
+### Suggested Approach
+[Your ideas, if any]
+```
+
+---
+
+## Context Techniques
+
+### Include Relevant Code
+
+```markdown
+Here's the current implementation:
+
+```typescript
+function processOrder(order: Order) {
+  // 50 lines of code
+}
+```
+
+Issues:
+1. Function is too long
+2. Mixing concerns
+
+Please refactor following our service layer pattern.
+```
+
+### Reference Existing Patterns
+
+```markdown
+Add a new API endpoint following the pattern in:
+- src/app/api/users/route.ts
+- src/app/api/products/route.ts
+
+The endpoint should handle:
+- GET /api/orders
+- POST /api/orders
+```
+
+### Provide Examples
+
+```markdown
+Create a hook like useUserData:
+
+Example usage:
+```typescript
+const { data, loading, error, refetch } = useOrders({
+  userId: currentUser.id,
+  status: 'pending'
+});
+```
+
+Return shape:
+```typescript
+{
+  data: Order[] | null,
+  loading: boolean,
+  error: Error | null,
+  refetch: () => Promise<void>
+}
+```
+```
+
+---
+
+## Iterative Refinement
+
+### Start Broad, Then Narrow
+
+```
+Round 1: "Add form validation to the signup page"
+↓
+Round 2: "The email validation works, but also add:
+         - Password strength indicator
+         - Real-time username availability check"
+↓
+Round 3: "The password indicator should show:
+         - Minimum 8 characters
+         - At least one uppercase
+         - At least one number"
+```
+
+### Ask for Options
+
+```markdown
+I need to implement caching for API responses.
+
+Please suggest 3 approaches:
+1. In-memory caching
+2. Redis caching
+3. Browser caching
+
+For each, explain:
+- Pros and cons
+- Implementation complexity
+- When to use
+```
+
+### Request Explanations
+
+```markdown
+You suggested using useMemo here. Please explain:
+1. Why is it needed in this case?
+2. What would happen without it?
+3. Are there alternatives?
+```
+
+---
+
+## Domain-Specific Prompts
+
+### Frontend (React/Next.js)
+
+```markdown
+Create a React component:
+- Name: ProductCard
+- Props: product (Product type), onAddToCart
+- Features:
+  - Image with lazy loading
+  - Price with currency formatting
+  - Add to cart button with loading state
+- Styling: Use Tailwind CSS
+- Tests: Include unit tests with Testing Library
+```
+
+### Backend (Node.js/Express)
+
+```markdown
+Create an API endpoint:
+- Route: POST /api/orders
+- Authentication: Required (JWT)
+- Validation: Use Zod schema
+- Actions:
+  1. Validate input
+  2. Check inventory
+  3. Create order
+  4. Send confirmation email
+- Error handling: Standard error format
+- Response: Created order with 201 status
+```
+
+### Database
+
+```markdown
+Design a Prisma schema for:
+- Users (with profile)
+- Organizations (users belong to orgs)
+- Projects (orgs have projects)
+- Tasks (projects have tasks)
+
+Include:
+- Proper relations
+- Timestamps
+- Soft delete for users
+- Indexes for common queries
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+### 1. Vague Instructions
+
+❌ "Make it work"
+✅ "Fix the null pointer error when user.profile is undefined"
+
+### 2. Too Much at Once
+
+❌ "Build the entire authentication system"
+✅ "Start with the login form component"
+
+### 3. No Context
+
+❌ "Add a button"
+✅ "Add a 'Save Draft' button below the form, using our Button component with variant='secondary'"
+
+### 4. Assuming Knowledge
+
+❌ "Use our standard pattern"
+✅ "Use the repository pattern as shown in src/repositories/UserRepository.ts"
+
+### 5. Ignoring Constraints
+
+❌ "Add a date picker"
+✅ "Add a date picker using react-datepicker (already in package.json), styled to match our form inputs"
+
+---
+
+## Prompt Modifiers
+
+### For Code Generation
+
+| Modifier | Effect |
+|----------|--------|
+| "with TypeScript types" | Includes type definitions |
+| "with error handling" | Adds try/catch and error states |
+| "with tests" | Includes unit tests |
+| "with comments" | Adds code comments |
+| "following [pattern]" | Uses specified pattern |
+
+### For Explanations
+
+| Modifier | Effect |
+|----------|--------|
+| "step by step" | Detailed walkthrough |
+| "briefly" | Concise explanation |
+| "with examples" | Include code examples |
+| "for a beginner" | Simpler language |
+| "for production" | Production considerations |
+
+### For Reviews
+
+| Modifier | Effect |
+|----------|--------|
+| "focus on security" | Security-focused review |
+| "focus on performance" | Performance-focused review |
+| "be thorough" | Comprehensive review |
+| "quick check" | High-level review |
+
+---
+
+## Conversation Management
+
+### Starting a Session
+
+```markdown
+I'm working on [project type] using [tech stack].
+
+Today I need to:
+1. [Task 1]
+2. [Task 2]
+
+Let's start with [Task 1].
+```
+
+### Switching Context
+
+```markdown
+Good progress on the login form.
+
+Let's switch to the API endpoint now.
+Here's the current state: [context]
+```
+
+### Ending a Session
+
+```markdown
+Let's wrap up. Please:
+1. Summarize what we implemented
+2. List any TODOs or follow-ups
+3. Note any potential issues to watch
+```
+
+---
+
+## ProAgents-Specific Tips
+
+### Use Slash Commands
+
+```bash
+/feature-start "Add user authentication"
+# More effective than: "I want to add auth"
+
+/fix "Login button not responding"
+# More effective than: "There's a bug"
+
+/analyze
+# Let ProAgents understand your codebase first
+```
+
+### Reference Phase Context
+
+```markdown
+Based on the analysis from Phase 1, implement the
+user service following the patterns identified in
+src/services/.
+```
+
+### Build on Previous Work
+
+```markdown
+Continue from where we left off with the checkout flow.
+The cart component is done, now let's add the payment form.
+```
+
+---
+
+## Measuring Prompt Effectiveness
+
+### Good Prompt Indicators
+
+- AI asks few clarifying questions
+- Generated code needs minimal modifications
+- Solution matches project patterns
+- Tests pass on first try
+
+### Signs to Improve
+
+- AI asks many questions
+- Multiple revision rounds
+- Code doesn't match patterns
+- Missing error handling
+
+---
+
+## Next Steps
+
+- Practice with [example prompts](../examples/)
+- Review [command reference](../cli/commands-reference.md)
+- Set up [project standards](../standards/)

package/proagents/getting-started/team-onboarding.md

@@ -0,0 +1,236 @@
+# Team Onboarding Guide
+
+Guide for onboarding new team members to ProAgents.
+
+---
+
+## Overview
+
+This guide helps team leads onboard new developers to use ProAgents effectively.
+
+---
+
+## Onboarding Checklist
+
+### Day 1: Setup
+
+- [ ] Install required tools
+- [ ] Configure IDE ([IDE Setup](./ide-setup.md))
+- [ ] Clone project repository
+- [ ] Run `proagents init` in project
+- [ ] Review project configuration
+
+### Day 2: Learn the Workflow
+
+- [ ] Read [WORKFLOW.md](../WORKFLOW.md)
+- [ ] Read [GETTING-STARTED-STORY.md](../GETTING-STARTED-STORY.md)
+- [ ] Understand the 10 workflow phases
+- [ ] Review project standards
+
+### Day 3: First Feature
+
+- [ ] Pick a small starter task
+- [ ] Run through workflow with mentor
+- [ ] Complete first feature with guidance
+- [ ] Review and get feedback
+
+---
+
+## Quick Start for New Developers
+
+### 1. Understand the Workflow
+
+ProAgents uses a 10-phase development workflow:
+
+```
+1. Init       → 2. Analysis   → 3. Requirements → 4. Design
+     ↓
+5. Planning   → 6. Implementation → 7. Testing → 8. Review
+     ↓
+9. Documentation → 10. Deployment
+```
+
+### 2. Key Commands
+
+```bash
+# Start a new feature
+/feature-start "Feature name"
+
+# Check status
+/status
+
+# Get help
+/help
+
+# Quick bug fix
+/fix "Bug description"
+```
+
+### 3. Important Files
+
+| File | Purpose |
+|------|---------|
+| `proagents.config.yaml` | Project configuration |
+| `proagents/prompts/` | Workflow phase prompts |
+| `proagents/standards/` | Coding standards |
+| `proagents/checklists/` | Quality checklists |
+
+---
+
+## Team Configuration
+
+### Setting Up Team Standards
+
+1. **Review Existing Standards**
+```bash
+ls proagents/standards/
+```
+
+2. **Customize for Your Team**
+```bash
+# Copy and customize templates
+cp proagents/config/standards/*.template.md proagents/standards/
+```
+
+3. **Document Team Conventions**
+   - Naming conventions
+   - Code review process
+   - Testing requirements
+   - Documentation standards
+
+---
+
+## Role-Based Onboarding
+
+### Junior Developers
+
+**Focus Areas:**
+- Understanding the workflow phases
+- Following existing patterns
+- Learning from codebase analysis
+- Pair programming with seniors
+
+**Recommended Learning Path:**
+1. Read GETTING-STARTED-STORY.md (narrative walkthrough)
+2. Complete example project walkthrough
+3. Shadow a senior on a feature
+4. Take on a small bug fix independently
+
+### Senior Developers
+
+**Focus Areas:**
+- Customizing workflow for team
+- Setting up project standards
+- Configuring integrations
+- Training other team members
+
+**Recommended Learning Path:**
+1. Read full WORKFLOW.md documentation
+2. Review configuration options
+3. Set up team-specific standards
+4. Configure PM tool integration
+
+### Tech Leads
+
+**Focus Areas:**
+- Overall workflow configuration
+- Team standards definition
+- Integration with existing processes
+- Metrics and reporting
+
+**Recommended Learning Path:**
+1. Full documentation review
+2. Configure checkpoints and approvals
+3. Set up reporting dashboards
+4. Define team conventions
+
+---
+
+## Common Questions
+
+### Q: How does ProAgents work with our existing tools?
+
+ProAgents integrates with:
+- **Git**: Automatic branch management, commit conventions
+- **Jira/Linear**: Issue tracking sync
+- **Slack**: Notifications and updates
+- **CI/CD**: Deployment integration
+
+See [PM Integration](./pm-integration.md) for setup.
+
+### Q: Can I skip workflow phases?
+
+Yes! ProAgents supports flexible entry modes:
+- **Full Mode**: All phases (new features)
+- **Bug Fix Mode**: Streamlined (fixes)
+- **Quick Change Mode**: Minimal (config changes)
+
+Configure in `proagents.config.yaml`:
+```yaml
+entry_modes:
+  allow_direct_implementation: true
+  allow_bug_fix_fast_track: true
+```
+
+### Q: How do I handle existing code that doesn't follow standards?
+
+1. Run codebase analysis first
+2. ProAgents learns existing patterns
+3. Gradually align new code with standards
+4. Create tech debt items for legacy code
+
+### Q: What if the AI suggestion is wrong?
+
+1. Provide feedback using the correction system
+2. ProAgents learns from corrections
+3. Future suggestions will improve
+4. Manual override is always available
+
+---
+
+## Training Sessions
+
+### Session 1: Introduction (30 min)
+- What is ProAgents?
+- Workflow overview
+- Demo of basic commands
+
+### Session 2: Hands-On (60 min)
+- Set up development environment
+- Walk through a feature together
+- Practice key commands
+
+### Session 3: Advanced (45 min)
+- Configuration customization
+- Integration setup
+- Parallel development
+
+---
+
+## Resources
+
+### Documentation
+- [Main README](../README.md)
+- [Full Workflow](../WORKFLOW.md)
+- [Getting Started Story](../GETTING-STARTED-STORY.md)
+
+### Examples
+- [React Example](../examples/web-frontend-react/)
+- [Next.js Example](../examples/fullstack-nextjs/)
+- [Node.js Example](../examples/backend-nodejs/)
+
+### Support
+- Check `/help` for command reference
+- Review troubleshooting guides
+- Ask in team Slack channel
+
+---
+
+## Feedback
+
+Help us improve onboarding:
+- What was confusing?
+- What was missing?
+- What worked well?
+
+Submit feedback through the ProAgents feedback system or team channels.