tapps-agents 3.7.1

A specification framework for defining, configuring, and orchestrating coding agents

TappsCodingAgents

An AI coding agent framework with quality gates, workflow orchestration, and adaptive learning.

TappsCodingAgents orchestrates 14 specialized agents across the full software development lifecycle. Use natural language commands in Cursor IDE or the CLI to plan, implement, review, test, and ship code with built-in quality enforcement.

---

Why TappsCodingAgents?

• Quality by default - Every workflow includes code review, scoring, and configurable quality gates
• 14 specialized agents - Analyst, Planner, Architect, Designer, Implementer, Debugger, Tester, Reviewer, Improver, Documenter, Ops, Orchestrator, Enhancer, Evaluator
• Simple Mode - Natural language interface: @simple-mode Build a user auth module
• 16 built-in experts - Security, Performance, Testing, Architecture, DevOps, and more
• Adaptive learning - Auto-generates experts, adjusts scoring weights, and improves with each use
• Works where you code - Cursor IDE (Skills), Claude Desktop (Commands), Claude Code CLI

---

Quick Start

1. Install

pip install tapps-agents

Requires Python 3.12+. On Windows, if tapps-agents is not found after install, use python -m tapps_agents.cli or a project venv. See Troubleshooting.

2. Initialize in your project

cd /path/to/your-project
tapps-agents init

This sets up Cursor Skills, Rules, workflow presets, configuration, and MCP integration.

3. Verify

tapps-agents doctor

4. Use in Cursor IDE

@simple-mode Build a user authentication module
@simple-mode Review src/api/auth.py
@simple-mode Fix the error in auth.py
@simple-mode Add tests for service.py

Or use individual agents:

@reviewer *review src/api/auth.py
@implementer *implement "Add validation" src/api/auth.py
@tester *test src/api/auth.py

5. Or use the CLI

tapps-agents workflow full --prompt "Add user authentication"
tapps-agents workflow fix --prompt "Fix the login timeout bug"
tapps-agents score src/api/auth.py
tapps-agents reviewer review src/api/auth.py

---

How It Works

TappsCodingAgents uses an instruction-based architecture:

1. You describe the task in natural language (Cursor chat or CLI)
2. Simple Mode detects your intent and selects the right agents
3. Agents prepare structured instructions (plans, reviews, tests, code)
4. Cursor Skills execute using your configured LLM (no API keys needed)
5. Quality gates enforce standards before completion

User prompt  -->  Intent detection  -->  Agent pipeline  -->  Quality gates  -->  Output
                  (Simple Mode)         (plan/impl/test)     (score >= 70)

No local LLM required. Cursor handles all LLM operations via Skills.

---

What's Included

14 Workflow Agents

Phase	Agents	Purpose
Planning	Analyst, Planner	Requirements, user stories, task breakdown
Design	Architect, Designer	System architecture, API design, data models
Development	Implementer, Debugger, Documenter	Code generation, debugging, documentation
Testing	Tester	Unit/integration tests, coverage analysis
Quality	Reviewer, Improver	Code review with 7-category scoring, refactoring
Operations	Ops	Security scanning, compliance, dependency auditing
Orchestration	Orchestrator, Enhancer, Evaluator	Workflow coordination, prompt enhancement, evaluation

22 Cursor Skills

All 14 agents plus Simple Mode, Expert, Backend/Frontend Patterns, Bug-Fix Agent, Coding Standards, Security Review, and a custom skill example.

16 Built-in Experts

Security, Performance, Testing, Data Privacy, Accessibility, UX, Code Quality, Software Architecture, DevOps, Documentation, AI Frameworks, Observability, API Design, Cloud Infrastructure, Database, Agent Learning.

Backed by 119 knowledge files across 16 domains with RAG integration.

7-Category Code Scoring

Every review produces scores (0-10) for: Complexity, Security, Maintainability, Test Coverage, Performance, Structure, and Developer Experience.

---

Workflow Presets

Choose the right level of rigor for your task:

Preset	Steps	Best For	Command
Fix	3-6	Bug fixes, hotfixes	tapps-agents workflow fix
Rapid Dev	5-7	Standard features	tapps-agents workflow rapid-dev
Full SDLC	5-10	Complete lifecycle	tapps-agents workflow full
Quality	6	Code review cycle	tapps-agents workflow quality
Brownfield	varies	Existing codebase analysis	tapps-agents workflow brownfield

All workflows include adaptive checkpoints that optimize execution:

• Checkpoint 1 (After Enhance): Detects workflow mismatch early
• Checkpoint 2 (After Planning): Analyzes task complexity, may switch to simpler workflow
• Checkpoint 3 (After Test): Quality-based early termination (saves 12K-50K tokens)

---

Simple Mode Commands

Simple Mode is the primary interface for most users:

@simple-mode *build "description"       # Feature development (plan/impl/review/test)
@simple-mode *fix <file> "description"  # Bug fixing workflow
@simple-mode *review <file>             # Code quality review
@simple-mode *test <file>               # Test generation
@simple-mode *refactor <file>           # Code modernization
@simple-mode *explore <query>           # Codebase exploration
@simple-mode *enhance "prompt"          # Prompt enhancement
@simple-mode *epic <epic-doc.md>        # Execute Epic with dependency resolution
@simple-mode *full "description"        # Full SDLC (9 steps, for framework dev)
@simple-mode *pr "title"               # Pull request with quality scores
@simple-mode *breakdown "prompt"        # Task breakdown
@simple-mode *todo <bd args>            # Beads-backed task tracking

---

CLI Reference

# Top-level commands
tapps-agents init                    # Initialize project
tapps-agents doctor                  # Environment diagnostics
tapps-agents score <file>            # Quick quality score
tapps-agents workflow <preset>       # Run workflow preset
tapps-agents health overview         # System health summary
tapps-agents simple-mode <cmd>       # Simple Mode management

# Agent commands (tapps-agents <agent> <command>)
tapps-agents reviewer review <file>  # Code review
tapps-agents reviewer score <file>   # Quick scoring
tapps-agents implementer implement "desc" <file>
tapps-agents tester test <file>
tapps-agents debugger debug "error" --file <file>
tapps-agents enhancer enhance "prompt"
tapps-agents planner plan "description"
tapps-agents architect design "description"

# Epic & Expert
tapps-agents epic status             # Epic progress
tapps-agents expert list             # List available experts
tapps-agents expert consult "query" --domain security

# Workflow state
tapps-agents workflow state list     # List workflow states
tapps-agents workflow resume         # Resume interrupted workflow

# Project management
tapps-agents create "description"    # Create new project
tapps-agents status                  # Active worktrees and progress
tapps-agents continuous-bug-fix      # Automated bug fixing loop

---

Project Structure

TappsCodingAgents/
├── tapps_agents/                # Framework source code
│   ├── agents/                  #   14 workflow agents
│   ├── core/                    #   Base classes, config, instructions
│   ├── epic/                    #   Epic orchestration and state management
│   ├── experts/                 #   Expert system (16 built-in + industry)
│   │   └── knowledge/           #     119 knowledge files across 16 domains
│   ├── simple_mode/             #   Natural language orchestration
│   │   └── orchestrators/       #     18 workflow orchestrators
│   ├── workflow/                #   Workflow engine, parsers, handlers
│   ├── context7/                #   Context7 KB integration
│   ├── mcp/                     #   MCP Gateway (5 servers)
│   ├── health/                  #   Health monitoring
│   ├── quality/                 #   Quality gates and enforcement
│   └── continuous_bug_fix/      #   Automated bug fixing
├── workflows/presets/           # 5 YAML workflow presets
├── .claude/skills/              # 22 Cursor Skills
├── .claude/agents/              # 6 Claude Code subagents
├── .cursor/rules/               # 15 Cursor Rules files
├── templates/                   # Agent roles, project types, user roles
├── tests/                       # 377 test files (unit, integration, e2e)
├── docs/                        # Documentation
└── requirements/                # Specifications and requirements

---

Configuration

After running tapps-agents init, configuration lives in .tapps-agents/:

# .tapps-agents/config.yaml
quality:
  overall_threshold: 70        # Minimum overall score
  security_threshold: 6.5      # Minimum security score
  maintainability_threshold: 7.0

simple_mode:
  enabled: true
  enable_checkpoints: true     # Adaptive workflow optimization

epic:
  story_workflow_mode: "full"  # or "story-only"
  max_parallel_stories: 3
  parallel_strategy: "asyncio" # or "agent-teams"

See Configuration Guide for all options.

---

Epic Orchestration

Execute multi-story epics with dependency resolution:

# In Cursor
@simple-mode *epic docs/prd/epic-51-feature.md

# CLI
tapps-agents epic status --all
tapps-agents epic approve <story-id>

Features: parallel wave execution, story dependency ordering, state persistence, handoff artifacts.

---

Documentation

Getting Started

• Quick Start Guide
• Simple Mode Guide
• Cursor Skills Installation
• Configuration Guide

Architecture

• Architecture Overview
• Architecture Decisions (ADRs)
• Source Tree
• Tech Stack

Integration

• Multi-Tool Integration (Cursor, Claude Code, VS Code, Codespaces)
• Custom Skills Guide
• Epic Workflow Guide
• Hooks Guide
• Task Management

Operations

• Troubleshooting
• Deployment Guide
• Release Guide
• Test Suite

All Documentation

• Documentation Index

---

Contributing

See CONTRIBUTING.md for guidelines.

Framework Development

When modifying tapps_agents/, use the Full SDLC workflow:

tapps-agents simple-mode full --prompt "Implement [description]" --auto

Version Management

.\scripts\update_version.ps1 -Version 3.6.2

Updates version across pyproject.toml, init.py, README, docs, and metadata.

---

Platform Support

• Windows (primary), Linux, macOS
• UTF-8 encoding throughout (Windows CP1252 fallback handled)
• See Troubleshooting for platform-specific issues

---

License

MIT