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

tapps_agents/resources/cursor/rules/cursor-mode-usage.mdc

@@ -0,0 +1,125 @@
+---
+description: Critical guidance on using CLI commands vs Cursor Skills in Cursor IDE. Prevents common mistakes when running tapps-agents commands.
+globs: []
+alwaysApply: true
+---
+
+# Cursor Mode Usage Guide - CLI vs Cursor Skills
+
+## ⚠️ CRITICAL: CLI Workflow Commands Not Recommended in Cursor Mode
+
+**If you see this warning:**
+```
+⚠️  CLI Workflow Commands Not Recommended in Cursor Mode
+```
+
+**This means:** You're trying to run a CLI workflow command (`tapps-agents workflow ...`) inside Cursor IDE, which is not recommended.
+
+## Quick Fix
+
+### ✅ Use Cursor Skills Instead (Recommended)
+
+**In Cursor IDE chat, use:**
+```cursor
+@simple-mode *fix <file> "description"
+@simple-mode *build "description"
+@simple-mode *review <file>
+@simple-mode *test <file>
+```
+
+**NOT:**
+```bash
+# ❌ Don't use CLI workflow commands in Cursor IDE
+tapps-agents workflow fix --file <file> --auto
+```
+
+### ✅ Use CLI Commands in Terminal/CI (Outside Cursor)
+
+**CLI commands work perfectly in:**
+- ✅ Standalone terminal (outside Cursor IDE)
+- ✅ CI/CD pipelines
+- ✅ Shell scripts
+- ✅ Automated workflows
+
+```bash
+# ✅ This works in terminal/CI
+tapps-agents workflow fix --file <file> --auto
+tapps-agents workflow rapid --prompt "description" --auto
+```
+
+## Why This Matters
+
+### Cursor Mode vs CLI Mode
+
+**Cursor Mode** (when running in Cursor IDE):
+- Uses Cursor Skills (`@agent-name *command`)
+- Leverages Cursor's native integration
+- Better context awareness
+- Skill-based execution
+- **Recommended for interactive development**
+
+**CLI Mode** (when running in terminal/CI):
+- Uses direct CLI commands (`tapps-agents <agent> <command>`)
+- Designed for automation and scripting
+- Structured output (JSON, text)
+- **Recommended for batch processing and CI/CD**
+
+### The Problem
+
+When you run CLI workflow commands in Cursor IDE:
+- ❌ May fail due to dependency issues
+- ❌ Bypasses Cursor's skill orchestration
+- ❌ Doesn't leverage workspace context
+- ❌ Poorer integration experience
+
+## Command Mapping
+
+| What You Want | In Cursor IDE | In Terminal/CI |
+|--------------|---------------|----------------|
+| Fix a bug | `@simple-mode *fix <file> "desc"` | `tapps-agents workflow fix --file <file> --auto` |
+| Build feature | `@simple-mode *build "desc"` | `tapps-agents workflow rapid --prompt "desc" --auto` |
+| Review code | `@simple-mode *review <file>` | `tapps-agents reviewer review <file>` |
+| Generate tests | `@simple-mode *test <file>` | `tapps-agents tester test <file>` |
+| Full SDLC | `@simple-mode *full "desc"` | `tapps-agents workflow full --prompt "desc" --auto` |
+
+## How to Verify Your Setup
+
+### Check if Simple Mode is Ready
+
+```bash
+tapps-agents simple-mode status
+tapps-agents cursor verify
+```
+
+### If Not Set Up, Run Init
+
+```bash
+tapps-agents init
+```
+
+This installs:
+- ✅ Cursor Rules (`.cursor/rules/`)
+- ✅ Cursor Skills (`.claude/skills/`) - **Required for `@simple-mode`**
+- ✅ Configuration (`.tapps-agents/config.yaml`)
+- ✅ Workflow presets
+
+## Override (Not Recommended)
+
+If you absolutely must use CLI commands in Cursor mode:
+
+```bash
+tapps-agents workflow fix --file <file> --auto --cli-mode
+```
+
+**Why this is not recommended:**
+- May fail due to dependency issues
+- Doesn't leverage Cursor's native capabilities
+- Poorer integration with workspace context
+- Better to use `@simple-mode` commands instead
+
+## Related Documentation
+
+- `.cursor/rules/simple-mode.mdc` - Simple Mode usage guide
+- `.cursor/rules/quick-reference.mdc` - Quick command reference
+- `.cursor/rules/command-reference.mdc` - Complete command reference
+- `docs/CURSOR_MODE_CLI_WORKFLOW_WARNING_ANALYSIS.md` - Detailed analysis

tapps_agents/resources/cursor/rules/git-workflow.mdc

@@ -0,0 +1,29 @@
+---
+description: Commit format, when to use *build/*fix branches, PR flow
+alwaysApply: false
+---
+
+# Git Workflow Rules
+
+## Commit Format
+
+- Use clear, imperative subject lines (e.g. "Add auth endpoint", "Fix null check in validator")
+- Optionally include scope: `feat(auth): add login endpoint`
+- Keep the body concise when needed; reference issues or PRs
+
+## Branching for Agent Workflows
+
+- **`*build` and `*full`**: when `human_oversight.branch_for_agent_changes` is true, work runs on `tapps-agents/build-{workflow_id}`; merge to main only after human review
+- **`*fix`**: typically on a short-lived branch or main, depending on project policy
+- Use `checkpoints_before_steps` (e.g. before implementer, designer) to review before large changes
+
+## PR Flow
+
+- Run `@simple-mode *review` on changed files before opening a PR
+- Use `@simple-mode *pr {title}` to generate PR description and quality summary
+- Ensure tests pass and quality gates meet thresholds (e.g. overall ≥70, security ≥6.5)
+
+## References
+
+- `tapps_agents/experts/knowledge/development-workflow/git-workflows.md`
+- `.cursor/rules/simple-mode.mdc` for workflow and human oversight options

tapps_agents/resources/cursor/rules/performance.mdc

@@ -0,0 +1,29 @@
+---
+description: Context and MCP usage - MCP/tool limits, when to delegate, model selection
+alwaysApply: false
+---
+
+# Performance and Context Rules
+
+## Context Window and MCP Usage
+
+- **MCPs**: Prefer ~20–30 MCPs configured total; enable **<10 per project** to avoid shrinking the effective context
+- **Tools**: Keep **<80 tools** active; disable unused MCPs via `disabledMcpServers` or project/local MCP config (e.g. `.cursor/mcp.json`)
+- Enable only MCPs needed for the current project (e.g. Context7 for docs; Playwright for E2E)
+
+## When to Delegate
+
+- Use `@simple-mode *build` for features; `*fix` for bugs; `*review` for quality—avoids ad-hoc context bloat
+- Prefer targeted agents (`@reviewer *score`, `@tester *test`) over loading many skills at once
+- For large codebases, narrow scope (file, module) before inviting broad search
+
+## Model and Resource Selection
+
+- Skills reference `model_profile` (e.g. `reviewer_profile`, `implementer_profile`); override in `requirements/model_profiles.yaml` or project config
+- Use higher-accuracy models for reviewer and security-review; lighter models for lint/score when acceptable
+- See `docs/MODEL_SELECTION.md` (or agent-capabilities) for profile resolution and overrides
+
+## References
+
+- `tapps_agents/core/doctor.py` - run `tapps-agents doctor` to check MCP and tool setup
+- `.cursor/mcp.json` and project MCP configuration for `disabledMcpServers` and enabled servers

tapps_agents/resources/cursor/rules/project-context.mdc

@@ -0,0 +1,163 @@
+# TappsCodingAgents Project Context
+
+## Important: Dual Nature of This Project
+
+**This project has TWO distinct roles:**
+
+### 1. Framework Development (Primary Role)
+**TappsCodingAgents is a framework** that provides:
+- 14 workflow agents (analyst, planner, architect, implementer, tester, reviewer, evaluator, etc.)
+- Industry Experts system
+- Cursor Skills integration (model-agnostic)
+- Code quality analysis tools
+- Workflow orchestration with CLI flags for control
+
+**When working on framework development:**
+- You're modifying the framework code itself (`tapps_agents/` package)
+- You're adding new agents, features, or capabilities
+- You're fixing bugs or improving the framework
+- Focus on: `tapps_agents/`, `tests/`, `requirements/`, `docs/`
+
+**⚠️ CRITICAL: Framework Changes MUST Use Full SDLC Workflow**
+
+When modifying the TappsCodingAgents framework itself, you **MUST** use Simple Mode Full SDLC workflow:
+
+```bash
+# CLI
+tapps-agents simple-mode full --prompt "Implement [enhancement description]" --auto
+
+# Or in Cursor chat
+@simple-mode *full "Implement [enhancement description]"
+```
+
+**Why?** The full SDLC workflow ensures:
+- ✅ Proper requirements analysis (analyst)
+- ✅ Architecture design (architect)
+- ✅ Quality gates with automatic loopbacks (reviewer)
+- ✅ Test generation and execution (tester)
+- ✅ Security validation (ops)
+- ✅ Complete documentation (documenter)
+- ✅ Full traceability (requirements → stories → architecture → implementation)
+
+**DO NOT:**
+- ❌ Directly implement code without using the workflow
+- ❌ Skip planning, design, or architecture phases
+- ❌ Validate only afterward (use quality gates during development)
+- ❌ Skip test generation (tests should be part of workflow)
+
+**Example:**
+```
+❌ WRONG: Directly implement Context7 enhancements
+✅ CORRECT: @simple-mode *full "Implement Context7 automatic integration enhancements"
+```
+
+### 2. Self-Hosting (Secondary Role)
+**TappsCodingAgents uses its own framework** for its own development:
+- Configuration: `.tapps-agents/` directory
+- 5 Industry Experts configured (AI frameworks, code quality, architecture, DevOps, documentation)
+- Enhancer Agent used for prompt enhancement
+- Context7 integration for library documentation
+
+**When working on self-hosted development:**
+- You're using the framework to develop the framework itself
+- You're using agents via CLI or Python API
+- You're configuring experts and knowledge bases
+- Focus on: `.tapps-agents/`, `workflows/`, project-specific tasks
+
+## Context Awareness
+
+**When AI assistants work in this project, they should:**
+
+1. **Understand the dual context:**
+   - Framework code (`tapps_agents/`) = developing the framework
+   - Project configuration (`.tapps-agents/`) = using the framework
+
+2. **Distinguish between:**
+   - **Framework users**: People who install and use TappsCodingAgents in their projects
+   - **Framework developers**: People working on TappsCodingAgents itself (us)
+
+3. **Documentation clarity:**
+   - User-facing docs should focus on "how to use the framework"
+   - Developer docs should focus on "how to develop the framework"
+   - Self-hosting docs should explain "how we use our own framework"
+
+## Current Self-Hosting Configuration
+
+**Version**: 2.0.0 (self-hosting)
+
+**Configured Experts:**
+- `expert-ai-frameworks` - AI agent orchestration, workflow management
+- `expert-code-quality` - Static analysis, code scoring, quality metrics
+- `expert-software-architecture` - System design patterns, architecture decisions
+- `expert-devops` - CI/CD integration, testing strategies, deployment
+- `expert-documentation` - Technical documentation, knowledge bases
+
+**Active Usage:**
+- Enhancer Agent: 23+ enhancement sessions in `.tapps-agents/sessions/`
+- Context7: KB cache in `.tapps-agents/kb/context7-cache/`
+- Workflows: `workflows/prompt-enhancement.yaml`
+
+## Guidelines for AI Assistants
+
+1. **When asked about "using TappsCodingAgents":**
+   - Explain how to use the framework in a user's project
+   - Reference user-facing documentation (QUICK_START.md, DEVELOPER_GUIDE.md)
+   - Show CLI and Python API examples
+
+2. **When asked about "developing TappsCodingAgents":**
+   - Explain how to modify the framework code
+   - Reference developer documentation (ARCHITECTURE.md, API.md)
+   - Show how to add agents, extend functionality
+
+3. **When asked about "this project's setup":**
+   - Explain the self-hosting configuration
+   - Reference `.tapps-agents/` configuration
+   - Show how the framework is used internally
+
+4. **Always clarify context:**
+   - If unclear, ask: "Are you asking about using the framework or developing it?"
+   - Provide examples for both contexts when relevant
+
+5. **When asked for feedback on tapps-agents effectiveness** (e.g. "provide feedback on how well tapps-agents helps you as an LLM"):
+   - **Include health metrics in the feedback report or document.** Run `tapps-agents health overview` (or `tapps-agents health usage dashboard`) and include the output or a summary.
+   - This ensures feedback is actionable and comparable (subsystem health, usage, top agents/workflows). See `docs/feedback/README.md` for placement.
+
+## File Organization
+
+```
+TappsCodingAgents/
+├── tapps_agents/          # Framework code (developing the framework)
+│   ├── agents/            # Agent implementations
+│   ├── core/              # Core framework components
+│   └── ...
+│
+├── .tapps-agents/         # Self-hosting configuration (using the framework)
+│   ├── experts.yaml       # Our project's experts
+│   ├── domains.md         # Our project's domains
+│   └── sessions/          # Enhancement sessions
+│
+├── docs/                  # User-facing documentation (how to use)
+├── requirements/          # Framework specifications (developing)
+└── docs/implementation/   # Implementation notes and EPIC/PHASE docs
+```
+
+## Examples
+
+### Example 1: User Question
+**Q: "How do I use the reviewer agent?"**
+**A:** Explain CLI usage, Python API, configuration - focus on user perspective
+
+### Example 2: Developer Question
+**Q: "How do I add a new agent?"**
+**A:** Explain framework architecture, BaseAgent class, agent registration - focus on development
+
+### Example 3: Self-Hosting Question
+**Q: "What experts are configured in this project?"**
+**A:** Explain `.tapps-agents/experts.yaml`, the 5 experts, how they're used internally
+
+## References
+
+- **Self-Hosting Setup**: `docs/implementation/SELF_HOSTING_SETUP_COMPLETE.md`
+- **User Guide**: `QUICK_START.md`, `docs/DEVELOPER_GUIDE.md`
+- **Framework Architecture**: `docs/ARCHITECTURE.md`
+- **Configuration**: `.tapps-agents/` directory

tapps_agents/resources/cursor/rules/project-profiling.mdc

@@ -0,0 +1,197 @@
+---
+description: Documentation of TappsCodingAgents automatic project profiling system for context-aware recommendations
+alwaysApply: false
+---
+
+# Project Profiling System
+
+## Overview
+
+TappsCodingAgents automatically detects and profiles project characteristics to provide context-aware recommendations and ensure compliance with project constraints. This profiling happens automatically during workflow execution and requires no manual configuration.
+
+## Automatic Detection
+
+The profiling system analyzes your codebase to detect:
+
+### Deployment Type
+- **Cloud**: AWS, Azure, GCP, or other cloud providers
+- **On-Premise**: Self-hosted infrastructure
+- **Hybrid**: Combination of cloud and on-premise
+- **Serverless**: Function-as-a-Service (Lambda, Cloud Functions, etc.)
+- **Container**: Docker, Kubernetes, or container orchestration
+
+### Tenancy Model
+- **Single-Tenant**: One customer per instance
+- **Multi-Tenant**: Multiple customers share resources
+- **Hybrid**: Mix of single and multi-tenant components
+
+### User Scale
+- **Small**: < 1,000 users
+- **Medium**: 1,000 - 100,000 users
+- **Large**: 100,000 - 1,000,000 users
+- **Enterprise**: > 1,000,000 users
+
+### Compliance Requirements
+- **HIPAA**: Healthcare data protection
+- **GDPR**: European data privacy
+- **PCI DSS**: Payment card industry
+- **SOC 2**: Security and availability
+- **ISO 27001**: Information security management
+- **None**: No specific compliance requirements
+
+### Security Level
+- **Low**: Basic security requirements
+- **Medium**: Standard security practices
+- **High**: Enhanced security controls
+- **Critical**: Maximum security requirements
+
+## Profile Storage
+
+**Location:** `.tapps-agents/project-profile.yaml`
+
+**Format:**
+```yaml
+deployment_type: cloud
+tenancy: multi-tenant
+user_scale: large
+compliance:
+  - GDPR
+  - SOC 2
+security_level: high
+detected_at: 2025-12-13T10:00:00Z
+```
+
+## How It Works
+
+### Detection Process
+
+1. **Codebase Analysis**: Scans project files for indicators
+   - Infrastructure as Code (Terraform, CloudFormation)
+   - Deployment configurations (Docker, Kubernetes)
+   - Database schemas and data models
+   - Security configurations
+   - Compliance documentation
+
+2. **Pattern Matching**: Identifies patterns that indicate:
+   - Deployment type (cloud provider configs, serverless functions)
+   - Tenancy model (tenant_id fields, isolation patterns)
+   - Scale indicators (caching, load balancing, scaling configs)
+   - Compliance (privacy policies, security docs, compliance mentions)
+   - Security level (encryption, authentication, authorization patterns)
+
+3. **Profile Generation**: Creates profile YAML file with detected characteristics
+
+4. **Context Injection**: Automatically includes profile in all agent commands
+
+### When Detection Happens
+
+- **First Workflow Run**: Profile is created during initial workflow execution
+- **Project Initialization**: Can be generated during `tapps-agents init` (optional)
+- **Manual Refresh**: Profile can be regenerated by deleting the file
+
+## Usage in Workflows
+
+### Automatic Inclusion
+
+Project profile is **automatically included** in all agent commands:
+
+- **Analyst**: Uses profile for requirements analysis and risk assessment
+- **Planner**: Ensures stories align with project constraints
+- **Architect**: Designs architecture matching deployment and tenancy model
+- **Designer**: Creates APIs and data models with compliance in mind
+- **Implementer**: Generates code following security and compliance requirements
+- **Ops**: Performs audits based on compliance and security level
+
+### Example Impact
+
+**Multi-Tenant Project:**
+- Architect designs tenant isolation patterns
+- Designer creates APIs with tenant context
+- Implementer adds tenant_id to all data models
+- Ops ensures tenant data isolation
+
+**GDPR-Compliant Project:**
+- Designer includes data privacy fields (consent, right to deletion)
+- Implementer adds data export and deletion endpoints
+- Ops verifies GDPR compliance in audit
+
+**High-Security Project:**
+- Architect designs defense-in-depth security
+- Implementer adds encryption, authentication, authorization
+- Reviewer checks for security vulnerabilities
+- Ops performs comprehensive security audit
+
+## Manual Override
+
+If automatic detection is incorrect, you can manually edit `.tapps-agents/project-profile.yaml`:
+
+```yaml
+deployment_type: cloud  # Override detected value
+tenancy: multi-tenant
+user_scale: large
+compliance:
+  - GDPR
+  - HIPAA  # Add additional compliance
+security_level: critical  # Increase security level
+```
+
+**Note:** Manual edits are preserved and not overwritten by automatic detection.
+
+## Best Practices
+
+1. **Review Profile**: Check `.tapps-agents/project-profile.yaml` after first workflow run
+2. **Update as Needed**: Manually update if project characteristics change
+3. **Share with Team**: Commit profile to version control for team consistency
+4. **Use in CI/CD**: Reference profile in CI/CD pipelines for compliance checks
+
+## Integration with Agents
+
+### Analyst Agent
+- Uses profile for requirements analysis
+- Considers compliance requirements in risk assessment
+- Adjusts effort estimates based on security level
+
+### Planner Agent
+- Creates stories aligned with project constraints
+- Prioritizes compliance-related stories
+- Estimates effort considering security requirements
+
+### Architect Agent
+- Designs architecture matching deployment type
+- Implements tenant isolation for multi-tenant projects
+- Includes security architecture for high-security projects
+
+### Designer Agent
+- Creates APIs with tenant context (multi-tenant)
+- Includes compliance fields (GDPR, HIPAA)
+- Designs data models with security in mind
+
+### Implementer Agent
+- Generates code following security best practices
+- Adds compliance-related functionality
+- Implements tenant isolation patterns
+
+### Ops Agent
+- Performs audits based on compliance requirements
+- Verifies security controls match security level
+- Checks deployment configuration matches deployment type
+
+## Troubleshooting
+
+### Profile Not Detected
+- **Issue**: Profile file doesn't exist
+- **Solution**: Run a workflow - profile is created automatically
+
+### Incorrect Detection
+- **Issue**: Profile shows wrong characteristics
+- **Solution**: Manually edit `.tapps-agents/project-profile.yaml`
+
+### Profile Not Used
+- **Issue**: Agents don't seem to use profile
+- **Solution**: Ensure profile file exists and is valid YAML
+
+## Related Documentation
+
+- [Quick Reference](quick-reference.mdc) - Command reference
+- [Agent Capabilities](agent-capabilities.mdc) - Agent documentation
+- [Cursor Native Integration](../../../CURSOR_NATIVE_INTEGRATION_DESIGN.md) - Integration details