proagents 1.6.19 → 1.6.21

package/.proagents/api-versioning/versioning-strategy.md

@@ -1,291 +0,0 @@
-# API Versioning Strategy
-
-Manage API versions and maintain backward compatibility.
-
----
-
-## Versioning Approaches
-
-### 1. URL Path Versioning (Recommended)
-
-```
-/api/v1/users
-/api/v2/users
-```
-
-**Pros:**
-- Clear and explicit
-- Easy to route
-- Works with all clients
-
-**Implementation:**
-```typescript
-// routes/index.ts
-import { Router } from 'express';
-import v1Routes from './v1';
-import v2Routes from './v2';
-
-const router = Router();
-
-router.use('/v1', v1Routes);
-router.use('/v2', v2Routes);
-
-export default router;
-```
-
----
-
-### 2. Header Versioning
-
-```
-Accept: application/vnd.api+json;version=2
-```
-
-**Implementation:**
-```typescript
-// middleware/version.middleware.ts
-export function versionMiddleware(req, res, next) {
-  const acceptHeader = req.headers.accept || '';
-  const versionMatch = acceptHeader.match(/version=(\d+)/);
-  req.apiVersion = versionMatch ? parseInt(versionMatch[1]) : 1;
-  next();
-}
-```
-
----
-
-### 3. Query Parameter Versioning
-
-```
-/api/users?version=2
-```
-
-**Note:** Generally not recommended, but useful for quick testing.
-
----
-
-## Version Lifecycle
-
-### Version States
-
-| State | Description | Support Level |
-|-------|-------------|---------------|
-| **Current** | Active, recommended version | Full support |
-| **Supported** | Still maintained | Security fixes |
-| **Deprecated** | Marked for removal | Limited support |
-| **Sunset** | No longer available | No support |
-
-### Lifecycle Timeline
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ Version Lifecycle                                               │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                 │
-│ v1 ──────────────┬─────────────┬────────────┬────────────────  │
-│    Current       │ Supported   │ Deprecated │ Sunset           │
-│    (12 months)   │ (6 months)  │ (6 months) │                  │
-│                  │             │            │                  │
-│ v2 ──────────────┴─────────────┴────────────┴─────────────     │
-│    Development → Current → Supported → Deprecated → Sunset     │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Breaking vs Non-Breaking Changes
-
-### Non-Breaking (Safe in same version)
-
-- Adding new endpoints
-- Adding optional fields to responses
-- Adding optional query parameters
-- Adding new enum values (if client ignores unknown)
-- Performance improvements
-- Bug fixes
-
-### Breaking (Requires new version)
-
-- Removing endpoints
-- Removing response fields
-- Changing field types
-- Renaming fields
-- Changing authentication
-- Changing error formats
-- Making optional fields required
-
----
-
-## Version Migration Guide
-
-### Creating a New Version
-
-```bash
-# 1. Copy existing version
-cp -r src/api/v1 src/api/v2
-
-# 2. Update version routes
-# src/api/v2/index.ts
-
-# 3. Implement changes
-# Make breaking changes in v2
-
-# 4. Update API docs
-# docs/api/v2.md
-
-# 5. Create migration guide
-# docs/migration/v1-to-v2.md
-```
-
-### Migration Guide Template
-
-```markdown
-# Migration Guide: v1 to v2
-
-## Overview
-Summary of changes in v2.
-
-## Breaking Changes
-
-### 1. User Response Format
-**Before (v1):**
-```json
-{ "id": 1, "name": "John" }
-```
-
-**After (v2):**
-```json
-{ "data": { "id": "uuid", "fullName": "John" } }
-```
-
-**Migration:**
-- Update response parsing
-- Change `name` to `fullName`
-- Handle wrapped response
-
-### 2. Authentication
-**Before:** API key in query
-**After:** Bearer token in header
-
-**Migration:**
-```javascript
-// Before
-fetch('/api/v1/users?apiKey=xxx')
-
-// After
-fetch('/api/v2/users', {
-  headers: { 'Authorization': 'Bearer xxx' }
-})
-```
-
-## Deprecation Timeline
-- v1 deprecated: March 1, 2024
-- v1 sunset: September 1, 2024
-```
-
----
-
-## Deprecation Process
-
-### 1. Announce Deprecation
-
-```typescript
-// Add deprecation header
-app.use('/api/v1', (req, res, next) => {
-  res.set('Deprecation', 'true');
-  res.set('Sunset', 'Sat, 01 Sep 2024 00:00:00 GMT');
-  res.set('Link', '</api/v2>; rel="successor-version"');
-  next();
-});
-```
-
-### 2. Add Warning to Responses
-
-```json
-{
-  "data": { ... },
-  "_warnings": [
-    {
-      "code": "DEPRECATED_VERSION",
-      "message": "API v1 is deprecated. Please migrate to v2 by September 1, 2024.",
-      "documentation": "https://docs.example.com/migration/v1-to-v2"
-    }
-  ]
-}
-```
-
-### 3. Track Usage
-
-```typescript
-// Log v1 usage for migration tracking
-app.use('/api/v1', (req, res, next) => {
-  logger.info('v1_api_call', {
-    endpoint: req.path,
-    client: req.headers['user-agent'],
-    timestamp: new Date()
-  });
-  next();
-});
-```
-
-### 4. Notify Clients
-
-```markdown
-Subject: API v1 Deprecation Notice
-
-Dear Developer,
-
-API v1 will be deprecated on March 1, 2024, and sunset on September 1, 2024.
-
-Action Required:
-- Migrate to API v2 before September 1, 2024
-- See migration guide: [link]
-- Contact support if you need assistance
-
-Timeline:
-- March 1: Deprecation warnings added
-- June 1: Rate limits reduced on v1
-- September 1: v1 endpoints return 410 Gone
-```
-
----
-
-## Configuration
-
-```yaml
-# proagents.config.yaml
-
-api_versioning:
-  strategy: "url_path"  # url_path | header | query
-  prefix: "/api"
-
-  versions:
-    v1:
-      status: "deprecated"
-      sunset_date: "2024-09-01"
-      successor: "v2"
-
-    v2:
-      status: "current"
-
-  deprecation:
-    warning_header: true
-    response_warning: true
-    log_usage: true
-
-  documentation:
-    auto_generate: true
-    format: "openapi"
-```
-
----
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `pa:api-version new [version]` | Create new API version |
-| `pa:api-version deprecate [version]` | Mark version as deprecated |
-| `pa:api-version status` | Show version status |
-| `pa:api-migration-guide [from] [to]` | Generate migration guide |

package/.proagents/automation/README.md

@@ -1,38 +0,0 @@
-# Automation
-
-Configure AI behavior and automated decision-making in the workflow.
-
----
-
-## Overview
-
-Control how the AI makes decisions, handles ambiguity, and automates routine tasks.
-
-## Documentation
-
-| Document | Description |
-|----------|-------------|
-| [Auto Decisions](./auto-decisions.md) | Configure automatic decision-making |
-| [AI Behavior Rules](./ai-behavior-rules.md) | Define AI behavior constraints |
-| [AI Prompt Injection](./ai-prompt-injection.md) | Custom context injection for AI |
-
-## Quick Start
-
-```yaml
-# proagents.config.yaml
-automation:
-  auto_decisions:
-    enabled: true
-    confidence_threshold: 0.8
-
-  behavior:
-    ask_before_destructive: true
-    prefer_existing_patterns: true
-```
-
-## Key Features
-
-- **Auto-Decisions**: Let AI make routine decisions automatically
-- **Behavior Rules**: Define constraints for AI actions
-- **Context Injection**: Add project-specific context to AI prompts
-- **Confidence Thresholds**: Control when AI asks vs decides

package/.proagents/automation/ai-behavior-rules.md

@@ -1,339 +0,0 @@
-# AI Behavior Rules for Automation
-
-Instructions for AI to maintain uninterrupted workflow execution.
-
----
-
-## Core Principle
-
-**NEVER ASK QUESTIONS DURING AUTOMATED WORKFLOWS**
-
-Instead of asking:
-- Check pre-configured decisions
-- Use inference rules
-- Apply defaults
-- Log the decision
-- Continue working
-
----
-
-## Decision Resolution Flow
-
-```
-┌─────────────────────────────────────────────────────────┐
-│ AI needs to make a decision                             │
-├─────────────────────────────────────────────────────────┤
-│                                                         │
-│  1. Check explicit config                               │
-│     └─ decisions.yaml has answer? → Use it             │
-│                                                         │
-│  2. Check project type defaults                         │
-│     └─ Project type defines it? → Use it               │
-│                                                         │
-│  3. Check codebase patterns                             │
-│     └─ Similar pattern exists? → Follow it             │
-│                                                         │
-│  4. Check inference rules                               │
-│     └─ Can infer from context? → Use inference         │
-│                                                         │
-│  5. Use global default                                  │
-│     └─ Default exists? → Use it                        │
-│                                                         │
-│  6. Use safest option                                   │
-│     └─ Pick most conservative choice                   │
-│                                                         │
-│  NEVER reach step 7: Ask user                           │
-│                                                         │
-└─────────────────────────────────────────────────────────┘
-```
-
----
-
-## Rules for AI
-
-### Rule 1: No Questions in Full Automation
-
-```
-❌ WRONG:
-"Should I use REST or GraphQL for this API?"
-
-✅ CORRECT:
-[Check config: api_style = "rest"]
-"Creating REST API endpoint as per project configuration."
-[Continue working]
-```
-
-### Rule 2: State Decisions, Don't Ask
-
-```
-❌ WRONG:
-"Where should I put this component? Options:
-1. src/components/
-2. src/features/auth/components/"
-
-✅ CORRECT:
-"Placing component in src/components/auth/ following existing project structure."
-[Continue working]
-```
-
-### Rule 3: Log Uncertain Decisions
-
-```
-❌ WRONG:
-"I'm not sure if this should be a hook or a utility function. What do you think?"
-
-✅ CORRECT:
-"Creating as custom hook (useAuth) - matches similar patterns in codebase."
-[Log: decision=hook, confidence=medium, reason=pattern_match]
-[Continue working]
-```
-
-### Rule 4: Use Defaults for Ambiguous Situations
-
-```
-❌ WRONG:
-"There are multiple ways to implement this. Which approach do you prefer?"
-
-✅ CORRECT:
-"Implementing using [default approach] as per project settings."
-[Continue working]
-```
-
-### Rule 5: Follow Existing Patterns
-
-```
-❌ WRONG:
-"I see you have both class and functional components. Which should I use?"
-
-✅ CORRECT:
-[Analyze: 90% functional components]
-"Using functional component to match project conventions."
-[Continue working]
-```
-
----
-
-## Decision Templates
-
-### When Creating Components
-
-```yaml
-auto_decide:
-  location: "src/components/[category]/"
-  style: "functional"
-  naming: "PascalCase"
-  test: "colocated"
-  export: "named"
-
-action:
-  1. Create component file
-  2. Create test file
-  3. Update index exports
-  4. Log decision
-  5. Continue
-```
-
-### When Creating API Endpoints
-
-```yaml
-auto_decide:
-  style: "{{config.api_style}}"
-  validation: "zod"
-  error_handling: "centralized"
-  documentation: "auto_generate"
-
-action:
-  1. Create route file
-  2. Create controller
-  3. Create service
-  4. Add validation
-  5. Generate docs
-  6. Log decision
-  7. Continue
-```
-
-### When Choosing Libraries
-
-```yaml
-auto_decide:
-  rule: "Use already installed, or project default"
-
-  priority:
-    1. Already in package.json
-    2. Project type default
-    3. Global default
-    4. Most popular stable option
-
-action:
-  1. Check package.json
-  2. Use found or default
-  3. Log decision
-  4. Continue
-```
-
-### When Naming Things
-
-```yaml
-auto_decide:
-  components: "PascalCase"
-  hooks: "useCamelCase"
-  services: "camelCaseService"
-  utils: "camelCase"
-  constants: "UPPER_SNAKE_CASE"
-  files:
-    components: "PascalCase.tsx"
-    others: "camelCase.ts"
-
-action:
-  1. Determine type
-  2. Apply naming rule
-  3. Continue
-```
-
----
-
-## Confidence Levels
-
-When making auto-decisions, assess confidence:
-
-### High Confidence (Just do it)
-- Explicit config exists
-- Clear project pattern exists
-- Standard best practice
-
-```
-"Using Zustand for state management (configured in project settings)."
-[confidence: high]
-```
-
-### Medium Confidence (Do it, flag for review)
-- Inferred from context
-- Multiple valid options
-- Slight uncertainty
-
-```
-"Creating separate service file for API calls (inferred from similar features)."
-[confidence: medium, flagged_for_review: true]
-```
-
-### Low Confidence (Do safest, definitely flag)
-- No clear guidance
-- Novel situation
-- Potential impact
-
-```
-"Using default error handling pattern (no specific guidance found)."
-[confidence: low, flagged_for_review: true, requires_post_review: true]
-```
-
----
-
-## Communication Style
-
-### During Execution
-
-```
-✅ DO:
-"Creating UserProfile component in src/components/user/..."
-"Adding Zod validation schema..."
-"Generating tests with 85% coverage target..."
-
-❌ DON'T:
-"Should I create this in components or features?"
-"Do you want me to add validation?"
-"What coverage target should I aim for?"
-```
-
-### Decision Announcements
-
-```
-Format:
-"[Action] [what] [where/how] [reason if non-obvious]"
-
-Examples:
-"Creating AuthService in src/services/ following existing service pattern."
-"Using React Query for server state as configured."
-"Adding error boundary wrapper (standard for page components)."
-```
-
-### Uncertainty Handling
-
-```
-Format:
-"[Action] using [choice] ([brief reason]). Flagged for review."
-
-Examples:
-"Implementing pagination using cursor-based approach (better for large datasets). Flagged for review."
-"Splitting into micro-components (file was getting large). Flagged for review."
-```
-
----
-
-## Post-Workflow Summary
-
-After completing automated workflow, provide:
-
-```markdown
-## Workflow Complete
-
-### Summary
-- Feature: User Authentication
-- Files created: 12
-- Files modified: 3
-- Tests added: 8
-
-### Decisions Made
-| Decision | Choice | Confidence | Rule Applied |
-|----------|--------|------------|--------------|
-| State management | Zustand | High | Explicit config |
-| Component location | src/components/auth | High | Pattern match |
-| API style | REST | High | Explicit config |
-| Error handling | Error boundary | Medium | Inference |
-
-### Flagged for Review (2)
-1. **Token storage**: Used httpOnly cookies (security best practice)
-   - Alternative: localStorage (faster but less secure)
-
-2. **Session duration**: Set to 7 days
-   - Based on: Default config
-   - Consider: Shorter for sensitive apps
-
-### No Issues Found
-✅ All decisions within confidence thresholds
-✅ No blocking questions needed
-✅ Automation completed successfully
-```
-
----
-
-## Emergency Override
-
-If AI truly cannot proceed without input:
-
-```yaml
-emergency_protocol:
-  condition: "Truly ambiguous AND high-impact decision"
-
-  actions:
-    1. Try harder to find a default
-    2. Use safest/most conservative option
-    3. Mark as "CRITICAL_REVIEW_NEEDED"
-    4. Continue with safest option
-    5. Do NOT block workflow
-
-  example:
-    situation: "Delete user data permanently vs soft delete"
-    action: "Use soft delete (safer), flag as CRITICAL_REVIEW_NEEDED"
-    reason: "Data deletion is irreversible, chose conservative option"
-```
-
----
-
-## Commands for AI
-
-| Command | Description |
-|---------|-------------|
-| `[AUTO-DECIDE]` | Marker in logs for auto-decisions |
-| `[FLAGGED]` | Decision flagged for review |
-| `[CONFIDENCE:HIGH/MEDIUM/LOW]` | Decision confidence level |
-| `[RULE:rule_name]` | Which rule was applied |