proagents 1.6.13 → 1.6.16

package/.proagents/.learning/global/common-patterns.template.json

@@ -0,0 +1,60 @@
+{
+  "_template_info": {
+    "description": "Template reference for common-patterns.json schema",
+    "note": "DO NOT modify this file - it gets updated with ProAgents upgrades",
+    "usage": "AI reads this to understand expected schema for common-patterns.json"
+  },
+
+  "$schema": "../schemas/patterns-schema.json",
+  "version": "1.0.0",
+  "updated_at": "2024-01-15T10:30:00Z",
+
+  "patterns": {
+    "component_patterns": [
+      {
+        "id": "pattern-id",
+        "name": "Pattern Name",
+        "frequency": 95,
+        "confidence": 0.98,
+        "template": "code template with {{placeholders}}"
+      }
+    ],
+    "api_patterns": [],
+    "error_handling": [],
+    "testing_patterns": []
+  },
+
+  "anti_patterns": [
+    {
+      "id": "anti-pattern-id",
+      "name": "Anti-pattern Name",
+      "detected_count": 0,
+      "suggestion": "How to fix",
+      "auto_suggest": true
+    }
+  ],
+
+  "learned_from": {
+    "codebase_analysis": 0,
+    "user_corrections": 0,
+    "explicit_teaching": 0
+  },
+
+  "_schema_notes": {
+    "patterns": {
+      "component_patterns": "React/Vue/etc component patterns",
+      "api_patterns": "API handler patterns",
+      "error_handling": "Error handling patterns",
+      "testing_patterns": "Test structure patterns"
+    },
+    "pattern_fields": {
+      "id": "Unique identifier",
+      "name": "Human-readable name",
+      "frequency": "How often used (0-100)",
+      "confidence": "AI confidence (0-1)",
+      "template": "Code template with {{placeholders}}"
+    },
+    "anti_patterns": "Patterns to avoid",
+    "learned_from": "Source of learning data"
+  }
+}

package/.proagents/.learning/global/user-preferences.template.json

@@ -0,0 +1,78 @@
+{
+  "_template_info": {
+    "description": "Template reference for user-preferences.json schema",
+    "note": "DO NOT modify this file - it gets updated with ProAgents upgrades",
+    "usage": "AI reads this to understand expected schema for user-preferences.json"
+  },
+
+  "$schema": "../schemas/user-preferences-schema.json",
+  "version": "1.0.0",
+  "updated_at": "2024-01-15T10:30:00Z",
+
+  "checkpoint_preferences": {
+    "usually_skips": ["after_requirements", "after_documentation"],
+    "always_reviews": ["after_design", "before_deployment"],
+    "auto_approve_conditions": [
+      {
+        "checkpoint": "after_analysis",
+        "condition": "files_changed < 5",
+        "confidence": 0.85
+      }
+    ]
+  },
+
+  "workflow_preferences": {
+    "preferred_mode": "full",
+    "skip_phases_for_bug_fixes": ["design", "documentation"],
+    "detail_level": "high",
+    "verbosity": "moderate"
+  },
+
+  "code_preferences": {
+    "naming_style": {
+      "components": "PascalCase",
+      "functions": "camelCase",
+      "constants": "UPPER_SNAKE_CASE",
+      "files": "kebab-case"
+    },
+    "formatting": {
+      "indent": 2,
+      "quotes": "single",
+      "semicolons": true,
+      "trailing_commas": "es5"
+    },
+    "patterns": {
+      "state_management": "zustand",
+      "data_fetching": "react-query",
+      "styling": "tailwind"
+    }
+  },
+
+  "review_preferences": {
+    "focus_areas": ["security", "performance", "accessibility"],
+    "thoroughness": "high",
+    "comment_style": "inline"
+  },
+
+  "notification_preferences": {
+    "on_checkpoint": true,
+    "on_completion": true,
+    "on_error": true,
+    "channels": ["terminal"]
+  },
+
+  "learning_consent": {
+    "track_corrections": true,
+    "track_patterns": true,
+    "share_anonymized": false
+  },
+
+  "_schema_notes": {
+    "checkpoint_preferences": "User's checkpoint review preferences",
+    "workflow_preferences": "How user prefers to work",
+    "code_preferences": "Coding style and patterns",
+    "review_preferences": "Code review settings",
+    "notification_preferences": "When to notify",
+    "learning_consent": "Privacy settings for learning"
+  }
+}

package/.proagents/AGENTS.md

@@ -0,0 +1,55 @@
+# ProAgents Commands for Codex
+
+This project uses ProAgents - an AI-agnostic development workflow framework.
+
+## MANDATORY: Every pa: Command Flow
+
+### BEFORE Any pa: Command (Auto-Sync)
+
+**Read these files FIRST before doing anything:**
+
+```bash
+cat .proagents/worklog/_context.md      # Current state
+cat .proagents/changelog/_recent.md     # Recent changes
+tail -10 .proagents/activity.log        # Recent activity
+```
+
+**This applies to EVERY command:** `pa:fix`, `pa:feature`, `pa:test`, `pa:doc`, etc.
+
+### AFTER Any pa: Command (Auto-Log)
+
+**After EVERY file edit, IMMEDIATELY update these files:**
+
+1. `.proagents/changelog/_recent.md` - Prepend change summary
+2. `.proagents/changelog/modules/[module].md` - Based on file path
+3. `.proagents/worklog/_context.md` - Update current state
+
+Module detection: `src/api/*`→api, `src/auth/*`→auth, `src/components/*`→ui
+
+## Essential Commands
+
+| Command | Action |
+|---------|--------|
+| `pa:feature "name"` | Start new feature workflow |
+| `pa:fix "bug"` | Quick bug fix mode |
+| `pa:doc` | Documentation options |
+| `pa:qa` | Quality assurance checks |
+| `pa:test` | Run test workflow |
+| `pa:deploy` | Deployment preparation |
+| `pa:status` | Show current progress |
+
+## Full Command Reference
+
+For complete command list, see: `./.proagents/AI_INSTRUCTIONS.md`
+
+## On `pa:` Command
+
+1. Read the corresponding file from `./.proagents/prompts/` or `./.proagents/workflow-modes/`
+2. Follow the workflow instructions
+3. Use project config from `./.proagents/proagents.config.yaml`
+
+## Key Files
+
+- `./.proagents/AI_INSTRUCTIONS.md` - Complete command reference
+- `./.proagents/WORKFLOW.md` - Full 10-phase workflow
+- `./.proagents/prompts/` - Phase-specific prompts

package/.proagents/AI_INSTRUCTIONS.md

@@ -41,6 +41,8 @@ tail -10 .proagents/activity.log 2>/dev/null
 5. AI logs to activity.log                          ← LOG ACTIVITY
 ```
 
+**Note:** When updating `_recent.md` or `_context.md`, first read the corresponding `*.template.md` file to use the latest format. See "Using Template Reference Files" section below.
+
 ---
 
 ## CRITICAL PRINCIPLE: ALWAYS DO, NEVER JUST TELL
@@ -155,6 +157,37 @@ AI immediately updates these files (no user prompt needed):
 4. .proagents/changelog/modules/X.md   ← Based on file path
 ```
 
+### Using Template Reference Files
+
+**IMPORTANT:** Template files (`*.template.md`, `*.template.json`) provide the latest format for user data files.
+
+| User Data File (EDIT THIS) | Template Reference (READ ONLY) |
+|----------------------------|-------------------------------|
+| `changelog/_recent.md` | `changelog/_recent.template.md` |
+| `worklog/_context.md` | `worklog/_context.template.md` |
+| `worklog/ai-stats.json` | `worklog/ai-stats.template.json` |
+| `active-features/_index.json` | `active-features/_index.template.json` |
+| `.learning/global/user-preferences.json` | `.learning/global/user-preferences.template.json` |
+| `.learning/global/common-patterns.json` | `.learning/global/common-patterns.template.json` |
+
+**How to use:**
+1. **Read the template FIRST** before creating/updating user data files
+2. **Apply the template format** to user data (structure, fields, sections)
+3. **NEVER modify template files** - they are READ ONLY (updated by framework)
+
+**Why templates exist:**
+- Templates get updated when ProAgents upgrades (new fields, better structure)
+- User data files are preserved during upgrades (your content stays safe)
+- AI always has access to the latest format by reading templates
+
+**Common mistake to avoid:**
+```
+WRONG: Edit _recent.template.md directly
+RIGHT: Read _recent.template.md, then edit _recent.md using that format
+```
+
+---
+
 ### Auto-Log Format for _recent.md:
 
 After editing `src/auth/login.ts`, AI prepends to `_recent.md`:

package/.proagents/active-features/_index.template.json

@@ -0,0 +1,75 @@
+{
+  "_template_info": {
+    "description": "Template reference for _index.json schema",
+    "note": "DO NOT modify this file - it gets updated with ProAgents upgrades",
+    "usage": "AI reads this to understand expected schema for _index.json"
+  },
+
+  "$schema": "./schemas/index-schema.json",
+  "version": "1.0.0",
+  "last_updated": "2024-03-13T10:30:00Z",
+
+  "active_features": [
+    {
+      "id": "feature-user-auth",
+      "name": "User Authentication",
+      "started_at": "2024-03-10T09:00:00Z",
+      "started_by": "claude",
+      "priority": "high",
+      "progress": 45,
+      "phase": "implementation"
+    }
+  ],
+
+  "paused_features": [
+    {
+      "id": "feature-dark-mode",
+      "name": "Dark Mode",
+      "paused_at": "2024-03-12T14:00:00Z",
+      "reason": "Waiting for design review"
+    }
+  ],
+
+  "completed_features": [
+    {
+      "id": "feature-login",
+      "name": "Login Page",
+      "completed_at": "2024-03-08T16:30:00Z",
+      "duration_days": 3
+    }
+  ],
+
+  "conflicts": {
+    "active": [],
+    "resolved": [
+      {
+        "files": ["src/auth.ts"],
+        "features": ["feature-user-auth", "feature-login"],
+        "resolved_at": "2024-03-08T12:00:00Z"
+      }
+    ]
+  },
+
+  "statistics": {
+    "total_active": 1,
+    "total_paused": 1,
+    "total_completed": 1,
+    "average_completion_days": 3,
+    "conflict_rate": 0.1
+  },
+
+  "_schema": {
+    "active_features": {
+      "type": "array",
+      "items": {
+        "id": "string - Unique feature ID",
+        "name": "string - Human-readable name",
+        "started_at": "string - ISO timestamp",
+        "started_by": "string - AI platform that started",
+        "priority": "string - low/medium/high",
+        "progress": "number - 0-100 percentage",
+        "phase": "string - planning/design/implementation/testing/review"
+      }
+    }
+  }
+}

package/.proagents/changelog/_recent.template.md

@@ -0,0 +1,51 @@
+# Recent Changes - Template Reference
+
+> This is the FORMAT REFERENCE for `_recent.md`.
+> AI should read this template when creating/updating `_recent.md`.
+> DO NOT modify this file - it gets updated with ProAgents upgrades.
+
+---
+
+## Expected Structure
+
+```markdown
+# Recent Changes
+
+> Last 10 changes across all features/modules.
+> Auto-updated by AI after each code change.
+
+---
+
+## Latest Changes
+
+### YYYY-MM-DD - [Change Type]
+**Module:** [auto-detected from file path]
+**AI:** [Platform] ([model])
+**Files:** path/to/file.ts (+lines, -lines)
+**Summary:** Brief description of change
+
+---
+```
+
+## Entry Format
+
+Each entry should include:
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| Date | ISO format | `2024-03-13` |
+| Change Type | bug-fix, feature, refactor, docs | `bug-fix` |
+| Module | Auto-detected from path | `auth`, `api`, `ui` |
+| AI | Platform and model | `Claude (opus-4)` |
+| Files | Changed files with line counts | `src/auth.ts (+15, -3)` |
+| Summary | Brief description | `Fixed login timeout issue` |
+
+## Auto-Update Rules
+
+1. **Prepend** new entries (newest first)
+2. **Keep only last 10** entries
+3. **Auto-detect module** from file path:
+   - `src/api/*` → api
+   - `src/auth/*` → auth
+   - `src/components/*` → ui
+4. **Update after every file edit**

package/.proagents/worklog/_context.template.md

@@ -0,0 +1,82 @@
+# Current Project Context - Template Reference
+
+> This is the FORMAT REFERENCE for `_context.md`.
+> AI should read this template when creating/updating `_context.md`.
+> DO NOT modify this file - it gets updated with ProAgents upgrades.
+
+---
+
+## Expected Structure
+
+```markdown
+# Current Project Context
+
+> **For AI Assistants:** Read this file first to understand current state.
+> **Auto-updated** after each code change.
+
+Last Updated: [ISO timestamp]
+Last AI: [Platform (model)]
+
+---
+
+## Quick Summary
+<!-- AI auto-generates - keep under 5 lines -->
+```
+Last: [Last action]
+Active: [Feature name or "No active features"]
+Pending: [N] tasks
+Tests: [Passing/Failing/Unknown]
+Status: [Current status]
+```
+
+---
+
+## Test Status
+<!-- AI updates after running tests -->
+```
+Status: [Passing/Failing/Unknown]
+Last Run: [Timestamp]
+Failing: [Test names or "None"]
+```
+
+---
+
+## Feature Progress
+<!-- AI auto-calculates -->
+```
+[Feature name]: [X]% ([done]/[total] tasks)
+```
+
+---
+
+## Active Work
+[Current active features or tasks]
+
+---
+
+## Recent Changes
+[Last 3-5 changes]
+
+---
+
+## Pending Items
+[Outstanding tasks]
+
+---
+
+## Quick Stats
+| Metric | Value |
+|--------|-------|
+| Active Features | [N] |
+| Completed Today | [N] |
+| Open Issues | [N] |
+```
+
+## Auto-Update Rules
+
+1. **Update `Last Updated`** with current timestamp
+2. **Update `Last AI`** with current platform
+3. **Keep Quick Summary under 5 lines**
+4. **Update Test Status after test runs**
+5. **Update Recent Changes with last 3-5 items**
+6. **Calculate Feature Progress from active-features/**

package/.proagents/worklog/ai-stats.template.json

@@ -0,0 +1,54 @@
+{
+  "_template_info": {
+    "description": "Template reference for ai-stats.json schema",
+    "note": "DO NOT modify this file - it gets updated with ProAgents upgrades",
+    "usage": "AI reads this to understand expected schema for ai-stats.json"
+  },
+
+  "ai_platforms": {
+    "claude": {
+      "sessions": 0,
+      "tasks_completed": 0,
+      "files_modified": 0,
+      "reverts": 0,
+      "avg_session_minutes": 0,
+      "last_session": "2024-03-13T10:30:00Z"
+    },
+    "chatgpt": {
+      "sessions": 0,
+      "tasks_completed": 0,
+      "files_modified": 0,
+      "reverts": 0,
+      "avg_session_minutes": 0,
+      "last_session": null
+    }
+  },
+
+  "totals": {
+    "total_sessions": 0,
+    "total_tasks": 0,
+    "total_files_modified": 0,
+    "total_reverts": 0
+  },
+
+  "_schema": {
+    "ai_platforms": {
+      "type": "object",
+      "description": "Stats per AI platform",
+      "properties": {
+        "[platform_id]": {
+          "sessions": "number - Total sessions by this AI",
+          "tasks_completed": "number - Tasks completed",
+          "files_modified": "number - Files modified",
+          "reverts": "number - Changes reverted by user",
+          "avg_session_minutes": "number - Average session duration",
+          "last_session": "string|null - ISO timestamp of last session"
+        }
+      }
+    },
+    "totals": {
+      "type": "object",
+      "description": "Aggregated totals across all AIs"
+    }
+  }
+}