claude-mpm 4.1.6__py3-none-any.whl → 4.24.0__py3-none-any.whl

claude_mpm/agents/WORKFLOW.md

@@ -1,192 +1,360 @@
-<!-- WORKFLOW_VERSION: 0002 -->
-<!-- LAST_MODIFIED: 2025-01-14T18:30:00Z -->
+<!-- PURPOSE: 5-phase workflow execution details -->
 
 # PM Workflow Configuration
 
-## Mandatory Workflow Sequence
-
-**STRICT PHASES - MUST FOLLOW IN ORDER**:
+## Mandatory 5-Phase Sequence
 
 ### Phase 1: Research (ALWAYS FIRST)
-- Analyze requirements and gather context
-- Investigate existing patterns and architecture
-- Identify constraints and dependencies
-- Output feeds directly to implementation phase
-
-### Phase 2: Implementation (AFTER Research)
-- Engineer Agent for code implementation
-- Data Engineer Agent for data pipelines/ETL
-- Security Agent for security implementations
-- Ops Agent for infrastructure/deployment
-
-### Phase 3: Quality Assurance (AFTER Implementation)
-
-The PM routes QA work based on agent capabilities discovered at runtime. QA agents are selected dynamically based on their routing metadata (keywords, paths, file extensions) matching the implementation context.
-
-**Available QA Agents** (discovered dynamically):
-- **API QA Agent**: Backend/server testing (REST, GraphQL, authentication)
-- **Web QA Agent**: Frontend/browser testing (UI, accessibility, responsive)  
-- **General QA Agent**: Default testing (libraries, CLI tools, utilities)
-
-**Routing Decision Process**:
-1. Analyze implementation output for keywords, paths, and file patterns
-2. Match against agent routing metadata from templates
-3. Select agent(s) with highest confidence scores
-4. For multiple matches, execute by priority (specialized before general)
-5. For full-stack changes, run specialized agents sequentially
-
-**Dynamic Routing Benefits**:
-- Agent capabilities always current (pulled from templates)
-- New QA agents automatically available when deployed
-- Routing logic centralized in agent templates
-- No duplicate documentation to maintain
-
-The routing metadata in each agent template defines:
-- `keywords`: Trigger words that indicate this agent should be used
-- `paths`: Directory patterns that match this agent's expertise
-- `extensions`: File types this agent specializes in testing
-- `priority`: Execution order when multiple agents match
-- `confidence_threshold`: Minimum score for agent selection
-
-See deployed agent capabilities via agent discovery for current routing details.
-
-**CRITICAL Requirements**:
-- QA Agent MUST receive original user instructions for context
-- Validation against acceptance criteria defined in user request
-- Edge case testing and error scenarios for robust implementation
-- Performance and security validation where applicable
-- Clear, standardized output format for tracking and reporting
-
-### Phase 4: Documentation (ONLY after QA sign-off)
-- API documentation updates
-- User guides and tutorials
-- Architecture documentation
-- Release notes
-
-**Override Commands** (user must explicitly state):
-- "Skip workflow" - bypass standard sequence
-- "Go directly to [phase]" - jump to specific phase
-- "No QA needed" - skip quality assurance
-- "Emergency fix" - bypass research phase
-
-## Enhanced Task Delegation Format
-
-```
-Task: <Specific, measurable action>
-Agent: <Specialized Agent Name>
-Context:
-  Goal: <Business outcome and success criteria>
-  Inputs: <Files, data, dependencies, previous outputs>
-  Acceptance Criteria: 
-    - <Objective test 1>
-    - <Objective test 2>
-  Constraints:
-    Performance: <Speed, memory, scalability requirements>
-    Style: <Coding standards, formatting, conventions>
-    Security: <Auth, validation, compliance requirements>
-    Timeline: <Deadlines, milestones>
-  Priority: <Critical|High|Medium|Low>
-  Dependencies: <Prerequisite tasks or external requirements>
-  Risk Factors: <Potential issues and mitigation strategies>
-```
-
-
-### Research-First Scenarios
-
-Delegate to Research when:
-- Codebase analysis required
-- Technical approach unclear
-- Integration requirements unknown
-- Standards/patterns need identification
-- Architecture decisions needed
-- Domain knowledge required
-
-### 🔴 MANDATORY Ticketing Agent Integration 🔴
-
-**THIS IS NOT OPTIONAL - ALL WORK MUST BE TRACKED IN TICKETS**
-
-The PM MUST create and maintain tickets for ALL user requests. Failure to track work in tickets is a CRITICAL VIOLATION of PM protocols.
-
-**IMPORTANT**: The ticketing system uses `aitrackdown` CLI directly, NOT `claude-mpm tickets` commands.
-
-**ALWAYS delegate to Ticketing Agent when user mentions:**
-- "ticket", "tickets", "ticketing"
-- "epic", "epics"  
-- "issue", "issues"
-- "task tracking", "task management"
-- "project documentation"
-- "work breakdown"
-- "user stories"
-
-**AUTOMATIC TICKETING WORKFLOW** (when ticketing is requested):
-
-#### Session Initialization
-1. **Single Session Work**: Delegate to Ticketing Agent to create an ISS (Issue) ticket
-   - Use command: `aitrackdown create issue "Title" --description "Details"`
-   - Attach to appropriate existing epic or create new one
-   - Transition to in_progress: `aitrackdown transition ISS-XXXX in-progress`
-   
-2. **Multi-Session Work**: Delegate to Ticketing Agent to create an EP (Epic) ticket
-   - Use command: `aitrackdown create epic "Title" --description "Overview"`
-   - Create first ISS (Issue) for current session with `--issue EP-XXXX` parent
-   - Attach session issue to the epic
-
-#### Phase Tracking
-After EACH workflow phase completion, delegate to Ticketing Agent to:
-
-1. **Create TSK (Task) ticket** for the completed phase:
-   - **Research Phase**: `aitrackdown create task "Research findings" --issue ISS-XXXX`
-   - **Implementation Phase**: `aitrackdown create task "Code implementation" --issue ISS-XXXX`
-   - **QA Phase**: `aitrackdown create task "Testing results" --issue ISS-XXXX`
-   - **Documentation Phase**: `aitrackdown create task "Documentation updates" --issue ISS-XXXX`
-   
-2. **Update parent ISS ticket** with:
-   - Comment: `aitrackdown comment ISS-XXXX "Phase completion summary"`
-   - Transition status: `aitrackdown transition ISS-XXXX [status]`
-   - Valid statuses: open, in-progress, ready, tested, blocked
-
-3. **Task Ticket Content** should include:
-   - Agent that performed the work
-   - Summary of what was accomplished
-   - Key decisions or findings
-   - Files modified or created
-   - Any blockers or issues encountered
-
-#### Continuous Updates
-- **After significant changes**: `aitrackdown comment ISS-XXXX "Progress update"`
-- **When blockers arise**: `aitrackdown transition ISS-XXXX blocked`
-- **On completion**: `aitrackdown transition ISS-XXXX tested` or `ready`
-
-#### Ticket Hierarchy Example
-```
-EP-0001: Authentication System Overhaul (Epic)
-└── ISS-0001: Implement OAuth2 Support (Session Issue)
-    ├── TSK-0001: Research OAuth2 patterns and existing auth (Research Agent)
-    ├── TSK-0002: Implement OAuth2 provider integration (Engineer Agent)
-    ├── TSK-0003: Test OAuth2 implementation (QA Agent)
-    └── TSK-0004: Document OAuth2 setup and API (Documentation Agent)
-```
-
-The Ticketing Agent specializes in:
-- Creating and managing epics, issues, and tasks using aitrackdown CLI
-- Using proper commands: `aitrackdown create issue/task/epic`
-- Updating tickets: `aitrackdown transition`, `aitrackdown comment`
-- Tracking project progress with `aitrackdown status tasks`
-- Maintaining clear audit trail of all work performed
-
-### Proper Ticket Creation Delegation
-
-When delegating to Ticketing Agent, specify the exact aitrackdown commands:
-- **Create Issue**: "Use `aitrackdown create issue 'Title' --description 'Details'`"
-- **Create Task**: "Use `aitrackdown create task 'Title' --issue ISS-XXXX`"
-- **Update Status**: "Use `aitrackdown transition ISS-XXXX in-progress`"
-- **Add Comment**: "Use `aitrackdown comment ISS-XXXX 'Update message'`"
-
-### Ticket-Based Work Resumption
-
-**Tickets replace session resume for work continuation**:
-- Check for open tickets: `aitrackdown status tasks --filter "status:in-progress"`
-- Show ticket details: `aitrackdown show ISS-XXXX`
-- Resume work on existing tickets rather than starting new ones
-- Use ticket history to understand context and progress
-- This ensures continuity across sessions and PMs
+**Agent**: Research
+**Output**: Requirements, constraints, success criteria, risks
+**Template**:
+```
+Task: Analyze requirements for [feature]
+Return: Technical requirements, gaps, measurable criteria, approach
+```
+
+### Phase 2: Code Analyzer Review (MANDATORY)
+**Agent**: Code Analyzer (Opus model)
+**Output**: APPROVED/NEEDS_IMPROVEMENT/BLOCKED
+**Template**:
+```
+Task: Review proposed solution
+Use: think/deepthink for analysis
+Return: Approval status with specific recommendations
+```
+
+**Decision**:
+- APPROVED → Implementation
+- NEEDS_IMPROVEMENT → Back to Research
+- BLOCKED → Escalate to user
+
+### Phase 3: Implementation
+**Agent**: Selected via delegation matrix
+**Requirements**: Complete code, error handling, basic test proof
+
+### Phase 4: QA (MANDATORY)
+**Agent**: api-qa (APIs), web-qa (UI), qa (general)
+**Requirements**: Real-world testing with evidence
+
+**Routing**:
+```python
+if "API" in implementation: use api_qa
+elif "UI" in implementation: use web_qa
+else: use qa
+```
+
+### Phase 5: Documentation
+**Agent**: Documentation
+**When**: Code changes made
+**Output**: Updated docs, API specs, README
+
+## Git Security Review (Before Push)
+
+**Mandatory before `git push`**:
+1. Run `git diff origin/main HEAD`
+2. Delegate to Security Agent for credential scan
+3. Block push if secrets detected
+
+**Security Check Template**:
+```
+Task: Pre-push security scan
+Scan for: API keys, passwords, private keys, tokens
+Return: Clean or list of blocked items
+```
+
+## Publish and Release Workflow
+
+**Trigger Keywords**: "publish", "release", "deploy to PyPI/npm", "create release", "tag version"
+
+**Agent Responsibility**: Ops (local-ops or platform-specific)
+
+**Mandatory Requirements**: All changes committed, quality gates passed, security scan complete, version incremented
+
+### Process Overview
+
+Publishing and releasing is a **multi-step orchestrated workflow** requiring coordination across multiple agents with mandatory verification at each stage. The PM NEVER executes release commands directly - this is ALWAYS delegated to the appropriate Ops agent.
+
+### Workflow Phases
+
+#### Phase 1: Pre-Release Validation (Research + QA)
+
+**Agent**: Research
+**Purpose**: Validate readiness for release
+**Template**:
+```
+Task: Pre-release readiness check
+Requirements:
+  - Verify all uncommitted changes are tracked
+  - Check git status for untracked files
+  - Validate all features documented
+  - Confirm CHANGELOG updated
+Success Criteria: Clean working directory, complete documentation
+```
+
+**Decision**:
+- Clean → Proceed to Phase 2
+- Uncommitted changes → Report to user, request commit approval
+- Missing documentation → Delegate to Documentation agent
+
+#### Phase 2: Quality Gate Validation (QA)
+
+**Agent**: QA
+**Purpose**: Execute comprehensive quality checks
+**Template**:
+```
+Task: Run pre-publish quality gate
+Requirements:
+  - Execute: make pre-publish
+  - Verify all linters pass (Ruff, Black, isort, Flake8)
+  - Confirm test suite passes
+  - Validate version consistency
+  - Check for debug prints, TODO comments
+Evidence Required: Complete quality gate output
+```
+
+**Decision**:
+- All checks pass → Proceed to Phase 3
+- Any failure → BLOCK release, report specific failures to user
+- Must provide full quality gate output as evidence
+
+#### Phase 3: Security Scan (Security Agent) - MANDATORY
+
+**Agent**: Security
+**Purpose**: Pre-push credential and secrets scan
+**Template**:
+```
+Task: Pre-release security scan
+Requirements:
+  - Run git diff origin/main HEAD
+  - Scan for: API keys, passwords, tokens, private keys, credentials
+  - Check environment files (.env, .env.local)
+  - Verify no hardcoded secrets in code
+Success Criteria: CLEAN scan or BLOCKED with specific secrets identified
+Evidence Required: Security scan results
+```
+
+**Decision**:
+- CLEAN → Proceed to Phase 4
+- SECRETS DETECTED → BLOCK release immediately, report violations
+- NEVER bypass this step, even for "urgent" releases
+
+#### Phase 4: Version Management (Ops Agent)
+
+**Agent**: local-ops-agent
+**Purpose**: Increment version following conventional commits
+**Template**:
+```
+Task: Increment version and commit
+Requirements:
+  - Analyze recent commits since last release
+  - Determine bump type (patch/minor/major):
+    * patch: bug fixes (fix:)
+    * minor: new features (feat:)
+    * major: breaking changes (feat!, BREAKING CHANGE:)
+  - Execute: ./scripts/manage_version.py bump {type}
+  - Commit version changes with message: "chore: bump version to {version}"
+  - Push to origin/main
+Minimum Requirement: At least patch version bump
+Success Criteria: Version incremented, committed, pushed
+Evidence Required: New version number, git commit SHA
+```
+
+**Conventional Commit Detection**:
+```python
+if "BREAKING CHANGE:" in commits or "feat!" in commits:
+    bump_type = "major"
+elif "feat:" in commits:
+    bump_type = "minor"
+else:  # "fix:", "refactor:", "perf:", etc.
+    bump_type = "patch"
+```
+
+#### Phase 5: Build and Publish (Ops Agent)
+
+**Agent**: local-ops-agent
+**Purpose**: Build release artifacts and publish to distribution channels
+**Template**:
+```
+Task: Build and publish release
+Requirements:
+  - Execute: make safe-release-build (includes quality gate)
+  - Publish to PyPI: make release-pypi
+  - Publish to npm (if applicable): make release-npm
+  - Create GitHub release: gh release create v{version}
+  - Tag release in git
+Verification Required:
+  - Confirm build artifacts created
+  - Verify PyPI upload successful (check PyPI page)
+  - Verify npm upload successful (if applicable)
+  - Confirm GitHub release created
+Evidence Required:
+  - Build logs
+  - PyPI package URL
+  - npm package URL (if applicable)
+  - GitHub release URL
+```
+
+#### Phase 5.5: Update Homebrew Tap (Ops Agent) - NON-BLOCKING
+
+**Agent**: local-ops-agent
+**Purpose**: Update Homebrew formula with new version (automated)
+**Trigger**: Automatically after PyPI publish (Phase 5)
+**Template**:
+```
+Task: Update Homebrew tap for new release
+Requirements:
+  - Wait for PyPI package to be available (retry with backoff)
+  - Fetch SHA256 from PyPI for version {version}
+  - Update formula in homebrew-claude-mpm repository
+  - Update version and checksum in Formula/claude-mpm.rb
+  - Run formula tests locally (syntax check, brew audit)
+  - Commit changes with conventional commit message
+  - Push changes to homebrew-claude-mpm repository (with confirmation)
+Success Criteria: Formula updated and committed, or graceful failure logged
+Evidence Required: Git commit SHA in homebrew-claude-mpm or error log
+```
+
+**Decision**:
+- Success → Continue to GitHub release (Phase 5 continued)
+- Failure → Log warning with manual fallback instructions, continue anyway (NON-BLOCKING)
+
+**IMPORTANT**: Homebrew tap update failures do NOT block PyPI releases. This phase is designed to be non-blocking to ensure PyPI releases always succeed even if Homebrew automation encounters issues.
+
+**Manual Fallback** (if automation fails):
+```bash
+cd /path/to/homebrew-claude-mpm
+./scripts/update_formula.sh {version}
+git add Formula/claude-mpm.rb
+git commit -m "feat: update to v{version}"
+git push origin main
+```
+
+**Automation Details**:
+- Script: `scripts/update_homebrew_tap.sh`
+- Makefile target: `make update-homebrew-tap`
+- Integrated into: `make release-publish`
+- Retry logic: 10 attempts with exponential backoff
+- Timeout: 5 minutes maximum
+- Phase: Semi-automated (requires push confirmation in Phase 1)
+
+#### Phase 6: Post-Release Verification (Ops Agent) - MANDATORY
+
+**Agent**: Same ops agent that published
+**Purpose**: Verify release is accessible and installable
+**Template**:
+```
+Task: Verify published release
+Requirements:
+  - PyPI: Test installation in clean environment
+    * pip install claude-mpm=={version}
+    * Verify version: claude-mpm --version
+  - npm (if applicable): Test installation
+    * npm install claude-mpm@{version}
+    * Verify version
+  - GitHub: Verify release appears in releases page
+  - For hosted projects: Check deployment logs
+Success Criteria: Package installable from all channels
+Evidence Required: Installation output, version verification
+```
+
+**For Hosted Projects** (Vercel, Heroku, etc.):
+```
+Additional Verification:
+  - Check platform deployment logs
+  - Verify build status on platform dashboard
+  - Test live deployment URL
+  - Confirm no errors in server logs
+Evidence: Platform logs, HTTP response, deployment status
+```
+
+### Agent Routing Matrix
+
+| Task | Primary Agent | Fallback | Verification Agent |
+|------|---------------|----------|-------------------|
+| Pre-release validation | Research | - | - |
+| Quality gate | QA | - | - |
+| Security scan | Security | - | - |
+| Version increment | local-ops-agent | Ops (generic) | local-ops-agent |
+| PyPI publish | local-ops-agent | Ops (generic) | local-ops-agent |
+| Homebrew tap update | local-ops-agent (automated) | Manual fallback | local-ops-agent |
+| npm publish | local-ops-agent | Ops (generic) | local-ops-agent |
+| GitHub release | local-ops-agent | Ops (generic) | local-ops-agent |
+| Vercel deploy | vercel-ops-agent | - | vercel-ops-agent |
+| Platform deploy | Ops (generic) | - | Ops (generic) |
+| Post-release verification | Same as publisher | - | QA |
+
+### Minimum Requirements Checklist
+
+PM MUST verify these with agents before claiming release complete:
+
+- [ ] All changes committed (Research verification)
+- [ ] Quality gate passed (QA evidence: `make pre-publish` output)
+- [ ] Security scan clean (Security evidence: scan results)
+- [ ] Version incremented (Ops evidence: new version number)
+- [ ] PyPI package published (Ops evidence: PyPI URL)
+- [ ] Homebrew tap updated (Ops evidence: commit SHA or logged warning)
+- [ ] GitHub release created (Ops evidence: release URL)
+- [ ] Installation verified (Ops evidence: version check from PyPI/Homebrew)
+- [ ] Changes pushed to origin (Ops evidence: git push output)
+- [ ] Built successfully (Ops evidence: build logs)
+- [ ] Published to PyPI (Ops evidence: PyPI URL)
+- [ ] Published to npm if applicable (Ops evidence: npm URL)
+- [ ] GitHub release created (Ops evidence: release URL)
+- [ ] Installation verified (Ops evidence: pip/npm install output)
+- [ ] For hosted: Deployment verified (Ops evidence: platform logs + endpoint test)
+
+**If ANY checkbox unchecked → Release is INCOMPLETE**
+
+## Ticketing Integration
+
+**When user mentions**: ticket, epic, issue, task tracking
+
+**Architecture**: MCP-first with CLI fallback (v2.5.0+)
+
+**Process**:
+
+### PRIMARY: mcp-ticketer MCP Server (Preferred)
+When mcp-ticketer MCP tools are available, use them for all ticket operations:
+- `mcp__mcp-ticketer__create_ticket` - Create epics, issues, tasks
+- `mcp__mcp-ticketer__list_tickets` - List tickets with filters
+- `mcp__mcp-ticketer__get_ticket` - View ticket details
+- `mcp__mcp-ticketer__update_ticket` - Update status, priority
+- `mcp__mcp-ticketer__search_tickets` - Search by keywords
+- `mcp__mcp-ticketer__add_comment` - Add ticket comments
+
+### SECONDARY: aitrackdown CLI (Fallback)
+When mcp-ticketer is NOT available, fall back to aitrackdown CLI:
+- `aitrackdown create {epic|issue|task} "Title" --description "Details"`
+- `aitrackdown show {TICKET_ID}`
+- `aitrackdown transition {TICKET_ID} {status}`
+- `aitrackdown status tasks`
+- `aitrackdown comment {TICKET_ID} "Comment"`
+
+### Detection Workflow
+1. **Check MCP availability** - Attempt MCP tool use first
+2. **Graceful fallback** - If MCP unavailable, use CLI
+3. **User override** - Honor explicit user preferences
+4. **Error handling** - If both unavailable, inform user with setup instructions
+
+**Agent**: Delegate to `ticketing-agent` for all ticket operations
+
+## Structural Delegation Format
+
+```
+Task: [Specific measurable action]
+Agent: [Selected Agent]
+Requirements:
+  Objective: [Measurable outcome]
+  Success Criteria: [Testable conditions]
+  Testing: MANDATORY - Provide logs
+  Constraints: [Performance, security, timeline]
+  Verification: Evidence of criteria met
+```
+
+## Override Commands
+
+User can explicitly state:
+- "Skip workflow" - bypass sequence
+- "Go directly to [phase]" - jump to phase
+- "No QA needed" - skip QA (not recommended)
+- "Emergency fix" - bypass research