memory-journal-mcp 7.7.0 → 8.0.0

package/skills/golang/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: golang
 description: |
-  Master Go development using production-grade best practices merged from the Google and Uber style guides. Use whenever writing Go code, designing APIs, handling errors, managing goroutines, or configuring linters.
+  Master Go development using production-grade best practices merged from the Google and Uber style guides. Use whenever writing backend Go microservices, designing APIs, handling errors, managing goroutines, or configuring linters.
+  Keywords: channels, context propagation, go.mod, Go generics. Do NOT trigger for generic 'build a server' requests unless the platform/language is explicitly specified as Go/Golang.
 ---
 
 # Golang Engineering Standards
@@ -52,3 +53,9 @@ This skill synthesizes the absolute best practices from the ecosystem (Uber Guid
 ## 7. Tooling & Enforcement
 
 - The agent should prioritize running `go fmt ./...` and `golangci-lint run` (if available) before confirming code completion.
+
+## 8. Security
+
+- **Command Injection**: Sanitize all inputs to `exec.Command`. Never pass unsanitized user input to the shell.
+- **SQL Injection**: Always use parameterized queries (e.g. `db.QueryRow("SELECT * FROM users WHERE id = ?", id)`).
+- **Path Traversal**: Validate and clean paths using `filepath.Clean` before `filepath.Join` to prevent directory escape vulnerabilities.

package/skills/graphql/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: graphql
+description: |
+  GraphQL best practices. Use when designing GraphQL schemas, writing resolvers, handling mutations, avoiding N+1 query problems (DataLoader), or configuring GraphQL servers. NOT for REST APIs, generic database design, or ORM setups.
+---
+
+# GraphQL Best Practices
+
+Standards for designing and implementing GraphQL APIs.
+
+## 1. Schema Design
+
+- **Business Logic Isolation**: Do not write business logic inside resolvers. Resolvers should only extract arguments and pass them to dedicated service/domain layer functions.
+- **Nullability**: Be mindful of non-null (`!`) fields. Only mark fields as non-null if you are absolutely certain they will never be missing, as a single null in a non-null field will bubble up and destroy the entire parent object.
+- **Custom Scalars**: Use custom scalars (e.g., `DateTime`, `Email`) to enforce type constraints at the schema level instead of raw `String`.
+
+## 2. Mutations
+
+- **Input Types**: Use a single, required `input` object argument for mutations instead of passing many individual arguments.
+- **Payload Types**: Return a specific payload type (e.g., `UpdateUserPayload`) that includes the mutated object and any potential operation-specific errors, rather than just returning the object.
+
+## 3. Performance (N+1 Problem)
+
+- **DataLoader**: ALWAYS use Facebook's `dataloader` pattern (or equivalent) to batch and cache database requests for nested relationships. Never loop and await queries inside child resolvers.
+- **Query Complexity**: Implement query complexity limits or depth limits on your GraphQL server to prevent malicious or accidental resource exhaustion.
+
+## 4. Error Handling
+
+- Use the standard `errors` array for unexpected exceptions.
+- For business logic errors (e.g., "Email already taken"), model them as Union types in your schema (e.g., `union CreateUserResult = User | EmailAlreadyTakenError`) so clients can handle them gracefully.

package/skills/hono/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: hono
+description: |
+  Hono framework best practices. Use when building, reviewing, or debugging Hono applications, especially on Cloudflare Workers. Covers routing, middleware, context (c), and RPC patterns. Do NOT trigger for generic 'build a server' requests unless Hono or Cloudflare Workers is explicitly requested.
+---
+
+# Hono Framework Guidelines
+
+This skill defines the standards for building ultra-fast web applications using Hono, primarily targeted at edge runtimes like Cloudflare Workers.
+
+## 1. Core Principles
+
+- **Standard Request/Response**: Hono is built on Web Standards. Familiarize yourself with standard `Request` and `Response` objects.
+- **Context (`c`)**: The `Context` object is central to Hono. It wraps the request, response, and environment bindings.
+- **Middleware-First**: Prefer composing small, focused middleware over large handler functions.
+- **RPC (`hono/client`)**: Use Hono's RPC feature for end-to-end type safety between backend routes and frontend clients.
+
+## 2. Environment Variables & Bindings (Cloudflare Workers)
+
+Always strictly type your environment bindings for Cloudflare Workers.
+
+```typescript
+import { Hono } from 'hono'
+
+type Bindings = {
+  DB: D1Database
+  API_KEY: string
+}
+
+const app = new Hono<{ Bindings: Bindings }>()
+
+app.get('/', (c) => {
+  const db = c.env.DB
+  return c.text('Hello Hono!')
+})
+```
+
+## 3. Middleware Usage
+
+Always use the built-in middleware for common tasks.
+
+- `cors()` for CORS.
+- `secureHeaders()` for security headers.
+- `logger()` for request logging.
+
+```typescript
+import { cors } from 'hono/cors'
+import { secureHeaders } from 'hono/secure-headers'
+
+app.use('*', cors())
+app.use('*', secureHeaders())
+```
+
+## 4. Routing & Validation
+
+Use `zodValidator` from `@hono/zod-validator` to validate inputs securely.
+
+```typescript
+import { zValidator } from '@hono/zod-validator'
+import { z } from 'zod'
+
+app.post(
+  '/post',
+  zValidator(
+    'json',
+    z.object({
+      title: z.string(),
+      body: z.string(),
+    })
+  ),
+  (c) => {
+    const { title, body } = c.req.valid('json')
+    return c.json({ title, body })
+  }
+)
+```
+
+## 5. Security Gates
+
+- **Input Validation**: Never trust client input. Always validate using Zod.
+- **Secrets**: Do not hardcode secrets. Always use `c.env`.
+- **SQL Injection**: When using D1 or SQLite, always use parameterized queries or an ORM like Drizzle. Never concatenate user input into SQL strings.

package/skills/journal-optimizer/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: journal-optimizer
+description: |
+  Guided database pruning and optimization workflows for memory-journal-mcp.
+  Uses importance scores, relationship density, and entry metadata to identify
+  low-value entries for safe soft-deletion. Includes dry-run previews, backup
+  gates, and revert guidance. Use when the user says "clean up the database",
+  "optimize entries", "prune old entries", "database maintenance",
+  "what entries can I delete?", "my journal is getting too big", or "archive old entries".
+---
+
+# Journal Optimizer
+
+Guided workflows for intelligently pruning, cleaning, and optimizing a
+memory-journal-mcp database. Every operation uses the soft-delete system
+as a safe first pass — entries remain recoverable via `restore_backup`
+until explicitly purged.
+
+## Prerequisites
+
+The following tool groups must be enabled:
+
+| Group           | Required Tools                                              | Purpose                        |
+| --------------- | ----------------------------------------------------------- | ------------------------------ |
+| `admin`         | `delete_entry`, `update_entry`                              | Soft-delete entries            |
+| `analytics`     | `get_statistics`                                            | Importance scores, graph stats |
+| `search`        | `search_entries`, `search_by_date_range`, `semantic_search` | Find candidates                |
+| `backup`        | `backup_journal`, `list_backups`, `restore_backup`          | Safety net                     |
+| `codemode`      | `mj_execute_code`                                           | Batch operations               |
+| `relationships` | `visualize_relationships`                                   | Orphan detection               |
+
+If any required group is missing, inform the user and suggest adding it
+via `--tool-filter` or `MEMORY_JOURNAL_MCP_TOOL_FILTER`.
+
+## Importance Score Reference
+
+The server computes importance scores (0.0–1.0) for every entry using
+a weighted formula. Understanding this formula is essential for making
+intelligent pruning decisions.
+
+### Formula
+
+| Component         | Weight | Max Score | How It's Earned                                                        |
+| ----------------- | ------ | --------- | ---------------------------------------------------------------------- |
+| **Significance**  | 0.30   | 0.30      | Entry has a `significance_type` (milestone, decision, release, etc.)   |
+| **Relationships** | 0.35   | 0.35      | Entry has ≥5 relationships (linear scale: 1 rel = 0.07)                |
+| **Causal**        | 0.20   | 0.20      | Entry has ≥3 causal relationships (`blocked_by`, `resolved`, `caused`) |
+| **Recency**       | 0.15   | 0.15      | Created within the last 90 days (linear decay to 0 at day 90)          |
+
+### Threshold Guide
+
+| Score       | Label      | Meaning                                                  |
+| ----------- | ---------- | -------------------------------------------------------- |
+| `0.00`      | Expendable | No significance, no relationships, older than 90 days    |
+| `0.01–0.14` | Low        | Minimal context — weak tags or a single old relationship |
+| `0.15–0.29` | Moderate   | Has some context but not structurally important          |
+| `0.30–0.49` | High       | Well-connected or has significance markers               |
+| `0.50+`     | Critical   | Major decisions, densely linked entries, milestones      |
+
+> **Key insight**: Entries scoring `0.00` have zero structural value to the
+> knowledge graph. They are safe to soft-delete in virtually all cases.
+> Entries scoring `0.01–0.14` should be reviewed individually.
+
+## Safety Rules
+
+These rules are **mandatory** for all workflows:
+
+1. **NEVER** use `permanent: true` unless the user explicitly says
+   "permanent delete" or "hard delete"
+2. **ALWAYS** call `backup_journal` before any batch delete — abort if
+   the backup fails
+3. **ALWAYS** show the user what will be deleted before deleting
+4. **NEVER** delete entries with `significance_type` set without explicit
+   user approval, regardless of other scores
+5. **Maximum batch size**: 50 entries per operation to prevent accidental
+   mass deletion
+6. **Log all cleanup operations** as a journal entry with
+   `entry_type: 'maintenance'` and tag `database-optimizer`
+
+## Safe Deletion Protocol
+
+For all destructive workflows (2–5), execute this exact sequence once the candidate list is prepared:
+
+1. **HITL Gate**: Ask the user to confirm the exact candidate list.
+2. **Backup**: Call `backup_journal`. **ABORT** immediately if the backup fails.
+3. **Execute**: Run the soft-delete batch script for the specific workflow (see [references/optimizer-scripts.md](references/optimizer-scripts.md)).
+4. **Log & Report**: Log a maintenance entry and provide revert instructions.
+
+---
+
+## Workflow 1: Importance Audit (Dry Run)
+
+Analyze the database to surface low-importance entries without modifying anything. This is the recommended starting point for all optimization work.
+
+### Steps
+
+**Step 1 & 2 — Gather stats and score entries:**
+_Read and execute the Workflow 1 code block in [references/optimizer-scripts.md](references/optimizer-scripts.md)._
+
+**Step 3 — Present results:**
+
+Render the distribution as a table:
+
+| Tier                 | Count | Action                                  |
+| -------------------- | ----- | --------------------------------------- |
+| Critical (≥0.50)     | N     | Keep — these are structural anchors     |
+| High (0.30–0.49)     | N     | Keep — well-connected entries           |
+| Moderate (0.15–0.29) | N     | Review individually if space is needed  |
+| Low (0.01–0.14)      | N     | Candidates for cleanup with user review |
+| Expendable (0.00)    | N     | Safe to soft-delete                     |
+
+Show the expendable sample with IDs, types, ages, and snippets.
+Ask the user which tier(s) they want to target for cleanup.
+
+---
+
+## Workflow 2: Targeted Cleanup (Interactive)
+
+Soft-delete entries matching user-selected criteria from the audit.
+
+### Steps
+
+1. Run **Workflow 1** if not already completed this session.
+2. Present the candidate list with importance breakdowns.
+3. Execute the **Safe Deletion Protocol** for user-selected entries.
+
+---
+
+## Workflow 3: Orphan Cleanup
+
+Find and soft-delete entries with zero relationships.
+
+### Steps
+
+1. Retrieve orphaned statistics and entries:
+   _Read and execute the Workflow 3 code block in [references/optimizer-scripts.md](references/optimizer-scripts.md)._
+2. Present the orphan list. Flag any with `significance_type` set — these should NOT be deleted without explicit approval.
+3. Execute the **Safe Deletion Protocol**.
+
+> **Alternative to deletion**: For orphans that have value but lack connections, suggest using `link_entries` to connect them to related entries instead of deleting them.
+
+---
+
+## Workflow 4: Duplicate Detection
+
+> **WARN: High tool-call budget** — This workflow executes an N×N semantic search loop. Limit the search set to 50 entries to avoid exhausting rate limits.
+
+Find entries with semantically similar content that may be redundant.
+
+### Steps
+
+1. Identify candidate duplicates using semantic search:
+   _Read and execute the Workflow 4 code block in [references/optimizer-scripts.md](references/optimizer-scripts.md)._
+2. Present duplicate pairs side-by-side with recommendations.
+3. Execute the **Safe Deletion Protocol** (targeting the lower-scoring entry of each pair).
+
+> **Note**: Semantic search requires the vector index. If `get_vector_index_stats` shows zero indexed entries, suggest running `rebuild_vector_index` first.
+
+---
+
+## Workflow 5: Type-Based Cleanup
+
+Clean up entries by `entry_type` — useful for removing bulk categories that were misclassified or have outlived their usefulness.
+
+### Steps
+
+1. Aggregate entry counts by type using `mj.analytics.getStatistics()`.
+2. Present the type breakdown. Flag commonly low-value types (`personal_reflection`, `retrospective`, `note`).
+3. User selects which types to target and an age threshold.
+4. Preview matching entries:
+   _Read and execute the Workflow 5 code block in [references/optimizer-scripts.md](references/optimizer-scripts.md)._
+5. Execute the **Safe Deletion Protocol**.
+
+---
+
+## Revert Guide
+
+Every workflow creates a backup before mutations. To revert:
+_Follow the restoration commands in [references/optimizer-scripts.md](references/optimizer-scripts.md)._
+
+> **Important**: Soft-deleted entries are physically present but excluded from queries. They are only permanently removed via `permanent: true`, restoring an old backup, or rebuilding from an export.
+
+---
+
+## Post-Optimization
+
+After completing any workflow, recommend these follow-up actions:
+
+1. **Rebuild the vector index** to remove stale embeddings:
+   `rebuild_vector_index`
+2. **Run a statistics check** to verify the database health:
+   `get_statistics`
+3. **Log the optimization** as a journal entry for audit trail
+4. **Review relationship density** — if density dropped below 2.0,
+   consider linking remaining orphans to related entries
+
+## Synergies
+
+| Tool/Workflow          | Relationship                                                       |
+| ---------------------- | ------------------------------------------------------------------ |
+| Auto-Prune (startup)   | Automated version of Workflow 2 with fixed thresholds              |
+| `get_statistics`       | Primary data source for importance scores and graph metrics        |
+| `backup_journal`       | Safety gate for all destructive operations                         |
+| `restore_backup`       | Revert mechanism for soft-deleted entries                          |
+| `rebuild_vector_index` | Post-cleanup maintenance to clean stale embeddings                 |
+| `link_entries`         | Alternative to deletion — connect orphans instead of removing them |

package/skills/journal-optimizer/references/optimizer-scripts.md

@@ -0,0 +1,169 @@
+# Journal Optimizer Scripts
+
+Reference implementations for the workflows defined in `SKILL.md`. Use these code blocks via `mj_execute_code` when conducting database optimization.
+
+## Workflow 1: Importance Audit
+
+**Step 1 & 2 — Gather statistics and score entries:**
+
+```javascript
+const s = await mj.analytics.getStatistics()
+const all = await mj.core.getRecentEntries({ limit: 500 })
+const tiers = { critical: [], high: [], moderate: [], low: [], expendable: [] }
+
+for (const e of all.entries) {
+  const score = e.importanceScore ?? 0
+  if (score >= 0.5) tiers.critical.push(e)
+  else if (score >= 0.3) tiers.high.push(e)
+  else if (score >= 0.15) tiers.moderate.push(e)
+  else if (score > 0) tiers.low.push(e)
+  else tiers.expendable.push(e)
+}
+
+return {
+  total: s.totalEntries,
+  density: s.relationshipComplexity?.avgPerEntry,
+  types: s.entriesByType,
+  distribution: Object.fromEntries(Object.entries(tiers).map(([k, v]) => [k, v.length])),
+  expendableSample: tiers.expendable.slice(0, 10).map((e) => ({
+    id: e.id,
+    type: e.entryType,
+    tags: e.tags,
+    age: Math.floor((Date.now() - new Date(e.timestamp).getTime()) / 86400000) + 'd',
+    snippet: e.content.substring(0, 80),
+  })),
+  lowSample: tiers.low.slice(0, 5).map((e) => ({
+    id: e.id,
+    score: e.importanceScore,
+    type: e.entryType,
+    snippet: e.content.substring(0, 80),
+  })),
+}
+```
+
+## Workflow 2: Targeted Cleanup
+
+**Execute soft-delete batch:**
+
+```javascript
+const ids = [
+  /* user-approved IDs */
+]
+const backup = await mj.backup.backupJournal()
+if (!backup.success) return { error: 'Backup failed — aborting', backup }
+
+const results = []
+for (const id of ids) {
+  const r = await mj.admin.deleteEntry({ entry_id: id })
+  results.push({ id, success: r.success })
+}
+
+const ok = results.filter((r) => r.success).length
+const fail = results.filter((r) => !r.success).length
+
+await mj.core.createEntry({
+  content: `Database optimization: soft-deleted ${ok} entries (batch). Backup: ${backup.filename}`,
+  entry_type: 'maintenance',
+  tags: ['database-optimizer', 'cleanup'],
+})
+
+return { deleted: ok, failed: fail, backupFile: backup.filename }
+```
+
+## Workflow 3: Orphan Cleanup
+
+**Get statistics and retrieve orphaned entries:**
+
+```javascript
+const s = await mj.analytics.getStatistics()
+const all = await mj.core.getRecentEntries({ limit: 500, sort_by: 'importance' })
+const orphans = all.entries.filter((e) => Object.keys(e.relationships || {}).length === 0)
+return {
+  total: s.totalEntries,
+  orphans: orphans.slice(0, 50).map((e) => ({
+    id: e.id,
+    type: e.entryType,
+    tags: e.tags,
+    significance: e.significanceType,
+    age: Math.floor((Date.now() - new Date(e.timestamp).getTime()) / 86400000) + 'd',
+    snippet: e.content.substring(0, 80),
+  })),
+}
+```
+
+## Workflow 4: Duplicate Detection
+
+**Identify candidate duplicates:**
+
+```javascript
+const recent = await mj.core.getRecentEntries({ limit: 50 })
+const candidates = []
+
+for (const entry of recent.entries) {
+  const similar = await mj.search.semanticSearch({
+    query: entry.content.substring(0, 200),
+    limit: 5,
+  })
+  for (const match of similar.entries) {
+    if (match.id !== entry.id && match.similarity > 0.85) {
+      candidates.push({
+        entryA: {
+          id: entry.id,
+          score: entry.importanceScore,
+          snippet: entry.content.substring(0, 60),
+        },
+        entryB: {
+          id: match.id,
+          score: match.importanceScore,
+          snippet: match.content.substring(0, 60),
+        },
+        similarity: match.similarity,
+      })
+    }
+  }
+}
+
+const seen = new Set()
+const unique = candidates.filter((c) => {
+  const key = [Math.min(c.entryA.id, c.entryB.id), Math.max(c.entryA.id, c.entryB.id)].join('-')
+  if (seen.has(key)) return false
+  seen.add(key)
+  return true
+})
+
+return { duplicatePairs: unique.length, pairs: unique.slice(0, 15) }
+```
+
+## Workflow 5: Type-Based Cleanup
+
+**Preview matching entries:**
+
+```javascript
+const cutoff = new Date()
+cutoff.setDate(cutoff.getDate() - 30) // user-specified days
+const matches = await mj.search.searchByDateRange({
+  start_date: '2020-01-01',
+  end_date: cutoff.toISOString().split('T')[0],
+  entry_type: 'personal_reflection',
+  limit: 100, // Update type as needed
+})
+return matches.entries.map((e) => ({
+  id: e.id,
+  score: e.importanceScore,
+  tags: e.tags,
+  snippet: e.content.substring(0, 80),
+}))
+```
+
+## Revert Guide
+
+**Find and restore backup:**
+
+```javascript
+// Step 1: list backups
+const backups = await mj.backup.listBackups()
+console.log(backups.backups)
+
+// Step 2: restore (uncomment and supply filename)
+// await mj.backup.restoreBackup({ filename: 'pre-cleanup-backup-TIMESTAMP.db' });
+```

package/skills/llm-app-engineering/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: llm-app-engineering
+description: |
+  Master modern LLM application engineering patterns. Use when designing prompt chains, evaluating output quality, managing token limits, streaming responses, or integrating LLMs into full-stack applications. SECURITY: Always sanitize user input before passing to LLM prompts to prevent prompt injection.
+---
+
+# LLM App Engineering
+
+Core principles for building robust LLM applications.
+
+## Key Patterns
+
+- **Prompt Engineering**: Use few-shot, chain-of-thought, and clear system instructions.
+- **Context Window Management**: Do not blindly append history to prompts. Implement sliding windows, summarization hooks, or token-based pruning to keep inputs within context limits and ensure high recall for recent instructions.
+- **Token Management**: Track usage, handle limits gracefully, and summarize context dynamically.
+- **Structured Outputs**: Always force structured outputs (e.g., JSON) using schema-guided generation or strict function calling rather than relying on prompt engineering to "ask nicely for JSON".
+- **Streaming**: Always stream responses for perceived performance improvements in UX.
+- **Evaluations (Evals)**: Build automated eval pipelines for your prompts to catch regressions. Do not rely solely on human vibe checks. Implement automated deterministic evals (e.g., regex matching, JSON validation) and LLM-as-a-judge evals for semantic quality.

package/skills/monorepo/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: monorepo
+description: |
+  Monorepo architecture and configuration standards. Use when working with Turborepo, pnpm workspaces, npm workspaces, or configuring shared packages, tsconfig bases, and internal dependencies. NOT for generic package management or single-package repositories. Require explicit monorepo context.
+---
+
+# Monorepo Standards
+
+Monorepos organize multiple applications and packages in a single repository, but require strict configuration to avoid dependency hell and build-time bottlenecks.
+
+## 1. Workspace Configuration (pnpm workspaces)
+
+- **Root Definition**: Define the `pnpm-workspace.yaml` explicitly at the root, separating applications (`apps/*`) from internal libraries (`packages/*`).
+- **Internal Dependencies**: Link internal packages using the `workspace:*` protocol. This ensures that the package manager resolves to the local source rather than attempting to fetch from the npm registry.
+
+```json
+{
+  "dependencies": {
+    "@my-org/ui": "workspace:*",
+    "@my-org/tsconfig": "workspace:*"
+  }
+}
+```
+
+## 2. Turborepo Configuration
+
+- **Pipeline Definition**: Define dependencies in `turbo.json`. Ensure `build` depends on `^build` (meaning a package's build step waits for its dependencies to build first).
+- **Caching**: Ensure `outputs` are correctly defined for cache hits (e.g., `.next/**`, `dist/**`).
+- **Dev Tasks**: The `dev` task should typically be configured as `persistent: true` since it starts a long-running server.
+
+```json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**", ".next/**"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    }
+  }
+}
+```
+
+## 3. Shared Configurations
+
+- **Shared TSConfig**: Create a `packages/tsconfig` containing `base.json`, `nextjs.json`, and `react-library.json`. Applications should extend these rather than duplicating compiler options.
+- **Shared ESLint/Prettier**: Centralize linting rules in a `packages/eslint-config` workspace to guarantee consistency across all apps.
+- **Entrypoints**: Use `"main"`, `"module"`, and `"types"` fields in `package.json` correctly for shared packages. Alternatively, rely on modern bundlers and Next.js transpile packages to consume raw TypeScript (`src/index.ts`).
+
+## 4. CI/CD Integration
+
+- **Remote Caching**: Always enable Vercel Remote Caching or an equivalent remote cache in CI to drastically reduce build times for unmodified packages.
+- **Affected Builds**: Use `--filter` commands (`turbo run build --filter=...[origin/main]`) to only test and build packages that changed in the current PR.

package/skills/multi-agent-orchestration/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: multi-agent-orchestration
+description: |
+  Patterns for multi-agent systems and agentic workflows. Use when designing systems where multiple AI agents collaborate, delegate tasks, or follow structured workflows (e.g. Plan-and-Execute).
+---
+
+# Multi-Agent Orchestration
+
+## Architectural Patterns
+
+- **Supervisor Pattern**: A top-level agent routes tasks to specialized worker agents. In a multi-agent setup, designate a Supervisor agent responsible for delegating sub-tasks to worker agents and synthesizing their final outputs.
+- **Plan-and-Execute**: One agent plans steps, others execute, and a reviewer validates. For complex tasks, separate the planning phase (using a high-reasoning model) from the execution phase (using faster, specialized models or tools).
+- **Tool Use**: Agents should have narrowly scoped, deterministic tools to interact with the environment. Worker agents should have the minimum tools required (Principle of Least Privilege). Do not give every agent access to file deletion or database writes.
+- **State Management**: Use persistent state (e.g., graphs) to track the conversation and execution flow. Use graph-based state machines (e.g., LangGraph) to model agent interactions as predictable state transitions with explicit human-in-the-loop (HITL) checkpoints for destructive actions.

package/skills/mysql/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: mysql
-description: Enterprise MySQL & MariaDB production rules — query safety, connection pooling, and strict schema configurations.
+description: |
+  Use when designing, querying, or managing a MySQL or MariaDB database.
+  Enforces enterprise production rules for query safety (strict parameterization), 
+  connection pooling, and strict schema configurations (STRICT_TRANS_TABLES).
+  MUST-ASK: Require explicit database engine name before triggering. Never guess. Do NOT trigger for generic "set up a database" requests. NOT for Postgres or SQLite. NOT for ORM-managed migrations.
 ---
 
 # MySQL / MariaDB Production Standards
@@ -27,4 +31,4 @@ MySQL and MariaDB are powerful relationship-driven databases, but AI agents MUST
 ## 4. Ecosystem & Diagnostics
 
 - **Error Handling**: When intercepting connection drops or authentication failures (e.g., ER_ACCESS_DENIED_ERROR), instruct the user to verify their `.env` configurations (`MYSQL_URL`, `MYSQL_HOST`, etc.). Do not hallucinate database names.
-- **Using MCP**: If the `mysql-mcp` server is attached, prefer utilizing its formal 227+ structured tools over executing raw Bash CLI scripts (`mysql -h ...`) to guarantee payload optimizations and schema intelligence.
+- **Using MCP**: If the `mysql-mcp` server is attached, prefer utilizing its formal structured tools over executing raw Bash CLI scripts (`mysql -h ...`) to guarantee payload optimizations and schema intelligence.