proagents 1.6.18 → 1.6.20

package/.claude/settings.local.json

@@ -163,7 +163,19 @@
       "Bash(timeout 5 node:*)",
       "Bash(timeout 20 node:*)",
       "Bash(CURSOR_TRACE_ID=test-123 node:*)",
-      "Bash(npm pack:*)"
+      "Bash(npm pack:*)",
+      "Bash(timeout 10 node:*)",
+      "Bash(bash -c 'printf \"\"1\\\\n\\\\n1\\\\n\"\" | node /Users/prakash/Saeculum/AI/proAgents/bin/proagents.js init 2>&1')",
+      "Bash(chmod:*)",
+      "Bash(/private/tmp/test-init.sh)",
+      "Bash(git -C /Users/prakash/Saeculum/AI/proAgents status --short)",
+      "Bash(git -C /Users/prakash/Saeculum/AI/proAgents diff --stat)",
+      "Bash(/private/tmp/test-comprehensive.sh)",
+      "Bash(/private/tmp/test-existing.sh)",
+      "Bash(git -C /Users/prakash/Saeculum/AI/proAgents diff lib/commands/ai.js)",
+      "Bash(for f in .proagents/AI_INSTRUCTIONS.md .proagents/CLAUDE.md .proagents/AGENTS.md .proagents/.cursorrules .proagents/.windsurfrules .proagents/GEMINI.md .proagents/BOLT.md .proagents/REPLIT.md .proagents/LOVABLE.md .proagents/KIRO.md)",
+      "Bash(if grep -q \"AI directives\" \"$f\")",
+      "Bash(if grep -q \"ANY.*pa:.*command\" \"$f\")"
     ]
   }
 }

package/.proagents/.cursorrules

@@ -2,29 +2,44 @@
 
 This project uses ProAgents workflow framework.
 
-## ⚠️ MANDATORY: Every pa: Command Flow
+> **IMPORTANT:** `pa:` commands are **AI directives**, NOT shell/terminal commands.
+> When user types ANY `pa:` command (e.g., `pa:feature`, `pa:fix`, `pa:status`),
+> DO NOT try to run it in terminal. Instead, follow the instructions below.
 
-### BEFORE Any pa: Command (Auto-Sync)
+## Auto-Sync Protocol
 
-**Read these files FIRST before doing anything:**
+### Rule: Sync for commands that WRITE, skip for commands that READ
 
+### Workflow Commands (Auto-Sync Required)
+
+Commands that CREATE or MODIFY code/content need context:
+
+**BEFORE these commands, read:**
 ```bash
 cat .proagents/worklog/_context.md      # Current state
 cat .proagents/changelog/_recent.md     # Recent changes
 tail -10 .proagents/activity.log        # Recent activity
 ```
 
-**This applies to EVERY command:** `pa:fix`, `pa:feature`, `pa:test`, `pa:doc`, etc.
+**Examples:** `pa:feature`, `pa:fix`, `pa:implement`, `pa:analyze`,
+`pa:design`, `pa:plan`, `pa:test`, `pa:review`, `pa:doc`, `pa:deploy`,
+`pa:rnd`, `pa:refactor`, `pa:debug`, `pa:qa`, `pa:changelog`, `pa:release`, `pa:resume`,
+`pa:session-start`, `pa:session-end`
 
-### AFTER Any pa: Command (Auto-Log)
+### Utility Commands (No Sync Required)
 
-**After EVERY file edit, IMMEDIATELY update these files:**
+Commands that only READ, DISPLAY, or CONFIGURE:
+- **Skip BEFORE step** - No context reading needed
+- **Skip AFTER step** - No logging needed
 
-1. `.proagents/changelog/_recent.md` - Prepend change summary
-2. `.proagents/changelog/modules/[module].md` - Based on file path
-3. `.proagents/worklog/_context.md` - Update current state
+**Examples:** `pa:help`, `pa:status`, `pa:progress`, `pa:history`,
+`pa:ai-*`, `pa:config-*`, `pa:sync`
 
-Module detection: `src/api/*`→api, `src/auth/*`→auth, `src/components/*`→ui
+### AFTER Workflow Commands (Auto-Log)
+
+**After commands that CHANGE files, update:**
+1. `.proagents/changelog/_recent.md` - Prepend change summary
+2. `.proagents/worklog/_context.md` - Update current state
 
 ## Essential Commands
 

package/.proagents/.windsurfrules

@@ -2,29 +2,44 @@
 
 This project uses ProAgents - an AI-agnostic development workflow framework.
 
-## ⚠️ MANDATORY: Every pa: Command Flow
+> **IMPORTANT:** `pa:` commands are **AI directives**, NOT shell/terminal commands.
+> When user types ANY `pa:` command (e.g., `pa:feature`, `pa:fix`, `pa:status`),
+> DO NOT try to run it in terminal. Instead, follow the instructions below.
 
-### BEFORE Any pa: Command (Auto-Sync)
+## Auto-Sync Protocol
 
-**Read these files FIRST before doing anything:**
+### Rule: Sync for commands that WRITE, skip for commands that READ
 
+### Workflow Commands (Auto-Sync Required)
+
+Commands that CREATE or MODIFY code/content need context:
+
+**BEFORE these commands, read:**
 ```bash
 cat .proagents/worklog/_context.md      # Current state
 cat .proagents/changelog/_recent.md     # Recent changes
 tail -10 .proagents/activity.log        # Recent activity
 ```
 
-**This applies to EVERY command:** `pa:fix`, `pa:feature`, `pa:test`, `pa:doc`, etc.
+**Examples:** `pa:feature`, `pa:fix`, `pa:implement`, `pa:analyze`,
+`pa:design`, `pa:plan`, `pa:test`, `pa:review`, `pa:doc`, `pa:deploy`,
+`pa:rnd`, `pa:refactor`, `pa:debug`, `pa:qa`, `pa:changelog`, `pa:release`, `pa:resume`,
+`pa:session-start`, `pa:session-end`
 
-### AFTER Any pa: Command (Auto-Log)
+### Utility Commands (No Sync Required)
 
-**After EVERY file edit, IMMEDIATELY update these files:**
+Commands that only READ, DISPLAY, or CONFIGURE:
+- **Skip BEFORE step** - No context reading needed
+- **Skip AFTER step** - No logging needed
 
-1. `.proagents/changelog/_recent.md` - Prepend change summary
-2. `.proagents/changelog/modules/[module].md` - Based on file path
-3. `.proagents/worklog/_context.md` - Update current state
+**Examples:** `pa:help`, `pa:status`, `pa:progress`, `pa:history`,
+`pa:ai-*`, `pa:config-*`, `pa:sync`
 
-Module detection: `src/api/*`→api, `src/auth/*`→auth, `src/components/*`→ui
+### AFTER Workflow Commands (Auto-Log)
+
+**After commands that CHANGE files, update:**
+1. `.proagents/changelog/_recent.md` - Prepend change summary
+2. `.proagents/worklog/_context.md` - Update current state
 
 ## Essential Commands
 

package/.proagents/AGENTS.md

@@ -1,30 +1,49 @@
-# ProAgents Commands for Codex
+# ProAgents Commands
+
+> **Universal AI Instructions** - Works with ChatGPT, Groq, Antigravity, Codex CLI, and any generic AI platform.
+>
+> ⚠️ **Do not remove this file** - Required for ProAgents to work properly.
 
 This project uses ProAgents - an AI-agnostic development workflow framework.
 
-## MANDATORY: Every pa: Command Flow
+> **IMPORTANT:** `pa:` commands are **AI directives**, NOT shell/terminal commands.
+> When user types ANY `pa:` command (e.g., `pa:feature`, `pa:fix`, `pa:status`),
+> DO NOT try to run it in terminal. Instead, follow the instructions below.
+
+## Auto-Sync Protocol
+
+### Rule: Sync for commands that WRITE, skip for commands that READ
 
-### BEFORE Any pa: Command (Auto-Sync)
+### Workflow Commands (Auto-Sync Required)
 
-**Read these files FIRST before doing anything:**
+Commands that CREATE or MODIFY code/content need context:
 
+**BEFORE these commands, read:**
 ```bash
 cat .proagents/worklog/_context.md      # Current state
 cat .proagents/changelog/_recent.md     # Recent changes
 tail -10 .proagents/activity.log        # Recent activity
 ```
 
-**This applies to EVERY command:** `pa:fix`, `pa:feature`, `pa:test`, `pa:doc`, etc.
+**Examples:** `pa:feature`, `pa:fix`, `pa:implement`, `pa:analyze`,
+`pa:design`, `pa:plan`, `pa:test`, `pa:review`, `pa:doc`, `pa:deploy`,
+`pa:rnd`, `pa:refactor`, `pa:debug`, `pa:qa`, `pa:changelog`, `pa:release`, `pa:resume`,
+`pa:session-start`, `pa:session-end`
 
-### AFTER Any pa: Command (Auto-Log)
+### Utility Commands (No Sync Required)
 
-**After EVERY file edit, IMMEDIATELY update these files:**
+Commands that only READ, DISPLAY, or CONFIGURE:
+- **Skip BEFORE step** - No context reading needed
+- **Skip AFTER step** - No logging needed
 
-1. `.proagents/changelog/_recent.md` - Prepend change summary
-2. `.proagents/changelog/modules/[module].md` - Based on file path
-3. `.proagents/worklog/_context.md` - Update current state
+**Examples:** `pa:help`, `pa:status`, `pa:progress`, `pa:history`,
+`pa:ai-*`, `pa:config-*`, `pa:sync`
+
+### AFTER Workflow Commands (Auto-Log)
 
-Module detection: `src/api/*`→api, `src/auth/*`→auth, `src/components/*`→ui
+**After commands that CHANGE files, update:**
+1. `.proagents/changelog/_recent.md` - Prepend change summary
+2. `.proagents/worklog/_context.md` - Update current state
 
 ## Essential Commands
 
@@ -32,6 +51,8 @@ Module detection: `src/api/*`→api, `src/auth/*`→auth, `src/components/*`→u
 |---------|--------|
 | `pa:feature "name"` | Start new feature workflow |
 | `pa:fix "bug"` | Quick bug fix mode |
+| `pa:project-setup` | Interactive project setup wizard |
+| `pa:rnd` | Research & Development workflow |
 | `pa:doc` | Documentation options |
 | `pa:qa` | Quality assurance checks |
 | `pa:test` | Run test workflow |

package/.proagents/AI_INSTRUCTIONS.md

@@ -2,34 +2,48 @@
 
 This project uses ProAgents - an AI-agnostic development workflow framework.
 
+> **IMPORTANT:** `pa:` commands are **AI directives**, NOT shell/terminal commands.
+> When user types ANY `pa:` command (e.g., `pa:feature`, `pa:fix`, `pa:status`),
+> DO NOT try to run it in terminal. Instead, follow the instructions below.
+
 ---
 
-## ⚠️ MANDATORY: Auto-Sync on EVERY pa: Command
+## Auto-Sync Protocol
+
+### Rule: Sync for commands that WRITE, skip for commands that READ
 
-**BEFORE executing ANY `pa:` command, AI MUST run these steps FIRST:**
+### Workflow Commands (Auto-Sync Required)
 
+Commands that CREATE or MODIFY code/content need context.
+
+**BEFORE these commands, read:**
 ```bash
-# STEP 1: Load context (REQUIRED - do this FIRST)
-cat .proagents/worklog/_context.md 2>/dev/null
-cat .proagents/changelog/_recent.md 2>/dev/null | head -30
-tail -10 .proagents/activity.log 2>/dev/null
+cat .proagents/worklog/_context.md 2>/dev/null      # Current state
+cat .proagents/changelog/_recent.md 2>/dev/null | head -30  # Recent changes
+tail -10 .proagents/activity.log 2>/dev/null        # Recent activity
 ```
 
-**This applies to ALL commands including:**
-- `pa:fix "bug"` - Load context FIRST, then fix
-- `pa:feature "name"` - Load context FIRST, then start feature
-- `pa:test` - Load context FIRST, then run tests
-- `pa:doc` - Load context FIRST, then generate docs
-- **EVERY pa: command** - Load context FIRST
+**Workflow commands:** `pa:feature`, `pa:fix`, `pa:implement`, `pa:analyze`,
+`pa:design`, `pa:plan`, `pa:test`, `pa:review`, `pa:doc`, `pa:deploy`,
+`pa:rnd`, `pa:refactor`, `pa:debug`, `pa:qa`, `pa:changelog`, `pa:release`, `pa:resume`,
+`pa:session-start`, `pa:session-end`
+
+### Utility Commands (No Sync Required)
 
-**AFTER executing ANY `pa:` command that changes files, AI MUST:**
+Commands that only READ, DISPLAY, or CONFIGURE:
+- **Skip BEFORE step** - No context reading needed
+- **Skip AFTER step** - No logging needed
 
+**Examples:** `pa:help`, `pa:status`, `pa:progress`, `pa:history`,
+`pa:ai-*`, `pa:config-*`, `pa:sync`
+
+### AFTER Workflow Commands (Auto-Log)
+
+**After commands that CHANGE files, update:**
 ```bash
-# Update worklogs and changelogs
 # 1. Prepend to .proagents/changelog/_recent.md
 # 2. Update .proagents/worklog/_context.md
-# 3. Update .proagents/changelog/modules/[module].md
-# 4. Log to .proagents/activity.log
+# 3. Log to .proagents/activity.log
 ```
 
 **Example flow for `pa:fix "login bug"`:**
@@ -41,7 +55,7 @@ tail -10 .proagents/activity.log 2>/dev/null
 5. AI logs to activity.log                          ← LOG ACTIVITY
 ```
 
-**Note:** When updating `_recent.md` or `_context.md`, first read the corresponding `*.template.md` file to use the latest format. See "Using Template Reference Files" section below.
+**Note:** When updating `_recent.md` or `_context.md`, first read the corresponding `*.template.md` file to use the latest format.
 
 ---
 
@@ -74,26 +88,20 @@ tail -10 .proagents/activity.log 2>/dev/null
 
 **Multiple AI tools may work on this project simultaneously. They do NOT share context.**
 
-### AUTOMATIC Context Loading (EVERY pa: Command)
+### Context Loading for Workflow Commands
 
-**On EVERY `pa:` command, AI MUST FIRST load context:**
+**For workflow commands (pa:feature, pa:fix, pa:implement, etc.), load context FIRST:**
 
 ```bash
-# MANDATORY FIRST STEP - Run before ANY pa: command
 cat .proagents/worklog/_context.md 2>/dev/null
 cat .proagents/changelog/_recent.md 2>/dev/null | head -30
 tail -10 .proagents/activity.log 2>/dev/null
-
-# Also check for conflicts
-cat .proagents/.active-files 2>/dev/null
+cat .proagents/.active-files 2>/dev/null  # Check for conflicts
 ```
 
-**This is NOT optional. This is NOT just for "first command".**
-**EVERY pa: command = Load context FIRST, then execute.**
-
-**User does NOT need to type pa:sync - AI does it automatically on EVERY pa: command.**
+**Skip context loading for utility commands** (pa:help, pa:status, pa:ai-*, etc.)
 
-### Before ANY `pa:` command:
+### Before Workflow Commands:
 
 1. **Auto-load context** - Read `worklog/_context.md` and `changelog/_recent.md`
 2. **Check activity log** - `./.proagents/activity.log`
@@ -101,7 +109,7 @@ cat .proagents/.active-files 2>/dev/null
 4. **Check watchlist** - `./.proagents/watchlist.yaml` (files requiring confirmation)
 5. **Check file locks** - `./.proagents/.active-files`
 
-### After ANY `pa:` command:
+### After Workflow Commands:
 
 **MANDATORY: Log every command to `./.proagents/activity.log`**
 
@@ -126,7 +134,7 @@ echo "[$(date '+%Y-%m-%d %H:%M')] [Claude:opus-4] [pa:feature] Started user-auth
 **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
+- Log workflow commands (skip utility commands like pa:help, pa:status)
 
 ### Lock File
 
@@ -488,6 +496,10 @@ Auto-detect issue numbers from user input and include in changelog:
 | `pa:status` | Show current progress |
 | `pa:feature "name"` | Start new feature |
 | `pa:fix "bug"` | Quick bug fix |
+| `pa:project-setup` | Interactive project setup wizard |
+| `pa:setup` | Alias for pa:project-setup |
+| `pa:rnd` | Research & Development workflow |
+| `pa:research` | Alias for pa:rnd |
 | `pa:feature-list` | List all features |
 | `pa:feature-complete` | Mark feature complete |
 
@@ -587,6 +599,14 @@ Auto-detect issue numbers from user input and include in changelog:
 | `pa:checkpoint` | Pause for approval |
 | `pa:skip-checkpoint` | Skip checkpoint |
 
+### AI Platform Management
+| Command | Action | Prompt File |
+|---------|--------|-------------|
+| `pa:ai-list` | Show installed AI platforms | `./prompts/ai-list.md` |
+| `pa:ai-add` | Add AI platform | `./prompts/ai-add.md` |
+| `pa:ai-remove` | Remove AI platform | `./prompts/ai-remove.md` |
+| `pa:ai-sync` | Sync config with files | `./prompts/ai-sync.md` |
+
 ### History & Progress
 | Command | Action |
 |---------|--------|
@@ -594,6 +614,42 @@ Auto-detect issue numbers from user input and include in changelog:
 | `pa:progress` | Show feature progress |
 | `pa:activity` | **Show ALL AI platforms activity** (cross-AI visibility) |
 
+### Navigation & Flow
+| Command | Action |
+|---------|--------|
+| `pa:next` | Show next step in workflow |
+| `pa:back` | Go to previous phase |
+| `pa:resume` | Resume last session |
+| `pa:skip` | Skip current phase |
+| `pa:lock-release` | Release lock after work |
+
+### Quality & Metrics
+| Command | Action |
+|---------|--------|
+| `pa:metrics` | Show code quality metrics |
+| `pa:coverage` | Show test coverage report |
+| `pa:perf` | Performance analysis |
+| `pa:a11y` | Accessibility audit |
+
+### Code Generation
+| Command | Action |
+|---------|--------|
+| `pa:generate-component "name"` | Generate component from template |
+| `pa:generate-api "name"` | Generate API endpoint |
+| `pa:generate-test "file"` | Generate test file |
+
+### Refactoring
+| Command | Action |
+|---------|--------|
+| `pa:rename "old" "new"` | Rename across codebase |
+| `pa:cleanup` | Remove dead code, unused imports |
+
+### Git & Release
+| Command | Action |
+|---------|--------|
+| `pa:version` | Show/bump version |
+| `pa:github-pr` | Create pull request |
+
 ---
 
 ## How to Execute Commands
@@ -624,6 +680,17 @@ When user types a `pa:` command:
 | `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:project-setup` | `./prompts/00-project-setup.md` |
+| `pa:setup` | `./prompts/00-project-setup.md` |
+| `pa:rnd` | `./prompts/12-rnd.md` |
+| `pa:research` | `./prompts/12-rnd.md` |
+| `pa:rnd-compare` | `./prompts/12-rnd.md` |
+| `pa:rnd-poc` | `./prompts/12-rnd.md` |
+| `pa:rnd-explore` | `./prompts/12-rnd.md` |
+| `pa:ai-list` | `./prompts/ai-list.md` |
+| `pa:ai-add` | `./prompts/ai-add.md` |
+| `pa:ai-remove` | `./prompts/ai-remove.md` |
+| `pa:ai-sync` | `./prompts/ai-sync.md` |
 
 ---
 
@@ -668,6 +735,8 @@ ProAgents Help
   Core Commands:
     pa:feature "name"     Start new feature with full workflow
     pa:fix "bug"          Quick bug fix mode
+    pa:project-setup      Interactive project setup wizard
+    pa:rnd                Research & Development workflow
     pa:status             Show current progress (enhanced)
     pa:help               Show this help
 

package/.proagents/BOLT.md

@@ -2,29 +2,44 @@
 
 This project uses ProAgents - an AI-agnostic development workflow framework.
 
-## ⚠️ MANDATORY: Every pa: Command Flow
+> **IMPORTANT:** `pa:` commands are **AI directives**, NOT shell/terminal commands.
+> When user types ANY `pa:` command (e.g., `pa:feature`, `pa:fix`, `pa:status`),
+> DO NOT try to run it in terminal. Instead, follow the instructions below.
 
-### BEFORE Any pa: Command (Auto-Sync)
+## Auto-Sync Protocol
 
-**Read these files FIRST before doing anything:**
+### Rule: Sync for commands that WRITE, skip for commands that READ
 
+### Workflow Commands (Auto-Sync Required)
+
+Commands that CREATE or MODIFY code/content need context:
+
+**BEFORE these commands, read:**
 ```bash
 cat .proagents/worklog/_context.md      # Current state
 cat .proagents/changelog/_recent.md     # Recent changes
 tail -10 .proagents/activity.log        # Recent activity
 ```
 
-**This applies to EVERY command:** `pa:fix`, `pa:feature`, `pa:test`, `pa:doc`, etc.
+**Examples:** `pa:feature`, `pa:fix`, `pa:implement`, `pa:analyze`,
+`pa:design`, `pa:plan`, `pa:test`, `pa:review`, `pa:doc`, `pa:deploy`,
+`pa:rnd`, `pa:refactor`, `pa:debug`, `pa:qa`, `pa:changelog`, `pa:release`, `pa:resume`,
+`pa:session-start`, `pa:session-end`
 
-### AFTER Any pa: Command (Auto-Log)
+### Utility Commands (No Sync Required)
 
-**After EVERY file edit, IMMEDIATELY update these files:**
+Commands that only READ, DISPLAY, or CONFIGURE:
+- **Skip BEFORE step** - No context reading needed
+- **Skip AFTER step** - No logging needed
 
-1. `.proagents/changelog/_recent.md` - Prepend change summary
-2. `.proagents/changelog/modules/[module].md` - Based on file path
-3. `.proagents/worklog/_context.md` - Update current state
+**Examples:** `pa:help`, `pa:status`, `pa:progress`, `pa:history`,
+`pa:ai-*`, `pa:config-*`, `pa:sync`
 
-Module detection: `src/api/*`→api, `src/auth/*`→auth, `src/components/*`→ui
+### AFTER Workflow Commands (Auto-Log)
+
+**After commands that CHANGE files, update:**
+1. `.proagents/changelog/_recent.md` - Prepend change summary
+2. `.proagents/worklog/_context.md` - Update current state
 
 ## Essential Commands
 
@@ -32,6 +47,8 @@ Module detection: `src/api/*`→api, `src/auth/*`→auth, `src/components/*`→u
 |---------|--------|
 | `pa:feature "name"` | Start new feature workflow |
 | `pa:fix "bug"` | Quick bug fix mode |
+| `pa:project-setup` | Interactive project setup wizard |
+| `pa:rnd` | Research & Development workflow |
 | `pa:doc` | Documentation options |
 | `pa:qa` | Quality assurance checks |
 | `pa:test` | Run test workflow |

package/.proagents/CLAUDE.md

@@ -2,29 +2,44 @@
 
 This project uses ProAgents - an AI-agnostic development workflow framework.
 
-## ⚠️ MANDATORY: Every pa: Command Flow
+> **IMPORTANT:** `pa:` commands are **AI directives**, NOT shell/terminal commands.
+> When user types ANY `pa:` command (e.g., `pa:feature`, `pa:fix`, `pa:status`),
+> DO NOT try to run it in terminal. Instead, follow the instructions below.
 
-### BEFORE Any pa: Command (Auto-Sync)
+## Auto-Sync Protocol
 
-**Read these files FIRST before doing anything:**
+### Rule: Sync for commands that WRITE, skip for commands that READ
 
+### Workflow Commands (Auto-Sync Required)
+
+Commands that CREATE or MODIFY code/content need context:
+
+**BEFORE these commands, read:**
 ```bash
 cat .proagents/worklog/_context.md      # Current state
 cat .proagents/changelog/_recent.md     # Recent changes
 tail -10 .proagents/activity.log        # Recent activity
 ```
 
-**This applies to EVERY command:** `pa:fix`, `pa:feature`, `pa:test`, `pa:doc`, etc.
+**Examples:** `pa:feature`, `pa:fix`, `pa:implement`, `pa:analyze`,
+`pa:design`, `pa:plan`, `pa:test`, `pa:review`, `pa:doc`, `pa:deploy`,
+`pa:rnd`, `pa:refactor`, `pa:debug`, `pa:qa`, `pa:changelog`, `pa:release`, `pa:resume`,
+`pa:session-start`, `pa:session-end`
 
-### AFTER Any pa: Command (Auto-Log)
+### Utility Commands (No Sync Required)
 
-**After EVERY file edit, IMMEDIATELY update these files:**
+Commands that only READ, DISPLAY, or CONFIGURE:
+- **Skip BEFORE step** - No context reading needed
+- **Skip AFTER step** - No logging needed
 
-1. `.proagents/changelog/_recent.md` - Prepend change summary
-2. `.proagents/changelog/modules/[module].md` - Based on file path
-3. `.proagents/worklog/_context.md` - Update current state
+**Examples:** `pa:help`, `pa:status`, `pa:progress`, `pa:history`,
+`pa:ai-*`, `pa:config-*`, `pa:sync`
 
-Module detection: `src/api/*`→api, `src/auth/*`→auth, `src/components/*`→ui
+### AFTER Workflow Commands (Auto-Log)
+
+**After commands that CHANGE files, update:**
+1. `.proagents/changelog/_recent.md` - Prepend change summary
+2. `.proagents/worklog/_context.md` - Update current state
 
 ## Essential Commands
 
@@ -32,6 +47,8 @@ Module detection: `src/api/*`→api, `src/auth/*`→auth, `src/components/*`→u
 |---------|--------|
 | `pa:feature "name"` | Start new feature workflow |
 | `pa:fix "bug"` | Quick bug fix mode |
+| `pa:project-setup` | Interactive project setup wizard |
+| `pa:rnd` | Research & Development workflow |
 | `pa:doc` | Documentation options |
 | `pa:qa` | Quality assurance checks |
 | `pa:test` | Run test workflow |

package/.proagents/GEMINI.md

@@ -2,29 +2,44 @@
 
 This project uses ProAgents - an AI-agnostic development workflow framework.
 
-## ⚠️ MANDATORY: Every pa: Command Flow
+> **IMPORTANT:** `pa:` commands are **AI directives**, NOT shell/terminal commands.
+> When user types ANY `pa:` command (e.g., `pa:feature`, `pa:fix`, `pa:status`),
+> DO NOT try to run it in terminal. Instead, follow the instructions below.
 
-### BEFORE Any pa: Command (Auto-Sync)
+## Auto-Sync Protocol
 
-**Read these files FIRST before doing anything:**
+### Rule: Sync for commands that WRITE, skip for commands that READ
 
+### Workflow Commands (Auto-Sync Required)
+
+Commands that CREATE or MODIFY code/content need context:
+
+**BEFORE these commands, read:**
 ```bash
 cat .proagents/worklog/_context.md      # Current state
 cat .proagents/changelog/_recent.md     # Recent changes
 tail -10 .proagents/activity.log        # Recent activity
 ```
 
-**This applies to EVERY command:** `pa:fix`, `pa:feature`, `pa:test`, `pa:doc`, etc.
+**Examples:** `pa:feature`, `pa:fix`, `pa:implement`, `pa:analyze`,
+`pa:design`, `pa:plan`, `pa:test`, `pa:review`, `pa:doc`, `pa:deploy`,
+`pa:rnd`, `pa:refactor`, `pa:debug`, `pa:qa`, `pa:changelog`, `pa:release`, `pa:resume`,
+`pa:session-start`, `pa:session-end`
 
-### AFTER Any pa: Command (Auto-Log)
+### Utility Commands (No Sync Required)
 
-**After EVERY file edit, IMMEDIATELY update these files:**
+Commands that only READ, DISPLAY, or CONFIGURE:
+- **Skip BEFORE step** - No context reading needed
+- **Skip AFTER step** - No logging needed
 
-1. `.proagents/changelog/_recent.md` - Prepend change summary
-2. `.proagents/changelog/modules/[module].md` - Based on file path
-3. `.proagents/worklog/_context.md` - Update current state
+**Examples:** `pa:help`, `pa:status`, `pa:progress`, `pa:history`,
+`pa:ai-*`, `pa:config-*`, `pa:sync`
 
-Module detection: `src/api/*`→api, `src/auth/*`→auth, `src/components/*`→ui
+### AFTER Workflow Commands (Auto-Log)
+
+**After commands that CHANGE files, update:**
+1. `.proagents/changelog/_recent.md` - Prepend change summary
+2. `.proagents/worklog/_context.md` - Update current state
 
 ## Essential Commands
 
@@ -32,6 +47,8 @@ Module detection: `src/api/*`→api, `src/auth/*`→auth, `src/components/*`→u
 |---------|--------|
 | `pa:feature "name"` | Start new feature workflow |
 | `pa:fix "bug"` | Quick bug fix mode |
+| `pa:project-setup` | Interactive project setup wizard |
+| `pa:rnd` | Research & Development workflow |
 | `pa:doc` | Documentation options |
 | `pa:qa` | Quality assurance checks |
 | `pa:test` | Run test workflow |