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

tapps_agents/resources/cursor/rules/quick-reference.mdc

@@ -0,0 +1,630 @@
+---
+description: Quick reference guide for common TappsCodingAgents commands and workflows. DEFAULT to @simple-mode for all development tasks.
+alwaysApply: false
+---
+
+# TappsCodingAgents Quick Reference
+
+## ⚠️ IMPORTANT: Default to @simple-mode
+
+**For ALL development tasks, you should DEFAULT to using `@simple-mode` commands.**
+
+**New Feature:** Simple Mode now proactively suggests workflows when you request feature implementation, bug fixes, or code reviews. These suggestions help ensure you get automatic test generation, quality gates, and comprehensive documentation.
+
+### Quick Decision Guide
+
+| User Wants To... | Use This Command |
+|------------------|------------------|
+| Build a new feature | `@simple-mode *build "description"` (includes mandatory tests, 80%+ coverage) |
+| Fix a bug/error | `@simple-mode *fix <file> "description"` |
+| Review code quality | `@simple-mode *review <file>` |
+| Add tests | `@simple-mode *test <file>` |
+| Refactor code | `@simple-mode *refactor <file>` |
+| TDD (Red-Green-Refactor) | `@simple-mode *tdd <file>` or `*tdd "description"` |
+| E2E tests | `@simple-mode *e2e` or `@tester *generate-e2e-tests` |
+| Fix build/compile errors | `@simple-mode *build-fix "output or description"` |
+| Dead code cleanup | `@simple-mode *refactor-clean <file>` |
+| Sync documentation | `@simple-mode *update-docs [path]` |
+| Refresh codemap/Context7 | `@simple-mode *update-codemaps` |
+| Coverage-driven tests | `@simple-mode *test-coverage <file> --target 80` |
+| Security audit | `@simple-mode *security-review [path]` or `@security-review` |
+| Coding standards | `@coding-standards` or `@simple-mode *review` |
+| Backend patterns | `@backend-patterns` |
+| Frontend/a11y patterns | `@frontend-patterns` |
+| Quick score only | `@reviewer *score <file>` (exception) |
+
+**Importance and when to use:** See `when-to-use.mdc` for which capabilities matter most (Tier 1–2 first) and when to use each workflow, agent, and command.
+
+---
+
+## ⚠️ IMPORTANT: CLI Workflow Commands Not Recommended in Cursor Mode
+
+**If you see a warning about CLI workflow commands in Cursor mode:**
+
+- ✅ **Use `@simple-mode` commands in Cursor chat instead**
+- ✅ **Use CLI commands in terminal/CI (outside Cursor IDE)**
+- ✅ **Run `tapps-agents init` if Simple Mode isn't working**
+
+See `.cursor/rules/cursor-mode-usage.mdc` for complete guidance.
+
+---
+
+## Where to Run Commands: Cursor Chat vs Terminal/CI
+
+### Use Cursor Chat (Recommended for Interactive Development)
+
+**Best for:** Interactive development, natural language, learning, iterative work
+
+**Primary Syntax:** `@simple-mode *command` (orchestrates multiple agents)
+**Advanced Syntax:** `@agent-name *command` (single agent operations)
+
+**Examples:**
+```cursor
+# Simple Mode (RECOMMENDED - use this by default)
+@simple-mode *build "Add user authentication"
+@simple-mode *review src/api.py
+@simple-mode *fix src/buggy.py "Fix the error"
+@simple-mode *test src/service.py
+@simple-mode *refactor src/legacy.py
+
+# Individual agents (use only for targeted operations)
+@reviewer *score src/main.py
+@reviewer *review src/api.py
+@implementer *implement "Add feature" src/feature.py
+@tester *test src/utils.py
+@debugger *debug "KeyError: 'user_id'" --file src/api.py --line 42
+```
+
+**Advantages:**
+- Natural language interaction
+- Context-aware (file open, selection)
+- Integrated with IDE
+- Skill-based execution
+
+### Use Terminal/CI (Recommended for Automation)
+
+**Best for:** Batch processing, CI/CD pipelines, scripting, headless environments
+
+**Syntax:** `tapps-agents <agent> <command> [--flags]`
+
+**Global options (all commands; flags can appear before OR after the subcommand):**
+
+```bash
+# Progress UI (modern 2025-style: Rich spinner/progress when interactive)
+tapps-agents doctor --progress rich
+tapps-agents reviewer score README.md --no-progress
+
+# Equivalent (flags before subcommand)
+tapps-agents --progress plain doctor
+```
+
+- `--quiet` / `-q`: Quiet mode (errors + final results)
+- `--verbose` / `-v`: Verbose diagnostics
+- `--progress {auto,rich,plain,off}`: Progress UI mode
+- `--no-progress`: Disable progress UI (same as `--progress off`)
+- Env: `TAPPS_PROGRESS=auto|rich|plain|off`, `TAPPS_NO_PROGRESS=1` / `NO_PROGRESS=1`
+
+**Examples:**
+```bash
+# Workflow presets (automated)
+tapps-agents workflow rapid --prompt "Add feature" --auto
+tapps-agents workflow fix --file src/buggy.py --auto
+
+# Batch processing
+tapps-agents reviewer review --pattern "**/*.py" --max-workers 8
+tapps-agents reviewer score src/ --format json > quality-report.json
+
+# CI/CD quality gates
+tapps-agents reviewer score src/ --format json
+tapps-agents reviewer lint src/ --format json
+```
+
+**Advantages:**
+- Scriptable and automatable
+- Structured output formats (JSON)
+- Batch file processing
+- CI/CD integration
+- Workflow state management
+
+### Dual-Mode Commands
+
+These commands work in **both** modes with equivalent results:
+
+| Task | Cursor Syntax | CLI Syntax |
+|------|---------------|------------|
+| Review | `@reviewer *review <file>` | `tapps-agents reviewer review <file>` |
+| Score | `@reviewer *score <file>` | `tapps-agents reviewer score <file>` |
+| Implement | `@implementer *implement "<spec>" <file>` | `tapps-agents implementer implement "<spec>" <file>` |
+| Test | `@tester *test <file>` | `tapps-agents tester test <file>` |
+| Debug | `@debugger *debug "<error>" --file <file>` | `tapps-agents debugger debug "<error>" --file <file>` |
+
+**Choose based on:**
+- **Cursor**: Interactive, context-aware, natural language
+- **CLI**: Batch, automation, structured output, CI/CD
+
+---
+
+## Most Common Commands
+
+### Code Review & Quality
+```bash
+# Quick code scoring (fast, no LLM)
+python -m tapps_agents.cli reviewer score <file>
+
+# Full code review (with LLM feedback)
+python -m tapps_agents.cli reviewer review <file>
+
+# Linting (Ruff)
+python -m tapps_agents.cli reviewer lint <file>
+
+# Type checking (mypy)
+python -m tapps_agents.cli reviewer type-check <file>
+
+# Generate quality reports
+python -m tapps_agents.cli reviewer report <dir> json markdown html
+```
+
+### Workflow Presets
+```bash
+# List all workflows
+python -m tapps_agents.cli workflow list
+
+# Run workflows
+python -m tapps_agents.cli workflow rapid      # Feature development
+python -m tapps_agents.cli workflow full       # Enterprise SDLC
+python -m tapps_agents.cli workflow quality    # Quality improvement
+python -m tapps_agents.cli workflow fix         # Bug fixes & refactoring
+python -m tapps_agents.cli workflow hotfix     # Urgent fixes
+```
+
+### Workflow Execution Flags
+```bash
+# Pre-flight validation (check before running)
+tapps-agents workflow rapid --dry-run --prompt "Add feature"
+
+# Explicit mode control
+tapps-agents workflow rapid --cli-mode --prompt "Add feature"   # Force CLI/headless
+tapps-agents workflow rapid --cursor-mode --prompt "Add feature" # Force Cursor Skills
+
+# Resume/partial execution
+tapps-agents workflow rapid --continue-from implementation --prompt "Add feature"
+tapps-agents workflow rapid --skip-steps "enhance,plan" --prompt "Add feature"
+
+# Output control
+tapps-agents workflow rapid --print-paths --prompt "Add feature"  # Show artifact paths (default)
+tapps-agents workflow rapid --no-print-paths --prompt "Add feature"
+```
+
+### Quick Project Creation (Cursor Native)
+```bash
+# Create a complete project from description (uses full SDLC workflow)
+python -m tapps_agents.cli create "Create a modern web application"
+
+# This is a shortcut for: workflow full --auto --prompt
+# Automatically runs in Cursor-native mode
+# Uses Cursor Skills
+```
+
+### Code Generation
+```bash
+# Generate code from specification
+python -m tapps_agents.cli implementer implement "description" <file.py>
+
+# Refactor existing code
+python -m tapps_agents.cli implementer refactor <file.py> "instruction"
+
+# Generate code without writing to file
+python -m tapps_agents.cli implementer generate-code "description"
+```
+
+### Testing
+```bash
+# Generate and run tests
+python -m tapps_agents.cli tester test <file.py>
+
+# Generate tests only
+python -m tapps_agents.cli tester generate-tests <file.py>
+
+# Run existing tests
+python -m tapps_agents.cli tester run-tests
+```
+
+### Environment & Setup
+```bash
+# Check environment status
+python -m tapps_agents.cli doctor
+
+# Initialize project
+python -m tapps_agents.cli init
+
+# Setup experts
+python -m tapps_agents.cli setup-experts init --yes --non-interactive
+```
+
+## Agent Usage Patterns
+
+### Reviewer Agent
+**Best for:** Code quality analysis, scoring, linting, type checking
+```bash
+# Quick score (fastest)
+python -m tapps_agents.cli reviewer score <file>
+
+# Full review (comprehensive)
+python -m tapps_agents.cli reviewer review <file> --model qwen2.5-coder:7b
+
+# Quality tools
+python -m tapps_agents.cli reviewer lint <file>
+python -m tapps_agents.cli reviewer type-check <file>
+python -m tapps_agents.cli reviewer report <dir> json markdown html
+```
+
+### Implementer Agent
+**Best for:** Code generation, refactoring, implementation
+```bash
+# Generate new code
+python -m tapps_agents.cli implementer implement "Create a function to calculate factorial" factorial.py
+
+# Refactor existing code
+python -m tapps_agents.cli implementer refactor service.py "Add type hints and extract helper functions"
+```
+
+### Planner Agent
+**Best for:** Planning features, creating user stories
+```bash
+# Create a plan
+python -m tapps_agents.cli planner plan "Add user authentication system"
+
+# Create user story
+python -m tapps_agents.cli planner create-story "User can log in" --epic auth --priority high
+
+# List stories
+python -m tapps_agents.cli planner list-stories
+```
+
+### Tester Agent
+**Best for:** Test generation and execution
+```bash
+# Generate and run tests
+python -m tapps_agents.cli tester test service.py
+
+# Generate integration tests
+python -m tapps_agents.cli tester test service.py --integration
+```
+
+### Debugger Agent
+**Best for:** Error analysis and debugging
+```bash
+# Debug an error
+python -m tapps_agents.cli debugger debug "ImportError: No module named 'xyz'" --file app.py --line 10
+
+# Analyze error
+python -m tapps_agents.cli debugger analyze-error "ValueError: invalid literal" --stack-trace "..."
+```
+
+### Enhancer Agent
+**Best for:** Prompt enhancement with expert consultation. Workflow: full-sdlc (optional), rapid-dev, Epic (EnhancerHandler). CLI: `auto_enhancement` (CONFIGURATION.md).
+```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"
+```
+
+### Evaluator Agent
+**Best for:** Framework effectiveness evaluation and continuous improvement
+```bash
+# Evaluate framework effectiveness
+@evaluator *evaluate
+@evaluator *evaluate --workflow-id workflow-123
+
+# Evaluate specific workflow
+@evaluator *evaluate-workflow workflow-123
+
+# CLI equivalent
+tapps-agents evaluator evaluate
+tapps-agents evaluator evaluate --workflow-id workflow-123
+tapps-agents evaluator evaluate-workflow workflow-123
+```
+
+**Output:** Structured markdown reports saved to `.tapps-agents/evaluations/`
+
+## Development Workflows
+
+### Adding a New Feature
+1. **Plan:** `python -m tapps_agents.cli planner plan "Feature description"`
+2. **Enhance prompt:** `python -m tapps_agents.cli enhancer enhance "Feature description"`
+3. **Implement:** `python -m tapps_agents.cli workflow rapid`
+4. **Review:** `python -m tapps_agents.cli reviewer review <new-file>`
+
+### Fixing a Bug
+1. **Debug:** `python -m tapps_agents.cli debugger debug "error message" --file <file>`
+2. **Fix:** `python -m tapps_agents.cli workflow hotfix`
+3. **Test:** `python -m tapps_agents.cli tester test <file>`
+
+### Refactoring Code
+1. **Analyze:** `python -m tapps_agents.cli reviewer score <file>`
+2. **Refactor:** `python -m tapps_agents.cli workflow fix`
+3. **Verify:** `python -m tapps_agents.cli reviewer review <file>`
+
+### Quality Improvement Sprint
+1. **Initial analysis:** `python -m tapps_agents.cli reviewer report . json markdown html`
+2. **Improve:** `python -m tapps_agents.cli workflow quality`
+3. **Validate:** `python -m tapps_agents.cli reviewer report . json markdown html`
+
+## Configuration Quick Fixes
+
+### Model Configuration
+Edit `.tapps-agents/config.yaml`:
+```yaml
+# MAL configuration removed - framework now uses Cursor Skills exclusively
+# All LLM operations are handled by Cursor via Skills
+```
+
+### Quality Thresholds
+```yaml
+agents:
+  reviewer:
+    quality_threshold: 70  # Minimum overall score
+    security_threshold: 7.0
+    maintainability_threshold: 7.0
+```
+
+### Tool Configuration
+```yaml
+external_tools:
+  mode: "soft"  # soft, strict, or disabled
+  ruff_enabled: true
+  mypy_enabled: true
+  pytest_enabled: true
+```
+
+## Troubleshooting
+
+### Tools Not Found on PATH
+**Issue:** Doctor shows tools missing on PATH
+**Solution:** Use Python module syntax:
+- `python -m ruff` instead of `ruff`
+- `python -m mypy` instead of `mypy`
+- `python -m pytest` instead of `pytest`
+
+The framework handles this automatically, but you can also add Scripts directory to PATH.
+
+### Python Version Warning
+**Issue:** Doctor warns about Python version
+**Solution:** If you're on Python 3.13+, you're fine. The warning is informational. The project requires `>=3.13`.
+
+### Playwright Warning
+**Issue:** "Playwright not available" message
+**Solution:** This refers to the **Python Playwright package** not being installed.
+
+**Playwright Options:**
+- **Playwright MCP Server** (recommended in Cursor): Browser automation via Cursor's MCP tools
+  - Check status: `tapps-agents doctor`
+  - Configure in `.cursor/mcp.json`:
+    ```json
+    {
+      "mcpServers": {
+        "Playwright": {
+          "command": "npx",
+          "args": ["-y", "@playwright/mcp-server"]
+        }
+      }
+    }
+    ```
+- **Python Playwright Package** (for CLI): Install if you need browser automation from CLI:
+  ```bash
+  python -m pip install playwright
+  python -m playwright install
+  ```
+
+**Note:** If you're using **Cursor with Playwright MCP configured**, you can ignore the warning (browser automation is available through Cursor tools).
+
+### Model Not Available
+**Issue:** Agent operations not executing
+**Solution:** 
+- Ensure Cursor Skills are properly installed and configured
+- Verify agents are creating instruction objects correctly
+- Check Cursor integration settings
+
+## Quick Examples
+
+### Example 1: Review a File
+```bash
+python -m tapps_agents.cli reviewer score tapps_agents/cli.py
+```
+
+### Example 2: Generate Code
+```bash
+python -m tapps_agents.cli implementer implement "Create a function to calculate fibonacci numbers" fibonacci.py
+```
+
+### Example 3: Run Quality Workflow
+```bash
+python -m tapps_agents.cli workflow quality
+```
+
+### Example 4: Generate Tests
+```bash
+python -m tapps_agents.cli tester test tapps_agents/core/config.py
+```
+
+### Example 5: Full Project Analysis
+```bash
+python -m tapps_agents.cli reviewer report . json markdown html
+```
+
+### Example 6: Evaluate Framework Effectiveness
+```bash
+# Evaluate overall framework effectiveness
+@evaluator *evaluate
+
+# Evaluate specific workflow execution
+@evaluator *evaluate-workflow workflow-123
+```
+
+## Simple Mode (New Users)
+
+**Simple Mode** provides a simplified, task-first interface that hides complexity while showcasing the power of TappsCodingAgents. Use natural language commands instead of agent-specific syntax.
+
+### Using Simple Mode
+
+Invoke Simple Mode using the `@simple-mode` skill in Cursor chat:
+
+```
+@simple-mode Build a user authentication feature
+@simple-mode Review my authentication code
+@simple-mode Fix the error in auth.py
+@simple-mode Add tests for service.py
+```
+
+### Natural Language Commands
+
+Simple Mode understands natural language intent:
+
+- **Build**: "Build a user authentication feature", "Create a REST API for products"
+- **Review**: "Review my authentication code", "Check the quality of auth.py"
+- **Fix**: "Fix the error in auth.py", "Debug the login issue"
+- **Test**: "Add tests for service.py", "Generate tests for auth.py"
+
+### Full Lifecycle Workflow
+
+Run complete SDLC with automatic quality loopbacks:
+
+```
+@simple-mode full --prompt "Build a REST API for a todo app"
+```
+
+### Configuration
+
+Enable Simple Mode:
+```bash
+tapps-agents simple-mode on
+tapps-agents simple-mode status
+```
+
+See `.cursor/rules/simple-mode.mdc` for complete Simple Mode documentation.
+
+## Natural Language Commands for Cursor
+
+You can use these phrases in Cursor AI conversations:
+
+- "Create a [project description]" → Uses `create` command (full SDLC)
+- "Run rapid development workflow"
+- "Set up experts"
+- "Score this file" (when file is open)
+- "Review the code quality"
+- "Generate tests for this file"
+- "Refactor this code"
+- "Run quality improvement workflow"
+- "Check for linting errors"
+- "Type check this file"
+- "Create a plan for [feature]"
+- "Debug this error"
+- "Evaluate framework effectiveness"
+- "How well is TappsCodingAgents working?"
+
+**Or use Simple Mode** (recommended for new users): `@simple-mode Build a feature`
+
+## File Locations
+
+- **Config:** `.tapps-agents/config.yaml`
+- **Project Profile:** `.tapps-agents/project-profile.yaml` (auto-generated)
+- **Workflow State:** `.tapps-agents/workflow-state/` (runtime state)
+- **Workflows:** `workflows/presets/`
+- **Reports:** `reports/quality/` or `.tapps-agents/reports/`
+- **Sessions:** `.tapps-agents/sessions/` (Enhancer sessions)
+- **Cache:** `.tapps-agents/kb/context7-cache/` (Context7 cache)
+- **Cursor Skills:** `.claude/skills/` (15 agent skills including simple-mode)
+
+## Context7 MCP Best Practices
+
+**Context7** provides library documentation lookup via MCP (Model Context Protocol). These rules help you use Context7 effectively in Cursor.
+
+### Automatic Context7 Usage
+
+This rule file automatically instructs Cursor to use Context7 MCP when you need library/API documentation, code generation, setup or configuration steps - you don't need to explicitly ask.
+
+**Example:**
+```
+User: "How do I use FastAPI routing?"
+AI: [Automatically uses Context7] @reviewer *docs fastapi routing
+```
+
+### Use Library ID for Faster Lookups
+
+If you already know the exact library you want, use the Context7 library ID syntax to skip library matching:
+
+**Syntax:** `use library /library/id`
+
+**Example:**
+```
+User: "Implement basic authentication with Supabase. use library /supabase/supabase for API and docs."
+AI: [Directly loads Supabase docs without matching step]
+```
+
+The slash syntax (`/library/id`) tells Context7 exactly which library to load, making lookups faster and more precise.
+
+### Specify Version for Version-Specific Docs
+
+Mention the version in your prompt to get documentation for a specific library version:
+
+**Example:**
+```
+User: "How do I set up Next.js 14 middleware? use context7"
+AI: [Automatically matches Next.js 14 version and retrieves appropriate docs]
+```
+
+**Best Practices:**
+- ✅ Always use Context7 for library documentation questions
+- ✅ Use library ID syntax (`/library/id`) when you know the exact library
+- ✅ Mention version numbers when you need version-specific documentation
+- ✅ Use `@reviewer *docs <library>` or `@implementer *docs <library>` commands explicitly when needed
+
+**Reference:** See [Context7 Best Practices](https://context7.com/docs/tips) for more information.
+
+## Getting Help
+
+```bash
+# General help
+python -m tapps_agents.cli --help
+
+# Agent-specific help
+python -m tapps_agents.cli reviewer help
+python -m tapps_agents.cli implementer help
+python -m tapps_agents.cli planner help
+```
+
+## Expert Setup (Cursor/CI-friendly)
+
+```bash
+python -m tapps_agents.cli setup-experts init --yes --non-interactive
+```
+
+## Version Check
+
+```bash
+python -c "import tapps_agents; print(tapps_agents.__version__)"
+```
+
+- Security Agent
+- Multi-Service Analyzer
+
+
+### Cursor Native Execution Mode
+
+When running in Cursor IDE, workflows automatically use **Cursor Native Execution**:
+- ✅ **No API Key Required** (file-based mode by default)
+- ✅ Uses Cursor Skills (`@agent-name` commands)
+- ✅ Leverages Cursor's configured LLM
+- ✅ Project profiling automatically included
+- ✅ Worktree isolation per workflow step
+
+**Execution Modes:**
+1. **File-Based** (default): Creates command files, works immediately
+2. **API-Based** (optional): Programmatic execution with `CURSOR_API_KEY` set
+
+**Project Profiling:**
+- Automatically detects project characteristics (deployment type, tenancy, scale, compliance)
+- Profile stored in `.tapps-agents/project-profile.yaml`
+- Automatically included in all agent context

tapps_agents/resources/cursor/rules/security.mdc

@@ -0,0 +1,32 @@
+---
+description: Mandatory security checks - no hardcoded secrets, input validation, OWASP-style reminders
+alwaysApply: true
+---
+
+# Security Rules
+
+Always-follow security guidelines for code and configuration.
+
+## No Hardcoded Secrets
+
+- Never commit API keys, passwords, tokens, or credentials to source
+- Use environment variables, secret managers, or project config (e.g. `.tapps-agents/config.yaml` with env overrides)
+- Sanitize logs and error messages to avoid leaking secrets
+
+## Input Validation
+
+- Validate and sanitize all user input and external data
+- Use allowlists over blocklists where possible
+- Apply length limits and type checks before processing
+
+## OWASP and Common Vulnerabilities
+
+- **Injection**: parameterize queries; avoid string concatenation for SQL/shell/commands
+- **XSS**: escape output in web UIs; use CSP where applicable
+- **Broken auth**: use proven auth libraries; secure session and token handling
+
+## References
+
+- `tapps_agents/experts/knowledge/security/` - owasp-top10, secure-coding-practices, threat-modeling, vulnerability-patterns
+- `tapps_agents/experts/knowledge/data-privacy-compliance/` - gdpr, hipaa, encryption-privacy
+- Use `@reviewer *security-scan` and `@ops *audit-security` for structured checks