proagents 1.6.9 → 1.6.11

package/.proagents/AI_INSTRUCTIONS.md

@@ -10,9 +10,8 @@ This project uses ProAgents - an AI-agnostic development workflow framework.
 |-----------------|----------------|
 | "To run tests: `npm test`" | Actually run `npm test` and show results |
 | "Create tests in `__tests__/`" | Actually create the test files |
-| "Install dependencies with `npm install`" | Actually run `npm install` |
 | "You can fix this by..." | Actually fix it |
-| "Next steps: 1. Create... 2. Run..." | Do all steps automatically |
+| "Next steps: 1. Create..." | Do all steps automatically |
 
 **Rules:**
 1. **Execute, don't instruct** - Run commands, don't tell user to run them
@@ -26,3399 +25,545 @@ This project uses ProAgents - an AI-agnostic development workflow framework.
 - Action is destructive and needs explicit user confirmation
 - Action is outside the project scope (external services, deployments)
 
-## CRITICAL: Multi-AI Environment
+---
 
-**Multiple AI tools may work on this project simultaneously (Claude, Cursor, Gemini, Copilot, etc.). They do NOT share context.**
+## Multi-AI Environment
 
-### Before executing ANY `pa:` command:
+**Multiple AI tools may work on this project simultaneously. They do NOT share context.**
 
-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
-   - `./.proagents/feedback.md` - Past corrections and preferences (LEARN FROM THESE!)
+### Before ANY `pa:` command:
 
-### AI Feedback & Learning
+1. **Read project context** - `./.proagents/context.md`
+2. **Check activity log** - `./.proagents/activity.log`
+3. **Check feedback** - `./.proagents/feedback.md` (learn from past corrections!)
+4. **Check watchlist** - `./.proagents/watchlist.yaml` (files requiring confirmation)
 
-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
+### After ANY `pa:` command:
 
-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
-
-### After completing ANY `pa:` command:
-
-**ALWAYS log your activity** to `./.proagents/activity.log`:
+**MANDATORY: Log every command to `./.proagents/activity.log`**
 
+AI must append to activity.log (create if not exists):
 ```
-[TIMESTAMP] [AI_PLATFORM:MODEL] [COMMAND] Description
+[TIMESTAMP] [AI:MODEL] [COMMAND] Result/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
+2024-03-06 15:15 [Claude:opus-4] [pa:analyze] Analyzed codebase - found 45 files
+2024-03-06 15:30 [Cursor:gpt-4] [pa:test] Ran 12 tests - all passed
+2024-03-06 16:00 [Gemini:pro] [pa:logs] Captured 50 log entries, found 2 errors
 ```
 
-**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.
+**How to log (AI executes this after EVERY pa: command):**
+```bash
+echo "[$(date '+%Y-%m-%d %H:%M')] [Claude:opus-4] [pa:feature] Started user-auth" >> .proagents/activity.log
+```
 
-### Command History
+**CRITICAL:**
+- Log AFTER the "--- Activity Log Start ---" marker
+- Use YOUR AI platform name (Claude, Cursor, Gemini, etc.)
+- Log EVERY pa: command, not just major ones
 
-Also log commands to `./.proagents/history.log` with their results:
+### Lock File
 
-```
-[TIMESTAMP] [AI:MODEL] COMMAND → RESULT
+For major tasks, create `./.proagents/.lock`:
+```yaml
+locked_by: Claude
+model: opus-4
+task: "pa:feature user-auth"
+expires: 2024-03-06T17:10:00
 ```
 
-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
-```
+Check lock before starting. Delete when done.
 
-This helps track what commands were run and their outcomes.
+---
 
-### Lock File for Active Work
+## CRITICAL: Auto-Log Every Code Change
 
-When starting a major task (feature, large fix, refactoring), create a lock file at `./.proagents/.lock`:
+**AI MUST automatically log EVERY code change. This is NOT optional.**
+
+### After EVERY file edit/create/delete:
+
+AI immediately updates these files (no user prompt needed):
 
-```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
+```
+1. .proagents/changelog/_recent.md     ← Prepend change summary
+2. .proagents/worklog/_context.md      ← Update current state
+3. .proagents/changelog/features/X.md  ← If working on feature
+4. .proagents/changelog/modules/X.md   ← Based on file path
 ```
 
-**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
+### Auto-Log Format for _recent.md:
 
-**After completing work:**
-1. Delete the `./.proagents/.lock` file
-2. Log completion in activity.log
+After editing `src/auth/login.ts`, AI prepends to `_recent.md`:
 
-### Conflict Detection
+```markdown
+### [DATE] - Code Change
+**Module:** auth
+**AI:** [Platform] ([model])
+**Files:** src/auth/login.ts (+15, -3)
+**Summary:** Added email validation to login function
 
-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
-   ```
+### Module Detection (Auto):
 
-**If you detect a potential conflict:**
+| File Path Changed | Update This Changelog |
+|-------------------|----------------------|
+| `src/api/*`, `routes/*` | `changelog/modules/api.md` |
+| `src/auth/*` | `changelog/modules/auth.md` |
+| `src/components/*` | `changelog/modules/ui.md` |
+| `src/services/*` | `changelog/modules/services.md` |
+| `src/utils/*`, `lib/*` | `changelog/modules/utils.md` |
+| `tests/*`, `*.test.*` | `changelog/modules/tests.md` |
+| `src/database/*`, `models/*` | `changelog/modules/database.md` |
 
-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"
+### Example - AI Edits a File:
 
-**After modifying files, always log:**
-```
-[TIMESTAMP] [AI:MODEL] [MODIFIED] file1.ts, file2.ts
 ```
+User: Fix the login validation bug
 
-This helps other AIs detect conflicts.
+AI: [Reads file, makes edit to src/auth/login.ts]
 
-**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) |
+AI: [AUTOMATICALLY does these updates - no user prompt:]
 
-### Handoff Notes
+1. Prepends to .proagents/changelog/_recent.md:
+   ### 2024-03-11 - Bug Fix
+   **Module:** auth
+   **AI:** Claude (opus-4)
+   **Files:** src/auth/login.ts (+5, -2)
+   **Summary:** Fixed null check in email validation
 
-When ending a session or switching to another AI, create handoff notes at `./.proagents/handoff.md`:
+2. Updates .proagents/changelog/modules/auth.md (creates if not exists)
 
-**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
-```
+3. Updates .proagents/worklog/_context.md with latest change
 
-**For `pa:handoff-read`** - Read and summarize current handoff notes before starting work.
+AI: "Fixed the login validation bug in src/auth/login.ts"
+```
 
-### Session Summary
+### Log Rollbacks & Corrections Too:
 
-**For `pa:session-end`** - Generate and save a session summary to `./.proagents/sessions/`:
+When removing or correcting previous changes, also log:
 
 ```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
+### YYYY-MM-DD - Rollback/Correction
+**Module:** auth
+**AI:** Claude (opus-4)
+**Files:** src/auth/login.ts (-20 lines removed)
+**Summary:** Reverted email validation - caused login failures
+**Reason:** Previous change broke existing functionality
+
+---
 ```
 
-Save to: `./.proagents/sessions/YYYY-MM-DD-HHMMSS.md`
-
-## Command Recognition
+### WRONG vs RIGHT:
 
-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` |
-| `pa:a` | `pa:analyze` |
-| `pa:r` | `pa:requirements` |
-| `pa:p` | `pa:plan` |
-| `pa:i` | `pa:implement` |
+| WRONG | RIGHT |
+|-------|-------|
+| Edit file → Tell user "done" | Edit file → Update changelogs → Tell user "done" |
+| Wait for pa:changelog command | Auto-update after every change |
+| Only log at session end | Log immediately after each change |
+| Undo changes silently | Log rollback with reason |
 
-### Initialization
-| Command | Action |
-|---------|--------|
-| `pa:init` | Initialize ProAgents in project |
-| `pa:help` | Show all available commands |
-| `pa:status` | Show current progress |
+---
 
-**How to execute Initialization commands:**
+## Cross-AI Session Tracking (MANDATORY)
 
-For `pa:status` (or `pa:s`):
-1. **Read the ACTUAL data** from `./.proagents/active-features/_index.json`
-2. **Check if empty** - if `active_features`, `paused_features`, and `completed_features` are all empty arrays:
-   ```
-   Project Status
-   ══════════════
+**Every AI must track work for other AIs to continue.**
 
-   No features currently tracked.
+### On Session Start (pa:sync):
 
-   Start a new feature with:
-   → pa:feature-start "feature name"
+AI reads these files to get context:
+```bash
+cat .proagents/worklog/_context.md        # Current state
+cat .proagents/changelog/_recent.md       # Recent changes
+ls -t .proagents/worklog/*.md | head -3   # Last 2 session logs
+cat .proagents/active-features/_index.json # Active features
+```
 
-   Or quick bug fix:
-   → pa:fix "bug description"
-   ```
+### During Work:
 
-3. **If has features**, show real status:
-   ```
-   Project Status
-   ══════════════
+After ANY code modification, AI must update:
 
-   Active Features: [count]
-   ────────────────────────
-   • [feature-name] - [phase] ([progress]%)
-     Branch: [branch]
-     Last updated: [timestamp]
+1. **Session Log** (`worklog/YYYY-MM-DD-[ai]-[num].md`)
+   - Tasks completed
+   - Files changed
+   - Decisions made
 
-   Paused Features: [count]
-   ────────────────────────
-   • [feature-name] - Paused: [reason]
+2. **Feature Changelog** (`changelog/features/[name].md`)
+   - If working on a feature
 
-   Completed Features: [count]
-   ──────────────────────────
-   • [feature-name] - Completed [date]
+3. **Module Changelog** (`changelog/modules/[name].md`)
+   - Based on file paths modified
 
-   Next Steps:
-   → [suggested action based on current state]
-   ```
+### On Session End (pa:session-end):
 
-4. **NEVER show example/template data** - only show what's actually in the JSON file
+AI updates:
+```bash
+# 1. Update context summary
+# Edit .proagents/worklog/_context.md with current state
 
-### Feature Development
-| Command | Action |
-|---------|--------|
-| `pa:feature "name"` | Start new feature workflow |
-| `pa:feature-start "name"` | Start new feature |
-| `pa:feature-status` | Check feature status |
-| `pa:feature-list` | List all features |
-| `pa:feature-complete` | Mark feature complete |
-| `pa:fix "description"` | Quick bug fix mode |
-
-### Workflow Phase Commands
-Run individual phases of the development workflow:
-
-| Command | Phase | Action |
-|---------|-------|--------|
-| `pa:analyze` | Analysis | Deep codebase analysis - structure, patterns, dependencies |
-| `pa:analyze-full` | Analysis | Comprehensive analysis with full depth |
-| `pa:analyze-quick` | Analysis | Quick overview analysis |
-| `pa:requirements` | Requirements | Gather and document feature requirements |
-| `pa:requirements "feature"` | Requirements | Requirements for specific feature |
-| `pa:design` | Design | UI/UX and architecture design |
-| `pa:design-ui` | Design | Focus on UI/UX design |
-| `pa:design-arch` | Design | Focus on architecture design |
-| `pa:plan` | Planning | Create implementation plan |
-| `pa:plan "feature"` | Planning | Plan specific feature implementation |
-| `pa:implement` | Implementation | Execute implementation phase |
-| `pa:implement-continue` | Implementation | Continue paused implementation |
-
-**How to execute Workflow Phase commands:**
-
-For `pa:analyze`:
-1. Read `./.proagents/prompts/01-analysis.md` for analysis workflow
-2. Scan project structure, dependencies, patterns
-3. Cache results in `./.proagents/cache/`
-4. Output analysis report
-
-For `pa:requirements`:
-1. Read `./.proagents/prompts/02-requirements.md`
-2. If feature name provided, create `./.proagents/active-features/feature-{name}/requirements.md`
-3. Gather user stories, acceptance criteria, constraints
-4. Output requirements document
-
-For `pa:design`:
-1. Read `./.proagents/prompts/03-ui-design.md`
-2. Check for design inputs (Figma, sketches, exports)
-3. Create component specifications
-4. Output design document
-
-For `pa:plan`:
-1. Read `./.proagents/prompts/04-planning.md`
-2. Create implementation plan with task breakdown
-3. Identify dependencies and risks
-4. Save to `./.proagents/active-features/feature-{name}/implementation-plan.md`
-
-For `pa:implement`:
-1. Read `./.proagents/prompts/05-implementation.md`
-2. Follow existing project patterns
-3. Implement code changes
-4. Log progress to activity.log
-
-### Documentation Commands
-| Command | Action |
-|---------|--------|
-| `pa:doc` | Show documentation options |
-| `pa:doc-full` | Generate full project documentation |
-| `pa:doc-moderate` | Generate balanced documentation |
-| `pa:doc-lite` | Generate quick reference |
-| `pa:doc-module [name]` | Document specific module |
-| `pa:doc-file [path]` | Document specific file |
-| `pa:doc-api` | Generate API documentation |
-| `pa:readme` | Generate/update README |
-| `pa:changelog` | Update CHANGELOG.md |
-| `pa:release` | Generate release notes |
-| `pa:release [version]` | Version-specific release notes |
-
-### Quality & Testing
-| Command | Action |
-|---------|--------|
-| `pa:qa` | Run quality assurance checks |
-| `pa:test` | Run test workflow |
-| `pa:review` | Code review workflow |
+# 2. Update recent changes
+# Prepend to .proagents/changelog/_recent.md
 
-### Deployment
-| Command | Action |
-|---------|--------|
-| `pa:deploy` | Deployment preparation |
-| `pa:rollback` | Rollback procedures |
+# 3. Finalize session log with "Next Steps"
 
-**How to execute Quality, Testing & Deployment commands (FULL AUTOMATION):**
+# 4. Log to activity.log
+echo "[$(date '+%Y-%m-%d %H:%M')] [AI:model] [pa:session-end] Session complete" >> .proagents/activity.log
+```
 
-For `pa:test`:
-1. **Detect project type** and test framework (Jest, Vitest, Mocha, Pytest, etc.)
-2. **Auto-install missing test dependencies** (no confirmation)
-3. **Run all tests:**
-   ```
-   Running tests...
-   ✓ 45 passed
-   ✗ 3 failed
-   ```
-4. **Auto-fix ALL failures** (no confirmation):
-   ```
-   AUTO-FIX: Fixing 3 failed tests...
-
-   Fix 1/3: UserService.test.ts
-   ─────────────────────────────
-   Root cause: Expected 'user' but got 'undefined'
-   Fixing: src/services/UserService.ts:23
-   → Added null check before return
-   Re-running test... ✓ PASSED
-   ```
-5. **Loop until all pass** or fix is impossible
-6. **Generate report** at `.proagents/test-reports/`
-
-For `pa:qa`:
-1. **Run ALL quality checks** automatically:
-   - Linting (ESLint, Prettier)
-   - Type checking (TypeScript)
-   - Security scan (npm audit)
-   - Dead code detection
-2. **Auto-fix ALL issues** (no confirmation):
-   ```
-   Running QA checks...
+### Module Auto-Detection:
 
-   ESLint: 12 errors found
-   AUTO-FIX: Fixing...
-   → Fixed 12/12 errors
+| File Path | Module Changelog |
+|-----------|------------------|
+| `src/api/*` | `modules/api.md` |
+| `src/auth/*` | `modules/auth.md` |
+| `src/components/*` | `modules/ui.md` |
+| `src/services/*` | `modules/services.md` |
+| `tests/*` | `modules/tests.md` |
 
-   TypeScript: 3 type errors
-   AUTO-FIX: Fixing...
-   → src/api/user.ts:15 - Added type annotation
-   → src/utils/date.ts:8 - Fixed return type
-   → src/hooks/useAuth.ts:22 - Added null check
+### Conflict Check (Before Editing):
 
-   Prettier: 28 files need formatting
-   AUTO-FIX: Formatting... ✓ Done
+Before modifying any file, AI checks if another AI recently changed it:
 
-   npm audit: 2 vulnerabilities
-   AUTO-FIX: Running npm audit fix... ✓ Fixed
-   ```
-3. **Re-run checks** to verify all fixed
-4. **Only report issues that cannot be auto-fixed**
-
-For `pa:fix "description"`:
-1. **Understand the bug** from description
-2. **Find the root cause** automatically
-3. **Apply the fix** directly (no confirmation)
-4. **Run related tests** to verify fix works
-5. **Auto-fix any test failures** caused by the fix
-6. **Commit when done** (if git is configured)
-   ```
-   pa:fix "login button not working"
+```bash
+grep "src/auth/login.ts" .proagents/changelog/_recent.md
+```
 
-   Finding root cause...
-   → Found: onClick handler missing in LoginButton.tsx:34
+If found, warn user:
+```
+⚠️ File src/auth/login.ts was modified by Gemini 2 hours ago.
+Review changes before editing? [Y/n]
+```
 
-   Applying fix...
-   → Added: onClick={() => handleLogin()}
+### File-Level Lock:
 
-   Running related tests...
-   ✓ LoginButton.test.tsx - 5/5 passed
+When editing files, track them:
 
-   ✓ Fix complete
-   ```
+```bash
+# On edit start:
+echo "src/auth/login.ts|Claude|$(date -Iseconds)" >> .proagents/.active-files
 
-For `pa:deploy`:
-1. **Run pre-deployment checks** automatically:
-   - All tests passing? If not → auto-fix
-   - QA checks passing? If not → auto-fix
-   - Security scan clean? If not → auto-fix
-   - Build succeeds? If not → auto-fix
-2. **Only proceed when all checks pass**
-3. **Deploy to target environment**
-4. **Run post-deployment verification**
-5. **Auto-rollback if verification fails**
-   ```
-   pa:deploy
+# On session end - clear your locks:
+grep -v "|Claude|" .proagents/.active-files > /tmp/af && mv /tmp/af .proagents/.active-files
+```
 
-   Pre-deployment checks...
-   ✓ Tests: 128/128 passed
-   ✓ QA: All checks passed
-   ✓ Security: No vulnerabilities
-   ✓ Build: Successful
+### Validation on pa:sync:
 
-   Deploying to staging...
-   ✓ Deployed successfully
+AI checks if previous session logged properly:
 
-   Post-deployment verification...
-   ✓ Health check passed
-   ✓ Smoke tests passed
+```bash
+# Compare git changes vs logged changes
+git diff --name-only HEAD~3 2>/dev/null | wc -l  # Files changed
+grep -c "Files:" .proagents/changelog/_recent.md  # Files logged
+```
 
-   ══════════════════════════════════════════
-   DEPLOYMENT SUCCESSFUL ✓
-   ══════════════════════════════════════════
-   ```
+If mismatch, warn:
+```
+⚠️ Previous session may have unlogged changes. Check git log.
+```
 
-**IMPORTANT - Full Automation Rules:**
-- **Never ask** "Should I fix this?" - Just fix it
-- **Never say** "Run `pa:test` to verify" - Run it yourself
-- **Never give** "Next steps" - Do the steps
-- **Only stop when:** All done OR truly impossible to proceed
+### Issue Linking:
 
-### Navigation & Flow
-| Command | Action |
-|---------|--------|
-| `pa:next` | Show next step in current workflow |
-| `pa:resume` | Resume paused feature from where left off |
-| `pa:skip` | Skip current phase, move to next |
-| `pa:back` | Go back to previous phase |
-| `pa:progress` | Show visual progress bar for current feature |
-
-**How to execute Navigation commands:**
-
-For `pa:next`:
-1. Read `./.proagents/active-features/*/status.json` to find current feature
-2. Identify current phase from status
-3. Show what the next step/phase is
-4. Provide guidance for the next action
-
-For `pa:resume`:
-1. Read `./.proagents/active-features/` to find paused features
-2. Read feature's `status.json` for last phase and progress
-3. Read `./.proagents/handoff.md` for context
-4. Continue from where it was left off
-
-For `pa:skip`:
-1. Read current feature status
-2. Mark current phase as "skipped" in status.json
-3. Move to next phase
-4. Log skip reason to activity.log
-5. Warn if skipping critical phase (testing, review)
-
-For `pa:back`:
-1. Read current feature status
-2. Move to previous phase
-3. Update status.json
-4. Reload context from previous phase
-
-For `pa:progress`:
-1. Read `./.proagents/active-features/*/status.json`
-2. Calculate percentage complete (current_phase / total_phases)
-3. Display visual progress bar:
-   ```
-   Feature: user-auth
-   Phase: 5/10 (Implementation)
-   Progress: [████████░░░░░░░░░░░░] 50%
+Auto-detect issue numbers from user input and include in changelog:
 
-   ✓ Init → ✓ Analysis → ✓ Requirements → ✓ Design → ● Implementation → ○ Testing → ○ Review → ○ Docs → ○ Deploy
-   ```
+```markdown
+### 2024-03-11 - Bug Fix
+**Issue:** #123
+**Module:** auth
+**Files:** src/auth/login.ts
+**Summary:** Fixed validation bug
+**Closes:** #123
+```
 
-### Context & History
-| Command | Action |
-|---------|--------|
-| `pa:context` | Quick view/edit project context |
-| `pa:context-edit` | Edit project context interactively |
-| `pa:diff` | Show what changed since last session |
-| `pa:history` | Show command history with results |
-| `pa:checkpoint` | Create a snapshot/restore point |
-| `pa:checkpoint-restore` | Restore from a checkpoint |
-| `pa:undo` | Undo last AI action using git |
-
-**How to execute Context & History commands:**
-
-For `pa:context`:
-1. Read `./.proagents/context.md`
-2. Display current project context summary
-3. Show last updated timestamp
-
-For `pa:diff`:
-1. Read `./.proagents/activity.log` for last session timestamp
-2. Run `git diff` from that point
-3. Summarize changes by file/module
-4. Highlight significant changes
-
-For `pa:history`:
-1. Read `./.proagents/history.log`
-2. Show recent commands with their results
-3. Format: `[timestamp] command → result`
-
-For `pa:checkpoint`:
-1. Create git commit with message "checkpoint: [description]"
-2. Save checkpoint info to `./.proagents/checkpoints.json`:
-   ```json
-   {
-     "checkpoints": [
-       {
-         "id": "cp-001",
-         "timestamp": "2024-03-06T15:00:00Z",
-         "commit": "abc123",
-         "description": "Before auth refactor",
-         "feature": "user-auth",
-         "phase": "implementation"
-       }
-     ]
-   }
-   ```
-3. Log to activity.log
+---
 
-For `pa:undo`:
-1. Read last action from `./.proagents/activity.log`
-2. If file changes, run `git checkout` to revert
-3. If multiple files, offer selective undo
-4. Update activity.log with undo entry
+## Command Quick Reference
 
-### Sprint & Project Management
-| Command | Action |
-|---------|--------|
-| `pa:sprint-start` | Start a new sprint |
-| `pa:sprint-end` | End sprint with summary |
-| `pa:sprint-status` | Show current sprint status |
-| `pa:estimate` | Estimate task complexity |
-| `pa:estimate "task"` | Estimate specific task |
-| `pa:velocity` | Show team velocity metrics |
-
-**How to execute Sprint commands:**
-
-For `pa:sprint-start`:
-1. Create `./.proagents/sprints/sprint-{number}.json`:
-   ```json
-   {
-     "sprint_number": 1,
-     "start_date": "2024-03-06",
-     "end_date": "2024-03-20",
-     "goals": [],
-     "features": [],
-     "status": "active"
-   }
-   ```
-2. Ask for sprint goals
-3. Link active features to sprint
-
-For `pa:sprint-end`:
-1. Read current sprint file
-2. Calculate metrics (completed features, velocity)
-3. Generate sprint summary → `./.proagents/sprints/sprint-{n}-summary.md`
-4. Archive sprint
-
-For `pa:estimate`:
-1. Analyze task/feature complexity
-2. Consider: code changes, files affected, dependencies, testing needs
-3. Provide estimate in story points or T-shirt sizes (S/M/L/XL)
-4. Save estimate to feature status.json
-
-For `pa:velocity`:
-1. Read completed sprints from `./.proagents/sprints/`
-2. Calculate average story points per sprint
-3. Show velocity chart/trend
-
-### Integration Commands
-| Command | Action |
-|---------|--------|
-| `pa:github` | GitHub integration commands |
-| `pa:github-issue` | Create GitHub issue from current work |
-| `pa:github-pr` | Create pull request |
-| `pa:jira` | Jira integration commands |
-| `pa:jira-sync` | Sync with Jira ticket |
-| `pa:notify` | Send notification |
-| `pa:notify-slack` | Send Slack notification |
-| `pa:notify-email` | Send email notification |
-
-**How to execute Integration commands:**
-
-For `pa:github-issue`:
-1. Read current feature/bug context
-2. Generate issue title and body
-3. Show preview and ask for confirmation
-4. Provide `gh issue create` command or API call
-
-For `pa:github-pr`:
-1. Read current feature context
-2. Generate PR title and description
-3. Include: summary, changes, test plan
-4. Provide `gh pr create` command
-
-For `pa:jira-sync`:
-1. Read Jira config from `proagents.config.yaml`
-2. Find linked ticket (from feature name or config)
-3. Update ticket status based on feature phase
-4. Add comment with progress
-
-For `pa:notify`:
-1. Read notification config from `proagents.config.yaml`
-2. Generate notification message based on context
-3. Send via configured channel (Slack webhook, email, etc.)
-
-### Code Quality Commands
-| Command | Action |
-|---------|--------|
-| `pa:metrics` | Show code quality metrics |
-| `pa:metrics-history` | Show metrics over time |
-| `pa:coverage` | Show test coverage report |
-| `pa:coverage-diff` | Show coverage changes |
-| `pa:deps` | Analyze dependencies |
-| `pa:deps-outdated` | Find outdated dependencies |
-| `pa:deps-security` | Security scan dependencies |
-
-**How to execute Code Quality commands:**
-
-For `pa:metrics`:
-1. Analyze codebase for:
-   - Lines of code (by language)
-   - Cyclomatic complexity
-   - Code duplication
-   - Function/file sizes
-2. Save to `./.proagents/metrics/latest.json`
-3. Display summary with warnings for issues
-
-For `pa:coverage`:
-1. Check for coverage reports (coverage/, .nyc_output/, etc.)
-2. Parse coverage data
-3. Display summary:
-   ```
-   Test Coverage Report
-   ═══════════════════
-   Overall: 82% ✓
-
-   By Module:
-   • src/auth/     95% ████████████████████ ✓
-   • src/api/      78% ███████████████░░░░░
-   • src/utils/    65% █████████████░░░░░░░ ⚠
-   ```
+### Aliases
+| Alias | Command |
+|-------|---------|
+| `pa:f` | `pa:feature` |
+| `pa:s` | `pa:status` |
+| `pa:h` | `pa:help` |
+| `pa:d` | `pa:doc` |
+| `pa:t` | `pa:test` |
+| `pa:q` | `pa:qa` |
+| `pa:a` | `pa:analyze` |
+| `pa:r` | `pa:requirements` |
+| `pa:p` | `pa:plan` |
+| `pa:i` | `pa:implement` |
+| `pa:rev` | `pa:review` |
+| `pa:dbg` | `pa:debug` |
+| `pa:l` | `pa:logs` |
 
-For `pa:deps`:
-1. Read package.json / requirements.txt
-2. Analyze dependency tree
-3. Identify:
-   - Direct vs transitive deps
-   - Duplicate packages
-   - Large dependencies
-   - Outdated versions
-
-For `pa:deps-security`:
-1. Run `npm audit` or equivalent
-2. Parse security advisories
-3. Categorize by severity
-4. Suggest fixes
-
-### Code Generation
-| Command | Action |
-|---------|--------|
-| `pa:generate` | Show generation options |
-| `pa:generate-component "name"` | Generate React/Vue component |
-| `pa:generate-api "name"` | Generate API endpoint |
-| `pa:generate-test "file"` | Generate test file for module |
-| `pa:generate-hook "name"` | Generate custom hook |
-| `pa:generate-service "name"` | Generate service class |
-
-**How to execute Code Generation commands:**
-
-For `pa:generate-component`:
-1. Read project type and patterns from `./.proagents/cache/patterns.json`
-2. Use template from `./.proagents/scaffolding/` matching project type
-3. Apply project naming conventions
-4. Create component file with:
-   - Component code
-   - Types/interfaces
-   - Basic styles (if applicable)
-   - Test file (optional)
-5. Save to appropriate directory based on project structure
-
-For `pa:generate-api`:
-1. Detect API framework (Express, Next.js, NestJS, etc.)
-2. Use appropriate template
-3. Generate:
-   - Route handler
-   - Input validation
-   - Error handling
-   - Types
-4. Add to routes index if applicable
-
-For `pa:generate-test`:
-1. Read the source file
-2. Detect testing framework (Jest, Vitest, etc.)
-3. Generate test file with:
-   - Import statements
-   - Describe blocks
-   - Test cases for each function
-   - Mock setup
-4. Save alongside source or in tests/ folder
-
-### Refactoring
-| Command | Action |
-|---------|--------|
-| `pa:refactor` | Analyze and suggest refactoring |
-| `pa:refactor "file"` | Refactor specific file |
-| `pa:rename "old" "new"` | Rename symbol across codebase |
-| `pa:extract "name"` | Extract function/component |
-| `pa:cleanup` | Remove dead code, unused imports |
-| `pa:cleanup-imports` | Clean up imports only |
-
-**How to execute Refactoring commands:**
-
-For `pa:refactor`:
-1. Analyze codebase for:
-   - Long functions (>50 lines)
-   - Deep nesting (>3 levels)
-   - Duplicate code
-   - Complex conditionals
-   - God classes/components
-2. Prioritize by impact
-3. Suggest specific refactoring for each issue
-4. Offer to apply refactoring
-
-For `pa:rename`:
-1. Find all occurrences of symbol
-2. Check for naming conflicts
-3. Show preview of changes
-4. Apply rename across all files
-5. Update imports/exports
-
-For `pa:cleanup`:
-1. Find unused imports
-2. Find unused variables
-3. Find dead code (unreachable)
-4. Find unused exports
-5. Show list and offer to remove
-6. Log changes to activity.log
-
-### Time Tracking
+### Core Commands
 | Command | Action |
 |---------|--------|
-| `pa:time-start` | Start time tracking |
-| `pa:time-start "task"` | Start tracking specific task |
-| `pa:time-stop` | Stop current time tracking |
-| `pa:time-pause` | Pause time tracking |
-| `pa:time-report` | Show time report |
-| `pa:time-report "feature"` | Report for specific feature |
-
-**How to execute Time Tracking commands:**
-
-For `pa:time-start`:
-1. Create/update `./.proagents/time-tracking.json`:
-   ```json
-   {
-     "current": {
-       "task": "feature-user-auth",
-       "started": "2024-03-06T15:00:00Z",
-       "status": "running"
-     },
-     "entries": []
-   }
-   ```
-2. Log to activity.log
-
-For `pa:time-stop`:
-1. Read current tracking
-2. Calculate duration
-3. Add to entries array:
-   ```json
-   {
-     "task": "feature-user-auth",
-     "started": "2024-03-06T15:00:00Z",
-     "ended": "2024-03-06T17:30:00Z",
-     "duration_minutes": 150,
-     "ai": "Claude:opus-4"
-   }
-   ```
-4. Clear current tracking
-
-For `pa:time-report`:
-1. Read all entries from time-tracking.json
-2. Group by task/feature
-3. Calculate totals
-4. Display report:
-   ```
-   Time Report
-   ═══════════
-   Feature: user-auth
-   Total: 5h 30m
-   Sessions: 3
-
-   Feature: dashboard
-   Total: 2h 15m
-   Sessions: 2
-   ```
+| `pa:help` | Show all commands |
+| `pa:status` | Show current progress |
+| `pa:feature "name"` | Start new feature |
+| `pa:fix "bug"` | Quick bug fix |
+| `pa:feature-list` | List all features |
+| `pa:feature-complete` | Mark feature complete |
 
-### Environment & Setup
+### Workflow Phases
 | Command | Action |
 |---------|--------|
-| `pa:env-check` | Verify environment setup |
-| `pa:env-setup` | Setup development environment |
-| `pa:env-diff` | Compare environments |
-| `pa:secrets-scan` | Scan for exposed secrets |
-| `pa:secrets-check` | Verify required secrets exist |
-
-**How to execute Environment commands:**
-
-For `pa:env-check`:
-1. Check for required files (.env, .env.local, etc.)
-2. Verify Node/Python/etc. version matches
-3. Check for required dependencies
-4. Verify database connection (if applicable)
-5. Check for required environment variables
-6. Report status:
-   ```
-   Environment Check
-   ═════════════════
-   ✓ Node.js v18.17.0 (required: >=18)
-   ✓ npm v9.6.0
-   ✓ .env.local exists
-   ⚠ DATABASE_URL not set
-   ✗ Redis not running
-   ```
+| `pa:analyze` | Codebase analysis |
+| `pa:requirements` | Gather requirements |
+| `pa:design` | UI/architecture design |
+| `pa:plan` | Create implementation plan |
+| `pa:implement` | Execute implementation |
+| `pa:test` | Run tests |
+| `pa:review` | Code review |
+| `pa:doc` | Generate documentation |
+| `pa:deploy` | Deployment preparation |
 
-For `pa:secrets-scan`:
-1. Scan codebase for patterns:
-   - API keys (sk_, pk_, api_key, etc.)
-   - Passwords in code
-   - Private keys
-   - Connection strings
-2. Check .gitignore for sensitive files
-3. Report findings with file locations
-4. Suggest fixes (move to .env, etc.)
-
-### Database Commands
-| Command | Action |
-|---------|--------|
-| `pa:db-migrate` | Run database migrations |
-| `pa:db-migrate-create "name"` | Create new migration |
-| `pa:db-seed` | Seed database with test data |
-| `pa:db-reset` | Reset database |
-| `pa:db-status` | Show migration status |
-
-**How to execute Database commands:**
-
-For `pa:db-migrate`:
-1. Detect ORM (Prisma, TypeORM, Sequelize, Drizzle, etc.)
-2. Run appropriate migrate command:
-   - Prisma: `npx prisma migrate dev`
-   - TypeORM: `npm run typeorm migration:run`
-3. Report results
-
-For `pa:db-seed`:
-1. Find seed files (prisma/seed.ts, seeds/, etc.)
-2. Run seed command
-3. Report inserted records
-
-For `pa:db-reset`:
-1. Warn user about data loss
-2. Require confirmation
-3. Drop and recreate database
-4. Run migrations
-5. Optionally run seeds
-
-### Accessibility & Performance
+### Testing
 | Command | Action |
 |---------|--------|
-| `pa:a11y` | Run accessibility audit |
-| `pa:a11y "url"` | Audit specific page |
-| `pa:lighthouse` | Run Lighthouse audit |
-| `pa:lighthouse "url"` | Audit specific URL |
-| `pa:perf` | Performance analysis |
-| `pa:perf-bundle` | Bundle size analysis |
-
-**How to execute A11y & Performance commands:**
-
-For `pa:a11y`:
-1. Check for a11y tools (axe, pa11y, etc.)
-2. Run audit on pages/components
-3. Report issues by severity:
-   ```
-   Accessibility Audit
-   ═══════════════════
-   Critical: 2
-   Serious: 5
-   Moderate: 12
-   Minor: 8
-
-   Top Issues:
-   • Missing alt text on images (5 instances)
-   • Low color contrast (3 instances)
-   • Missing form labels (2 instances)
-   ```
-4. Link to WCAG guidelines for each issue
-
-For `pa:lighthouse`:
-1. Check if Lighthouse is available
-2. Run audit (provide command or use API)
-3. Parse results
-4. Display scores:
-   ```
-   Lighthouse Scores
-   ═════════════════
-   Performance:    85 ████████░░
-   Accessibility:  92 █████████░
-   Best Practices: 100 ██████████
-   SEO:            90 █████████░
-   ```
+| `pa:test` | Run all tests |
+| `pa:test-unit` | Unit tests only |
+| `pa:test-e2e` | E2E tests only |
+| `pa:test-coverage` | Run with coverage |
+| `pa:test-watch` | Watch mode |
 
-For `pa:perf`:
-1. Analyze:
-   - Bundle sizes
-   - Load times
-   - Render performance
-   - Memory usage patterns
-2. Identify bottlenecks
-3. Suggest optimizations
-
-### Export & Backup
-| Command | Action |
-|---------|--------|
-| `pa:export` | Export ProAgents config and data |
-| `pa:export-config` | Export only configuration |
-| `pa:import` | Import from export file |
-| `pa:backup` | Create full backup |
-| `pa:backup-restore` | Restore from backup |
-
-**How to execute Export & Backup commands:**
-
-For `pa:export`:
-1. Gather all ProAgents data:
-   - proagents.config.yaml
-   - context.md
-   - decisions.md
-   - feedback.md
-   - active-features/
-   - learned patterns
-2. Create export file: `proagents-export-YYYY-MM-DD.json`
-3. Optionally encrypt sensitive data
-
-For `pa:import`:
-1. Read export file
-2. Validate format
-3. Merge or replace existing data
-4. Report what was imported
-
-For `pa:backup`:
-1. Create timestamped backup of entire .proagents/ folder
-2. Save to `./.proagents/backups/` or specified location
-3. Compress if large
-4. Maintain rolling backups (keep last N)
-
-### Learning & AI
+### Documentation
 | Command | Action |
 |---------|--------|
-| `pa:learn "pattern"` | Teach AI a new pattern |
-| `pa:learn-from "file"` | Learn patterns from file |
-| `pa:forget "pattern"` | Remove learned pattern |
-| `pa:suggestions` | Show AI suggestions for project |
-| `pa:suggestions-apply` | Apply a suggestion |
-
-**How to execute Learning commands:**
-
-For `pa:learn`:
-1. Parse the pattern description
-2. Add to `./.proagents/.learning/`:
-   ```json
-   {
-     "pattern": "Always use React Query for API calls",
-     "type": "preference",
-     "added": "2024-03-06",
-     "added_by": "user",
-     "applies_to": ["api", "data-fetching"]
-   }
-   ```
-3. Confirm pattern learned
-
-For `pa:forget`:
-1. Find matching pattern
-2. Remove from learning data
-3. Confirm removal
-
-For `pa:suggestions`:
-1. Analyze project state
-2. Check learned patterns
-3. Generate suggestions:
-   ```
-   AI Suggestions
-   ══════════════
-   1. [Code Quality] Consider adding error boundaries to page components
-   2. [Performance] Bundle size increased 15% - review new dependencies
-   3. [Testing] Test coverage dropped below 80% in src/utils/
-   4. [Security] 2 dependencies have known vulnerabilities
-   ```
-4. Offer to apply each suggestion
+| `pa:doc` | **Create** docs in `./docs/` |
+| `pa:doc-api` | **Create** API docs in `./docs/api/` |
+| `pa:doc-module X` | **Create** `./docs/modules/X.md` |
+| `pa:doc-component` | **Create** component docs |
+| `pa:doc-readme` | **Update** `./README.md` |
+| `pa:release` | **Create** `./RELEASE_NOTES.md` |
+| `pa:changelog` | **Update** `./CHANGELOG.md` |
 
-### API & Documentation Generation
+### Quality & Review
 | Command | Action |
 |---------|--------|
-| `pa:api-docs` | Generate OpenAPI/Swagger documentation |
-| `pa:api-docs "path"` | Generate docs for specific API path |
-| `pa:storybook` | Generate Storybook stories for components |
-| `pa:storybook "component"` | Generate story for specific component |
-| `pa:readme` | Auto-generate/update README.md |
-| `pa:readme-section "name"` | Update specific README section |
-| `pa:types` | Generate TypeScript types/interfaces |
-| `pa:types "file"` | Generate types for specific file |
-
-**How to execute API & Documentation commands:**
-
-For `pa:api-docs`:
-1. Detect API framework (Express, Next.js, NestJS, FastAPI, etc.)
-2. Scan route files for endpoints
-3. Extract:
-   - HTTP methods and paths
-   - Request/response types
-   - Query/path parameters
-   - Authentication requirements
-4. Generate OpenAPI 3.0 spec:
-   ```yaml
-   openapi: 3.0.0
-   info:
-     title: API Documentation
-     version: 1.0.0
-   paths:
-     /api/users:
-       get:
-         summary: List all users
-         responses:
-           '200':
-             description: Success
-   ```
-5. Save to `./docs/openapi.yaml` or `./swagger.json`
-6. Optionally generate HTML documentation
-
-For `pa:storybook`:
-1. Find React/Vue/Angular components
-2. Analyze component props/interfaces
-3. Generate story file with:
-   - Default story
-   - Variant stories for different props
-   - Interactive controls
-4. Save to `*.stories.tsx` alongside component:
-   ```tsx
-   import type { Meta, StoryObj } from '@storybook/react';
-   import { Button } from './Button';
-
-   const meta: Meta<typeof Button> = {
-     component: Button,
-     title: 'Components/Button',
-   };
-   export default meta;
-
-   export const Primary: StoryObj<typeof Button> = {
-     args: { variant: 'primary', children: 'Click me' },
-   };
-   ```
-
-For `pa:readme`:
-1. Analyze project structure
-2. Detect:
-   - Project type and framework
-   - Available scripts (npm scripts)
-   - Dependencies
-   - Existing documentation
-3. Generate/update README with:
-   - Project title and description
-   - Installation instructions
-   - Usage examples
-   - Available commands
-   - Contributing guidelines
-4. Preserve existing custom sections
-
-For `pa:types`:
-1. Analyze source file or API responses
-2. Infer TypeScript types:
-   - From JavaScript usage patterns
-   - From JSON data structures
-   - From API responses
-3. Generate interface/type definitions:
-   ```typescript
-   interface User {
-     id: string;
-     name: string;
-     email: string;
-     createdAt: Date;
-   }
-   ```
-4. Save to `types/` folder or alongside source
+| `pa:qa` | Full QA checks |
+| `pa:qa-security` | Security audit |
+| `pa:qa-performance` | Performance check |
+| `pa:review` | Code review |
+| `pa:lint` | Run linters |
 
-### Git Advanced
+### Debug & Logs
 | Command | Action |
 |---------|--------|
-| `pa:branch` | Branch management (list, info) |
-| `pa:branch-create "name"` | Create new branch |
-| `pa:branch-clean` | Clean up merged/stale branches |
-| `pa:merge` | Smart merge with conflict preview |
-| `pa:merge "branch"` | Merge specific branch |
-| `pa:conflict` | Resolve merge conflicts with AI |
-| `pa:conflict "file"` | Resolve conflicts in specific file |
-| `pa:changelog-gen` | Auto-generate changelog from commits |
-| `pa:changelog-gen "version"` | Generate for specific version |
-
-**How to execute Git Advanced commands:**
-
-For `pa:branch`:
-1. Run `git branch -a` to list all branches
-2. Show current branch with `git branch --show-current`
-3. Display branch info:
-   ```
-   Branches
-   ════════
-   Current: feature/user-auth
-
-   Local:
-   • main (2 days ago)
-   • develop (1 hour ago)
-   • feature/user-auth * (current)
-   • feature/dashboard (5 days ago, stale)
-
-   Remote:
-   • origin/main
-   • origin/develop
-   ```
-
-For `pa:branch-clean`:
-1. Find merged branches: `git branch --merged`
-2. Find stale branches (no commits in 30+ days)
-3. Show list and ask for confirmation
-4. Delete selected branches
-5. Optionally prune remote tracking branches
-
-For `pa:merge`:
-1. Show current branch and target
-2. Preview changes: `git diff branch...HEAD`
-3. Check for conflicts: `git merge --no-commit --no-ff branch`
-4. If conflicts exist, list conflicting files
-5. If clean, proceed with merge
-6. Create merge commit with descriptive message
-
-For `pa:conflict`:
-1. List conflicting files: `git diff --name-only --diff-filter=U`
-2. For each file:
-   - Show conflict markers
-   - Analyze both versions
-   - Suggest resolution based on:
-     - Code context
-     - Which change is more recent
-     - What each change accomplishes
-3. Apply resolution and mark as resolved
-4. Stage resolved files
-
-For `pa:changelog-gen`:
-1. Get commits since last tag: `git log $(git describe --tags --abbrev=0)..HEAD`
-2. Parse conventional commits
-3. Group by type (feat, fix, docs, etc.)
-4. Generate changelog:
-   ```markdown
-   ## [1.2.0] - 2024-03-06
-
-   ### Added
-   - User authentication with JWT (#123)
-   - Dashboard component (#125)
-
-   ### Fixed
-   - Login button styling (#124)
-
-   ### Changed
-   - Updated dependencies (#126)
-   ```
-5. Prepend to CHANGELOG.md
+| `pa:debug` | Start debug session |
+| `pa:debug-add` | Add debug logs to code |
+| `pa:debug-add "file"` | Add logs to specific file |
+| `pa:debug-trace "func"` | Add entry/exit logs to function |
+| `pa:debug-var "var"` | Track variable changes |
+| `pa:debug-api` | Add API request/response logging |
+| `pa:debug-state` | Add state change logging |
+| `pa:debug-error` | Add error boundary logging |
+| `pa:debug-web` | Web console debugging |
+| `pa:debug-rn` | React Native debugging |
+| `pa:debug-android` | Android native (logcat) |
+| `pa:debug-ios` | iOS native debugging |
+| `pa:logs` | View recent logs |
+| `pa:logs-filter "term"` | Filter logs by term |
+| `pa:debug-clean` | Remove all debug statements |
 
-### Search & Code Navigation
+### Collaboration
 | Command | Action |
 |---------|--------|
-| `pa:find "pattern"` | Find code patterns/usage |
-| `pa:find-usage "symbol"` | Find all usages of symbol |
-| `pa:find-definition "symbol"` | Find definition of symbol |
-| `pa:todo` | Find and list all TODOs |
-| `pa:todo-add "message"` | Add TODO at current location |
-| `pa:fixme` | Find FIXMEs and critical issues |
-| `pa:unused` | Find unused code/exports |
-| `pa:unused-deps` | Find unused dependencies |
-
-**How to execute Search commands:**
-
-For `pa:find`:
-1. Search codebase for pattern using grep/ripgrep
-2. Support regex patterns
-3. Show results with context:
-   ```
-   Search Results: "useAuth"
-   ═══════════════════════════
-
-   src/hooks/useAuth.ts:5
-   │ export function useAuth() {
-
-   src/pages/Login.tsx:12
-   │ const { login, logout } = useAuth();
-
-   src/components/Navbar.tsx:8
-   │ const { user } = useAuth();
-
-   Found 3 matches in 3 files
-   ```
-
-For `pa:todo`:
-1. Search for TODO, FIXME, HACK, XXX comments
-2. Parse priority markers (TODO(high):, TODO:, etc.)
-3. Group by priority and file:
-   ```
-   TODOs Found: 15
-   ═══════════════
-
-   High Priority:
-   • src/auth/jwt.ts:45 - TODO(high): Add token refresh
-   • src/api/users.ts:78 - FIXME: SQL injection risk
-
-   Medium Priority:
-   • src/utils/date.ts:12 - TODO: Handle timezone
-
-   Low Priority:
-   • src/components/Button.tsx:5 - TODO: Add loading state
-   ```
-
-For `pa:fixme`:
-1. Search for FIXME, BUG, HACK, XXX, SECURITY
-2. Prioritize by keyword severity
-3. Show with context and age (when added via git blame)
-4. Suggest fixes where possible
-
-For `pa:unused`:
-1. Analyze exports and imports
-2. Find:
-   - Exported but never imported
-   - Defined but never used
-   - Dead code (unreachable)
-3. Report with confidence level:
-   ```
-   Unused Code Analysis
-   ═══════════════════
-
-   Definitely Unused:
-   • src/utils/old-helper.ts - entire file (no imports)
-   • src/types/legacy.ts:LegacyUser - type never used
-
-   Possibly Unused:
-   • src/api/deprecated.ts:oldEndpoint - only test imports
-   ```
-
-For `pa:unused-deps`:
-1. Read package.json dependencies
-2. Search codebase for imports
-3. Find packages never imported:
-   ```
-   Unused Dependencies
-   ═══════════════════
-
-   dependencies:
-   • lodash - never imported
-   • moment - never imported (consider date-fns)
-
-   devDependencies:
-   • @types/node - used
-   ```
+| `pa:activity` | Show AI activity log |
+| `pa:lock` | Show lock status |
+| `pa:handoff` | Create handoff notes |
+| `pa:feedback "text"` | Log feedback for AI learning |
+| `pa:decision "title"` | Log architectural decision |
 
-### Code Analysis
+### Cross-AI Continuity (CRITICAL)
 | Command | Action |
 |---------|--------|
-| `pa:complexity` | Cyclomatic complexity analysis |
-| `pa:complexity "file"` | Analyze specific file |
-| `pa:duplication` | Find duplicate code blocks |
-| `pa:duplication "threshold"` | Set minimum lines threshold |
-| `pa:hotspots` | Find frequently changed files |
-| `pa:hotspots "days"` | Analyze over specific period |
-
-**How to execute Code Analysis commands:**
-
-For `pa:complexity`:
-1. Analyze functions/methods for:
-   - Cyclomatic complexity (if/else, switch, loops)
-   - Cognitive complexity
-   - Nesting depth
-   - Parameter count
-2. Report high complexity areas:
-   ```
-   Complexity Report
-   ═════════════════
-
-   High Complexity (>10):
-   • src/utils/parser.ts:parseData() - complexity: 15
-     ↳ 8 if statements, 3 loops, max depth: 4
-     ↳ Suggestion: Split into smaller functions
-
-   • src/api/handler.ts:processRequest() - complexity: 12
-     ↳ Large switch statement (10 cases)
-     ↳ Suggestion: Use strategy pattern
-
-   Medium Complexity (5-10):
-   • src/auth/validate.ts:validateUser() - complexity: 7
-   ```
-
-For `pa:duplication`:
-1. Find duplicate code blocks (default: 6+ lines)
-2. Calculate similarity percentage
-3. Report duplicates:
-   ```
-   Code Duplication Report
-   ═══════════════════════
+| `pa:sync` | **Run FIRST** - Load project context |
+| `pa:resume` | Quick resume - shows last session + next action |
+| `pa:session-start` | Begin new work session |
+| `pa:session-end` | Finalize session, update logs |
+| `pa:conflict-check` | Check if files modified by other AI |
+| `pa:history` | View command history |
+| `pa:progress` | View feature progress |
+| `pa:changelog` | Update all changelogs |
+| `pa:changelog --from-git` | Auto-populate from git commits |
+| `pa:changelog-feature X` | View feature changelog |
+| `pa:changelog-module X` | View module changelog |
+| `pa:error "desc"` | Log error and solution |
 
-   Duplicate #1 (98% similar, 15 lines):
-   • src/api/users.ts:45-60
-   • src/api/posts.ts:32-47
-   ↳ Suggestion: Extract to shared utility
-
-   Duplicate #2 (100% identical, 8 lines):
-   • src/components/Card.tsx:12-20
-   • src/components/Panel.tsx:8-16
-   ↳ Suggestion: Create shared component
-
-   Total: 5 duplicate blocks, ~120 duplicated lines
-   ```
-
-For `pa:hotspots`:
-1. Analyze git history for frequently changed files
-2. Correlate with bug fixes
-3. Identify risky areas:
-   ```
-   Code Hotspots (Last 30 Days)
-   ════════════════════════════
-
-   Most Changed:
-   1. src/api/auth.ts - 45 changes, 12 bug fixes
-      ↳ High churn + bugs = refactoring candidate
-
-   2. src/utils/helpers.ts - 32 changes, 3 bug fixes
-      ↳ Frequently modified utility
-
-   3. src/components/Form.tsx - 28 changes, 8 bug fixes
-      ↳ Complex component, consider splitting
-   ```
-
-### Testing Advanced
+### Configuration
 | Command | Action |
 |---------|--------|
-| `pa:test-e2e` | Create/run E2E tests |
-| `pa:test-e2e "flow"` | E2E test for specific flow |
-| `pa:test-unit` | Generate unit tests |
-| `pa:test-unit "file"` | Generate tests for file |
-| `pa:mock` | Generate mocks/stubs |
-| `pa:mock "module"` | Mock specific module |
-| `pa:snapshot` | Snapshot testing management |
-| `pa:snapshot-update` | Update snapshots |
-
-**How to execute Testing Advanced commands:**
-
-For `pa:test-e2e`:
-1. Detect E2E framework (Playwright, Cypress, etc.)
-2. Analyze user flows in the app
-3. Generate E2E test:
-   ```typescript
-   import { test, expect } from '@playwright/test';
-
-   test.describe('User Authentication', () => {
-     test('should login successfully', async ({ page }) => {
-       await page.goto('/login');
-       await page.fill('[name="email"]', 'test@example.com');
-       await page.fill('[name="password"]', 'password123');
-       await page.click('button[type="submit"]');
-       await expect(page).toHaveURL('/dashboard');
-     });
-
-     test('should show error for invalid credentials', async ({ page }) => {
-       await page.goto('/login');
-       await page.fill('[name="email"]', 'wrong@example.com');
-       await page.fill('[name="password"]', 'wrong');
-       await page.click('button[type="submit"]');
-       await expect(page.locator('.error')).toBeVisible();
-     });
-   });
-   ```
-
-For `pa:test-unit`:
-1. Read source file
-2. Identify functions/methods to test
-3. Generate comprehensive test file:
-   ```typescript
-   import { describe, it, expect, vi } from 'vitest';
-   import { calculateTotal, formatPrice } from './pricing';
-
-   describe('calculateTotal', () => {
-     it('should calculate total with tax', () => {
-       expect(calculateTotal(100, 0.1)).toBe(110);
-     });
-
-     it('should handle zero amount', () => {
-       expect(calculateTotal(0, 0.1)).toBe(0);
-     });
-
-     it('should throw for negative amounts', () => {
-       expect(() => calculateTotal(-100, 0.1)).toThrow();
-     });
-   });
-   ```
-
-For `pa:mock`:
-1. Analyze module dependencies
-2. Generate mock implementations:
-   ```typescript
-   // mocks/api.ts
-   import { vi } from 'vitest';
-
-   export const mockApi = {
-     getUsers: vi.fn().mockResolvedValue([
-       { id: '1', name: 'Test User' }
-     ]),
-     createUser: vi.fn().mockResolvedValue({ id: '2' }),
-     deleteUser: vi.fn().mockResolvedValue(true),
-   };
-
-   vi.mock('../api', () => mockApi);
-   ```
-3. Include type-safe mocks with TypeScript
+| `pa:config` | Show config |
+| `pa:checkpoint` | Pause for approval |
+| `pa:skip-checkpoint` | Skip checkpoint |
 
-For `pa:snapshot`:
-1. Find existing snapshots
-2. Show status:
-   ```
-   Snapshot Status
-   ═══════════════
-
-   Total: 45 snapshots in 12 files
-
-   Outdated (need update):
-   • Button.test.tsx - 3 snapshots
-   • Card.test.tsx - 1 snapshot
-
-   Obsolete (no matching test):
-   • OldComponent.test.tsx.snap - entire file
-
-   Commands:
-   • pa:snapshot-update - Update outdated
-   • pa:snapshot-clean - Remove obsolete
-   ```
-
-### DevOps & Infrastructure
+### History & Progress
 | Command | Action |
 |---------|--------|
-| `pa:docker` | Docker commands overview |
-| `pa:docker-build` | Build Docker image |
-| `pa:docker-compose` | Docker Compose operations |
-| `pa:ci` | CI/CD pipeline status/management |
-| `pa:ci-run` | Trigger CI pipeline |
-| `pa:deploy-preview` | Deploy to preview environment |
-| `pa:deploy-preview-url` | Get preview deployment URL |
-
-**How to execute DevOps commands:**
-
-For `pa:docker`:
-1. Check for Dockerfile and docker-compose.yml
-2. Show available commands:
-   ```
-   Docker Status
-   ═════════════
-
-   Dockerfile: ✓ Found
-   docker-compose.yml: ✓ Found
-
-   Services:
-   • app - Node.js application
-   • db - PostgreSQL
-   • redis - Redis cache
-
-   Commands:
-   • pa:docker-build - Build images
-   • pa:docker-compose up - Start services
-   • pa:docker-compose down - Stop services
-   ```
-
-For `pa:docker-build`:
-1. Read Dockerfile
-2. Suggest optimizations if needed
-3. Build image with appropriate tags
-4. Report build status and size
-
-For `pa:ci`:
-1. Detect CI system (GitHub Actions, GitLab CI, etc.)
-2. Show pipeline status:
-   ```
-   CI/CD Status
-   ════════════
-
-   Platform: GitHub Actions
+| `pa:history` | Show command history (read activity.log) |
+| `pa:progress` | Show feature progress |
+| `pa:activity` | Show recent AI activity |
 
-   Recent Workflows:
-   ✓ Build & Test (main) - 2m ago - passed
-   ✓ Deploy Preview (PR #123) - 15m ago - passed
-   ✗ Security Scan (main) - 1h ago - failed
-     ↳ 2 vulnerabilities found
+---
 
-   Current:
-   ● Build & Test (feature/auth) - running (1m 30s)
-   ```
-
-For `pa:deploy-preview`:
-1. Detect preview deployment platform (Vercel, Netlify, etc.)
-2. Trigger preview deployment
-3. Wait for deployment URL
-4. Return preview URL:
-   ```
-   Preview Deployment
-   ══════════════════
+## How to Execute Commands
 
-   Branch: feature/user-auth
-   Status: Deploying...
+When user types a `pa:` command:
 
-   ✓ Building... done (45s)
-   ✓ Deploying... done (30s)
+1. **Read the prompt file** from `./.proagents/prompts/`
+2. **Follow the workflow** defined in that prompt
+3. **Use project config** from `proagents.config.yaml`
 
-   Preview URL: https://my-app-user-auth-123.vercel.app
-   ```
+### Prompt File Mapping
+| Command | Prompt File |
+|---------|-------------|
+| `pa:feature` | `./prompts/00-init.md` |
+| `pa:analyze` | `./prompts/01-analysis.md` |
+| `pa:requirements` | `./prompts/02-requirements.md` |
+| `pa:design` | `./prompts/03-ui-design.md` |
+| `pa:plan` | `./prompts/04-planning.md` |
+| `pa:implement` | `./prompts/05-implementation.md` |
+| `pa:test` | `./prompts/06-testing.md` |
+| `pa:review` | `./prompts/06.5-code-review.md` |
+| `pa:doc` | `./prompts/07-documentation.md` |
+| `pa:deploy` | `./prompts/08-deployment.md` |
+| `pa:fix` | `./workflow-modes/entry-modes.md` |
+| `pa:debug` | `./prompts/10-debug-logs.md` |
+| `pa:logs` | `./prompts/10-debug-logs.md` |
+| `pa:sync` | `./prompts/11-session-tracking.md` |
+| `pa:session-start` | `./prompts/11-session-tracking.md` |
+| `pa:session-end` | `./prompts/11-session-tracking.md` |
+| `pa:changelog` | `./prompts/11-session-tracking.md` + `./prompts/07-documentation.md` |
+
+---
+
+## pa:history Execution
+
+**AI MUST read and display the actual log file content.**
+
+1. Read `./.proagents/activity.log`
+2. Filter out header lines (lines starting with #)
+3. Display entries (most recent first)
+4. NEVER say "no commands yet" without reading the file
+
+```bash
+# AI runs this:
+grep -v "^#" .proagents/activity.log | grep -v "^$" | grep -v "Activity Log Start" | tail -30
+```
 
-### Release Management
-| Command | Action |
-|---------|--------|
-| `pa:version` | Show current version |
-| `pa:version-bump "type"` | Bump version (major/minor/patch) |
-| `pa:tag` | Create git tag for release |
-| `pa:tag "version"` | Create specific version tag |
-| `pa:publish` | Publish package to registry |
-| `pa:publish-dry` | Dry run of publish |
-
-**How to execute Release commands:**
-
-For `pa:version`:
-1. Read version from package.json or equivalent
-2. Show version info:
-   ```
-   Version Info
-   ════════════
+If no entries found after filtering, show:
+```
+No pa: commands logged yet.
+Run some commands, then try pa:history again.
+```
 
-   Current: 1.2.3
-   Last Release: 1.2.2 (2024-03-01)
+**Output format:**
+```
+Command History
+═══════════════
+[2024-03-06 16:00] [Gemini] pa:logs - Captured 50 entries
+[2024-03-06 15:30] [Cursor] pa:test - 12 tests passed
+[2024-03-06 15:15] [Claude] pa:analyze - Analyzed 45 files
+[2024-03-06 15:10] [Claude] pa:feature - Started "user-auth"
+```
 
-   Unreleased Changes:
-   • 5 features
-   • 3 bug fixes
-   • 2 breaking changes
+---
 
-   Suggested Next:
-   • Major (2.0.0) - has breaking changes
-   • Minor (1.3.0) - new features
-   • Patch (1.2.4) - bug fixes only
-   ```
+## pa:progress Execution
 
-For `pa:version-bump`:
-1. Determine bump type (major/minor/patch)
-2. Update version in:
-   - package.json
-   - package-lock.json
-   - Other version files
-3. Update CHANGELOG.md with new version
-4. Show changes:
-   ```
-   Version Bump: 1.2.3 → 1.3.0
-   ═══════════════════════════
+**AI MUST read feature status from actual files.**
 
-   Updated files:
-   • package.json
-   • package-lock.json
-   • CHANGELOG.md
+1. Read `./.proagents/active-features/_index.json`
+2. Read each feature's `status.json`
+3. Calculate and display progress
 
-   Next steps:
-   • pa:tag 1.3.0 - Create release tag
-   • pa:publish - Publish to npm
-   ```
+```bash
+# AI runs this:
+cat .proagents/active-features/_index.json
+cat .proagents/active-features/feature-*/status.json
+```
 
-For `pa:tag`:
-1. Create annotated git tag
-2. Include release notes in tag message
-3. Optionally push to remote:
-   ```
-   Created Tag: v1.3.0
-   ═══════════════════
+**Output format:**
+```
+Feature Progress
+════════════════
+user-auth [████████░░] 80%
+  Phase: testing
+  Last: Ran 12 unit tests
+
+dashboard [████░░░░░░] 40%
+  Phase: implementation
+  Last: Created 3 components
+```
 
-   Tag: v1.3.0
-   Message: Release 1.3.0 - User Authentication
+---
 
-   Included:
-   • feat: Add user authentication
-   • feat: Add password reset
-   • fix: Login validation
+## pa:status Execution
 
-   Push to remote? (git push origin v1.3.0)
-   ```
+**IMPORTANT:** Show REAL data only, never example data.
 
-For `pa:publish`:
-1. Run pre-publish checks:
-   - Tests pass
-   - Build succeeds
-   - No uncommitted changes
-   - Version is tagged
-2. Show publish preview
-3. Publish to registry:
+1. Read `./.proagents/active-features/_index.json`
+2. If empty:
    ```
-   Publishing: mypackage@1.3.0
-   ═══════════════════════════
-
-   Pre-checks:
-   ✓ Tests passing
-   ✓ Build successful
-   ✓ Clean working directory
-   ✓ Version tagged (v1.3.0)
-
-   Publishing to npm...
-   ✓ Published successfully!
+   Project Status
+   ══════════════
+   No features tracked.
 
-   https://www.npmjs.com/package/mypackage
+   Start with:
+   → pa:feature "name"
+   → pa:fix "bug"
    ```
-
-### Code Review & PR
-| Command | Action |
-|---------|--------|
-| `pa:review-request` | Request code review from team |
-| `pa:review-request "user"` | Request review from specific user |
-| `pa:review-comments` | Show PR review comments |
-| `pa:review-comments "pr"` | Comments for specific PR |
-| `pa:review-approve` | Approve current PR |
-| `pa:review-approve "pr"` | Approve specific PR |
-
-**How to execute Code Review commands:**
-
-For `pa:review-request`:
-1. Detect current branch and PR status
-2. If no PR exists, suggest creating one first
-3. Get team members from config or git history
-4. Request review:
+3. If has features:
    ```
-   Review Request
+   Project Status
    ══════════════
 
-   PR: #123 - Add user authentication
-   Branch: feature/user-auth
+   Active: [count]
+   • [name] - [phase] ([progress]%)
 
-   Requesting review from:
-   • @tech-lead (suggested - code owner)
-   • @senior-dev (suggested - recent contributor)
-
-   Select reviewers or type username:
-   > @tech-lead, @qa-engineer
-
-   ✓ Review requested from 2 reviewers
-   ```
-
-For `pa:review-comments`:
-1. Get PR comments from GitHub/GitLab
-2. Group by file and status:
+   Paused: [count]
+   Completed: [count]
    ```
-   PR Review Comments
-   ══════════════════
-
-   PR #123: Add user authentication
-   Status: Changes requested (2 pending)
-
-   src/auth/login.ts:
-   ├─ Line 45 [PENDING] @tech-lead:
-   │  "Consider using bcrypt instead of md5 for hashing"
-   │
-   └─ Line 78 [RESOLVED] @qa-engineer:
-      "Add error handling for network failures"
-
-   src/api/users.ts:
-   └─ Line 12 [PENDING] @tech-lead:
-      "Missing input validation"
-
-   Actions:
-   • Reply to comment: pa:review-reply "comment-id" "response"
-   • Resolve comment: pa:review-resolve "comment-id"
-   ```
-
-For `pa:review-approve`:
-1. Check all required checks pass
-2. Verify no pending comments
-3. Approve PR:
-   ```
-   PR Approval
-   ═══════════
-
-   PR #123: Add user authentication
 
-   Checks:
-   ✓ Tests passing
-   ✓ Build successful
-   ✓ No conflicts
-   ⚠ 1 pending comment (optional)
+---
 
-   Approve anyway? [y/N]
+## Detailed Documentation
 
-   ✓ PR approved!
-   Ready to merge.
-   ```
-
-### Architecture
-| Command | Action |
-|---------|--------|
-| `pa:architecture` | Show architecture overview |
-| `pa:architecture "module"` | Architecture for specific module |
-| `pa:architecture-diagram` | Generate architecture diagram |
-| `pa:architecture-export` | Export architecture docs |
+For detailed instructions, read these files:
 
-**How to execute Architecture commands:**
+| Topic | File |
+|-------|------|
+| Command details | `./.proagents/docs/command-details.md` |
+| Workflow guide | `./.proagents/WORKFLOW.md` |
+| Testing config | `./.proagents/docs/testing.md` |
+| Quick reference | `./.proagents/PROAGENTS.md` |
 
-For `pa:architecture`:
-1. Analyze project structure
-2. Identify architectural patterns
-3. Generate overview:
-   ```
-   Architecture Overview
-   ═════════════════════
-
-   Project: my-app
-   Type: Full-stack Next.js
-   Pattern: Clean Architecture + Feature-based
-
-   Layers:
-   ┌─────────────────────────────────────────┐
-   │  Presentation (app/, components/)       │
-   │  ┌───────────────────────────────────┐  │
-   │  │  Application (services/, hooks/)  │  │
-   │  │  ┌─────────────────────────────┐  │  │
-   │  │  │  Domain (types/, entities/) │  │  │
-   │  │  └─────────────────────────────┘  │  │
-   │  └───────────────────────────────────┘  │
-   └─────────────────────────────────────────┘
-
-   Key Components:
-   • API Routes: /app/api/* (15 endpoints)
-   • Pages: /app/* (12 pages)
-   • Components: /components/* (45 components)
-   • Services: /services/* (8 services)
-
-   Dependencies:
-   • Database: PostgreSQL via Prisma
-   • Auth: NextAuth.js with JWT
-   • State: Zustand + React Query
-   • Styling: Tailwind CSS
-
-   Patterns Detected:
-   • Repository Pattern (services/)
-   • Factory Pattern (components/forms/)
-   • Singleton (lib/prisma.ts)
-   ```
+Or ask user: "Should I read the detailed docs for [topic]?"
 
-For `pa:architecture-diagram`:
-1. Generate Mermaid diagram from codebase
-2. Show component relationships:
-   ```mermaid
-   graph TB
-     subgraph Presentation
-       Pages[Pages]
-       Components[Components]
-     end
-
-     subgraph Application
-       Services[Services]
-       Hooks[Hooks]
-     end
-
-     subgraph Infrastructure
-       API[API Routes]
-       DB[(Database)]
-     end
-
-     Pages --> Components
-     Pages --> Hooks
-     Hooks --> Services
-     Services --> API
-     API --> DB
-   ```
-3. Save to `./docs/architecture.md`
+---
 
-### API Testing
-| Command | Action |
-|---------|--------|
-| `pa:api-test` | Test API endpoints |
-| `pa:api-test "endpoint"` | Test specific endpoint |
-| `pa:curl` | Generate curl commands |
-| `pa:curl "endpoint"` | Curl for specific endpoint |
-| `pa:postman` | Generate Postman collection |
-| `pa:postman-export` | Export to Postman file |
-
-**How to execute API Testing commands:**
-
-For `pa:api-test`:
-1. Discover API endpoints from routes
-2. Generate and run tests:
-   ```
-   API Test Results
-   ════════════════
-
-   Testing: /api/*
-   Environment: development (localhost:3000)
-
-   GET /api/users
-   ├─ Status: 200 OK ✓
-   ├─ Time: 45ms
-   └─ Response: Array[10 items]
-
-   POST /api/users
-   ├─ Status: 201 Created ✓
-   ├─ Time: 120ms
-   └─ Response: { id: "123", name: "Test" }
-
-   GET /api/users/:id
-   ├─ Status: 200 OK ✓
-   ├─ Time: 32ms
-   └─ Response: { id: "1", name: "John" }
-
-   DELETE /api/users/:id
-   ├─ Status: 401 Unauthorized ✗
-   ├─ Time: 15ms
-   └─ Error: Missing auth token
-
-   Summary: 3/4 passed (75%)
-   ```
-
-For `pa:curl`:
-1. Analyze API routes and generate curl commands:
-   ```
-   Generated Curl Commands
-   ═══════════════════════
-
-   # List users
-   curl -X GET http://localhost:3000/api/users \
-     -H "Content-Type: application/json" \
-     -H "Authorization: Bearer $TOKEN"
-
-   # Create user
-   curl -X POST http://localhost:3000/api/users \
-     -H "Content-Type: application/json" \
-     -H "Authorization: Bearer $TOKEN" \
-     -d '{"name": "John", "email": "john@example.com"}'
-
-   # Get user by ID
-   curl -X GET http://localhost:3000/api/users/123 \
-     -H "Authorization: Bearer $TOKEN"
-
-   Saved to: ./docs/curl-commands.sh
-   ```
-
-For `pa:postman`:
-1. Scan API routes and extract endpoints
-2. Generate Postman collection:
-   ```
-   Postman Collection Generated
-   ════════════════════════════
-
-   Collection: my-app API
-   Endpoints: 15
-
-   Folders:
-   ├─ Auth (3 endpoints)
-   │  ├─ POST /api/auth/login
-   │  ├─ POST /api/auth/register
-   │  └─ POST /api/auth/logout
-   ├─ Users (5 endpoints)
-   │  ├─ GET /api/users
-   │  ├─ POST /api/users
-   │  ├─ GET /api/users/:id
-   │  ├─ PUT /api/users/:id
-   │  └─ DELETE /api/users/:id
-   └─ Posts (7 endpoints)
-      └─ ...
-
-   Saved to: ./docs/postman-collection.json
-
-   Import: File > Import in Postman
-   ```
-
-### Health & Monitoring
-| Command | Action |
-|---------|--------|
-| `pa:health` | Project health check |
-| `pa:health-full` | Comprehensive health report |
-| `pa:monitor` | Show monitoring status |
-| `pa:monitor "service"` | Monitor specific service |
-| `pa:uptime` | Service uptime check |
-
-**How to execute Health & Monitoring commands:**
-
-For `pa:health`:
-1. Check various project health indicators:
-   ```
-   Project Health Check
-   ════════════════════
-
-   Overall: 85% Healthy ████████░░
-
-   Code Quality:
-   ✓ Linting: No errors
-   ✓ Type checking: No errors
-   ⚠ Test coverage: 72% (target: 80%)
-   ✓ No security vulnerabilities
-
-   Dependencies:
-   ✓ All dependencies installed
-   ⚠ 3 outdated packages
-   ✓ No security advisories
-
-   Configuration:
-   ✓ Environment variables set
-   ✓ Config files valid
-   ⚠ Missing .env.example
-
-   Git Status:
-   ✓ Clean working directory
-   ✓ Up to date with remote
-   ✓ No merge conflicts
-
-   Performance:
-   ✓ Bundle size: 245KB (limit: 500KB)
-   ✓ Build time: 12s
-   ⚠ Lighthouse score: 78 (target: 90)
-
-   Issues Found: 4
-   • Test coverage below 80%
-   • 3 outdated packages
-   • Missing .env.example
-   • Lighthouse score below target
-   ```
-
-For `pa:monitor`:
-1. Check running services and status:
-   ```
-   Service Monitor
-   ═══════════════
-
-   Services:
-   ┌────────────────┬──────────┬─────────┬────────────┐
-   │ Service        │ Status   │ Uptime  │ Health     │
-   ├────────────────┼──────────┼─────────┼────────────┤
-   │ App (Next.js)  │ Running  │ 2h 15m  │ Healthy    │
-   │ Database       │ Running  │ 5d 3h   │ Healthy    │
-   │ Redis Cache    │ Running  │ 5d 3h   │ Healthy    │
-   │ Worker         │ Stopped  │ -       │ ⚠ Down     │
-   └────────────────┴──────────┴─────────┴────────────┘
-
-   Recent Events:
-   • 10:30 - App restarted (deployment)
-   • 09:15 - Worker stopped (manual)
-   • Yesterday - Database backup completed
-
-   Alerts:
-   ⚠ Worker service is not running
-   ```
-
-For `pa:uptime`:
-1. Check endpoint availability:
-   ```
-   Uptime Check
-   ════════════
-
-   Checking endpoints...
-
-   Production (https://myapp.com):
-   ├─ / (homepage): 200 OK (125ms) ✓
-   ├─ /api/health: 200 OK (45ms) ✓
-   ├─ /api/users: 200 OK (89ms) ✓
-   └─ /dashboard: 200 OK (156ms) ✓
-
-   Staging (https://staging.myapp.com):
-   ├─ / (homepage): 200 OK (145ms) ✓
-   └─ /api/health: 200 OK (52ms) ✓
-
-   All endpoints responding ✓
-   Average response time: 102ms
-   ```
-
-### Quick Actions
-| Command | Action |
-|---------|--------|
-| `pa:quick` | Show quick actions menu |
-| `pa:quick "action"` | Execute quick action |
-| `pa:alias` | Manage command aliases |
-| `pa:alias-add "name" "command"` | Add new alias |
-| `pa:alias-remove "name"` | Remove alias |
-
-**How to execute Quick Actions commands:**
-
-For `pa:quick`:
-1. Show context-aware quick actions:
-   ```
-   Quick Actions
-   ═════════════
-
-   Based on current context (feature/user-auth):
-
-   Development:
-   [1] Run tests for current feature
-   [2] Check code coverage
-   [3] Lint and fix
-
-   Git:
-   [4] Commit all changes
-   [5] Push to remote
-   [6] Create PR
-
-   Quality:
-   [7] Run full QA check
-   [8] Security scan
-   [9] Performance audit
-
-   Documentation:
-   [10] Update docs for changes
-
-   Select action (1-10) or type command:
-   > 6
-
-   Creating PR...
-   ```
-
-For `pa:alias`:
-1. List and manage command aliases:
-   ```
-   Command Aliases
-   ═══════════════
-
-   Current Aliases:
-   ┌──────────┬───────────────────────────┐
-   │ Alias    │ Command                   │
-   ├──────────┼───────────────────────────┤
-   │ pa:c     │ pa:commit                 │
-   │ pa:pr    │ pa:github-pr              │
-   │ pa:cov   │ pa:coverage               │
-   │ pa:sec   │ pa:security-scan          │
-   │ pa:up    │ pa:deps-outdated          │
-   └──────────┴───────────────────────────┘
-
-   Add alias: pa:alias-add "name" "command"
-   Remove: pa:alias-remove "name"
-
-   Built-in aliases cannot be modified:
-   pa:f, pa:s, pa:h, pa:d, pa:t, pa:q, pa:a, pa:r, pa:p, pa:i
-   ```
-
-For `pa:alias-add`:
-1. Add custom alias:
-   ```
-   Adding Alias
-   ════════════
-
-   Alias: pa:ship
-   Command: pa:test && pa:build && pa:deploy
-
-   ✓ Alias created!
-
-   Usage: pa:ship
-   Runs: pa:test && pa:build && pa:deploy
-   ```
-
-### Platform-Specific Test Suites
-
-**Mobile (React Native / Expo):**
-| Command | Action |
-|---------|--------|
-| `pa:test-mobile` | Run full mobile test suite |
-| `pa:test-mobile "feature"` | Test specific feature |
-
-**Web (React / Next.js / Vue / etc.):**
-| Command | Action |
-|---------|--------|
-| `pa:test-web` | Run full web test suite |
-| `pa:test-web "feature"` | Test specific web feature |
-
-**API / Backend (Node.js / Python / etc.):**
-| Command | Action |
-|---------|--------|
-| `pa:test-api` | Run full API/backend test suite |
-| `pa:test-api "endpoint"` | Test specific API endpoint |
-
-**Visual & Comparison:**
-| Command | Action |
-|---------|--------|
-| `pa:test-visual` | Visual/design comparison testing |
-| `pa:compare-figma` | Compare UI against Figma design |
-| `pa:compare-image "path"` | Compare UI against image/sketch |
-| `pa:screenshot` | Take app screenshots for comparison |
-
-**Auto-Fix:**
-| Command | Action |
-|---------|--------|
-| `pa:test-auto-fix` | Auto-fix failing tests |
-| `pa:test-loop` | Test → Fix → Retest loop until success |
-
-**How to execute Mobile Test Suite commands:**
-
-For `pa:test-mobile`:
-
-**Supports ALL mobile platforms:**
-- React Native / Expo
-- Native Android (Kotlin/Java)
-- Native iOS (Swift/Objective-C)
-- Flutter (Dart)
-
-1. **Detect project type automatically:**
-   ```
-   Detecting mobile project type...
-
-   Checking for:
-   ├── package.json + react-native → React Native
-   ├── android/build.gradle (no RN) → Native Android
-   ├── ios/*.xcodeproj (no RN) → Native iOS
-   ├── pubspec.yaml → Flutter
-
-   Detected: [PROJECT_TYPE]
-   ```
-
-2. **Check & auto-install required tools based on platform:**
-
-   **React Native / Expo:**
-   ```
-   ✓ Node.js
-   ✓ Jest / Vitest
-   ✓ React Native Testing Library
-   ✗ MISSING: Maestro → Auto-installing...
-   ✗ MISSING: Detox → Auto-installing...
-   ```
-
-   **Native Android (Kotlin/Java):**
-   ```
-   ✓ Android Studio / Gradle
-   ✓ JUnit
-   ✗ MISSING: Espresso → Auto-adding to build.gradle
-   ✗ MISSING: UI Automator → Auto-adding to build.gradle
-   ✗ MISSING: Maestro → Auto-installing...
-   ```
-
-   **Native iOS (Swift/Objective-C):**
-   ```
-   ✓ Xcode
-   ✓ XCTest (built-in)
-   ✓ XCUITest (built-in)
-   ✗ MISSING: Maestro → Auto-installing...
-   ```
-
-   **Flutter:**
-   ```
-   ✓ Flutter SDK
-   ✓ flutter_test (built-in)
-   ✗ MISSING: integration_test → Auto-adding to pubspec.yaml
-   ✗ MISSING: Maestro → Auto-installing...
-   ```
-
-   **IMPORTANT - FULL AUTOMATION:**
-   - Missing tools? **Install automatically** (no confirmation)
-   - Tests fail? **Fix automatically** (no confirmation)
-   - Fix doesn't work? **Try alternative fix** (no confirmation)
-   - Only stop when: all tests pass OR no fix possible
-
-   **Just DO it.**
-
-3. **Run platform-specific test suite:**
-
-   **For React Native:**
-   ```
-   Mobile Test Suite
-   ═════════════════
-
-   Running full test suite for: feature/user-auth
-
-   Phase 1: Unit Tests
-   ───────────────────
-   ✓ AuthService.login() - 5 tests passed
-   ✓ AuthService.logout() - 3 tests passed
-   ✓ TokenManager - 8 tests passed
-   ✓ UserStore - 12 tests passed
-
-   Phase 2: Component Tests
-   ────────────────────────
-   ✓ LoginScreen - renders correctly
-   ✓ LoginScreen - validates email format
-   ✓ LoginScreen - shows error on invalid credentials
-   ✓ SignupScreen - all fields required
-   ✓ ProfileScreen - displays user data
-
-   Phase 3: Integration Tests
-   ──────────────────────────
-   ✓ Login flow end-to-end
-   ✓ Token refresh on expiry
-   ✓ Logout clears all data
-   ✗ FAILED: Password reset flow
-     → Error: Reset email not sent
-
-   Phase 4: E2E Tests (Maestro/Detox)
-   ──────────────────────────────────
-   ✓ User can login with valid credentials
-   ✓ User sees error with invalid password
-   ✗ FAILED: User can reset password
-     → Button not found: "Send Reset Email"
-
-   Phase 5: Visual Tests
-   ─────────────────────
-   ✓ LoginScreen matches design
-   ✗ FAILED: SignupScreen has visual differences
-     → Button color: expected #007AFF, got #0066CC
-     → Font size: expected 16px, got 14px
-
-   ══════════════════════════════════════════
-   RESULTS: 35/38 tests passed (3 failed)
-   ══════════════════════════════════════════
-
-   Failed Tests:
-   1. Integration: Password reset flow
-   2. E2E: User can reset password
-   3. Visual: SignupScreen design mismatch
-
-   ══════════════════════════════════════════
-   AUTO-FIX: Attempting to fix 3 failed tests...
-   ══════════════════════════════════════════
-   ```
-
-3. **Automatically fix all failures** (no confirmation needed):
-   ```
-   ══════════════════════════════════════════
-   AUTO-FIX: Fixing 3 failed tests...
-   ══════════════════════════════════════════
-
-   Fix 1/3: Integration - Password reset flow
-   ──────────────────────────────────────────
-   Root cause: ResetEmailService.send() not called
-   Fixing: src/services/AuthService.ts:142
-   → Added: await this.resetEmailService.send(email)
-   Re-running test... ✓ PASSED
-
-   Fix 2/3: E2E - User can reset password
-   ──────────────────────────────────────────
-   Root cause: Button text mismatch
-   Fixing: src/screens/ResetPassword.tsx:28
-   → Changed: "Reset" → "Send Reset Email"
-   Re-running test... ✓ PASSED
-
-   Fix 3/3: Visual - SignupScreen design mismatch
-   ──────────────────────────────────────────
-   Root cause: Wrong color and font size
-   Fixing: src/screens/SignupScreen.styles.ts:15-16
-   → Changed: color #0066CC → #007AFF
-   → Changed: fontSize 14px → 16px
-   Re-running test... ✓ PASSED
-
-   ══════════════════════════════════════════
-   ALL TESTS PASSING: 38/38 ✓
-   ══════════════════════════════════════════
-   ```
-
-   **For Native Android (Kotlin/Java):**
-   ```
-   Android Test Suite
-   ══════════════════
-
-   Phase 1: Unit Tests (JUnit)
-   ───────────────────────────
-   Running: ./gradlew test
-   ✓ UserRepositoryTest - 8 passed
-   ✓ AuthViewModelTest - 12 passed
-   ✓ PaymentServiceTest - 6 passed
-
-   Phase 2: Instrumented Tests (Espresso)
-   ──────────────────────────────────────
-   Running: ./gradlew connectedAndroidTest
-   ✓ LoginActivityTest - UI renders correctly
-   ✓ MainActivityTest - Navigation works
-   ✗ FAILED: CheckoutActivityTest - Button not found
-
-   AUTO-FIX: Analyzing failure...
-   Root cause: Button ID changed
-   Fixing: app/src/main/res/layout/activity_checkout.xml
-   → Changed: android:id="@+id/btn_pay" → android:id="@+id/checkout_button"
-   Fixing: app/src/androidTest/.../CheckoutActivityTest.kt
-   → Changed: R.id.btn_pay → R.id.checkout_button
-   Re-running test... ✓ PASSED
-
-   Phase 3: UI Tests (UI Automator)
-   ─────────────────────────────────
-   ✓ Full checkout flow
-   ✓ User settings update
-   ✓ Push notification handling
-
-   Phase 4: E2E Tests (Maestro)
-   ────────────────────────────
-   Running: maestro test .maestro/
-   ✓ User login flow
-   ✓ Product purchase flow
-
-   ══════════════════════════════════════════
-   ALL TESTS PASSING: 32/32 ✓
-   ══════════════════════════════════════════
-   ```
-
-   **For Native iOS (Swift/Objective-C):**
-   ```
-   iOS Test Suite
-   ══════════════
-
-   Phase 1: Unit Tests (XCTest)
-   ────────────────────────────
-   Running: xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'
-   ✓ UserServiceTests - 10 passed
-   ✓ AuthManagerTests - 8 passed
-   ✓ NetworkClientTests - 12 passed
-
-   Phase 2: UI Tests (XCUITest)
-   ────────────────────────────
-   ✓ LoginViewControllerTests - UI renders
-   ✓ HomeViewControllerTests - Navigation works
-   ✗ FAILED: ProfileViewControllerTests - Label not found
-
-   AUTO-FIX: Analyzing failure...
-   Root cause: Accessibility identifier missing
-   Fixing: ProfileViewController.swift:45
-   → Added: nameLabel.accessibilityIdentifier = "profile_name_label"
-   Re-running test... ✓ PASSED
-
-   Phase 3: E2E Tests (Maestro)
-   ────────────────────────────
-   Running: maestro test .maestro/
-   ✓ Onboarding flow
-   ✓ Purchase flow
-   ✓ Settings update
-
-   ══════════════════════════════════════════
-   ALL TESTS PASSING: 28/28 ✓
-   ══════════════════════════════════════════
-   ```
-
-   **For Flutter (Dart):**
-   ```
-   Flutter Test Suite
-   ══════════════════
-
-   Phase 1: Unit Tests
-   ───────────────────
-   Running: flutter test test/unit/
-   ✓ user_repository_test.dart - 8 passed
-   ✓ auth_bloc_test.dart - 15 passed
-   ✓ api_client_test.dart - 10 passed
-
-   Phase 2: Widget Tests
-   ─────────────────────
-   Running: flutter test test/widget/
-   ✓ login_screen_test.dart - renders correctly
-   ✓ home_screen_test.dart - shows user data
-   ✗ FAILED: cart_screen_test.dart - widget not found
-
-   AUTO-FIX: Analyzing failure...
-   Root cause: Key not set on widget
-   Fixing: lib/screens/cart_screen.dart:67
-   → Added: key: const Key('checkout_button')
-   Re-running test... ✓ PASSED
-
-   Phase 3: Integration Tests
-   ──────────────────────────
-   Running: flutter test integration_test/
-   ✓ app_test.dart - Full app flow
-   ✓ checkout_test.dart - Purchase complete
-
-   Phase 4: E2E Tests (Maestro)
-   ────────────────────────────
-   Running: maestro test .maestro/
-   ✓ User registration
-   ✓ Product browsing
-   ✓ Checkout flow
-
-   ══════════════════════════════════════════
-   ALL TESTS PASSING: 42/42 ✓
-   ══════════════════════════════════════════
-   ```
-
-4. If a fix cannot be applied automatically:
-   ```
-   ✗ Cannot auto-fix: Database schema mismatch
-   Reason: Requires migration file and database access
-
-   Manual action needed:
-   → Run: npx prisma migrate dev --name fix_user_table
-   ```
-
-5. Generate detailed test report at `./.proagents/test-reports/mobile-{timestamp}.md`
-
-For `pa:test-web`:
-1. **Check required tools and auto-install:**
-   ```
-   Checking required tools...
-   ✓ Node.js
-   ✓ Vitest / Jest
-   ✗ MISSING: Playwright
-
-   Auto-installing Playwright...
-   → npx playwright install
-   ✓ Playwright installed
-   ```
-
-2. **Run full web test suite:**
-   ```
-   Web Test Suite
-   ══════════════
-
-   Phase 1: Unit Tests (Vitest/Jest)
-   ──────────────────────────────────
-   Running: npm test
-   ✓ utils/formatDate.test.ts - 5 passed
-   ✓ hooks/useAuth.test.ts - 8 passed
-   ✓ services/api.test.ts - 12 passed
-
-   Phase 2: Component Tests
-   ────────────────────────
-   ✓ Button.test.tsx - renders correctly
-   ✓ Form.test.tsx - validates inputs
-   ✗ FAILED: Modal.test.tsx - close handler
-
-   AUTO-FIX: Analyzing failure...
-   Root cause: onClose prop not called
-   Fixing: src/components/Modal.tsx:24
-   → Added: onClick={() => onClose?.()}
-   Re-running test... ✓ PASSED
-
-   Phase 3: Integration Tests
-   ──────────────────────────
-   ✓ Login flow
-   ✓ Checkout process
-   ✓ User settings update
-
-   Phase 4: E2E Tests (Playwright)
-   ────────────────────────────────
-   Running: npx playwright test
-   ✓ Homepage loads correctly
-   ✓ User can login
-   ✓ User can add to cart
-   ✗ FAILED: Checkout completes
-
-   AUTO-FIX: Analyzing failure...
-   Root cause: Submit button selector changed
-   Fixing: e2e/checkout.spec.ts:45
-   → Changed: 'button.submit' → 'button[type="submit"]'
-   Re-running test... ✓ PASSED
-
-   Phase 5: Visual Regression (Percy/Playwright)
-   ──────────────────────────────────────────────
-   ✓ Homepage - no visual changes
-   ✓ Product page - no visual changes
-   ✗ FAILED: Cart page - button color changed
-
-   AUTO-FIX: Analyzing failure...
-   Root cause: CSS variable override
-   Fixing: src/styles/cart.css:12
-   → Changed: --btn-color: blue → --btn-color: var(--primary)
-   Re-running test... ✓ PASSED
-
-   ══════════════════════════════════════════
-   ALL TESTS PASSING: 45/45 ✓
-   ══════════════════════════════════════════
-   ```
-
-3. Generate detailed test report at `./.proagents/test-reports/web-{timestamp}.md`
-
-For `pa:test-api`:
-1. **Check required tools and auto-install:**
-   ```
-   Checking required tools...
-   ✓ Node.js / Python
-   ✓ Jest / Pytest
-   ✗ MISSING: Supertest
-   ✗ MISSING: k6 (load testing)
-
-   Auto-installing...
-   → npm install --save-dev supertest
-   → brew install k6
-   ✓ All tools installed
-   ```
-
-2. **Run full API test suite:**
-   ```
-   API Test Suite
-   ══════════════
-
-   Phase 1: Unit Tests
-   ───────────────────
-   ✓ UserService - 12 tests passed
-   ✓ AuthService - 8 tests passed
-   ✓ PaymentService - 15 tests passed
-
-   Phase 2: Integration Tests
-   ──────────────────────────
-   Testing: GET /api/users
-   ✓ Returns 200 with user list
-   ✓ Supports pagination
-   ✓ Filters by role
-
-   Testing: POST /api/auth/login
-   ✓ Returns token on valid credentials
-   ✓ Returns 401 on invalid password
-   ✗ FAILED: Returns 429 on rate limit
-
-   AUTO-FIX: Analyzing failure...
-   Root cause: Rate limiter not configured in test env
-   Fixing: src/middleware/rateLimit.ts:8
-   → Added: if (process.env.NODE_ENV === 'test') return next()
-   Re-running test... ✓ PASSED
-
-   Phase 3: Contract Tests
-   ───────────────────────
-   Validating OpenAPI spec...
-   ✓ GET /api/users matches schema
-   ✓ POST /api/users matches schema
-   ✗ FAILED: PUT /api/users/:id - missing field
-
-   AUTO-FIX: Analyzing failure...
-   Root cause: Response missing 'updatedAt' field
-   Fixing: src/controllers/userController.ts:89
-   → Added: updatedAt: user.updatedAt to response
-   Re-running test... ✓ PASSED
-
-   Phase 4: Load Tests (k6)
-   ────────────────────────
-   Running: k6 run loadtest.js
-   ✓ 100 VUs, 30s duration
-   ✓ p95 response time: 145ms (< 200ms threshold)
-   ✓ Error rate: 0.1% (< 1% threshold)
-   ✓ Throughput: 850 req/s
-
-   Phase 5: Security Tests
-   ───────────────────────
-   ✓ SQL injection: Protected
-   ✓ XSS: Protected
-   ✓ CSRF: Protected
-   ✗ FAILED: Rate limiting on /api/auth/login
-
-   AUTO-FIX: Analyzing failure...
-   Root cause: Rate limit too high (1000 req/min)
-   Fixing: src/config/security.ts:15
-   → Changed: loginRateLimit: 1000 → loginRateLimit: 10
-   Re-running test... ✓ PASSED
-
-   ══════════════════════════════════════════
-   ALL TESTS PASSING: 52/52 ✓
-   ══════════════════════════════════════════
-   ```
-
-3. Generate detailed test report at `./.proagents/test-reports/api-{timestamp}.md`
-
-For `pa:test-visual`:
-1. Take screenshots of all screens/components
-2. Compare against design references:
-   ```
-   Visual Design Testing
-   ═════════════════════
-
-   Comparing app UI against design references...
-
-   Design Source: ./designs/ (Figma exports)
-
-   Screen: LoginScreen
-   ───────────────────
-   ✓ Layout matches design
-   ✓ Colors match design tokens
-   ✓ Typography correct
-   ✓ Spacing/padding correct
-   ✓ Button styles match
-
-   Screen: SignupScreen
-   ────────────────────
-   ✗ MISMATCH DETECTED
-
-   Differences found:
-   ┌─────────────────┬──────────────┬──────────────┐
-   │ Element         │ Expected     │ Actual       │
-   ├─────────────────┼──────────────┼──────────────┤
-   │ Submit Button   │ #007AFF      │ #0066CC      │
-   │ Title Font      │ 24px Bold    │ 22px Regular │
-   │ Input Height    │ 48px         │ 44px         │
-   │ Bottom Margin   │ 16px         │ 12px         │
-   └─────────────────┴──────────────┴──────────────┘
-
-   Screenshot saved: ./.proagents/test-reports/visual/signup-diff.png
-
-   Screen: ProfileScreen
-   ─────────────────────
-   ✓ All elements match design
-
-   ══════════════════════════════════════════
-   VISUAL TEST RESULTS: 2/3 screens passed
-   ══════════════════════════════════════════
-
-   Run `pa:test-auto-fix` to fix visual issues automatically.
-   ```
-
-For `pa:test-auto-fix`:
-1. Analyze failing tests
-2. Identify root cause
-3. Generate and apply fixes:
-   ```
-   Auto-Fix Mode
-   ═════════════
-
-   Analyzing 3 failing tests...
-
-   Fix 1: Password reset flow
-   ──────────────────────────
-   Root Cause: API endpoint missing in AuthService
-
-   Applying fix to: src/services/AuthService.ts
-   + async resetPassword(email: string): Promise<void> {
-   +   const response = await api.post('/auth/reset-password', { email });
-   +   if (!response.ok) throw new Error('Reset failed');
-   + }
-
-   ✓ Fix applied
-
-   Fix 2: Reset button not found
-   ─────────────────────────────
-   Root Cause: Button testID missing
-
-   Applying fix to: src/screens/ResetPasswordScreen.tsx
-   - <Button title="Send Reset Email" onPress={handleReset} />
-   + <Button
-   +   testID="send-reset-email-button"
-   +   title="Send Reset Email"
-   +   onPress={handleReset}
-   + />
-
-   ✓ Fix applied
-
-   Fix 3: SignupScreen visual mismatch
-   ────────────────────────────────────
-   Root Cause: Style values don't match design tokens
-
-   Applying fix to: src/screens/SignupScreen.styles.ts
-   - submitButton: { backgroundColor: '#0066CC' }
-   + submitButton: { backgroundColor: '#007AFF' }
-
-   - title: { fontSize: 22, fontWeight: 'normal' }
-   + title: { fontSize: 24, fontWeight: 'bold' }
-
-   - input: { height: 44, marginBottom: 12 }
-   + input: { height: 48, marginBottom: 16 }
-
-   ✓ Fix applied
-
-   ══════════════════════════════════════════
-   AUTO-FIX COMPLETE: 3/3 issues fixed
-   ══════════════════════════════════════════
-
-   Running verification tests...
-   ```
-
-4. **Learn from fixes** - Store successful fixes for future use:
-   ```
-   Saving fix patterns to .proagents/.learning/fixes.json...
-
-   New patterns learned:
-   ┌────────────────────┬────────────────────────────────────────┐
-   │ Error Pattern      │ Fix Pattern                            │
-   ├────────────────────┼────────────────────────────────────────┤
-   │ "undefined" error  │ Add null check before access           │
-   │ testID not found   │ Add testID prop to component           │
-   │ color mismatch     │ Use design token instead of hex        │
-   │ rate limit fail    │ Disable in test environment            │
-   │ schema mismatch    │ Add missing field to response          │
-   └────────────────────┴────────────────────────────────────────┘
-
-   ✓ 5 fix patterns saved
-   ```
-
-**Auto-Fix Intelligence:**
-
-The AI learns from previous fixes to apply them faster:
-
-1. **Pattern Database** - Stored in `.proagents/.learning/`:
-   ```
-   .proagents/.learning/
-   ├── fixes.json           # Successful fix patterns
-   ├── errors.json          # Common error patterns
-   └── project-patterns.json # Project-specific patterns
-   ```
-
-2. **Fix Matching** - When a test fails:
-   ```
-   Analyzing failure: "Cannot read property 'id' of undefined"
-
-   Checking learned patterns...
-   ✓ Match found: "undefined property access"
-
-   Applying known fix:
-   → Add optional chaining: user?.id
-
-   Confidence: 95% (applied 12 times before, 100% success rate)
-   ```
-
-3. **Learning from Corrections** - If AI fix is wrong:
-   ```
-   User corrected fix:
-   - AI suggested: user?.id ?? 'default'
-   - User changed to: user?.id || throw new Error('User required')
-
-   Learning...
-   → Updated pattern: In auth contexts, throw error instead of default
-   → Saved to .proagents/.learning/corrections.json
-   ```
-
-4. **Project-Specific Learning**:
-   - Learns project conventions (e.g., "this project uses Zod for validation")
-   - Remembers file structure patterns
-   - Knows which solutions worked in this codebase
-
-For `pa:test-loop`:
-1. Run complete Test → Fix → Retest cycle:
-   ```
-   Test Loop Mode
-   ══════════════
-
-   Starting automated test-fix-retest cycle...
-   Max iterations: 5
-
-   ┌─────────────────────────────────────────────────────┐
-   │ ITERATION 1                                         │
-   ├─────────────────────────────────────────────────────┤
-   │ Running tests...                                    │
-   │ Results: 35/38 passed (3 failed)                   │
-   │                                                     │
-   │ Analyzing failures...                               │
-   │ Applying auto-fixes...                              │
-   │ Fixes applied: 3                                    │
-   └─────────────────────────────────────────────────────┘
-
-   ┌─────────────────────────────────────────────────────┐
-   │ ITERATION 2                                         │
-   ├─────────────────────────────────────────────────────┤
-   │ Running tests...                                    │
-   │ Results: 37/38 passed (1 failed)                   │
-   │                                                     │
-   │ Analyzing failures...                               │
-   │ New issue: TypeScript type error after fix         │
-   │ Applying auto-fixes...                              │
-   │ Fixes applied: 1                                    │
-   └─────────────────────────────────────────────────────┘
-
-   ┌─────────────────────────────────────────────────────┐
-   │ ITERATION 3                                         │
-   ├─────────────────────────────────────────────────────┤
-   │ Running tests...                                    │
-   │ Results: 38/38 passed (0 failed)                   │
-   │                                                     │
-   │ ✓ ALL TESTS PASSING!                               │
-   └─────────────────────────────────────────────────────┘
-
-   ══════════════════════════════════════════════════════
-   TEST LOOP COMPLETE
-   ══════════════════════════════════════════════════════
-
-   Summary:
-   ────────
-   Iterations: 3
-   Initial failures: 3
-   Fixes applied: 4
-   Final status: ALL PASSING ✓
-
-   Files modified:
-   • src/services/AuthService.ts
-   • src/screens/ResetPasswordScreen.tsx
-   • src/screens/SignupScreen.styles.ts
-   • src/types/auth.ts
-
-   Test report: ./.proagents/test-reports/test-loop-{timestamp}.md
-
-   Ready for commit? (y/n)
-   ```
-
-For `pa:compare-figma`:
-1. Connect to Figma API or use exported frames
-2. Extract design specifications
-3. Compare with actual app:
-   ```
-   Figma Design Comparison
-   ═══════════════════════
-
-   Design Source: [Figma Link or ./designs/figma-export/]
-
-   Extracting design tokens from Figma...
-   ✓ Colors extracted
-   ✓ Typography extracted
-   ✓ Spacing system extracted
-   ✓ Component specs extracted
-
-   Comparing: LoginScreen
-   ──────────────────────
-
-   Layout Comparison:
-   ┌────────────────────┬────────────────────┐
-   │   Figma Design     │   App Screenshot   │
-   │   ┌──────────┐     │   ┌──────────┐     │
-   │   │  Logo    │     │   │  Logo    │ ✓   │
-   │   ├──────────┤     │   ├──────────┤     │
-   │   │  Email   │     │   │  Email   │ ✓   │
-   │   │  Input   │     │   │  Input   │     │
-   │   ├──────────┤     │   ├──────────┤     │
-   │   │ Password │     │   │ Password │ ✓   │
-   │   │  Input   │     │   │  Input   │     │
-   │   ├──────────┤     │   ├──────────┤     │
-   │   │  Login   │     │   │  Login   │ ✗   │
-   │   │  Button  │     │   │  Button  │     │
-   │   └──────────┘     │   └──────────┘     │
-   └────────────────────┴────────────────────┘
-
-   Detailed Comparison:
-   ┌───────────────┬─────────────┬─────────────┬────────┐
-   │ Element       │ Figma       │ App         │ Status │
-   ├───────────────┼─────────────┼─────────────┼────────┤
-   │ Logo Size     │ 120x40      │ 120x40      │ ✓      │
-   │ Input Height  │ 48px        │ 48px        │ ✓      │
-   │ Input Border  │ 1px #E0E0E0 │ 1px #E0E0E0 │ ✓      │
-   │ Button Color  │ #007AFF     │ #0056B3     │ ✗      │
-   │ Button Radius │ 8px         │ 4px         │ ✗      │
-   │ Button Height │ 52px        │ 48px        │ ✗      │
-   │ Vertical Gap  │ 16px        │ 12px        │ ✗      │
-   └───────────────┴─────────────┴─────────────┴────────┘
-
-   Issues Found: 4
-
-   Auto-fix available? Yes
-   Run `pa:test-auto-fix` to apply design corrections.
-   ```
-
-For `pa:compare-image "path"`:
-1. Load reference image (sketch, screenshot, mockup)
-2. Use visual comparison:
-   ```
-   Image Comparison
-   ════════════════
-
-   Reference: ./designs/sketch-login.png
-   App Screen: LoginScreen
-
-   Analyzing reference image...
-   ✓ Detected UI elements
-   ✓ Extracted layout structure
-   ✓ Identified colors and typography
-
-   Taking app screenshot...
-   ✓ Screenshot captured
-
-   Visual Diff Analysis:
-   ─────────────────────
-
-   Overall Match: 87%
-
-   Differences Detected:
-
-   1. Header Section (Region: 0,0 to 375,100)
-      • Logo position: slightly lower than reference
-      • Background: matches ✓
-
-   2. Form Section (Region: 0,100 to 375,350)
-      • Input fields: match ✓
-      • Labels: font slightly smaller
-      • Spacing: compressed by ~4px
-
-   3. Button Section (Region: 0,350 to 375,450)
-      • Color: differs by 15% (darker in app)
-      • Corner radius: sharper in app
-      • Shadow: missing in app
-
-   Diff image saved: ./.proagents/test-reports/visual/login-diff-overlay.png
-
-   ┌─────────────────────────────────────────────┐
-   │ [Reference]        │ [App]        │ [Diff] │
-   │ Expected design    │ Actual app   │ Δ      │
-   └─────────────────────────────────────────────┘
-
-   Suggested fixes generated.
-   Run `pa:test-auto-fix` to apply.
-   ```
-
-For `pa:screenshot`:
-1. Capture screenshots of all app screens:
-   ```
-   Screenshot Capture
-   ══════════════════
-
-   Detecting available screens...
-
-   Found 12 screens in navigation:
-
-   Capturing screenshots...
-
-   ✓ LoginScreen → ./.proagents/screenshots/LoginScreen.png
-   ✓ SignupScreen → ./.proagents/screenshots/SignupScreen.png
-   ✓ HomeScreen → ./.proagents/screenshots/HomeScreen.png
-   ✓ ProfileScreen → ./.proagents/screenshots/ProfileScreen.png
-   ✓ SettingsScreen → ./.proagents/screenshots/SettingsScreen.png
-   ✓ NotificationsScreen → ./.proagents/screenshots/NotificationsScreen.png
-   ... (6 more)
-
-   Component screenshots:
-   ✓ Button variants → ./.proagents/screenshots/components/Button.png
-   ✓ Input variants → ./.proagents/screenshots/components/Input.png
-   ✓ Card variants → ./.proagents/screenshots/components/Card.png
-
-   ══════════════════════════════════════════
-   Screenshots saved: 15 images
-   Location: ./.proagents/screenshots/
-   ══════════════════════════════════════════
-
-   Use these for:
-   • Visual regression testing
-   • Design comparison with `pa:compare-image`
-   • Documentation
-   ```
-
-**Mobile Test Configuration:**
-Add to `proagents.config.yaml`:
-```yaml
-mobile_testing:
-  platform: react-native  # or flutter, native
-
-  test_frameworks:
-    unit: jest
-    component: "@testing-library/react-native"
-    e2e: maestro  # or detox, appium
-
-  visual_testing:
-    enabled: true
-    design_source: figma  # or ./designs/
-    figma_file_id: "your-figma-file-id"  # if using Figma
-    threshold: 0.95  # 95% match required
-
-  auto_fix:
-    enabled: true
-    max_iterations: 5
-    require_approval: false  # true = ask before applying fixes
-
-  screenshot:
-    output_dir: ./.proagents/screenshots
-    devices:
-      - iPhone 14 Pro
-      - Pixel 7
-
-  test_on:
-    feature_complete: true  # auto-run tests when feature done
-    bug_fix: true  # auto-run tests after bug fix
-    pre_commit: false  # run before git commit
-```
-
-**Test Report Structure:**
-```
-./.proagents/test-reports/
-├── mobile-2024-03-06-1500.md      # Full test report
-├── visual/
-│   ├── LoginScreen-diff.png       # Visual diff images
-│   ├── SignupScreen-diff.png
-│   └── comparison-report.md
-├── coverage/
-│   └── coverage-report.html       # Test coverage
-└── auto-fix-log.md                # Log of all auto-fixes
-```
-
-### Custom Testing Tools Configuration
-
-Users can configure their own testing tools in `proagents.config.yaml`. **AI MUST check and use these custom tools** instead of defaults.
-
-**Read custom tools from config:**
-```yaml
-# proagents.config.yaml → testing.tools section
-testing:
-  tools:
-    unit:
-      command: "npm test"           # Custom unit test command
-      framework: "jest"             # jest | vitest | mocha | pytest | junit | xctest
-    integration:
-      command: "npm run test:integration"
-      framework: "jest"
-    e2e:
-      command: "npx playwright test"
-      framework: "playwright"       # playwright | cypress | maestro | detox
-    visual:
-      command: "npx percy exec -- npm test"
-      framework: "percy"            # percy | chromatic | applitools
-    load:
-      command: "k6 run loadtest.js"
-      framework: "k6"               # k6 | artillery | locust | jmeter
-    security:
-      command: "npm audit && snyk test"
-      framework: "snyk"             # snyk | npm-audit | owasp-zap
-
-  auto_install: true   # Auto-install missing tools
-
-  custom_commands:     # User shortcuts
-    "test:quick": "npm test -- --onlyChanged"
-    "test:ci": "npm test -- --coverage --ci"
-```
-
-**How AI uses custom tools:**
-
-For `pa:test`, `pa:test-mobile`, `pa:test-web`, `pa:test-api`:
-
-1. **Read proagents.config.yaml first:**
-   ```
-   Loading test configuration...
-
-   Custom tools configured:
-   ├── Unit: npm test (jest)
-   ├── Integration: npm run test:integration (jest)
-   ├── E2E: npx playwright test (playwright)
-   ├── Visual: npx percy exec -- npm test (percy)
-   ├── Load: k6 run loadtest.js (k6)
-   └── Security: npm audit && snyk test (snyk)
-   ```
-
-2. **Use custom command instead of default:**
-   ```
-   Running Unit Tests
-   ══════════════════
-
-   Using custom command: npm test
-   Framework: jest
-
-   > npm test
-
-   PASS  src/__tests__/auth.test.ts
-   PASS  src/__tests__/user.test.ts
-   ...
-   ```
-
-3. **Auto-install if tool missing and auto_install: true:**
-   ```
-   Tool not found: k6
-   Config: auto_install: true
-
-   Installing k6...
-   ✓ k6 installed successfully
-
-   Running load tests...
-   ```
-
-4. **Support custom_commands shortcuts:**
-   ```
-   User runs: pa:test quick
-
-   Checking custom_commands...
-   Found: "test:quick" → "npm test -- --onlyChanged"
-
-   Running: npm test -- --onlyChanged
-   ```
-
-**Mobile Testing Tools (platform-specific):**
-
-For `pa:test-mobile`, read the `testing.mobile` section:
-
-```yaml
-# proagents.config.yaml → testing.mobile section
-testing:
-  mobile:
-    # React Native / Expo
-    react_native:
-      unit:
-        command: "npm test"
-        framework: "jest"
-      component:
-        command: "npm test -- --testPathPattern=components"
-        framework: "@testing-library/react-native"
-      e2e:
-        command: "maestro test .maestro/"
-        framework: "maestro"          # maestro | detox | appium
-
-    # Native Android (Kotlin/Java)
-    android:
-      unit:
-        command: "./gradlew test"
-        framework: "junit"
-      integration:
-        command: "./gradlew connectedAndroidTest"
-        framework: "espresso"
-      e2e:
-        command: "maestro test .maestro/"
-        framework: "maestro"
-
-    # Native iOS (Swift/Objective-C)
-    ios:
-      unit:
-        command: "xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'"
-        framework: "xctest"
-      e2e:
-        command: "maestro test .maestro/"
-        framework: "maestro"
-
-    # Flutter
-    flutter:
-      unit:
-        command: "flutter test"
-        framework: "flutter_test"
-      integration:
-        command: "flutter test integration_test/"
-        framework: "integration_test"
-      e2e:
-        command: "maestro test .maestro/"
-        framework: "maestro"
-```
-
-**How AI uses mobile tools:**
-
-1. **Detect platform first:**
-   ```
-   Detecting mobile project type...
-
-   Checking for:
-   ├── package.json + react-native → React Native
-   ├── android/build.gradle (no RN) → Native Android
-   ├── ios/*.xcodeproj (no RN) → Native iOS
-   ├── pubspec.yaml → Flutter
-
-   Detected: React Native
-   ```
-
-2. **Read platform-specific config:**
-   ```
-   Loading config: testing.mobile.react_native
-
-   Tools:
-   ├── Unit: npm test (jest)
-   ├── Component: npm test -- --testPathPattern=components
-   └── E2E: maestro test .maestro/ (maestro)
-   ```
-
-3. **Run with configured commands:**
-   ```
-   Running React Native Test Suite
-   ═══════════════════════════════
-
-   Phase 1: Unit Tests
-   > npm test
-   ✓ 45 tests passed
-
-   Phase 2: Component Tests
-   > npm test -- --testPathPattern=components
-   ✓ 23 tests passed
-
-   Phase 3: E2E Tests
-   > maestro test .maestro/
-   ✓ 12 flows passed
-   ```
-
-**Default fallbacks (if no custom config):**
-
-| Test Type | Detect From | Default Command |
-|-----------|-------------|-----------------|
-| Unit | package.json scripts | `npm test` or `npx jest` |
-| Integration | test files | `npm run test:integration` |
-| E2E | playwright.config / cypress.json | `npx playwright test` or `npx cypress run` |
-| Visual | percy.yml / chromatic | `npx percy exec` |
-| Load | k6 / artillery config | `k6 run` or `artillery run` |
-| Security | package.json | `npm audit` |
-
-**Mobile fallbacks (if no custom config):**
-
-| Platform | Unit | E2E |
-|----------|------|-----|
-| React Native | `npm test` (jest) | `maestro test` or `detox test` |
-| Android | `./gradlew test` | `./gradlew connectedAndroidTest` |
-| iOS | `xcodebuild test` | `maestro test` |
-| Flutter | `flutter test` | `flutter test integration_test/` |
-
-**IMPORTANT:** Always check `proagents.config.yaml` FIRST before using defaults.
-
-### AI Platform Management
-| Command | Action |
-|---------|--------|
-| `pa:ai-list` | List installed AI platforms |
-| `pa:ai-add` | Add more AI platforms |
-| `pa:ai-remove` | Remove AI platforms from config |
-| `pa:ai-sync` | Sync config with existing files |
-
-**How to execute AI Platform commands:**
-
-For `pa:ai-list`:
-- Read `./.proagents/proagents.config.yaml` and show the `platforms` array
-- Show which AI instruction files exist in project root
-
-For `pa:ai-add`:
-1. Show ALL platforms to user (always show complete list):
-
-   **IDE-based AI Assistants:**
-   | Platform | File Created | Description |
-   |----------|--------------|-------------|
-   | Claude Code | CLAUDE.md | Anthropic Claude in terminal/IDE |
-   | Cursor | .cursorrules | Cursor AI IDE |
-   | Windsurf | .windsurfrules | Codeium Windsurf IDE |
-   | GitHub Copilot | .github/copilot-instructions.md | GitHub Copilot |
-   | AWS Kiro | KIRO.md | AWS Kiro IDE |
-   | Antigravity | ANTIGRAVITY.md | Antigravity IDE (Gemini/Claude) |
-
-   **Web-based AI Platforms:**
-   | Platform | File Created | Description |
-   |----------|--------------|-------------|
-   | ChatGPT | CHATGPT.md | OpenAI ChatGPT |
-   | Gemini | GEMINI.md | Google Gemini |
-   | Replit AI | REPLIT.md | Replit Ghostwriter |
-   | Bolt.new | BOLT.md | StackBlitz Bolt |
-   | Lovable | LOVABLE.md | Lovable (GPT Engineer) |
-   | Groq | GROQ.md | Groq fast inference |
-
-2. Ask user which platforms to add (show all 12 options)
-3. For each selected platform:
-   - Copy content from `./.proagents/{PLATFORM}.md` (e.g., `./.proagents/CLAUDE.md`)
-   - If target file exists, wrap new content with markers and append:
-     ```
-     <!-- PROAGENTS:START -->
-     {content from proagents folder}
-     <!-- PROAGENTS:END -->
-     ```
-   - If target file doesn't exist, create it with the content wrapped in markers
-4. Update `./.proagents/proagents.config.yaml` to add platform to `platforms` array
-
-For `pa:ai-remove`:
-1. Read `./.proagents/proagents.config.yaml` to get current platforms
-2. Show list and ask which to remove
-3. For each selected:
-   - Remove the PROAGENTS section (between markers) from the file, OR delete the file if it only contains ProAgents content
-   - Update config to remove from `platforms` array
-
-For `pa:ai-sync`:
-1. Scan project root for AI instruction files
-2. Read current config from `./.proagents/proagents.config.yaml`
-3. Compare and show differences:
-   - Files that exist but not in config
-   - Config entries that don't have matching files
-4. Ask user: "Add missing files to config?" or "Remove orphan config entries?"
-5. Update config to match actual files
-
-**Platform ID to File Mapping:**
-| Platform ID | File |
-|-------------|------|
-| claude | CLAUDE.md |
-| cursor | .cursorrules |
-| windsurf | .windsurfrules |
-| copilot | .github/copilot-instructions.md |
-| chatgpt | CHATGPT.md |
-| gemini | GEMINI.md |
-| bolt | BOLT.md |
-| lovable | LOVABLE.md |
-| replit | REPLIT.md |
-| kiro | KIRO.md |
-| groq | GROQ.md |
-| antigravity | ANTIGRAVITY.md |
-
-### Configuration
-| Command | Action |
-|---------|--------|
-| `pa:config` | Show current configuration |
-| `pa:config-list` | List all configurable options |
-| `pa:config-show` | Show current config values |
-| `pa:config-set K V` | Set a config value |
-| `pa:config-get K` | Get a config value |
-| `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:
-
-1. **Read the corresponding prompt file** from `./.proagents/prompts/`
-2. **Follow the workflow** defined in that prompt
-3. **Use project context** from `./.proagents/` folder
-
-### Prompt File Mapping
-- `pa:feature` → `./.proagents/prompts/00-init.md` + workflow
-- `pa:fix` → `./.proagents/workflow-modes/entry-modes.md` (Bug Fix section)
-- `pa:doc*` → `./.proagents/prompts/07-documentation.md`
-- `pa:qa` → `./.proagents/checklists/code-quality.md`
-- `pa:test` → `./.proagents/prompts/06-testing.md`
-- `pa:deploy` → `./.proagents/prompts/08-deployment.md`
-- `pa:release` → `./.proagents/prompts/07-documentation.md` (Release Notes section)
+## Key Files
 
-## Workflow Reference
+| File | Purpose |
+|------|---------|
+| `context.md` | Persistent project context |
+| `activity.log` | Recent AI activity |
+| `feedback.md` | Past corrections (learn from these!) |
+| `watchlist.yaml` | Files requiring confirmation |
+| `proagents.config.yaml` | Project config |
+| `active-features/_index.json` | Feature status |
 
-Full workflow documentation: `./.proagents/WORKFLOW.md`
-Quick command reference: `./.proagents/PROAGENTS.md`
+---
 
 ## Important
 
 - Always check `./.proagents/` folder for project-specific configurations
 - Preserve user's `proagents.config.yaml` settings
 - Follow existing code patterns found in the project
+- Log all activity for other AIs to see
+- Learn from feedback.md - don't repeat past mistakes