proagents 1.0.17 → 1.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 **AI-Agnostic Development Workflow Framework**
 
-A portable, universal development workflow framework that automates the full software development lifecycle. Works with **any AI platform** (Claude, ChatGPT, Gemini, Copilot, etc.) and **any IDE**.
+A portable, universal development workflow framework that works with **any AI platform** (Claude, ChatGPT, Gemini, Cursor, Copilot, etc.) and enables **multi-AI collaboration** on the same project.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm version](https://img.shields.io/npm/v/proagents.svg)](https://www.npmjs.com/package/proagents)
@@ -12,48 +12,43 @@ A portable, universal development workflow framework that automates the full sof
 ## Installation
 
 ```bash
-# Install globally
-npm install -g proagents
-
-# Or use directly with npx
+# Initialize in your project
 npx proagents init
-```
 
----
-
-## Why ProAgents?
+# Or with a template
+npx proagents init --template nextjs-saas
 
-- **No vendor lock-in** - Switch AI platforms without changing your workflow
-- **Full lifecycle automation** - From requirements to deployment
-- **Self-learning** - Adapts to your coding patterns and preferences
-- **Flexible entry points** - Full workflow, bug fix mode, or quick changes
+# Install globally (optional)
+npm install -g proagents
+```
 
 ---
 
 ## Quick Start
 
-### 1. Initialize ProAgents in your project
+### 1. Initialize ProAgents
 
 ```bash
 cd your-project
 npx proagents init
 ```
 
-### 2. Start a feature
+This creates a `./proagents/` folder with workflow files, and prompts for:
+- Project name and type (auto-detected)
+- Tech stack (API style, database, styling, auth, etc.)
+- AI platforms to use (Claude, Cursor, Gemini, etc.)
 
-**Using CLI:**
-```bash
-proagents feature start "Add user authentication"
-```
+### 2. Use Commands in Any AI
+
+Type `pa:` commands in your AI assistant:
 
-**Using AI assistant (Claude, ChatGPT, etc.):**
 ```
 pa:feature "Add user authentication"
+pa:fix "Login button not working"
+pa:status
 ```
 
-### 3. Follow the guided workflow
-
-The AI guides you through 10 phases:
+### 3. AI Follows the Guided Workflow
 
 ```
 Init → Analysis → Requirements → Design → Planning →
@@ -62,84 +57,312 @@ Implementation → Testing → Review → Documentation → Deployment
 
 ---
 
+## Features
+
+### Multi-AI Collaboration
+
+Multiple AIs can work on the same project without conflicts:
+
+| Feature | Description |
+|---------|-------------|
+| **Activity Log** | Track what each AI does with model name |
+| **Lock File** | Prevent conflicts during major work |
+| **Handoff Notes** | Pass context between AI sessions |
+| **Conflict Detection** | Warn before overwriting another AI's changes |
+| **Session Summaries** | Auto-generate summary at session end |
+
+### Project Templates
+
+Pre-configured settings for common stacks:
+
+```bash
+npx proagents init --template nextjs-saas      # Next.js SaaS
+npx proagents init --template react-spa        # React SPA
+npx proagents init --template react-native-app # React Native
+npx proagents init --template express-api      # Express API
+npx proagents init --template nestjs-api       # NestJS API
+npx proagents init --template vue-spa          # Vue.js SPA
+npx proagents init --template python-fastapi   # Python FastAPI
+
+npx proagents init --list-templates            # Show all templates
+```
+
+### AI Learning & Feedback
+
+- **Feedback Log** - AI learns from corrections, doesn't repeat mistakes
+- **Error Tracker** - Log errors and solutions for future reference
+- **Decision Log** - Track architectural decisions with reasoning
+- **Context File** - Persistent project knowledge AI reads every session
+
+### File Protection
+
+- **Watch List** - Critical files require confirmation before AI modifies
+- Never auto-modify `.env`, config files, migrations, etc.
+
+---
+
 ## CLI Commands
 
 ```bash
-proagents init                      # Initialize in current project
-proagents feature start "name"      # Start a new feature
-proagents feature status            # Check feature status
-proagents fix "bug description"     # Quick bug fix mode
-proagents status                    # Show ProAgents status
-proagents docs                      # Open documentation
-proagents commands                  # Show all commands
+# Initialization
+npx proagents init                    # Initialize in project
+npx proagents init --template <name>  # Use a project template
+npx proagents init --list-templates   # List available templates
+
+# Features & Fixes
+proagents feature start "name"        # Start a new feature
+proagents feature status              # Check feature status
+proagents fix "bug description"       # Quick bug fix mode
+
+# Maintenance
+proagents doctor                      # Health check installation
+proagents upgrade                     # Upgrade to latest version
+proagents status                      # Show ProAgents status
+
+# AI Platforms
+proagents ai list                     # List installed AI platforms
+proagents ai add                      # Add more platforms
+proagents ai remove                   # Remove platforms
+
+# Configuration
+proagents config show                 # Show current config
+proagents config setup                # Interactive config wizard
+
+# Other
+proagents docs                        # Open documentation
+proagents commands                    # Show all commands
+proagents uninstall                   # Remove ProAgents
 ```
 
 ---
 
-## Key Features
+## AI Commands (pa:)
+
+Type these in any AI assistant (Claude, ChatGPT, Gemini, Cursor, etc.):
+
+### 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` |
+
+### Core Commands
+| Command | Description |
+|---------|-------------|
+| `pa:feature "name"` | Start new feature workflow (all phases) |
+| `pa:fix "description"` | Quick bug fix mode |
+| `pa:status` | Show current progress |
+| `pa:help` | Show all commands |
+
+### Workflow Phase Commands
+| Command | Phase | Description |
+|---------|-------|-------------|
+| `pa:analyze` | Analysis | Deep codebase analysis |
+| `pa:requirements` | Requirements | Gather feature requirements |
+| `pa:design` | Design | UI/Architecture design |
+| `pa:plan` | Planning | Create implementation plan |
+| `pa:implement` | Implementation | Execute code changes |
+| `pa:test` | Testing | Create and run tests |
+| `pa:review` | Review | Code review workflow |
+| `pa:doc` | Documentation | Generate documentation |
+| `pa:deploy` | Deployment | Deployment preparation |
+
+### Documentation
+| Command | Description |
+|---------|-------------|
+| `pa:doc` | Generate documentation |
+| `pa:changelog` | Update CHANGELOG.md |
+| `pa:release` | Generate release notes |
 
-| Feature | Description |
+### Quality & Testing
+| Command | Description |
 |---------|-------------|
-| **AI Agnostic** | Works with Claude, ChatGPT, Gemini, Copilot, and more |
-| **IDE Agnostic** | VS Code, JetBrains, Cursor, Neovim, any editor |
-| **10-Phase Workflow** | Complete SDLC from analysis to deployment |
-| **Self-Learning** | Learns your patterns, conventions, and preferences |
-| **Flexible Modes** | Full workflow, bug fix fast-track, or quick changes |
-| **Parallel Development** | Work on multiple features with conflict detection |
-| **Git Integration** | Branching, commits, PRs, and rollback strategies |
-| **PM Integration** | Jira, Linear, GitHub Issues, Notion, and more |
+| `pa:qa` | Run quality assurance checks |
+| `pa:rollback` | Rollback procedures |
 
----
+### Multi-AI Collaboration
+| Command | Description |
+|---------|-------------|
+| `pa:activity` | Show recent AI activity |
+| `pa:lock` | Show/check lock status |
+| `pa:lock-release` | Release your lock |
+| `pa:handoff` | Create handoff notes for next AI |
+| `pa:handoff-read` | Read handoff notes |
+| `pa:session-end` | Generate session summary |
+
+### Learning & Tracking
+| Command | Description |
+|---------|-------------|
+| `pa:decision "title"` | Log architectural decision |
+| `pa:decisions` | Show all decisions |
+| `pa:error "description"` | Log error and solution |
+| `pa:errors` | Search past errors |
+| `pa:feedback "description"` | Log feedback for AI learning |
 
-## Commands
+### AI Platform Management
+| Command | Description |
+|---------|-------------|
+| `pa:ai-list` | List installed AI platforms |
+| `pa:ai-add` | Add more AI platforms |
+| `pa:ai-sync` | Sync config with files |
 
-Type `pa:` in your AI assistant to use ProAgents commands:
+### Navigation & Flow
+| Command | Description |
+|---------|-------------|
+| `pa:next` | Show next step in workflow |
+| `pa:resume` | Resume paused feature |
+| `pa:skip` | Skip current phase |
+| `pa:back` | Go to previous phase |
+| `pa:progress` | Show visual progress bar |
 
+### Context & History
 | Command | Description |
 |---------|-------------|
-| `pa:init` | Initialize ProAgents in your project |
-| `pa:feature` | Start a new feature |
-| `pa:fix` | Quick bug fix mode |
-| `pa:doc` | Generate documentation |
-| `pa:qa` | Quality assurance checks |
-| `pa:test` | Run test workflows |
-| `pa:deploy` | Deployment preparation |
-| `pa:status` | Check current status |
-| `pa:help` | Show all commands |
+| `pa:context` | View project context |
+| `pa:diff` | Show changes since last session |
+| `pa:history` | Show command history |
+| `pa:checkpoint` | Create restore point |
+| `pa:undo` | Undo last action |
+
+### Sprint & Estimation
+| Command | Description |
+|---------|-------------|
+| `pa:sprint-start` | Start new sprint |
+| `pa:sprint-end` | End sprint with summary |
+| `pa:estimate` | Estimate task complexity |
+| `pa:velocity` | Show velocity metrics |
+
+### Integration
+| Command | Description |
+|---------|-------------|
+| `pa:github` | GitHub integration |
+| `pa:github-pr` | Create pull request |
+| `pa:jira` | Sync with Jira |
+| `pa:notify` | Send notification |
+
+### Code Quality
+| Command | Description |
+|---------|-------------|
+| `pa:metrics` | Code quality metrics |
+| `pa:coverage` | Test coverage report |
+| `pa:deps` | Analyze dependencies |
+| `pa:deps-outdated` | Find outdated packages |
+| `pa:deps-security` | Security scan |
+
+### Custom Commands
+| Command | Description |
+|---------|-------------|
+| `pa:standup` | Generate daily standup |
+| `pa:tech-debt` | Scan for technical debt |
+| `pa:security-scan` | Run security checklist |
+
+Define your own in `./proagents/custom-commands.yaml`
 
 ---
 
-## Documentation
+## Key Files
 
-| Document | Description |
-|----------|-------------|
-| [Getting Started Story](./proagents/GETTING-STARTED-STORY.md) | Narrative walkthrough of a typical day |
-| [Complete Workflow Guide](./proagents/WORKFLOW.md) | Detailed 10-phase workflow documentation |
-| [Configuration Reference](./proagents/config/README.md) | Configuration options |
-| [Examples](./proagents/examples/) | Project-specific walkthroughs |
-| [Prompts](./proagents/prompts/) | AI prompts for each phase |
+After initialization, these files help AI understand your project:
+
+| File | Purpose | AI Should |
+|------|---------|-----------|
+| `proagents/context.md` | Persistent project knowledge | **Read first every session!** |
+| `proagents/feedback.md` | Past corrections & preferences | Learn from mistakes |
+| `proagents/watchlist.yaml` | Protected files list | Ask before modifying |
+| `proagents/activity.log` | AI activity history | Check for conflicts |
+| `proagents/decisions.md` | Architectural decisions | Understand why choices were made |
+| `proagents/errors.md` | Past errors & solutions | Find solutions faster |
+| `proagents/handoff.md` | Handoff notes | Continue where another AI left off |
 
 ---
 
 ## Project Structure
 
 ```
-proagents/
-├── README.md                 # Quick start guide
-├── WORKFLOW.md               # Complete workflow documentation
-├── proagents.config.yaml     # Configuration template
-├── prompts/                  # AI prompts for each phase
-├── templates/                # Output document templates
-├── checklists/               # Quality checklists
-├── standards/                # Customizable coding standards
-├── examples/                 # Project type walkthroughs
-├── config/                   # Integration configurations
-└── ...                       # Additional modules
+your-project/
+├── proagents/
+│   ├── proagents.config.yaml   # Project configuration
+│   ├── AI_INSTRUCTIONS.md      # Instructions for all AIs
+│   ├── PROAGENTS.md            # Quick command reference
+│   ├── context.md              # Persistent project context
+│   ├── feedback.md             # AI learning from corrections
+│   ├── watchlist.yaml          # Protected files
+│   ├── activity.log            # AI activity log
+│   ├── decisions.md            # Decision log
+│   ├── errors.md               # Error tracker
+│   ├── handoff.md              # Handoff notes
+│   ├── custom-commands.yaml    # Custom pa: commands
+│   ├── sessions/               # Session summaries
+│   ├── active-features/        # Feature tracking
+│   ├── prompts/                # Workflow prompts
+│   ├── templates/              # Document templates
+│   ├── checklists/             # Quality checklists
+│   └── ...
+├── CLAUDE.md                   # Claude-specific instructions
+├── .cursorrules                # Cursor-specific instructions
+├── GEMINI.md                   # Gemini-specific instructions
+└── proagents.config.yaml       # Main config (project root)
+```
+
+---
+
+## Configuration
+
+`proagents.config.yaml` stores your project settings:
+
+```yaml
+project:
+  name: my-app
+  type: nextjs
+
+automation:
+  decisions:
+    architecture:
+      api_style: rest
+      state_management: zustand
+      styling: tailwind
+      database: postgresql
+      orm: prisma
+      auth_method: jwt
+    testing:
+      framework: vitest
+      coverage_target: 80
+
+platforms:
+  - claude
+  - cursor
+  - copilot
 ```
 
 ---
 
-## Supported Integrations
+## Supported AI Platforms
+
+| Platform | Instruction File |
+|----------|-----------------|
+| Claude Code | `CLAUDE.md` |
+| Cursor | `.cursorrules` |
+| Windsurf | `.windsurfrules` |
+| GitHub 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` |
+
+---
+
+## Integrations
 
 **Project Management:** Jira, Linear, GitHub Issues, GitLab Issues, Asana, Trello, Notion
 
@@ -151,6 +374,17 @@ proagents/
 
 ---
 
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Getting Started Story](./proagents/GETTING-STARTED-STORY.md) | Narrative walkthrough |
+| [Complete Workflow](./proagents/WORKFLOW.md) | 10-phase workflow guide |
+| [AI Instructions](./proagents/AI_INSTRUCTIONS.md) | Full AI command reference |
+| [Examples](./proagents/examples/) | Project-specific walkthroughs |
+
+---
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
@@ -159,12 +393,10 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+MIT License - see [LICENSE](LICENSE) file.
 
 ---
 
-## Acknowledgments
-
-Built for developers who want to automate their workflow without vendor lock-in.
+**Built for developers who want AI collaboration without vendor lock-in.**
 
-**Co-authored with Claude (Anthropic)**
+*Co-authored with Claude (Anthropic)*

package/bin/proagents.js

@@ -9,6 +9,8 @@ import { helpCommand } from '../lib/commands/help.js';
 import { aiAddCommand, aiListCommand, aiRemoveCommand } from '../lib/commands/ai.js';
 import { uninstallCommand } from '../lib/commands/uninstall.js';
 import { configListCommand, configShowCommand, configEditCommand, configSetCommand, configGetCommand, configSetupCommand, configCustomizeCommand } from '../lib/commands/config.js';
+import { doctorCommand } from '../lib/commands/doctor.js';
+import { upgradeCommand } from '../lib/commands/upgrade.js';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
@@ -32,6 +34,8 @@ program
   .description('Initialize ProAgents in the current project')
   .option('-f, --force', 'Overwrite existing proagents folder')
   .option('--skip-config', 'Skip creating config file')
+  .option('-t, --template <name>', 'Use a project template (e.g., nextjs-saas, react-spa)')
+  .option('--list-templates', 'List available project templates')
   .action(initCommand);
 
 // Feature commands
@@ -157,4 +161,17 @@ program
   .description('Show all available commands with examples')
   .action(helpCommand);
 
+// Doctor command
+program
+  .command('doctor')
+  .description('Check health of ProAgents installation')
+  .action(doctorCommand);
+
+// Upgrade command
+program
+  .command('upgrade')
+  .description('Upgrade proagents folder to latest version')
+  .option('-f, --force', 'Skip confirmation prompt')
+  .action(upgradeCommand);
+
 program.parse();