Ai Agent Guidelines

npm version License: MIT Node ≥22.7.5 CI

[!CAUTION] 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.

A TypeScript ESM MCP server exposing 19 public instruction tools and 3 utility tools, backed by 72 internal skills across 16 domain families — from requirements discovery and code quality through governance and resilience.

📖 Full documentation on GitHub Pages

---

Table of Contents

• Requirements
• Installation
• VS Code Integration (One-Click)
• MCP Server Configuration
• CLI Usage
• Features
• Instruction Workflows
• Skill Taxonomy
• Configuration
• Development
• Environment Variables
• Contributing
• License

---

Requirements

Runtime	Version
Node.js	≥ 22.7.5
npm	≥ 10.0.0

---

Installation

npx (zero-install, recommended for MCP config)

npx -y mcp-ai-agent-guidelines@latest

Global install

npm install -g mcp-ai-agent-guidelines

# MCP stdio server entrypoint
mcp-ai-agent-guidelines

# IDE hook + skill-file installer
mcp-cli --help

Local install (monorepo / project dependency)

npm install mcp-ai-agent-guidelines

---

VS Code Integration (One-Click)

Click a badge below to add this MCP server directly to VS Code (User Settings → mcp.servers):

Install with NPX in VS Code Install with NPX in VS Code Insiders Install with Docker in VS Code Install with Docker in VS Code Insiders

Or add manually to User Settings JSON:

{
  "mcp": {
    "servers": {
      "ai-agent-guidelines": {
        "command": "npx",
        "args": ["-y", "mcp-ai-agent-guidelines@latest"]
      }
    }
  }
}

Using Docker:

{
  "mcp": {
    "servers": {
      "ai-agent-guidelines": {
        "command": "docker",
        "args": ["run", "--rm", "-i", "ghcr.io/anselmoo/mcp-ai-agent-guidelines:latest"]
      }
    }
  }
}

---

MCP Server Configuration

Add the server to your MCP host config. The entry-point is dist/index.js and communicates over stdin/stdout.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)

[!IMPORTANT] Claude Desktop spawns the server with a different working directory than your project. Set MCP_WORKSPACE_ROOT to the absolute path of the project you want the server to write state into.

{
  "mcpServers": {
    "ai-agent-guidelines": {
      "command": "npx",
      "args": ["-y", "mcp-ai-agent-guidelines@latest"],
      "env": {
        "MCP_WORKSPACE_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

VS Code (.vscode/mcp.json or user settings)

{
  "servers": {
    "ai-agent-guidelines": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-ai-agent-guidelines@latest"],
      "env": {
        "MCP_WORKSPACE_ROOT": "${workspaceFolder}"
      }
    }
  }
}

From local build

{
  "mcpServers": {
    "ai-agent-guidelines": {
      "command": "node",
      "args": ["/path/to/repo/dist/index.js"]
    }
  }
}

---

CLI Usage

The published package exposes two entrypoints:

• mcp-ai-agent-guidelines — MCP stdio server entrypoint for editors and MCP hosts (the primary surface; an agent reaches all functionality through this)
• mcp-cli — a thin IDE-integration installer. It does not duplicate MCP server functionality; its only purpose is to wire up the hook scripts and per-IDE SKILL.md files that an agent itself cannot install.

# Install SessionStart / PreToolUse hooks for an IDE
mcp-cli hooks setup --client vscode        # or copilot-cli / claude-code
mcp-cli hooks print --client claude-code   # preview without writing

# Emit per-IDE skill files for every public instruction
mcp-cli onboard skills --target all        # copilot + claude + codex
mcp-cli onboard skills --target claude --global   # user-home install

Instruction-tool input schema — the public instruction workflows share this shape:

{
  request: string;        // required — the task description
  context?: string;       // optional — background context
  options?: object;       // optional — skill-specific overrides
}

---

Configuration Files

• .mcp-ai-agent-guidelines/config/orchestration.toml — optional orchestration overrides. The MCP server no longer auto-writes this file; defaults come from src/config/orchestration-defaults.ts in memory. Write the file explicitly (via mcp-cli is no longer available — edit by hand, or persist via the model-discover MCP tool's save action) if you need to override the advisory defaults.
• src/config/orchestration-defaults.ts — builtin defaults used in memory whenever a workspace config is absent.

---

Features

• 19 public instruction tools exposed through the MCP instruction surface
• 3 public utility tools for workspace, model-discovery, and visualization operations (before any HIDDEN_TOOLS filtering)
• 72 internal skills across 16 domain prefixes — see Skill Taxonomy
• Bio-inspired adaptive routing: ACO, Hebbian, Slime-mould, Quorum, Homeostatic, Clone-Mutate, Replay
• Governance layer: prompt-injection hardening, PII guardrails, policy validation, regulated-workflow design
• Model orchestration guidance: 5 multi-model patterns (parallel critique, draft-review, majority vote, cascade, free triple)
• Zero runtime LLM calls — advisory outputs; wire a concrete executor to enable real LLM dispatch
• xstate v5 state-machine orchestration built-in
• graphology graph routing for topological skill sequencing

---

Public MCP Surface

ListTools exposes 22 tools on the full surface (MCP_FULL_SURFACE=true); the default slim surface exposes only task-bootstrap and meta-routing:

Category	Count	Tools
Instruction (workflow)	17	meta-routing, bootstrap, implement, refactor, debug, testing, design, review, research, orchestrate, adapt, resilience, evaluate, prompt-engineering, plan, document, govern
Instruction (discovery)	2	task-bootstrap, meta-routing
Utility	3	agent-workspace, model-discover, graph-visualize

The 72 skill definitions are internal workflow assets — not individually exposed as MCP tools. See docs for full tool reference.

---

Skill Taxonomy

Skills are organised under 18 domain-specific prefixes:

Prefix	Domain	Count
req-	Requirements Discovery	4
orch-	Orchestration	4
doc-	Documentation	4
qual-	Code Analysis & Quality	5
synth-	Research & Synthesis	4
flow-	Workflow	3
eval-	Evaluation & Benchmarking	5
debug-	Debugging	4
strat-	Strategy & Decision Making	4
arch-	Architecture Design	4
prompt-	Prompting	4
adapt-	Bio-inspired Adaptive Routing	5
bench-	Advanced Evals	3
lead-	Leadership & Enterprise	7
resil-	Resilience & Self-repair	5
gov-	Safety & Governance	7

Full taxonomy details: docs/architecture/03-skill-graph.md.

---

Instruction Workflows

20 mission-driven instruction workflows orchestrate internal skills into complete task flows:

Instruction	Purpose
meta-routing	Master routing — choose which instruction to invoke
bootstrap	Scope clarification and requirements extraction
implement	Build new features end-to-end
refactor	Improve existing code safely
debug	Diagnose and fix problems
testing	Write, run, and verify tests
design	Architecture and system design
review	Code quality and security review
research	Synthesis, comparison, recommendations
orchestrate	Compose multi-agent workflows
adapt	Bio-inspired adaptive routing
resilience	Self-healing and fault tolerance
evaluate	Benchmark and assess AI quality
prompt-engineering	Build, evaluate, optimise prompts
plan	Strategy, roadmap, sprint planning
document	Generate documentation artifacts
govern	Safety, compliance, guardrails
enterprise	Leadership and enterprise-scale AI strategy

---

Architecture

See docs/architecture/ for ADRs and full module layout. The entry-point is src/index.ts; instructions live in src/instructions/, skills in src/skills/, and generated tool definitions in src/generated/ (do not edit by hand).

---

Development

# Install dependencies
npm install

# Type-check
npm run type-check

# Build (tsc → dist/)
npm run build

# Watch mode
npm run dev

# Run MCP server
node dist/index.js

Code Quality

npm run check          # biome check (lint + format)
npm run check:fix      # auto-fix
npm run quality        # full suite: verify_matrix + type-check + workflow-docs + biome

Regenerate generated tool definitions after editing canonical registries or workflow specs

python3 scripts/generate-tool-definitions.py
npm run build

Verify skill/instruction coverage matrix (zero orphans required)

python3 scripts/verify_matrix.py

---

Testing

npm test                  # vitest run
npm run test:coverage     # vitest + v8 coverage (80% threshold)

Tests live both co-located with source (src/**/*.test.ts) and in src/tests/.

Published package note: the npm package ships dist/, README.md, and LICENSE. Repository-only source assets such as docs/, .github/, and scripts/ are development references, not package runtime files.

---

Environment Variables

Variable	Default	Description
HIDDEN_TOOLS	""	Comma-separated list of tool names to exclude from ListTools
LOG_LEVEL	"info"	Observability log level (debug, info, warn, error)
ALLOW_GOVERNANCE_SKILLS	unset / "false"	Must be true to allow gov-* skills through criticalSkillGuard
DISABLE_ADAPTIVE_ROUTING	unset / "false"	Set to true to hide routing-adapt and block adapt-* skills; enabled by default (opt-out model)
ALLOW_INTENSIVE_SKILLS	unset / "false"	Must be true to allow resource-intensive skills such as bench-eval-suite and eval-prompt-bench
MCP_WORKSPACE_ROOT	unset	Absolute path to the project directory the server should write state into (.mcp-ai-agent-guidelines/). Required when using npx via Claude Desktop, Cursor, or Windsurf — these clients do not preserve the terminal's working directory. VS Code supports ${workspaceFolder}.
MCP_FULL_SURFACE	unset / "false"	Set to true to expose the full surface; default is the slim 2-tool routing surface: task-bootstrap, meta-routing

Target-oriented output & the slim surface. The situation-transform that turns a tool's keyword-matched template into a project-specific deliverable applies to 19 of the 20 public tools — the domain tools (code-review, issue-debug, feature-implement, …) plus both slim-surface tools (meta-routing → routing decision, task-bootstrap → orientation brief). analogy-think is the sole passthrough (it already gates to a request-specific metaphor). The hidden domain tools remain callable by name; set MCP_FULL_SURFACE=true to list them for discovery.

| MCP_SERENA_COMMAND | unset | Opt-in. When set, the server spawns Serena as a child MCP server over stdio and resolves Serena queries directly. When unset (default), the server emits structured advisories that the host model executes via its own Serena connection — recommended when the host (e.g. Claude Code) already runs Serena. | | MCP_SERENA_ARGS | unset | Space-separated args passed to MCP_SERENA_COMMAND. Example: --from git+https://github.com/oraios/serena serena-mcp-server. | | MCP_SERENA_CWD | unset | Working directory for the spawned Serena child. Defaults to the parent process cwd. |

Symbol & memory backend (Serena)

Tool responses can be enriched with Serena's LSP-backed symbol surface and per-project memories. Two modes:

• Advisory mode (default) — no setup. Tool responses append a 🧭 Serena enrichment available footer that names the exact Serena tool (mcp__serena__find_symbol, mcp__serena__list_memories, etc.) and arguments the host model should call. Use this when your MCP host already loads Serena as a sibling server (e.g. Claude Code with Serena configured).
• Child-spawn mode (opt-in) — set MCP_SERENA_COMMAND=uvx and MCP_SERENA_ARGS="--from git+https://github.com/oraios/serena serena start-mcp-server --project <your-project-path>". The server spawns Serena once on startup and resolves queries directly, embedding the data in the response footer. Pin --project explicitly because Serena's global registry won't auto-activate a fresh cwd. Use this mode when no host-level Serena is available. Verify the wiring with npm run test:mcp:serena (requires MCP_SERENA_E2E=1 and uvx installed).

Both modes go through the same internal seam (src/serena/client.ts), so tool code paths are identical regardless of mode.

Skill gates

Skill execution is gated by environment variables above. Model availability is derived from .mcp-ai-agent-guidelines/config/orchestration.toml; strict_mode = false allows warnings-only, strict_mode = true blocks on missing models.

---

Auto Mode & Session Hooks

Long-running agent sessions (VS Code Copilot, Claude Code, Copilot CLI) can drift away from MCP tools after the first few exchanges. The session hooks mechanism counteracts this by injecting lightweight reminders at the IDE lifecycle boundaries.

What the hooks do

Hook	Trigger	Effect
SessionStart	New chat session begins	Reminds agent to call task-bootstrap / meta-routing first
PreToolUse	Before every tool call	Detects consecutive non-MCP calls; nudges agent to re-orient

Quick install

# VS Code / Copilot CLI (writes to ~/.copilot/hooks/)
mcp-cli hooks setup --client vscode

# Claude Code (writes to ~/.claude/)
mcp-cli hooks setup --client claude-code

# Inspect what will be written without touching the filesystem
mcp-cli hooks print --client vscode

Manual install

Copy the following JSON to ~/.copilot/hooks/mcp-ai-agent-guidelines-hooks.json:

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "mcp-ai-agent-guidelines hooks remind-session"
      }
    ],
    "PreToolUse": [
      {
        "type": "command",
        "command": "mcp-ai-agent-guidelines hooks remind-drift"
      }
    ]
  }
}

Manual install: add scripts/hooks/session-start-bootstrap.mjs as a SessionStart hook in ~/.claude/settings.json (or ~/.copilot/hooks/).

Routing guidance

The .claude/rules/ directory contains IDE-readable routing tables:

• .claude/rules/default.md — universal symptom → tool pipeline table and anti-patterns
• .claude/rules/copilot.md — VS Code Copilot-specific quick reference and session-start checklist

These files are automatically picked up by Claude Code, Copilot's custom instructions system, and Serena's hook integration layer.

[!NOTE] The published npm package does not include .claude/rules/. If you install from npm and want these routing rules, copy them from the GitHub repository into your workspace.

---

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines, code standards, and the skill/instruction development workflow.

---

License

MIT © 2025 Anselmoo