proagents 1.0.17 → 1.1.0

package/proagents/PROAGENTS.md

@@ -2,7 +2,10 @@
 
 Execute these commands when user types them (prefix: `pa:`):
 
-> **Multi-AI Note:** Multiple AIs may work on this project. Always read fresh state from files before executing commands. See `./proagents/AI_INSTRUCTIONS.md` for details.
+## Quick Aliases
+`pa:f` → feature | `pa:s` → status | `pa:h` → help | `pa:d` → doc | `pa:t` → test | `pa:q` → qa | `pa:a` → analyze | `pa:r` → requirements | `pa:p` → plan | `pa:i` → implement
+
+> **Multi-AI Note:** Multiple AIs may work on this project. Always read `./proagents/activity.log` before executing commands, and log your actions after completing them.
 
 ## Commands
 
@@ -11,6 +14,11 @@ Execute these commands when user types them (prefix: `pa:`):
 | `pa:help` | Show this command table |
 | `pa:feature "name"` | Create `./proagents/active-features/feature-[name]/`, analyze codebase, implement feature |
 | `pa:fix "description"` | Find bug, fix it, update `./CHANGELOG.md` |
+| `pa:analyze` | Deep codebase analysis → `./proagents/cache/` |
+| `pa:requirements` | Gather requirements → `./proagents/active-features/` |
+| `pa:design` | UI/Architecture design phase |
+| `pa:plan` | Create implementation plan |
+| `pa:implement` | Execute implementation phase |
 | `pa:status` | Read `./proagents/active-features/*/status.json`, show progress |
 | `pa:qa` | Check code quality, run tests, report issues |
 | `pa:test` | Create/run tests for current work |
@@ -21,19 +29,92 @@ Execute these commands when user types them (prefix: `pa:`):
 | `pa:ai-add` | Show platform options, create AI instruction files |
 | `pa:ai-remove` | Show installed platforms, remove selected files |
 | `pa:ai-sync` | Sync config with existing files (fix mismatches) |
+| `pa:activity` | Show recent AI activity from `./proagents/activity.log` |
+| `pa:lock` | Show lock status, check if another AI is working |
+| `pa:lock-release` | Release your lock after completing work |
+| `pa:handoff` | Create handoff notes → `./proagents/handoff.md` |
+| `pa:handoff-read` | Read handoff notes before starting work |
+| `pa:session-end` | Generate session summary → `./proagents/sessions/` |
+| `pa:decision "title"` | Log architectural decision → `./proagents/decisions.md` |
+| `pa:error "desc"` | Log error & solution → `./proagents/errors.md` |
+| `pa:feedback "desc"` | Log feedback for AI learning → `./proagents/feedback.md` |
+| `pa:standup` | Generate daily standup summary |
+| `pa:tech-debt` | Scan for technical debt |
+
+## Navigation & Flow
+
+| Command | What to Do |
+|---------|------------|
+| `pa:next` | Show next step in current workflow |
+| `pa:resume` | Resume paused feature from last checkpoint |
+| `pa:skip` | Skip current phase, move to next |
+| `pa:back` | Go back to previous phase |
+| `pa:progress` | Show visual progress bar |
+
+## Context & History
+
+| Command | What to Do |
+|---------|------------|
+| `pa:context` | View project context |
+| `pa:diff` | Show changes since last session |
+| `pa:history` | Show command history with results |
+| `pa:checkpoint` | Create snapshot/restore point |
+| `pa:undo` | Undo last AI action (git revert) |
+
+## Sprint & Estimation
+
+| Command | What to Do |
+|---------|------------|
+| `pa:sprint-start` | Start new sprint → `./proagents/sprints/` |
+| `pa:sprint-end` | End sprint with summary |
+| `pa:estimate` | Estimate task complexity (S/M/L/XL) |
+| `pa:velocity` | Show velocity metrics |
+
+## Integration
+
+| Command | What to Do |
+|---------|------------|
+| `pa:github` | GitHub commands (issue, PR) |
+| `pa:github-pr` | Create pull request |
+| `pa:jira` | Sync with Jira ticket |
+| `pa:notify` | Send notification (Slack/email) |
+
+## Code Quality
+
+| Command | What to Do |
+|---------|------------|
+| `pa:metrics` | Show code quality metrics |
+| `pa:coverage` | Show test coverage report |
+| `pa:deps` | Analyze dependencies |
+| `pa:deps-outdated` | Find outdated packages |
+| `pa:deps-security` | Security scan dependencies |
+
+## Key Files to Read
+
+| File | Purpose |
+|------|---------|
+| `./proagents/context.md` | Persistent project context (READ FIRST!) |
+| `./proagents/feedback.md` | Past corrections - don't repeat mistakes |
+| `./proagents/watchlist.yaml` | Files requiring confirmation before changes |
+| `./proagents/errors.md` | Past errors and solutions |
+| `./proagents/decisions.md` | Architectural decisions and reasoning |
 
 ## Feature Workflow
 
-`pa:feature` follows these phases:
-1. **Init** → Create tracking files
-2. **Analysis** → Understand existing code
-3. **Requirements** → Define what to build
-4. **Design** → Plan architecture
-5. **Implementation** → Write code
-6. **Testing** → Create tests
-7. **Review** → Quality check
-8. **Documentation** → Update docs
-9. **Deploy** → Prepare release
+`pa:feature` runs all phases, or run individually:
+
+| Phase | Command | Action |
+|-------|---------|--------|
+| 1. Init | `pa:feature "name"` | Create tracking files |
+| 2. Analysis | `pa:analyze` | Understand existing code |
+| 3. Requirements | `pa:requirements` | Define what to build |
+| 4. Design | `pa:design` | Plan UI/architecture |
+| 5. Planning | `pa:plan` | Create implementation plan |
+| 6. Implementation | `pa:implement` | Write code |
+| 7. Testing | `pa:test` | Create/run tests |
+| 8. Review | `pa:review` | Quality check |
+| 9. Documentation | `pa:doc` | Update docs |
+| 10. Deployment | `pa:deploy` | Prepare release |
 
 ## Save Locations
 

package/proagents/activity.log

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

package/proagents/checkpoints.json

@@ -0,0 +1,13 @@
+{
+  "checkpoints": [],
+  "_comment": "Checkpoints are created with pa:checkpoint command",
+  "_format": {
+    "id": "cp-001",
+    "timestamp": "2024-03-06T15:00:00Z",
+    "commit": "abc123def",
+    "description": "Before major refactor",
+    "feature": "feature-name",
+    "phase": "implementation",
+    "created_by": "Claude:opus-4"
+  }
+}

package/proagents/context.md

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

package/proagents/custom-commands.yaml

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

package/proagents/decisions.md

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

package/proagents/errors.md

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

package/proagents/feedback.md

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

package/proagents/handoff.md

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

package/proagents/history.log

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

package/proagents/metrics/README.md

@@ -1,174 +1,69 @@
-# Metrics & KPIs
+# Code Metrics
 
-Track development productivity, code quality, and workflow effectiveness.
+This folder contains code quality metrics and reports.
 
----
+## Commands
 
-## Overview
+- `pa:metrics` - Show current code quality metrics
+- `pa:metrics-history` - Show metrics over time
+- `pa:coverage` - Show test coverage report
+- `pa:coverage-diff` - Show coverage changes
 
-ProAgents provides comprehensive metrics collection and KPI tracking to help teams understand their development velocity, code quality, and workflow effectiveness.
+## Files
 
----
-
-## Available Metrics
-
-| Category | Document | Description |
-|----------|----------|-------------|
-| [Developer Productivity](./developer-productivity.md) | Velocity, cycle time, throughput | Track team and individual efficiency |
-| [Code Quality KPIs](./code-quality-kpis.md) | Coverage, complexity, debt | Measure code health over time |
-| [Deployment Metrics](./deployment-metrics.md) | DORA, frequency, stability | Track delivery performance |
-| [Learning Effectiveness](./learning-effectiveness.md) | Adoption, improvement rates | Measure workflow optimization |
-
----
-
-## Quick Start
-
-### Enable Metrics Collection
-
-```yaml
-# proagents.config.yaml
-metrics:
-  enabled: true
-
-  collection:
-    developer_productivity: true
-    code_quality: true
-    deployment: true
-    learning: true
-
-  storage:
-    type: "local"  # local, database, api
-    path: ".proagents/metrics/"
-    retention_days: 90
-
-  reporting:
-    schedule: "weekly"  # daily, weekly, monthly
-    format: "markdown"  # markdown, json, html
-    output: "./reports/"
 ```
-
----
-
-## Dashboard Commands
-
-```bash
-# View current metrics dashboard
-pa:metrics dashboard
-
-# Generate weekly report
-pa:metrics report --period weekly
-
-# View specific category
-pa:metrics productivity
-pa:metrics quality
-pa:metrics deployment
-
-# Export metrics
-pa:metrics export --format json --output ./metrics.json
+metrics/
+├── latest.json         # Most recent metrics snapshot
+├── history/            # Historical metrics
+│   ├── 2024-03-01.json
+│   └── 2024-03-15.json
+└── README.md
 ```
 
----
-
-## Metric Categories
-
-### Developer Productivity Metrics
-
-| Metric | Description | Target |
-|--------|-------------|--------|
-| Cycle Time | Time from start to completion | < 3 days |
-| Throughput | Features completed per sprint | Consistent |
-| Lead Time | Time from request to delivery | < 1 week |
-| WIP | Work in progress count | < 3 per dev |
-
-### Code Quality Metrics
-
-| Metric | Description | Target |
-|--------|-------------|--------|
-| Test Coverage | Percentage of code tested | > 80% |
-| Code Complexity | Cyclomatic complexity | < 10 |
-| Tech Debt Ratio | Debt vs development time | < 5% |
-| Duplication | Duplicated code percentage | < 3% |
-
-### Deployment Metrics (DORA)
-
-| Metric | Description | Elite Target |
-|--------|-------------|--------------|
-| Deployment Frequency | How often you deploy | Multiple/day |
-| Lead Time for Changes | Commit to production | < 1 hour |
-| Change Failure Rate | Deployments causing failure | < 5% |
-| MTTR | Mean time to recovery | < 1 hour |
-
----
-
-## Integration
-
-### With CI/CD
-
-```yaml
-# .github/workflows/metrics.yml
-- name: Collect ProAgents Metrics
-  run: |
-    proagents metrics collect \
-      --coverage ./coverage/lcov.info \
-      --tests ./test-results.xml \
-      --commit ${{ github.sha }}
-```
-
-### With Dashboards
-
-```yaml
-# Export to external dashboards
-metrics:
-  export:
-    grafana:
-      enabled: true
-      endpoint: "${GRAFANA_URL}"
-    datadog:
-      enabled: true
-      api_key: "${DD_API_KEY}"
-```
-
----
-
-## Reports
-
-### Weekly Summary Template
-
-```markdown
-## Development Metrics - Week {{week}}
-
-### Productivity
-- Features Completed: {{features_completed}}
-- Average Cycle Time: {{avg_cycle_time}}
-- Throughput Trend: {{throughput_trend}}
-
-### Code Quality
-- Test Coverage: {{coverage}}% ({{coverage_trend}})
-- New Technical Debt: {{new_debt}}
-- Debt Resolved: {{resolved_debt}}
-
-### Deployment
-- Deployments: {{deployment_count}}
-- Success Rate: {{success_rate}}%
-- Average Lead Time: {{avg_lead_time}}
-
-### Highlights
-{{#each highlights}}
-- {{this}}
-{{/each}}
-
-### Action Items
-{{#each actions}}
-- [ ] {{this}}
-{{/each}}
+## Metrics Format
+
+```json
+{
+  "timestamp": "2024-03-06T15:00:00Z",
+  "generated_by": "Claude:opus-4",
+  "summary": {
+    "total_files": 45,
+    "total_lines": 12500,
+    "languages": {
+      "typescript": 10200,
+      "javascript": 1500,
+      "css": 800
+    }
+  },
+  "quality": {
+    "complexity": {
+      "average": 4.2,
+      "max": 15,
+      "high_complexity_files": ["src/utils/parser.ts"]
+    },
+    "duplication": {
+      "percentage": 3.5,
+      "duplicated_blocks": 12
+    }
+  },
+  "coverage": {
+    "overall": 82,
+    "by_module": {
+      "src/auth": 95,
+      "src/api": 78,
+      "src/utils": 65
+    }
+  }
+}
 ```
 
----
+## Thresholds
 
-## Best Practices
+Default thresholds (customize in proagents.config.yaml):
 
-1. **Focus on Trends**: Individual metrics matter less than trends over time
-2. **Context Matters**: Compare metrics within similar project types
-3. **Avoid Gaming**: Use metrics for improvement, not punishment
-4. **Regular Review**: Schedule weekly metric reviews
-5. **Team Ownership**: Let teams define their own targets
+| Metric | Warning | Error |
+|--------|---------|-------|
+| Coverage | < 70% | < 50% |
+| Complexity | > 10 | > 20 |
+| File size | > 300 lines | > 500 lines |
+| Duplication | > 5% | > 10% |

package/proagents/sessions/README.md

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