proagents 1.0.17 → 1.0.18

package/proagents/AI_INSTRUCTIONS.md

@@ -6,24 +6,237 @@ This project uses ProAgents - an AI-agnostic development workflow framework.
 
 **Multiple AI tools may work on this project simultaneously (Claude, Cursor, Gemini, Copilot, etc.). They do NOT share context.**
 
-Before executing ANY `pa:` command:
+### Before executing ANY `pa:` command:
 
-1. **ALWAYS read fresh state from files** - Never rely on previous knowledge or cached data
-2. **Key files to check:**
+1. **Read fresh state from files** - Never rely on previous knowledge
+2. **Read project context** - Read `./proagents/context.md` for persistent project knowledge
+3. **Check the activity log** - Read `./proagents/activity.log` to see recent AI actions
+4. **Key files to check:**
+   - `./proagents/context.md` - Persistent project context (READ FIRST!)
+   - `./proagents/activity.log` - Recent AI activity
+   - `./proagents/watchlist.yaml` - Files requiring confirmation before changes
    - `./proagents/proagents.config.yaml` - Project and platform config
    - `./proagents/active-features/` - Active feature status
    - `./CHANGELOG.md` - Recent changes
-   - `./RELEASE_NOTES.md` - Release history
-3. **If you detect conflicts or outdated state:**
+   - `./proagents/feedback.md` - Past corrections and preferences (LEARN FROM THESE!)
+
+### AI Feedback & Learning
+
+Before starting work, check `./proagents/feedback.md` for:
+- **Corrections**: Mistakes other AIs made - don't repeat them!
+- **Preferences**: How the user/team prefers things done
+- **Patterns**: What worked well in this project
+
+When you receive feedback or correction from the user:
+1. Log it in `./proagents/feedback.md` using `pa:feedback`
+2. Apply the learning to your current work
+3. Avoid making the same mistake again
+
+### File Watch List
+
+Before modifying ANY file, check `./proagents/watchlist.yaml`:
+
+- **critical**: Ask user for confirmation before modifying
+- **review_required**: Warn user and explain changes before modifying
+- **never_modify**: NEVER modify these files/patterns
+
+If a file matches a pattern, inform the user:
+> "This file is on the watch list (critical). Do you want me to proceed with the changes?"
+4. **If you detect conflicts or outdated state:**
    - Inform the user: "I notice [X] may have changed since my last context. Let me refresh..."
    - Re-read the relevant files before proceeding
-4. **After making changes:**
-   - Always update the relevant tracking files (status.json, config, etc.)
-   - Other AIs will read these files to stay in sync
+
+### After completing ANY `pa:` command:
+
+**ALWAYS log your activity** to `./proagents/activity.log`:
+
+```
+[TIMESTAMP] [AI_PLATFORM:MODEL] [COMMAND] Description
+```
+
+Example entries:
+```
+2024-03-06 15:10 [Claude:opus-4] [pa:feature] Started feature "user-auth"
+2024-03-06 15:12 [Cursor:gpt-4o] [pa:fix] Fixed login button bug in src/auth/login.ts
+2024-03-06 15:15 [Gemini:1.5-pro] [pa:doc] Updated API documentation
+2024-03-06 15:20 [Claude:sonnet-4] [pa:feature] Completed feature "user-auth"
+2024-03-06 15:25 [Copilot:gpt-4o] [pa:test] Added unit tests for auth module
+```
+
+**Include your model name** (e.g., opus-4, sonnet-4, gpt-4o, gemini-1.5-pro).
+Keep log entries concise (one line). Other AIs will read this to understand recent changes.
+
+### Command History
+
+Also log commands to `./proagents/history.log` with their results:
+
+```
+[TIMESTAMP] [AI:MODEL] COMMAND → RESULT
+```
+
+Example:
+```
+2024-03-06 15:10 [Claude:opus-4] pa:feature "user-auth" → Started
+2024-03-06 15:30 [Claude:opus-4] pa:feature "user-auth" → Completed
+2024-03-06 15:35 [Cursor:gpt-4o] pa:test → 15 passed, 2 failed
+2024-03-06 15:40 [Claude:sonnet-4] pa:fix "login bug" → Fixed
+```
+
+This helps track what commands were run and their outcomes.
+
+### Lock File for Active Work
+
+When starting a major task (feature, large fix, refactoring), create a lock file at `./proagents/.lock`:
+
+```yaml
+locked_by: Claude        # Your AI platform
+model: opus-4            # Your model name
+started: 2024-03-06T15:10:00
+task: "pa:feature user-auth"
+description: "Implementing user authentication with JWT"
+files:
+  - src/auth/*
+  - src/api/auth.ts
+expires: 2024-03-06T17:10:00  # Auto-expires after 2 hours
+```
+
+**Before starting major work:**
+1. Check if `./proagents/.lock` exists
+2. If locked by another AI, inform user: "Project is locked by [AI] working on [task]. Wait or ask user to override."
+3. If lock is expired (past `expires` time), you may delete it and proceed
+
+**After completing work:**
+1. Delete the `./proagents/.lock` file
+2. Log completion in activity.log
+
+### Conflict Detection
+
+Before modifying any file, check for potential conflicts:
+
+1. **Read activity.log** - See if another AI recently modified the same file
+2. **Check lock file** - See if another AI is working on related files
+3. **Look for patterns** like:
+   ```
+   2024-03-06 15:10 [Cursor:gpt-4o] Modified src/auth/login.ts
+   ```
+
+**If you detect a potential conflict:**
+
+Warn the user:
+> "I notice [Other AI] modified `src/auth/login.ts` 10 minutes ago.
+> There may be uncommitted changes. Should I:
+> 1. Proceed anyway (may overwrite their changes)
+> 2. Wait and check with them first
+> 3. Show me the recent changes to this file"
+
+**After modifying files, always log:**
+```
+[TIMESTAMP] [AI:MODEL] [MODIFIED] file1.ts, file2.ts
+```
+
+This helps other AIs detect conflicts.
+
+**Lock commands:**
+| Command | Action |
+|---------|--------|
+| `pa:lock` | Show current lock status |
+| `pa:lock-release` | Release lock (if you hold it) |
+| `pa:lock-override` | Force release lock (requires user confirmation) |
+
+### Handoff Notes
+
+When ending a session or switching to another AI, create handoff notes at `./proagents/handoff.md`:
+
+**For `pa:handoff`** - Create/update handoff notes:
+```markdown
+# AI Handoff Notes
+Updated: 2024-03-06 15:30 by Claude (opus-4)
+
+## Current Status
+- **Working on:** User authentication feature
+- **Phase:** Implementation (5 of 9)
+- **Branch:** feature/user-auth
+
+## Completed
+- [x] Login UI component
+- [x] JWT token generation
+- [x] Password hashing setup
+
+## In Progress
+- [ ] Password reset flow (50% done)
+- [ ] Email verification endpoint
+
+## Blocked / Needs Attention
+- Need API endpoint for sending emails (waiting on backend team)
+- Rate limiting not yet implemented
+
+## Files Modified
+- src/auth/login.tsx
+- src/auth/jwt.ts
+- src/api/auth.ts
+
+## Next Steps
+1. Complete password reset flow
+2. Add email verification
+3. Write tests for auth module
+
+## Notes for Next AI
+- Using bcrypt for password hashing (see src/auth/hash.ts)
+- JWT secret is in .env.local
+- Test user: test@example.com / password123
+```
+
+**For `pa:handoff-read`** - Read and summarize current handoff notes before starting work.
+
+### Session Summary
+
+**For `pa:session-end`** - Generate and save a session summary to `./proagents/sessions/`:
+
+```markdown
+# Session Summary
+Date: 2024-03-06 15:00-17:30
+AI: Claude (opus-4)
+
+## What Was Done
+- Implemented user authentication feature
+- Fixed 3 bugs in login flow
+- Added unit tests for auth module
+
+## Files Modified
+- src/auth/login.tsx (created)
+- src/auth/jwt.ts (created)
+- src/api/auth.ts (modified)
+- tests/auth.test.ts (created)
+
+## Commands Executed
+- pa:feature "user-auth" → Completed
+- pa:test → 15 passed, 0 failed
+- pa:doc → Updated API docs
+
+## Issues Encountered
+- Rate limiting not yet implemented (deferred)
+
+## Next Session Should
+1. Implement rate limiting
+2. Add password reset flow
+3. Write integration tests
+```
+
+Save to: `./proagents/sessions/YYYY-MM-DD-HHMMSS.md`
 
 ## Command Recognition
 
-When the user types commands starting with `pa:`, recognize and execute them:
+When the user types commands starting with `pa:`, recognize and execute them.
+
+### Quick Aliases
+| Alias | Expands To |
+|-------|------------|
+| `pa:f` | `pa:feature` |
+| `pa:s` | `pa:status` |
+| `pa:h` | `pa:help` |
+| `pa:d` | `pa:doc` |
+| `pa:t` | `pa:test` |
+| `pa:q` | `pa:qa` |
 
 ### Initialization
 | Command | Action |
@@ -156,11 +369,43 @@ For `pa:ai-sync`:
 | `pa:config-setup` | Interactive config wizard |
 | `pa:config-customize` | Copy templates to customize |
 
+### Custom Commands
+
+Check `./proagents/custom-commands.yaml` for project-specific commands.
+
+Built-in custom commands:
+| Command | Action |
+|---------|--------|
+| `pa:standup` | Generate daily standup summary |
+| `pa:sprint-review` | Generate sprint review |
+| `pa:tech-debt` | Scan and document technical debt |
+| `pa:security-scan` | Run security checklist |
+
+Users can add their own commands in `custom-commands.yaml`.
+
 ### Utilities
 | Command | Action |
 |---------|--------|
 | `pa:uninstall` | Remove ProAgents from project |
 
+### Collaboration (Multi-AI)
+| Command | Action |
+|---------|--------|
+| `pa:activity` | Show recent AI activity log |
+| `pa:lock` | Show current lock status |
+| `pa:lock-release` | Release lock (if you hold it) |
+| `pa:lock-override` | Force release lock (requires user confirmation) |
+| `pa:handoff` | Create handoff notes for other AIs |
+| `pa:handoff-read` | Read latest handoff notes |
+| `pa:session-end` | Generate session summary before ending |
+| `pa:session-history` | Show recent session summaries |
+| `pa:decision "title"` | Log an architectural/technical decision |
+| `pa:decisions` | Show all logged decisions |
+| `pa:error "description"` | Log an error and its solution |
+| `pa:errors` | Show logged errors (search for solutions) |
+| `pa:feedback "description"` | Log feedback/correction for AI learning |
+| `pa:feedback-list` | Show all feedback (learn from past corrections) |
+
 ## How to Execute Commands
 
 When user types a `pa:` command:

package/proagents/PROAGENTS.md

@@ -2,7 +2,10 @@
 
 Execute these commands when user types them (prefix: `pa:`):
 
-> **Multi-AI Note:** Multiple AIs may work on this project. Always read fresh state from files before executing commands. See `./proagents/AI_INSTRUCTIONS.md` for details.
+## Quick Aliases
+`pa:f` → feature | `pa:s` → status | `pa:h` → help | `pa:d` → doc | `pa:t` → test | `pa:q` → qa
+
+> **Multi-AI Note:** Multiple AIs may work on this project. Always read `./proagents/activity.log` before executing commands, and log your actions after completing them.
 
 ## Commands
 
@@ -21,6 +24,27 @@ Execute these commands when user types them (prefix: `pa:`):
 | `pa:ai-add` | Show platform options, create AI instruction files |
 | `pa:ai-remove` | Show installed platforms, remove selected files |
 | `pa:ai-sync` | Sync config with existing files (fix mismatches) |
+| `pa:activity` | Show recent AI activity from `./proagents/activity.log` |
+| `pa:lock` | Show lock status, check if another AI is working |
+| `pa:lock-release` | Release your lock after completing work |
+| `pa:handoff` | Create handoff notes → `./proagents/handoff.md` |
+| `pa:handoff-read` | Read handoff notes before starting work |
+| `pa:session-end` | Generate session summary → `./proagents/sessions/` |
+| `pa:decision "title"` | Log architectural decision → `./proagents/decisions.md` |
+| `pa:error "desc"` | Log error & solution → `./proagents/errors.md` |
+| `pa:feedback "desc"` | Log feedback for AI learning → `./proagents/feedback.md` |
+| `pa:standup` | Generate daily standup summary |
+| `pa:tech-debt` | Scan for technical debt |
+
+## Key Files to Read
+
+| File | Purpose |
+|------|---------|
+| `./proagents/context.md` | Persistent project context (READ FIRST!) |
+| `./proagents/feedback.md` | Past corrections - don't repeat mistakes |
+| `./proagents/watchlist.yaml` | Files requiring confirmation before changes |
+| `./proagents/errors.md` | Past errors and solutions |
+| `./proagents/decisions.md` | Architectural decisions and reasoning |
 
 ## Feature Workflow
 

package/proagents/activity.log

@@ -0,0 +1,11 @@
+# ProAgents Activity Log
+# Format: [TIMESTAMP] [AI_PLATFORM:MODEL] [COMMAND] Description
+# This file helps multiple AIs stay in sync by logging their actions.
+#
+# Example:
+# 2024-03-06 15:10 [Claude:opus-4] [pa:feature] Started feature "user-auth"
+# 2024-03-06 15:12 [Cursor:gpt-4o] [pa:fix] Fixed login button bug
+# 2024-03-06 15:15 [Gemini:1.5-pro] [pa:doc] Updated API documentation
+#
+# --- Activity Log Start ---
+

package/proagents/context.md

@@ -0,0 +1,39 @@
+# Project Context
+
+> This file contains persistent context that ALL AIs should read at the start of every session.
+> Update this file with important information that should be remembered across sessions.
+
+## Project Overview
+<!-- Describe what this project does -->
+
+
+## Key Decisions
+<!-- Important architectural or technical decisions -->
+
+
+## Current Focus
+<!-- What is the team currently working on? -->
+
+
+## Important Notes
+<!-- Gotchas, workarounds, things to remember -->
+
+
+## Do NOT Touch
+<!-- Files or areas that should not be modified -->
+
+
+## Credentials & Secrets
+<!-- WHERE secrets are stored (never the actual values!) -->
+- Environment variables: `.env.local`
+- API keys: Never commit to git
+
+
+## Useful Commands
+<!-- Project-specific commands that are helpful -->
+```bash
+# Example: npm run dev
+```
+
+---
+*Keep this file updated. All AIs read it before starting work.*

package/proagents/custom-commands.yaml

@@ -0,0 +1,59 @@
+# Custom Commands
+# Define your own pa: commands that AI will recognize and execute.
+#
+# Format:
+# command_name:
+#   description: "What this command does"
+#   steps:
+#     - "Step 1 instruction"
+#     - "Step 2 instruction"
+#   files_to_read: []  # Optional: files AI should read first
+#   output: "file.md"  # Optional: where to save output
+
+# Example custom commands (uncomment to use):
+
+# pa:standup
+standup:
+  description: "Generate daily standup summary"
+  steps:
+    - "Read ./proagents/activity.log for today's entries"
+    - "Read ./proagents/active-features/ for current work"
+    - "Summarize: What was done yesterday, what's planned today, any blockers"
+  output: "stdout"
+
+# pa:sprint-review
+sprint_review:
+  description: "Generate sprint review summary"
+  steps:
+    - "Read all session summaries from ./proagents/sessions/"
+    - "Read ./CHANGELOG.md for completed features"
+    - "Generate sprint review with completed items, metrics, and highlights"
+  output: "./proagents/sprint-reviews/YYYY-MM-DD.md"
+
+# pa:tech-debt
+tech_debt:
+  description: "Scan for and document technical debt"
+  steps:
+    - "Search for TODO, FIXME, HACK comments in codebase"
+    - "Check for deprecated dependencies"
+    - "Document findings in ./proagents/tech-debt.md"
+  output: "./proagents/tech-debt.md"
+
+# pa:security-scan
+security_scan:
+  description: "Run security checklist"
+  steps:
+    - "Read ./proagents/checklists/security.md"
+    - "Check for hardcoded secrets in code"
+    - "Review authentication/authorization code"
+    - "Generate security report"
+  files_to_read:
+    - "./proagents/security/owasp-checklist.md"
+  output: "./proagents/security-report.md"
+
+# Add your own commands below:
+# my_command:
+#   description: "What it does"
+#   steps:
+#     - "Step 1"
+#     - "Step 2"

package/proagents/decisions.md

@@ -0,0 +1,43 @@
+# Decision Log
+
+> Track important architectural and technical decisions made during development.
+> This helps future AIs (and humans) understand WHY certain choices were made.
+
+## How to Log Decisions
+
+Use `pa:decision "title"` or add manually:
+
+```markdown
+### [DATE] Decision Title
+**Status:** Accepted | Rejected | Superseded
+**Decided by:** AI/Human name
+**Context:** Why was this decision needed?
+**Decision:** What was decided?
+**Alternatives Considered:**
+- Option A: ...
+- Option B: ...
+**Consequences:** What are the implications?
+```
+
+---
+
+## Decisions
+
+<!-- Add new decisions below this line -->
+
+### [TEMPLATE] Example Decision
+**Status:** Accepted
+**Decided by:** Claude (opus-4)
+**Context:** Needed to choose a state management solution for the React app.
+**Decision:** Use Zustand over Redux
+**Alternatives Considered:**
+- Redux: Too much boilerplate for our needs
+- Context API: Not powerful enough for complex state
+- Jotai: Good but team less familiar with it
+**Consequences:**
+- Simpler codebase
+- Faster development
+- Team needs to learn Zustand patterns
+
+---
+

package/proagents/errors.md

@@ -0,0 +1,36 @@
+# Error Tracker
+
+> Log errors encountered during development and their solutions.
+> This helps AIs avoid repeating the same mistakes and find solutions faster.
+
+## How to Log Errors
+
+Use `pa:error "description"` or add manually when you encounter and solve an error.
+
+---
+
+## Error Log
+
+<!-- Add new errors below this line, newest first -->
+
+### [TEMPLATE] Example Error
+**Date:** 2024-03-06
+**Logged by:** Claude (opus-4)
+**Error:**
+```
+TypeError: Cannot read property 'map' of undefined
+```
+**File:** src/components/UserList.tsx:42
+**Cause:** API returned null instead of empty array when no users exist
+**Solution:**
+```typescript
+// Before
+users.map(user => ...)
+
+// After
+(users || []).map(user => ...)
+```
+**Prevention:** Always provide default values for arrays from API responses
+
+---
+

package/proagents/feedback.md

@@ -0,0 +1,49 @@
+# AI Feedback Log
+
+> Track corrections and feedback to help AIs learn from mistakes.
+> When an AI makes a mistake or user provides correction, log it here.
+
+## How to Log Feedback
+
+Use `pa:feedback "description"` or add manually.
+
+Types:
+- **correction**: AI did something wrong, here's the fix
+- **preference**: User prefers things done a certain way
+- **praise**: AI did something well (reinforcement)
+
+---
+
+## Feedback Log
+
+<!-- Add new feedback below, newest first -->
+
+### [TEMPLATE] Example Correction
+**Date:** 2024-03-06
+**Type:** correction
+**AI:** Claude (opus-4)
+**Context:** AI generated a React component
+**Issue:** Used class components instead of functional components
+**Correction:** This project uses functional components with hooks only. Never use class components.
+**Apply to:** All React components in this project
+
+---
+
+### [TEMPLATE] Example Preference
+**Date:** 2024-03-06
+**Type:** preference
+**AI:** Cursor (gpt-4o)
+**Context:** Code style
+**Preference:** Always use explicit return types in TypeScript functions
+**Example:**
+```typescript
+// Don't do this
+const add = (a: number, b: number) => a + b;
+
+// Do this
+const add = (a: number, b: number): number => a + b;
+```
+**Apply to:** All TypeScript files
+
+---
+

package/proagents/handoff.md

@@ -0,0 +1,33 @@
+# AI Handoff Notes
+
+> This file is used to pass context between AI assistants working on this project.
+> Update this file when ending a session using `pa:handoff`.
+> Read this file when starting work using `pa:handoff-read`.
+
+---
+
+## Current Status
+- **Working on:** (describe current task)
+- **Phase:** (which workflow phase)
+- **Branch:** (git branch if applicable)
+
+## Completed
+- [ ] (list completed items)
+
+## In Progress
+- [ ] (list items currently being worked on with % progress)
+
+## Blocked / Needs Attention
+- (list any blockers or items needing user input)
+
+## Files Modified
+- (list recently modified files)
+
+## Next Steps
+1. (prioritized list of what to do next)
+
+## Notes for Next AI
+- (any important context, credentials locations, gotchas, etc.)
+
+---
+*Last updated: (timestamp) by (AI platform:model, e.g., Claude:opus-4)*

package/proagents/history.log

@@ -0,0 +1,12 @@
+# ProAgents Command History
+# Format: [TIMESTAMP] [AI:MODEL] COMMAND → RESULT
+# Track which commands were executed and their outcomes
+#
+# Example:
+# 2024-03-06 15:10 [Claude:opus-4] pa:feature "user-auth" → Started
+# 2024-03-06 15:30 [Claude:opus-4] pa:feature "user-auth" → Completed
+# 2024-03-06 15:35 [Cursor:gpt-4o] pa:test → 15 passed, 2 failed
+# 2024-03-06 15:40 [Claude:sonnet-4] pa:fix "login bug" → Fixed
+#
+# --- Command History Start ---
+

package/proagents/sessions/README.md

@@ -0,0 +1,5 @@
+# Session Summaries
+
+This folder contains session summaries generated by `pa:session-end`.
+
+Each file is named: `YYYY-MM-DD-HHMMSS.md`

package/proagents/watchlist.yaml

@@ -0,0 +1,39 @@
+# File Watch List
+# Files and patterns that require CONFIRMATION before AI modifies them.
+# AI must ask user before changing these files.
+
+# Critical files that should never be auto-modified
+critical:
+  - ".env*"                    # Environment variables
+  - "*.config.js"              # Configuration files
+  - "*.config.ts"
+  - "package.json"             # Dependencies
+  - "package-lock.json"
+  - "yarn.lock"
+  - "pnpm-lock.yaml"
+  - "tsconfig.json"            # TypeScript config
+  - "docker-compose*.yml"      # Docker configs
+  - "Dockerfile*"
+  - ".github/workflows/*"      # CI/CD pipelines
+  - "database/migrations/*"    # Database migrations
+
+# Files that need careful review before changes
+review_required:
+  - "src/lib/*"                # Core libraries
+  - "src/utils/*"              # Utility functions
+  - "src/config/*"             # App configuration
+  - "src/middleware/*"         # Middleware
+  - "src/auth/*"               # Authentication code
+
+# Patterns to never modify (absolute protection)
+never_modify:
+  - ".git/*"
+  - "node_modules/*"
+  - "dist/*"
+  - "build/*"
+  - ".next/*"
+  - "*.lock"
+  - "*.log"
+
+# Custom patterns (add your own)
+custom: []