proagents 1.6.18 → 1.6.20

package/.proagents/prompts/ai-add.md

@@ -0,0 +1,80 @@
+# pa:ai-add - Add AI Platform
+
+Add a new AI platform configuration to this project.
+
+## Steps
+
+### 1. Read Available Platforms
+
+**IMPORTANT:** Always read the authoritative list first - do not hallucinate platforms.
+
+```bash
+cat .proagents/platforms.yaml
+```
+
+### 2. Show Options to User
+
+Display platforms grouped by category:
+
+```
+IDE-based AI Assistants:
+  1. claude    - Claude Code (CLAUDE.md)
+  2. cursor    - Cursor (.cursorrules)
+  3. windsurf  - Windsurf (.windsurfrules)
+  4. copilot   - GitHub Copilot (.github/copilot-instructions.md)
+  5. kiro      - AWS Kiro (KIRO.md)
+  6. gemini    - Gemini (GEMINI.md)
+
+Web-based AI Platforms:
+  7. replit    - Replit AI (REPLIT.md)
+  8. bolt      - Bolt.new (BOLT.md)
+  9. lovable   - Lovable (LOVABLE.md)
+
+Auto-handled (use AGENTS.md):
+  - ChatGPT, Groq, Antigravity, Codex CLI, OpenAI API
+
+Which platform to add?
+```
+
+### 3. Create the File
+
+After user selects platform:
+
+1. **Read source template** from `.proagents/{file}`
+2. **Check if target file exists** in project root:
+   - If exists: Merge using markers (append ProAgents section)
+   - If not exists: Create new file with markers
+
+3. **Wrap content with markers:**
+   ```
+   <!-- PROAGENTS_START -->
+   {content from template}
+   <!-- PROAGENTS_END -->
+   ```
+
+### 4. Update Config
+
+Add platform to `ai_platforms` array in `./proagents.config.yaml`:
+
+```yaml
+ai_platforms:
+  - claude
+  - cursor
+  - {new_platform}  # Add this
+```
+
+### 5. Confirm
+
+```
+Added {platform_name}!
+  File: {file_path}
+  Config updated: ./proagents.config.yaml
+```
+
+## Merge Rules
+
+When target file already exists:
+
+1. **Has PROAGENTS markers:** Update content between markers only
+2. **No markers:** Append ProAgents section at end with markers
+3. **Never overwrite** user's existing configuration

package/.proagents/prompts/ai-list.md

@@ -0,0 +1,41 @@
+# pa:ai-list - List AI Platforms
+
+Show which AI platforms are configured for this project.
+
+## Steps
+
+1. **Read config file:**
+   ```bash
+   cat ./proagents.config.yaml
+   ```
+
+2. **Extract `ai_platforms` array** from the config
+
+3. **Display installed platforms:**
+   ```
+   Installed AI Platforms:
+   - Claude Code (CLAUDE.md)
+   - Cursor (.cursorrules)
+   - ...
+   ```
+
+4. **Show available platforms** (not yet installed):
+   - Read `.proagents/platforms.yaml` for full list
+   - Compare with installed list
+   - Show what can be added
+
+## Output Format
+
+```
+Installed AI Platforms:
+  [x] claude - Claude Code
+  [x] cursor - Cursor
+
+Available to Add:
+  [ ] windsurf - Windsurf
+  [ ] copilot - GitHub Copilot
+  [ ] gemini - Gemini
+  ...
+
+Use pa:ai-add to add more platforms.
+```

package/.proagents/prompts/ai-remove.md

@@ -0,0 +1,112 @@
+# pa:ai-remove - Remove AI Platform
+
+Remove an AI platform configuration from this project.
+
+## Steps
+
+### 1. Show Installed Platforms
+
+Read config and show what's installed:
+
+```bash
+cat ./proagents.config.yaml
+```
+
+Display:
+```
+Installed AI Platforms:
+  1. claude  - Claude Code (CLAUDE.md)
+  2. cursor  - Cursor (.cursorrules)
+
+Which platform to remove?
+```
+
+### 2. Locate the File
+
+Get file path from `.proagents/platforms.yaml`:
+- claude → `CLAUDE.md`
+- cursor → `.cursorrules`
+- copilot → `.github/copilot-instructions.md`
+- etc.
+
+### 3. Remove ProAgents Content
+
+**CRITICAL: Follow these rules carefully to avoid deleting user's config.**
+
+#### Step 3a: Check for Markers
+
+Look for these markers in the file:
+```
+<!-- PROAGENTS_START -->
+...content...
+<!-- PROAGENTS_END -->
+```
+
+#### Step 3b: If Markers Found
+
+1. Remove ONLY the content between markers (including the markers)
+2. Keep ALL other content in the file
+3. Clean up extra blank lines
+4. If file is empty after removal → delete the file
+5. If file has remaining content → keep the file
+
+**Example:**
+```
+# My Custom Rules        ← KEEP
+Some user config         ← KEEP
+
+<!-- PROAGENTS_START --> ← REMOVE
+ProAgents content...     ← REMOVE
+<!-- PROAGENTS_END -->   ← REMOVE
+
+# More user config       ← KEEP
+```
+
+#### Step 3c: If NO Markers Found
+
+**DO NOT DELETE THE FILE.**
+
+The file may contain user's own configuration that predates ProAgents or was manually edited.
+
+Action:
+1. Warn user: "No ProAgents markers found in {file}"
+2. Suggest: "Manual cleanup may be needed"
+3. Skip file removal
+4. Still update config (step 4)
+
+### 4. Update Config
+
+Remove platform from `ai_platforms` in `./proagents.config.yaml`:
+
+```yaml
+ai_platforms:
+  - claude
+  # - cursor  ← removed
+```
+
+### 5. Confirm
+
+Success cases:
+```
+Removed {platform}:
+  - Deleted: {file}  (file only had ProAgents content)
+  OR
+  - Cleaned: {file}  (kept your custom config)
+```
+
+Skip case:
+```
+Skipped {platform}:
+  - No ProAgents markers in {file}
+  - Manual cleanup may be needed
+  - Config updated anyway
+```
+
+## Safety Summary
+
+| Scenario | Action |
+|----------|--------|
+| File has markers, only ProAgents content | Delete file |
+| File has markers + user content | Remove markers section, keep rest |
+| File has no markers | **SKIP - don't delete** |
+| File doesn't exist | Skip silently |

package/.proagents/prompts/ai-sync.md

@@ -0,0 +1,96 @@
+# pa:ai-sync - Sync AI Platform Config
+
+Synchronize the config file with actual AI instruction files (fix mismatches).
+
+## When to Use
+
+- After manually adding/removing AI files
+- When config is out of sync with files
+- To detect and fix inconsistencies
+
+## Steps
+
+### 1. Read Current Config
+
+```bash
+cat ./proagents.config.yaml
+```
+
+Extract `ai_platforms` array.
+
+### 2. Read Platform Definitions
+
+```bash
+cat .proagents/platforms.yaml
+```
+
+### 3. Scan for Existing Files
+
+Check project root for each platform's file:
+
+| Platform | File to Check |
+|----------|---------------|
+| claude | `CLAUDE.md` |
+| cursor | `.cursorrules` |
+| windsurf | `.windsurfrules` |
+| copilot | `.github/copilot-instructions.md` |
+| kiro | `KIRO.md` |
+| gemini | `GEMINI.md` |
+| replit | `REPLIT.md` |
+| bolt | `BOLT.md` |
+| lovable | `LOVABLE.md` |
+
+### 4. Compare and Report
+
+```
+AI Platform Sync Status:
+
+In Config + File Exists:
+  [x] claude  - CLAUDE.md
+  [x] cursor  - .cursorrules
+
+In Config but File Missing:
+  [!] windsurf - .windsurfrules NOT FOUND
+
+File Exists but Not in Config:
+  [?] gemini - GEMINI.md exists
+
+Actions needed:
+  1. Add windsurf file OR remove from config
+  2. Add gemini to config OR delete file
+```
+
+### 5. Ask User for Action
+
+For each mismatch:
+
+**File missing:**
+```
+windsurf is in config but file doesn't exist.
+  1. Create the file (copy from .proagents/)
+  2. Remove from config
+```
+
+**File exists but not in config:**
+```
+GEMINI.md exists but gemini not in config.
+  1. Add to config
+  2. Delete the file
+```
+
+### 6. Apply Fixes
+
+Based on user choice:
+- Create missing files (use `pa:ai-add` logic)
+- Remove orphaned entries from config
+- Add discovered platforms to config
+- Delete orphaned files (use `pa:ai-remove` logic)
+
+### 7. Confirm
+
+```
+Sync complete!
+  - Added: gemini to config
+  - Created: .windsurfrules
+  - Removed: kiro from config (file was missing)
+```

package/.proagents/workflow-modes/entry-modes.md

@@ -55,6 +55,30 @@ The complete 10-phase development workflow for new features.
 └─────────────────────────────────────────────────────────────┘
 ```
 
+### Flow Context Check
+
+Before starting, check `.proagents/worklog/_context.md` for Flow Context:
+
+```
+📋 Checking for prior context...
+
+If Flow Context exists:
+┌─────────────────────────────────────────────────────────┐
+│ 📋 Continuing from previous workflow                    │
+│                                                         │
+│ Last Command: pa:rnd-compare                            │
+│ Decision: Zustand for state management                  │
+│ Context: E-commerce cart state                          │
+│ Research: docs/research/comparisons/state-mgmt.md       │
+│                                                         │
+│ Use this context? (yes/no/modify)                       │
+└─────────────────────────────────────────────────────────┘
+
+If "yes": Pre-populate feature with context data
+If "no": Start fresh, clear Flow Context
+If "modify": Allow user to adjust context
+```
+
 ### Starting Full Workflow
 
 ```bash
@@ -63,6 +87,9 @@ pa:feature start "User Profile Management"
 
 # With options
 pa:feature start "User Profile" --skip-ui --checkpoint=critical
+
+# Continue from RND (auto-reads Flow Context)
+pa:feature start "Cart State" --from-rnd
 ```
 
 ### Checkpoints

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

@@ -72,6 +72,53 @@ Failing: [Test names or "None"]
 | Open Issues | [N] |
 ```
 
+---
+
+## Flow Context
+<!-- Tracks command chain for seamless transitions between pa: commands -->
+```
+Current Flow: [command chain, e.g., "rnd → feature → plan"]
+Last Command: [last pa: command run]
+Decision: [key decision made, if any]
+Context: [relevant context to carry forward]
+Next Suggested: [suggested next command]
+Data: [JSON data to pass to next command]
+```
+
+### Flow Context Rules
+
+1. **Write after completion** - Each command writes its output to Flow Context
+2. **Read on start** - Commands check Flow Context for relevant prior decisions
+3. **Offer continuation** - If Flow Context has Next Suggested, offer to run it
+4. **Clear on explicit start** - When user starts fresh workflow, clear Flow Context
+5. **Preserve data** - JSON data carries structured info (tech stack, decisions, etc.)
+
+### Example Flow
+
+```markdown
+## Flow Context
+```
+Current Flow: rnd → feature
+Last Command: pa:rnd-compare
+Decision: Zustand for state management
+Context: E-commerce cart with complex state
+Next Suggested: pa:feature "cart state management"
+Data: {"tech": "zustand", "use_case": "cart", "research_doc": "docs/research/comparisons/state-management-2024-03-17.md"}
+```
+```
+
+When pa:feature starts, it reads this and says:
+```
+📋 Continuing from R&D...
+
+You recently decided on Zustand for cart state management.
+Research: docs/research/comparisons/state-management-2024-03-17.md
+
+Start feature with this context? (yes/no/different)
+```
+
+---
+
 ## Auto-Update Rules
 
 1. **Update `Last Updated`** with current timestamp

package/COMMANDS.md

@@ -212,6 +212,65 @@ Type these in any AI assistant (Claude, ChatGPT, Gemini, Cursor, etc.)
 
 ---
 
+## Project Setup
+
+| Command | Description |
+|---------|-------------|
+| `pa:project-setup` | Interactive setup wizard (new or existing projects) |
+| `pa:setup` | Alias for pa:project-setup |
+| `pa:setup --preset [name]` | Use quick preset (mobile-mvp, saas, etc.) |
+| `pa:setup --analyze` | Analyze existing project only |
+| `pa:setup --resume` | Resume interrupted setup |
+| `pa:setup --clear-progress` | Clear saved progress and start fresh |
+
+**Features:**
+- Quick Presets - Instant setup for common stacks (Mobile MVP, SaaS, E-commerce, etc.)
+- Idea-First Mode - Describe your idea, AI suggests tech stack with comparison table
+- Full Automation - Installs packages, creates folders, generates docs
+- Resume Support - Auto-saves progress, resume if interrupted
+- Merge Strategy - Updates existing docs without overwriting custom content
+- Works for both new projects and existing codebases
+
+---
+
+## Research & Development
+
+| Command | Description |
+|---------|-------------|
+| `pa:rnd` | Interactive R&D workflow (compare, prototype, explore) |
+| `pa:research` | Alias for pa:rnd |
+| `pa:rnd-compare` | Direct to comparison mode |
+| `pa:rnd-poc` | Direct to prototype mode |
+| `pa:rnd-explore` | Direct to exploration mode |
+| `pa:rnd --quick` | Quick 5-minute research |
+| `pa:rnd --resume` | Resume interrupted session |
+| `pa:rnd --clear` | Clear saved progress |
+
+**Features:**
+- Compare Options - Side-by-side library/framework comparisons with weighted scoring
+- Build POC - Quick proof-of-concept in isolated `./poc/` folder
+- Explore Solutions - Research and document findings
+- Web Search - Verify latest package stats (stars, downloads, releases)
+- Cost Estimator - Monthly costs at different user scales
+- Deprecation Alerts - Warn about deprecated/insecure packages
+- Comparison Tables - Visual side-by-side with recommendations
+- Past Decision Recall - Surface previous decisions on similar topics
+- Scope Guard - Alert when research drifts off-topic
+- Resume Support - Auto-saves progress
+- Tags & Categories - Organize research by topic
+- Archive System - Auto-archive old research after 6 months
+- Review Reminders - Set reminder to revisit decisions
+- Next Phase Integration - After RND, trigger pa:feature or pa:plan
+
+**Outputs:**
+- Comparison docs: `docs/research/comparisons/`
+- Research findings: `docs/research/findings/`
+- Research index: `docs/research/INDEX.md`
+- Bookmarks: `docs/research/BOOKMARKS.md`
+- POC code: `./poc/[name]/`
+
+---
+
 ## Workflow Phase Commands
 
 | Command | Phase | Description |

package/README.md

@@ -164,6 +164,8 @@ Type these in any AI assistant (Claude, ChatGPT, Gemini, Cursor, etc.):
 |---------|-------------|
 | `pa:feature "name"` | Start new feature workflow (all phases) |
 | `pa:fix "description"` | Quick bug fix mode |
+| `pa:project-setup` | Interactive project setup wizard |
+| `pa:rnd` | Research & Development workflow |
 | `pa:status` | Show current progress |
 | `pa:sync` | Load project context (usually auto) |
 | `pa:test` | Run tests |
@@ -173,7 +175,7 @@ Type these in any AI assistant (Claude, ChatGPT, Gemini, Cursor, etc.):
 | `pa:undo-last` | Revert last AI's changes |
 | `pa:handoff` | Create notes for another AI |
 
-**Quick aliases:** `pa:f` (feature), `pa:s` (status), `pa:t` (test), `pa:h` (help)
+**Quick aliases:** `pa:f` (feature), `pa:s` (status), `pa:t` (test), `pa:h` (help), `pa:setup` (project-setup), `pa:research` (rnd)
 
 📖 **Want more?** See [COMMANDS.md](COMMANDS.md) for 100+ AI commands (debugging, testing, refactoring, code generation, sprints...)