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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (815) hide show
  1. tapps_agents/__init__.py +2 -2
  2. tapps_agents/agents/__init__.py +22 -22
  3. tapps_agents/agents/analyst/__init__.py +5 -5
  4. tapps_agents/agents/architect/__init__.py +5 -5
  5. tapps_agents/agents/architect/agent.py +1033 -1033
  6. tapps_agents/agents/architect/pattern_detector.py +75 -75
  7. tapps_agents/agents/cleanup/__init__.py +7 -7
  8. tapps_agents/agents/cleanup/agent.py +445 -445
  9. tapps_agents/agents/debugger/__init__.py +7 -7
  10. tapps_agents/agents/debugger/agent.py +310 -310
  11. tapps_agents/agents/debugger/error_analyzer.py +437 -437
  12. tapps_agents/agents/designer/__init__.py +5 -5
  13. tapps_agents/agents/designer/agent.py +786 -786
  14. tapps_agents/agents/designer/visual_designer.py +638 -638
  15. tapps_agents/agents/documenter/__init__.py +7 -7
  16. tapps_agents/agents/documenter/agent.py +531 -531
  17. tapps_agents/agents/documenter/doc_generator.py +472 -472
  18. tapps_agents/agents/documenter/doc_validator.py +393 -393
  19. tapps_agents/agents/documenter/framework_doc_updater.py +493 -493
  20. tapps_agents/agents/enhancer/__init__.py +7 -7
  21. tapps_agents/agents/evaluator/__init__.py +7 -7
  22. tapps_agents/agents/evaluator/agent.py +443 -443
  23. tapps_agents/agents/evaluator/priority_evaluator.py +641 -641
  24. tapps_agents/agents/evaluator/quality_analyzer.py +147 -147
  25. tapps_agents/agents/evaluator/report_generator.py +344 -344
  26. tapps_agents/agents/evaluator/usage_analyzer.py +192 -192
  27. tapps_agents/agents/evaluator/workflow_analyzer.py +189 -189
  28. tapps_agents/agents/implementer/__init__.py +7 -7
  29. tapps_agents/agents/implementer/agent.py +798 -798
  30. tapps_agents/agents/implementer/auto_fix.py +1119 -1119
  31. tapps_agents/agents/implementer/code_generator.py +73 -73
  32. tapps_agents/agents/improver/__init__.py +1 -1
  33. tapps_agents/agents/improver/agent.py +753 -753
  34. tapps_agents/agents/ops/__init__.py +1 -1
  35. tapps_agents/agents/ops/agent.py +619 -619
  36. tapps_agents/agents/ops/dependency_analyzer.py +600 -600
  37. tapps_agents/agents/orchestrator/__init__.py +5 -5
  38. tapps_agents/agents/orchestrator/agent.py +522 -522
  39. tapps_agents/agents/planner/__init__.py +7 -7
  40. tapps_agents/agents/planner/agent.py +1127 -1127
  41. tapps_agents/agents/reviewer/__init__.py +24 -24
  42. tapps_agents/agents/reviewer/agent.py +3513 -3513
  43. tapps_agents/agents/reviewer/aggregator.py +213 -213
  44. tapps_agents/agents/reviewer/batch_review.py +448 -448
  45. tapps_agents/agents/reviewer/cache.py +443 -443
  46. tapps_agents/agents/reviewer/context7_enhancer.py +630 -630
  47. tapps_agents/agents/reviewer/context_detector.py +203 -203
  48. tapps_agents/agents/reviewer/docker_compose_validator.py +158 -158
  49. tapps_agents/agents/reviewer/dockerfile_validator.py +176 -176
  50. tapps_agents/agents/reviewer/error_handling.py +126 -126
  51. tapps_agents/agents/reviewer/feedback_generator.py +490 -490
  52. tapps_agents/agents/reviewer/influxdb_validator.py +316 -316
  53. tapps_agents/agents/reviewer/issue_tracking.py +169 -169
  54. tapps_agents/agents/reviewer/library_detector.py +295 -295
  55. tapps_agents/agents/reviewer/library_patterns.py +268 -268
  56. tapps_agents/agents/reviewer/maintainability_scorer.py +593 -593
  57. tapps_agents/agents/reviewer/metric_strategies.py +276 -276
  58. tapps_agents/agents/reviewer/mqtt_validator.py +160 -160
  59. tapps_agents/agents/reviewer/output_enhancer.py +105 -105
  60. tapps_agents/agents/reviewer/pattern_detector.py +241 -241
  61. tapps_agents/agents/reviewer/performance_scorer.py +357 -357
  62. tapps_agents/agents/reviewer/phased_review.py +516 -516
  63. tapps_agents/agents/reviewer/progressive_review.py +435 -435
  64. tapps_agents/agents/reviewer/react_scorer.py +331 -331
  65. tapps_agents/agents/reviewer/score_constants.py +228 -228
  66. tapps_agents/agents/reviewer/score_validator.py +507 -507
  67. tapps_agents/agents/reviewer/scorer_registry.py +373 -373
  68. tapps_agents/agents/reviewer/service_discovery.py +534 -534
  69. tapps_agents/agents/reviewer/tools/parallel_executor.py +581 -581
  70. tapps_agents/agents/reviewer/tools/ruff_grouping.py +250 -250
  71. tapps_agents/agents/reviewer/tools/scoped_mypy.py +284 -284
  72. tapps_agents/agents/reviewer/typescript_scorer.py +1142 -1142
  73. tapps_agents/agents/reviewer/validation.py +208 -208
  74. tapps_agents/agents/reviewer/websocket_validator.py +132 -132
  75. tapps_agents/agents/tester/__init__.py +7 -7
  76. tapps_agents/agents/tester/accessibility_auditor.py +309 -309
  77. tapps_agents/agents/tester/agent.py +1080 -1080
  78. tapps_agents/agents/tester/batch_generator.py +54 -54
  79. tapps_agents/agents/tester/context_learner.py +51 -51
  80. tapps_agents/agents/tester/coverage_analyzer.py +386 -386
  81. tapps_agents/agents/tester/coverage_test_generator.py +290 -290
  82. tapps_agents/agents/tester/debug_enhancer.py +238 -238
  83. tapps_agents/agents/tester/device_emulator.py +241 -241
  84. tapps_agents/agents/tester/integration_generator.py +62 -62
  85. tapps_agents/agents/tester/network_recorder.py +300 -300
  86. tapps_agents/agents/tester/performance_monitor.py +320 -320
  87. tapps_agents/agents/tester/test_fixer.py +316 -316
  88. tapps_agents/agents/tester/test_generator.py +632 -632
  89. tapps_agents/agents/tester/trace_manager.py +234 -234
  90. tapps_agents/agents/tester/visual_regression.py +291 -291
  91. tapps_agents/analysis/pattern_detector.py +36 -36
  92. tapps_agents/beads/hydration.py +213 -213
  93. tapps_agents/beads/parse.py +32 -32
  94. tapps_agents/beads/specs.py +206 -206
  95. tapps_agents/cli/__init__.py +9 -9
  96. tapps_agents/cli/__main__.py +8 -8
  97. tapps_agents/cli/base.py +478 -478
  98. tapps_agents/cli/command_classifier.py +72 -72
  99. tapps_agents/cli/commands/__init__.py +2 -2
  100. tapps_agents/cli/commands/analyst.py +173 -173
  101. tapps_agents/cli/commands/architect.py +109 -109
  102. tapps_agents/cli/commands/cleanup_agent.py +92 -92
  103. tapps_agents/cli/commands/common.py +126 -126
  104. tapps_agents/cli/commands/debugger.py +90 -90
  105. tapps_agents/cli/commands/designer.py +112 -112
  106. tapps_agents/cli/commands/documenter.py +136 -136
  107. tapps_agents/cli/commands/enhancer.py +110 -110
  108. tapps_agents/cli/commands/evaluator.py +255 -255
  109. tapps_agents/cli/commands/implementer.py +301 -301
  110. tapps_agents/cli/commands/improver.py +91 -91
  111. tapps_agents/cli/commands/knowledge.py +111 -111
  112. tapps_agents/cli/commands/learning.py +172 -172
  113. tapps_agents/cli/commands/observability.py +283 -283
  114. tapps_agents/cli/commands/ops.py +135 -135
  115. tapps_agents/cli/commands/orchestrator.py +116 -116
  116. tapps_agents/cli/commands/planner.py +237 -237
  117. tapps_agents/cli/commands/reviewer.py +1872 -1872
  118. tapps_agents/cli/commands/status.py +285 -285
  119. tapps_agents/cli/commands/task.py +227 -227
  120. tapps_agents/cli/commands/tester.py +191 -191
  121. tapps_agents/cli/feedback.py +936 -936
  122. tapps_agents/cli/formatters.py +608 -608
  123. tapps_agents/cli/help/__init__.py +7 -7
  124. tapps_agents/cli/help/static_help.py +425 -425
  125. tapps_agents/cli/network_detection.py +110 -110
  126. tapps_agents/cli/output_compactor.py +274 -274
  127. tapps_agents/cli/parsers/__init__.py +2 -2
  128. tapps_agents/cli/parsers/analyst.py +186 -186
  129. tapps_agents/cli/parsers/architect.py +167 -167
  130. tapps_agents/cli/parsers/cleanup_agent.py +228 -228
  131. tapps_agents/cli/parsers/debugger.py +116 -116
  132. tapps_agents/cli/parsers/designer.py +182 -182
  133. tapps_agents/cli/parsers/documenter.py +134 -134
  134. tapps_agents/cli/parsers/enhancer.py +113 -113
  135. tapps_agents/cli/parsers/evaluator.py +213 -213
  136. tapps_agents/cli/parsers/implementer.py +168 -168
  137. tapps_agents/cli/parsers/improver.py +132 -132
  138. tapps_agents/cli/parsers/ops.py +159 -159
  139. tapps_agents/cli/parsers/orchestrator.py +98 -98
  140. tapps_agents/cli/parsers/planner.py +145 -145
  141. tapps_agents/cli/parsers/reviewer.py +462 -462
  142. tapps_agents/cli/parsers/tester.py +124 -124
  143. tapps_agents/cli/progress_heartbeat.py +254 -254
  144. tapps_agents/cli/streaming_progress.py +336 -336
  145. tapps_agents/cli/utils/__init__.py +6 -6
  146. tapps_agents/cli/utils/agent_lifecycle.py +48 -48
  147. tapps_agents/cli/utils/error_formatter.py +82 -82
  148. tapps_agents/cli/utils/error_recovery.py +188 -188
  149. tapps_agents/cli/utils/output_handler.py +59 -59
  150. tapps_agents/cli/utils/prompt_enhancer.py +319 -319
  151. tapps_agents/cli/validators/__init__.py +9 -9
  152. tapps_agents/cli/validators/command_validator.py +81 -81
  153. tapps_agents/context7/__init__.py +112 -112
  154. tapps_agents/context7/agent_integration.py +869 -869
  155. tapps_agents/context7/analytics.py +382 -382
  156. tapps_agents/context7/analytics_dashboard.py +299 -299
  157. tapps_agents/context7/async_cache.py +681 -681
  158. tapps_agents/context7/backup_client.py +958 -958
  159. tapps_agents/context7/cache_locking.py +194 -194
  160. tapps_agents/context7/cache_metadata.py +214 -214
  161. tapps_agents/context7/cache_prewarm.py +488 -488
  162. tapps_agents/context7/cache_structure.py +168 -168
  163. tapps_agents/context7/cache_warming.py +604 -604
  164. tapps_agents/context7/circuit_breaker.py +376 -376
  165. tapps_agents/context7/cleanup.py +461 -461
  166. tapps_agents/context7/commands.py +858 -858
  167. tapps_agents/context7/credential_validation.py +276 -276
  168. tapps_agents/context7/cross_reference_resolver.py +168 -168
  169. tapps_agents/context7/cross_references.py +424 -424
  170. tapps_agents/context7/doc_manager.py +225 -225
  171. tapps_agents/context7/fuzzy_matcher.py +369 -369
  172. tapps_agents/context7/kb_cache.py +404 -404
  173. tapps_agents/context7/language_detector.py +219 -219
  174. tapps_agents/context7/library_detector.py +725 -725
  175. tapps_agents/context7/lookup.py +738 -738
  176. tapps_agents/context7/metadata.py +258 -258
  177. tapps_agents/context7/refresh_queue.py +300 -300
  178. tapps_agents/context7/security.py +373 -373
  179. tapps_agents/context7/staleness_policies.py +278 -278
  180. tapps_agents/context7/tiles_integration.py +47 -47
  181. tapps_agents/continuous_bug_fix/__init__.py +20 -20
  182. tapps_agents/continuous_bug_fix/bug_finder.py +306 -306
  183. tapps_agents/continuous_bug_fix/bug_fix_coordinator.py +177 -177
  184. tapps_agents/continuous_bug_fix/commit_manager.py +178 -178
  185. tapps_agents/continuous_bug_fix/continuous_bug_fixer.py +322 -322
  186. tapps_agents/continuous_bug_fix/proactive_bug_finder.py +285 -285
  187. tapps_agents/core/__init__.py +298 -298
  188. tapps_agents/core/adaptive_cache_config.py +432 -432
  189. tapps_agents/core/agent_base.py +647 -647
  190. tapps_agents/core/agent_cache.py +466 -466
  191. tapps_agents/core/agent_learning.py +1865 -1865
  192. tapps_agents/core/analytics_dashboard.py +563 -563
  193. tapps_agents/core/analytics_enhancements.py +597 -597
  194. tapps_agents/core/anonymization.py +274 -274
  195. tapps_agents/core/ast_parser.py +228 -228
  196. tapps_agents/core/async_file_ops.py +402 -402
  197. tapps_agents/core/best_practice_consultant.py +299 -299
  198. tapps_agents/core/brownfield_analyzer.py +299 -299
  199. tapps_agents/core/brownfield_review.py +541 -541
  200. tapps_agents/core/browser_controller.py +513 -513
  201. tapps_agents/core/capability_registry.py +418 -418
  202. tapps_agents/core/change_impact_analyzer.py +190 -190
  203. tapps_agents/core/checkpoint_manager.py +377 -377
  204. tapps_agents/core/code_generator.py +329 -329
  205. tapps_agents/core/code_validator.py +276 -276
  206. tapps_agents/core/command_registry.py +327 -327
  207. tapps_agents/core/context_gathering/__init__.py +2 -2
  208. tapps_agents/core/context_gathering/repository_explorer.py +28 -28
  209. tapps_agents/core/context_intelligence/__init__.py +2 -2
  210. tapps_agents/core/context_intelligence/relevance_scorer.py +24 -24
  211. tapps_agents/core/context_intelligence/token_budget_manager.py +27 -27
  212. tapps_agents/core/context_manager.py +240 -240
  213. tapps_agents/core/cursor_feedback_monitor.py +146 -146
  214. tapps_agents/core/cursor_verification.py +290 -290
  215. tapps_agents/core/customization_loader.py +280 -280
  216. tapps_agents/core/customization_schema.py +260 -260
  217. tapps_agents/core/customization_template.py +238 -238
  218. tapps_agents/core/debug_logger.py +124 -124
  219. tapps_agents/core/design_validator.py +298 -298
  220. tapps_agents/core/diagram_generator.py +226 -226
  221. tapps_agents/core/docker_utils.py +232 -232
  222. tapps_agents/core/document_generator.py +617 -617
  223. tapps_agents/core/domain_detector.py +30 -30
  224. tapps_agents/core/error_envelope.py +454 -454
  225. tapps_agents/core/error_handler.py +270 -270
  226. tapps_agents/core/estimation_tracker.py +189 -189
  227. tapps_agents/core/eval_prompt_engine.py +116 -116
  228. tapps_agents/core/evaluation_base.py +119 -119
  229. tapps_agents/core/evaluation_models.py +320 -320
  230. tapps_agents/core/evaluation_orchestrator.py +225 -225
  231. tapps_agents/core/evaluators/__init__.py +7 -7
  232. tapps_agents/core/evaluators/architectural_evaluator.py +205 -205
  233. tapps_agents/core/evaluators/behavioral_evaluator.py +160 -160
  234. tapps_agents/core/evaluators/performance_profile_evaluator.py +160 -160
  235. tapps_agents/core/evaluators/security_posture_evaluator.py +148 -148
  236. tapps_agents/core/evaluators/spec_compliance_evaluator.py +181 -181
  237. tapps_agents/core/exceptions.py +107 -107
  238. tapps_agents/core/expert_config_generator.py +293 -293
  239. tapps_agents/core/export_schema.py +202 -202
  240. tapps_agents/core/external_feedback_models.py +102 -102
  241. tapps_agents/core/external_feedback_storage.py +213 -213
  242. tapps_agents/core/fallback_strategy.py +314 -314
  243. tapps_agents/core/feedback_analyzer.py +162 -162
  244. tapps_agents/core/feedback_collector.py +178 -178
  245. tapps_agents/core/git_operations.py +445 -445
  246. tapps_agents/core/hardware_profiler.py +151 -151
  247. tapps_agents/core/instructions.py +324 -324
  248. tapps_agents/core/io_guardrails.py +69 -69
  249. tapps_agents/core/issue_manifest.py +249 -249
  250. tapps_agents/core/issue_schema.py +139 -139
  251. tapps_agents/core/json_utils.py +128 -128
  252. tapps_agents/core/knowledge_graph.py +446 -446
  253. tapps_agents/core/language_detector.py +296 -296
  254. tapps_agents/core/learning_confidence.py +242 -242
  255. tapps_agents/core/learning_dashboard.py +246 -246
  256. tapps_agents/core/learning_decision.py +384 -384
  257. tapps_agents/core/learning_explainability.py +578 -578
  258. tapps_agents/core/learning_export.py +287 -287
  259. tapps_agents/core/learning_integration.py +228 -228
  260. tapps_agents/core/llm_behavior.py +232 -232
  261. tapps_agents/core/long_duration_support.py +786 -786
  262. tapps_agents/core/mcp_setup.py +106 -106
  263. tapps_agents/core/memory_integration.py +396 -396
  264. tapps_agents/core/meta_learning.py +666 -666
  265. tapps_agents/core/module_path_sanitizer.py +199 -199
  266. tapps_agents/core/multi_agent_orchestrator.py +382 -382
  267. tapps_agents/core/network_errors.py +125 -125
  268. tapps_agents/core/nfr_validator.py +336 -336
  269. tapps_agents/core/offline_mode.py +158 -158
  270. tapps_agents/core/output_contracts.py +300 -300
  271. tapps_agents/core/output_formatter.py +300 -300
  272. tapps_agents/core/path_normalizer.py +174 -174
  273. tapps_agents/core/path_validator.py +322 -322
  274. tapps_agents/core/pattern_library.py +250 -250
  275. tapps_agents/core/performance_benchmark.py +301 -301
  276. tapps_agents/core/performance_monitor.py +184 -184
  277. tapps_agents/core/playwright_mcp_controller.py +771 -771
  278. tapps_agents/core/policy_loader.py +135 -135
  279. tapps_agents/core/progress.py +166 -166
  280. tapps_agents/core/project_profile.py +354 -354
  281. tapps_agents/core/project_type_detector.py +454 -454
  282. tapps_agents/core/prompt_base.py +223 -223
  283. tapps_agents/core/prompt_learning/__init__.py +2 -2
  284. tapps_agents/core/prompt_learning/learning_loop.py +24 -24
  285. tapps_agents/core/prompt_learning/project_prompt_store.py +25 -25
  286. tapps_agents/core/prompt_learning/skills_prompt_analyzer.py +35 -35
  287. tapps_agents/core/prompt_optimization/__init__.py +6 -6
  288. tapps_agents/core/prompt_optimization/ab_tester.py +114 -114
  289. tapps_agents/core/prompt_optimization/correlation_analyzer.py +160 -160
  290. tapps_agents/core/prompt_optimization/progressive_refiner.py +129 -129
  291. tapps_agents/core/prompt_optimization/prompt_library.py +37 -37
  292. tapps_agents/core/requirements_evaluator.py +431 -431
  293. tapps_agents/core/resource_aware_executor.py +449 -449
  294. tapps_agents/core/resource_monitor.py +343 -343
  295. tapps_agents/core/resume_handler.py +298 -298
  296. tapps_agents/core/retry_handler.py +197 -197
  297. tapps_agents/core/review_checklists.py +479 -479
  298. tapps_agents/core/role_loader.py +201 -201
  299. tapps_agents/core/role_template_loader.py +201 -201
  300. tapps_agents/core/runtime_mode.py +60 -60
  301. tapps_agents/core/security_scanner.py +342 -342
  302. tapps_agents/core/skill_agent_registry.py +194 -194
  303. tapps_agents/core/skill_integration.py +208 -208
  304. tapps_agents/core/skill_loader.py +492 -492
  305. tapps_agents/core/skill_template.py +341 -341
  306. tapps_agents/core/skill_validator.py +478 -478
  307. tapps_agents/core/stack_analyzer.py +35 -35
  308. tapps_agents/core/startup.py +174 -174
  309. tapps_agents/core/storage_manager.py +397 -397
  310. tapps_agents/core/storage_models.py +166 -166
  311. tapps_agents/core/story_evaluator.py +410 -410
  312. tapps_agents/core/subprocess_utils.py +170 -170
  313. tapps_agents/core/task_duration.py +296 -296
  314. tapps_agents/core/task_memory.py +582 -582
  315. tapps_agents/core/task_state.py +226 -226
  316. tapps_agents/core/tech_stack_priorities.py +208 -208
  317. tapps_agents/core/temp_directory.py +194 -194
  318. tapps_agents/core/template_merger.py +600 -600
  319. tapps_agents/core/template_selector.py +280 -280
  320. tapps_agents/core/test_generator.py +286 -286
  321. tapps_agents/core/tiered_context.py +253 -253
  322. tapps_agents/core/token_monitor.py +345 -345
  323. tapps_agents/core/traceability.py +254 -254
  324. tapps_agents/core/trajectory_tracker.py +50 -50
  325. tapps_agents/core/unicode_safe.py +143 -143
  326. tapps_agents/core/unified_cache_config.py +170 -170
  327. tapps_agents/core/unified_state.py +324 -324
  328. tapps_agents/core/validate_cursor_setup.py +237 -237
  329. tapps_agents/core/validation_registry.py +136 -136
  330. tapps_agents/core/validators/__init__.py +4 -4
  331. tapps_agents/core/validators/python_validator.py +87 -87
  332. tapps_agents/core/verification_agent.py +90 -90
  333. tapps_agents/core/visual_feedback.py +644 -644
  334. tapps_agents/core/workflow_validator.py +197 -197
  335. tapps_agents/core/worktree.py +367 -367
  336. tapps_agents/docker/__init__.py +10 -10
  337. tapps_agents/docker/analyzer.py +186 -186
  338. tapps_agents/docker/debugger.py +229 -229
  339. tapps_agents/docker/error_patterns.py +216 -216
  340. tapps_agents/epic/__init__.py +22 -22
  341. tapps_agents/epic/beads_sync.py +115 -115
  342. tapps_agents/epic/markdown_sync.py +105 -105
  343. tapps_agents/epic/models.py +96 -96
  344. tapps_agents/experts/__init__.py +163 -163
  345. tapps_agents/experts/agent_integration.py +243 -243
  346. tapps_agents/experts/auto_generator.py +331 -331
  347. tapps_agents/experts/base_expert.py +536 -536
  348. tapps_agents/experts/builtin_registry.py +261 -261
  349. tapps_agents/experts/business_metrics.py +565 -565
  350. tapps_agents/experts/cache.py +266 -266
  351. tapps_agents/experts/confidence_breakdown.py +306 -306
  352. tapps_agents/experts/confidence_calculator.py +336 -336
  353. tapps_agents/experts/confidence_metrics.py +236 -236
  354. tapps_agents/experts/domain_config.py +311 -311
  355. tapps_agents/experts/domain_detector.py +550 -550
  356. tapps_agents/experts/domain_utils.py +84 -84
  357. tapps_agents/experts/expert_config.py +113 -113
  358. tapps_agents/experts/expert_engine.py +465 -465
  359. tapps_agents/experts/expert_registry.py +744 -744
  360. tapps_agents/experts/expert_synthesizer.py +70 -70
  361. tapps_agents/experts/governance.py +197 -197
  362. tapps_agents/experts/history_logger.py +312 -312
  363. tapps_agents/experts/knowledge/README.md +180 -180
  364. tapps_agents/experts/knowledge/accessibility/accessible-forms.md +331 -331
  365. tapps_agents/experts/knowledge/accessibility/aria-patterns.md +344 -344
  366. tapps_agents/experts/knowledge/accessibility/color-contrast.md +285 -285
  367. tapps_agents/experts/knowledge/accessibility/keyboard-navigation.md +332 -332
  368. tapps_agents/experts/knowledge/accessibility/screen-readers.md +282 -282
  369. tapps_agents/experts/knowledge/accessibility/semantic-html.md +355 -355
  370. tapps_agents/experts/knowledge/accessibility/testing-accessibility.md +369 -369
  371. tapps_agents/experts/knowledge/accessibility/wcag-2.1.md +296 -296
  372. tapps_agents/experts/knowledge/accessibility/wcag-2.2.md +211 -211
  373. tapps_agents/experts/knowledge/agent-learning/best-practices.md +715 -715
  374. tapps_agents/experts/knowledge/agent-learning/pattern-extraction.md +282 -282
  375. tapps_agents/experts/knowledge/agent-learning/prompt-optimization.md +320 -320
  376. tapps_agents/experts/knowledge/ai-frameworks/model-optimization.md +90 -90
  377. tapps_agents/experts/knowledge/ai-frameworks/openvino-patterns.md +260 -260
  378. tapps_agents/experts/knowledge/api-design-integration/api-gateway-patterns.md +309 -309
  379. tapps_agents/experts/knowledge/api-design-integration/api-security-patterns.md +521 -521
  380. tapps_agents/experts/knowledge/api-design-integration/api-versioning.md +421 -421
  381. tapps_agents/experts/knowledge/api-design-integration/async-protocol-patterns.md +61 -61
  382. tapps_agents/experts/knowledge/api-design-integration/contract-testing.md +221 -221
  383. tapps_agents/experts/knowledge/api-design-integration/external-api-integration.md +489 -489
  384. tapps_agents/experts/knowledge/api-design-integration/fastapi-patterns.md +360 -360
  385. tapps_agents/experts/knowledge/api-design-integration/fastapi-testing.md +262 -262
  386. tapps_agents/experts/knowledge/api-design-integration/graphql-patterns.md +582 -582
  387. tapps_agents/experts/knowledge/api-design-integration/grpc-best-practices.md +499 -499
  388. tapps_agents/experts/knowledge/api-design-integration/mqtt-patterns.md +455 -455
  389. tapps_agents/experts/knowledge/api-design-integration/rate-limiting.md +507 -507
  390. tapps_agents/experts/knowledge/api-design-integration/restful-api-design.md +618 -618
  391. tapps_agents/experts/knowledge/api-design-integration/websocket-patterns.md +480 -480
  392. tapps_agents/experts/knowledge/cloud-infrastructure/cloud-native-patterns.md +175 -175
  393. tapps_agents/experts/knowledge/cloud-infrastructure/container-health-checks.md +261 -261
  394. tapps_agents/experts/knowledge/cloud-infrastructure/containerization.md +222 -222
  395. tapps_agents/experts/knowledge/cloud-infrastructure/cost-optimization.md +122 -122
  396. tapps_agents/experts/knowledge/cloud-infrastructure/disaster-recovery.md +153 -153
  397. tapps_agents/experts/knowledge/cloud-infrastructure/dockerfile-patterns.md +285 -285
  398. tapps_agents/experts/knowledge/cloud-infrastructure/infrastructure-as-code.md +187 -187
  399. tapps_agents/experts/knowledge/cloud-infrastructure/kubernetes-patterns.md +253 -253
  400. tapps_agents/experts/knowledge/cloud-infrastructure/multi-cloud-strategies.md +155 -155
  401. tapps_agents/experts/knowledge/cloud-infrastructure/serverless-architecture.md +200 -200
  402. tapps_agents/experts/knowledge/code-quality-analysis/README.md +16 -16
  403. tapps_agents/experts/knowledge/code-quality-analysis/code-metrics.md +137 -137
  404. tapps_agents/experts/knowledge/code-quality-analysis/complexity-analysis.md +181 -181
  405. tapps_agents/experts/knowledge/code-quality-analysis/technical-debt-patterns.md +191 -191
  406. tapps_agents/experts/knowledge/data-privacy-compliance/anonymization.md +313 -313
  407. tapps_agents/experts/knowledge/data-privacy-compliance/ccpa.md +255 -255
  408. tapps_agents/experts/knowledge/data-privacy-compliance/consent-management.md +282 -282
  409. tapps_agents/experts/knowledge/data-privacy-compliance/data-minimization.md +275 -275
  410. tapps_agents/experts/knowledge/data-privacy-compliance/data-retention.md +297 -297
  411. tapps_agents/experts/knowledge/data-privacy-compliance/data-subject-rights.md +383 -383
  412. tapps_agents/experts/knowledge/data-privacy-compliance/encryption-privacy.md +285 -285
  413. tapps_agents/experts/knowledge/data-privacy-compliance/gdpr.md +344 -344
  414. tapps_agents/experts/knowledge/data-privacy-compliance/hipaa.md +385 -385
  415. tapps_agents/experts/knowledge/data-privacy-compliance/privacy-by-design.md +280 -280
  416. tapps_agents/experts/knowledge/database-data-management/acid-vs-cap.md +164 -164
  417. tapps_agents/experts/knowledge/database-data-management/backup-and-recovery.md +182 -182
  418. tapps_agents/experts/knowledge/database-data-management/data-modeling.md +172 -172
  419. tapps_agents/experts/knowledge/database-data-management/database-design.md +187 -187
  420. tapps_agents/experts/knowledge/database-data-management/flux-query-optimization.md +342 -342
  421. tapps_agents/experts/knowledge/database-data-management/influxdb-connection-patterns.md +432 -432
  422. tapps_agents/experts/knowledge/database-data-management/influxdb-patterns.md +442 -442
  423. tapps_agents/experts/knowledge/database-data-management/migration-strategies.md +216 -216
  424. tapps_agents/experts/knowledge/database-data-management/nosql-patterns.md +259 -259
  425. tapps_agents/experts/knowledge/database-data-management/scalability-patterns.md +184 -184
  426. tapps_agents/experts/knowledge/database-data-management/sql-optimization.md +175 -175
  427. tapps_agents/experts/knowledge/database-data-management/time-series-modeling.md +444 -444
  428. tapps_agents/experts/knowledge/development-workflow/README.md +16 -16
  429. tapps_agents/experts/knowledge/development-workflow/automation-best-practices.md +216 -216
  430. tapps_agents/experts/knowledge/development-workflow/build-strategies.md +198 -198
  431. tapps_agents/experts/knowledge/development-workflow/deployment-patterns.md +205 -205
  432. tapps_agents/experts/knowledge/development-workflow/git-workflows.md +205 -205
  433. tapps_agents/experts/knowledge/documentation-knowledge-management/README.md +16 -16
  434. tapps_agents/experts/knowledge/documentation-knowledge-management/api-documentation-patterns.md +231 -231
  435. tapps_agents/experts/knowledge/documentation-knowledge-management/documentation-standards.md +191 -191
  436. tapps_agents/experts/knowledge/documentation-knowledge-management/knowledge-management.md +171 -171
  437. tapps_agents/experts/knowledge/documentation-knowledge-management/technical-writing-guide.md +192 -192
  438. tapps_agents/experts/knowledge/observability-monitoring/alerting-patterns.md +461 -461
  439. tapps_agents/experts/knowledge/observability-monitoring/apm-tools.md +459 -459
  440. tapps_agents/experts/knowledge/observability-monitoring/distributed-tracing.md +367 -367
  441. tapps_agents/experts/knowledge/observability-monitoring/logging-strategies.md +478 -478
  442. tapps_agents/experts/knowledge/observability-monitoring/metrics-and-monitoring.md +510 -510
  443. tapps_agents/experts/knowledge/observability-monitoring/observability-best-practices.md +492 -492
  444. tapps_agents/experts/knowledge/observability-monitoring/open-telemetry.md +573 -573
  445. tapps_agents/experts/knowledge/observability-monitoring/slo-sli-sla.md +419 -419
  446. tapps_agents/experts/knowledge/performance/anti-patterns.md +284 -284
  447. tapps_agents/experts/knowledge/performance/api-performance.md +256 -256
  448. tapps_agents/experts/knowledge/performance/caching.md +327 -327
  449. tapps_agents/experts/knowledge/performance/database-performance.md +252 -252
  450. tapps_agents/experts/knowledge/performance/optimization-patterns.md +327 -327
  451. tapps_agents/experts/knowledge/performance/profiling.md +297 -297
  452. tapps_agents/experts/knowledge/performance/resource-management.md +293 -293
  453. tapps_agents/experts/knowledge/performance/scalability.md +306 -306
  454. tapps_agents/experts/knowledge/security/owasp-top10.md +209 -209
  455. tapps_agents/experts/knowledge/security/secure-coding-practices.md +207 -207
  456. tapps_agents/experts/knowledge/security/threat-modeling.md +220 -220
  457. tapps_agents/experts/knowledge/security/vulnerability-patterns.md +342 -342
  458. tapps_agents/experts/knowledge/software-architecture/docker-compose-patterns.md +314 -314
  459. tapps_agents/experts/knowledge/software-architecture/microservices-patterns.md +379 -379
  460. tapps_agents/experts/knowledge/software-architecture/service-communication.md +316 -316
  461. tapps_agents/experts/knowledge/testing/best-practices.md +310 -310
  462. tapps_agents/experts/knowledge/testing/coverage-analysis.md +293 -293
  463. tapps_agents/experts/knowledge/testing/mocking.md +256 -256
  464. tapps_agents/experts/knowledge/testing/test-automation.md +276 -276
  465. tapps_agents/experts/knowledge/testing/test-data.md +271 -271
  466. tapps_agents/experts/knowledge/testing/test-design-patterns.md +280 -280
  467. tapps_agents/experts/knowledge/testing/test-maintenance.md +236 -236
  468. tapps_agents/experts/knowledge/testing/test-strategies.md +311 -311
  469. tapps_agents/experts/knowledge/user-experience/information-architecture.md +325 -325
  470. tapps_agents/experts/knowledge/user-experience/interaction-design.md +363 -363
  471. tapps_agents/experts/knowledge/user-experience/prototyping.md +293 -293
  472. tapps_agents/experts/knowledge/user-experience/usability-heuristics.md +337 -337
  473. tapps_agents/experts/knowledge/user-experience/usability-testing.md +311 -311
  474. tapps_agents/experts/knowledge/user-experience/user-journeys.md +296 -296
  475. tapps_agents/experts/knowledge/user-experience/user-research.md +373 -373
  476. tapps_agents/experts/knowledge/user-experience/ux-principles.md +340 -340
  477. tapps_agents/experts/knowledge_freshness.py +321 -321
  478. tapps_agents/experts/knowledge_ingestion.py +438 -438
  479. tapps_agents/experts/knowledge_need_detector.py +93 -93
  480. tapps_agents/experts/knowledge_validator.py +382 -382
  481. tapps_agents/experts/observability.py +440 -440
  482. tapps_agents/experts/passive_notifier.py +238 -238
  483. tapps_agents/experts/proactive_orchestrator.py +32 -32
  484. tapps_agents/experts/rag_chunker.py +205 -205
  485. tapps_agents/experts/rag_embedder.py +152 -152
  486. tapps_agents/experts/rag_evaluation.py +299 -299
  487. tapps_agents/experts/rag_index.py +303 -303
  488. tapps_agents/experts/rag_metrics.py +293 -293
  489. tapps_agents/experts/rag_safety.py +263 -263
  490. tapps_agents/experts/report_generator.py +296 -296
  491. tapps_agents/experts/setup_wizard.py +441 -441
  492. tapps_agents/experts/simple_rag.py +431 -431
  493. tapps_agents/experts/vector_rag.py +354 -354
  494. tapps_agents/experts/weight_distributor.py +304 -304
  495. tapps_agents/health/__init__.py +24 -24
  496. tapps_agents/health/base.py +75 -75
  497. tapps_agents/health/checks/__init__.py +22 -22
  498. tapps_agents/health/checks/automation.py +127 -127
  499. tapps_agents/health/checks/context7_cache.py +210 -210
  500. tapps_agents/health/checks/environment.py +116 -116
  501. tapps_agents/health/checks/execution.py +170 -170
  502. tapps_agents/health/checks/knowledge_base.py +187 -187
  503. tapps_agents/health/checks/outcomes.backup_20260204_064058.py +324 -0
  504. tapps_agents/health/checks/outcomes.backup_20260204_064256.py +324 -0
  505. tapps_agents/health/checks/outcomes.backup_20260204_064600.py +324 -0
  506. tapps_agents/health/checks/outcomes.py +324 -324
  507. tapps_agents/health/collector.py +280 -280
  508. tapps_agents/health/dashboard.py +137 -137
  509. tapps_agents/health/metrics.py +151 -151
  510. tapps_agents/health/registry.py +166 -166
  511. tapps_agents/hooks/__init__.py +33 -33
  512. tapps_agents/hooks/config.py +140 -140
  513. tapps_agents/hooks/events.py +135 -135
  514. tapps_agents/hooks/executor.py +128 -128
  515. tapps_agents/hooks/manager.py +143 -143
  516. tapps_agents/integration/__init__.py +8 -8
  517. tapps_agents/integration/service_integrator.py +121 -121
  518. tapps_agents/integrations/__init__.py +10 -10
  519. tapps_agents/integrations/clawdbot.py +525 -525
  520. tapps_agents/integrations/memory_bridge.py +356 -356
  521. tapps_agents/mcp/__init__.py +18 -18
  522. tapps_agents/mcp/gateway.py +112 -112
  523. tapps_agents/mcp/servers/__init__.py +13 -13
  524. tapps_agents/mcp/servers/analysis.py +204 -204
  525. tapps_agents/mcp/servers/context7.py +198 -198
  526. tapps_agents/mcp/servers/filesystem.py +218 -218
  527. tapps_agents/mcp/servers/git.py +201 -201
  528. tapps_agents/mcp/tool_registry.py +115 -115
  529. tapps_agents/quality/__init__.py +54 -54
  530. tapps_agents/quality/coverage_analyzer.py +379 -379
  531. tapps_agents/quality/enforcement.py +82 -82
  532. tapps_agents/quality/gates/__init__.py +37 -37
  533. tapps_agents/quality/gates/approval_gate.py +255 -255
  534. tapps_agents/quality/gates/base.py +84 -84
  535. tapps_agents/quality/gates/exceptions.py +43 -43
  536. tapps_agents/quality/gates/policy_gate.py +195 -195
  537. tapps_agents/quality/gates/registry.py +239 -239
  538. tapps_agents/quality/gates/security_gate.py +156 -156
  539. tapps_agents/quality/quality_gates.py +369 -369
  540. tapps_agents/quality/secret_scanner.py +335 -335
  541. tapps_agents/resources/__init__.py +5 -0
  542. tapps_agents/resources/claude/__init__.py +1 -0
  543. tapps_agents/resources/claude/commands/README.md +156 -0
  544. tapps_agents/resources/claude/commands/__init__.py +1 -0
  545. tapps_agents/resources/claude/commands/build-fix.md +22 -0
  546. tapps_agents/resources/claude/commands/build.md +77 -0
  547. tapps_agents/resources/claude/commands/debug.md +53 -0
  548. tapps_agents/resources/claude/commands/design.md +68 -0
  549. tapps_agents/resources/claude/commands/docs.md +53 -0
  550. tapps_agents/resources/claude/commands/e2e.md +22 -0
  551. tapps_agents/resources/claude/commands/fix.md +54 -0
  552. tapps_agents/resources/claude/commands/implement.md +53 -0
  553. tapps_agents/resources/claude/commands/improve.md +53 -0
  554. tapps_agents/resources/claude/commands/library-docs.md +64 -0
  555. tapps_agents/resources/claude/commands/lint.md +52 -0
  556. tapps_agents/resources/claude/commands/plan.md +65 -0
  557. tapps_agents/resources/claude/commands/refactor-clean.md +21 -0
  558. tapps_agents/resources/claude/commands/refactor.md +55 -0
  559. tapps_agents/resources/claude/commands/review.md +67 -0
  560. tapps_agents/resources/claude/commands/score.md +60 -0
  561. tapps_agents/resources/claude/commands/security-review.md +22 -0
  562. tapps_agents/resources/claude/commands/security-scan.md +54 -0
  563. tapps_agents/resources/claude/commands/tdd.md +24 -0
  564. tapps_agents/resources/claude/commands/test-coverage.md +21 -0
  565. tapps_agents/resources/claude/commands/test.md +54 -0
  566. tapps_agents/resources/claude/commands/update-codemaps.md +20 -0
  567. tapps_agents/resources/claude/commands/update-docs.md +21 -0
  568. tapps_agents/resources/claude/skills/__init__.py +1 -0
  569. tapps_agents/resources/claude/skills/analyst/SKILL.md +272 -0
  570. tapps_agents/resources/claude/skills/analyst/__init__.py +1 -0
  571. tapps_agents/resources/claude/skills/architect/SKILL.md +282 -0
  572. tapps_agents/resources/claude/skills/architect/__init__.py +1 -0
  573. tapps_agents/resources/claude/skills/backend-patterns/SKILL.md +30 -0
  574. tapps_agents/resources/claude/skills/backend-patterns/__init__.py +1 -0
  575. tapps_agents/resources/claude/skills/coding-standards/SKILL.md +29 -0
  576. tapps_agents/resources/claude/skills/coding-standards/__init__.py +1 -0
  577. tapps_agents/resources/claude/skills/debugger/SKILL.md +203 -0
  578. tapps_agents/resources/claude/skills/debugger/__init__.py +1 -0
  579. tapps_agents/resources/claude/skills/designer/SKILL.md +243 -0
  580. tapps_agents/resources/claude/skills/designer/__init__.py +1 -0
  581. tapps_agents/resources/claude/skills/documenter/SKILL.md +252 -0
  582. tapps_agents/resources/claude/skills/documenter/__init__.py +1 -0
  583. tapps_agents/resources/claude/skills/enhancer/SKILL.md +307 -0
  584. tapps_agents/resources/claude/skills/enhancer/__init__.py +1 -0
  585. tapps_agents/resources/claude/skills/evaluator/SKILL.md +204 -0
  586. tapps_agents/resources/claude/skills/evaluator/__init__.py +1 -0
  587. tapps_agents/resources/claude/skills/frontend-patterns/SKILL.md +29 -0
  588. tapps_agents/resources/claude/skills/frontend-patterns/__init__.py +1 -0
  589. tapps_agents/resources/claude/skills/implementer/SKILL.md +188 -0
  590. tapps_agents/resources/claude/skills/implementer/__init__.py +1 -0
  591. tapps_agents/resources/claude/skills/improver/SKILL.md +218 -0
  592. tapps_agents/resources/claude/skills/improver/__init__.py +1 -0
  593. tapps_agents/resources/claude/skills/ops/SKILL.md +281 -0
  594. tapps_agents/resources/claude/skills/ops/__init__.py +1 -0
  595. tapps_agents/resources/claude/skills/orchestrator/SKILL.md +390 -0
  596. tapps_agents/resources/claude/skills/orchestrator/__init__.py +1 -0
  597. tapps_agents/resources/claude/skills/planner/SKILL.md +254 -0
  598. tapps_agents/resources/claude/skills/planner/__init__.py +1 -0
  599. tapps_agents/resources/claude/skills/reviewer/SKILL.md +434 -0
  600. tapps_agents/resources/claude/skills/reviewer/__init__.py +1 -0
  601. tapps_agents/resources/claude/skills/security-review/SKILL.md +31 -0
  602. tapps_agents/resources/claude/skills/security-review/__init__.py +1 -0
  603. tapps_agents/resources/claude/skills/simple-mode/SKILL.md +695 -0
  604. tapps_agents/resources/claude/skills/simple-mode/__init__.py +1 -0
  605. tapps_agents/resources/claude/skills/tester/SKILL.md +219 -0
  606. tapps_agents/resources/claude/skills/tester/__init__.py +1 -0
  607. tapps_agents/resources/cursor/.cursorignore +35 -0
  608. tapps_agents/resources/cursor/__init__.py +1 -0
  609. tapps_agents/resources/cursor/commands/__init__.py +1 -0
  610. tapps_agents/resources/cursor/commands/build-fix.md +11 -0
  611. tapps_agents/resources/cursor/commands/build.md +11 -0
  612. tapps_agents/resources/cursor/commands/e2e.md +11 -0
  613. tapps_agents/resources/cursor/commands/fix.md +11 -0
  614. tapps_agents/resources/cursor/commands/refactor-clean.md +11 -0
  615. tapps_agents/resources/cursor/commands/review.md +11 -0
  616. tapps_agents/resources/cursor/commands/security-review.md +11 -0
  617. tapps_agents/resources/cursor/commands/tdd.md +11 -0
  618. tapps_agents/resources/cursor/commands/test-coverage.md +11 -0
  619. tapps_agents/resources/cursor/commands/test.md +11 -0
  620. tapps_agents/resources/cursor/commands/update-codemaps.md +10 -0
  621. tapps_agents/resources/cursor/commands/update-docs.md +11 -0
  622. tapps_agents/resources/cursor/rules/__init__.py +1 -0
  623. tapps_agents/resources/cursor/rules/agent-capabilities.mdc +687 -0
  624. tapps_agents/resources/cursor/rules/coding-style.mdc +31 -0
  625. tapps_agents/resources/cursor/rules/command-reference.mdc +2081 -0
  626. tapps_agents/resources/cursor/rules/cursor-mode-usage.mdc +125 -0
  627. tapps_agents/resources/cursor/rules/git-workflow.mdc +29 -0
  628. tapps_agents/resources/cursor/rules/performance.mdc +29 -0
  629. tapps_agents/resources/cursor/rules/project-context.mdc +163 -0
  630. tapps_agents/resources/cursor/rules/project-profiling.mdc +197 -0
  631. tapps_agents/resources/cursor/rules/quick-reference.mdc +630 -0
  632. tapps_agents/resources/cursor/rules/security.mdc +32 -0
  633. tapps_agents/resources/cursor/rules/simple-mode.mdc +500 -0
  634. tapps_agents/resources/cursor/rules/testing.mdc +31 -0
  635. tapps_agents/resources/cursor/rules/when-to-use.mdc +156 -0
  636. tapps_agents/resources/cursor/rules/workflow-presets.mdc +179 -0
  637. tapps_agents/resources/customizations/__init__.py +1 -0
  638. tapps_agents/resources/customizations/example-custom.yaml +83 -0
  639. tapps_agents/resources/hooks/__init__.py +1 -0
  640. tapps_agents/resources/hooks/templates/README.md +5 -0
  641. tapps_agents/resources/hooks/templates/__init__.py +1 -0
  642. tapps_agents/resources/hooks/templates/add-project-context.yaml +8 -0
  643. tapps_agents/resources/hooks/templates/auto-format-js.yaml +10 -0
  644. tapps_agents/resources/hooks/templates/auto-format-python.yaml +10 -0
  645. tapps_agents/resources/hooks/templates/git-commit-check.yaml +7 -0
  646. tapps_agents/resources/hooks/templates/notify-on-complete.yaml +8 -0
  647. tapps_agents/resources/hooks/templates/quality-gate.yaml +8 -0
  648. tapps_agents/resources/hooks/templates/security-scan-on-edit.yaml +10 -0
  649. tapps_agents/resources/hooks/templates/session-end-log.yaml +7 -0
  650. tapps_agents/resources/hooks/templates/show-beads-ready.yaml +8 -0
  651. tapps_agents/resources/hooks/templates/test-on-edit.yaml +10 -0
  652. tapps_agents/resources/hooks/templates/update-docs-on-complete.yaml +8 -0
  653. tapps_agents/resources/hooks/templates/user-prompt-log.yaml +7 -0
  654. tapps_agents/resources/scripts/__init__.py +1 -0
  655. tapps_agents/resources/scripts/set_bd_path.ps1 +51 -0
  656. tapps_agents/resources/workflows/__init__.py +1 -0
  657. tapps_agents/resources/workflows/presets/__init__.py +1 -0
  658. tapps_agents/resources/workflows/presets/brownfield-analysis.yaml +235 -0
  659. tapps_agents/resources/workflows/presets/fix.yaml +78 -0
  660. tapps_agents/resources/workflows/presets/full-sdlc.yaml +122 -0
  661. tapps_agents/resources/workflows/presets/quality.yaml +82 -0
  662. tapps_agents/resources/workflows/presets/rapid-dev.yaml +84 -0
  663. tapps_agents/session/__init__.py +19 -19
  664. tapps_agents/session/manager.py +256 -256
  665. tapps_agents/simple_mode/__init__.py +66 -66
  666. tapps_agents/simple_mode/agent_contracts.py +357 -357
  667. tapps_agents/simple_mode/beads_hooks.py +151 -151
  668. tapps_agents/simple_mode/code_snippet_handler.py +382 -382
  669. tapps_agents/simple_mode/documentation_manager.py +395 -395
  670. tapps_agents/simple_mode/documentation_reader.py +187 -187
  671. tapps_agents/simple_mode/file_inference.py +292 -292
  672. tapps_agents/simple_mode/framework_change_detector.py +268 -268
  673. tapps_agents/simple_mode/intent_parser.py +510 -510
  674. tapps_agents/simple_mode/learning_progression.py +358 -358
  675. tapps_agents/simple_mode/nl_handler.py +700 -700
  676. tapps_agents/simple_mode/onboarding.py +253 -253
  677. tapps_agents/simple_mode/orchestrators/__init__.py +38 -38
  678. tapps_agents/simple_mode/orchestrators/breakdown_orchestrator.py +49 -49
  679. tapps_agents/simple_mode/orchestrators/brownfield_orchestrator.py +135 -135
  680. tapps_agents/simple_mode/orchestrators/deliverable_checklist.py +349 -349
  681. tapps_agents/simple_mode/orchestrators/enhance_orchestrator.py +53 -53
  682. tapps_agents/simple_mode/orchestrators/epic_orchestrator.py +122 -122
  683. tapps_agents/simple_mode/orchestrators/explore_orchestrator.py +184 -184
  684. tapps_agents/simple_mode/orchestrators/plan_analysis_orchestrator.py +206 -206
  685. tapps_agents/simple_mode/orchestrators/pr_orchestrator.py +237 -237
  686. tapps_agents/simple_mode/orchestrators/refactor_orchestrator.py +222 -222
  687. tapps_agents/simple_mode/orchestrators/requirements_tracer.py +262 -262
  688. tapps_agents/simple_mode/orchestrators/resume_orchestrator.py +210 -210
  689. tapps_agents/simple_mode/orchestrators/review_orchestrator.py +161 -161
  690. tapps_agents/simple_mode/orchestrators/test_orchestrator.py +82 -82
  691. tapps_agents/simple_mode/output_aggregator.py +340 -340
  692. tapps_agents/simple_mode/result_formatters.py +598 -598
  693. tapps_agents/simple_mode/step_dependencies.py +382 -382
  694. tapps_agents/simple_mode/step_results.py +276 -276
  695. tapps_agents/simple_mode/streaming.py +388 -388
  696. tapps_agents/simple_mode/variations.py +129 -129
  697. tapps_agents/simple_mode/visual_feedback.py +238 -238
  698. tapps_agents/simple_mode/zero_config.py +274 -274
  699. tapps_agents/suggestions/__init__.py +8 -8
  700. tapps_agents/suggestions/inline_suggester.py +52 -52
  701. tapps_agents/templates/__init__.py +8 -8
  702. tapps_agents/templates/microservice_generator.py +274 -274
  703. tapps_agents/utils/env_validator.py +291 -291
  704. tapps_agents/workflow/__init__.py +171 -171
  705. tapps_agents/workflow/acceptance_verifier.py +132 -132
  706. tapps_agents/workflow/agent_handlers/__init__.py +41 -41
  707. tapps_agents/workflow/agent_handlers/analyst_handler.py +75 -75
  708. tapps_agents/workflow/agent_handlers/architect_handler.py +107 -107
  709. tapps_agents/workflow/agent_handlers/base.py +84 -84
  710. tapps_agents/workflow/agent_handlers/debugger_handler.py +100 -100
  711. tapps_agents/workflow/agent_handlers/designer_handler.py +110 -110
  712. tapps_agents/workflow/agent_handlers/documenter_handler.py +94 -94
  713. tapps_agents/workflow/agent_handlers/implementer_handler.py +235 -235
  714. tapps_agents/workflow/agent_handlers/ops_handler.py +62 -62
  715. tapps_agents/workflow/agent_handlers/orchestrator_handler.py +43 -43
  716. tapps_agents/workflow/agent_handlers/planner_handler.py +98 -98
  717. tapps_agents/workflow/agent_handlers/registry.py +119 -119
  718. tapps_agents/workflow/agent_handlers/reviewer_handler.py +119 -119
  719. tapps_agents/workflow/agent_handlers/tester_handler.py +69 -69
  720. tapps_agents/workflow/analytics_accessor.py +337 -337
  721. tapps_agents/workflow/analytics_alerts.py +416 -416
  722. tapps_agents/workflow/analytics_dashboard_cursor.py +281 -281
  723. tapps_agents/workflow/analytics_dual_write.py +103 -103
  724. tapps_agents/workflow/analytics_integration.py +119 -119
  725. tapps_agents/workflow/analytics_query_parser.py +278 -278
  726. tapps_agents/workflow/analytics_visualizer.py +259 -259
  727. tapps_agents/workflow/artifact_helper.py +204 -204
  728. tapps_agents/workflow/audit_logger.py +263 -263
  729. tapps_agents/workflow/auto_execution_config.py +340 -340
  730. tapps_agents/workflow/auto_progression.py +586 -586
  731. tapps_agents/workflow/branch_cleanup.py +349 -349
  732. tapps_agents/workflow/checkpoint.py +256 -256
  733. tapps_agents/workflow/checkpoint_manager.py +178 -178
  734. tapps_agents/workflow/code_artifact.py +179 -179
  735. tapps_agents/workflow/common_enums.py +96 -96
  736. tapps_agents/workflow/confirmation_handler.py +130 -130
  737. tapps_agents/workflow/context_analyzer.py +222 -222
  738. tapps_agents/workflow/context_artifact.py +230 -230
  739. tapps_agents/workflow/cursor_chat.py +94 -94
  740. tapps_agents/workflow/cursor_skill_helper.py +516 -516
  741. tapps_agents/workflow/dependency_resolver.py +244 -244
  742. tapps_agents/workflow/design_artifact.py +156 -156
  743. tapps_agents/workflow/detector.py +751 -751
  744. tapps_agents/workflow/direct_execution_fallback.py +301 -301
  745. tapps_agents/workflow/docs_artifact.py +168 -168
  746. tapps_agents/workflow/enforcer.py +389 -389
  747. tapps_agents/workflow/enhancement_artifact.py +142 -142
  748. tapps_agents/workflow/error_recovery.py +806 -806
  749. tapps_agents/workflow/event_bus.py +183 -183
  750. tapps_agents/workflow/event_log.py +612 -612
  751. tapps_agents/workflow/events.py +63 -63
  752. tapps_agents/workflow/exceptions.py +43 -43
  753. tapps_agents/workflow/execution_graph.py +498 -498
  754. tapps_agents/workflow/execution_plan.py +126 -126
  755. tapps_agents/workflow/file_utils.py +186 -186
  756. tapps_agents/workflow/gate_evaluator.py +182 -182
  757. tapps_agents/workflow/gate_integration.py +200 -200
  758. tapps_agents/workflow/graph_visualizer.py +130 -130
  759. tapps_agents/workflow/health_checker.py +206 -206
  760. tapps_agents/workflow/logging_helper.py +243 -243
  761. tapps_agents/workflow/manifest.py +582 -582
  762. tapps_agents/workflow/marker_writer.py +250 -250
  763. tapps_agents/workflow/messaging.py +325 -325
  764. tapps_agents/workflow/metadata_models.py +91 -91
  765. tapps_agents/workflow/metrics_integration.py +226 -226
  766. tapps_agents/workflow/migration_utils.py +116 -116
  767. tapps_agents/workflow/models.py +148 -148
  768. tapps_agents/workflow/nlp_config.py +198 -198
  769. tapps_agents/workflow/nlp_error_handler.py +207 -207
  770. tapps_agents/workflow/nlp_executor.py +163 -163
  771. tapps_agents/workflow/nlp_parser.py +528 -528
  772. tapps_agents/workflow/observability_dashboard.py +451 -451
  773. tapps_agents/workflow/observer.py +170 -170
  774. tapps_agents/workflow/ops_artifact.py +257 -257
  775. tapps_agents/workflow/output_passing.py +214 -214
  776. tapps_agents/workflow/parallel_executor.py +463 -463
  777. tapps_agents/workflow/planning_artifact.py +179 -179
  778. tapps_agents/workflow/preset_loader.py +285 -285
  779. tapps_agents/workflow/preset_recommender.py +270 -270
  780. tapps_agents/workflow/progress_logger.py +145 -145
  781. tapps_agents/workflow/progress_manager.py +303 -303
  782. tapps_agents/workflow/progress_monitor.py +186 -186
  783. tapps_agents/workflow/progress_updates.py +423 -423
  784. tapps_agents/workflow/quality_artifact.py +158 -158
  785. tapps_agents/workflow/quality_loopback.py +101 -101
  786. tapps_agents/workflow/recommender.py +387 -387
  787. tapps_agents/workflow/remediation_loop.py +166 -166
  788. tapps_agents/workflow/result_aggregator.py +300 -300
  789. tapps_agents/workflow/review_artifact.py +185 -185
  790. tapps_agents/workflow/schema_validator.py +522 -522
  791. tapps_agents/workflow/session_handoff.py +178 -178
  792. tapps_agents/workflow/skill_invoker.py +648 -648
  793. tapps_agents/workflow/state_manager.py +756 -756
  794. tapps_agents/workflow/state_persistence_config.py +331 -331
  795. tapps_agents/workflow/status_monitor.py +449 -449
  796. tapps_agents/workflow/step_checkpoint.py +314 -314
  797. tapps_agents/workflow/step_details.py +201 -201
  798. tapps_agents/workflow/story_models.py +147 -147
  799. tapps_agents/workflow/streaming.py +416 -416
  800. tapps_agents/workflow/suggestion_engine.py +552 -552
  801. tapps_agents/workflow/testing_artifact.py +186 -186
  802. tapps_agents/workflow/timeline.py +158 -158
  803. tapps_agents/workflow/token_integration.py +209 -209
  804. tapps_agents/workflow/validation.py +217 -217
  805. tapps_agents/workflow/visual_feedback.py +391 -391
  806. tapps_agents/workflow/workflow_chain.py +95 -95
  807. tapps_agents/workflow/workflow_summary.py +219 -219
  808. tapps_agents/workflow/worktree_manager.py +724 -724
  809. {tapps_agents-3.6.0.dist-info → tapps_agents-3.6.1.dist-info}/METADATA +672 -672
  810. tapps_agents-3.6.1.dist-info/RECORD +883 -0
  811. {tapps_agents-3.6.0.dist-info → tapps_agents-3.6.1.dist-info}/licenses/LICENSE +22 -22
  812. tapps_agents-3.6.0.dist-info/RECORD +0 -758
  813. {tapps_agents-3.6.0.dist-info → tapps_agents-3.6.1.dist-info}/WHEEL +0 -0
  814. {tapps_agents-3.6.0.dist-info → tapps_agents-3.6.1.dist-info}/entry_points.txt +0 -0
  815. {tapps_agents-3.6.0.dist-info → tapps_agents-3.6.1.dist-info}/top_level.txt +0 -0
@@ -0,0 +1,2081 @@
1
+ ---
2
+ description: Complete command reference for all TappsCodingAgents commands, parameters, and workflows. Use this as the authoritative source for available commands in Cursor IDE.
3
+ globs: []
4
+ alwaysApply: true
5
+ ---
6
+
7
+ # TappsCodingAgents Complete Command Reference
8
+
9
+ This document provides the complete reference for all tapps-agent commands, parameter combinations, and Simple Mode workflows available in Cursor IDE.
10
+
11
+ ## Command Syntax
12
+
13
+ ### Cursor Skills (Recommended in Cursor IDE)
14
+ ```
15
+ @agent-name *command [parameters]
16
+ ```
17
+
18
+ ### CLI Commands (Terminal/CI)
19
+ ```bash
20
+ tapps-agents <agent> <command> [--flags]
21
+ python -m tapps_agents.cli <agent> <command> [--flags]
22
+ ```
23
+
24
+ ### Global CLI Options (All Commands)
25
+
26
+ These flags work for **any** CLI command, and can be placed **before or after** the subcommand (modern CLI behavior):
27
+
28
+ ```bash
29
+ # Examples (flags can appear anywhere)
30
+ tapps-agents doctor --progress rich
31
+ tapps-agents --progress plain doctor
32
+ tapps-agents reviewer score README.md --no-progress
33
+ ```
34
+
35
+ - `--quiet` / `-q`: Quiet mode (errors + final results)
36
+ - `--verbose` / `-v`: Verbose diagnostics
37
+ - `--progress {auto,rich,plain,off}`: Progress UI mode
38
+ - `--no-progress`: Disable progress UI (same as `--progress off`)
39
+
40
+ **Environment variables:**
41
+ - `TAPPS_PROGRESS=auto|rich|plain|off`
42
+ - `TAPPS_NO_PROGRESS=1` (or `NO_PROGRESS=1`)
43
+
44
+ ## Top-Level Commands
45
+
46
+ ### `init` - Initialize Project
47
+ **Purpose:** Set up TappsCodingAgents in your project (Cursor Rules, Skills, config). **This is the first command you should run on any project** to enable all tapps-agents capabilities in Cursor IDE.
48
+
49
+ **CLI Syntax:**
50
+ ```bash
51
+ tapps-agents init [--no-rules] [--no-presets] [--no-config] [--no-skills] [--no-cache] [--no-cursorignore] [--reset] [--upgrade] [--no-backup] [--reset-mcp] [--preserve-custom] [--rollback <path>] [--yes] [--dry-run]
52
+ ```
53
+
54
+ **When to Use:**
55
+ - **First-time setup**: Run `tapps-agents init` when adding TappsCodingAgents to a new or existing project
56
+ - **Upgrading framework**: Use `tapps-agents init --reset` to upgrade framework files to latest version
57
+ - **Selective setup**: Use `--no-<component>` flags to skip specific components you don't need
58
+ - **CI/CD automation**: Use `--yes` flag to skip confirmation prompts
59
+
60
+ **What Happens When Executed on Other Projects:**
61
+
62
+ When you run `tapps-agents init` on any project (new or existing), it:
63
+
64
+ 1. **Detects existing installation**: Checks for existing tapps-agents files and warns if found (unless using `--reset`)
65
+ 2. **Creates directory structure**: Sets up all required directories if they don't exist
66
+ 3. **Copies framework files**: Installs framework-provided files (Skills, Rules, Presets) from the installed package
67
+ 4. **Preserves user files**: Never overwrites existing user files unless using `--reset` mode
68
+ 5. **Detects tech stack**: Automatically detects project dependencies (Python packages, frameworks) and configures experts
69
+ 6. **Pre-populates cache**: Optionally pre-populates Context7 cache with project dependencies (unless `--no-cache`)
70
+ 7. **Validates setup**: Runs environment diagnostics to verify everything is configured correctly
71
+
72
+ **What it installs:**
73
+
74
+ 1. **Cursor Rules** (`.cursor/rules/`) - rule files including:
75
+ - `workflow-presets.mdc` - Workflow preset documentation (auto-generated from YAML)
76
+ - `quick-reference.mdc` - Quick command reference
77
+ - `agent-capabilities.mdc` - Agent capability descriptions
78
+ - `when-to-use.mdc` - Importance and when to use each capability (workflows, agents, commands)
79
+ - `project-context.mdc` - Project context template
80
+ - `project-profiling.mdc` - Project profiling guide
81
+ - `simple-mode.mdc` - Simple Mode guide (natural language orchestration)
82
+ - `command-reference.mdc` - This file (complete command reference)
83
+ - `cursor-mode-usage.mdc` - Cursor vs CLI usage (when to use @simple-mode vs tapps-agents workflow)
84
+
85
+ 2. **Cursor Skills** (`.claude/skills/`) - 14 agent skills + simple-mode skill:
86
+ - Enables `@agent-name *command` syntax in Cursor chat
87
+ - Each skill defines agent capabilities, tools, and instructions
88
+ - Skills are model-agnostic (use Cursor's configured LLM)
89
+ - **Agents**: analyst, architect, debugger, designer, documenter, enhancer, evaluator, implementer, improver, ops, orchestrator, planner, reviewer, tester
90
+ - **Simple Mode skill** (`.claude/skills/simple-mode/`) - **INSTALLED BY DEFAULT**:
91
+ - **Primary interface** for TappsCodingAgents in Cursor
92
+ - Natural language orchestration of multiple skills
93
+ - **Available immediately after `init`** (no additional setup needed)
94
+ - Commands:
95
+ - `@simple-mode *build` - Complete 7-step feature development workflow
96
+ - `@simple-mode *review` - Code quality review workflow
97
+ - `@simple-mode *fix` - Bug fixing workflow with debugging
98
+ - `@simple-mode *test` - Test generation workflow
99
+ - `@simple-mode *epic` - Epic execution workflow (all stories in dependency order)
100
+ - `@simple-mode *tdd` - TDD workflow (Red-Green-Refactor, coverage ≥80%)
101
+ - `@simple-mode *e2e` - E2E test generation and run (Playwright MCP if available)
102
+ - `@simple-mode *build-fix` - Fix build/compile errors (distinct from *fix, *fix-tests)
103
+ - `@simple-mode *refactor-clean` - Dead code cleanup (unused imports, duplication)
104
+ - `@simple-mode *update-docs` - Sync documentation with code
105
+ - `@simple-mode *update-codemaps` - Refresh Context7 or codemap index
106
+ - `@simple-mode *test-coverage` - Coverage-driven test generation
107
+ - `@simple-mode *security-review` - Security audit (reviewer + ops + OWASP-style)
108
+ - `@simple-mode *fix-tests` - Auto-fix test failures
109
+ - `@simple-mode *microservice` - Generate complete microservice structure
110
+ - `@simple-mode *docker-fix` - Debug container errors
111
+ - `@simple-mode *integrate-service` - Service-to-service integration
112
+ - `@simple-mode *full` - Full SDLC workflow (9 steps)
113
+ - Domain skills: `@coding-standards`, `@backend-patterns`, `@frontend-patterns`, `@security-review`
114
+ - Natural language commands (e.g., `@simple-mode Build a feature`)
115
+ - **Simple Mode is enabled by default** in config after `init`
116
+
117
+ 3. **Configuration** (`.tapps-agents/config.yaml`):
118
+ - Framework settings and agent configurations
119
+ - Tech stack detection results
120
+ - Quality thresholds and automation settings
121
+
122
+ 5. **Workflow Presets** (`workflows/presets/`):
123
+ - 5 workflow preset YAML files: full-sdlc, rapid-dev, fix, quality, brownfield-analysis
124
+ - Can be customized per project
125
+
126
+ 6. **MCP Config** (`.cursor/mcp.json`):
127
+ - Context7 MCP server configuration for library documentation lookup
128
+ - Enables `@reviewer *docs <library>` commands
129
+
130
+ 7. **Context7 Cache**:
131
+ - Pre-populated with project dependencies + built-in expert libraries
132
+ - Speeds up library documentation lookups
133
+ - Can be skipped with `--no-cache` if Context7 not configured
134
+
135
+ 8. **`.cursorignore`**:
136
+ - Performance optimization patterns
137
+ - Excludes large/generated files from Cursor indexing
138
+ - Auto-updated with TappsCodingAgents patterns (backups, archives, artifacts)
139
+ - Preserves existing user patterns
140
+
141
+ **Parameters:**
142
+
143
+ - `--no-rules`: Skip creating `.cursor/rules/` directory
144
+ - **When to use**: If you want to manage rules manually or use custom rules only
145
+ - **Why**: Reduces setup time if you don't need framework-provided rules
146
+
147
+ - `--no-presets`: Skip creating workflow presets directory
148
+ - **When to use**: If you only use custom workflows or CLI commands
149
+ - **Why**: Reduces setup time if you don't need preset workflows
150
+
151
+ - `--no-config`: Skip creating `.tapps-agents/config.yaml`
152
+ - **When to use**: If you have existing config or want to configure manually
153
+ - **Why**: Allows manual configuration without framework defaults
154
+
155
+ - `--no-skills`: Skip installing Cursor Skills
156
+ - **When to use**: If you only use CLI commands, not Cursor chat
157
+ - **Why**: Reduces setup time, but disables `@agent-name` commands in Cursor
158
+
159
+
160
+ - `--no-cache`: Skip pre-populating Context7 cache
161
+ - **When to use**: If Context7 is not configured or you want to populate manually
162
+ - **Why**: Faster init if Context7 API key not available
163
+
164
+ - `--no-cursorignore`: Skip creating/updating `.cursorignore` file
165
+ - **When to use**: If you have custom indexing preferences
166
+ - **Why**: Manual control over Cursor indexing patterns
167
+ - **Note**: If `.cursorignore` exists, `init` will append missing TappsCodingAgents patterns (preserves your custom patterns)
168
+
169
+ - `--reset` / `--upgrade`: Reset framework-managed files to latest version
170
+ - **When to use**: After upgrading tapps-agents package, to get latest framework files
171
+ - **Why**: Updates Skills, Rules, Presets to match installed package version
172
+ - **Note**: Preserves user data (config, experts, knowledge base, custom files)
173
+
174
+ - `--no-backup`: Skip backup before reset (not recommended)
175
+ - **When to use**: Only if you're certain you don't need rollback capability
176
+ - **Why**: Faster reset, but no way to undo changes
177
+
178
+ - `--reset-mcp`: Also reset `.cursor/mcp.json` to framework version
179
+ - **When to use**: If MCP config is corrupted or you want framework defaults
180
+ - **Why**: Restores MCP configuration to framework-provided version
181
+
182
+ - `--preserve-custom`: Preserve custom Skills, Rules, and presets (default: True)
183
+ - **When to use**: Default behavior - custom files are always preserved
184
+ - **Why**: Protects user customizations during reset
185
+
186
+ - `--rollback <path>`: Rollback an init reset from a backup
187
+ - **When to use**: If reset caused issues and you need to restore previous state
188
+ - **Why**: Restores files from backup created during reset
189
+
190
+ - `--yes` / `-y`: Automatically answer 'yes' to all confirmation prompts
191
+ - **When to use**: CI/CD pipelines, automation scripts, non-interactive environments
192
+ - **Why**: Enables fully automated init without user interaction
193
+
194
+ - `--dry-run`: Preview what would be reset without making changes
195
+ - **When to use**: Before running `--reset` to see what will change
196
+ - **Why**: Safe way to preview reset impact without modifying files
197
+
198
+ **Examples:**
199
+
200
+ ```bash
201
+ # Initial setup (recommended for all projects)
202
+ tapps-agents init
203
+
204
+ # Initial setup without Context7 cache (if API key not configured)
205
+ tapps-agents init --no-cache
206
+
207
+ # Upgrade framework files after package update
208
+ tapps-agents init --reset
209
+
210
+ # Preview what would be reset (safe to run)
211
+ tapps-agents init --reset --dry-run
212
+
213
+ # Automated setup for CI/CD
214
+ tapps-agents init --yes
215
+
216
+ # Minimal setup (only Skills and Rules, no presets or cache)
217
+ tapps-agents init --no-presets --no-cache
218
+
219
+ # Rollback from backup
220
+ tapps-agents init --rollback .tapps-agents/backups/init-reset-20250116-143022
221
+ ```
222
+
223
+ **After Init - What You Can Do:**
224
+
225
+ **Simple Mode is Ready to Use:**
226
+ After `tapps-agents init`, Simple Mode is automatically set up and ready:
227
+ - ✅ Simple Mode skill installed (`.claude/skills/simple-mode/`)
228
+ - ✅ Simple Mode rule installed (`.cursor/rules/simple-mode.mdc`)
229
+ - ✅ Simple Mode enabled by default in config
230
+ - ✅ Ready to use immediately in Cursor chat
231
+
232
+ **Verify Simple Mode Setup:**
233
+ ```bash
234
+ tapps-agents simple-mode status
235
+ ```
236
+
237
+ **In Cursor Chat (Recommended - Use Simple Mode):**
238
+ ```cursor
239
+ # Natural language commands (Simple Mode auto-detects intent)
240
+ @simple-mode Build a user authentication feature
241
+ @simple-mode Review my authentication code
242
+ @simple-mode Fix the error in auth.py
243
+ @simple-mode Add tests for service.py
244
+
245
+ # Explicit commands (more reliable for complex workflows)
246
+ @simple-mode *build "Add user authentication"
247
+ @simple-mode *review src/api/auth.py
248
+ @simple-mode *fix src/buggy.py "Fix the error"
249
+ @simple-mode *epic docs/prd/epic-51.md
250
+
251
+ # Individual agent commands (when you need specific agents)
252
+ @reviewer *score src/main.py
253
+ @implementer *implement "Add feature" src/feature.py
254
+ @reviewer *docs fastapi routing
255
+ ```
256
+
257
+ **In Terminal/CI:**
258
+ ```bash
259
+ # Workflow presets
260
+ tapps-agents workflow rapid --prompt "Add feature" --auto
261
+ tapps-agents workflow full --prompt "Build API" --auto
262
+
263
+ # Individual agent commands
264
+ tapps-agents reviewer review src/
265
+ tapps-agents score src/main.py
266
+
267
+ # Simple Mode management
268
+ tapps-agents simple-mode on
269
+ tapps-agents simple-mode status
270
+ tapps-agents simple-mode full --prompt "Build feature" --auto
271
+ ```
272
+
273
+ ### `create` - Create New Project
274
+ **Purpose:** Create a complete application from natural language description
275
+
276
+ **CLI Syntax:**
277
+ ```bash
278
+ tapps-agents create "<description>" [--workflow <preset>]
279
+ ```
280
+
281
+ **Parameters:**
282
+ - `description` (required): Natural language description
283
+ - `--workflow`: `full` (default), `rapid`, `enterprise`, `feature`
284
+
285
+ ### `workflow` - Run Preset Workflows
286
+ **Purpose:** Execute predefined workflow presets
287
+
288
+ **CLI Syntax:**
289
+ ```bash
290
+ tapps-agents workflow <preset> [--prompt "<description>"] [--file <path>] [--auto] [--cli-mode] [--cursor-mode] [--dry-run] [--continue-from <step>] [--skip-steps <steps>]
291
+ ```
292
+
293
+ **Available Presets (5):**
294
+ - `full` / `enterprise` - Complete SDLC pipeline
295
+ - `rapid` / `feature` / `new-feature` / `simple-new-feature` - Fast feature development
296
+ - `fix` / `maintenance` / `hotfix` / `urgent` / `quick-fix` / `refactor` - Bug fixes, hotfixes, maintenance
297
+ - `quality` / `improve` / `simple-improve-quality` - Code quality improvement
298
+ - `brownfield` / `brownfield-analysis` - Brownfield/legacy analysis
299
+ - `list` - List all available presets
300
+ - `recommend` - Get AI-powered workflow recommendation
301
+ - `state` - Workflow state management (list, show, cleanup, resume)
302
+ - `resume` - Resume interrupted workflow
303
+
304
+ **Common Parameters:**
305
+ - `--prompt` / `-p`: Natural language description
306
+ - `--file`: Target file/directory
307
+ - `--auto`: Fully automated execution
308
+
309
+ **Execution Mode Parameters:**
310
+ - `--cli-mode`: Force CLI/headless mode (direct LLM calls, no Cursor Skills)
311
+ - `--cursor-mode`: Force Cursor mode (uses Cursor Skills for LLM operations)
312
+
313
+ **Pre-flight Validation:**
314
+ - `--dry-run`: Validate workflow without executing. Shows what steps would run, checks for existing artifacts, validates environment, and reports potential issues.
315
+
316
+ **Partial Execution (Resume/Skip):**
317
+ - `--continue-from <step>`: Continue workflow from a specific step (e.g., 'implement', 'review'). Skips earlier steps. Use `tapps-agents workflow state list` to see available steps.
318
+ - `--skip-steps <steps>`: Comma-separated list of steps to skip (e.g., 'enhance,plan'). Useful when those steps were already completed manually.
319
+
320
+ **Output Control:**
321
+ - `--print-paths`: Print artifact file paths after each step completes (default: True)
322
+ - `--no-print-paths`: Disable printing artifact paths after each step
323
+
324
+ **Workflow State Management:**
325
+ ```bash
326
+ tapps-agents workflow state list [--workflow-id <id>] [--format json|text]
327
+ tapps-agents workflow state show <workflow_id> [--format json|text]
328
+ tapps-agents workflow state cleanup [--retention-days 30] [--max-states-per-workflow 10] [--remove-completed] [--dry-run]
329
+ tapps-agents workflow resume [--workflow-id <id>] [--validate]
330
+ ```
331
+
332
+ **Examples:**
333
+ ```bash
334
+ # Pre-flight validation before running
335
+ tapps-agents workflow rapid --dry-run --prompt "Add user authentication"
336
+
337
+ # Resume from a specific step after failure
338
+ tapps-agents workflow rapid --continue-from implementation --prompt "Add user auth"
339
+
340
+ # Skip already-completed steps
341
+ tapps-agents workflow rapid --skip-steps "enhance,planning" --prompt "Add user auth"
342
+
343
+ # Force CLI mode for CI/CD pipelines
344
+ tapps-agents workflow rapid --cli-mode --auto --prompt "Add user auth"
345
+ ```
346
+
347
+ ### `cleanup` - Cleanup TappsCodingAgents Artifacts
348
+ **Purpose:** Clean up various TappsCodingAgents artifacts to free disk space and reduce IDE clutter
349
+
350
+ **CLI Syntax:**
351
+ ```bash
352
+ tapps-agents cleanup workflow-docs [--keep-latest <n>] [--retention-days <n>] [--archive] [--no-archive] [--dry-run]
353
+ ```
354
+
355
+ **Subcommands:**
356
+ - `workflow-docs` - Clean up old workflow documentation directories
357
+
358
+ **Parameters:**
359
+ - `--keep-latest <n>`: Keep N most recent workflows visible (default: from config, typically 5)
360
+ - `--retention-days <n>`: Archive workflows older than N days (default: from config, typically 30)
361
+ - `--archive`: Enable archival of old workflows (default: from config)
362
+ - `--no-archive`: Disable archival (workflows will be kept visible)
363
+ - `--dry-run`: Preview changes without making them
364
+
365
+ **When to Use:**
366
+ - Reducing IDE clutter from accumulated workflow directories
367
+ - Freeing disk space from old workflow documentation
368
+ - Managing workflow artifact retention policies
369
+
370
+ **Examples:**
371
+ ```bash
372
+ # Preview cleanup (dry-run)
373
+ tapps-agents cleanup workflow-docs --dry-run
374
+
375
+ # Cleanup with defaults from config
376
+ tapps-agents cleanup workflow-docs
377
+
378
+ # Custom retention policy
379
+ tapps-agents cleanup workflow-docs --keep-latest 10 --retention-days 60
380
+
381
+ # Cleanup without archiving (keep workflows visible)
382
+ tapps-agents cleanup workflow-docs --no-archive
383
+ ```
384
+
385
+ **What It Does:**
386
+ - Scans `docs/workflows/simple-mode/` for workflow directories
387
+ - Keeps the N most recent workflows visible
388
+ - Archives workflows older than retention period to `.tapps-agents/archives/workflows/`
389
+ - Preserves workflow history while reducing IDE clutter
390
+
391
+ ### `health` - Health Checks and Usage (Analytics)
392
+ **Purpose:** Health checks (environment, execution, cache, KB, outcomes) and usage/analytics (agent/workflow metrics). The former top-level `tapps-agents analytics` is replaced by `health usage`.
393
+
394
+ **CLI Syntax:**
395
+ ```bash
396
+ tapps-agents health check [--check <name>] [--format json|text]
397
+ tapps-agents health dashboard [--format json|text]
398
+ tapps-agents health usage dashboard|agents|workflows|system|trends [--format json|text] [--agent-id <id>] [--workflow-id <id>] [--days <n>] [--metric-type <type>]
399
+ tapps-agents health metrics [--check-name <name>] [--status <status>] [--days <n>]
400
+ tapps-agents health trends [--check-name <name>] [--days <n>]
401
+ ```
402
+
403
+ **Usage subcommands (analytics):**
404
+ - `health usage dashboard` (or `show`) - Usage/analytics overview
405
+ - `health usage agents` - Agent performance; `--agent-id` to filter
406
+ - `health usage workflows` - Workflow performance; `--workflow-id` to filter
407
+ - `health usage system` - System status and resources
408
+ - `health usage trends` - Historical trends; `--metric-type`, `--days`
409
+
410
+ **When to Use:**
411
+ - `health check`: Validate environment and run health checks
412
+ - `health usage dashboard`: View agent/workflow metrics (replaces `tapps-agents analytics`)
413
+
414
+ ### `score` - Quick Code Scoring
415
+ **Purpose:** Fast code quality scoring (shortcut for `reviewer score`)
416
+
417
+ **CLI Syntax:**
418
+ ```bash
419
+ tapps-agents score <file> [--format json|text]
420
+ ```
421
+
422
+ **Cursor Syntax:**
423
+ ```cursor
424
+ @reviewer *score <file>
425
+ ```
426
+
427
+ ### `doctor` - Environment Diagnostics
428
+ **Purpose:** Validate local development environment
429
+
430
+ **CLI Syntax:**
431
+ ```bash
432
+ tapps-agents doctor [--format json|text] [--config-path <path>] [--full]
433
+ ```
434
+
435
+ **Parameters:**
436
+ - `--format json|text`: Output format (default: `text`)
437
+ - `--config-path <path>`: Explicit path to config file if not in default location
438
+ - `--full`: Run both doctor checks and health checks for comprehensive diagnostics
439
+
440
+ **What It Checks:**
441
+ - Python version compatibility
442
+ - Required tools (ruff, mypy, pytest, etc.)
443
+ - MCP server configuration (Context7, Playwright)
444
+ - Cursor integration components (Rules, Skills, Background Agents)
445
+ - Workflow presets
446
+ - Project configuration
447
+ - **Context7 cache status** (enabled/disabled, directory accessible, entry count)
448
+
449
+ **When to Use:**
450
+ - **Initial setup verification**: After `tapps-agents init` to verify installation
451
+ - **Troubleshooting**: When commands aren't working as expected
452
+ - **CI/CD validation**: Ensure environment is properly configured
453
+ - **Comprehensive diagnostics**: Use `--full` flag for detailed health checks including cache metrics
454
+
455
+ **Examples:**
456
+ ```bash
457
+ # Basic environment check
458
+ tapps-agents doctor
459
+
460
+ # JSON output for automation
461
+ tapps-agents doctor --format json
462
+
463
+ # Comprehensive diagnostics (doctor + health checks)
464
+ tapps-agents doctor --full
465
+
466
+ # Full diagnostics with JSON output
467
+ tapps-agents doctor --full --format json
468
+ ```
469
+
470
+ **Note:** The `--full` flag runs both doctor checks (environment validation) and health checks (operational metrics). Doctor provides basic Context7 cache status; health checks provide detailed metrics (hit rate, response time, staleness analysis).
471
+
472
+ ### `cursor` - Cursor AI Integration Verification
473
+ **Purpose:** Verify and manage Cursor AI integration components
474
+
475
+ **CLI Syntax:**
476
+ ```bash
477
+ tapps-agents cursor verify [--format json|text]
478
+ tapps-agents cursor check [--format json|text] # alias
479
+ ```
480
+
481
+ **When to Use:**
482
+ - **After `init`**: Verify all Cursor integration components were installed correctly
483
+ - **Troubleshooting**: When Cursor Skills or Rules aren't working as expected
484
+ - **CI/CD validation**: Ensure integration is properly configured before deployment
485
+ - **Migration verification**: After moving or copying project files
486
+ - **Pre-commit checks**: Validate setup before committing integration files
487
+
488
+ **What It Checks:**
489
+ - **Cursor Skills** (`.claude/skills/`) - Validates all 14 agent skills + simple-mode are present
490
+ - Checks directory structure
491
+ - Verifies YAML frontmatter in SKILL.md files
492
+ - Reports missing skills
493
+ - **Cursor Rules** (`.cursor/rules/`) - Validates required rule files are present
494
+ - Checks for rule files including: workflow-presets, quick-reference, agent-capabilities, when-to-use, project-context, project-profiling, simple-mode, command-reference, cursor-mode-usage (and others)
495
+ - Verifies file format (.mdc extension)
496
+ - Checks YAML syntax validity
497
+ - Verifies agents are configured
498
+ - Reports agent count
499
+ - **`.cursorignore`** - Checks for recommended patterns
500
+ - Validates presence of common ignore patterns (.venv, __pycache__, etc.)
501
+ - **`.cursorrules`** (legacy) - Optional legacy support file
502
+
503
+ **Parameters:**
504
+ - `--format json|text`: Output format (default: `text`)
505
+ - **When to use**:
506
+ - `text`: Human-readable verification report (default)
507
+ - `json`: Structured validation data for CI/CD or automation
508
+
509
+ **Output:**
510
+ - **Status**: `VALID` or `INVALID` overall status
511
+ - **Components**: Per-component validation results
512
+ - **Errors**: Critical issues that prevent Cursor integration from working
513
+ - **Warnings**: Non-critical issues or missing optional components
514
+
515
+ **Exit Codes:**
516
+ - `0`: All components valid
517
+ - `1`: One or more components invalid (use in CI/CD quality gates)
518
+
519
+ **Examples:**
520
+ ```bash
521
+ # Verify Cursor integration (human-readable)
522
+ tapps-agents cursor verify
523
+
524
+ # Verify with JSON output (for automation)
525
+ tapps-agents cursor verify --format json
526
+
527
+ # Use alias
528
+ tapps-agents cursor check
529
+
530
+ # In CI/CD pipeline (fails if invalid)
531
+ tapps-agents cursor verify --format json || exit 1
532
+ ```
533
+
534
+ **Related:**
535
+ - Run `tapps-agents init` to install/repair missing components
536
+ - See `.cursor/rules/quick-reference.mdc` for quick command reference
537
+ - See `docs/CURSOR_SKILLS_INSTALLATION_GUIDE.md` for detailed setup guide
538
+
539
+ ### `simple-mode` - Simple Mode Management
540
+ **Purpose:** Manage Simple Mode - simplified natural language interface. Simple Mode is the **primary user interface** for TappsCodingAgents in Cursor, providing natural language commands that automatically orchestrate multiple specialized skills.
541
+
542
+ **CLI Syntax:**
543
+ ```bash
544
+ tapps-agents simple-mode <command> [options]
545
+ ```
546
+
547
+ **Subcommands:**
548
+ - `on` - Enable Simple Mode
549
+ - **When to use**: After running `tapps-agents init`, to enable Simple Mode
550
+ - **Why**: Activates Simple Mode configuration in `.tapps-agents/config.yaml`
551
+ - **Note**: Simple Mode skill is installed by `init`, but must be enabled via this command
552
+
553
+ - `off` - Disable Simple Mode
554
+ - **When to use**: If you want to use individual agent commands only
555
+ - **Why**: Disables Simple Mode but keeps skill installed
556
+
557
+ - `status [--format json|text]` - Check Simple Mode status
558
+ - **When to use**: Verify Simple Mode is enabled and configured
559
+ - **Why**: Shows current configuration and enabled state
560
+
561
+ - `init` - Run onboarding wizard
562
+ - **When to use**: First time using Simple Mode, or to reconfigure
563
+ - **Why**: Interactive setup with guided configuration
564
+ - **What it does**: Detects project type, configures settings, suggests first command
565
+
566
+ - `configure` / `config` - Configure settings interactively
567
+ - **When to use**: To change Simple Mode settings after initial setup
568
+ - **Why**: Update configuration without running full onboarding
569
+
570
+ - `progress` - Show learning progression
571
+ - **When to use**: Track your Simple Mode usage and unlocked features
572
+ - **Why**: Shows learning level, commands used, features unlocked
573
+
574
+ - `full [--prompt "<desc>"] [--file <path>] [--auto]` - Run full lifecycle workflow
575
+ - **When to use**: Complete SDLC workflow with all quality gates
576
+ - **Why**: Comprehensive workflow with requirements, design, implementation, testing, security, documentation
577
+ - **Parameters**:
578
+ - `--prompt`: Natural language description (required for greenfield)
579
+ - `--file`: Target file/directory (for brownfield/refactoring)
580
+ - `--auto`: Fully automated execution
581
+
582
+ **Simple Mode is Installed by `init`:**
583
+ - Simple Mode skill (`.claude/skills/simple-mode/`) is automatically installed by `tapps-agents init`
584
+ - Simple Mode rule (`.cursor/rules/simple-mode.mdc`) is automatically installed
585
+ - Simple Mode is enabled by default in config, but you can run `tapps-agents simple-mode on` to ensure it's active
586
+
587
+ **Cursor Usage (Natural Language - Recommended):**
588
+ ```cursor
589
+ @simple-mode Build a user authentication feature
590
+ @simple-mode Review my authentication code
591
+ @simple-mode Fix the error in auth.py
592
+ @simple-mode Add tests for service.py
593
+ @simple-mode Execute epic docs/prd/epic-51.md
594
+ ```
595
+
596
+ **Cursor Usage (Explicit Commands - More Reliable):**
597
+ ```cursor
598
+ @simple-mode *build "Create a user authentication feature"
599
+ @simple-mode *review src/api/auth.py
600
+ @simple-mode *fix src/buggy.py "Fix the error"
601
+ @simple-mode *test src/api/auth.py
602
+ @simple-mode *enhance "Add OAuth2 login"
603
+ @simple-mode *breakdown "Migrate to microservices"
604
+ @simple-mode *todo ready
605
+ @simple-mode *epic docs/prd/epic-51-yaml-automation-quality-enhancement.md
606
+ @simple-mode *full "Build a complete REST API"
607
+ ```
608
+
609
+ **When to Use Simple Mode:**
610
+ - **New users**: Start with Simple Mode for natural language commands
611
+ - **Feature development**: Use `*build` for complete feature workflows
612
+ - **Code review**: Use `*review` for quality analysis
613
+ - **Bug fixing**: Use `*fix` for systematic debugging
614
+ - **Testing**: Use `*test` for test generation
615
+ - **Epic execution**: Use `*epic` for implementing entire Epic documents
616
+ - **Full lifecycle**: Use `*full` for complete SDLC workflows
617
+
618
+ **Why Use Simple Mode:**
619
+ - **Natural language**: Use plain English instead of learning multiple agent commands
620
+ - **Automatic orchestration**: Skills are coordinated automatically in the right sequence
621
+ - **Quality gates**: Automatic quality checks with loopback on failures
622
+ - **Better outcomes**: Produces higher quality code with comprehensive documentation
623
+ - **Workflow enforcement**: Ensures all steps are executed (enhance → plan → design → implement → review → test)
624
+
625
+ ## Agent Commands
626
+
627
+ ### Reviewer Agent (`@reviewer`)
628
+
629
+ **Available Commands:**
630
+
631
+ #### `*review` / `review` (Dual-Mode)
632
+ **Purpose:** Comprehensive code review with AI analysis. Provides detailed feedback on code quality, security, maintainability, and best practices.
633
+
634
+ **CLI Syntax:**
635
+ ```bash
636
+ tapps-agents reviewer review [<files>...] [--pattern <glob>] [--max-workers <n>] [--format json|text|markdown|html] [--output <file>] [--fail-under <score>]
637
+ ```
638
+
639
+ **Cursor Syntax:**
640
+ ```cursor
641
+ @reviewer *review <file>
642
+ ```
643
+
644
+ **When to Use:**
645
+ - **Pre-commit reviews**: Review code before committing changes
646
+ - **Code quality audits**: Comprehensive analysis of codebase quality
647
+ - **Learning best practices**: Get detailed feedback on code improvements
648
+ - **Batch processing**: Review multiple files or entire directories
649
+ - **CI/CD integration**: Use `--fail-under` to enforce quality gates
650
+
651
+ **Parameters:**
652
+ - `files` (optional): One or more file paths. Supports multiple files, directories (auto-discovers code files), or glob patterns
653
+ - **When to use**: Review specific files or directories
654
+ - **Why**: Targeted review of changed or problematic code
655
+
656
+ - `--pattern <glob>`: Glob pattern to match files (e.g., `**/*.py`, `src/**/*.ts`)
657
+ - **When to use**: Review all files matching a pattern across the project
658
+ - **Why**: Efficient batch review without listing individual files
659
+
660
+ - `--max-workers <n>`: Concurrent file operations (default: 4)
661
+ - **When to use**: Adjust based on system resources and file count
662
+ - **Why**: Balance speed vs. resource usage (higher = faster but more CPU/memory)
663
+
664
+ - `--format <format>`: Output format - `json` (default), `text`, `markdown`, `html`
665
+ - **When to use**:
666
+ - `json`: CI/CD, automation, programmatic processing
667
+ - `text`: Terminal output, quick reviews
668
+ - `markdown`: Documentation, reports, PR comments
669
+ - `html`: Web-based reports, sharing with team
670
+ - **Why**: Different formats suit different use cases
671
+
672
+ - `--output <file>`: Output file path
673
+ - **When to use**: Save review results to file for later analysis
674
+ - **Why**: Persist review results, share with team, track over time
675
+
676
+ - `--fail-under <score>`: Exit with code 1 if overall score is below threshold (0-100)
677
+ - **When to use**: CI/CD quality gates, enforcing minimum quality standards
678
+ - **Why**: Automatically fail builds if code quality is too low
679
+
680
+ **Examples:**
681
+ ```bash
682
+ # Review single file
683
+ tapps-agents reviewer review src/app.py
684
+
685
+ # Review multiple files
686
+ tapps-agents reviewer review src/app.py src/utils.py src/models.py
687
+
688
+ # Review all Python files in project
689
+ tapps-agents reviewer review --pattern "**/*.py" --max-workers 8
690
+
691
+ # Generate HTML report
692
+ tapps-agents reviewer review src/ --format html --output review-report.html
693
+
694
+ # CI/CD quality gate (fail if score < 70)
695
+ tapps-agents reviewer review src/ --fail-under 70 --format json
696
+ ```
697
+
698
+ #### `*score` / `score` (Dual-Mode)
699
+ **Purpose:** Fast objective quality metrics (no LLM feedback)
700
+
701
+ **CLI Syntax:**
702
+ ```bash
703
+ tapps-agents reviewer score [<files>...] [--pattern <glob>] [--max-workers <n>] [--format json|text|markdown|html] [--output <file>]
704
+ ```
705
+
706
+ **Cursor Syntax:**
707
+ ```cursor
708
+ @reviewer *score <file>
709
+ ```
710
+
711
+ #### `*lint` / `lint` (Dual-Mode)
712
+ **Purpose:** Code style checking (Ruff)
713
+
714
+ **CLI Syntax:**
715
+ ```bash
716
+ tapps-agents reviewer lint [<files>...] [--pattern <glob>] [--max-workers <n>] [--format json|text] [--output <file>]
717
+ ```
718
+
719
+ **Cursor Syntax:**
720
+ ```cursor
721
+ @reviewer *lint <file>
722
+ ```
723
+
724
+ #### `*type-check` / `type-check` (Dual-Mode)
725
+ **Purpose:** Type annotation validation (mypy)
726
+
727
+ **CLI Syntax:**
728
+ ```bash
729
+ tapps-agents reviewer type-check [<files>...] [--pattern <glob>] [--max-workers <n>] [--format json|text] [--output <file>]
730
+ ```
731
+
732
+ **Cursor Syntax:**
733
+ ```cursor
734
+ @reviewer *type-check <file>
735
+ ```
736
+
737
+ #### `*report` / `report` (CLI-First)
738
+ **Purpose:** Comprehensive project-wide quality reports
739
+
740
+ **CLI Syntax:**
741
+ ```bash
742
+ tapps-agents reviewer report <target> <formats>... [--output-dir <dir>]
743
+ ```
744
+
745
+ **Parameters:**
746
+ - `target` (required): File or directory path
747
+ - `formats` (required): One or more of `json`, `markdown`, `html`, `all`
748
+ - `--output-dir`: Directory for reports (default: `reports/quality/`)
749
+
750
+ #### `*duplication` / `duplication` (CLI-First)
751
+ **Purpose:** Code duplication detection
752
+
753
+ **CLI Syntax:**
754
+ ```bash
755
+ tapps-agents reviewer duplication <target> [--format json|text]
756
+ ```
757
+
758
+ #### `*docs` / `docs` (Dual-Mode)
759
+ **Purpose:** Get library documentation from Context7
760
+
761
+ **CLI Syntax:**
762
+ ```bash
763
+ tapps-agents reviewer docs <library> [<topic>]
764
+ ```
765
+
766
+ **Cursor Syntax:**
767
+ ```cursor
768
+ @reviewer *docs <library> [<topic>]
769
+ ```
770
+
771
+ ### Implementer Agent (`@implementer`)
772
+
773
+ **Available Commands:**
774
+
775
+ #### `*implement` / `implement` (Dual-Mode)
776
+ **Purpose:** Generate code from specification
777
+
778
+ **CLI Syntax:**
779
+ ```bash
780
+ tapps-agents implementer implement "<description>" <file> [--model <model>] [--no-review] [--backup]
781
+ ```
782
+
783
+ **Cursor Syntax:**
784
+ ```cursor
785
+ @implementer *implement "<description>" <file>
786
+ ```
787
+
788
+ **Parameters:**
789
+ - `description` (required): Natural language description
790
+ - `file` (required): Target file path
791
+ - `--model`: LLM model to use
792
+ - `--no-review`: Skip automatic code review
793
+ - `--backup`: Create backup before writing
794
+
795
+ #### `*refactor` / `refactor` (Dual-Mode)
796
+ **Purpose:** Refactor existing code
797
+
798
+ **CLI Syntax:**
799
+ ```bash
800
+ tapps-agents implementer refactor <file> "<instructions>" [--model <model>] [--no-review] [--backup]
801
+ ```
802
+
803
+ **Cursor Syntax:**
804
+ ```cursor
805
+ @implementer *refactor <file> "<instructions>"
806
+ ```
807
+
808
+ #### `*generate-code` / `generate-code` (CLI-First)
809
+ **Purpose:** Generate code without writing to file
810
+
811
+ **CLI Syntax:**
812
+ ```bash
813
+ tapps-agents implementer generate-code "<description>" [--format json|text]
814
+ ```
815
+
816
+ #### `*docs` / `docs` (Dual-Mode)
817
+ **Purpose:** Get library documentation from Context7
818
+
819
+ **CLI Syntax:**
820
+ ```bash
821
+ tapps-agents implementer docs <library> [<topic>]
822
+ ```
823
+
824
+ **Cursor Syntax:**
825
+ ```cursor
826
+ @implementer *docs <library> [<topic>]
827
+ ```
828
+
829
+ ### Tester Agent (`@tester`)
830
+
831
+ **Available Commands:**
832
+
833
+ #### `*test` / `test` (Dual-Mode)
834
+ **Purpose:** Generate and run tests
835
+
836
+ **CLI Syntax:**
837
+ ```bash
838
+ tapps-agents tester test <file> [--integration] [--coverage] [--format json|text]
839
+ ```
840
+
841
+ **Cursor Syntax:**
842
+ ```cursor
843
+ @tester *test <file>
844
+ ```
845
+
846
+ **Parameters:**
847
+ - `--integration`: Generate integration tests
848
+ - `--coverage`: Run with coverage analysis
849
+ - `--format`: Output format
850
+
851
+ #### `*generate-tests` / `generate-tests` (Dual-Mode)
852
+ **Purpose:** Generate tests without running
853
+
854
+ **CLI Syntax:**
855
+ ```bash
856
+ tapps-agents tester generate-tests <file> [--integration] [--format json|text]
857
+ ```
858
+
859
+ **Cursor Syntax:**
860
+ ```cursor
861
+ @tester *generate-tests <file>
862
+ ```
863
+
864
+ #### `*run-tests` / `run-tests` (CLI-First)
865
+ **Purpose:** Run existing test suite
866
+
867
+ **CLI Syntax:**
868
+ ```bash
869
+ tapps-agents tester run-tests [--coverage] [--format json|text]
870
+ ```
871
+
872
+ ### Planner Agent (`@planner`)
873
+
874
+ **Available Commands:**
875
+
876
+ #### `*plan` / `plan` (Dual-Mode)
877
+ **Purpose:** Create development plan
878
+
879
+ **CLI Syntax:**
880
+ ```bash
881
+ tapps-agents planner plan "<description>" [--format json|text]
882
+ ```
883
+
884
+ **Cursor Syntax:**
885
+ ```cursor
886
+ @planner *plan "<description>"
887
+ ```
888
+
889
+ #### `*create-story` / `create-story` (CLI-First)
890
+ **Purpose:** Create user story
891
+
892
+ **CLI Syntax:**
893
+ ```bash
894
+ tapps-agents planner create-story "<title>" [--epic <epic>] [--priority <priority>] [--format json|text]
895
+ ```
896
+
897
+ **Parameters:**
898
+ - `--epic`: Epic name
899
+ - `--priority`: `high`, `medium`, `low`
900
+
901
+ #### `*list-stories` / `list-stories` (CLI-First)
902
+ **Purpose:** List user stories
903
+
904
+ **CLI Syntax:**
905
+ ```bash
906
+ tapps-agents planner list-stories [--epic <epic>] [--format json|text]
907
+ ```
908
+
909
+ ### Architect Agent (`@architect`)
910
+
911
+ **Available Commands:**
912
+
913
+ #### `*design` / `design` (Dual-Mode)
914
+ **Purpose:** System architecture design
915
+
916
+ **CLI Syntax:**
917
+ ```bash
918
+ tapps-agents architect design "<description>" [--format json|text]
919
+ ```
920
+
921
+ **Cursor Syntax:**
922
+ ```cursor
923
+ @architect *design "<description>"
924
+ ```
925
+
926
+ #### `*patterns` / `patterns` (CLI-First)
927
+ **Purpose:** Design pattern recommendations
928
+
929
+ **CLI Syntax:**
930
+ ```bash
931
+ tapps-agents architect patterns "<description>" [--format json|text]
932
+ ```
933
+
934
+ ### Designer Agent (`@designer`)
935
+
936
+ **Available Commands:**
937
+
938
+ #### `*design-api` / `design-api` (Dual-Mode)
939
+ **Purpose:** API design and specification
940
+
941
+ **CLI Syntax:**
942
+ ```bash
943
+ tapps-agents designer design-api "<description>" [--format json|text]
944
+ ```
945
+
946
+ **Cursor Syntax:**
947
+ ```cursor
948
+ @designer *design-api "<description>"
949
+ ```
950
+
951
+ #### `*design-model` / `design-model` (Dual-Mode)
952
+ **Purpose:** Data model design
953
+
954
+ **CLI Syntax:**
955
+ ```bash
956
+ tapps-agents designer design-model "<description>" [--format json|text]
957
+ ```
958
+
959
+ **Cursor Syntax:**
960
+ ```cursor
961
+ @designer *design-model "<description>"
962
+ ```
963
+
964
+ ### Enhancer Agent (`@enhancer`)
965
+
966
+ **Available Commands:**
967
+
968
+ #### `*enhance` / `enhance` (Dual-Mode)
969
+ **Purpose:** Full prompt enhancement (7-stage pipeline) for code generation prompts. The 7-stage pipeline is defined by the Enhancer agent (analysis, requirements, architecture, codebase context, quality, implementation, synthesis). **Adaptive enhancement:** Build orchestrator and EnhancerHandler use PromptAnalyzer; when the prompt is detailed (>150 words), **quick** (stages 1–3) is used automatically to save time and tokens. In task/template copy, use "Run enhancement (full or quick per prompt analysis)" rather than "Run full 7-stage" so intent detectors and streamlining control the mode.
970
+
971
+ **CLI Syntax:**
972
+ ```bash
973
+ tapps-agents enhancer enhance "<prompt>" [--format json|markdown|yaml]
974
+ ```
975
+
976
+ **Cursor Syntax:**
977
+ ```cursor
978
+ @enhancer *enhance "<prompt>"
979
+ ```
980
+
981
+ **When to Use:**
982
+ - ✅ **Enhancing prompts for code generation** - Transform simple prompts into detailed implementation specifications
983
+ - ✅ **Preparing prompts for @implementer** - Create comprehensive specs before code generation
984
+ - ✅ **Code generation workflows** - Part of Simple Mode build workflow
985
+
986
+ **When NOT to Use:**
987
+ - ❌ **Requirements gathering** → Use `@analyst *gather-requirements` instead
988
+ - ❌ **Creating requirements documents** → Use `@analyst *gather-requirements` instead
989
+ - ❌ **User story creation** → Use `@planner *plan` instead
990
+
991
+ **Parameters:**
992
+ - `--format`: Output format (default: `markdown`)
993
+
994
+ **Note:** The enhancer is designed for **code generation prompts**, not requirements gathering. If you need to extract requirements from stakeholder descriptions, use `@analyst *gather-requirements` instead.
995
+
996
+ **Workflow:** Enhance steps in full-sdlc, rapid-dev, and Epic run via EnhancerHandler. **CLI auto-enhancement:** `auto_enhancement`, `PROMPT_ARGUMENT_MAP` (docs/CONFIGURATION.md).
997
+
998
+ #### `*enhance-quick` / `enhance-quick` (Dual-Mode)
999
+ **Purpose:** Quick prompt enhancement (stages 1-3)
1000
+
1001
+ **CLI Syntax:**
1002
+ ```bash
1003
+ tapps-agents enhancer enhance-quick "<prompt>" [--format json|markdown|yaml]
1004
+ ```
1005
+
1006
+ **Cursor Syntax:**
1007
+ ```cursor
1008
+ @enhancer *enhance-quick "<prompt>"
1009
+ ```
1010
+
1011
+ #### `*enhance-stage` / `enhance-stage` (CLI-First)
1012
+ **Purpose:** Run specific enhancement stage
1013
+
1014
+ **CLI Syntax:**
1015
+ ```bash
1016
+ tapps-agents enhancer enhance-stage <stage> "<prompt>" [--format json|markdown|yaml]
1017
+ ```
1018
+
1019
+ **Stages:** `analysis`, `requirements`, `architecture`, `codebase`, `quality`, `strategy`, `synthesis`
1020
+
1021
+ ### Debugger Agent (`@debugger`)
1022
+
1023
+ **Available Commands:**
1024
+
1025
+ #### `*debug` / `debug` (Dual-Mode)
1026
+ **Purpose:** Debug error and find root cause
1027
+
1028
+ **CLI Syntax:**
1029
+ ```bash
1030
+ tapps-agents debugger debug "<error>" [--file <file>] [--line <line>] [--format json|text]
1031
+ ```
1032
+
1033
+ **Cursor Syntax:**
1034
+ ```cursor
1035
+ @debugger *debug "<error>" --file <file> [--line <line>]
1036
+ ```
1037
+
1038
+ #### `*analyze-error` / `analyze-error` (CLI-First)
1039
+ **Purpose:** Analyze error with stack trace
1040
+
1041
+ **CLI Syntax:**
1042
+ ```bash
1043
+ tapps-agents debugger analyze-error "<error>" [--stack-trace "<trace>"] [--format json|text]
1044
+ ```
1045
+
1046
+ #### `*trace` / `trace` (CLI-First)
1047
+ **Purpose:** Code execution tracing
1048
+
1049
+ **CLI Syntax:**
1050
+ ```bash
1051
+ tapps-agents debugger trace "<description>" [--file <file>] [--format json|text]
1052
+ ```
1053
+
1054
+ ### Documenter Agent (`@documenter`)
1055
+
1056
+ **Available Commands:**
1057
+
1058
+ #### `*document` / `document` (Dual-Mode)
1059
+ **Purpose:** Generate documentation for a file
1060
+
1061
+ **CLI Syntax:**
1062
+ ```bash
1063
+ tapps-agents documenter document <file> [--output-format <format>] [--output-file <file>]
1064
+ ```
1065
+
1066
+ **Cursor Syntax:**
1067
+ ```cursor
1068
+ @documenter *document <file>
1069
+ ```
1070
+
1071
+ #### `*generate-docs` / `generate-docs` (CLI-First)
1072
+ **Purpose:** Generate API documentation
1073
+
1074
+ **CLI Syntax:**
1075
+ ```bash
1076
+ tapps-agents documenter generate-docs [--format json|text]
1077
+ ```
1078
+
1079
+ #### `*update-readme` / `update-readme` (CLI-First)
1080
+ **Purpose:** Generate or update README.md
1081
+
1082
+ **CLI Syntax:**
1083
+ ```bash
1084
+ tapps-agents documenter update-readme [--format json|text]
1085
+ ```
1086
+
1087
+ #### `*document-api` / `document-api` (Dual-Mode)
1088
+ **Purpose:** Document API endpoints
1089
+
1090
+ **CLI Syntax:**
1091
+ ```bash
1092
+ tapps-agents documenter document-api <file> [--format json|text]
1093
+ ```
1094
+
1095
+ **Cursor Syntax:**
1096
+ ```cursor
1097
+ @documenter *document-api <file>
1098
+ ```
1099
+
1100
+ ### Improver Agent (`@improver`)
1101
+
1102
+ **Available Commands:**
1103
+
1104
+ #### `*improve` / `improve` (Dual-Mode)
1105
+ **Purpose:** Code improvement suggestions
1106
+
1107
+ **CLI Syntax:**
1108
+ ```bash
1109
+ tapps-agents improver improve <file> "<instructions>" [--format json|text]
1110
+ ```
1111
+
1112
+ **Cursor Syntax:**
1113
+ ```cursor
1114
+ @improver *improve <file> "<instructions>"
1115
+ ```
1116
+
1117
+ #### `*optimize` / `optimize` (CLI-First)
1118
+ **Purpose:** Performance optimization
1119
+
1120
+ **CLI Syntax:**
1121
+ ```bash
1122
+ tapps-agents improver optimize <file> "<instructions>" [--format json|text]
1123
+ ```
1124
+
1125
+ #### `*refactor` / `refactor` (CLI-First)
1126
+ **Purpose:** Code refactoring
1127
+
1128
+ **CLI Syntax:**
1129
+ ```bash
1130
+ tapps-agents improver refactor <file> "<instructions>" [--format json|text]
1131
+ ```
1132
+
1133
+ ### Ops Agent (`@ops`)
1134
+
1135
+ **Available Commands:**
1136
+
1137
+ #### `*audit-security` / `audit-security` (CLI-First)
1138
+ **Purpose:** Security audit
1139
+
1140
+ **CLI Syntax:**
1141
+ ```bash
1142
+ tapps-agents ops audit-security <target> [--format json|text]
1143
+ ```
1144
+
1145
+ #### `*check-compliance` / `check-compliance` (CLI-First)
1146
+ **Purpose:** Compliance checking
1147
+
1148
+ **CLI Syntax:**
1149
+ ```bash
1150
+ tapps-agents ops check-compliance [--standard <standard>] [--format json|text]
1151
+ ```
1152
+
1153
+ **Standards:** `GDPR`, `HIPAA`, `PCI-DSS`
1154
+
1155
+ #### `*audit-dependencies` / `audit-dependencies` (CLI-First)
1156
+ **Purpose:** Dependency vulnerability scanning
1157
+
1158
+ **CLI Syntax:**
1159
+ ```bash
1160
+ tapps-agents ops audit-dependencies [--format json|text]
1161
+ ```
1162
+
1163
+ #### `*plan-deployment` / `plan-deployment` (CLI-First)
1164
+ **Purpose:** Deployment planning
1165
+
1166
+ **CLI Syntax:**
1167
+ ```bash
1168
+ tapps-agents ops plan-deployment "<description>" [--format json|text]
1169
+ ```
1170
+
1171
+ #### `*audit-bundle` / `audit-bundle` (Dual-Mode)
1172
+ **Purpose:** Opt-in bundle size analysis for Node/React/Vue (dist/build/out). Best-effort; does not block on build failure.
1173
+ **CLI:** `tapps-agents ops audit-bundle` | **Cursor:** `@ops *audit-bundle`
1174
+
1175
+ ### Analyst Agent (`@analyst`)
1176
+
1177
+ **Available Commands:**
1178
+
1179
+ #### `*gather-requirements` / `gather-requirements` (Dual-Mode)
1180
+ **Purpose:** Gather and document requirements from description or stakeholder input
1181
+
1182
+ **CLI Syntax:**
1183
+ ```bash
1184
+ tapps-agents analyst gather-requirements "<description>" [--context "<context>"] [--output <file>] [--format json|text|markdown]
1185
+ ```
1186
+
1187
+ **Cursor Syntax:**
1188
+ ```cursor
1189
+ @analyst *gather-requirements "<description>"
1190
+ ```
1191
+
1192
+ **When to Use:**
1193
+ - ✅ **Extracting requirements** from stakeholder descriptions or user stories
1194
+ - ✅ **Creating requirements documents** (functional, non-functional, constraints)
1195
+ - ✅ **Requirements analysis and documentation** for project planning
1196
+ - ✅ **Requirements gathering** before implementation planning
1197
+
1198
+ **When NOT to Use:**
1199
+ - ❌ **Enhancing prompts for code generation** → Use `@enhancer *enhance` instead
1200
+ - ❌ **Creating implementation plans** → Use `@planner *plan` instead
1201
+ - ❌ **Generating code** → Use `@implementer *implement` instead
1202
+
1203
+ **Output:**
1204
+ - Generates structured markdown requirements document
1205
+ - Includes functional requirements, non-functional requirements, constraints, assumptions, and open questions
1206
+ - Saves to specified output file (default: `requirements.md`)
1207
+
1208
+ **Examples:**
1209
+ ```bash
1210
+ # Gather requirements from description
1211
+ tapps-agents analyst gather-requirements "Enhance service details popup with health status" --output requirements.md
1212
+
1213
+ # With context
1214
+ tapps-agents analyst gather-requirements "Add user authentication" --context "Existing FastAPI application" --output docs/requirements.md
1215
+ ```
1216
+
1217
+ #### `*analyze-stakeholders` / `stakeholder-analysis` (Dual-Mode)
1218
+ **Purpose:** Analyze stakeholders and their needs
1219
+
1220
+ **CLI Syntax:**
1221
+ ```bash
1222
+ tapps-agents analyst stakeholder-analysis "<description>" [--stakeholders <stakeholder>...] [--format json|text]
1223
+ ```
1224
+
1225
+ **Cursor Syntax:**
1226
+ ```cursor
1227
+ @analyst *analyze-stakeholders "<description>"
1228
+ ```
1229
+
1230
+ #### `*research-technology` / `tech-research` (Dual-Mode)
1231
+ **Purpose:** Research technology options for a requirement
1232
+
1233
+ **CLI Syntax:**
1234
+ ```bash
1235
+ tapps-agents analyst tech-research "<requirement>" [--context "<context>"] [--criteria <criteria>...] [--format json|text]
1236
+ ```
1237
+
1238
+ **Cursor Syntax:**
1239
+ ```cursor
1240
+ @analyst *research-technology "<requirement>"
1241
+ ```
1242
+
1243
+ #### `*estimate-effort` / `estimate-effort` (Dual-Mode)
1244
+ **Purpose:** Estimate effort and complexity for a feature
1245
+
1246
+ **CLI Syntax:**
1247
+ ```bash
1248
+ tapps-agents analyst estimate-effort "<feature_description>" [--context "<context>"] [--format json|text]
1249
+ ```
1250
+
1251
+ **Cursor Syntax:**
1252
+ ```cursor
1253
+ @analyst *estimate-effort "<feature_description>"
1254
+ ```
1255
+
1256
+ #### `*assess-risk` / `assess-risk` (Dual-Mode)
1257
+ **Purpose:** Assess risks for a feature or project
1258
+
1259
+ **CLI Syntax:**
1260
+ ```bash
1261
+ tapps-agents analyst assess-risk "<feature_description>" [--context "<context>"] [--format json|text]
1262
+ ```
1263
+
1264
+ **Cursor Syntax:**
1265
+ ```cursor
1266
+ @analyst *assess-risk "<feature_description>"
1267
+ ```
1268
+
1269
+ #### `*competitive-analysis` / `competitive-analysis` (Dual-Mode)
1270
+ **Purpose:** Perform competitive analysis
1271
+
1272
+ **CLI Syntax:**
1273
+ ```bash
1274
+ tapps-agents analyst competitive-analysis "<product_description>" [--competitors <competitor>...] [--format json|text]
1275
+ ```
1276
+
1277
+ **Cursor Syntax:**
1278
+ ```cursor
1279
+ @analyst *competitive-analysis "<product_description>"
1280
+ ```
1281
+
1282
+ ### Orchestrator Agent (`@orchestrator`)
1283
+
1284
+ **Available Commands:**
1285
+
1286
+ #### `*orchestrate` / `orchestrate` (CLI-First)
1287
+ **Purpose:** Execute YAML workflow
1288
+
1289
+ **CLI Syntax:**
1290
+ ```bash
1291
+ tapps-agents orchestrator orchestrate <workflow.yaml> [--format json|text]
1292
+ ```
1293
+
1294
+ #### `*sequence` / `sequence` (CLI-First)
1295
+ **Purpose:** Sequence multiple agents
1296
+
1297
+ **CLI Syntax:**
1298
+ ```bash
1299
+ tapps-agents orchestrator sequence "<agent-list>" [--format json|text]
1300
+ ```
1301
+
1302
+ **Example:** `"plan,design,implement,test"`
1303
+
1304
+ ### Evaluator Agent (`@evaluator`)
1305
+
1306
+ **Available Commands:**
1307
+
1308
+ #### `*evaluate` / `evaluate` (Dual-Mode)
1309
+ **Purpose:** Evaluate TappsCodingAgents framework effectiveness
1310
+
1311
+ **CLI Syntax:**
1312
+ ```bash
1313
+ tapps-agents evaluator evaluate [--workflow-id <id>] [--format json|text]
1314
+ ```
1315
+
1316
+ **Cursor Syntax:**
1317
+ ```cursor
1318
+ @evaluator *evaluate
1319
+ @evaluator *evaluate --workflow-id workflow-123
1320
+ ```
1321
+
1322
+ **Parameters:**
1323
+ - `--workflow-id` (optional): Evaluate specific workflow execution
1324
+ - `--format`: Output format (`json` or `text`)
1325
+
1326
+ **Output:**
1327
+ - Structured evaluation report saved to `.tapps-agents/evaluations/`
1328
+ - Report includes: usage statistics, workflow adherence, quality metrics, recommendations
1329
+
1330
+ #### `*evaluate-workflow` / `evaluate-workflow` (Dual-Mode)
1331
+ **Purpose:** Evaluate a specific workflow execution
1332
+
1333
+ **CLI Syntax:**
1334
+ ```bash
1335
+ tapps-agents evaluator evaluate-workflow <workflow_id> [--format json|text]
1336
+ ```
1337
+
1338
+ **Cursor Syntax:**
1339
+ ```cursor
1340
+ @evaluator *evaluate-workflow workflow-123
1341
+ ```
1342
+
1343
+ **When to Use:**
1344
+ - After completing a workflow to assess adherence
1345
+ - To identify gaps between intended and actual usage
1346
+ - For continuous improvement analysis
1347
+
1348
+ ## Simple Mode Workflows
1349
+
1350
+ Simple Mode provides natural language orchestration with structured workflows. Use `@simple-mode` in Cursor chat. **Simple Mode is installed by `tapps-agents init`** - the skill and rule files are automatically set up.
1351
+
1352
+ ### Build Workflow (`*build`)
1353
+
1354
+ **Purpose:** Build new features with complete 7-step workflow. **This is the most commonly used Simple Mode command.**
1355
+
1356
+ **Cursor Syntax:**
1357
+ ```cursor
1358
+ @simple-mode *build "Create a user authentication feature"
1359
+ ```
1360
+
1361
+ **When to Use:**
1362
+ - Creating new features from scratch
1363
+ - Implementing user stories
1364
+ - Adding new functionality to existing projects
1365
+ - Greenfield development
1366
+
1367
+ **Workflow Steps (MUST FOLLOW ALL STEPS):**
1368
+ 1. **@enhancer *enhance** - Enhanced prompt with requirements analysis (7-stage pipeline)
1369
+ - Creates: `docs/workflows/simple-mode/step1-enhanced-prompt.md`
1370
+ - Output: Comprehensive specification with requirements, architecture guidance, quality standards
1371
+ 2. **@planner *plan** - User stories with acceptance criteria
1372
+ - Creates: `docs/workflows/simple-mode/step2-user-stories.md`
1373
+ - Output: User stories, story points, estimates
1374
+ 3. **@architect *design** - System architecture design
1375
+ - Creates: `docs/workflows/simple-mode/step3-architecture.md`
1376
+ - Output: Architecture, component design, data flow, performance considerations
1377
+ 4. **@designer *design-api** - Component design specifications
1378
+ - Creates: `docs/workflows/simple-mode/step4-design.md`
1379
+ - Output: API specifications, data models, component designs
1380
+ 5. **@implementer *implement** - Code implementation
1381
+ - Uses: All specifications from previous steps
1382
+ - Output: Implemented code following design system and architecture
1383
+ 6. **@reviewer *review** - Code quality review (with scores)
1384
+ - Creates: `docs/workflows/simple-mode/step6-review.md`
1385
+ - Output: Quality scores (7 categories: complexity, security, maintainability, test coverage, performance, structure, devex), issues found, recommendations
1386
+ 7. **@tester *test** - Testing plan and validation
1387
+ - Creates: `docs/workflows/simple-mode/step7-testing.md`
1388
+ - Output: Test plan, test cases, validation criteria
1389
+
1390
+ **Documentation Created:**
1391
+ - `docs/workflows/simple-mode/step1-enhanced-prompt.md`
1392
+ - `docs/workflows/simple-mode/step2-user-stories.md`
1393
+ - `docs/workflows/simple-mode/step3-architecture.md`
1394
+ - `docs/workflows/simple-mode/step4-design.md`
1395
+ - `docs/workflows/simple-mode/step6-review.md`
1396
+ - `docs/workflows/simple-mode/step7-testing.md`
1397
+
1398
+ **Quality Gates:**
1399
+ - Overall score must be ≥ 70 (configurable)
1400
+ - Security score must be ≥ 6.5
1401
+ - If thresholds not met, workflow loops back to improve code
1402
+
1403
+ ### Review Workflow (`*review`)
1404
+
1405
+ **Purpose:** Code quality review with improvement suggestions
1406
+
1407
+ **Cursor Syntax:**
1408
+ ```cursor
1409
+ @simple-mode *review <file>
1410
+ ```
1411
+
1412
+ **When to Use:**
1413
+ - Before committing code
1414
+ - Code quality audits
1415
+ - Pre-PR reviews
1416
+ - Learning best practices
1417
+
1418
+ **Workflow Steps:**
1419
+ 1. **@reviewer *review** - Quality scores (7 categories: complexity, security, maintainability, test coverage, performance, structure, devex)
1420
+ 2. **@improver *improve** - Improvement suggestions (if issues found or score < threshold)
1421
+
1422
+ **Output:**
1423
+ - Quality scores for all 7 categories
1424
+ - Detailed feedback on issues
1425
+ - Improvement suggestions (if needed)
1426
+
1427
+ ### Fix Workflow (`*fix`)
1428
+
1429
+ **Purpose:** Fix bugs and errors with systematic debugging
1430
+
1431
+ **Cursor Syntax:**
1432
+ ```cursor
1433
+ @simple-mode *fix <file> "<description>"
1434
+ ```
1435
+
1436
+ **When to Use:**
1437
+ - Debugging runtime errors
1438
+ - Fixing bugs reported by users
1439
+ - Resolving test failures
1440
+ - Correcting logic errors
1441
+
1442
+ **Workflow Steps:**
1443
+ 1. **@debugger *debug** - Root cause analysis
1444
+ - Analyzes error message, stack trace, code context
1445
+ - Identifies root cause and suggests fix
1446
+ 2. **@implementer *refactor** - Fix applied
1447
+ - Implements the fix based on debugger analysis
1448
+ 3. **@tester *test** - Verification
1449
+ - Generates/updates tests to verify fix
1450
+ - Ensures fix doesn't break existing functionality
1451
+
1452
+ ### Test Workflow (`*test`)
1453
+
1454
+ **Purpose:** Generate comprehensive tests for code
1455
+
1456
+ **Cursor Syntax:**
1457
+ ```cursor
1458
+ @simple-mode *test <file>
1459
+ ```
1460
+
1461
+ **When to Use:**
1462
+ - After implementing features
1463
+ - To improve test coverage
1464
+ - When user asks for tests
1465
+ - Test-driven development
1466
+
1467
+ **Workflow Steps:**
1468
+ 1. **@tester *test** - Tests generated and executed
1469
+ - Analyzes code structure
1470
+ - Generates unit tests
1471
+ - Optionally generates integration tests
1472
+ - Runs tests and reports coverage
1473
+
1474
+ ### Epic Workflow (`*epic`)
1475
+
1476
+ **Purpose:** Execute all stories in an Epic document in dependency order
1477
+
1478
+ **Cursor Syntax:**
1479
+ ```cursor
1480
+ @simple-mode *epic <epic-doc.md> [--quality-threshold 70] [--auto-mode]
1481
+ ```
1482
+
1483
+ **When to Use:**
1484
+ - Implementing entire Epic documents
1485
+ - Executing multiple related stories
1486
+ - Large feature development
1487
+ - Project milestones
1488
+
1489
+ **Workflow Steps:**
1490
+ 1. Parse Epic document (extract stories, dependencies, acceptance criteria)
1491
+ 2. Resolve story dependencies (topological sort)
1492
+ 3. Execute each story in order:
1493
+ - Create workflow for story
1494
+ - Execute with quality gates
1495
+ - Loopback if quality < threshold (max 3 iterations)
1496
+ 4. Track progress across all stories
1497
+ 5. Generate Epic completion report
1498
+
1499
+ **Parameters:**
1500
+ - `epic-doc.md` (required): Path to Epic markdown document
1501
+ - `--quality-threshold`: Minimum quality score (default: 70)
1502
+ - `--critical-service-threshold`: Minimum for critical services (default: 80)
1503
+ - `--auto-mode`: Fully automated execution
1504
+
1505
+ **Example:**
1506
+ ```cursor
1507
+ @simple-mode *epic docs/prd/epic-51-yaml-automation-quality-enhancement.md
1508
+ ```
1509
+
1510
+ **Output:**
1511
+ - Execution report with completion percentage
1512
+ - Story-by-story results
1513
+ - Quality gate status
1514
+ - Report saved to `docs/prd/epic-{number}-report.json`
1515
+
1516
+ ### Test Coverage Workflow (`*test-coverage`)
1517
+
1518
+ **Purpose:** Generate tests targeting specific uncovered code paths
1519
+
1520
+ **Cursor Syntax:**
1521
+ ```cursor
1522
+ @simple-mode *test-coverage <file> --target 80
1523
+ ```
1524
+
1525
+ **When to Use:**
1526
+ - Improving test coverage
1527
+ - Targeting uncovered code paths
1528
+ - Coverage-driven test development
1529
+
1530
+ **Workflow Steps:**
1531
+ 1. Analyze coverage data (from `coverage.json`)
1532
+ 2. Identify uncovered code paths
1533
+ 3. Prioritize gaps (critical paths, error handling, public APIs)
1534
+ 4. Generate targeted tests for uncovered code
1535
+ 5. Verify coverage improvement
1536
+
1537
+ ### TDD Workflow (`*tdd`)
1538
+
1539
+ **Purpose:** Test-driven development: Red-Green-Refactor with coverage ≥80%
1540
+
1541
+ **Cursor Syntax:**
1542
+ ```cursor
1543
+ @simple-mode *tdd {file}
1544
+ @simple-mode *tdd "<description>"
1545
+ ```
1546
+
1547
+ **Workflow Steps:** Define interfaces → failing tests (RED) → minimal code (GREEN) → refactor (IMPROVE) → @tester *test for coverage.
1548
+
1549
+ ### E2E Workflow (`*e2e`)
1550
+
1551
+ **Purpose:** Generate and run E2E tests; Playwright MCP for execution when available
1552
+
1553
+ **Cursor Syntax:**
1554
+ ```cursor
1555
+ @simple-mode *e2e [path]
1556
+ ```
1557
+
1558
+ **Workflow Steps:** @tester *generate-e2e-tests → run via Playwright MCP if available → report.
1559
+
1560
+ ### Build Fix Workflow (`*build-fix`)
1561
+
1562
+ **Purpose:** Fix build/compile errors (Python, npm, tsc, cargo). Distinct from *fix (runtime) and *fix-tests.
1563
+
1564
+ **Cursor Syntax:**
1565
+ ```cursor
1566
+ @simple-mode *build-fix "<build-output or description>"
1567
+ ```
1568
+
1569
+ **Workflow Steps:** Parse errors → @debugger *debug → @implementer *refactor → re-run build to verify.
1570
+
1571
+ ### Refactor Clean Workflow (`*refactor-clean`)
1572
+
1573
+ **Purpose:** Mechanical cleanup: unused imports, dead code, duplication. Use *refactor for design changes.
1574
+
1575
+ **Cursor Syntax:**
1576
+ ```cursor
1577
+ @simple-mode *refactor-clean {file}
1578
+ ```
1579
+
1580
+ **Workflow Steps:** @reviewer *duplication and/or Ruff → @implementer *refactor for cleanup.
1581
+
1582
+ ### Update Docs Workflow (`*update-docs`)
1583
+
1584
+ **Purpose:** Sync documentation with code
1585
+
1586
+ **Cursor Syntax:**
1587
+ ```cursor
1588
+ @simple-mode *update-docs [path]
1589
+ ```
1590
+
1591
+ **Workflow Steps:** @documenter *document or *document-api → sync README or docs/ if project scripts exist.
1592
+
1593
+ ### Update Codemaps Workflow (`*update-codemaps`)
1594
+
1595
+ **Purpose:** Refresh codemap/context index (e.g. Context7 cache)
1596
+
1597
+ **Cursor Syntax:**
1598
+ ```cursor
1599
+ @simple-mode *update-codemaps
1600
+ ```
1601
+
1602
+ **Workflow Steps:** Refresh project index; if Context7: @reviewer *docs-refresh or project cache refresh.
1603
+
1604
+ ### Security Review Workflow (`*security-review`)
1605
+
1606
+ **Purpose:** Structured security check: reviewer + ops + OWASP-style checklist
1607
+
1608
+ **Cursor Syntax:**
1609
+ ```cursor
1610
+ @simple-mode *security-review [path]
1611
+ ```
1612
+
1613
+ **Workflow Steps:** @reviewer *review (security, bandit) → @ops *audit-security → OWASP-style checklist; summarize and remediation hints.
1614
+
1615
+ ### Fix Tests Workflow (`*fix-tests`)
1616
+
1617
+ **Purpose:** Analyze test failures and automatically fix common patterns
1618
+
1619
+ **Cursor Syntax:**
1620
+ ```cursor
1621
+ @simple-mode *fix-tests <test-file>
1622
+ ```
1623
+
1624
+ **When to Use:**
1625
+ - Test failures after code changes
1626
+ - Async/await migration issues
1627
+ - Mock configuration errors
1628
+ - Import path issues
1629
+
1630
+ **Supported Patterns:**
1631
+ - `async`: TestClient → AsyncClient migration, missing await
1632
+ - `auth`: Authentication header issues
1633
+ - `mock`: Mock configuration errors
1634
+ - `import`: Import path issues
1635
+
1636
+ ### Microservice Workflow (`*microservice`)
1637
+
1638
+ **Purpose:** Generate complete microservice structure with Docker, tests, and health checks
1639
+
1640
+ **Cursor Syntax:**
1641
+ ```cursor
1642
+ @simple-mode *microservice <name> --port <port> --type <fastapi|flask|homeiq>
1643
+ ```
1644
+
1645
+ **When to Use:**
1646
+ - Creating new microservices
1647
+ - Service scaffolding
1648
+ - Docker-based services
1649
+
1650
+ **What It Generates:**
1651
+ - Service structure (`src/`, `tests/`, `Dockerfile`, `requirements.txt`)
1652
+ - Docker Compose integration
1653
+ - Health check endpoints
1654
+ - Logging configuration
1655
+ - API router structure
1656
+ - Test scaffolding
1657
+ - README with service docs
1658
+
1659
+ ### Docker Fix Workflow (`*docker-fix`)
1660
+
1661
+ **Purpose:** Debug container errors with automatic fix suggestions
1662
+
1663
+ **Cursor Syntax:**
1664
+ ```cursor
1665
+ @simple-mode *docker-fix <service> "<error>"
1666
+ ```
1667
+
1668
+ **When to Use:**
1669
+ - Container startup failures
1670
+ - Docker build errors
1671
+ - Runtime container issues
1672
+
1673
+ **Features:**
1674
+ - Analyzes container logs
1675
+ - Matches errors to known patterns
1676
+ - Checks Dockerfile for issues
1677
+ - Suggests fixes with confidence scores
1678
+ - Auto-applies high-confidence fixes (>95%)
1679
+
1680
+ ### Service Integration Workflow (`*integrate-service`)
1681
+
1682
+ **Purpose:** Automate service-to-service integration (client classes, config, DI)
1683
+
1684
+ **Cursor Syntax:**
1685
+ ```cursor
1686
+ @simple-mode *integrate-service <service1> --with <service2>
1687
+ ```
1688
+
1689
+ **When to Use:**
1690
+ - Integrating microservices
1691
+ - Service-to-service communication setup
1692
+ - Client class generation
1693
+
1694
+ **What It Does:**
1695
+ - Generates HTTP client classes for target service
1696
+ - Updates config files with service URLs
1697
+ - Adds dependency injection setup
1698
+ - Updates docker-compose.yml with service dependencies
1699
+ - Generates integration tests
1700
+ - Updates API documentation
1701
+
1702
+ ### Full SDLC Workflow (`*full`)
1703
+
1704
+ **Purpose:** Complete software development lifecycle with all quality gates
1705
+
1706
+ **Cursor Syntax:**
1707
+ ```cursor
1708
+ @simple-mode *full "<description>"
1709
+ ```
1710
+
1711
+ **When to Use:**
1712
+ - Enterprise projects
1713
+ - Mission-critical features
1714
+ - Complete application development
1715
+ - Full lifecycle management
1716
+
1717
+ **Workflow Steps:**
1718
+ 1. **@analyst *gather-requirements** - Requirements gathering
1719
+ 2. **@planner *plan** - User stories
1720
+ 3. **@architect *design** - Architecture design
1721
+ 4. **@designer *design-api** - API design
1722
+ 5. **@implementer *implement** - Code implementation
1723
+ 6. **@reviewer *review** - Quality review (loop if < 70)
1724
+ 7. **@tester *test** - Test generation
1725
+ 8. **@ops *security-scan** - Security scanning
1726
+ 9. **@documenter *document-api** - Documentation
1727
+
1728
+ **Features:**
1729
+ - Automatic loopbacks if code quality scores aren't good enough
1730
+ - Test execution with retry logic
1731
+ - Security validation with remediation
1732
+ - Final quality review before completion
1733
+
1734
+ **⚠️ CRITICAL: Framework Development MUST Use Full SDLC**
1735
+
1736
+ When modifying the **TappsCodingAgents framework itself** (`tapps_agents/` package), you **MUST** use this workflow:
1737
+
1738
+ ```bash
1739
+ # CLI
1740
+ tapps-agents simple-mode full --prompt "Implement [enhancement description]" --auto
1741
+
1742
+ # Or in Cursor chat
1743
+ @simple-mode *full "Implement [enhancement description]"
1744
+ ```
1745
+
1746
+ **Why?** Framework changes require:
1747
+ - ✅ Requirements analysis before implementation
1748
+ - ✅ Architecture design for integration patterns
1749
+ - ✅ Quality gates (≥75 score) with automatic loopbacks
1750
+ - ✅ Test generation and execution
1751
+ - ✅ Security validation
1752
+ - ✅ Complete documentation
1753
+ - ✅ Full traceability
1754
+
1755
+ **DO NOT skip the workflow for framework changes!** See `.cursor/rules/project-context.mdc` for details.
1756
+
1757
+ ### Natural Language Intent Detection
1758
+
1759
+ Simple Mode automatically detects intent from keywords:
1760
+
1761
+ - **Build**: build, create, make, generate, add, implement, develop, write, new, feature
1762
+ - **Review**: review, check, analyze, inspect, examine, score, quality, audit, assess, evaluate
1763
+ - **Fix**: fix, repair, resolve, debug, error, bug, issue, problem, broken, correct
1764
+ - **Test**: test, verify, validate, coverage, testing, tests
1765
+ - **Epic**: epic, implement epic, execute epic, run epic, story, stories
1766
+ - **Full**: full, complete, sdlc, lifecycle, everything
1767
+
1768
+ **Examples:**
1769
+ ```cursor
1770
+ @simple-mode Build a user authentication feature
1771
+ @simple-mode Review my authentication code
1772
+ @simple-mode Fix the error in auth.py
1773
+ @simple-mode Add tests for service.py
1774
+ @simple-mode Execute epic docs/prd/epic-51.md
1775
+ ```
1776
+
1777
+ ### Simple Mode Configuration
1778
+
1779
+ Simple Mode is configured in `.tapps-agents/config.yaml` (created by `init`):
1780
+
1781
+ ```yaml
1782
+ simple_mode:
1783
+ enabled: true # Enable Simple Mode (default: true after init)
1784
+ auto_detect: true # Auto-detect intent from natural language
1785
+ show_advanced: false # Hide advanced features initially
1786
+ natural_language: true # Enable natural language commands
1787
+ default_orchestrator: "build" # Default when intent is ambiguous
1788
+ onboarding_enabled: true # Enable onboarding wizard
1789
+ progressive_disclosure_enabled: true # Gradually reveal advanced features
1790
+ ```
1791
+
1792
+ **After `init`, Simple Mode is:**
1793
+ - ✅ Skill installed (`.claude/skills/simple-mode/`)
1794
+ - ✅ Rule installed (`.cursor/rules/simple-mode.mdc`)
1795
+ - ✅ Enabled by default in config
1796
+ - ✅ Ready to use in Cursor chat
1797
+
1798
+ **To verify Simple Mode is ready:**
1799
+ ```bash
1800
+ tapps-agents simple-mode status
1801
+ ```
1802
+
1803
+ **To enable/configure:**
1804
+ ```bash
1805
+ tapps-agents simple-mode on # Enable (usually already enabled after init)
1806
+ tapps-agents simple-mode init # Run onboarding wizard
1807
+ tapps-agents simple-mode configure # Configure settings
1808
+ ```
1809
+
1810
+ ## Command Help
1811
+
1812
+ ### Get Agent Help
1813
+
1814
+ **CLI:**
1815
+ ```bash
1816
+ tapps-agents <agent> help
1817
+ tapps-agents <agent> *help
1818
+ ```
1819
+
1820
+ **Cursor:**
1821
+ ```cursor
1822
+ @reviewer *help
1823
+ @simple-mode *help
1824
+ ```
1825
+
1826
+ ### General Help
1827
+
1828
+ **CLI:**
1829
+ ```bash
1830
+ tapps-agents --help
1831
+ tapps-agents <command> --help
1832
+ ```
1833
+
1834
+ ## Configuration
1835
+
1836
+ Commands are configured in `.tapps-agents/config.yaml`:
1837
+
1838
+ ```yaml
1839
+ agents:
1840
+ reviewer:
1841
+ quality_threshold: 70
1842
+ security_threshold: 7.0
1843
+ maintainability_threshold: 7.0
1844
+
1845
+ implementer:
1846
+ require_review: true
1847
+ auto_approve_threshold: 80.0
1848
+ backup_files: true
1849
+
1850
+ tester:
1851
+ coverage_threshold: 80.0
1852
+ generate_integration_tests: true
1853
+
1854
+ simple_mode:
1855
+ enabled: true
1856
+ auto_detect: true
1857
+ show_advanced: false
1858
+ natural_language: true
1859
+ ```
1860
+
1861
+ ## Guide for Cursor: When and Why to Use tapps-agents
1862
+
1863
+ This section helps Cursor AI understand when to suggest or use tapps-agents commands during development.
1864
+
1865
+ ### Always Use tapps-agents For:
1866
+
1867
+ 1. **Code Quality Checks**
1868
+ - **When**: Before committing code, reviewing PRs, or when user asks about code quality
1869
+ - **Why**: Provides objective metrics and AI-powered feedback
1870
+ - **Commands**: `@reviewer *review`, `@reviewer *score`, `@reviewer *lint`, `@reviewer *type-check`
1871
+ - **Example**: User says "Is this code good?" → Use `@reviewer *review <file>`
1872
+
1873
+ 2. **Code Generation**
1874
+ - **When**: User asks to implement features, create new files, or generate code
1875
+ - **Why**: Follows project patterns, includes tests, meets quality standards
1876
+ - **Commands**: `@implementer *implement`, `@simple-mode *build`
1877
+ - **Example**: User says "Add user authentication" → Use `@simple-mode *build "Add user authentication"`
1878
+
1879
+ 3. **Bug Fixing**
1880
+ - **When**: User reports errors, exceptions, or bugs
1881
+ - **Why**: Systematic debugging with root cause analysis
1882
+ - **Commands**: `@debugger *debug`, `@simple-mode *fix`
1883
+ - **Example**: User says "Fix the error in auth.py" → Use `@simple-mode *fix src/auth.py "Fix the error"`
1884
+
1885
+ 4. **Testing**
1886
+ - **When**: After implementing features, when user asks for tests, or to improve coverage
1887
+ - **Why**: Generates comprehensive tests following project patterns
1888
+ - **Commands**: `@tester *test`, `@tester *generate-tests`
1889
+ - **Example**: User says "Add tests for this" → Use `@tester *test <file>`
1890
+
1891
+ 5. **Documentation**
1892
+ - **When**: User asks for documentation, or after implementing features
1893
+ - **Why**: Maintains consistent documentation standards
1894
+ - **Commands**: `@documenter *document`, `@documenter *document-api`
1895
+ - **Example**: User says "Document this API" → Use `@documenter *document-api <file>`
1896
+
1897
+ 6. **Library Documentation Lookup**
1898
+ - **When**: User asks "How do I use X library?" or needs API reference
1899
+ - **Why**: Provides up-to-date library documentation from Context7
1900
+ - **Commands**: `@reviewer *docs <library> [topic]`
1901
+ - **Example**: User says "How do I use FastAPI routing?" → Use `@reviewer *docs fastapi routing`
1902
+
1903
+ 7. **Project Setup**
1904
+ - **When**: User is setting up a new project or adding tapps-agents to existing project
1905
+ - **Why**: Enables all tapps-agents capabilities in Cursor
1906
+ - **Commands**: `tapps-agents init`
1907
+ - **Example**: User says "Set up tapps-agents" → Suggest `tapps-agents init`
1908
+
1909
+ ### Command Selection Guide
1910
+
1911
+ **For Interactive Development (Cursor Chat):**
1912
+ - Prefer Cursor Skills syntax: `@agent-name *command`
1913
+ - Use Simple Mode for complex workflows: `@simple-mode *build`
1914
+ - Natural language works: `@simple-mode Build a user authentication feature`
1915
+
1916
+ **For Batch/Automation (Terminal/CI):**
1917
+ - Use CLI commands: `tapps-agents <agent> <command>`
1918
+ - Use `--auto` flag for non-interactive execution
1919
+ - Use `--format json` for programmatic processing
1920
+
1921
+ **For Quality Gates:**
1922
+ - Use `@reviewer *score` for quick checks
1923
+ - Use `@reviewer *review` for comprehensive analysis
1924
+ - Use `--fail-under` in CI/CD to enforce thresholds
1925
+
1926
+ **For Feature Development:**
1927
+ - Use `@simple-mode *build` for complete feature workflow
1928
+ - Use `@planner *plan` for planning phase
1929
+ - Use `@architect *design` for architecture decisions
1930
+
1931
+ **For Bug Fixes:**
1932
+ - Use `@simple-mode *fix` for complete fix workflow
1933
+ - Use `@debugger *debug` for error analysis
1934
+ - Use `@tester *test` for verification
1935
+
1936
+ ### Parameter Selection Guide
1937
+
1938
+ **Output Formats:**
1939
+ - `json`: CI/CD, automation, programmatic processing
1940
+ - `text`: Human-readable terminal output
1941
+ - `markdown`: Documentation, reports, PR comments
1942
+ - `html`: Web-based reports, sharing with team
1943
+
1944
+ **Batch Processing:**
1945
+ - Use `--pattern` for glob patterns across project
1946
+ - Use `--max-workers` to balance speed vs. resources
1947
+ - Use multiple files for targeted batch operations
1948
+
1949
+ **Automation:**
1950
+ - Use `--auto` for fully automated workflows
1951
+ - Use `--yes` for non-interactive commands
1952
+ - Use `--format json` for structured output
1953
+
1954
+ **Quality Gates:**
1955
+ - Use `--fail-under` to enforce minimum scores
1956
+ - Use `--fail-on-issues` to fail on lint errors
1957
+ - Use `--coverage` to require test coverage
1958
+
1959
+ ### Common Workflows
1960
+
1961
+ **New Feature Development:**
1962
+ 1. `@simple-mode *build "<description>"` - Complete workflow
1963
+ 2. Or step-by-step: `@planner *plan` → `@architect *design` → `@implementer *implement` → `@reviewer *review` → `@tester *test`
1964
+
1965
+ **Code Review:**
1966
+ 1. `@reviewer *score <file>` - Quick quality check
1967
+ 2. `@reviewer *review <file>` - Comprehensive analysis
1968
+ 3. `@improver *improve <file> "<issues>"` - Apply improvements
1969
+
1970
+ **Bug Fixing:**
1971
+ 1. `@simple-mode *fix <file> "<description>"` - Complete workflow
1972
+ 2. Or step-by-step: `@debugger *debug` → `@implementer *refactor` → `@tester *test`
1973
+
1974
+ **Testing:**
1975
+ 1. `@tester *test <file>` - Generate and run tests
1976
+ 2. `@tester *generate-tests <file>` - Generate without running
1977
+ 3. `@tester *run-tests` - Run existing test suite
1978
+
1979
+ ## Windows Compatibility & Encoding Requirements
1980
+
1981
+ **⚠️ CRITICAL: All scripts and code must work correctly on Windows**
1982
+
1983
+ This project is developed and tested on **Windows** (in addition to Linux/macOS). When creating or modifying Python scripts, you MUST handle Windows-specific encoding issues correctly.
1984
+
1985
+ ### Windows Encoding Requirements
1986
+
1987
+ **All Python scripts MUST:**
1988
+
1989
+ 1. **Set UTF-8 encoding for console output** (Windows uses CP1252 by default):
1990
+ ```python
1991
+ import sys
1992
+ import os
1993
+
1994
+ # Set UTF-8 encoding for Windows console
1995
+ if sys.platform == "win32":
1996
+ os.environ["PYTHONIOENCODING"] = "utf-8"
1997
+ try:
1998
+ sys.stdout.reconfigure(encoding="utf-8")
1999
+ sys.stderr.reconfigure(encoding="utf-8")
2000
+ except AttributeError:
2001
+ # Python < 3.7 - use environment variable only
2002
+ pass
2003
+ ```
2004
+
2005
+ 2. **Use ASCII-safe fallbacks for Unicode characters**:
2006
+ ```python
2007
+ # Use ASCII-safe symbols instead of Unicode emojis
2008
+ SUCCESS_SYMBOL = "[OK]"
2009
+ ERROR_SYMBOL = "[FAIL]"
2010
+ WARNING_SYMBOL = "[WARN]"
2011
+
2012
+ # Or handle UnicodeEncodeError gracefully
2013
+ try:
2014
+ print(f"{GREEN}✅ {text}{RESET}")
2015
+ except UnicodeEncodeError:
2016
+ print(f"[OK] {text}")
2017
+ ```
2018
+
2019
+ 3. **Always specify encoding when opening files**:
2020
+ ```python
2021
+ # ✅ CORRECT - Always specify encoding
2022
+ with open("file.txt", "r", encoding="utf-8") as f:
2023
+ content = f.read()
2024
+
2025
+ # Using pathlib (also specify encoding)
2026
+ content = Path("file.txt").read_text(encoding="utf-8")
2027
+
2028
+ # ❌ WRONG - Relies on system default (CP1252 on Windows)
2029
+ with open("file.txt", "r") as f:
2030
+ content = f.read()
2031
+ ```
2032
+
2033
+ 4. **Specify encoding for subprocess output**:
2034
+ ```python
2035
+ # ✅ CORRECT - Specify encoding and error handling
2036
+ result = subprocess.run(
2037
+ cmd,
2038
+ capture_output=True,
2039
+ text=True,
2040
+ encoding="utf-8",
2041
+ errors="replace", # Replace invalid characters instead of failing
2042
+ )
2043
+
2044
+ # ❌ WRONG - May fail on Windows with non-ASCII output
2045
+ result = subprocess.run(cmd, capture_output=True, text=True)
2046
+ ```
2047
+
2048
+ ### Why This Matters
2049
+
2050
+ - **Windows default encoding is CP1252**, not UTF-8
2051
+ - **Unicode emojis (✅, ❌, ⚠️) fail on Windows** without proper encoding setup
2052
+ - **File I/O without explicit encoding** can cause `UnicodeDecodeError` on Windows
2053
+ - **GitHub Actions runs on Linux**, but developers use Windows - both must work
2054
+
2055
+ ### Testing on Windows
2056
+
2057
+ Before committing code that prints to console or reads files:
2058
+
2059
+ ```bash
2060
+ # Test script on Windows PowerShell
2061
+ python scripts/your_script.py
2062
+
2063
+ # Verify no encoding errors
2064
+ # Check that Unicode characters display correctly
2065
+ # Or use ASCII-safe alternatives
2066
+ ```
2067
+
2068
+ ### Reference
2069
+
2070
+ - [Python 3.10 Documentation - Windows Encoding](https://docs.python.org/3.10/library/sys.html)
2071
+ - [Python 3.10 Documentation - File Encoding](https://docs.python.org/3.10/library/io.html)
2072
+ - See `README.md` for complete Windows compatibility guidelines
2073
+
2074
+ ## Related Documentation
2075
+
2076
+ - **When to Use**: `.cursor/rules/when-to-use.mdc` — Importance and when to use each capability (workflows, agents, commands)
2077
+ - **Quick Reference**: `.cursor/rules/quick-reference.mdc`
2078
+ - **Agent Capabilities**: `.cursor/rules/agent-capabilities.mdc`
2079
+ - **Simple Mode Guide**: `.cursor/rules/simple-mode.mdc`
2080
+ - **Workflow Presets**: `.cursor/rules/workflow-presets.mdc`
2081
+ - **Command Reference**: `docs/TAPPS_AGENTS_COMMAND_REFERENCE.md`