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

{tapps_agents-3.6.0.dist-info → tapps_agents-3.6.1.dist-info}/METADATA

@@ -1,672 +1,672 @@
-Metadata-Version: 2.4
-Name: tapps-agents
-Version: 3.6.0
-Summary: A specification framework for defining, configuring, and orchestrating coding agents
-Author: Tapps
-Maintainer: Tapps
-License: MIT
-Project-URL: Homepage, https://github.com/wtthornton/TappsCodingAgents
-Project-URL: Repository, https://github.com/wtthornton/TappsCodingAgents
-Project-URL: Documentation, https://github.com/wtthornton/TappsCodingAgents
-Project-URL: Issues, https://github.com/wtthornton/TappsCodingAgents/issues
-Keywords: ai,agents,coding,workflow,automation
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pydantic>=2.12.5
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: pyyaml>=6.0.3
-Requires-Dist: aiohttp>=3.13.3
-Requires-Dist: psutil>=7.2.2
-Requires-Dist: radon>=6.0.1
-Requires-Dist: bandit>=1.9.3
-Requires-Dist: coverage>=7.13.3
-Requires-Dist: jinja2>=3.1.6
-Requires-Dist: packaging<27,>=23.2
-Requires-Dist: rich>=14.3.2
-Requires-Dist: aiofiles>=25.1.0
-Provides-Extra: dev
-Requires-Dist: ruff<1.0,>=0.15.0; extra == "dev"
-Requires-Dist: mypy<2.0,>=1.19.1; extra == "dev"
-Requires-Dist: types-PyYAML>=6.0.12.20250915; extra == "dev"
-Requires-Dist: pytest>=9.0.2; extra == "dev"
-Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
-Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
-Requires-Dist: pytest-mock>=3.15.1; extra == "dev"
-Requires-Dist: pytest-timeout>=2.4.0; extra == "dev"
-Requires-Dist: pytest-xdist>=3.8.0; extra == "dev"
-Requires-Dist: pytest-sugar>=1.1.1; extra == "dev"
-Requires-Dist: pytest-html>=4.1.1; extra == "dev"
-Requires-Dist: pytest-rich>=0.2.0; extra == "dev"
-Requires-Dist: pip-audit>=2.10.0; extra == "dev"
-Requires-Dist: pip-tools>=7.5.2; extra == "dev"
-Provides-Extra: reporting
-Requires-Dist: plotly>=6.5.2; extra == "reporting"
-Provides-Extra: dependency-analysis
-Requires-Dist: pipdeptree>=2.30.0; extra == "dependency-analysis"
-Dynamic: license-file
-
-# TappsCodingAgents
-
-[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
-[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
-[![Status](https://img.shields.io/badge/status-production--ready-brightgreen.svg)](README.md)
-[![Version](https://img.shields.io/badge/version-3.5.39-blue.svg)](CHANGELOG.md)
-
-**A specification framework for defining, configuring, and orchestrating coding agents.**
-
-TappsCodingAgents helps teams build and orchestrate AI coding agents with **quality gates**, **Cursor IDE integration**, and **full SDLC workflows**—so you get consistent, traceable results instead of one-off AI edits.
-
-**Highlights:** 14 workflow agents (review, implement, test, fix, plan, …) · **Simple Mode** for natural language (`@simple-mode *build "feature"`) · Cursor Skills + Claude Desktop · 11 YAML workflow presets · Code scoring, experts, and MCP gateway · **Adaptive Learning** system that auto-generates experts and improves scoring for first-pass code correctness.
-
-**Prerequisites:** Python 3.13+, [Cursor IDE](https://cursor.com) or [Claude Desktop](https://claude.ai). Optional: [Context7](https://context7.com) API key for library docs.
-
----
-
-## Table of Contents
-
-- [Quick Start (5 min)](#-cursor-quick-start-5-minutes)
-- [Simple Mode (New Users)](#-simple-mode-new-users)
-- [Key Features](#key-features)
-- [Documentation](#documentation)
-- [Contributing](#contributing)
-- [For Framework Developers](#for-framework-developers--contributors)
-
----
-
-## Overview
-
-> **Note:** This project both **develops** the framework and **uses** it for its own development (self-hosting). See [Project Context](docs/PROJECT_CONTEXT.md).
-
-**In the box:**
-- **14 workflow agents** — Analyst, Planner, Architect, Designer, Implementer, Tester, Debugger, Documenter, Reviewer, Improver, Ops, Orchestrator, Enhancer, Evaluator
-- **Simple Mode** — `@simple-mode *build "feature"`, `*review`, `*fix`, `*test`, and more in Cursor
-- **Cursor Skills + Claude Desktop** — All agents as `@agent *command`; 15 Claude Desktop commands
-- **11 YAML workflow presets** — rapid-dev, full-sdlc, maintenance, quality, quick-fix, and others
-- **Experts & quality** — 16 built-in experts, 7-category code scoring, MCP gateway (Context7, Playwright, Git, …)
-- **Adaptive Learning** — Auto-generates experts from usage patterns, adaptively adjusts scoring weights, improves expert voting, and optimizes for first-pass code correctness
-
-For the full list, see [Key Features](#key-features) and [Documentation](docs/README.md).
-
-### How it works (no confusion version)
-
-- **Cursor is the LLM runtime**: Skills use the developer's configured model in Cursor (Auto or pinned).
-- **This framework is the tooling layer**: workflows, quality tools, reporting, worktrees, caching.
-- **Cursor-native execution**: All LLM operations are handled by Cursor via Skills. No local LLM required.
-
-See:
-- `docs/HOW_IT_WORKS.md`
-- `docs/CURRENT_DEFAULTS.md`
-- `docs/PR_MODE_GUIDE.md`
-
-### 🚀 Cursor Quick Start (5 minutes)
-
-If you're using **Cursor IDE**, get started quickly:
-
-1. **Install the framework:**
-
-   Ensure Python 3.13+ (`python --version`). On Windows with multiple versions use `py -3.13`.
-
-   **For consuming projects (recommended):**
-   ```bash
-   # Install from PyPI (clean install, framework code only)
-   pip install tapps-agents
-   # or specific version:
-   pip install tapps-agents==3.5.39
-   ```
-   **Windows:** If `tapps-agents` is not found after install (user Scripts often not on PATH), use a project venv or run `python -m tapps_agents.cli` instead. See [Troubleshooting CLI installation](docs/TROUBLESHOOTING_CLI_INSTALLATION.md).
-
-   **For framework development (contributors):**
-   ```bash
-   # Clone repository and install in editable mode
-   git clone https://github.com/wtthornton/TappsCodingAgents.git
-   cd TappsCodingAgents
-   python3.13 -m pip install -e .
-   # Windows: py -3.13 -m pip install -e .
-   ```
-
-   After installing, run `tapps-agents doctor` (or `python -m tapps_agents.cli doctor`) to verify the setup.
-
-2. **Initialize Cursor integration:**
-
-   Run `init` from your **project root**, not from the TappsCodingAgents framework directory.
-
-   ```bash
-   # Correct: from your project
-   cd /path/to/your-project
-   tapps-agents init
-   # If 'tapps-agents' not found: python -m tapps_agents.cli init
-
-   # Wrong: from the framework directory (creates config in the wrong place)
-   # cd /path/to/TappsCodingAgents && tapps-agents init
-   ```
-
-   Optional: `tapps-agents init --hooks` creates `.tapps-agents/hooks.yaml` and `.tapps-agents/context/` from templates (all hooks disabled by default). Use `tapps-agents task create|list|run` for task specs and multi-session workflows; see [Task Management Guide](docs/TASK_MANAGEMENT_GUIDE.md).
-
-   This installs:
-   - ✅ **Cursor Skills** (`.claude/skills/`) - Use `@agent *command` in Cursor IDE
-   - ✅ **Claude Desktop Commands** (`.claude/commands/`) - Use `@command` in Claude Desktop
-   - ✅ **Cursor Rules** (`.cursor/rules/`)
-   - ✅ **Configuration** (`.tapps-agents/config.yaml`) - Tech stack detection, quality thresholds
-   - ✅ **Workflow Presets** (`workflows/presets/`) - full-sdlc, rapid-dev, fix, quality, brownfield-analysis
-   - ✅ **MCP Config** (`.cursor/mcp.json`) - Context7 for library docs (optional)
-   - ✅ **Framework version** (`.tapps-agents/.framework-version`) - Installed package version
-   - ✅ **Beads (bd)** - When `tools/bd` exists, `scripts/set_bd_path.ps1` is added if missing; init hints `bd init` / `bd doctor --fix` when `.beads` is missing. Set `beads.required: true` to make Beads mandatory (workflows fail if bd unavailable). See [Beads Integration](docs/BEADS_INTEGRATION.md).
-
-   **Note:** If you get "command not found" (common on Windows with user pip installs), use `python -m tapps_agents.cli` instead of `tapps-agents`, or use a project venv. See [Troubleshooting CLI installation](docs/TROUBLESHOOTING_CLI_INSTALLATION.md) for details.
-
-3. **Try it in Cursor IDE:**
-   - Open Cursor chat
-   - Type: `@reviewer *help`
-   - Type: `@implementer *help`
-   - Type: `@tester *help`
-   - Type: `@evaluator *help`
-
-4. **Or use Claude Desktop:**
-   - Type: `@review src/api/auth.py`
-   - Type: `@build "Create a user authentication feature"`
-   - Type: `@test src/api/auth.py`
-
-
-### 🎬 Try the Demo (5 minutes)
-
-**Want to see it in action?** Run our interactive demo:
-
-```bash
-# Run the automated demo script
-python demo/run_demo.py
-
-# Or follow the quick start guide
-cat demo/DEMO_QUICK_START.md
-```
-
-The demo showcases:
-- ✅ Code scoring with objective metrics
-- ✅ Code review with detailed feedback
-- ✅ Quality tools (linting, type checking)
-- ✅ Code generation workflows
-
-See [Demo Plan](docs/DEMO_PLAN.md) for complete demo scenarios and instructions.
-
-### 🎯 Simple Mode (New Users)
-
-**New to TappsCodingAgents?** Try **Simple Mode** - a streamlined, task-first interface that hides complexity while showcasing the power of the framework:
-
-1. **Initialize project** (first time setup):
-   ```bash
-   # If 'tapps-agents' command not found, use:
-   python -m tapps_agents.cli init
-   
-   # OR if entry point is working:
-   tapps-agents init
-   ```
-   This sets up configuration, Cursor Rules, workflow presets, Skills, and Claude Desktop Commands.
-
-2. **Enable Simple Mode:**
-   ```bash
-   tapps-agents simple-mode on
-   ```
-
-3. **Run the onboarding wizard** (optional, recommended for new users):
-   ```bash
-   tapps-agents simple-mode init
-   ```
-
-4. **Use Simple Mode in Cursor chat:**
-   
-   Open Cursor chat and use natural language commands with `@simple-mode`:
-   ```
-   @simple-mode Build a user authentication module
-   @simple-mode Review my authentication code
-   @simple-mode Fix the error in auth.py
-   @simple-mode Add tests for service.py
-   @simple-mode Explore the authentication system
-   @simple-mode Refactor legacy code in utils.py
-   @simple-mode Plan analysis for OAuth2 migration
-   @simple-mode PR "Add user authentication feature"
-   @simple-mode *enhance "Add OAuth2 login"
-   @simple-mode *breakdown "Migrate to microservices"
-   @simple-mode *todo ready
-   @simple-mode *epic docs/prd/epic-51-yaml-automation-quality-enhancement.md
-   ```
-   
-   Simple Mode automatically detects your intent and orchestrates the right agents.
-
-**Note:** Simple Mode natural language commands work in Cursor chat (via `@simple-mode` skill). CLI management commands (`on`, `off`, `status`, `init`) are available for configuration.
-
-**Simple Mode Features:**
-- ✅ **Task-first interface** - Focus on what you want to achieve
-- ✅ **Natural language commands** - Use plain English
-- ✅ **Guided onboarding** - Interactive wizard for new users
-- ✅ **Zero-config mode** - Smart defaults with auto-detection
-- ✅ **Learning progression** - Unlock advanced features as you learn
-- ✅ **Friendly error handling** - Clear messages with recovery suggestions
-
-**Full Documentation:**
-- [Simple Mode Guide](docs/SIMPLE_MODE_GUIDE.md) - Complete Simple Mode documentation
-- [Cursor Skills Installation Guide](docs/CURSOR_SKILLS_INSTALLATION_GUIDE.md)
-- [Cursor Rules Setup Guide](docs/CURSOR_RULES_SETUP.md)
-- [Cursor Integration Review](CURSOR_INTEGRATION_REVIEW.md) - Comprehensive integration status
-
-### Enhanced Features (v1.6.0+)
-
-- **Code Scoring System**: Objective quality metrics (complexity, security, maintainability)
-- **Tiered Context Injection**: 90%+ token savings with intelligent caching
-- **Adaptive Workflow Checkpoints** (v3.5.37+): Automatic workflow optimization
-  - 3 strategic checkpoints detect when workflows are overkill
-  - Switches to simpler workflows automatically (with user confirmation)
-  - Skips optional steps when quality is excellent (≥80)
-  - Saves 20K-40K tokens per optimization
-  - See [Checkpoint System Guide](docs/CHECKPOINT_SYSTEM_GUIDE.md)
-- **MCP Gateway**: Unified Model Context Protocol interface for tool access
-  - **Context7 MCP Server**: Library documentation lookup (required, auto-configured)
-  - **Playwright MCP Server**: Browser automation for E2E testing (optional, auto-detected)
-  - **Beads (bd)** (optional or required): Task tracking; `tapps-agents beads`; doctor reports bd status; init hints or mandates `bd init` when detected. Set `beads.required: true` to make workflows fail when bd unavailable. [Beads Integration](docs/BEADS_INTEGRATION.md)
-- **Hooks** (opt-in): Run shell commands at UserPromptSubmit, PostToolUse, SessionStart, SessionEnd, and WorkflowComplete. Configure in `.tapps-agents/hooks.yaml`; use `tapps-agents init --hooks` to create a template. [Hooks Guide](docs/HOOKS_GUIDE.md)
-- **Task management / multi-session**: Task specs in `.tapps-agents/task-specs/`, `tapps-agents task create|list|show|update|close|hydrate|dehydrate|run`, and hydration/dehydration for Beads. [Task Management Guide](docs/TASK_MANAGEMENT_GUIDE.md)
-- **YAML Workflow Definitions**: Declarative, version-controlled orchestration with strict schema enforcement
-- **Greenfield/Brownfield Workflows**: Context-appropriate workflows for project types
-- **YAML-First Architecture** ✅ (Epics 6-10 Complete):
-  - **Strict Schema Enforcement** (Epic 6): All YAML structures validated and executed, no "YAML theater"
-  - **Task Manifest Generation** (Epic 7): Auto-generated task checklists from workflow YAML + state
-  - **Automated Documentation** (Epic 8): Cursor Rules auto-generated from workflow YAML
-  - **Documentation Alignment** (Epic 10): All documentation aligned with YAML-first architecture
-- **Cursor AI Integration**: Complete 7-phase integration with Cursor AI
-  - Cursor Skills for all 14 agents
-  - Multi-agent orchestration
-  - Context7 KB-first caching
-
-## Current Status
-
-**Version** 3.5.39 · **Production ready** · All 7 Cursor AI integration phases complete · YAML-first architecture (Epics 6–10) · 14 workflow agents + Simple Mode · 16 built-in experts.
-
-📋 [Changelog](CHANGELOG.md) · [Cursor AI Integration Plan](docs/CURSOR_AI_INTEGRATION_PLAN_2025.md) · [YAML Workflow Design](docs/YAML_WORKFLOW_ARCHITECTURE_DESIGN.md)
-
-✅ **Core Framework Complete:**
-- **All 14 Workflow Agents** ✅ (analyst, planner, architect, designer, implementer, tester, debugger, documenter, reviewer, improver, ops, orchestrator, enhancer, evaluator)
-- **Complete Code Scoring System** ✅ (7 categories: complexity, security, maintainability, test_coverage, performance, structure, devex)
-- **Instruction-Based Architecture** ✅ - Agents prepare structured instructions for Cursor Skills execution
-- **Tiered Context System** ✅ (90%+ token savings, 3 tiers with caching)
-- **Unified Cache Architecture** ✅ (Single interface for all caching systems with hardware auto-detection)
-- **MCP Gateway** ✅ (Unified tool access with 5 servers: Context7, Playwright, Filesystem, Git, Analysis)
-  - **MCP Server Detection**: Automatic detection of Context7 and Playwright MCP servers
-  - **Setup Instructions**: Auto-generated setup instructions when MCP servers are missing
-  - **Status Reporting**: `tapps-agents doctor` reports MCP server configuration status and Beads (bd) status (optional)
-- **YAML Workflow Definitions** ✅ (Parser, executor, artifact tracking, conditional steps, gates)
-  - **YAML-First Architecture** ✅ (Epics 6-10): YAML as single source of truth with strict schema enforcement
-  - **Auto-Generated Artifacts** ✅: Task manifests, Cursor Rules docs
-  - **Dependency-Based Parallelism**: Automatic parallel execution based on step dependencies (no `parallel_tasks`)
-  - **11 Workflow Presets**: rapid-dev (enhance step), full-sdlc (optional enhance before requirements), maintenance, quality, quick-fix, feature-implementation, brownfield-analysis, simple-new-feature, simple-full, simple-improve-quality, simple-fix-issues
-- **Industry Experts Framework** ✅ (Weighted decision-making, domain configuration, expert registry)
-  - **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
-  - **100+ Knowledge Files**: Across 13 knowledge domains
-  - **Configuration-Only Experts**: YAML-based expert definition, no code classes required
-  - **RAG Integration**: Simple file-based and vector-based RAG for knowledge retrieval
-- **Simple Mode** ✅ (15+ orchestrators: build, review, fix, test, explore, refactor, plan-analysis, pr, epic, full, enhance, breakdown, todo, brownfield, validate, resume)
-- **Scale-Adaptive Workflow Selection** ✅ (Project type auto-detection, workflow recommendation)
-- **State Management** ✅ (Advanced workflow state persistence with checkpointing, migration, versioning, resume)
-- **Analytics & Health** ✅ (CLI: `health check`, `health overview`, `health usage dashboard|agents|workflows|system|trends`; performance metrics, trends, system health monitoring)
-- **Governance & Safety** ✅ (Secrets/PII filtering, knowledge ingestion safety)
-- **Comprehensive test suite** ✅ (1200+ unit tests, integration tests, and E2E tests with parallel execution support - see `tests/`)
-
-✅ **Enhancer Agent - Prompt Enhancement Utility (v1.6.0)**
-- **7-Stage Enhancement Pipeline** - Transforms simple prompts into comprehensive, context-aware prompts
-- **Industry Expert Integration** - Automatic domain detection and weighted expert consultation
-- **Multiple Usage Modes** - Full enhancement, quick enhancement, stage-by-stage execution
-- **Session Management** - Resume interrupted enhancements
-- **Multiple Output Formats** - Markdown, JSON, YAML
-- **Workflow integration** - full-sdlc (optional enhance step before requirements), rapid-dev, and Epic story workflows run the enhancer when an `enhance` step is present (EnhancerHandler). AnalystHandler and PlannerHandler consume `enhanced_prompt`/`description` from state.
-- **CLI auto-enhancement** - `auto_enhancement` in config enhances low-quality prompts for implementer, planner, analyst (see [Configuration](docs/CONFIGURATION.md#automatic-prompt-enhancement-auto_enhancement)). `PROMPT_ARGUMENT_MAP` and `commands` control which agent/command pairs are eligible.
-- See [Enhancer Agent Guide](docs/ENHANCER_AGENT.md) for details
-
-🎉 **All Core Framework Features Complete!**
-
-✅ **January 2026 Critical Features Complete:**
-- **Custom Skills Support** ✅ - Create, validate, and integrate custom Skills
-- **State Persistence Configuration** ✅ - Configurable checkpointing and cleanup policies
-- **Governance & Safety Layer** ✅ - Security and safety controls for knowledge ingestion
-- **Epic 20: Complexity Reduction** ✅ - Refactored high-complexity functions (122→C, 114→C, 66→C, 60→C, 64→A/B)
-  - Agent handler extraction using Strategy Pattern
-  - Workflow execution control flow simplification
-  - Zero code duplication between execution paths
-  - See [Complexity Reduction Summary](docs/COMPLEXITY_REDUCTION_EPIC_20.md)
-
-## Upcoming Enhancements (Planned)
-
-### SDLC Quality Engine Improvements
-
-The framework is being enhanced to transform the SDLC from a linear pipeline with score-only gates into a **self-correcting quality engine** that achieves "zero issues" consistently across any codebase.
-
-**Key Improvements:**
-- **Pluggable Validation Layer**: Stack-agnostic validation that adapts to detected project profile and repository signals
-- **Comprehensive Verification**: Expansion of "testing" into verification bundle (tests + linters + config checks + security scans + artifact integrity)
-- **Standardized Issues Manifest**: Machine-actionable issue schema (id, severity, category, evidence, repro, suggested_fix, owner_step) for deterministic remediation
-- **Composite Gating Model**: Gates evaluate issues + verification outcomes, not just numeric scores
-  - Hard fail conditions: critical issues, verification failures, missing artifacts
-  - Soft fail/loopback conditions: high issues above threshold, regression vs baseline, low expert confidence
-- **Bounded Loopback Protocol**: Deterministic remediation with structured fix plans, re-validation, and bounded retries
-- **Traceability Matrix**: Lightweight requirements → stories → validations mapping for completeness verification
-
-**Status**: Design phase - See [SDLC Improvements Analysis](SDLC_ISSUES_AND_IMPROVEMENTS_ANALYSIS.md) and [Epic 1: SDLC Quality Engine](docs/prd/epic-1-sdlc-quality-engine.md)
-
-### Dynamic Expert & RAG Engine
-
-An always-on **Dynamic Knowledge/Expert Orchestrator** that automatically detects project domains, creates and curates experts/knowledge for the current project, and continuously enriches agents with the best available, project-relevant information.
-
-**Key Features:**
-- **Automatic Expert Creation**: Framework-controlled technical experts + project-controlled business/domain experts generated from repo signals
-- **Knowledge Ingestion Pipeline**: Auto-fills RAG from project sources (requirements, architecture docs, ADRs), dependency sources (Context7 KB), and operational sources (CI failures, runtime exceptions)
-- **Expert Engine Runtime**: Continuously detects what domain knowledge is needed, proactively consults the right experts, and populates knowledge stores as agents learn
-- **Governance & Safety**: Do-not-index filters for secrets/PII, prompt-injection handling, retention & scope controls
-- **Observability & Quality Improvement**: Metrics tracking (expert confidence, RAG quality, Context7 KB hit rate) with scheduled KB maintenance jobs
-
-**Status**: Design phase - See [SDLC Improvements Analysis](SDLC_ISSUES_AND_IMPROVEMENTS_ANALYSIS.md) and [Epic 2: Dynamic Expert & RAG Engine](docs/prd/epic-2-dynamic-expert-rag-engine.md)
-
-## Key Features
-
-### Two-Layer Agent Model
-
-| Layer | Type | Purpose | Count |
-|-------|------|---------|-------|
-| **Knowledge** | Industry Experts | Business domain authority | N (per project) |
-| **Execution** | Workflow Agents | SDLC task execution | 14 (fixed) |
-
-### Workflow Agents (14)
-
-- **Planning**: 
-  - **analyst** ✅ - Requirements gathering, stakeholder analysis, tech research, effort estimation, risk assessment, competitive analysis
-  - **planner** ✅ - User story creation, task breakdown, story point estimation, acceptance criteria
-- **Design**: 
-  - **architect** ✅ - System architecture design, design patterns, tech selection, security architecture, boundary definition, architecture diagrams, pattern detection (*detect-patterns)
-  - **designer** ✅ - API design, data model design, UI/UX design, wireframes, design systems
-- **Development**: 
-  - **implementer** ✅ - Code generation, refactoring, file writing with backup support
-  - **debugger** ✅ - Error analysis, stack trace analysis, code execution tracing, root cause identification
-  - **documenter** ✅ - API documentation, README generation, docstring generation, code documentation
-- **Testing**: 
-  - **tester** ✅ - Test generation (unit, integration), test execution, coverage analysis
-- **Quality**: 
-  - **reviewer** ✅ - Code review with 7-category scoring (complexity, security, maintainability, test coverage, performance, structure, devex), actionable feedback with specific issues and line numbers, structured feedback always provided, context-aware quality gates, linting (Ruff), type checking (mypy), duplication detection, security scanning, project analysis, service analysis
-  - **improver** ✅ - Code refactoring, performance optimization, quality improvement suggestions
-- **Operations**: 
-  - **ops** ✅ - Security auditing, compliance checking (GDPR, HIPAA, PCI-DSS), dependency auditing, deployment planning
-- **Orchestration**: 
-  - **orchestrator** ✅ - Workflow coordination, step sequencing, gate decisions, workflow state management
-- **Enhancement**: 
-  - **enhancer** ✅ - 7-stage prompt enhancement pipeline (analysis, requirements, architecture, codebase, quality, strategy, synthesis), quick enhancement, stage-by-stage execution, session management
-- **Evaluation**: 
-  - **evaluator** ✅ - Framework effectiveness analysis, workflow evaluation, improvement recommendations, usage pattern analysis
-
-### Code Scoring System
-
-The Reviewer Agent includes a comprehensive code scoring system with 5 objective metrics and actionable feedback (2026-01-16):
-
-**Enhanced Features:**
-- ✅ **Accurate Test Coverage:** Returns 0.0% when no tests exist (not 5.0-6.0)
-- ✅ **Maintainability Issues:** Specific issues with line numbers, severity, and suggestions
-- ✅ **Structured Feedback:** Always provides actionable feedback (summary, strengths, issues, recommendations, priority)
-- ✅ **Performance Issues:** Performance bottlenecks with line numbers and context
-- ✅ **Accurate Type Checking:** Reflects actual mypy errors (not static 5.0)
-- ✅ **Context-Aware Quality Gates:** Adapts thresholds for new/modified/existing files
-
-The Reviewer Agent scoring system includes:
-
-1. **Complexity Score** (0-10): Cyclomatic complexity analysis using Radon
-2. **Security Score** (0-10): Vulnerability detection using Bandit + heuristics; npm audit for JS/TS
-3. **Maintainability Score** (0-10): Maintainability Index using Radon MI
-4. **Test Coverage Score** (0-10): Coverage data parsing + heuristic; Vitest/Jest/lcov for JS/TS
-5. **Performance Score** (0-10): Static analysis (function size, nesting depth, pattern detection)
-6. **Structure Score** (0-10): Project layout, key files (README, config, tests), conventions
-7. **DevEx Score** (0-10): Docs (AGENTS.md, CLAUDE.md), config, tooling
-
-All metrics are configurable with weighted scoring and quality thresholds.
-
-### Industry Experts
-
-- **Business Domain Experts** (N): Project-specific domain authorities (not technical specialists)
-  - 1:1 mapping: N domains → N experts
-  - Weighted decision-making (Primary: 51%, Others: 49%/(N-1))
-  - RAG integration (simple file-based and vector-based)
-  - Fine-tuning support (LoRA adapters - planned)
-  - Consult-based integration with 6 workflow agents (Architect, Implementer, Reviewer, Tester, Designer, Ops)
-- **Built-in Technical Experts** (16): Framework-controlled domain experts
-  - Security, Performance, Testing, Data Privacy, Accessibility, UX, Code Quality, Software Architecture, DevOps, Documentation, AI Frameworks, Observability, API Design, Cloud Infrastructure, Database, Agent Learning
-  - 100+ knowledge files across 13 knowledge domains
-  - Automatic domain detection and expert consultation
-  - Project profiling for context-aware guidance
-- **Expert Governance**: Secrets/PII filtering, prompt injection handling, knowledge ingestion safety
-
-### CLI Commands
-
-**Top-Level Commands:**
-- `init` - Initialize project (Cursor Rules, Skills, config)
-- `create <description>` - Create new project from natural language description
-- `workflow <preset>` - Run workflow presets (rapid, full, fix, quality, hotfix, etc.)
-- `continuous-bug-fix` - Continuously find and fix bugs from test failures (automated bug fixing loop)
-- `score <file>` - Quick code quality scoring (shortcut for `reviewer score`)
-- `doctor` - Environment diagnostics and validation
-- `cursor verify` - Verify Cursor AI integration components
-- `simple-mode <command>` - Simple Mode management (on, off, status, init, configure, progress, full, build, resume, enhance, breakdown, todo)
-- `health <command>` - Health monitoring (check, dashboard, metrics, trends, usage). Use `health usage dashboard|agents|workflows|system|trends` for analytics (formerly `analytics`).
-- `customize <command>` - Agent customization (init)
-- `skill <command>` - Custom Skills management (validate, template)
-- `install-dev` - Install development tools (ruff, mypy, pytest, pip-audit, pipdeptree)
-- `setup-experts` - Expert setup wizard (init, add, remove, list)
-- `status` - Unified status (active worktrees, progress)
-- `generate-rules` - Generate Cursor Rules from workflow YAML
-
-**Agent Commands** (use `tapps-agents <agent> help` for details):
-- `analyst` - Requirements gathering, stakeholder analysis, tech research, effort estimation, risk assessment
-- `architect` - System design, architecture diagrams, tech selection, security architecture, boundary definition
-- `debugger` - Error debugging, stack trace analysis, code tracing
-- `designer` - API design, data models, UI/UX design, wireframes, design systems
-- `documenter` - Generate documentation, update README, document APIs
-- `enhancer` - Prompt enhancement (full, quick, stage-by-stage, resume)
-- `evaluator` - Framework effectiveness evaluation, workflow evaluation
-- `implementer` - Code generation, refactoring
-- `improver` - Code refactoring, performance optimization
-- `ops` - Security scanning, compliance checks, dependency auditing, deployment planning, bundle analysis (audit-bundle)
-- `orchestrator` - Workflow management, step coordination, gate decisions
-- `planner` - Create plans, user stories, task breakdowns
-- `reviewer` - Code review, scoring, actionable feedback with specific issues, structured feedback, context-aware quality gates, linting, type checking, reports, duplication detection, security scanning, project/service analysis
-- `tester` - Generate and run tests, test coverage
-
-**Workflow State Management:**
-- `workflow state list` - List workflow states
-- `workflow state show <id>` - Show workflow state details
-- `workflow state cleanup` - Cleanup old workflow states
-- `workflow cleanup-branches` - Cleanup workflow worktree branches
-- `workflow resume` - Resume interrupted workflow
-
-**Simple Mode Workflows** (in Cursor chat with `@simple-mode`):
-- `*build <description>` - Complete feature development workflow (7 steps)
-- `*review <file>` - Code quality review with improvements
-- `*fix <file> <description>` - Systematic bug fixing workflow
-- `*test <file>` - Test generation and execution
-- `*explore <query>` - Codebase exploration and navigation
-- `*refactor <file>` - Systematic code modernization with safety checks
-- `*plan-analysis <description>` - Safe read-only code analysis and planning
-- `*pr <title>` - Pull request creation with quality scores
-- `*enhance "prompt"` - Prompt enhancement (EnhancerAgent)
-- `*breakdown "prompt"` - Task breakdown (PlannerAgent)
-- `*todo <bd args>` - Beads-backed todo (e.g. ready, create "Title")
-- `*epic <epic-doc.md>` - Execute Epic documents with dependency resolution
-- `*full <description>` - Full SDLC workflow (9 steps)
-
-## Project Structure
-
-```
-TappsCodingAgents/
-├── requirements/                  # Specification documents (see requirements/README.md)
-│   ├── PROJECT_REQUIREMENTS.md    # Main requirements document
-│   ├── agent_api.md               # Agent API specification
-│   ├── agents.md                  # Agent types specification
-│   ├── model_profiles.yaml        # Model configurations
-│   └── template/                  # Templates and schemas
-│
-├── tapps_agents/                  # Framework source code
-│   ├── agents/                    # All 14 workflow agents
-│   │   ├── reviewer/             # Code review & scoring
-│   │   ├── implementer/          # Code generation
-│   │   ├── tester/               # Test generation
-│   │   └── ...                   # 11 more agents (14 total)
-│   ├── core/                     # Core framework components
-│   ├── context7/                 # Context7 KB integration
-│   ├── experts/                  # Industry experts framework
-│   ├── workflow/                 # Workflow engine
-│   └── mcp/                      # MCP Gateway
-│
-├── .claude/                       # Cursor Skills (canonical; init copies from tapps_agents/resources/claude)
-├── workflows/                     # YAML workflow definitions and presets
-├── examples/                      # Example configurations
-├── docs/                          # Documentation
-│   ├── implementation/           # EPIC/PHASE plans, IMPROVEMENT_PLAN.json
-│   ├── archive/                  # Archived summaries; stories in archive/stories/
-│   ├── releases/                 # Release notes
-│   ├── context7/                 # Context7 integration
-│   └── operations/               # Deployment, release, package distribution
-├── scripts/                       # Utilities (see scripts/README.md)
-├── templates/                     # Agent roles, project types, tech stacks, cursor-rules-template
-└── tests/                         # Test suite
-    ├── unit/                      # Unit tests (fast, isolated)
-    ├── integration/               # Integration tests (with real services)
-    └── e2e/                       # End-to-end tests (see tests/e2e/README.md)
-```
-
-## Documentation
-
-### Getting Started
-- **[Quick Start Guide](docs/guides/QUICK_START.md)** - 🚀 Get started in 10 minutes
-- **[Simple Mode Guide](docs/SIMPLE_MODE_GUIDE.md)** - 🎯 Simple Mode for new users (task-first, natural language)
-- **[Cursor AI Integration Plan 2025](docs/CURSOR_AI_INTEGRATION_PLAN_2025.md)** - Complete integration roadmap (all 7 phases complete)
-- **[Cursor Skills Installation Guide](docs/CURSOR_SKILLS_INSTALLATION_GUIDE.md)** - Install and use Cursor Skills
-- **[Documentation Index](docs/README.md)** - Complete documentation overview
-- **[API Reference](docs/API.md)** - Python API and CLI documentation
-- **[Enhancer Agent Guide](docs/ENHANCER_AGENT.md)** - Prompt enhancement utility documentation
-
-### Complete Command Reference
-- **Cursor Rules**: `.cursor/rules/command-reference.mdc` (installed by `tapps-agents init`) - **Complete command reference with all commands, subcommands, and parameters**
-- **Quick Reference**: `.cursor/rules/quick-reference.mdc` - Quick command reference for common tasks
-- **Agent Capabilities**: `.cursor/rules/agent-capabilities.mdc` - Detailed agent capability descriptions
-- **Simple Mode Guide**: `.cursor/rules/simple-mode.mdc` - Simple Mode workflow documentation
-
-**Note**: After running `tapps-agents init`, all command reference documentation is available in `.cursor/rules/` directory. The `command-reference.mdc` file contains the most comprehensive documentation with all commands, subcommands, parameters, and examples.
-
-### Core Guides
-- **[Architecture Overview](docs/ARCHITECTURE.md)** - System architecture and design
-- **[Configuration Guide](docs/CONFIGURATION.md)** - Complete configuration reference
-- **[Developer Guide](docs/DEVELOPER_GUIDE.md)** - Development setup and workflows
-- **[User Role Templates Guide](docs/USER_ROLE_TEMPLATES_GUIDE.md)** - Customize agents by role (senior-dev, junior-dev, tech-lead, PM, QA)
-- **[Customization Guide](docs/CUSTOMIZATION_GUIDE.md)** - Project-specific agent customizations
-
-### Cursor AI Integration
-- **[Cursor Skills Installation Guide](docs/CURSOR_SKILLS_INSTALLATION_GUIDE.md)** - Install and configure Cursor Skills
-- **[Custom Skills Guide](docs/CUSTOM_SKILLS_GUIDE.md)** - Create, validate, and manage custom Skills
-- **[Cursor Rules Setup Guide](docs/CURSOR_RULES_SETUP.md)** - Cursor Rules setup (auto-generated from YAML workflows)
-- **[Multi-Agent Orchestration Guide](docs/MULTI_AGENT_ORCHESTRATION_GUIDE.md)** - Parallel agent execution
-- **[YAML Workflow Architecture Design](docs/YAML_WORKFLOW_ARCHITECTURE_DESIGN.md)** - YAML-first architecture with generated artifacts
-- **[Unified Cache Architecture](docs/implementation/UNIFIED_CACHE_ARCHITECTURE_PLAN.md)** - Single interface for all caching systems
-- **[Unified Cache Integration Guide](docs/implementation/UNIFIED_CACHE_INTEGRATION_GUIDE.md)** - Using unified cache in agents
-- **[Context7 Cache Optimization](docs/CONTEXT7_CACHE_OPTIMIZATION.md)** - Optimize cache hit rates
-- **[Context7 Security & Privacy](docs/context7/CONTEXT7_SECURITY_PRIVACY.md)** - Security best practices
-- **[Playwright MCP Integration](docs/PLAYWRIGHT_MCP_INTEGRATION.md)** - Browser automation with Playwright MCP server
-### Operations
-- **[Deployment Guide](docs/operations/DEPLOYMENT.md)** - Production deployment instructions
-- **[Troubleshooting Guide](docs/TROUBLESHOOTING.md)** - Common issues and solutions
-- **[Checkpoint & Resume Guide](docs/CHECKPOINT_RESUME_GUIDE.md)** - State persistence and workflow resumption
-- **[Test Suite Documentation](tests/README.md)** - Complete test suite overview and E2E test guide
-- **[E2E Test Suite](tests/e2e/README.md)** - End-to-end test documentation (smoke, workflow, scenario, CLI tests)
-- **[Test Performance Guide](docs/TEST_PERFORMANCE_GUIDE.md)** - Optimize test execution (5-10x faster with parallel execution)
-- **[Hardware Recommendations](docs/HARDWARE_RECOMMENDATIONS.md)** - Optimal computer specs for fast development
-- **[Security Policy](SECURITY.md)** - Security guidelines
-
-### Contributing
-
-**Get help:** [CONTRIBUTING](CONTRIBUTING.md) · [Documentation](docs/README.md)
-
-- **[Contributing Guidelines](CONTRIBUTING.md)** — How to contribute
-- **[Changelog](CHANGELOG.md)** — Version history and changes
-
-### Version Management
-
-When updating the version number, use the automated script to ensure all files are updated consistently:
-
-```powershell
-# Update version to 3.0.4 (or any version)
-.\scripts\update_version.ps1 -Version 3.0.4
-
-# Update core files only (skip documentation)
-.\scripts\update_version.ps1 -Version 3.0.4 -SkipDocs
-```
-
-**What it updates:**
-- ✅ `pyproject.toml` - Package version
-- ✅ `tapps_agents/__init__.py` - Module version
-- ✅ `README.md` - Version badge and references
-- ✅ `docs/README.md` - Documentation version
-- ✅ `docs/API.md` - API version
-- ✅ `docs/ARCHITECTURE.md` - Architecture version
-- ✅ `docs/implementation/IMPROVEMENT_PLAN.json` - Metadata version
-- ✅ Other documentation files with version references
-
-**After running the script:**
-1. Review changes: `git diff`
-2. Update `CHANGELOG.md` with release notes
-3. Commit and push changes
-4. Create git tag: `git tag v3.0.4 && git push origin v3.0.4`
-
-See [Release Guide](docs/operations/RELEASE_GUIDE.md) for complete release process.
-
-### Reference
-- **[Project Requirements](requirements/PROJECT_REQUIREMENTS.md)** - Complete specification
-- **[Technology Stack](requirements/TECH_STACK.md)** - Recommended technologies
-
-## Status
-
-**Phase**: ✅ **All 7 Phases Complete - Cursor AI Integration Plan 2025**  
-**Version**: 3.5.39  
-**Last Updated**: January 2026  
-**Cursor AI Integration**: ✅ Complete (Phases 1-7)  
-**Dependencies**: ✅ Updated to latest 2025 stable versions (pytest 9.x, ruff 0.14.8, mypy 1.19.0, etc.)
-
-### Integration Status
-- ✅ Phase 1: Core Agents to Skills
-- ✅ Phase 2: Quality Tools Integration
-- ✅ Phase 3: Remaining Agents + Advanced Features
-- ✅ Phase 5: Multi-Agent Orchestration
-- ✅ Phase 6: Context7 Optimization + Security
-- ✅ Phase 7: NUC Optimization
-
-See [Cursor AI Integration Plan 2025](docs/CURSOR_AI_INTEGRATION_PLAN_2025.md) for complete details.
-
-## Self-Hosting
-
-This project uses its own framework for development:
-- **5 Industry Experts** configured (AI frameworks, code quality, architecture, DevOps, documentation)
-- **Enhancer Agent** actively used (23+ enhancement sessions)
-- **Context7 Integration** with KB cache
-- **14 Cursor Skills** available in `.claude/skills/` (14 agent skills + simple-mode)
-- **NUC Optimization** enabled for resource-constrained environments
-- Configuration in `.tapps-agents/` directory
-
-See [Self-Hosting Setup](docs/implementation/SELF_HOSTING_SETUP_COMPLETE.md) for details.
-
-## Platform & repository
-
-- **Windows:** Supported (Windows, Linux, macOS). Use UTF-8 for scripts and file I/O. See [Troubleshooting](docs/TROUBLESHOOTING.md) and [CONTRIBUTING](CONTRIBUTING.md) for encoding guidelines.
-- **Repository:** Dependabot, CODEOWNERS, issue/PR templates, GitHub Actions, SECURITY.md. See [CONTRIBUTING](CONTRIBUTING.md) and [.github/](.github/).
-
-## For Framework Developers & Contributors
-
-- **Accuracy:** Agents and skills must report only verified facts. Do not assume success from tests or error handling. See project rules in `.cursor/rules/` and [CONTRIBUTING](CONTRIBUTING.md).
-- **Framework changes:** When modifying `tapps_agents/`, use the Full SDLC workflow: `@simple-mode *full "Implement [description]"` or `tapps-agents simple-mode full --prompt "..." --auto`. See [Framework Development Workflow](docs/FRAMEWORK_DEVELOPMENT_WORKFLOW.md).
-
-## License
-
-See [LICENSE](LICENSE) file for details.
+Metadata-Version: 2.4
+Name: tapps-agents
+Version: 3.6.1
+Summary: A specification framework for defining, configuring, and orchestrating coding agents
+Author: Tapps
+Maintainer: Tapps
+License: MIT
+Project-URL: Homepage, https://github.com/wtthornton/TappsCodingAgents
+Project-URL: Repository, https://github.com/wtthornton/TappsCodingAgents
+Project-URL: Documentation, https://github.com/wtthornton/TappsCodingAgents
+Project-URL: Issues, https://github.com/wtthornton/TappsCodingAgents/issues
+Keywords: ai,agents,coding,workflow,automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: aiohttp>=3.13.3
+Requires-Dist: psutil>=7.2.2
+Requires-Dist: radon>=6.0.1
+Requires-Dist: bandit>=1.9.3
+Requires-Dist: coverage>=7.13.3
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: packaging<27,>=23.2
+Requires-Dist: rich>=14.3.2
+Requires-Dist: aiofiles>=25.1.0
+Provides-Extra: dev
+Requires-Dist: ruff<1.0,>=0.15.0; extra == "dev"
+Requires-Dist: mypy<2.0,>=1.19.1; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0.12.20250915; extra == "dev"
+Requires-Dist: pytest>=9.0.2; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
+Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.15.1; extra == "dev"
+Requires-Dist: pytest-timeout>=2.4.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.8.0; extra == "dev"
+Requires-Dist: pytest-sugar>=1.1.1; extra == "dev"
+Requires-Dist: pytest-html>=4.1.1; extra == "dev"
+Requires-Dist: pytest-rich>=0.2.0; extra == "dev"
+Requires-Dist: pip-audit>=2.10.0; extra == "dev"
+Requires-Dist: pip-tools>=7.5.2; extra == "dev"
+Provides-Extra: reporting
+Requires-Dist: plotly>=6.5.2; extra == "reporting"
+Provides-Extra: dependency-analysis
+Requires-Dist: pipdeptree>=2.30.0; extra == "dependency-analysis"
+Dynamic: license-file
+
+# TappsCodingAgents
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Status](https://img.shields.io/badge/status-production--ready-brightgreen.svg)](README.md)
+[![Version](https://img.shields.io/badge/version-3.5.39-blue.svg)](CHANGELOG.md)
+
+**A specification framework for defining, configuring, and orchestrating coding agents.**
+
+TappsCodingAgents helps teams build and orchestrate AI coding agents with **quality gates**, **Cursor IDE integration**, and **full SDLC workflows**—so you get consistent, traceable results instead of one-off AI edits.
+
+**Highlights:** 14 workflow agents (review, implement, test, fix, plan, …) · **Simple Mode** for natural language (`@simple-mode *build "feature"`) · Cursor Skills + Claude Desktop · 11 YAML workflow presets · Code scoring, experts, and MCP gateway · **Adaptive Learning** system that auto-generates experts and improves scoring for first-pass code correctness.
+
+**Prerequisites:** Python 3.13+, [Cursor IDE](https://cursor.com) or [Claude Desktop](https://claude.ai). Optional: [Context7](https://context7.com) API key for library docs.
+
+---
+
+## Table of Contents
+
+- [Quick Start (5 min)](#-cursor-quick-start-5-minutes)
+- [Simple Mode (New Users)](#-simple-mode-new-users)
+- [Key Features](#key-features)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [For Framework Developers](#for-framework-developers--contributors)
+
+---
+
+## Overview
+
+> **Note:** This project both **develops** the framework and **uses** it for its own development (self-hosting). See [Project Context](docs/PROJECT_CONTEXT.md).
+
+**In the box:**
+- **14 workflow agents** — Analyst, Planner, Architect, Designer, Implementer, Tester, Debugger, Documenter, Reviewer, Improver, Ops, Orchestrator, Enhancer, Evaluator
+- **Simple Mode** — `@simple-mode *build "feature"`, `*review`, `*fix`, `*test`, and more in Cursor
+- **Cursor Skills + Claude Desktop** — All agents as `@agent *command`; 15 Claude Desktop commands
+- **11 YAML workflow presets** — rapid-dev, full-sdlc, maintenance, quality, quick-fix, and others
+- **Experts & quality** — 16 built-in experts, 7-category code scoring, MCP gateway (Context7, Playwright, Git, …)
+- **Adaptive Learning** — Auto-generates experts from usage patterns, adaptively adjusts scoring weights, improves expert voting, and optimizes for first-pass code correctness
+
+For the full list, see [Key Features](#key-features) and [Documentation](docs/README.md).
+
+### How it works (no confusion version)
+
+- **Cursor is the LLM runtime**: Skills use the developer's configured model in Cursor (Auto or pinned).
+- **This framework is the tooling layer**: workflows, quality tools, reporting, worktrees, caching.
+- **Cursor-native execution**: All LLM operations are handled by Cursor via Skills. No local LLM required.
+
+See:
+- `docs/HOW_IT_WORKS.md`
+- `docs/CURRENT_DEFAULTS.md`
+- `docs/PR_MODE_GUIDE.md`
+
+### 🚀 Cursor Quick Start (5 minutes)
+
+If you're using **Cursor IDE**, get started quickly:
+
+1. **Install the framework:**
+
+   Ensure Python 3.13+ (`python --version`). On Windows with multiple versions use `py -3.13`.
+
+   **For consuming projects (recommended):**
+   ```bash
+   # Install from PyPI (clean install, framework code only)
+   pip install tapps-agents
+   # or specific version:
+   pip install tapps-agents==3.5.39
+   ```
+   **Windows:** If `tapps-agents` is not found after install (user Scripts often not on PATH), use a project venv or run `python -m tapps_agents.cli` instead. See [Troubleshooting CLI installation](docs/TROUBLESHOOTING_CLI_INSTALLATION.md).
+
+   **For framework development (contributors):**
+   ```bash
+   # Clone repository and install in editable mode
+   git clone https://github.com/wtthornton/TappsCodingAgents.git
+   cd TappsCodingAgents
+   python3.13 -m pip install -e .
+   # Windows: py -3.13 -m pip install -e .
+   ```
+
+   After installing, run `tapps-agents doctor` (or `python -m tapps_agents.cli doctor`) to verify the setup.
+
+2. **Initialize Cursor integration:**
+
+   Run `init` from your **project root**, not from the TappsCodingAgents framework directory.
+
+   ```bash
+   # Correct: from your project
+   cd /path/to/your-project
+   tapps-agents init
+   # If 'tapps-agents' not found: python -m tapps_agents.cli init
+
+   # Wrong: from the framework directory (creates config in the wrong place)
+   # cd /path/to/TappsCodingAgents && tapps-agents init
+   ```
+
+   Optional: `tapps-agents init --hooks` creates `.tapps-agents/hooks.yaml` and `.tapps-agents/context/` from templates (all hooks disabled by default). Use `tapps-agents task create|list|run` for task specs and multi-session workflows; see [Task Management Guide](docs/TASK_MANAGEMENT_GUIDE.md).
+
+   This installs:
+   - ✅ **Cursor Skills** (`.claude/skills/`) - Use `@agent *command` in Cursor IDE
+   - ✅ **Claude Desktop Commands** (`.claude/commands/`) - Use `@command` in Claude Desktop
+   - ✅ **Cursor Rules** (`.cursor/rules/`)
+   - ✅ **Configuration** (`.tapps-agents/config.yaml`) - Tech stack detection, quality thresholds
+   - ✅ **Workflow Presets** (`workflows/presets/`) - full-sdlc, rapid-dev, fix, quality, brownfield-analysis
+   - ✅ **MCP Config** (`.cursor/mcp.json`) - Context7 for library docs (optional)
+   - ✅ **Framework version** (`.tapps-agents/.framework-version`) - Installed package version
+   - ✅ **Beads (bd)** - When `tools/bd` exists, `scripts/set_bd_path.ps1` is added if missing; init hints `bd init` / `bd doctor --fix` when `.beads` is missing. Set `beads.required: true` to make Beads mandatory (workflows fail if bd unavailable). See [Beads Integration](docs/BEADS_INTEGRATION.md).
+
+   **Note:** If you get "command not found" (common on Windows with user pip installs), use `python -m tapps_agents.cli` instead of `tapps-agents`, or use a project venv. See [Troubleshooting CLI installation](docs/TROUBLESHOOTING_CLI_INSTALLATION.md) for details.
+
+3. **Try it in Cursor IDE:**
+   - Open Cursor chat
+   - Type: `@reviewer *help`
+   - Type: `@implementer *help`
+   - Type: `@tester *help`
+   - Type: `@evaluator *help`
+
+4. **Or use Claude Desktop:**
+   - Type: `@review src/api/auth.py`
+   - Type: `@build "Create a user authentication feature"`
+   - Type: `@test src/api/auth.py`
+
+
+### 🎬 Try the Demo (5 minutes)
+
+**Want to see it in action?** Run our interactive demo:
+
+```bash
+# Run the automated demo script
+python demo/run_demo.py
+
+# Or follow the quick start guide
+cat demo/DEMO_QUICK_START.md
+```
+
+The demo showcases:
+- ✅ Code scoring with objective metrics
+- ✅ Code review with detailed feedback
+- ✅ Quality tools (linting, type checking)
+- ✅ Code generation workflows
+
+See [Demo Plan](docs/DEMO_PLAN.md) for complete demo scenarios and instructions.
+
+### 🎯 Simple Mode (New Users)
+
+**New to TappsCodingAgents?** Try **Simple Mode** - a streamlined, task-first interface that hides complexity while showcasing the power of the framework:
+
+1. **Initialize project** (first time setup):
+   ```bash
+   # If 'tapps-agents' command not found, use:
+   python -m tapps_agents.cli init
+   
+   # OR if entry point is working:
+   tapps-agents init
+   ```
+   This sets up configuration, Cursor Rules, workflow presets, Skills, and Claude Desktop Commands.
+
+2. **Enable Simple Mode:**
+   ```bash
+   tapps-agents simple-mode on
+   ```
+
+3. **Run the onboarding wizard** (optional, recommended for new users):
+   ```bash
+   tapps-agents simple-mode init
+   ```
+
+4. **Use Simple Mode in Cursor chat:**
+   
+   Open Cursor chat and use natural language commands with `@simple-mode`:
+   ```
+   @simple-mode Build a user authentication module
+   @simple-mode Review my authentication code
+   @simple-mode Fix the error in auth.py
+   @simple-mode Add tests for service.py
+   @simple-mode Explore the authentication system
+   @simple-mode Refactor legacy code in utils.py
+   @simple-mode Plan analysis for OAuth2 migration
+   @simple-mode PR "Add user authentication feature"
+   @simple-mode *enhance "Add OAuth2 login"
+   @simple-mode *breakdown "Migrate to microservices"
+   @simple-mode *todo ready
+   @simple-mode *epic docs/prd/epic-51-yaml-automation-quality-enhancement.md
+   ```
+   
+   Simple Mode automatically detects your intent and orchestrates the right agents.
+
+**Note:** Simple Mode natural language commands work in Cursor chat (via `@simple-mode` skill). CLI management commands (`on`, `off`, `status`, `init`) are available for configuration.
+
+**Simple Mode Features:**
+- ✅ **Task-first interface** - Focus on what you want to achieve
+- ✅ **Natural language commands** - Use plain English
+- ✅ **Guided onboarding** - Interactive wizard for new users
+- ✅ **Zero-config mode** - Smart defaults with auto-detection
+- ✅ **Learning progression** - Unlock advanced features as you learn
+- ✅ **Friendly error handling** - Clear messages with recovery suggestions
+
+**Full Documentation:**
+- [Simple Mode Guide](docs/SIMPLE_MODE_GUIDE.md) - Complete Simple Mode documentation
+- [Cursor Skills Installation Guide](docs/CURSOR_SKILLS_INSTALLATION_GUIDE.md)
+- [Cursor Rules Setup Guide](docs/CURSOR_RULES_SETUP.md)
+- [Cursor Integration Review](CURSOR_INTEGRATION_REVIEW.md) - Comprehensive integration status
+
+### Enhanced Features (v1.6.0+)
+
+- **Code Scoring System**: Objective quality metrics (complexity, security, maintainability)
+- **Tiered Context Injection**: 90%+ token savings with intelligent caching
+- **Adaptive Workflow Checkpoints** (v3.5.37+): Automatic workflow optimization
+  - 3 strategic checkpoints detect when workflows are overkill
+  - Switches to simpler workflows automatically (with user confirmation)
+  - Skips optional steps when quality is excellent (≥80)
+  - Saves 20K-40K tokens per optimization
+  - See [Checkpoint System Guide](docs/CHECKPOINT_SYSTEM_GUIDE.md)
+- **MCP Gateway**: Unified Model Context Protocol interface for tool access
+  - **Context7 MCP Server**: Library documentation lookup (required, auto-configured)
+  - **Playwright MCP Server**: Browser automation for E2E testing (optional, auto-detected)
+  - **Beads (bd)** (optional or required): Task tracking; `tapps-agents beads`; doctor reports bd status; init hints or mandates `bd init` when detected. Set `beads.required: true` to make workflows fail when bd unavailable. [Beads Integration](docs/BEADS_INTEGRATION.md)
+- **Hooks** (opt-in): Run shell commands at UserPromptSubmit, PostToolUse, SessionStart, SessionEnd, and WorkflowComplete. Configure in `.tapps-agents/hooks.yaml`; use `tapps-agents init --hooks` to create a template. [Hooks Guide](docs/HOOKS_GUIDE.md)
+- **Task management / multi-session**: Task specs in `.tapps-agents/task-specs/`, `tapps-agents task create|list|show|update|close|hydrate|dehydrate|run`, and hydration/dehydration for Beads. [Task Management Guide](docs/TASK_MANAGEMENT_GUIDE.md)
+- **YAML Workflow Definitions**: Declarative, version-controlled orchestration with strict schema enforcement
+- **Greenfield/Brownfield Workflows**: Context-appropriate workflows for project types
+- **YAML-First Architecture** ✅ (Epics 6-10 Complete):
+  - **Strict Schema Enforcement** (Epic 6): All YAML structures validated and executed, no "YAML theater"
+  - **Task Manifest Generation** (Epic 7): Auto-generated task checklists from workflow YAML + state
+  - **Automated Documentation** (Epic 8): Cursor Rules auto-generated from workflow YAML
+  - **Documentation Alignment** (Epic 10): All documentation aligned with YAML-first architecture
+- **Cursor AI Integration**: Complete 7-phase integration with Cursor AI
+  - Cursor Skills for all 14 agents
+  - Multi-agent orchestration
+  - Context7 KB-first caching
+
+## Current Status
+
+**Version** 3.5.39 · **Production ready** · All 7 Cursor AI integration phases complete · YAML-first architecture (Epics 6–10) · 14 workflow agents + Simple Mode · 16 built-in experts.
+
+📋 [Changelog](CHANGELOG.md) · [Cursor AI Integration Plan](docs/CURSOR_AI_INTEGRATION_PLAN_2025.md) · [YAML Workflow Design](docs/YAML_WORKFLOW_ARCHITECTURE_DESIGN.md)
+
+✅ **Core Framework Complete:**
+- **All 14 Workflow Agents** ✅ (analyst, planner, architect, designer, implementer, tester, debugger, documenter, reviewer, improver, ops, orchestrator, enhancer, evaluator)
+- **Complete Code Scoring System** ✅ (7 categories: complexity, security, maintainability, test_coverage, performance, structure, devex)
+- **Instruction-Based Architecture** ✅ - Agents prepare structured instructions for Cursor Skills execution
+- **Tiered Context System** ✅ (90%+ token savings, 3 tiers with caching)
+- **Unified Cache Architecture** ✅ (Single interface for all caching systems with hardware auto-detection)
+- **MCP Gateway** ✅ (Unified tool access with 5 servers: Context7, Playwright, Filesystem, Git, Analysis)
+  - **MCP Server Detection**: Automatic detection of Context7 and Playwright MCP servers
+  - **Setup Instructions**: Auto-generated setup instructions when MCP servers are missing
+  - **Status Reporting**: `tapps-agents doctor` reports MCP server configuration status and Beads (bd) status (optional)
+- **YAML Workflow Definitions** ✅ (Parser, executor, artifact tracking, conditional steps, gates)
+  - **YAML-First Architecture** ✅ (Epics 6-10): YAML as single source of truth with strict schema enforcement
+  - **Auto-Generated Artifacts** ✅: Task manifests, Cursor Rules docs
+  - **Dependency-Based Parallelism**: Automatic parallel execution based on step dependencies (no `parallel_tasks`)
+  - **11 Workflow Presets**: rapid-dev (enhance step), full-sdlc (optional enhance before requirements), maintenance, quality, quick-fix, feature-implementation, brownfield-analysis, simple-new-feature, simple-full, simple-improve-quality, simple-fix-issues
+- **Industry Experts Framework** ✅ (Weighted decision-making, domain configuration, expert registry)
+  - **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
+  - **100+ Knowledge Files**: Across 13 knowledge domains
+  - **Configuration-Only Experts**: YAML-based expert definition, no code classes required
+  - **RAG Integration**: Simple file-based and vector-based RAG for knowledge retrieval
+- **Simple Mode** ✅ (15+ orchestrators: build, review, fix, test, explore, refactor, plan-analysis, pr, epic, full, enhance, breakdown, todo, brownfield, validate, resume)
+- **Scale-Adaptive Workflow Selection** ✅ (Project type auto-detection, workflow recommendation)
+- **State Management** ✅ (Advanced workflow state persistence with checkpointing, migration, versioning, resume)
+- **Analytics & Health** ✅ (CLI: `health check`, `health overview`, `health usage dashboard|agents|workflows|system|trends`; performance metrics, trends, system health monitoring)
+- **Governance & Safety** ✅ (Secrets/PII filtering, knowledge ingestion safety)
+- **Comprehensive test suite** ✅ (1200+ unit tests, integration tests, and E2E tests with parallel execution support - see `tests/`)
+
+✅ **Enhancer Agent - Prompt Enhancement Utility (v1.6.0)**
+- **7-Stage Enhancement Pipeline** - Transforms simple prompts into comprehensive, context-aware prompts
+- **Industry Expert Integration** - Automatic domain detection and weighted expert consultation
+- **Multiple Usage Modes** - Full enhancement, quick enhancement, stage-by-stage execution
+- **Session Management** - Resume interrupted enhancements
+- **Multiple Output Formats** - Markdown, JSON, YAML
+- **Workflow integration** - full-sdlc (optional enhance step before requirements), rapid-dev, and Epic story workflows run the enhancer when an `enhance` step is present (EnhancerHandler). AnalystHandler and PlannerHandler consume `enhanced_prompt`/`description` from state.
+- **CLI auto-enhancement** - `auto_enhancement` in config enhances low-quality prompts for implementer, planner, analyst (see [Configuration](docs/CONFIGURATION.md#automatic-prompt-enhancement-auto_enhancement)). `PROMPT_ARGUMENT_MAP` and `commands` control which agent/command pairs are eligible.
+- See [Enhancer Agent Guide](docs/ENHANCER_AGENT.md) for details
+
+🎉 **All Core Framework Features Complete!**
+
+✅ **January 2026 Critical Features Complete:**
+- **Custom Skills Support** ✅ - Create, validate, and integrate custom Skills
+- **State Persistence Configuration** ✅ - Configurable checkpointing and cleanup policies
+- **Governance & Safety Layer** ✅ - Security and safety controls for knowledge ingestion
+- **Epic 20: Complexity Reduction** ✅ - Refactored high-complexity functions (122→C, 114→C, 66→C, 60→C, 64→A/B)
+  - Agent handler extraction using Strategy Pattern
+  - Workflow execution control flow simplification
+  - Zero code duplication between execution paths
+  - See [Complexity Reduction Summary](docs/COMPLEXITY_REDUCTION_EPIC_20.md)
+
+## Upcoming Enhancements (Planned)
+
+### SDLC Quality Engine Improvements
+
+The framework is being enhanced to transform the SDLC from a linear pipeline with score-only gates into a **self-correcting quality engine** that achieves "zero issues" consistently across any codebase.
+
+**Key Improvements:**
+- **Pluggable Validation Layer**: Stack-agnostic validation that adapts to detected project profile and repository signals
+- **Comprehensive Verification**: Expansion of "testing" into verification bundle (tests + linters + config checks + security scans + artifact integrity)
+- **Standardized Issues Manifest**: Machine-actionable issue schema (id, severity, category, evidence, repro, suggested_fix, owner_step) for deterministic remediation
+- **Composite Gating Model**: Gates evaluate issues + verification outcomes, not just numeric scores
+  - Hard fail conditions: critical issues, verification failures, missing artifacts
+  - Soft fail/loopback conditions: high issues above threshold, regression vs baseline, low expert confidence
+- **Bounded Loopback Protocol**: Deterministic remediation with structured fix plans, re-validation, and bounded retries
+- **Traceability Matrix**: Lightweight requirements → stories → validations mapping for completeness verification
+
+**Status**: Design phase - See [SDLC Improvements Analysis](SDLC_ISSUES_AND_IMPROVEMENTS_ANALYSIS.md) and [Epic 1: SDLC Quality Engine](docs/prd/epic-1-sdlc-quality-engine.md)
+
+### Dynamic Expert & RAG Engine
+
+An always-on **Dynamic Knowledge/Expert Orchestrator** that automatically detects project domains, creates and curates experts/knowledge for the current project, and continuously enriches agents with the best available, project-relevant information.
+
+**Key Features:**
+- **Automatic Expert Creation**: Framework-controlled technical experts + project-controlled business/domain experts generated from repo signals
+- **Knowledge Ingestion Pipeline**: Auto-fills RAG from project sources (requirements, architecture docs, ADRs), dependency sources (Context7 KB), and operational sources (CI failures, runtime exceptions)
+- **Expert Engine Runtime**: Continuously detects what domain knowledge is needed, proactively consults the right experts, and populates knowledge stores as agents learn
+- **Governance & Safety**: Do-not-index filters for secrets/PII, prompt-injection handling, retention & scope controls
+- **Observability & Quality Improvement**: Metrics tracking (expert confidence, RAG quality, Context7 KB hit rate) with scheduled KB maintenance jobs
+
+**Status**: Design phase - See [SDLC Improvements Analysis](SDLC_ISSUES_AND_IMPROVEMENTS_ANALYSIS.md) and [Epic 2: Dynamic Expert & RAG Engine](docs/prd/epic-2-dynamic-expert-rag-engine.md)
+
+## Key Features
+
+### Two-Layer Agent Model
+
+| Layer | Type | Purpose | Count |
+|-------|------|---------|-------|
+| **Knowledge** | Industry Experts | Business domain authority | N (per project) |
+| **Execution** | Workflow Agents | SDLC task execution | 14 (fixed) |
+
+### Workflow Agents (14)
+
+- **Planning**: 
+  - **analyst** ✅ - Requirements gathering, stakeholder analysis, tech research, effort estimation, risk assessment, competitive analysis
+  - **planner** ✅ - User story creation, task breakdown, story point estimation, acceptance criteria
+- **Design**: 
+  - **architect** ✅ - System architecture design, design patterns, tech selection, security architecture, boundary definition, architecture diagrams, pattern detection (*detect-patterns)
+  - **designer** ✅ - API design, data model design, UI/UX design, wireframes, design systems
+- **Development**: 
+  - **implementer** ✅ - Code generation, refactoring, file writing with backup support
+  - **debugger** ✅ - Error analysis, stack trace analysis, code execution tracing, root cause identification
+  - **documenter** ✅ - API documentation, README generation, docstring generation, code documentation
+- **Testing**: 
+  - **tester** ✅ - Test generation (unit, integration), test execution, coverage analysis
+- **Quality**: 
+  - **reviewer** ✅ - Code review with 7-category scoring (complexity, security, maintainability, test coverage, performance, structure, devex), actionable feedback with specific issues and line numbers, structured feedback always provided, context-aware quality gates, linting (Ruff), type checking (mypy), duplication detection, security scanning, project analysis, service analysis
+  - **improver** ✅ - Code refactoring, performance optimization, quality improvement suggestions
+- **Operations**: 
+  - **ops** ✅ - Security auditing, compliance checking (GDPR, HIPAA, PCI-DSS), dependency auditing, deployment planning
+- **Orchestration**: 
+  - **orchestrator** ✅ - Workflow coordination, step sequencing, gate decisions, workflow state management
+- **Enhancement**: 
+  - **enhancer** ✅ - 7-stage prompt enhancement pipeline (analysis, requirements, architecture, codebase, quality, strategy, synthesis), quick enhancement, stage-by-stage execution, session management
+- **Evaluation**: 
+  - **evaluator** ✅ - Framework effectiveness analysis, workflow evaluation, improvement recommendations, usage pattern analysis
+
+### Code Scoring System
+
+The Reviewer Agent includes a comprehensive code scoring system with 5 objective metrics and actionable feedback (2026-01-16):
+
+**Enhanced Features:**
+- ✅ **Accurate Test Coverage:** Returns 0.0% when no tests exist (not 5.0-6.0)
+- ✅ **Maintainability Issues:** Specific issues with line numbers, severity, and suggestions
+- ✅ **Structured Feedback:** Always provides actionable feedback (summary, strengths, issues, recommendations, priority)
+- ✅ **Performance Issues:** Performance bottlenecks with line numbers and context
+- ✅ **Accurate Type Checking:** Reflects actual mypy errors (not static 5.0)
+- ✅ **Context-Aware Quality Gates:** Adapts thresholds for new/modified/existing files
+
+The Reviewer Agent scoring system includes:
+
+1. **Complexity Score** (0-10): Cyclomatic complexity analysis using Radon
+2. **Security Score** (0-10): Vulnerability detection using Bandit + heuristics; npm audit for JS/TS
+3. **Maintainability Score** (0-10): Maintainability Index using Radon MI
+4. **Test Coverage Score** (0-10): Coverage data parsing + heuristic; Vitest/Jest/lcov for JS/TS
+5. **Performance Score** (0-10): Static analysis (function size, nesting depth, pattern detection)
+6. **Structure Score** (0-10): Project layout, key files (README, config, tests), conventions
+7. **DevEx Score** (0-10): Docs (AGENTS.md, CLAUDE.md), config, tooling
+
+All metrics are configurable with weighted scoring and quality thresholds.
+
+### Industry Experts
+
+- **Business Domain Experts** (N): Project-specific domain authorities (not technical specialists)
+  - 1:1 mapping: N domains → N experts
+  - Weighted decision-making (Primary: 51%, Others: 49%/(N-1))
+  - RAG integration (simple file-based and vector-based)
+  - Fine-tuning support (LoRA adapters - planned)
+  - Consult-based integration with 6 workflow agents (Architect, Implementer, Reviewer, Tester, Designer, Ops)
+- **Built-in Technical Experts** (16): Framework-controlled domain experts
+  - Security, Performance, Testing, Data Privacy, Accessibility, UX, Code Quality, Software Architecture, DevOps, Documentation, AI Frameworks, Observability, API Design, Cloud Infrastructure, Database, Agent Learning
+  - 100+ knowledge files across 13 knowledge domains
+  - Automatic domain detection and expert consultation
+  - Project profiling for context-aware guidance
+- **Expert Governance**: Secrets/PII filtering, prompt injection handling, knowledge ingestion safety
+
+### CLI Commands
+
+**Top-Level Commands:**
+- `init` - Initialize project (Cursor Rules, Skills, config)
+- `create <description>` - Create new project from natural language description
+- `workflow <preset>` - Run workflow presets (rapid, full, fix, quality, hotfix, etc.)
+- `continuous-bug-fix` - Continuously find and fix bugs from test failures (automated bug fixing loop)
+- `score <file>` - Quick code quality scoring (shortcut for `reviewer score`)
+- `doctor` - Environment diagnostics and validation
+- `cursor verify` - Verify Cursor AI integration components
+- `simple-mode <command>` - Simple Mode management (on, off, status, init, configure, progress, full, build, resume, enhance, breakdown, todo)
+- `health <command>` - Health monitoring (check, dashboard, metrics, trends, usage). Use `health usage dashboard|agents|workflows|system|trends` for analytics (formerly `analytics`).
+- `customize <command>` - Agent customization (init)
+- `skill <command>` - Custom Skills management (validate, template)
+- `install-dev` - Install development tools (ruff, mypy, pytest, pip-audit, pipdeptree)
+- `setup-experts` - Expert setup wizard (init, add, remove, list)
+- `status` - Unified status (active worktrees, progress)
+- `generate-rules` - Generate Cursor Rules from workflow YAML
+
+**Agent Commands** (use `tapps-agents <agent> help` for details):
+- `analyst` - Requirements gathering, stakeholder analysis, tech research, effort estimation, risk assessment
+- `architect` - System design, architecture diagrams, tech selection, security architecture, boundary definition
+- `debugger` - Error debugging, stack trace analysis, code tracing
+- `designer` - API design, data models, UI/UX design, wireframes, design systems
+- `documenter` - Generate documentation, update README, document APIs
+- `enhancer` - Prompt enhancement (full, quick, stage-by-stage, resume)
+- `evaluator` - Framework effectiveness evaluation, workflow evaluation
+- `implementer` - Code generation, refactoring
+- `improver` - Code refactoring, performance optimization
+- `ops` - Security scanning, compliance checks, dependency auditing, deployment planning, bundle analysis (audit-bundle)
+- `orchestrator` - Workflow management, step coordination, gate decisions
+- `planner` - Create plans, user stories, task breakdowns
+- `reviewer` - Code review, scoring, actionable feedback with specific issues, structured feedback, context-aware quality gates, linting, type checking, reports, duplication detection, security scanning, project/service analysis
+- `tester` - Generate and run tests, test coverage
+
+**Workflow State Management:**
+- `workflow state list` - List workflow states
+- `workflow state show <id>` - Show workflow state details
+- `workflow state cleanup` - Cleanup old workflow states
+- `workflow cleanup-branches` - Cleanup workflow worktree branches
+- `workflow resume` - Resume interrupted workflow
+
+**Simple Mode Workflows** (in Cursor chat with `@simple-mode`):
+- `*build <description>` - Complete feature development workflow (7 steps)
+- `*review <file>` - Code quality review with improvements
+- `*fix <file> <description>` - Systematic bug fixing workflow
+- `*test <file>` - Test generation and execution
+- `*explore <query>` - Codebase exploration and navigation
+- `*refactor <file>` - Systematic code modernization with safety checks
+- `*plan-analysis <description>` - Safe read-only code analysis and planning
+- `*pr <title>` - Pull request creation with quality scores
+- `*enhance "prompt"` - Prompt enhancement (EnhancerAgent)
+- `*breakdown "prompt"` - Task breakdown (PlannerAgent)
+- `*todo <bd args>` - Beads-backed todo (e.g. ready, create "Title")
+- `*epic <epic-doc.md>` - Execute Epic documents with dependency resolution
+- `*full <description>` - Full SDLC workflow (9 steps)
+
+## Project Structure
+
+```
+TappsCodingAgents/
+├── requirements/                  # Specification documents (see requirements/README.md)
+│   ├── PROJECT_REQUIREMENTS.md    # Main requirements document
+│   ├── agent_api.md               # Agent API specification
+│   ├── agents.md                  # Agent types specification
+│   ├── model_profiles.yaml        # Model configurations
+│   └── template/                  # Templates and schemas
+│
+├── tapps_agents/                  # Framework source code
+│   ├── agents/                    # All 14 workflow agents
+│   │   ├── reviewer/             # Code review & scoring
+│   │   ├── implementer/          # Code generation
+│   │   ├── tester/               # Test generation
+│   │   └── ...                   # 11 more agents (14 total)
+│   ├── core/                     # Core framework components
+│   ├── context7/                 # Context7 KB integration
+│   ├── experts/                  # Industry experts framework
+│   ├── workflow/                 # Workflow engine
+│   └── mcp/                      # MCP Gateway
+│
+├── .claude/                       # Cursor Skills (canonical; init copies from tapps_agents/resources/claude)
+├── workflows/                     # YAML workflow definitions and presets
+├── examples/                      # Example configurations
+├── docs/                          # Documentation
+│   ├── implementation/           # EPIC/PHASE plans, IMPROVEMENT_PLAN.json
+│   ├── archive/                  # Archived summaries; stories in archive/stories/
+│   ├── releases/                 # Release notes
+│   ├── context7/                 # Context7 integration
+│   └── operations/               # Deployment, release, package distribution
+├── scripts/                       # Utilities (see scripts/README.md)
+├── templates/                     # Agent roles, project types, tech stacks, cursor-rules-template
+└── tests/                         # Test suite
+    ├── unit/                      # Unit tests (fast, isolated)
+    ├── integration/               # Integration tests (with real services)
+    └── e2e/                       # End-to-end tests (see tests/e2e/README.md)
+```
+
+## Documentation
+
+### Getting Started
+- **[Quick Start Guide](docs/guides/QUICK_START.md)** - 🚀 Get started in 10 minutes
+- **[Simple Mode Guide](docs/SIMPLE_MODE_GUIDE.md)** - 🎯 Simple Mode for new users (task-first, natural language)
+- **[Cursor AI Integration Plan 2025](docs/CURSOR_AI_INTEGRATION_PLAN_2025.md)** - Complete integration roadmap (all 7 phases complete)
+- **[Cursor Skills Installation Guide](docs/CURSOR_SKILLS_INSTALLATION_GUIDE.md)** - Install and use Cursor Skills
+- **[Documentation Index](docs/README.md)** - Complete documentation overview
+- **[API Reference](docs/API.md)** - Python API and CLI documentation
+- **[Enhancer Agent Guide](docs/ENHANCER_AGENT.md)** - Prompt enhancement utility documentation
+
+### Complete Command Reference
+- **Cursor Rules**: `.cursor/rules/command-reference.mdc` (installed by `tapps-agents init`) - **Complete command reference with all commands, subcommands, and parameters**
+- **Quick Reference**: `.cursor/rules/quick-reference.mdc` - Quick command reference for common tasks
+- **Agent Capabilities**: `.cursor/rules/agent-capabilities.mdc` - Detailed agent capability descriptions
+- **Simple Mode Guide**: `.cursor/rules/simple-mode.mdc` - Simple Mode workflow documentation
+
+**Note**: After running `tapps-agents init`, all command reference documentation is available in `.cursor/rules/` directory. The `command-reference.mdc` file contains the most comprehensive documentation with all commands, subcommands, parameters, and examples.
+
+### Core Guides
+- **[Architecture Overview](docs/ARCHITECTURE.md)** - System architecture and design
+- **[Configuration Guide](docs/CONFIGURATION.md)** - Complete configuration reference
+- **[Developer Guide](docs/DEVELOPER_GUIDE.md)** - Development setup and workflows
+- **[User Role Templates Guide](docs/USER_ROLE_TEMPLATES_GUIDE.md)** - Customize agents by role (senior-dev, junior-dev, tech-lead, PM, QA)
+- **[Customization Guide](docs/CUSTOMIZATION_GUIDE.md)** - Project-specific agent customizations
+
+### Cursor AI Integration
+- **[Cursor Skills Installation Guide](docs/CURSOR_SKILLS_INSTALLATION_GUIDE.md)** - Install and configure Cursor Skills
+- **[Custom Skills Guide](docs/CUSTOM_SKILLS_GUIDE.md)** - Create, validate, and manage custom Skills
+- **[Cursor Rules Setup Guide](docs/CURSOR_RULES_SETUP.md)** - Cursor Rules setup (auto-generated from YAML workflows)
+- **[Multi-Agent Orchestration Guide](docs/MULTI_AGENT_ORCHESTRATION_GUIDE.md)** - Parallel agent execution
+- **[YAML Workflow Architecture Design](docs/YAML_WORKFLOW_ARCHITECTURE_DESIGN.md)** - YAML-first architecture with generated artifacts
+- **[Unified Cache Architecture](docs/implementation/UNIFIED_CACHE_ARCHITECTURE_PLAN.md)** - Single interface for all caching systems
+- **[Unified Cache Integration Guide](docs/implementation/UNIFIED_CACHE_INTEGRATION_GUIDE.md)** - Using unified cache in agents
+- **[Context7 Cache Optimization](docs/CONTEXT7_CACHE_OPTIMIZATION.md)** - Optimize cache hit rates
+- **[Context7 Security & Privacy](docs/context7/CONTEXT7_SECURITY_PRIVACY.md)** - Security best practices
+- **[Playwright MCP Integration](docs/PLAYWRIGHT_MCP_INTEGRATION.md)** - Browser automation with Playwright MCP server
+### Operations
+- **[Deployment Guide](docs/operations/DEPLOYMENT.md)** - Production deployment instructions
+- **[Troubleshooting Guide](docs/TROUBLESHOOTING.md)** - Common issues and solutions
+- **[Checkpoint & Resume Guide](docs/CHECKPOINT_RESUME_GUIDE.md)** - State persistence and workflow resumption
+- **[Test Suite Documentation](tests/README.md)** - Complete test suite overview and E2E test guide
+- **[E2E Test Suite](tests/e2e/README.md)** - End-to-end test documentation (smoke, workflow, scenario, CLI tests)
+- **[Test Performance Guide](docs/TEST_PERFORMANCE_GUIDE.md)** - Optimize test execution (5-10x faster with parallel execution)
+- **[Hardware Recommendations](docs/HARDWARE_RECOMMENDATIONS.md)** - Optimal computer specs for fast development
+- **[Security Policy](SECURITY.md)** - Security guidelines
+
+### Contributing
+
+**Get help:** [CONTRIBUTING](CONTRIBUTING.md) · [Documentation](docs/README.md)
+
+- **[Contributing Guidelines](CONTRIBUTING.md)** — How to contribute
+- **[Changelog](CHANGELOG.md)** — Version history and changes
+
+### Version Management
+
+When updating the version number, use the automated script to ensure all files are updated consistently:
+
+```powershell
+# Update version to 3.0.4 (or any version)
+.\scripts\update_version.ps1 -Version 3.0.4
+
+# Update core files only (skip documentation)
+.\scripts\update_version.ps1 -Version 3.0.4 -SkipDocs
+```
+
+**What it updates:**
+- ✅ `pyproject.toml` - Package version
+- ✅ `tapps_agents/__init__.py` - Module version
+- ✅ `README.md` - Version badge and references
+- ✅ `docs/README.md` - Documentation version
+- ✅ `docs/API.md` - API version
+- ✅ `docs/ARCHITECTURE.md` - Architecture version
+- ✅ `docs/implementation/IMPROVEMENT_PLAN.json` - Metadata version
+- ✅ Other documentation files with version references
+
+**After running the script:**
+1. Review changes: `git diff`
+2. Update `CHANGELOG.md` with release notes
+3. Commit and push changes
+4. Create git tag: `git tag v3.0.4 && git push origin v3.0.4`
+
+See [Release Guide](docs/operations/RELEASE_GUIDE.md) for complete release process.
+
+### Reference
+- **[Project Requirements](requirements/PROJECT_REQUIREMENTS.md)** - Complete specification
+- **[Technology Stack](requirements/TECH_STACK.md)** - Recommended technologies
+
+## Status
+
+**Phase**: ✅ **All 7 Phases Complete - Cursor AI Integration Plan 2025**  
+**Version**: 3.5.39  
+**Last Updated**: January 2026  
+**Cursor AI Integration**: ✅ Complete (Phases 1-7)  
+**Dependencies**: ✅ Updated to latest 2025 stable versions (pytest 9.x, ruff 0.14.8, mypy 1.19.0, etc.)
+
+### Integration Status
+- ✅ Phase 1: Core Agents to Skills
+- ✅ Phase 2: Quality Tools Integration
+- ✅ Phase 3: Remaining Agents + Advanced Features
+- ✅ Phase 5: Multi-Agent Orchestration
+- ✅ Phase 6: Context7 Optimization + Security
+- ✅ Phase 7: NUC Optimization
+
+See [Cursor AI Integration Plan 2025](docs/CURSOR_AI_INTEGRATION_PLAN_2025.md) for complete details.
+
+## Self-Hosting
+
+This project uses its own framework for development:
+- **5 Industry Experts** configured (AI frameworks, code quality, architecture, DevOps, documentation)
+- **Enhancer Agent** actively used (23+ enhancement sessions)
+- **Context7 Integration** with KB cache
+- **14 Cursor Skills** available in `.claude/skills/` (14 agent skills + simple-mode)
+- **NUC Optimization** enabled for resource-constrained environments
+- Configuration in `.tapps-agents/` directory
+
+See [Self-Hosting Setup](docs/implementation/SELF_HOSTING_SETUP_COMPLETE.md) for details.
+
+## Platform & repository
+
+- **Windows:** Supported (Windows, Linux, macOS). Use UTF-8 for scripts and file I/O. See [Troubleshooting](docs/TROUBLESHOOTING.md) and [CONTRIBUTING](CONTRIBUTING.md) for encoding guidelines.
+- **Repository:** Dependabot, CODEOWNERS, issue/PR templates, GitHub Actions, SECURITY.md. See [CONTRIBUTING](CONTRIBUTING.md) and [.github/](.github/).
+
+## For Framework Developers & Contributors
+
+- **Accuracy:** Agents and skills must report only verified facts. Do not assume success from tests or error handling. See project rules in `.cursor/rules/` and [CONTRIBUTING](CONTRIBUTING.md).
+- **Framework changes:** When modifying `tapps_agents/`, use the Full SDLC workflow: `@simple-mode *full "Implement [description]"` or `tapps-agents simple-mode full --prompt "..." --auto`. See [Framework Development Workflow](docs/FRAMEWORK_DEVELOPMENT_WORKFLOW.md).
+
+## License
+
+See [LICENSE](LICENSE) file for details.