mcp-ai-agent-guidelines 0.7.2 → 0.7.4

package/README.md

@@ -130,14 +130,18 @@ After adding the server, open your chat client (e.g., Cline in VS Code). The too
 
 - Run a tool directly by name:
 	- `hierarchical-prompt-builder` — Provide context, goal, and optional requirements.
+	- `clean-code-scorer` — Calculate comprehensive Clean Code score (0-100) with coverage metrics.
 	- `code-hygiene-analyzer` — Paste code or point to a file and set language.
 	- `mermaid-diagram-generator` — Describe the system and select a diagram type.
 - Ask in natural language and pick the suggested tool.
 
 Example prompts:
 - "Use hierarchical-prompt-builder to create a refactor plan for src/index.ts with outputFormat markdown."
+- "Use clean-code-scorer to analyze my project with current coverage metrics and get a quality score."
 - "Analyze this Python file with code-hygiene-analyzer; highlight security issues."
-- "Generate a Mermaid diagram for our pipeline using mermaid-diagram-generator (flowchart)."
+- "Generate a Mermaid sequence diagram showing: User sends request to API, API queries Database, Database returns data, API responds to User."
+- "Create an ER diagram for: Customer has Orders, Order contains LineItems, Product referenced in LineItems."
+- "Build a user journey map for our checkout flow using mermaid-diagram-generator."
 
 Tip: Most clients can pass file content automatically when you select a file and invoke a tool.
 
@@ -145,6 +149,140 @@ GitHub Chat (VS Code): In the chat, type your request and pick a tool suggestion
 
 ## Features
 
+> **🏆 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.
+> - **Dashboard**: Run `npm run clean-code-dashboard` to generate score report
+> - **MCP Tool**: `clean-code-scorer` for on-demand quality analysis
+> - **Automated Gates**: Lefthook quality gates enforce standards on every commit
+
+> **🆕 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.
+
+> **🌊 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.
+> - **Examples**: [docs/FLOW_PROMPTING_EXAMPLES.md](./docs/FLOW_PROMPTING_EXAMPLES.md)
+> - **Integration Guide**: [docs/FLOW_SERENA_INTEGRATION.md](./docs/FLOW_SERENA_INTEGRATION.md) - Combining flow-based prompting with Serena memory patterns
+
+<details>
+<summary><strong>🔗 Prompt Chaining Builder</strong> — Multi-step prompts with output passing (NEW)</summary>
+
+Usage: `prompt-chaining-builder`
+
+| Parameter      | Required | Description                           |
+| -------------- | -------- | ------------------------------------- |
+| `chainName`    | ✅        | Name of the prompt chain              |
+| `steps`        | ✅        | Array of chain steps with prompts     |
+| `description`  | ❌        | Description of chain purpose          |
+| `context`      | ❌        | Global context for the chain          |
+| `globalVariables` | ❌     | Variables accessible to all steps     |
+| `executionStrategy` | ❌   | sequential/parallel-where-possible    |
+
+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.
+
+**Example:**
+```typescript
+{
+  chainName: "Security Analysis Pipeline",
+  steps: [
+    {
+      name: "Scan",
+      prompt: "Scan for vulnerabilities",
+      outputKey: "vulns"
+    },
+    {
+      name: "Assess",
+      prompt: "Assess severity of {{vulns}}",
+      dependencies: ["vulns"],
+      errorHandling: "retry"
+    }
+  ]
+}
+```
+
+</details>
+
+<details>
+<summary><strong>🌊 Prompt Flow Builder</strong> — Declarative flows with branching/loops (NEW)</summary>
+
+Usage: `prompt-flow-builder`
+
+| Parameter      | Required | Description                           |
+| -------------- | -------- | ------------------------------------- |
+| `flowName`     | ✅        | Name of the prompt flow               |
+| `nodes`        | ✅        | Flow nodes (prompt/condition/loop/parallel/merge/transform) |
+| `edges`        | ❌        | Connections between nodes with conditions |
+| `entryPoint`   | ❌        | Starting node ID                      |
+| `variables`    | ❌        | Flow-level variables                  |
+| `outputFormat` | ❌        | markdown/mermaid/both                 |
+
+Create complex adaptive prompt flows with conditional branching, loops, parallel execution, and merge points. Automatically generates Mermaid flowcharts and execution guides.
+
+**Example:**
+```typescript
+{
+  flowName: "Adaptive Code Review",
+  nodes: [
+    { id: "analyze", type: "prompt", name: "Analyze" },
+    { id: "check", type: "condition", name: "Complex?",
+      config: { expression: "complexity > 10" } },
+    { id: "deep", type: "prompt", name: "Deep Review" },
+    { id: "quick", type: "prompt", name: "Quick Check" }
+  ],
+  edges: [
+    { from: "analyze", to: "check" },
+    { from: "check", to: "deep", condition: "true" },
+    { from: "check", to: "quick", condition: "false" }
+  ]
+}
+```
+
+</details>
+
+<details>
+<summary><strong>🔍 Semantic Code Analyzer</strong> — Symbol-based code understanding (NEW)</summary>
+
+Usage: `semantic-code-analyzer`
+
+| Parameter      | Required | Description                           |
+| -------------- | -------- | ------------------------------------- |
+| `codeContent`  | ✅        | Code content to analyze               |
+| `language`     | ❌        | Programming language (auto-detected)  |
+| `analysisType` | ❌        | symbols/structure/dependencies/patterns/all |
+
+Performs semantic analysis to identify symbols, dependencies, patterns, and structure. Inspired by Serena's language server approach.
+
+</details>
+
+<details>
+<summary><strong>🚀 Project Onboarding</strong> — Comprehensive project familiarization (NEW)</summary>
+
+Usage: `project-onboarding`
+
+| Parameter      | Required | Description                           |
+| -------------- | -------- | ------------------------------------- |
+| `projectPath`  | ✅        | Path to project directory             |
+| `projectName`  | ❌        | Name of the project                   |
+| `projectType`  | ❌        | library/application/service/tool/other |
+| `analysisDepth`| ❌        | quick/standard/deep                   |
+| `includeMemories` | ❌     | Generate project memories (default: true) |
+
+Analyzes project structure, detects technologies, and generates memories for context retention. Based on Serena's onboarding system.
+
+</details>
+
+<details>
+<summary><strong>🔄 Mode Switcher</strong> — Flexible agent operation modes (NEW)</summary>
+
+Usage: `mode-switcher`
+
+| Parameter      | Required | Description                           |
+| -------------- | -------- | ------------------------------------- |
+| `targetMode`   | ✅        | Mode to switch to (planning/editing/analysis/etc.) |
+| `currentMode`  | ❌        | Current active mode                   |
+| `context`      | ❌        | Operating context (desktop-app/ide-assistant/etc.) |
+| `reason`       | ❌        | Reason for mode switch                |
+
+Switches between operation modes with optimized tool sets and prompting strategies. Modes include: planning, editing, analysis, interactive, one-shot, debugging, refactoring, documentation.
+
+</details>
+
 <details>
 <summary><strong>Hierarchical Prompt Builder</strong> — Build structured prompts with clear hierarchies</summary>
 
@@ -205,11 +343,75 @@ Usage: `security-hardening-prompt-builder`
 
 Usage: `mermaid-diagram-generator`
 
-| Parameter     | Required | Description                                                      |
-| ------------- | -------- | ---------------------------------------------------------------- |
-| `description` | ✅        | Description of the system or process to diagram                  |
-| `diagramType` | ✅        | Type: `flowchart`, `sequence`, `class`, `state`, `gantt`, `pie` |
-| `theme`       | ❌        | Visual theme for the diagram                                     |
+Generates Mermaid diagrams with intelligent parsing of descriptions for rich, customizable visualizations.
+
+| Parameter          | Required | Description                                                                                                                                          |
+| ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `description`      | ✅        | Description of the system or process to diagram. Be detailed and specific for better diagram generation.                                            |
+| `diagramType`      | ✅        | Type: `flowchart`, `sequence`, `class`, `state`, `gantt`, `pie`, `er`, `journey`, `quadrant`, `git-graph`, `mindmap`, `timeline`                   |
+| `theme`            | ❌        | Visual theme: `default`, `dark`, `forest`, `neutral`                                                                                                 |
+| `direction`        | ❌        | Flowchart direction: `TD`/`TB` (top-down), `BT` (bottom-top), `LR` (left-right), `RL` (right-left)                                                  |
+| `strict`           | ❌        | If true, never emit invalid diagram; use fallback if needed (default: true)                                                                          |
+| `repair`           | ❌        | Attempt auto-repair on validation failure (default: true)                                                                                            |
+| `accTitle`         | ❌        | Accessibility title (added as Mermaid comment)                                                                                                       |
+| `accDescr`         | ❌        | Accessibility description (added as Mermaid comment)                                                                                                 |
+| `customStyles`     | ❌        | Custom CSS/styling directives for advanced customization                                                                                             |
+| `advancedFeatures` | ❌        | Type-specific advanced features (e.g., `{autonumber: true}` for sequence diagrams)                                                                   |
+
+**Enhanced Features:**
+
+- **Intelligent Description Parsing**: All diagram types now parse descriptions to extract relevant entities, relationships, and structures
+- **New Diagram Types**:
+  - `er` - Entity Relationship diagrams for database schemas
+  - `journey` - User journey maps for UX workflows
+  - `quadrant` - Quadrant/priority charts for decision matrices
+  - `git-graph` - Git commit history visualization
+  - `mindmap` - Hierarchical concept maps
+  - `timeline` - Event timelines and roadmaps
+- **Advanced Customization**: Direction control, themes, custom styles, and type-specific features
+- **Smart Fallbacks**: Generates sensible default diagrams when description parsing is ambiguous
+
+**Examples:**
+
+```bash
+# Sequence diagram with participants auto-detected from description
+{
+  "description": "User sends login request to API. API queries Database for credentials. Database returns user data. API responds to User with token.",
+  "diagramType": "sequence",
+  "advancedFeatures": {"autonumber": true}
+}
+
+# Class diagram with relationships extracted
+{
+  "description": "User has id and email. Order contains Product items. User places Order. Product has price and name.",
+  "diagramType": "class"
+}
+
+# ER diagram for database schema
+{
+  "description": "Customer places Order. Order contains LineItem. Product is referenced in LineItem.",
+  "diagramType": "er"
+}
+
+# User journey map
+{
+  "description": "Shopping Journey. Section Discovery: User finds product. User reads reviews. Section Purchase: User adds to cart. User completes checkout.",
+  "diagramType": "journey"
+}
+
+# Gantt chart with tasks from description
+{
+  "description": "Project: Feature Development. Phase Planning: Research requirements. Design architecture. Phase Development: Implement backend. Create frontend. Phase Testing: QA validation.",
+  "diagramType": "gantt"
+}
+
+# Flowchart with custom direction
+{
+  "description": "Receive request. Validate input. Process data. Return response.",
+  "diagramType": "flowchart",
+  "direction": "LR"
+}
+```
 
 </details>
 
@@ -323,6 +525,9 @@ npm run test:demo        # Demo runner
 npm run test:mcp         # MCP smoke script
 npm run test:coverage:unit # Unit test coverage (text-summary, lcov, html)
 npm run quality          # Type-check + Biome check
+npm run audit            # Security audit (production dependencies)
+npm run audit:fix        # Auto-fix vulnerabilities
+npm run audit:production # Audit production dependencies only
 ```
 
 ### Git Hooks with Lefthook 🪝
@@ -346,6 +551,7 @@ npx lefthook run pre-push    # Run pre-push checks manually
 - 🧹 **Code Hygiene**: Trailing whitespace & EOF fixes
 
 **Pre-push hooks** (comprehensive validation):
+- 🔒 **Security Audit**: Dependency vulnerability scanning (moderate+ level)
 - 🧪 **Testing**: Full test suite (unit, integration, demo, MCP)
 - ⚡ **Quality**: Type checking + Biome validation
 
@@ -395,9 +601,30 @@ VS Code + Docker settings:
 
 ## Security
 
-- No secrets committed; releases use provenance where supported.
-- Docker images are signed (Cosign); supply‑chain security via Sigstore.
-- Report vulnerabilities via GitHub Security tab or Issues.
+- **Dependency Scanning**: Automated vulnerability scanning runs on every PR and push to main
+  - Production dependencies: fails on moderate+ vulnerabilities
+  - All dependencies: audited and reported (dev dependencies don't block builds)
+  - Local audit: `npm run audit` or `npm audit --audit-level=moderate`
+  - Auto-fix: `npm run audit:fix` to automatically fix vulnerabilities when possible
+  - Pre-push hook: automatically checks for vulnerabilities before pushing code
+- **Secrets Protection**: No secrets committed; releases use provenance where supported
+- **Supply Chain Security**: Docker images are signed (Cosign); artifacts signed via Sigstore
+- **Vulnerability Reporting**: Report security issues via [GitHub Security tab](https://github.com/Anselmoo/mcp-ai-agent-guidelines/security) or Issues
+
+### Remediation Steps for Maintainers
+
+When vulnerabilities are detected:
+
+1. **Review the vulnerability**: `npm audit` provides details about affected packages
+2. **Update dependencies**: `npm run audit:fix` to apply automatic fixes
+3. **Manual updates**: If auto-fix doesn't work, update package.json manually:
+   ```bash
+   npm update <package-name>
+   # or for major version updates
+   npm install <package-name>@latest
+   ```
+4. **Test changes**: Run `npm run test:all` to ensure updates don't break functionality
+5. **Override if needed**: For false positives or accepted risks, document in security policy
 
 ## Documentation