mcp-ai-agent-guidelines 0.7.4 โ†’ 0.9.0

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 (195) hide show
  1. package/README.md +464 -164
  2. package/dist/index.js +298 -24
  3. package/dist/index.js.map +1 -1
  4. package/dist/prompts/index.d.ts.map +1 -1
  5. package/dist/prompts/index.js +83 -0
  6. package/dist/prompts/index.js.map +1 -1
  7. package/dist/resources/index.d.ts.map +1 -1
  8. package/dist/resources/index.js +6 -0
  9. package/dist/resources/index.js.map +1 -1
  10. package/dist/resources/structured.d.ts.map +1 -1
  11. package/dist/resources/structured.js +706 -2
  12. package/dist/resources/structured.js.map +1 -1
  13. package/dist/schemas/flow-tool-schemas.d.ts +23 -0
  14. package/dist/schemas/flow-tool-schemas.d.ts.map +1 -1
  15. package/dist/schemas/flow-tool-schemas.js +42 -7
  16. package/dist/schemas/flow-tool-schemas.js.map +1 -1
  17. package/dist/tools/analysis/gap-frameworks-analyzers.js +27 -7
  18. package/dist/tools/analysis/gap-frameworks-analyzers.js.map +1 -1
  19. package/dist/tools/analysis/strategy-frameworks-builder.js +22 -6
  20. package/dist/tools/analysis/strategy-frameworks-builder.js.map +1 -1
  21. package/dist/tools/bridge/semantic-analyzer-bridge.d.ts +35 -0
  22. package/dist/tools/bridge/semantic-analyzer-bridge.d.ts.map +1 -1
  23. package/dist/tools/bridge/semantic-analyzer-bridge.js +35 -0
  24. package/dist/tools/bridge/semantic-analyzer-bridge.js.map +1 -1
  25. package/dist/tools/clean-code-scorer.d.ts.map +1 -1
  26. package/dist/tools/clean-code-scorer.js +22 -6
  27. package/dist/tools/clean-code-scorer.js.map +1 -1
  28. package/dist/tools/code-hygiene-analyzer.d.ts.map +1 -1
  29. package/dist/tools/code-hygiene-analyzer.js +12 -4
  30. package/dist/tools/code-hygiene-analyzer.js.map +1 -1
  31. package/dist/tools/config/model-config.d.ts +2 -2
  32. package/dist/tools/config/model-config.d.ts.map +1 -1
  33. package/dist/tools/config/model-config.js +11 -205
  34. package/dist/tools/config/model-config.js.map +1 -1
  35. package/dist/tools/config/model-loader.d.ts +57 -0
  36. package/dist/tools/config/model-loader.d.ts.map +1 -0
  37. package/dist/tools/config/model-loader.js +97 -0
  38. package/dist/tools/config/model-loader.js.map +1 -0
  39. package/dist/tools/config/models.yaml +320 -0
  40. package/dist/tools/dependency-auditor.d.ts +7 -0
  41. package/dist/tools/dependency-auditor.d.ts.map +1 -0
  42. package/dist/tools/dependency-auditor.js +403 -0
  43. package/dist/tools/dependency-auditor.js.map +1 -0
  44. package/dist/tools/design/constraint-manager.d.ts +4 -4
  45. package/dist/tools/design/design-assistant.d.ts +2 -1
  46. package/dist/tools/design/design-assistant.d.ts.map +1 -1
  47. package/dist/tools/design/design-assistant.js +56 -1
  48. package/dist/tools/design/design-assistant.js.map +1 -1
  49. package/dist/tools/design/services/context-pattern-analyzer.service.d.ts +29 -0
  50. package/dist/tools/design/services/context-pattern-analyzer.service.d.ts.map +1 -0
  51. package/dist/tools/design/services/context-pattern-analyzer.service.js +861 -0
  52. package/dist/tools/design/services/context-pattern-analyzer.service.js.map +1 -0
  53. package/dist/tools/design/services/index.d.ts +1 -0
  54. package/dist/tools/design/services/index.d.ts.map +1 -1
  55. package/dist/tools/design/services/index.js +1 -0
  56. package/dist/tools/design/services/index.js.map +1 -1
  57. package/dist/tools/design/services/session-management.service.d.ts.map +1 -1
  58. package/dist/tools/design/services/session-management.service.js +15 -0
  59. package/dist/tools/design/services/session-management.service.js.map +1 -1
  60. package/dist/tools/guidelines-validator.d.ts.map +1 -1
  61. package/dist/tools/guidelines-validator.js +54 -12
  62. package/dist/tools/guidelines-validator.js.map +1 -1
  63. package/dist/tools/iterative-coverage-enhancer.d.ts.map +1 -1
  64. package/dist/tools/iterative-coverage-enhancer.js +37 -9
  65. package/dist/tools/iterative-coverage-enhancer.js.map +1 -1
  66. package/dist/tools/memory-context-optimizer.d.ts.map +1 -1
  67. package/dist/tools/memory-context-optimizer.js +17 -5
  68. package/dist/tools/memory-context-optimizer.js.map +1 -1
  69. package/dist/tools/mode-switcher.d.ts.map +1 -1
  70. package/dist/tools/mode-switcher.js +22 -6
  71. package/dist/tools/mode-switcher.js.map +1 -1
  72. package/dist/tools/project-onboarding.js +17 -5
  73. package/dist/tools/project-onboarding.js.map +1 -1
  74. package/dist/tools/prompt/architecture-design-prompt-builder.d.ts.map +1 -1
  75. package/dist/tools/prompt/architecture-design-prompt-builder.js +7 -3
  76. package/dist/tools/prompt/architecture-design-prompt-builder.js.map +1 -1
  77. package/dist/tools/prompt/code-analysis-prompt-builder.d.ts.map +1 -1
  78. package/dist/tools/prompt/code-analysis-prompt-builder.js +7 -3
  79. package/dist/tools/prompt/code-analysis-prompt-builder.js.map +1 -1
  80. package/dist/tools/prompt/debugging-assistant-prompt-builder.d.ts.map +1 -1
  81. package/dist/tools/prompt/debugging-assistant-prompt-builder.js +8 -4
  82. package/dist/tools/prompt/debugging-assistant-prompt-builder.js.map +1 -1
  83. package/dist/tools/prompt/digital-enterprise-architect-prompt-builder.d.ts +80 -0
  84. package/dist/tools/prompt/digital-enterprise-architect-prompt-builder.d.ts.map +1 -0
  85. package/dist/tools/prompt/digital-enterprise-architect-prompt-builder.js +284 -0
  86. package/dist/tools/prompt/digital-enterprise-architect-prompt-builder.js.map +1 -0
  87. package/dist/tools/prompt/documentation-generator-prompt-builder.d.ts.map +1 -1
  88. package/dist/tools/prompt/documentation-generator-prompt-builder.js +7 -3
  89. package/dist/tools/prompt/documentation-generator-prompt-builder.js.map +1 -1
  90. package/dist/tools/prompt/domain-neutral-prompt-builder.d.ts +5 -5
  91. package/dist/tools/prompt/enterprise-architect-prompt-builder.d.ts +95 -0
  92. package/dist/tools/prompt/enterprise-architect-prompt-builder.d.ts.map +1 -0
  93. package/dist/tools/prompt/enterprise-architect-prompt-builder.js +522 -0
  94. package/dist/tools/prompt/enterprise-architect-prompt-builder.js.map +1 -0
  95. package/dist/tools/prompt/hierarchical-prompt-builder.d.ts +17 -2
  96. package/dist/tools/prompt/hierarchical-prompt-builder.d.ts.map +1 -1
  97. package/dist/tools/prompt/hierarchical-prompt-builder.js +52 -273
  98. package/dist/tools/prompt/hierarchical-prompt-builder.js.map +1 -1
  99. package/dist/tools/prompt/hierarchy-level-selector.d.ts.map +1 -1
  100. package/dist/tools/prompt/hierarchy-level-selector.js +17 -5
  101. package/dist/tools/prompt/hierarchy-level-selector.js.map +1 -1
  102. package/dist/tools/prompt/l9-distinguished-engineer-prompt-builder.d.ts +95 -0
  103. package/dist/tools/prompt/l9-distinguished-engineer-prompt-builder.d.ts.map +1 -0
  104. package/dist/tools/prompt/l9-distinguished-engineer-prompt-builder.js +475 -0
  105. package/dist/tools/prompt/l9-distinguished-engineer-prompt-builder.js.map +1 -0
  106. package/dist/tools/prompt/prompt-chaining-builder.js +17 -5
  107. package/dist/tools/prompt/prompt-chaining-builder.js.map +1 -1
  108. package/dist/tools/prompt/prompt-flow-builder.js +22 -6
  109. package/dist/tools/prompt/prompt-flow-builder.js.map +1 -1
  110. package/dist/tools/prompt/prompting-hierarchy-evaluator.d.ts.map +1 -1
  111. package/dist/tools/prompt/prompting-hierarchy-evaluator.js +17 -5
  112. package/dist/tools/prompt/prompting-hierarchy-evaluator.js.map +1 -1
  113. package/dist/tools/prompt/security-hardening-prompt-builder.d.ts.map +1 -1
  114. package/dist/tools/prompt/security-hardening-prompt-builder.js +786 -21
  115. package/dist/tools/prompt/security-hardening-prompt-builder.js.map +1 -1
  116. package/dist/tools/prompt/spark-prompt-builder.d.ts +3 -3
  117. package/dist/tools/prompt/technique-applicator.d.ts +37 -0
  118. package/dist/tools/prompt/technique-applicator.d.ts.map +1 -0
  119. package/dist/tools/prompt/technique-applicator.js +353 -0
  120. package/dist/tools/prompt/technique-applicator.js.map +1 -0
  121. package/dist/tools/semantic-analyzer/analyzer.d.ts +17 -0
  122. package/dist/tools/semantic-analyzer/analyzer.d.ts.map +1 -0
  123. package/dist/tools/semantic-analyzer/analyzer.js +37 -0
  124. package/dist/tools/semantic-analyzer/analyzer.js.map +1 -0
  125. package/dist/tools/semantic-analyzer/formatters.d.ts +31 -0
  126. package/dist/tools/semantic-analyzer/formatters.d.ts.map +1 -0
  127. package/dist/tools/semantic-analyzer/formatters.js +132 -0
  128. package/dist/tools/semantic-analyzer/formatters.js.map +1 -0
  129. package/dist/tools/semantic-analyzer/index.d.ts +10 -0
  130. package/dist/tools/semantic-analyzer/index.d.ts.map +1 -0
  131. package/dist/tools/semantic-analyzer/index.js +12 -0
  132. package/dist/tools/semantic-analyzer/index.js.map +1 -0
  133. package/dist/tools/semantic-analyzer/services/dependency-extraction.d.ts +31 -0
  134. package/dist/tools/semantic-analyzer/services/dependency-extraction.d.ts.map +1 -0
  135. package/dist/tools/semantic-analyzer/services/dependency-extraction.js +138 -0
  136. package/dist/tools/semantic-analyzer/services/dependency-extraction.js.map +1 -0
  137. package/dist/tools/semantic-analyzer/services/index.d.ts +11 -0
  138. package/dist/tools/semantic-analyzer/services/index.d.ts.map +1 -0
  139. package/dist/tools/semantic-analyzer/services/index.js +11 -0
  140. package/dist/tools/semantic-analyzer/services/index.js.map +1 -0
  141. package/dist/tools/semantic-analyzer/services/language-detection.d.ts +38 -0
  142. package/dist/tools/semantic-analyzer/services/language-detection.d.ts.map +1 -0
  143. package/dist/tools/semantic-analyzer/services/language-detection.js +155 -0
  144. package/dist/tools/semantic-analyzer/services/language-detection.js.map +1 -0
  145. package/dist/tools/semantic-analyzer/services/pattern-detection.d.ts +37 -0
  146. package/dist/tools/semantic-analyzer/services/pattern-detection.d.ts.map +1 -0
  147. package/dist/tools/semantic-analyzer/services/pattern-detection.js +248 -0
  148. package/dist/tools/semantic-analyzer/services/pattern-detection.js.map +1 -0
  149. package/dist/tools/semantic-analyzer/services/structure-analysis.d.ts +11 -0
  150. package/dist/tools/semantic-analyzer/services/structure-analysis.d.ts.map +1 -0
  151. package/dist/tools/semantic-analyzer/services/structure-analysis.js +47 -0
  152. package/dist/tools/semantic-analyzer/services/structure-analysis.js.map +1 -0
  153. package/dist/tools/semantic-analyzer/services/symbol-extraction.d.ts +23 -0
  154. package/dist/tools/semantic-analyzer/services/symbol-extraction.d.ts.map +1 -0
  155. package/dist/tools/semantic-analyzer/services/symbol-extraction.js +129 -0
  156. package/dist/tools/semantic-analyzer/services/symbol-extraction.js.map +1 -0
  157. package/dist/tools/semantic-analyzer/types/index.d.ts +56 -0
  158. package/dist/tools/semantic-analyzer/types/index.d.ts.map +1 -0
  159. package/dist/tools/semantic-analyzer/types/index.js +5 -0
  160. package/dist/tools/semantic-analyzer/types/index.js.map +1 -0
  161. package/dist/tools/semantic-code-analyzer.d.ts +2 -0
  162. package/dist/tools/semantic-code-analyzer.d.ts.map +1 -1
  163. package/dist/tools/semantic-code-analyzer.js +23 -311
  164. package/dist/tools/semantic-code-analyzer.js.map +1 -1
  165. package/dist/tools/shared/constants.d.ts +13 -0
  166. package/dist/tools/shared/constants.d.ts.map +1 -0
  167. package/dist/tools/shared/constants.js +13 -0
  168. package/dist/tools/shared/constants.js.map +1 -0
  169. package/dist/tools/shared/errors.d.ts.map +1 -1
  170. package/dist/tools/shared/errors.js +1 -0
  171. package/dist/tools/shared/errors.js.map +1 -1
  172. package/dist/tools/shared/export-utils.d.ts +40 -0
  173. package/dist/tools/shared/export-utils.d.ts.map +1 -0
  174. package/dist/tools/shared/export-utils.js +190 -0
  175. package/dist/tools/shared/export-utils.js.map +1 -0
  176. package/dist/tools/shared/prompt-sections.d.ts +9 -0
  177. package/dist/tools/shared/prompt-sections.d.ts.map +1 -1
  178. package/dist/tools/shared/prompt-sections.js +37 -8
  179. package/dist/tools/shared/prompt-sections.js.map +1 -1
  180. package/dist/tools/shared/prompt-utils.d.ts +26 -1
  181. package/dist/tools/shared/prompt-utils.d.ts.map +1 -1
  182. package/dist/tools/shared/prompt-utils.js +111 -3
  183. package/dist/tools/shared/prompt-utils.js.map +1 -1
  184. package/dist/tools/shared/types/export-format.types.d.ts +52 -0
  185. package/dist/tools/shared/types/export-format.types.d.ts.map +1 -0
  186. package/dist/tools/shared/types/export-format.types.js +41 -0
  187. package/dist/tools/shared/types/export-format.types.js.map +1 -0
  188. package/dist/tools/shared/types/index.d.ts +1 -0
  189. package/dist/tools/shared/types/index.d.ts.map +1 -1
  190. package/dist/tools/shared/types/index.js +1 -0
  191. package/dist/tools/shared/types/index.js.map +1 -1
  192. package/dist/tools/sprint-timeline-calculator.d.ts.map +1 -1
  193. package/dist/tools/sprint-timeline-calculator.js +19 -5
  194. package/dist/tools/sprint-timeline-calculator.js.map +1 -1
  195. package/package.json +21 -6
package/README.md CHANGED
@@ -1,11 +1,15 @@
1
+ <!-- HEADER:START -->
2
+ ![Header](docs/.frames-static/09-header.svg)
3
+ <!-- HEADER:END -->
4
+
1
5
  # MCP AI Agent Guidelines Server
2
6
 
3
- > [!CAUTION]
4
- > **Disclaimer -- Experimental / Early Stage:** This _research demonstrator_ project references thirdโ€‘party models, tools, pricing, and docs that evolve quickly. Treat outputs as recommendations and verify against official docs and your own benchmarks before production use.
7
+ > [!CAUTION] > **Disclaimer -- Experimental / Early Stage:** This _research demonstrator_ project references thirdโ€‘party models, tools, pricing, and docs that evolve quickly. Treat outputs as recommendations and verify against official docs and your own benchmarks before production use.
5
8
 
6
9
  [![CI/CD Pipeline](https://img.shields.io/github/actions/workflow/status/Anselmoo/mcp-ai-agent-guidelines/ci-cd.yml?branch=main&label=CI%2FCD&logo=github-actions&logoColor=white)](https://github.com/Anselmoo/mcp-ai-agent-guidelines/actions/workflows/ci-cd.yml)
10
+ [![Auto-Regenerate Demos](https://img.shields.io/github/actions/workflow/status/Anselmoo/mcp-ai-agent-guidelines/auto-regenerate-demos.yml?label=demos&logo=github-actions&logoColor=white)](https://github.com/Anselmoo/mcp-ai-agent-guidelines/actions/workflows/auto-regenerate-demos.yml)
11
+ [![Link Checker](https://img.shields.io/github/actions/workflow/status/Anselmoo/mcp-ai-agent-guidelines/link-checker.yml?branch=main&label=links&logo=link&logoColor=white)](https://github.com/Anselmoo/mcp-ai-agent-guidelines/actions/workflows/link-checker.yml)
7
12
  [![Coverage Status](https://img.shields.io/codecov/c/github/Anselmoo/mcp-ai-agent-guidelines/main?label=coverage&logo=codecov&logoColor=white)](https://codecov.io/gh/Anselmoo/mcp-ai-agent-guidelines)
8
- [![NPM Version](https://img.shields.io/npm/v/mcp-ai-agent-guidelines?label=npm&logo=npm&logoColor=white&color=red)](https://www.npmjs.com/package/mcp-ai-agent-guidelines)
9
13
  [![Node.js Version](https://img.shields.io/node/v/mcp-ai-agent-guidelines?label=node&logo=node.js&logoColor=white&color=green)](https://nodejs.org/en/download/)
10
14
  [![Docker](https://img.shields.io/badge/docker-available-blue?logo=docker&logoColor=white)](https://github.com/Anselmoo/mcp-ai-agent-guidelines/pkgs/container/mcp-ai-agent-guidelines)
11
15
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow?logo=opensourceinitiative&logoColor=white)](./LICENSE)
@@ -13,10 +17,23 @@
13
17
  [![GitHub Stars](https://img.shields.io/github/stars/Anselmoo/mcp-ai-agent-guidelines?style=social)](https://github.com/Anselmoo/mcp-ai-agent-guidelines/stargazers)
14
18
  [![GitHub Forks](https://img.shields.io/github/forks/Anselmoo/mcp-ai-agent-guidelines?style=social)](https://github.com/Anselmoo/mcp-ai-agent-guidelines/network/members)
15
19
  [![GitHub Issues](https://img.shields.io/github/issues/Anselmoo/mcp-ai-agent-guidelines?label=issues&logo=github&logoColor=white)](https://github.com/Anselmoo/mcp-ai-agent-guidelines/issues)
16
- [![NPM Downloads](https://img.shields.io/npm/dt/mcp-ai-agent-guidelines?label=downloads&logo=npm&logoColor=white&color=blue)](https://www.npmjs.com/package/mcp-ai-agent-guidelines)
17
20
  [![GitHub Last Commit](https://img.shields.io/github/last-commit/Anselmoo/mcp-ai-agent-guidelines?logo=github&logoColor=white)](https://github.com/Anselmoo/mcp-ai-agent-guidelines/commits/main)
18
21
 
19
- A Model Context Protocol (MCP) server offering professional tools and templates for hierarchical prompting, code hygiene, visualization, memory optimization, and agile planning.
22
+ A Model Context Protocol (MCP) server offering advanced tools and templates for hierarchical prompting, code hygiene, visualization, memory optimization, and agile planning.
23
+
24
+ ## ๐Ÿ“š Table of Contents
25
+
26
+ - [Installation](#installation)
27
+ - [Documentation](#documentation)
28
+ - [Demos](#demos)
29
+ - [Features](#features)
30
+ - [VS Code Integration](#vs-code-integration-one-click)
31
+ - [Agent-Relative Calls](#agent-relative-calls)
32
+ - [Configuration](#configuration)
33
+ - [Development](#development)
34
+ - [Contributing](#contributing)
35
+ - [Changelog](./CHANGELOG.md)
36
+ - [License](#license)
20
37
 
21
38
  ## Installation
22
39
 
@@ -41,46 +58,199 @@ npm run start # Build and start server
41
58
  npm run test:all # Unit + integration + demos + MCP smoke
42
59
  npm run test:coverage:unit # Unit test coverage (c8) -> coverage/ + summary
43
60
  npm run quality # Type-check + Biome checks
61
+ npm run links:check # Check links in main markdown files
62
+ npm run links:check:all # Check links in all markdown files (slow)
44
63
  ```
45
64
 
65
+ ### Local Link Checking
66
+
67
+ The project includes automated link checking via GitHub Actions. To check links locally before committing:
68
+
69
+ ```bash
70
+ # Quick check (README, CONTRIBUTING, DISCLAIMER)
71
+ npm run links:check
72
+
73
+ # Comprehensive check (all markdown files)
74
+ npm run links:check:all
75
+
76
+ # Or use npx directly
77
+ npx markdown-link-check --config .mlc_config.json README.md
78
+ ```
79
+
80
+ Configuration is in `.mlc_config.json`. Ignored patterns and retries are configured there.
81
+
82
+ ## Documentation
83
+
84
+ ## Documentation
85
+
86
+ **[๐Ÿ“– Complete Documentation Index](./docs/README.md)** - Full guide to all tools and features
87
+
88
+ ### Getting Started Guides
89
+
90
+ - **[๐ŸŽฏ AI Interaction Tips](./docs/tips/AI_INTERACTION_TIPS.md)** - Learn to ask targeted questions for better results
91
+ - **[๐Ÿ“Š Prompting Hierarchy](./docs/tips/PROMPTING_HIERARCHY.md)** - Understanding prompt levels and evaluation
92
+ - **[๐Ÿ”— Agent-Relative Call Patterns](./docs/tips/AGENT_RELATIVE_CALLS.md)** - Invoking tools in workflows
93
+
94
+ ### Advanced Features
95
+
96
+ - **[๐ŸŒŠ Flow-Based Prompting](./docs/tips/FLOW_PROMPTING_EXAMPLES.md)** - Multi-step prompt workflows
97
+ - **[๐ŸŽจ Mermaid Diagram Generation](./docs/tips/MERMAID_DIAGRAM_EXAMPLES.md)** - Create flowcharts, sequences, ER diagrams
98
+ - **[๐Ÿ” Code Quality Analysis](./docs/tips/CODE_QUALITY_IMPROVEMENTS.md)** - Hygiene scoring and best practices
99
+ - **[โšก Sprint Planning](./docs/tips/SPRINT_PLANNING_RELIABILITY.md)** - Dependency-aware timeline calculation
100
+
101
+ ### Integration & Reference
102
+
103
+ - **[๐Ÿ—๏ธ Bridge Connectors](./docs/tips/BRIDGE_CONNECTORS.md)** - Integration patterns for external systems
104
+ - **[๐Ÿ”„ Serena Integration](./docs/tips/SERENA_STRATEGIES.md)** - Semantic analysis strategies
105
+ - **[๐Ÿ“š Complete Reference](./docs/tips/REFERENCES.md)** - Credits, research papers, and citations
106
+
107
+ See **[docs/README.md](./docs/README.md)** for the complete documentation index.
108
+
109
+ ### Quick Links
110
+
111
+ #### For Users
112
+
113
+ - **[๐ŸŽฏ AI Interaction Tips](./docs/tips/AI_INTERACTION_TIPS.md)** - Learn to ask targeted questions for better results
114
+ - **[๐Ÿ“Š Prompting Hierarchy](./docs/tips/PROMPTING_HIERARCHY.md)** - Understanding prompt levels and evaluation
115
+ - **[๐Ÿ”— Agent-Relative Call Patterns](./docs/tips/AGENT_RELATIVE_CALLS.md)** - Invoking tools in workflows
116
+ - **[๐ŸŒŠ Flow-Based Prompting](./docs/tips/FLOW_PROMPTING_EXAMPLES.md)** - Advanced chaining strategies
117
+ - **[๐ŸŽจ Mermaid Diagrams](./docs/tips/MERMAID_DIAGRAM_EXAMPLES.md)** - Visual diagram generation
118
+
119
+ #### For Developers
120
+
121
+ - **[๐Ÿค Contributing Guidelines](./CONTRIBUTING.md)** - How to contribute
122
+ - **[โœจ Clean Code Initiative](./docs/tips/CLEAN_CODE_INITIATIVE.md)** - Quality standards (100/100 scoring)
123
+ - **[๐Ÿ”ง Technical Improvements](./docs/tips/TECHNICAL_IMPROVEMENTS.md)** - Refactoring and enhancements
124
+ - **[โš ๏ธ Error Handling](./docs/tips/ERROR_HANDLING.md)** - Best practices
125
+ - **[๐Ÿ—๏ธ Bridge Connectors](./docs/tips/BRIDGE_CONNECTORS.md)** - Integration patterns
126
+
127
+ See the **[complete documentation](./docs/README.md)** for the full list of guides organized by topic.
128
+
46
129
  ## Demos
47
130
 
48
- Explore generated demo reports in the repository:
131
+ Explore real-world examples showing the tools in action. All demos are auto-generated and kept in sync with the codebase.
132
+
133
+ **[๐Ÿ“– Complete Demo Index](./demos/README.md)** - Full list of all demos with descriptions
134
+
135
+ ### Featured Examples
136
+
137
+ **Code Analysis & Quality:**
138
+
139
+ - [Code Hygiene Report](./demos/demo-code-analysis.hygiene.md) - Pattern detection and best practices
140
+ - [Guidelines Validation](./demos/demo-code-analysis.guidelines.md) - AI agent development standards
141
+ - [Clean Code Scoring](./demos/demo-clean-code-score.md) - Comprehensive quality metrics (0-100)
142
+
143
+ **Prompt Engineering:**
49
144
 
50
- - Code Hygiene Report: [demos/demo-code-analysis.hygiene.md](./demos/demo-code-analysis.hygiene.md)
51
- - Guidelines Validation: [demos/demo-code-analysis.guidelines.md](./demos/demo-code-analysis.guidelines.md)
52
- - Hierarchical Prompt (Refactor plan): [demos/demo-code-analysis.hierarchical.prompt.md](./demos/demo-code-analysis.hierarchical.prompt.md)
53
- - Domain-neutral Prompt Template: [demos/demo-code-analysis.domain-neutral.prompt.md](./demos/demo-code-analysis.domain-neutral.prompt.md)
54
- - Security Hardening Prompt: [demos/demo-code-analysis.security-hardening.prompt.md](./demos/demo-code-analysis.security-hardening.prompt.md)
55
- - Spark Prompt Card: [demos/demo-code-analysis.spark.prompt.md](./demos/demo-code-analysis.spark.prompt.md)
56
- - Memory Context Optimization: [demos/demo-code-analysis.memory.md](./demos/demo-code-analysis.memory.md)
57
- - Architecture Diagram (Mermaid): [demos/demo-code-analysis.diagram.md](./demos/demo-code-analysis.diagram.md)
58
- - Model Compatibility Analysis: [demos/demo-code-analysis.model-compat.md](./demos/demo-code-analysis.model-compat.md)
59
- - Sprint Plan: [demos/demo-code-analysis.sprint.md](./demos/demo-code-analysis.sprint.md)
145
+ - [Hierarchical Prompt](./demos/demo-code-analysis.hierarchical.prompt.md) - Structured refactoring plan
146
+ - [Domain-Neutral Prompt](./demos/demo-code-analysis.domain-neutral.prompt.md) - Generic template
147
+ - [Security Hardening Prompt](./demos/demo-code-analysis.security-hardening.prompt.md) - OWASP-focused analysis
148
+ - [Flow-Based Prompting](./demos/demo-design-session.md) - Multi-step workflows
60
149
 
61
- See more in [demos/README.md](./demos/README.md).
150
+ **Visualization & Planning:**
62
151
 
63
- ### Demo scripts (.js)
152
+ - [Architecture Diagram](./demos/demo-code-analysis.diagram.md) - Mermaid system diagrams
153
+ - [Sprint Planning](./demos/demo-code-analysis.sprint.md) - Dependency-aware timeline
154
+ - [Model Compatibility](./demos/demo-code-analysis.model-compat.md) - AI model selection
64
155
 
65
- Run demo scripts to generate or test artifacts:
156
+ **Advanced Features:**
157
+
158
+ - [Memory Context Optimization](./demos/demo-code-analysis.memory.md) - Token efficiency
159
+ - [Strategy Frameworks](./demos/demo-strategy-frameworks.md) - SWOT, BCG, Porter's Five Forces
160
+ - [Gap Analysis](./demos/demo-gap-analysis.md) - Current vs. desired state
161
+
162
+ ### Running Demos Locally
66
163
 
67
164
  ```bash
68
- # Build first
69
165
  npm run build
166
+ node demos/demo-tools.js # Generate sample tool outputs
167
+ ```
70
168
 
71
- # Run sample tool calls
72
- node demos/demo-tools.js
169
+ Demos are automatically regenerated when tool code changes via GitHub Actions.
73
170
 
74
- # Generate demo reports
75
- node demos/demo-tools.js
76
- ```
171
+ ## Features & Tools
172
+
173
+ **27 professional tools** for AI-powered development workflows. Each tool is rated by complexity:
174
+
175
+ **โญ Complexity Ratings:**
176
+
177
+ - โญ **Simple** - Single input, immediate output (5-10 min to master)
178
+ - โญโญ **Moderate** - Multiple parameters, straightforward usage (15-30 min)
179
+ - โญโญโญ **Advanced** - Complex inputs, requires understanding of domain (1-2 hours)
180
+ - โญโญโญโญ **Expert** - Multi-phase workflows, deep domain knowledge (half day)
181
+ - โญโญโญโญโญ **Master** - Enterprise-scale, comprehensive orchestration (1-2 days)
182
+
183
+ **๐Ÿ“– [Complete Tools Reference](./docs/tips/TOOLS_REFERENCE.md)** - Detailed documentation with examples
184
+
185
+ ---
186
+
187
+ ### ๐ŸŽจ Prompt Builders (9 tools)
188
+
189
+ Build structured, effective prompts for various use cases.
190
+
191
+ | Tool | Purpose | Complexity | Learn More |
192
+ | --------------------------------------------- | --------------------------------------------------------------- | ---------- | -------------------------------------------------------------------- |
193
+ | `hierarchical-prompt-builder` | Multi-level specificity prompts (context โ†’ goal โ†’ requirements) | โญโญ | [Guide](./docs/tools/hierarchical-prompt-builder.md) |
194
+ | `code-analysis-prompt-builder` | Code review prompts (security, performance, maintainability) | โญโญ | [Guide](./docs/tools/code-analysis-prompt-builder.md) |
195
+ | `architecture-design-prompt-builder` | Architecture design with scale-appropriate guidance | โญโญโญ | [Guide](./docs/tools/architecture-design-prompt-builder.md) |
196
+ | `digital-enterprise-architect-prompt-builder` | Enterprise architecture with mentor perspectives & research | โญโญโญโญ | [Guide](./docs/tools/digital-enterprise-architect-prompt-builder.md) |
197
+ | `debugging-assistant-prompt-builder` | Systematic debugging prompts with structured analysis | โญโญ | [Guide](./docs/tools/debugging-assistant-prompt-builder.md) |
198
+ | `l9-distinguished-engineer-prompt-builder` | L9 (Distinguished Engineer) high-level technical design | โญโญโญโญโญ | [Guide](./docs/tools/l9-distinguished-engineer-prompt-builder.md) |
199
+ | `documentation-generator-prompt-builder` | Technical docs tailored to audience (API, user guide, spec) | โญโญ | [Guide](./docs/tools/documentation-generator-prompt-builder.md) |
200
+ | `domain-neutral-prompt-builder` | Generic templates with objectives and workflows | โญโญโญ | [Guide](./docs/tools/domain-neutral-prompt-builder.md) |
201
+ | `security-hardening-prompt-builder` | Security analysis with OWASP/compliance focus | โญโญโญ | [Guide](./docs/tools/security-hardening-prompt-builder.md) |
202
+
203
+ ### ๐Ÿ” Code Analysis & Quality (7 tools)
204
+
205
+ Analyze and improve code quality with automated insights.
206
+
207
+ | Tool | Purpose | Complexity | Learn More |
208
+ | ----------------------------- | ------------------------------------------------------------------ | ---------- | ---------------------------------------------------- |
209
+ | `clean-code-scorer` | Comprehensive 0-100 quality score with metric breakdown | โญโญโญ | [Guide](./docs/tools/clean-code-scorer.md) |
210
+ | `code-hygiene-analyzer` | Detect outdated patterns, unused dependencies, code smells | โญโญ | [Guide](./docs/tools/code-hygiene-analyzer.md) |
211
+ | `dependency-auditor` | Audit package.json for security, deprecation, ESM compatibility | โญ | [Guide](./docs/tools/dependency-auditor.md) |
212
+ | `iterative-coverage-enhancer` | Analyze coverage gaps, generate test suggestions, adapt thresholds | โญโญโญ | [Guide](./docs/tools/iterative-coverage-enhancer.md) |
213
+ | `semantic-code-analyzer` | Identify symbols, structure, dependencies, patterns (LSP-based) | โญโญ | [Guide](./docs/tools/semantic-code-analyzer.md) |
214
+ | `guidelines-validator` | Validate practices against AI agent development guidelines | โญ | [Guide](./docs/tools/guidelines-validator.md) |
215
+ | `mermaid-diagram-generator` | Generate visual diagrams (flowchart, sequence, ER, class, etc.) | โญโญ | [Guide](./docs/tools/mermaid-diagram-generator.md) |
216
+
217
+ ### ๐Ÿ“Š Strategy & Planning (5 tools)
218
+
219
+ Business strategy analysis and agile project planning.
77
220
 
78
- Scripts:
79
- - `demos/demo-tools.js` โ€” invokes several tools with sample inputs
80
- - `demos/generate-demo-reports.js` โ€” produces end-to-end demo outputs
81
- - `demos/generate-hygiene-reports.js` โ€” hygiene-focused reports
221
+ | Tool | Purpose | Complexity | Learn More |
222
+ | ----------------------------- | --------------------------------------------------------------------- | ---------- | ---------------------------------------------------- |
223
+ | `strategy-frameworks-builder` | SWOT, BSC, VRIO, Porter's Five Forces, market analysis | โญโญโญ | [Guide](./docs/tools/strategy-frameworks-builder.md) |
224
+ | `gap-frameworks-analyzers` | Capability, technology, maturity, skills gap analysis | โญโญโญ | [Guide](./docs/tools/gap-frameworks-analyzers.md) |
225
+ | `sprint-timeline-calculator` | Dependency-aware sprint planning with bin-packing optimization | โญโญ | [Guide](./docs/tools/sprint-timeline-calculator.md) |
226
+ | `model-compatibility-checker` | Recommend best AI models for task requirements and budget | โญ | [Guide](./docs/tools/model-compatibility-checker.md) |
227
+ | `project-onboarding` | Comprehensive project structure analysis and documentation generation | โญโญ | [Guide](./docs/tools/project-onboarding.md) |
82
228
 
83
- ## VS Code Integration (Oneโ€‘Click)
229
+ ### ๐ŸŽจ Design Workflow (1 tool)
230
+
231
+ Multi-phase design orchestration with constraint enforcement.
232
+
233
+ | Tool | Purpose | Complexity | Learn More |
234
+ | ------------------ | ---------------------------------------------------------------------------------- | ---------- | ----------------------------------------- |
235
+ | `design-assistant` | Constraint-driven design sessions with artifact generation (ADRs, specs, roadmaps) | โญโญโญโญ | [Guide](./docs/tools/design-assistant.md) |
236
+
237
+ ### ๐Ÿ› ๏ธ Utilities (5 tools)
238
+
239
+ Supporting tools for workflow optimization.
240
+
241
+ | Tool | Purpose | Complexity | Learn More |
242
+ | ------------------------------- | ----------------------------------------------------------------------------------- | ---------- | ------------------------------------------------------ |
243
+ | `memory-context-optimizer` | Optimize prompt caching and context window usage | โญโญ | [Guide](./docs/tools/memory-context-optimizer.md) |
244
+ | `mode-switcher` | Switch between agent operation modes (planning, debugging, refactoring) | โญ | [Guide](./docs/tools/mode-switcher.md) |
245
+ | `prompting-hierarchy-evaluator` | Evaluate prompts with numeric scoring (clarity, specificity, completeness) | โญโญ | [Guide](./docs/tools/prompting-hierarchy-evaluator.md) |
246
+ | `hierarchy-level-selector` | Select optimal prompting level for task complexity | โญ | [Guide](./docs/tools/hierarchy-level-selector.md) |
247
+ | `spark-prompt-builder` | Build UI/UX product prompts with structured inputs (colors, typography, components) | โญโญโญ | [Guide](./docs/tools/spark-prompt-builder.md) |
248
+
249
+ **๐Ÿ’ก Pro Tip**: Start with โญ tools to learn the basics, then progress to โญโญโญ+ tools for advanced workflows.
250
+
251
+ ---
252
+
253
+ ## VS Code Integration (One-Click)
84
254
 
85
255
  Use buttons below to add this MCP server to VS Code (User Settings โ†’ mcp.servers):
86
256
 
@@ -93,14 +263,14 @@ Manual settings (User Settings JSON):
93
263
 
94
264
  ```json
95
265
  {
96
- "mcp": {
97
- "servers": {
98
- "ai-agent-guidelines": {
99
- "command": "npx",
100
- "args": ["-y", "mcp-ai-agent-guidelines"]
101
- }
102
- }
103
- }
266
+ "mcp": {
267
+ "servers": {
268
+ "ai-agent-guidelines": {
269
+ "command": "npx",
270
+ "args": ["-y", "mcp-ai-agent-guidelines"]
271
+ }
272
+ }
273
+ }
104
274
  }
105
275
  ```
106
276
 
@@ -108,19 +278,19 @@ Using Docker:
108
278
 
109
279
  ```json
110
280
  {
111
- "mcp": {
112
- "servers": {
113
- "ai-agent-guidelines": {
114
- "command": "docker",
115
- "args": [
116
- "run",
117
- "--rm",
118
- "-i",
119
- "ghcr.io/anselmoo/mcp-ai-agent-guidelines:latest"
120
- ]
121
- }
122
- }
123
- }
281
+ "mcp": {
282
+ "servers": {
283
+ "ai-agent-guidelines": {
284
+ "command": "docker",
285
+ "args": [
286
+ "run",
287
+ "--rm",
288
+ "-i",
289
+ "ghcr.io/anselmoo/mcp-ai-agent-guidelines:latest"
290
+ ]
291
+ }
292
+ }
293
+ }
124
294
  }
125
295
  ```
126
296
 
@@ -129,13 +299,14 @@ Using Docker:
129
299
  After adding the server, open your chat client (e.g., Cline in VS Code). The tools appear under the server name. You can:
130
300
 
131
301
  - Run a tool directly by name:
132
- - `hierarchical-prompt-builder` โ€” Provide context, goal, and optional requirements.
133
- - `clean-code-scorer` โ€” Calculate comprehensive Clean Code score (0-100) with coverage metrics.
134
- - `code-hygiene-analyzer` โ€” Paste code or point to a file and set language.
135
- - `mermaid-diagram-generator` โ€” Describe the system and select a diagram type.
302
+ - `hierarchical-prompt-builder` โ€” Provide context, goal, and optional requirements.
303
+ - `clean-code-scorer` โ€” Calculate comprehensive Clean Code score (0-100) with coverage metrics.
304
+ - `code-hygiene-analyzer` โ€” Paste code or point to a file and set language.
305
+ - `mermaid-diagram-generator` โ€” Describe the system and select a diagram type.
136
306
  - Ask in natural language and pick the suggested tool.
137
307
 
138
308
  Example prompts:
309
+
139
310
  - "Use hierarchical-prompt-builder to create a refactor plan for src/index.ts with outputFormat markdown."
140
311
  - "Use clean-code-scorer to analyze my project with current coverage metrics and get a quality score."
141
312
  - "Analyze this Python file with code-hygiene-analyzer; highlight security issues."
@@ -147,36 +318,99 @@ Tip: Most clients can pass file content automatically when you select a file and
147
318
 
148
319
  GitHub Chat (VS Code): In the chat, type your request and pick a tool suggestion, or explicitly reference a tool by name (e.g., โ€œUse mermaid-diagram-generator to draw a flowchart for our pipelineโ€).
149
320
 
150
- ## Features
321
+ ## Agent-Relative Calls
322
+
323
+ This MCP server fully supports **agent-relative calls**, the MCP standard pattern for enabling AI agents to discover and invoke tools contextually. Following the [GitHub MCP documentation](https://docs.github.com/en/copilot/tutorials/enhance-agent-mode-with-mcp), agents can use natural language patterns to orchestrate complex multi-tool workflows.
151
324
 
152
- > **๐Ÿ† NEW: Clean Code 100/100 Initiative** โ€” Comprehensive code quality scoring system with automated dashboard generation. Track and achieve perfect code quality across coverage, TypeScript, linting, and security. See [docs/CLEAN_CODE_INITIATIVE.md](./docs/CLEAN_CODE_INITIATIVE.md) for the complete guide.
153
- > - **Dashboard**: Run `npm run clean-code-dashboard` to generate score report
154
- > - **MCP Tool**: `clean-code-scorer` for on-demand quality analysis
155
- > - **Automated Gates**: Lefthook quality gates enforce standards on every commit
325
+ ### What Are Agent-Relative Calls?
156
326
 
157
- > **๐Ÿ†• NEW: Serena-Inspired Strategies** โ€” We've integrated effective agent strategies from [@oraios/serena](https://github.com/oraios/serena) including semantic code analysis, project onboarding, and flexible mode switching. See [docs/SERENA_STRATEGIES.md](./docs/SERENA_STRATEGIES.md) for details.
327
+ Agent-relative calls are natural language patterns like:
158
328
 
159
- > **๐ŸŒŠ NEW: Flow-Based Prompting** โ€” Advanced prompting strategies inspired by [@ruvnet/claude-flow](https://github.com/ruvnet/claude-flow) including prompt chaining, declarative flows, and dynamic orchestration.
160
- > - **Examples**: [docs/FLOW_PROMPTING_EXAMPLES.md](./docs/FLOW_PROMPTING_EXAMPLES.md)
161
- > - **Integration Guide**: [docs/FLOW_SERENA_INTEGRATION.md](./docs/FLOW_SERENA_INTEGRATION.md) - Combining flow-based prompting with Serena memory patterns
329
+ ```markdown
330
+ Use the [tool-name] MCP to [action] with [parameters/context]
331
+ ```
332
+
333
+ ### Quick Examples
334
+
335
+ **Single Tool Invocation:**
336
+
337
+ ```markdown
338
+ Use the hierarchical-prompt-builder MCP to create a code review prompt for our authentication module focusing on security best practices and OAuth2 implementation.
339
+ ```
340
+
341
+ **Multi-Tool Workflow:**
342
+
343
+ ```markdown
344
+ 1. Use the clean-code-scorer MCP to establish baseline quality metrics
345
+ 2. Use the code-hygiene-analyzer MCP to identify specific technical debt
346
+ 3. Use the security-hardening-prompt-builder MCP to create a remediation plan
347
+ 4. Use the sprint-timeline-calculator MCP to estimate implementation timeline
348
+ ```
349
+
350
+ **Integration with Other MCP Servers:**
351
+
352
+ ```markdown
353
+ # Accessibility Compliance Workflow
354
+
355
+ Use the Figma MCP to analyze design specifications for WCAG 2.1 AA compliance.
356
+ Use the security-hardening-prompt-builder MCP from AI Agent Guidelines to create accessibility security audit prompts.
357
+ Use the GitHub MCP to categorize open accessibility issues.
358
+ Use the iterative-coverage-enhancer MCP from AI Agent Guidelines to plan accessibility test coverage.
359
+ Use the Playwright MCP to create and run automated accessibility tests.
360
+ ```
361
+
362
+ ### Comprehensive Guide
363
+
364
+ For complete documentation with 20+ detailed examples, workflow patterns, and best practices, see:
365
+
366
+ ๐Ÿ“˜ **[Agent-Relative Call Patterns Guide](./docs/tips/AGENT_RELATIVE_CALLS.md)**
367
+
368
+ This guide covers:
369
+
370
+ - Core prompt patterns (single tool, chains, parallel, conditional)
371
+ - Tool categories with complete usage examples
372
+ - Multi-MCP server integration workflows
373
+ - Best practices for agent-driven development
374
+ - Performance optimization techniques
375
+ - Troubleshooting common issues
376
+
377
+ ### Available Resources
378
+
379
+ Access agent-relative call guidance via MCP resources:
380
+
381
+ ```markdown
382
+ Use the resource guidelines://agent-relative-calls to get comprehensive patterns and examples
383
+ ```
384
+
385
+ Or access programmatically:
386
+
387
+ ```typescript
388
+ // MCP ReadResource request
389
+ {
390
+ uri: "guidelines://agent-relative-calls";
391
+ }
392
+ ```
393
+
394
+ ## Features
162
395
 
163
396
  <details>
164
- <summary><strong>๐Ÿ”— Prompt Chaining Builder</strong> โ€” Multi-step prompts with output passing (NEW)</summary>
397
+ <summary><strong>๐Ÿ”— Prompt Chaining Builder</strong> โ€” Multi-step prompts with output passing</summary>
165
398
 
166
399
  Usage: `prompt-chaining-builder`
167
400
 
168
- | Parameter | Required | Description |
169
- | -------------- | -------- | ------------------------------------- |
170
- | `chainName` | โœ… | Name of the prompt chain |
171
- | `steps` | โœ… | Array of chain steps with prompts |
172
- | `description` | โŒ | Description of chain purpose |
173
- | `context` | โŒ | Global context for the chain |
174
- | `globalVariables` | โŒ | Variables accessible to all steps |
175
- | `executionStrategy` | โŒ | sequential/parallel-where-possible |
401
+ | Parameter | Required | Description |
402
+ | ------------------- | -------- | ---------------------------------- |
403
+ | `chainName` | โœ… | Name of the prompt chain |
404
+ | `steps` | โœ… | Array of chain steps with prompts |
405
+ | `description` | โŒ | Description of chain purpose |
406
+ | `context` | โŒ | Global context for the chain |
407
+ | `globalVariables` | โŒ | Variables accessible to all steps |
408
+ | `executionStrategy` | โŒ | sequential/parallel-where-possible |
176
409
 
177
410
  Build sophisticated multi-step prompt workflows where each step can depend on outputs from previous steps. Supports error handling strategies (skip/retry/abort) and automatic Mermaid visualization.
178
411
 
179
412
  **Example:**
413
+
180
414
  ```typescript
181
415
  {
182
416
  chainName: "Security Analysis Pipeline",
@@ -199,22 +433,23 @@ Build sophisticated multi-step prompt workflows where each step can depend on ou
199
433
  </details>
200
434
 
201
435
  <details>
202
- <summary><strong>๐ŸŒŠ Prompt Flow Builder</strong> โ€” Declarative flows with branching/loops (NEW)</summary>
436
+ <summary><strong>๐ŸŒŠ Prompt Flow Builder</strong> โ€” Declarative flows with branching/loops</summary>
203
437
 
204
438
  Usage: `prompt-flow-builder`
205
439
 
206
- | Parameter | Required | Description |
207
- | -------------- | -------- | ------------------------------------- |
208
- | `flowName` | โœ… | Name of the prompt flow |
209
- | `nodes` | โœ… | Flow nodes (prompt/condition/loop/parallel/merge/transform) |
210
- | `edges` | โŒ | Connections between nodes with conditions |
211
- | `entryPoint` | โŒ | Starting node ID |
212
- | `variables` | โŒ | Flow-level variables |
213
- | `outputFormat` | โŒ | markdown/mermaid/both |
440
+ | Parameter | Required | Description |
441
+ | -------------- | -------- | ----------------------------------------------------------- |
442
+ | `flowName` | โœ… | Name of the prompt flow |
443
+ | `nodes` | โœ… | Flow nodes (prompt/condition/loop/parallel/merge/transform) |
444
+ | `edges` | โŒ | Connections between nodes with conditions |
445
+ | `entryPoint` | โŒ | Starting node ID |
446
+ | `variables` | โŒ | Flow-level variables |
447
+ | `outputFormat` | โŒ | markdown/mermaid/both |
214
448
 
215
449
  Create complex adaptive prompt flows with conditional branching, loops, parallel execution, and merge points. Automatically generates Mermaid flowcharts and execution guides.
216
450
 
217
451
  **Example:**
452
+
218
453
  ```typescript
219
454
  {
220
455
  flowName: "Adaptive Code Review",
@@ -236,48 +471,48 @@ Create complex adaptive prompt flows with conditional branching, loops, parallel
236
471
  </details>
237
472
 
238
473
  <details>
239
- <summary><strong>๐Ÿ” Semantic Code Analyzer</strong> โ€” Symbol-based code understanding (NEW)</summary>
474
+ <summary><strong>๐Ÿ” Semantic Code Analyzer</strong> โ€” Symbol-based code understanding</summary>
240
475
 
241
476
  Usage: `semantic-code-analyzer`
242
477
 
243
- | Parameter | Required | Description |
244
- | -------------- | -------- | ------------------------------------- |
245
- | `codeContent` | โœ… | Code content to analyze |
246
- | `language` | โŒ | Programming language (auto-detected) |
247
- | `analysisType` | โŒ | symbols/structure/dependencies/patterns/all |
478
+ | Parameter | Required | Description |
479
+ | -------------- | -------- | ------------------------------------------- |
480
+ | `codeContent` | โœ… | Code content to analyze |
481
+ | `language` | โŒ | Programming language (auto-detected) |
482
+ | `analysisType` | โŒ | symbols/structure/dependencies/patterns/all |
248
483
 
249
484
  Performs semantic analysis to identify symbols, dependencies, patterns, and structure. Inspired by Serena's language server approach.
250
485
 
251
486
  </details>
252
487
 
253
488
  <details>
254
- <summary><strong>๐Ÿš€ Project Onboarding</strong> โ€” Comprehensive project familiarization (NEW)</summary>
489
+ <summary><strong>๐Ÿš€ Project Onboarding</strong> โ€” Comprehensive project familiarization</summary>
255
490
 
256
491
  Usage: `project-onboarding`
257
492
 
258
- | Parameter | Required | Description |
259
- | -------------- | -------- | ------------------------------------- |
260
- | `projectPath` | โœ… | Path to project directory |
261
- | `projectName` | โŒ | Name of the project |
262
- | `projectType` | โŒ | library/application/service/tool/other |
263
- | `analysisDepth`| โŒ | quick/standard/deep |
264
- | `includeMemories` | โŒ | Generate project memories (default: true) |
493
+ | Parameter | Required | Description |
494
+ | ----------------- | -------- | ----------------------------------------- |
495
+ | `projectPath` | โœ… | Path to project directory |
496
+ | `projectName` | โŒ | Name of the project |
497
+ | `projectType` | โŒ | library/application/service/tool/other |
498
+ | `analysisDepth` | โŒ | quick/standard/deep |
499
+ | `includeMemories` | โŒ | Generate project memories (default: true) |
265
500
 
266
501
  Analyzes project structure, detects technologies, and generates memories for context retention. Based on Serena's onboarding system.
267
502
 
268
503
  </details>
269
504
 
270
505
  <details>
271
- <summary><strong>๐Ÿ”„ Mode Switcher</strong> โ€” Flexible agent operation modes (NEW)</summary>
506
+ <summary><strong>๐Ÿ”„ Mode Switcher</strong> โ€” Flexible agent operation modes</summary>
272
507
 
273
508
  Usage: `mode-switcher`
274
509
 
275
- | Parameter | Required | Description |
276
- | -------------- | -------- | ------------------------------------- |
277
- | `targetMode` | โœ… | Mode to switch to (planning/editing/analysis/etc.) |
278
- | `currentMode` | โŒ | Current active mode |
279
- | `context` | โŒ | Operating context (desktop-app/ide-assistant/etc.) |
280
- | `reason` | โŒ | Reason for mode switch |
510
+ | Parameter | Required | Description |
511
+ | ------------- | -------- | -------------------------------------------------- |
512
+ | `targetMode` | โœ… | Mode to switch to (planning/editing/analysis/etc.) |
513
+ | `currentMode` | โŒ | Current active mode |
514
+ | `context` | โŒ | Operating context (desktop-app/ide-assistant/etc.) |
515
+ | `reason` | โŒ | Reason for mode switch |
281
516
 
282
517
  Switches between operation modes with optimized tool sets and prompting strategies. Modes include: planning, editing, analysis, interactive, one-shot, debugging, refactoring, documentation.
283
518
 
@@ -290,11 +525,11 @@ Usage: `hierarchical-prompt-builder`
290
525
 
291
526
  | Parameter | Required | Description |
292
527
  | -------------- | -------- | ------------------------------------- |
293
- | `context` | โœ… | The broad context or domain |
294
- | `goal` | โœ… | The specific goal or objective |
295
- | `requirements` | โŒ | Detailed requirements and constraints |
296
- | `outputFormat` | โŒ | Desired output format |
297
- | `audience` | โŒ | Target audience or expertise level |
528
+ | `context` | โœ… | The broad context or domain |
529
+ | `goal` | โœ… | The specific goal or objective |
530
+ | `requirements` | โŒ | Detailed requirements and constraints |
531
+ | `outputFormat` | โŒ | Desired output format |
532
+ | `audience` | โŒ | Target audience or expertise level |
298
533
 
299
534
  </details>
300
535
 
@@ -305,9 +540,9 @@ Usage: `code-hygiene-analyzer`
305
540
 
306
541
  | Parameter | Required | Description |
307
542
  | ------------- | -------- | ----------------------------- |
308
- | `codeContent` | โœ… | Code content to analyze |
309
- | `language` | โœ… | Programming language |
310
- | `framework` | โŒ | Framework or technology stack |
543
+ | `codeContent` | โœ… | Code content to analyze |
544
+ | `language` | โœ… | Programming language |
545
+ | `framework` | โŒ | Framework or technology stack |
311
546
 
312
547
  </details>
313
548
 
@@ -316,18 +551,19 @@ Usage: `code-hygiene-analyzer`
316
551
 
317
552
  Usage: `security-hardening-prompt-builder`
318
553
 
319
- | Parameter | Required | Description |
320
- | --------- | -------- | ----------- |
321
- | `codeContext` | โœ… | Code context or description to analyze for security |
322
- | `securityFocus` | โŒ | Security analysis focus (vulnerability-analysis, security-hardening, compliance-check, threat-modeling, penetration-testing) |
323
- | `securityRequirements` | โŒ | Specific security requirements to check |
324
- | `complianceStandards` | โŒ | Compliance standards (OWASP-Top-10, NIST-Cybersecurity-Framework, ISO-27001, SOC-2, GDPR, HIPAA, PCI-DSS) |
325
- | `language` | โŒ | Programming language of the code |
326
- | `riskTolerance` | โŒ | Risk tolerance level (low, medium, high) |
327
- | `analysisScope` | โŒ | Security areas to focus on (input-validation, authentication, authorization, etc.) |
328
- | `outputFormat` | โŒ | Output format (detailed, checklist, annotated-code) |
554
+ | Parameter | Required | Description |
555
+ | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
556
+ | `codeContext` | โœ… | Code context or description to analyze for security |
557
+ | `securityFocus` | โŒ | Security analysis focus (vulnerability-analysis, security-hardening, compliance-check, threat-modeling, penetration-testing) |
558
+ | `securityRequirements` | โŒ | Specific security requirements to check |
559
+ | `complianceStandards` | โŒ | Compliance standards (OWASP-Top-10, NIST-Cybersecurity-Framework, ISO-27001, SOC-2, GDPR, HIPAA, PCI-DSS) |
560
+ | `language` | โŒ | Programming language of the code |
561
+ | `riskTolerance` | โŒ | Risk tolerance level (low, medium, high) |
562
+ | `analysisScope` | โŒ | Security areas to focus on (input-validation, authentication, authorization, etc.) |
563
+ | `outputFormat` | โŒ | Output format (detailed, checklist, annotated-code) |
329
564
 
330
565
  **Security Focus Areas:**
566
+
331
567
  - ๐Ÿ” Vulnerability analysis with OWASP Top 10 coverage
332
568
  - ๐Ÿ›ก๏ธ Security hardening recommendations
333
569
  - ๐Ÿ“‹ Compliance checking against industry standards
@@ -345,18 +581,18 @@ Usage: `mermaid-diagram-generator`
345
581
 
346
582
  Generates Mermaid diagrams with intelligent parsing of descriptions for rich, customizable visualizations.
347
583
 
348
- | Parameter | Required | Description |
349
- | ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
350
- | `description` | โœ… | Description of the system or process to diagram. Be detailed and specific for better diagram generation. |
351
- | `diagramType` | โœ… | Type: `flowchart`, `sequence`, `class`, `state`, `gantt`, `pie`, `er`, `journey`, `quadrant`, `git-graph`, `mindmap`, `timeline` |
352
- | `theme` | โŒ | Visual theme: `default`, `dark`, `forest`, `neutral` |
353
- | `direction` | โŒ | Flowchart direction: `TD`/`TB` (top-down), `BT` (bottom-top), `LR` (left-right), `RL` (right-left) |
354
- | `strict` | โŒ | If true, never emit invalid diagram; use fallback if needed (default: true) |
355
- | `repair` | โŒ | Attempt auto-repair on validation failure (default: true) |
356
- | `accTitle` | โŒ | Accessibility title (added as Mermaid comment) |
357
- | `accDescr` | โŒ | Accessibility description (added as Mermaid comment) |
358
- | `customStyles` | โŒ | Custom CSS/styling directives for advanced customization |
359
- | `advancedFeatures` | โŒ | Type-specific advanced features (e.g., `{autonumber: true}` for sequence diagrams) |
584
+ | Parameter | Required | Description |
585
+ | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
586
+ | `description` | โœ… | Description of the system or process to diagram. Be detailed and specific for better diagram generation. |
587
+ | `diagramType` | โœ… | Type: `flowchart`, `sequence`, `class`, `state`, `gantt`, `pie`, `er`, `journey`, `quadrant`, `git-graph`, `mindmap`, `timeline` |
588
+ | `theme` | โŒ | Visual theme: `default`, `dark`, `forest`, `neutral` |
589
+ | `direction` | โŒ | Flowchart direction: `TD`/`TB` (top-down), `BT` (bottom-top), `LR` (left-right), `RL` (right-left) |
590
+ | `strict` | โŒ | If true, never emit invalid diagram; use fallback if needed (default: true) |
591
+ | `repair` | โŒ | Attempt auto-repair on validation failure (default: true) |
592
+ | `accTitle` | โŒ | Accessibility title (added as Mermaid comment) |
593
+ | `accDescr` | โŒ | Accessibility description (added as Mermaid comment) |
594
+ | `customStyles` | โŒ | Custom CSS/styling directives for advanced customization |
595
+ | `advancedFeatures` | โŒ | Type-specific advanced features (e.g., `{autonumber: true}` for sequence diagrams) |
360
596
 
361
597
  **Enhanced Features:**
362
598
 
@@ -422,9 +658,9 @@ Usage: `memory-context-optimizer`
422
658
 
423
659
  | Parameter | Required | Description |
424
660
  | ---------------- | -------- | -------------------------------------------------- |
425
- | `contextContent` | โœ… | Context content to optimize |
426
- | `maxTokens` | โŒ | Maximum token limit |
427
- | `cacheStrategy` | โŒ | Strategy: `aggressive`, `conservative`, `balanced` |
661
+ | `contextContent` | โœ… | Context content to optimize |
662
+ | `maxTokens` | โŒ | Maximum token limit |
663
+ | `cacheStrategy` | โŒ | Strategy: `aggressive`, `conservative`, `balanced` |
428
664
 
429
665
  </details>
430
666
 
@@ -435,10 +671,10 @@ Usage: `sprint-timeline-calculator`
435
671
 
436
672
  | Parameter | Required | Description |
437
673
  | -------------- | -------- | --------------------------------------- |
438
- | `tasks` | โœ… | List of tasks with estimates |
439
- | `teamSize` | โœ… | Number of team members |
440
- | `sprintLength` | โŒ | Sprint length in days |
441
- | `velocity` | โŒ | Team velocity (story points per sprint) |
674
+ | `tasks` | โœ… | List of tasks with estimates |
675
+ | `teamSize` | โœ… | Number of team members |
676
+ | `sprintLength` | โŒ | Sprint length in days |
677
+ | `velocity` | โŒ | Team velocity (story points per sprint) |
442
678
 
443
679
  </details>
444
680
 
@@ -449,9 +685,9 @@ Usage: `model-compatibility-checker`
449
685
 
450
686
  | Parameter | Required | Description |
451
687
  | ----------------- | -------- | -------------------------------------------------------- |
452
- | `taskDescription` | โœ… | Description of the task |
453
- | `requirements` | โŒ | Specific requirements (context length, multimodal, etc.) |
454
- | `budget` | โŒ | Budget constraints: `low`, `medium`, `high` |
688
+ | `taskDescription` | โœ… | Description of the task |
689
+ | `requirements` | โŒ | Specific requirements (context length, multimodal, etc.) |
690
+ | `budget` | โŒ | Budget constraints: `low`, `medium`, `high` |
455
691
 
456
692
  </details>
457
693
 
@@ -462,8 +698,8 @@ Usage: `guidelines-validator`
462
698
 
463
699
  | Parameter | Required | Description |
464
700
  | --------------------- | -------- | ----------------------------------------------------------------------------------------------- |
465
- | `practiceDescription` | โœ… | Description of the development practice |
466
- | `category` | โœ… | Category: `prompting`, `code-management`, `architecture`, `visualization`, `memory`, `workflow` |
701
+ | `practiceDescription` | โœ… | Description of the development practice |
702
+ | `category` | โœ… | Category: `prompting`, `code-management`, `architecture`, `visualization`, `memory`, `workflow` |
467
703
 
468
704
  </details>
469
705
 
@@ -488,11 +724,12 @@ Use the [Release Setup Issue Form](.github/ISSUE_TEMPLATE/release-setup.yml) to
488
724
  - **Quality gates**: Pre-release checklist ensures reliability
489
725
  - **CI/CD integration**: Supports existing NPM and Docker publishing workflow
490
726
 
491
- To create a new release, [open a release setup issue](../../issues/new?template=release-setup.yml) with the target version and release details.
727
+ To create a new release, [open a release setup issue](https://github.com/Anselmoo/mcp-ai-agent-guidelines/issues/new?template=release-setup.yml) with the target version and release details.
492
728
 
493
729
  ## Development
494
730
 
495
731
  Prerequisites:
732
+
496
733
  - Node.js 20+
497
734
  - npm 10+
498
735
 
@@ -530,6 +767,29 @@ npm run audit:fix # Auto-fix vulnerabilities
530
767
  npm run audit:production # Audit production dependencies only
531
768
  ```
532
769
 
770
+ ### Automated Demo Regeneration ๐Ÿ”„
771
+
772
+ Demo files are automatically regenerated when tools change via GitHub Actions:
773
+
774
+ - **Trigger**: Any changes to `src/tools/**/*.ts` in a pull request
775
+ - **Action**: Automatically runs `npm run test:demo` to regenerate demos
776
+ - **Result**: Updated demo files are committed to the PR automatically
777
+
778
+ **Benefits**:
779
+
780
+ - โœ… Documentation always stays in sync with code
781
+ - โœ… No manual steps to remember
782
+ - โœ… Reviewers can see demo changes alongside code changes
783
+
784
+ **Workflow**: [`.github/workflows/auto-regenerate-demos.yml`](./.github/workflows/auto-regenerate-demos.yml)
785
+
786
+ **Manual regeneration** (if needed):
787
+
788
+ ```bash
789
+ npm run build
790
+ npm run test:demo
791
+ ```
792
+
533
793
  ### Git Hooks with Lefthook ๐Ÿช
534
794
 
535
795
  This project uses [Lefthook](https://github.com/evilmartians/lefthook) for fast, reliable Git hooks that enforce code quality and security standards.
@@ -537,6 +797,7 @@ This project uses [Lefthook](https://github.com/evilmartians/lefthook) for fast,
537
797
  **Mandatory for GitHub Copilot Agent**: All quality gates must pass before commits and pushes.
538
798
 
539
799
  Setup (automatic via `npm install`):
800
+
540
801
  ```bash
541
802
  npm run hooks:install # Install lefthook git hooks
542
803
  npm run hooks:uninstall # Remove lefthook git hooks
@@ -545,17 +806,20 @@ npx lefthook run pre-push # Run pre-push checks manually
545
806
  ```
546
807
 
547
808
  **Pre-commit hooks** (fast, parallel execution):
809
+
548
810
  - ๐Ÿ”’ **Security**: Gitleaks secret detection
549
811
  - ๐ŸŸจ **Code Quality**: Biome formatting & linting
550
812
  - ๐Ÿ”ท **Type Safety**: TypeScript type checking
551
813
  - ๐Ÿงน **Code Hygiene**: Trailing whitespace & EOF fixes
552
814
 
553
815
  **Pre-push hooks** (comprehensive validation):
816
+
554
817
  - ๐Ÿ”’ **Security Audit**: Dependency vulnerability scanning (moderate+ level)
555
818
  - ๐Ÿงช **Testing**: Full test suite (unit, integration, demo, MCP)
556
819
  - โšก **Quality**: Type checking + Biome validation
557
820
 
558
821
  **Why Lefthook?**
822
+
559
823
  - โšก **Fast**: Written in Go, parallel execution
560
824
  - ๐Ÿ”„ **Reliable**: Better error handling than pre-commit
561
825
  - ๐Ÿค– **CI Integration**: Mandatory quality gates for GitHub Copilot Agent
@@ -583,19 +847,19 @@ VS Code + Docker settings:
583
847
 
584
848
  ```json
585
849
  {
586
- "mcp": {
587
- "servers": {
588
- "mcp-ai-agent-guidelines": {
589
- "command": "docker",
590
- "args": [
591
- "run",
592
- "--rm",
593
- "-i",
594
- "ghcr.io/anselmoo/mcp-ai-agent-guidelines:latest"
595
- ]
596
- }
597
- }
598
- }
850
+ "mcp": {
851
+ "servers": {
852
+ "mcp-ai-agent-guidelines": {
853
+ "command": "docker",
854
+ "args": [
855
+ "run",
856
+ "--rm",
857
+ "-i",
858
+ "ghcr.io/anselmoo/mcp-ai-agent-guidelines:latest"
859
+ ]
860
+ }
861
+ }
862
+ }
599
863
  }
600
864
  ```
601
865
 
@@ -632,16 +896,52 @@ When vulnerabilities are detected:
632
896
  - Tools implementation: see `src/tools/` in this repo.
633
897
  - Generated examples: see `demos/` and links above.
634
898
 
899
+ ## Disclaimer
900
+
901
+ This project references third-party tools, frameworks, APIs, and services for informational purposes. See [DISCLAIMER.md](./DISCLAIMER.md) for important information about external references, trademarks, and limitations of liability.
902
+
635
903
  ## Contributing
636
904
 
637
- Contributions welcome. Please see [CONTRIBUTING.md](./CONTRIBUTING.md). Keep changes typed, linted, and include tests when behavior changes.
905
+ Contributions welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
906
+
907
+ ### Developer Resources
908
+
909
+ - **[Complete Documentation](./docs/README.md)** - Full documentation index
910
+ - **[Clean Code Standards](./docs/tips/CLEAN_CODE_INITIATIVE.md)** - Quality requirements and scoring
911
+ - **[Error Handling Patterns](./docs/tips/ERROR_HANDLING.md)** - Best practices for error handling
912
+ - **[Architecture Guide](./docs/tips/BRIDGE_CONNECTORS.md)** - System architecture and integration patterns
913
+ - **[Type System Organization](./docs/tips/TYPE_ORGANIZATION_EXTENSION.md)** - TypeScript conventions
914
+
915
+ ### Quality Standards
916
+
917
+ - **TypeScript strict mode** - All code must pass type checking
918
+ - **100% test coverage goal** - See [Clean Code Initiative](./docs/tips/CLEAN_CODE_INITIATIVE.md)
919
+ - **Biome linting** - Code must pass `npm run quality`
920
+ - **Git hooks** - Automated checks via Lefthook (see [lefthook.yml](./lefthook.yml))
921
+
922
+ Keep changes typed, linted, and include tests when behavior changes.
638
923
 
639
924
  ## License
640
925
 
641
926
  MIT ยฉ Anselmoo โ€” see [LICENSE](./LICENSE).
642
927
 
643
- ## Acknowledgments
928
+ ## References & Acknowledgments
929
+
930
+ For a comprehensive list of references, research papers, and detailed attribution, see **[docs/tips/REFERENCES.md](./docs/tips/REFERENCES.md)**.
931
+
932
+ ### Key Acknowledgments
933
+
934
+ ---
935
+
936
+ - **Model Context Protocol team** for the specification
937
+ - **Anthropic** for prompt caching research
938
+ - **Mermaid community** for diagram tooling
939
+ - **[@ruvnet/claude-flow](https://github.com/ruvnet/claude-flow)** - Inspired flow-based prompting features
940
+ - **[@oraios/serena](https://github.com/oraios/serena)** - Influenced semantic analysis and mode switching
941
+ - **All open-source contributors** whose work has shaped this project
942
+
943
+ See [docs/tips/REFERENCES.md](./docs/tips/REFERENCES.md) for the complete list of research papers, projects, and inspirations.
644
944
 
645
- - Model Context Protocol team for the spec
646
- - Anthropic for prompt caching research
647
- - Mermaid community for diagram tooling
945
+ <!-- FOOTER:START -->
946
+ ![Footer](docs/.frames-static/09-footer.svg)
947
+ <!-- FOOTER:END -->