tapps-agents 3.6.0__py3-none-any.whl → 3.6.1__py3-none-any.whl

tapps_agents/resources/cursor/rules/agent-capabilities.mdc

@@ -0,0 +1,687 @@
+---
+description: Comprehensive guide to all 14 TappsCodingAgents workflow agents, their capabilities, and usage patterns
+alwaysApply: false
+---
+
+# TappsCodingAgents: Agent Capabilities Guide
+
+This guide helps you understand what each agent does, when to use them, and common usage patterns.
+
+## Overview
+
+TappsCodingAgents provides **14 specialized workflow agents** covering the complete software development lifecycle:
+
+- **Planning**: analyst, planner
+- **Design**: architect, designer
+- **Development**: implementer, debugger, documenter
+- **Testing**: tester
+- **Quality**: reviewer, improver, evaluator
+- **Operations**: ops
+- **Orchestration**: orchestrator
+- **Enhancement**: enhancer
+
+**Model selection:** Each skill specifies a `model_profile` (e.g. `reviewer_profile`). Override in `requirements/model_profiles.yaml` or project config; when a profile is missing, Cursor uses the project/user default. See `docs/MODEL_SELECTION.md` for resolution and overrides. Prefer higher-accuracy models for reviewer and security-review; lighter models for lint/score.
+
+---
+
+## Planning Agents
+
+### Analyst Agent
+
+**Purpose**: Requirements gathering, analysis, and project understanding.
+
+**When to Use**:
+- Starting a new feature or project
+- Understanding existing codebase
+- Gathering requirements from stakeholders
+- Analyzing project scope and complexity
+- Creating project profiles
+
+**Capabilities**:
+- Requirements analysis
+- Project profiling
+- Codebase analysis
+- Stakeholder interview simulation
+- Scope definition
+
+**Common Commands**:
+```bash
+python -m tapps_agents.cli analyst analyze "Add user authentication system"
+python -m tapps_agents.cli analyst requirements "Payment processing feature"
+python -m tapps_agents.cli analyst profile .
+```
+
+**Expert Integration**: Consults domain experts for business context.
+
+---
+
+### Planner Agent
+
+**Purpose**: Create development plans, user stories, and task breakdowns.
+
+**When to Use**:
+- Creating feature plans
+- Generating user stories
+- Breaking down epics into tasks
+- Planning sprint work
+- Creating implementation roadmaps
+
+**Capabilities**:
+- Feature planning
+- User story generation
+- Story management (list, filter, update)
+- Task breakdown
+- Epic organization
+
+**Common Commands**:
+```bash
+python -m tapps_agents.cli planner plan "Add user authentication system"
+python -m tapps_agents.cli planner create-story "User can log in" --epic auth --priority high
+python -m tapps_agents.cli planner list-stories --epic auth
+```
+
+**Expert Integration**: Consults domain experts for business rules and requirements.
+
+---
+
+## Design Agents
+
+### Architect Agent
+
+**Purpose**: System architecture design, technical decisions, and high-level design.
+
+**When to Use**:
+- Designing new systems
+- Making architectural decisions
+- Creating system diagrams
+- Defining technical patterns
+- Planning system integration
+
+**Capabilities**:
+- System architecture design
+- Technical pattern selection
+- Component design
+- Integration planning
+- Architecture documentation
+
+**Common Commands**:
+```bash
+python -m tapps_agents.cli architect design "Microservices architecture for e-commerce"
+python -m tapps_agents.cli architect patterns "REST API design patterns"
+```
+
+**Expert Integration**: Consults security, performance, and cloud infrastructure experts.
+
+---
+
+### Designer Agent
+
+**Purpose**: API design, data model design, and interface specifications.
+
+**When to Use**:
+- Designing REST APIs
+- Creating data models
+- Defining interfaces
+- Designing database schemas
+- Creating API specifications
+
+**Capabilities**:
+- API design (REST, GraphQL)
+- Data model design
+- Interface specification
+- Schema design
+- API documentation generation
+
+**Common Commands**:
+```bash
+python -m tapps_agents.cli designer design-api "User management API"
+python -m tapps_agents.cli designer design-model "Product catalog data model"
+```
+
+**Expert Integration**: Consults API design, UX, and data privacy experts.
+
+---
+
+## Development Agents
+
+### Implementer Agent
+
+**Purpose**: Code generation, implementation, and refactoring.
+
+**When to Use**:
+- Implementing new features
+- Generating code from specifications
+- Refactoring existing code
+- Creating new files
+- Writing production code
+
+**Capabilities**:
+- Code generation from specifications
+- File writing with safety checks
+- Code refactoring
+- Pattern following
+- Automatic code review integration
+
+**Common Commands**:
+```bash
+python -m tapps_agents.cli implementer implement "Create a function to calculate factorial" factorial.py
+python -m tapps_agents.cli implementer refactor service.py "Add type hints and extract helper functions"
+python -m tapps_agents.cli implementer generate-code "Create a REST API client class"
+```
+
+**Safety Features**:
+- Automatic code review before writing
+- File backups before overwriting
+- Path validation
+- File size limits
+- Automatic rollback on failure
+
+**Expert Integration**: Consults code quality and relevant domain experts.
+
+---
+
+### Debugger Agent
+
+**Purpose**: Error analysis, debugging, and code tracing.
+
+**When to Use**:
+- Debugging errors
+- Analyzing stack traces
+- Finding root causes
+- Code tracing
+- Error pattern analysis
+
+**Capabilities**:
+- Error analysis
+- Stack trace interpretation
+- Code tracing
+- Root cause analysis
+- Debugging strategies
+
+**Common Commands**:
+```bash
+python -m tapps_agents.cli debugger debug "ImportError: No module named 'xyz'" --file app.py --line 10
+python -m tapps_agents.cli debugger analyze-error "ValueError: invalid literal" --stack-trace "..."
+python -m tapps_agents.cli debugger trace "Function call path from main() to process_data()"
+```
+
+**Expert Integration**: Consults testing and code quality experts.
+
+---
+
+### Documenter Agent
+
+**Purpose**: Documentation generation, API docs, and README creation.
+
+**When to Use**:
+- Generating API documentation
+- Creating README files
+- Documenting code
+- Writing user guides
+- Creating technical documentation
+
+**Capabilities**:
+- API documentation generation
+- README generation
+- Code documentation
+- User guide creation
+- Technical writing
+
+**Common Commands**:
+```bash
+python -m tapps_agents.cli documenter document-api api.py
+python -m tapps_agents.cli documenter generate-readme .
+python -m tapps_agents.cli documenter document-code service.py
+```
+
+**Expert Integration**: Consults documentation and UX experts.
+
+---
+
+## Testing Agent
+
+### Tester Agent
+
+**Purpose**: Test generation, execution, and test strategy.
+
+**When to Use**:
+- Generating unit tests
+- Creating integration tests
+- Running test suites
+- Test coverage analysis
+- Test strategy planning
+
+**Capabilities**:
+- Unit test generation
+- Integration test generation
+- E2E test generation with **Playwright MCP awareness** (NEW): Automatically detects Playwright MCP availability and leverages it for browser automation
+- Test execution
+- Coverage analysis
+- Test strategy
+- **Coverage-driven test generation** (NEW): Generate targeted tests for uncovered code paths
+- **Test fixing** (NEW): Automatically fix common test failures (async/await, mocks, authentication)
+- **Batch test generation** (NEW): Generate tests for multiple files with shared fixtures
+- **Context-aware test generation** (NEW): Learn from existing test patterns in codebase
+- **Service integration testing** (NEW): Generate service-to-service integration tests
+
+**Common Commands**:
+```bash
+python -m tapps_agents.cli tester test service.py
+python -m tapps_agents.cli tester generate-tests service.py --integration
+python -m tapps_agents.cli tester run-tests
+# Coverage-driven testing (NEW)
+python -m tapps_agents.cli tester analyze-coverage coverage.json --target 80
+python -m tapps_agents.cli tester generate-coverage-tests coverage.json --module src/clients
+# Test fixing (NEW)
+python -m tapps_agents.cli tester fix-failures tests/ --pattern async --auto-fix
+# Batch generation (NEW)
+python -m tapps_agents.cli tester generate-tests-batch src/clients/*.py --output-dir tests/clients
+```
+
+**Playwright MCP Integration**:
+- Automatically detects Playwright MCP server availability when generating E2E tests
+- Leverages Playwright MCP tools for browser automation when available
+- Falls back to Python Playwright package if MCP not configured
+- Check status: `tapps-agents doctor` shows Playwright MCP configuration
+
+**Expert Integration**: Consults testing and code quality experts.
+
+---
+
+## Quality Agents
+
+### Reviewer Agent
+
+**Purpose**: Code review, quality analysis, and scoring.
+
+**When to Use**:
+- Code quality checks
+- Pre-commit reviews
+- Quality scoring
+- Linting and type checking
+- Security analysis
+
+**Capabilities**:
+- Code scoring (7 categories: complexity, security, maintainability, test coverage, performance, structure, devex)
+- LLM-based code review
+- Linting (Ruff)
+- Type checking (mypy)
+- Quality reports (JSON, Markdown, HTML)
+
+**Common Commands**:
+```bash
+# Quick score (fast, no LLM)
+python -m tapps_agents.cli reviewer score file.py
+
+# Full review (with LLM feedback)
+python -m tapps_agents.cli reviewer review file.py
+
+# Quality tools
+python -m tapps_agents.cli reviewer lint file.py
+python -m tapps_agents.cli reviewer type-check file.py
+python -m tapps_agents.cli reviewer report . json markdown html
+```
+
+**Scoring Metrics**:
+- **Complexity Score** (0-10): Cyclomatic complexity
+- **Security Score** (0-10): Vulnerability detection
+- **Maintainability Score** (0-10): Code quality metrics
+- **Test Coverage** (0-10): Test coverage analysis
+- **Performance Score** (0-10): Performance patterns
+- **Overall Score** (0-100): Weighted combination
+
+**Expert Integration**: Consults security, code quality, and performance experts.
+
+---
+
+### Improver Agent
+
+**Purpose**: Code refactoring, optimization, and improvement.
+
+**When to Use**:
+- Refactoring code
+- Performance optimization
+- Code improvement
+- Technical debt reduction
+- Code modernization
+
+**Capabilities**:
+- Code refactoring
+- Performance optimization
+- Code improvement suggestions
+- Technical debt analysis
+- Pattern modernization
+
+**Common Commands**:
+```bash
+python -m tapps_agents.cli improver improve file.py "Refactor to use async/await"
+python -m tapps_agents.cli improver optimize file.py "Improve performance"
+python -m tapps_agents.cli improver refactor file.py "Extract common patterns"
+```
+
+**Expert Integration**: Consults performance, code quality, and architecture experts.
+
+---
+
+### Evaluator Agent
+
+**Purpose**: Framework effectiveness evaluation, usage pattern analysis, and continuous improvement recommendations.
+
+**When to Use**:
+- Evaluating TappsCodingAgents framework effectiveness
+- Analyzing usage patterns (CLI vs Cursor Skills vs Simple Mode)
+- Measuring workflow adherence
+- Generating improvement recommendations
+- Tracking quality metrics over time
+
+**Capabilities**:
+- Usage pattern analysis
+- Workflow adherence measurement
+- Quality metrics collection
+- Structured evaluation reports
+- Prioritized recommendations (Priority 1, 2, 3)
+
+**Common Commands**:
+```bash
+python -m tapps_agents.cli evaluator evaluate
+python -m tapps_agents.cli evaluator evaluate --workflow-id workflow-123
+python -m tapps_agents.cli evaluator evaluate-workflow workflow-123
+```
+
+**Output**: Structured markdown reports saved to `.tapps-agents/evaluations/`
+
+**Expert Integration**: Read-only agent focused on framework analysis.
+
+---
+
+## Operations Agent
+
+### Ops Agent
+
+**Purpose**: Security, compliance, deployment, and dependency management.
+
+**When to Use**:
+- Security audits
+- Compliance checks
+- Deployment planning
+- Dependency auditing
+- Infrastructure as code
+
+**Capabilities**:
+- Security auditing
+- Compliance checking (HIPAA, GDPR, PCI DSS)
+- Deployment strategies
+- Dependency vulnerability scanning
+- Bundle analysis (Node/React/Vue; opt-in, best-effort)
+- Infrastructure planning
+
+**Common Commands**:
+```bash
+python -m tapps_agents.cli ops audit-security .
+python -m tapps_agents.cli ops check-compliance --standard GDPR
+python -m tapps_agents.cli ops audit-dependencies
+python -m tapps_agents.cli ops audit-bundle
+python -m tapps_agents.cli ops plan-deployment "Kubernetes deployment"
+```
+
+**Expert Integration**: Consults security, data privacy, cloud infrastructure, and DevOps experts.
+
+---
+
+## Orchestration Agent
+
+### Orchestrator Agent
+
+**Purpose**: Workflow coordination, multi-agent orchestration, and task sequencing.
+
+**When to Use**:
+- Coordinating multiple agents
+- Managing complex workflows
+- Sequencing tasks
+- Workflow execution
+- Agent coordination
+
+**Capabilities**:
+- Multi-agent orchestration
+- Workflow execution
+- Task sequencing
+- Agent coordination
+- Workflow state management
+- **Epic orchestration** (NEW): Execute Epic documents with story dependency resolution
+- **Quality gate enforcement** (NEW): Automatic quality checks with loopback on failures
+- **Service integration** (NEW): Automate service-to-service integration (client generation, config updates)
+
+**Common Commands**:
+```bash
+python -m tapps_agents.cli orchestrator orchestrate workflow.yaml
+python -m tapps_agents.cli orchestrator sequence "plan,design,implement,test"
+# Epic orchestration (NEW)
+@simple-mode *epic docs/prd/epic-51-yaml-automation-quality-enhancement.md
+# Service integration (NEW)
+python -m tapps_agents.cli orchestrator integrate-service "service1" --with "service2"
+```
+
+**Expert Integration**: Consults AI frameworks expert for orchestration patterns.
+
+---
+
+## Enhancement Agent
+
+### Enhancer Agent
+
+**Purpose**: Prompt enhancement with expert consultation and context enrichment.
+
+**When to Use**:
+- Enhancing simple prompts into comprehensive specifications
+- Adding domain context to prompts
+- Enriching requirements
+- Creating detailed implementation prompts
+- Quick prompt iteration
+
+**Capabilities**:
+- **Full Enhancement Pipeline** (7 stages):
+  1. Analysis: Intent and scope detection
+  2. Requirements: Functional/non-functional requirements
+  3. Architecture: System design guidance
+  4. Codebase Context: Relevant code patterns
+  5. Quality Standards: Security, testing thresholds
+  6. Implementation Strategy: Task breakdown
+  7. Synthesis: Final enhanced prompt
+- **Quick Enhancement**: Fast path (stages 1-3)
+- **Stage-by-Stage**: Run specific stages independently
+- **Session Management**: Resume interrupted sessions
+
+**Common Commands**:
+```bash
+# Full enhancement
+python -m tapps_agents.cli enhancer enhance "Add user authentication"
+
+# Quick enhancement
+python -m tapps_agents.cli enhancer enhance-quick "Add user authentication"
+
+# Stage-by-stage
+python -m tapps_agents.cli enhancer enhance-stage analysis "Create payment system"
+python -m tapps_agents.cli enhancer enhance-stage requirements --session-id <session-id>
+```
+
+**Expert Integration**: Automatically detects domains and consults relevant Industry Experts with weighted decision-making (Primary 51%, Others 49%).
+
+**Output Formats**: Markdown (default), JSON, YAML
+
+**Workflow integration:** full-sdlc (optional enhance before requirements), rapid-dev, and Epic run enhance steps via EnhancerHandler. **CLI auto-enhancement:** `auto_enhancement` and `PROMPT_ARGUMENT_MAP` in docs/CONFIGURATION.md.
+
+---
+
+## Agent Selection Guide
+
+### By Task Type
+
+| Task | Primary Agent | Supporting Agents |
+|------|--------------|-------------------|
+| **New Feature** | planner → implementer | analyst, architect, tester, reviewer |
+| **Bug Fix** | debugger → implementer | tester, reviewer |
+| **Code Review** | reviewer | - |
+| **Refactoring** | improver | reviewer, tester |
+| **Framework Evaluation** | evaluator | reviewer |
+| **Architecture** | architect | analyst, designer |
+| **API Design** | designer | architect, documenter |
+| **Testing** | tester | reviewer |
+| **Documentation** | documenter | - |
+| **Security Audit** | ops | reviewer |
+| **Prompt Enhancement** | enhancer | analyst, architect, planner |
+
+### By Workflow Stage
+
+| Stage | Agents |
+|-------|--------|
+| **Planning** | analyst, planner |
+| **Design** | architect, designer |
+| **Implementation** | implementer, debugger |
+| **Testing** | tester |
+| **Quality** | reviewer, improver |
+| **Operations** | ops |
+| **Documentation** | documenter |
+| **Orchestration** | orchestrator |
+
+---
+
+## Common Usage Patterns
+
+### Pattern 1: New Feature Development
+
+```bash
+# 1. Plan the feature
+python -m tapps_agents.cli planner plan "Add user authentication"
+
+# 2. Enhance the prompt (optional but recommended)
+python -m tapps_agents.cli enhancer enhance "Add user authentication"
+
+# 3. Design the system
+python -m tapps_agents.cli architect design "Authentication system architecture"
+
+# 4. Design the API
+python -m tapps_agents.cli designer design-api "Authentication API"
+
+# 5. Implement
+python -m tapps_agents.cli implementer implement "Authentication service" auth_service.py
+
+# 6. Test
+python -m tapps_agents.cli tester test auth_service.py
+
+# 7. Review
+python -m tapps_agents.cli reviewer review auth_service.py
+```
+
+### Pattern 2: Bug Fix
+
+```bash
+# 1. Debug the error
+python -m tapps_agents.cli debugger debug "Error message" --file buggy.py --line 42
+
+# 2. Fix the code
+python -m tapps_agents.cli implementer refactor buggy.py "Fix the bug"
+
+# 3. Test
+python -m tapps_agents.cli tester test buggy.py
+
+# 4. Review
+python -m tapps_agents.cli reviewer score buggy.py
+```
+
+### Pattern 3: Code Quality Improvement
+
+```bash
+# 1. Analyze current quality
+python -m tapps_agents.cli reviewer report . json markdown html
+
+# 2. Improve code
+python -m tapps_agents.cli improver improve file.py "Refactor for better maintainability"
+
+# 3. Verify improvement
+python -m tapps_agents.cli reviewer score file.py
+```
+
+### Pattern 4: Security Audit
+
+```bash
+# 1. Security audit
+python -m tapps_agents.cli ops audit-security .
+
+# 2. Review findings
+python -m tapps_agents.cli reviewer review --security .
+
+# 3. Fix issues
+python -m tapps_agents.cli implementer refactor vulnerable.py "Fix security issues"
+```
+
+---
+
+## Expert Integration
+
+Several agents automatically consult **Industry Experts** and **Built-in Experts** for domain-specific guidance:
+
+### Agents with Expert Integration
+
+1. **Architect**: Security, Performance, Cloud Infrastructure
+2. **Designer**: API Design, UX, Data Privacy
+3. **Implementer**: Code Quality, Domain Experts
+4. **Reviewer**: Security, Code Quality, Performance
+5. **Tester**: Testing, Code Quality
+6. **Ops**: Security, Data Privacy, Cloud Infrastructure, DevOps
+7. **Enhancer**: All relevant domain experts (automatic detection)
+
+### Expert Consultation Process
+
+1. Agent identifies relevant domains
+2. Expert Registry finds matching experts
+3. Weighted consultation (Primary 51%, Others 49%)
+4. Aggregated response with confidence scores
+5. Expert advice integrated into agent output
+
+---
+
+## Configuration
+
+Agent behavior is configured in `.tapps-agents/config.yaml`:
+
+```yaml
+agents:
+  reviewer:
+    quality_threshold: 70  # Minimum overall score
+    security_threshold: 7.0
+    maintainability_threshold: 7.0
+  
+  implementer:
+    require_review: true
+    auto_approve_threshold: 80.0
+    backup_files: true
+  
+  tester:
+    coverage_threshold: 80.0
+    generate_integration_tests: true
+```
+
+---
+
+## Best Practices
+
+1. **Start with Planning**: Use `analyst` and `planner` for new features
+2. **Enhance Prompts**: Use `enhancer` to enrich simple prompts before implementation
+3. **Design Before Code**: Use `architect` and `designer` for complex features
+4. **Review Before Commit**: Always run `reviewer` before committing code
+5. **Test After Implementation**: Use `tester` to generate and run tests
+6. **Use Workflows**: Leverage workflow presets for common patterns
+7. **Consult Experts**: Agents automatically consult experts, but you can also use `enhancer` for explicit expert consultation
+
+---
+
+## Related Documentation
+
+- [When to Use](when-to-use.mdc) - ⭐ **Importance and when to use** each capability (workflows, agents, commands)
+- [Command Reference](command-reference.mdc) - ⭐ **Complete command reference** - All commands and parameters
+- [Simple Mode](simple-mode.mdc) - ⭐ **Recommended orchestration method** - Complete workflow execution
+- [Quick Reference](quick-reference.mdc) - Quick command reference
+- [Workflow Presets](workflow-presets.mdc) - Workflow documentation
+- [Simple Mode User Guide](../docs/SIMPLE_MODE_USER_GUIDE.md) - How to ensure workflow execution
+- [API Documentation](../docs/API.md) - Full API reference
+- [Configuration Guide](../docs/CONFIGURATION.md) - Configuration details

tapps_agents/resources/cursor/rules/coding-style.mdc

@@ -0,0 +1,31 @@
+---
+description: Immutability, file and line limits, structure; code quality and static analysis patterns
+alwaysApply: false
+---
+
+# Coding Style Rules
+
+Guidelines for consistency and maintainability.
+
+## Immutability and Side Effects
+
+- Prefer immutable data and pure functions where practical
+- Isolate side effects (I/O, mutations) at boundaries
+- Document when mutating shared state is necessary
+
+## File and Line Limits
+
+- Keep files under ~400 lines; split when larger
+- Prefer functions under ~50 lines; extract when logic grows
+- Use consistent module and package structure
+
+## Structure and Organization
+
+- One primary responsibility per module or class
+- Place public API at top; helpers and private below
+- Group related code; avoid scattered concerns
+
+## References
+
+- `tapps_agents/experts/knowledge/code-quality-analysis/` - code-metrics, complexity-analysis, static-analysis-patterns, technical-debt-patterns, quality-gates
+- Use `@reviewer *lint` and `@reviewer *review` for enforcement