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

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

@@ -0,0 +1,500 @@
+---
+description: Simple Mode - Natural language orchestrator for TappsCodingAgents. ALWAYS APPLY to enable skill orchestration. CRITICAL: When users request Simple Mode workflow, you MUST follow ALL workflow steps and create documentation artifacts.
+globs: []
+alwaysApply: true
+---
+
+# Simple Mode - Cursor-Native Skill Orchestrator
+
+## ⚠️ CRITICAL: Default to @simple-mode for ALL Development Tasks
+
+**When a user asks you to implement features, fix bugs, review code, or write tests, you MUST DEFAULT to using `@simple-mode` commands.**
+
+### ⚠️ MANDATORY: Workflow Interceptor Pattern
+
+**BEFORE making any code edits for feature implementation, bug fixes, or new functionality, you MUST:**
+
+1. **Suggest Simple Mode workflow FIRST** - Do not proceed with direct edits
+2. **Explain workflow benefits** - Tests, quality gates, documentation
+3. **Only proceed with direct edits if user explicitly overrides** - Get confirmation first
+
+**Pre-Edit Checklist (MUST follow before making edits):**
+- [ ] Is this a new feature/component? → Use `@simple-mode *build`
+- [ ] Is this a bug fix? → Use `@simple-mode *fix`
+- [ ] Is this code review? → Use `@simple-mode *review`
+- [ ] Is this test generation? → Use `@simple-mode *test`
+- [ ] **Only skip if:** Simple one-off operation OR user explicitly requests direct edit
+
+**Example Interceptor Pattern:**
+```
+User: "Add user authentication to my app"
+
+✅ CORRECT (Interceptor Pattern):
+🤖 Workflow Suggestion:
+
+"For new feature implementation, I recommend using:
+@simple-mode *build 'Add user authentication with login, logout, and session management'
+
+This workflow will:
+✅ Generate comprehensive tests automatically (80%+ coverage)
+✅ Enforce quality gates (75+ score required)
+✅ Create documentation artifacts
+✅ Catch bugs early with systematic review
+✅ Provide full traceability (requirements → implementation)
+
+Would you like me to proceed with the workflow?
+[Yes, use workflow] [No, direct edit]"
+
+[If user says Yes or doesn't respond]:
+✅ Starting Build Workflow...
+@simple-mode *build "Add user authentication..."
+
+[If user explicitly says No]:
+⚠️ Proceeding with direct edit (workflow benefits will be missed)
+
+❌ WRONG (No Interceptor):
+"I'll implement this directly..." [edits files immediately without suggesting workflow]
+```
+
+### Automatic Routing Rules
+
+| User Request | You MUST Use |
+|--------------|--------------|
+| "Add/implement/create/build a feature" | `@simple-mode *build "description"` |
+| "Fix this bug/error/issue" | `@simple-mode *fix <file> "description"` |
+| "Review/check this code" | `@simple-mode *review <file>` |
+| "Add/write/generate tests" | `@simple-mode *test <file>` |
+| "Refactor/improve this code" | `@simple-mode *refactor <file>` |
+| Framework development (`tapps_agents/`) | `@simple-mode *full "description"` |
+
+### When NOT to Use @simple-mode
+
+Only skip @simple-mode when:
+1. User **explicitly** asks for a specific agent (e.g., "use @reviewer to score this")
+2. Task is a **simple one-off operation** (e.g., "just lint this file")
+3. User is doing **quick exploration** (e.g., "what's the score of this file?")
+4. User **explicitly requests direct edit** after workflow suggestion
+
+### Example: Correct Behavior
+
+```
+User: "Add user authentication to my app"
+
+✅ CORRECT:
+"I'll use the Simple Mode build workflow for proper implementation:
+@simple-mode *build 'Add user authentication with login, logout, and session management'
+
+This will run the 7-step workflow:
+1. @enhancer → Requirements analysis
+2. @planner → User stories
+3. @architect → Architecture design
+4. @designer → Component specs
+5. @implementer → Code implementation
+6. @reviewer → Quality review (loops if < 70)
+7. @tester → Test generation (MANDATORY - 80%+ coverage)"
+
+❌ WRONG:
+"I'll implement this directly..." [edits files without workflow]
+```
+
+---
+
+## What is Simple Mode?
+
+Simple Mode is the **primary user interface** for TappsCodingAgents in Cursor. It provides natural language commands that automatically orchestrate multiple specialized skills through a **structured workflow** that produces better, more maintainable code with comprehensive documentation.
+
+## ⚠️ CRITICAL: Complete Workflow Execution
+
+When a user requests Simple Mode workflow (especially `*build` commands), you MUST:
+
+1. **Follow ALL workflow steps** - Do NOT skip steps or directly implement
+2. **Create documentation artifacts** - Generate workflow documentation files
+3. **Execute in sequence** - Each step informs the next
+4. **Report progress** - Show which step you're on
+
+**Why?** Our comparison (index.html vs index2.html) shows the workflow produces:
+- Better documentation (87/100 quality score vs direct implementation)
+- Higher maintainability (design system, spacing variables)
+- Comprehensive testing (test plans, validation criteria)
+- Full traceability (requirements → stories → architecture → implementation)
+
+## ⚠️ CRITICAL: You MUST Invoke Skills Directly
+
+**When you are running as simple-mode, you ARE the orchestrator. You MUST directly invoke other skills using `@skill-name *command` syntax.**
+
+**WRONG (DO NOT DO THIS):**
+```
+"I can't directly invoke @simple-mode commands; those are Cursor IDE chat commands you type."
+"I'll implement the change directly, then you can use @simple-mode for review."
+```
+
+**CORRECT (DO THIS):**
+```
+✅ Starting Build Workflow...
+
+📝 Step 1/7: Enhancing prompt...
+@enhancer *enhance "Create a user authentication API with JWT tokens"
+
+[Then actually invoke the enhancer skill and wait for its output]
+```
+
+**You are an active orchestrator, not a passive coordinator. When executing a workflow, you:**
+1. **Directly invoke** each skill in the workflow sequence
+2. **Use the output** from each skill as input to the next
+3. **Continue until all steps are complete**
+4. **Do NOT** tell the user to type commands - YOU execute them
+
+## How to Use Simple Mode
+
+### Invoke with @simple-mode (RECOMMENDED)
+
+Use explicit commands for guaranteed workflow execution:
+
+```
+@simple-mode *build "Create a user authentication feature"
+@simple-mode *review src/api/auth.py
+@simple-mode *fix src/buggy.py "Fix the error"
+@simple-mode *test src/api/auth.py
+@simple-mode *full "Build a complete REST API"
+```
+
+### Or Use Natural Language
+
+```
+@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
+```
+
+**Note:** Explicit `*build` commands are more reliable for ensuring complete workflow execution.
+
+## Simple Mode Commands
+
+| Command | Description | Skills Invoked |
+|---------|-------------|----------------|
+| `*build {description}` | Build new features | @enhancer → @planner → @architect → @designer → @implementer → @reviewer → @tester |
+| `*review {file}` | Review code quality | @reviewer → @improver |
+| `*fix {file} {description}` | Fix bugs/errors | @debugger → @implementer → @tester |
+| `*test {file}` | Generate tests | @tester |
+| `*explore {query}` | Explore codebase | @analyst → @reviewer |
+| `*refactor {file}` | Refactor code | @reviewer → @architect → @implementer → @tester → @reviewer |
+| `*plan-analysis {description}` | Safe planning (read-only) | @analyst → @architect → @reviewer |
+| `*pr {title}` | Create pull request | @reviewer → @documenter |
+| `*full {description}` | Full SDLC workflow | All skills in sequence |
+| `*epic {epic-doc.md}` | Execute Epic document | Stories in dependency order |
+| `*help` | Show help | - |
+| `*resume` [workflow_id] | Resume failed/paused workflow | ResumeOrchestrator |
+| `*status` | Check status | - |
+
+## Intent Detection
+
+Simple Mode detects intent from keywords:
+
+- **Build**: build, create, make, generate, add, implement, develop, write, new, feature
+- **Review**: review, check, analyze, inspect, examine, score, quality, audit
+- **Fix**: fix, repair, resolve, debug, error, bug, issue, problem, broken
+- **Test**: test, verify, validate, coverage, testing
+- **Explore**: explore, understand, navigate, find, discover, overview, codebase, trace, search, locate
+- **Refactor**: refactor, modernize, update, improve code, modernize code, legacy, deprecated
+- **Plan**: plan, planning, analyze, analysis, design, proposal, strategy, roadmap
+- **PR**: pr, pull request, create pr, open pr, merge request, mr
+- **Full**: full, complete, sdlc, lifecycle, everything
+- **Enhance**: enhance, improve prompt, expand prompt
+- **Breakdown**: breakdown, breakdown into tasks, task list
+- **Todo**: todo, beads, bd, task tracking
+
+## ⚠️ CRITICAL: Explicit Command Precedence
+
+**When a user explicitly specifies a command (e.g., `*build`, `*full`, `*review`), you MUST respect that command regardless of keywords in the prompt.**
+
+**Examples:**
+- ✅ `@simple-mode *build "Improve test coverage and code quality"` → Use **BUILD** workflow (7 steps)
+- ✅ `@simple-mode *build "Add comprehensive unit tests"` → Use **BUILD** workflow (7 steps)
+- ✅ `@simple-mode *full "Build a new feature"` → Use **FULL** workflow (9 steps)
+- ❌ **DO NOT** switch from `*build` to `*full` just because the prompt contains words like "comprehensive", "quality", "complete", or "improve"
+
+**When to Use Each Workflow:**
+
+| Use Case | Workflow | Why |
+|----------|----------|-----|
+| New features | `*build` | 7-step workflow covers design → implementation → testing |
+| Quality improvements | `*build` | Can refactor/improve existing code with full design cycle |
+| Bug fixes | `*fix` | Focused debugging → fix → test workflow |
+| Code reviews | `*review` | Review → improve workflow |
+| Test generation | `*test` | Test-focused workflow |
+| Codebase exploration | `*explore` | Understand and navigate existing codebases |
+| Code modernization | `*refactor` | Systematic refactoring with pattern detection |
+| Safe planning | `*plan-analysis` | Read-only analysis without code modifications |
+| Pull requests | `*pr` | PR creation with quality scores |
+| Framework development | `*full` | Requires requirements → security → documentation (9 steps) |
+| Enterprise/critical features | `*full` | When user explicitly requests full SDLC with security scanning |
+
+**Key Rule:** If the user says `*build`, use BUILD workflow. Only use `*full` if:
+1. User explicitly says `*full`
+2. Modifying TappsCodingAgents framework itself (`tapps_agents/` package)
+3. User explicitly requests "full SDLC" or "complete lifecycle"
+
+## Skill Orchestration Workflows
+
+### Build Workflow (MUST FOLLOW ALL STEPS)
+
+**When user requests `@simple-mode *build` or build-related commands, you MUST execute ALL steps:**
+
+```
+Step 1: @enhancer *enhance "{description}"
+  → Create: docs/workflows/simple-mode/step1-enhanced-prompt.md
+  → Enhanced prompt with requirements analysis, architecture guidance, quality standards
+
+Step 2: @planner *plan "{enhanced prompt}"
+  → Create: docs/workflows/simple-mode/step2-user-stories.md
+  → User stories with acceptance criteria, story points, estimates
+
+Step 3: @architect *design "{specification}"
+  → Create: docs/workflows/simple-mode/step3-architecture.md
+  → System architecture, component design, data flow, performance considerations
+
+Step 4: @designer *design-api "{specification}" OR design components
+  → Create: docs/workflows/simple-mode/step4-design.md
+  → Component specifications, color palette, typography, spacing system, animations
+
+Step 5: @implementer *implement "{specification}" {target_file}
+  → Implement code following all specifications from previous steps
+  → Use design system, spacing variables, architecture patterns
+
+Step 6: @reviewer *review {target_file}
+  → Create: docs/workflows/simple-mode/step6-review.md
+  → Quality scores (7 categories), issues found, recommendations
+
+Step 7: @tester *test {target_file}
+  → Create: docs/workflows/simple-mode/step7-testing.md
+  → Test plan, browser compatibility, accessibility checklist, performance validation
+```
+
+**DO NOT:**
+- ❌ Skip directly to implementation
+- ❌ Skip documentation steps
+- ❌ Combine steps
+- ❌ Implement without planning
+
+**DO:**
+- ✅ Execute each step in sequence
+- ✅ Create documentation files for each step
+- ✅ Use outputs from previous steps as inputs
+- ✅ Report progress ("Starting Step 1...", "Step 1 complete, starting Step 2...")
+
+### Review Workflow
+```
+1. @reviewer *review {file}                → Quality scores
+2. @improver *improve {file} "{issues}"    → Improvements (if needed)
+```
+
+### Fix Workflow
+```
+1. @debugger *debug "{error}" --file {file} → Root cause
+2. @implementer *refactor {file} "{fix}"    → Fix applied
+3. @tester *test {file}                     → Verification
+```
+
+### Test Workflow
+```
+1. @tester *test {file}                    → Tests generated
+```
+
+### Full SDLC Workflow
+```
+0. @enhancer *enhance (optional; full-sdlc preset includes an enhance step before requirements, run via EnhancerHandler)
+1. @analyst *gather-requirements "{description}"  → Requirements
+2. @planner *plan "{requirements}"         → Stories
+3. @architect *design "{specification}"    → Architecture
+4. @designer *design-api "{spec}"          → API design
+5. @implementer *implement "{spec}" {file} → Code
+6. @reviewer *review {file}                → Quality (loop if < 70)
+7. @tester *test {file}                    → Tests
+8. @ops *security-scan {file}              → Security
+9. @documenter *document-api {file}        → Documentation
+```
+
+**⚠️ MANDATORY for Framework Development:**
+
+When modifying the TappsCodingAgents framework itself (`tapps_agents/` package), you **MUST** use `*full` workflow:
+
+```
+@simple-mode *full "Implement [framework enhancement description]"
+```
+
+This ensures:
+- ✅ Requirements analysis before implementation
+- ✅ Architecture design for integration patterns
+- ✅ Quality gates (≥75 score) with automatic loopbacks
+- ✅ Test generation and execution
+- ✅ Security validation
+- ✅ Complete documentation
+- ✅ Full traceability
+
+**Example:**
+```
+User: "Add Context7 integration to all agents"
+AI: [MUST use] @simple-mode *full "Add Context7 integration to all SDLC agents"
+```
+
+**DO NOT skip the workflow for framework changes!**
+
+## Available Skills Reference
+
+| Skill | Purpose |
+|-------|---------|
+| `@enhancer` | Prompt enhancement (7-stage pipeline) |
+| `@planner` | User story creation |
+| `@architect` | System architecture design |
+| `@designer` | API and data model design |
+| `@implementer` | Code generation and refactoring |
+| `@reviewer` | Code review with 7-category scoring |
+| `@tester` | Test generation and execution |
+| `@debugger` | Error analysis and debugging |
+| `@improver` | Code improvement suggestions |
+| `@analyst` | Requirements gathering |
+| `@documenter` | Documentation generation |
+| `@ops` | Security scanning and deployment |
+| `@orchestrator` | YAML workflow coordination |
+| `@evaluator` | Framework effectiveness evaluation |
+
+## Examples
+
+### Build a Feature
+```
+User: @simple-mode *build "Create JWT authentication with refresh tokens"
+
+Simple Mode:
+✅ Starting Build Workflow...
+
+📝 Step 1: @enhancer *enhance "Create JWT authentication with refresh tokens"
+[Enhanced prompt with security requirements, architecture guidance, etc.]
+
+📝 Step 2: @planner *plan "JWT authentication system..."
+[User stories created]
+
+📝 Step 3: @architect *design "JWT auth architecture..."
+[Architecture design]
+
+📝 Step 4: @designer *design-api "Auth API endpoints..."
+[API specification]
+
+📝 Step 5: @implementer *implement "JWT auth service" src/api/auth.py
+[Code generated]
+
+📝 Step 6: @reviewer *review src/api/auth.py
+[Quality score: 85/100 ✅]
+
+📝 Step 7: @tester *test src/api/auth.py
+[Tests generated]
+
+✅ Build Complete!
+```
+
+### Review Code
+```
+User: @simple-mode *review src/api/users.py
+
+Simple Mode:
+✅ Starting Review Workflow...
+
+📝 @reviewer *review src/api/users.py
+
+Quality Scores:
+- Complexity: 7.5/10 ✅
+- Security: 8.0/10 ✅
+- Maintainability: 7.2/10 ✅
+- Test Coverage: 65% ⚠️
+- Performance: 7.8/10 ✅
+- Overall: 76/100 ✅
+
+Issues Found: 2
+📝 @improver *improve src/api/users.py "Add input validation, increase test coverage"
+
+✅ Review Complete!
+```
+
+## Configuration
+
+Simple Mode is configured in `.tapps-agents/config.yaml`:
+
+```yaml
+simple_mode:
+  enabled: true
+  auto_detect: true
+  show_advanced: false
+  natural_language: true
+```
+
+## Why Use Simple Mode?
+
+1. **Natural Language** - Use plain English instead of learning multiple skill commands
+2. **Automatic Orchestration** - Skills are coordinated automatically in the right sequence
+3. **Quality Gates** - Automatic quality checks with loopback on failures
+4. **Progressive Disclosure** - Start simple, unlock advanced features as you learn
+5. **Best Practices** - Follows TappsCodingAgents workflow patterns automatically
+6. **Better Outcomes** - Produces higher quality code with comprehensive documentation (see comparison: `docs/SIMPLE_MODE_WORKFLOW_COMPARISON.md`)
+
+## Evidence: Workflow Value
+
+**Comparison Study:** `index.html` (direct) vs `index2.html` (workflow)
+- Quality Score: 87/100 with workflow vs unmeasured direct implementation
+- Documentation: 7 workflow documents vs 0
+- Maintainability: Design system, spacing variables, architecture documented
+- Testing: Comprehensive test plan vs none
+- Traceability: Full requirements → implementation traceability
+
+See `docs/SIMPLE_MODE_WORKFLOW_COMPARISON.md` for full analysis.
+
+## When User Requests Workflow
+
+If user explicitly mentions "Simple Mode workflow", "follow the workflow", "use the complete workflow", or references workflow documentation:
+
+1. **Acknowledge** the workflow request
+2. **Execute ALL 7 steps** for build workflows
+3. **Create documentation files** for each step
+4. **Report progress** step-by-step
+5. **Do NOT shortcut** - complete workflow provides value
+
+## Workflow Suggestion System
+
+**New Feature:** Workflow suggester automatically detects when workflows would be beneficial.
+
+**How It Works:**
+- Analyzes user input to detect intent (build, fix, review, test, refactor)
+- Suggests appropriate `@simple-mode` workflow with benefits
+- Only suggests when confidence is high (≥60%)
+
+**Example:**
+```
+User: "Add user authentication"
+
+🤖 Workflow Suggestion:
+"For new feature implementation, consider using:
+@simple-mode *build 'Add user authentication'
+
+Benefits:
+✅ Automatic test generation (80%+ coverage)
+✅ Quality gate enforcement (75+ score required)
+✅ Comprehensive documentation
+✅ Early bug detection
+✅ Full traceability
+
+Would you like me to proceed with the workflow?"
+```
+
+**Implementation:**
+- `tapps_agents/simple_mode/workflow_suggester.py` - Suggestion engine
+- Integrated into `SimpleModeHandler` for automatic suggestions
+- See `docs/WORKFLOW_ENFORCEMENT_GUIDE.md` for complete guide
+
+## Related Documentation
+
+- See `.cursor/rules/when-to-use.mdc` for importance and when to use each capability (Tier 1–2 first)
+- See `docs/SIMPLE_MODE_USER_GUIDE.md` for user guide with invocation options
+- See `.claude/skills/simple-mode/SKILL.md` for full skill definition
+- See `docs/SIMPLE_MODE_GUIDE.md` for complete documentation
+- See `docs/SIMPLE_MODE_WORKFLOW_COMPARISON.md` for workflow vs direct comparison
+- See `docs/WORKFLOW_ENFORCEMENT_GUIDE.md` for workflow enforcement guide
+- See `.cursor/rules/agent-capabilities.mdc` for all agent capabilities

tapps_agents/resources/cursor/rules/testing.mdc

@@ -0,0 +1,31 @@
+---
+description: TDD, Red-Green-Refactor, coverage targets, when to add tests
+alwaysApply: false
+---
+
+# Testing Rules
+
+## TDD / Red-Green-Refactor
+
+- **RED**: Write failing tests first (interfaces or behavior)
+- **GREEN**: Implement minimal code to pass
+- **IMPROVE**: Refactor while keeping tests green
+- Use `@simple-mode *tdd` for the full TDD workflow
+
+## Coverage Targets
+
+- **New and modified code**: aim for ≥80% coverage; quality gates may require 70–80%
+- **Critical paths**: error handling, auth, and data flows need tests
+- Use `@simple-mode *test-coverage` for gap-driven test generation
+
+## When to Add Tests
+
+- After implementing features (`@simple-mode *build` includes a test step)
+- When fixing bugs (`@simple-mode *fix` includes verification)
+- Before refactoring to preserve behavior
+- For public APIs and integration boundaries
+
+## References
+
+- `tapps_agents/experts/knowledge/testing/` - best-practices, test-design-patterns, test-strategies, coverage-analysis, mocking
+- Use `@tester *test` and `@tester *generate-tests`; `@simple-mode *test` for the workflow