agentic-advisor 0.7.1

A proactive AI coding advisor MCP server — orchestration layer for agentic development workflows

agentic-advisor

A proactive AI coding advisor MCP server — the orchestration layer that sits alongside any AI coding tool and provides guardrails, best practices, routing, and workflow automation.

27 tools · 4 prompts · 9 resources · 12 proactive modules · v0.7.1

---

What It Does

Knowledge & Routing

Tool	Description
ask_advisor	RAG query over 30 knowledge base documents (semantic or TF-IDF)
route_task	Routes tasks to the best MCP: "Use [Snyk], call [snyk_test]"
get_session_briefing	Session health check with warnings and MCP recommendations

Setup & Planning

Tool	Description
assess_project	Auto-detect project type, language, framework, database
setup_project	Generate CLAUDE.md, AGENTS.md, Skills, and Workflows
create_spec	Scaffold requirements.md, design.md, tasks.md for spec-driven dev

Execution Loop

Tool	Description
whats_next	Next task from tasks.md with phase, progress %, and counts
mark_done	Check off a task (fuzzy match), closes the autonomous loop

Agentic Memory

Tool	Description
read_agentic_memory	Retrieve long-horizon context and architectural decisions from NOTES.md
write_agentic_memory	Persist key decisions and summaries to NOTES.md
summarize_memory	Compact NOTES.md — keeps N newest entries, summarizes older ones

Security

Tool	Description
scan_for_secrets	17 regex patterns + Shannon entropy detection
scan_diff	Diff review: secrets + 10 risky code patterns on added lines
validate_dependency	Heuristic + live PyPI/npm registry check for hallucinated packages
generate_hook_script	Install lifecycle hooks to .claude/hooks/ (allow-list, audit, tests)

Safety & Blast Radius

Tool	Description
record_loop_event	Report test failures for death-loop detection
record_semantic_event	Report agent reasoning and tool calls for semantic loop tracking
get_circuit_status	Check if circuit breaker has tripped
reset_circuit	Reset breaker after human intervention
revert_to_checkpoint	Hard-reset to last advisor git checkpoint

Human-in-the-Loop Approval

Tool	Description
request_approval	Submit high-stakes actions for human review (4 risk levels)
check_approval	Poll approval status — agents wait for human decision
list_pending_approvals	List all pending requests awaiting review
grant_approval	Human reviewer grants approval
deny_approval	Human reviewer denies approval

Analytics & Compliance

Tool	Description
get_session_analytics	Loop velocity, tool usage, knowledge gaps, estimated ROI
generate_aibom	AI Bill of Materials: Commit → Task → RAG Docs → Scan Results

MCP Resources (Zero-Cost State Access)

Resource URI	Description
advisor://briefing	Session briefing with project health and recommendations
advisor://routing-guide	Full routing guide for all 17 task categories
advisor://spec-templates	Spec-driven development templates reference
advisor://patterns-guide	Multi-agent patterns, context engineering, MCP security
advisor://memory	Current NOTES.md contents — no tool call overhead
advisor://circuit-status	Circuit breaker state (tripped/normal)
advisor://aibom	Last generated AIBOM compliance artifact
advisor://alerts	Proactive alerts from scanner and circuit breaker
advisor://pending-approvals	Pending human approval requests

Prompts (Multi-Tool Workflows)

Prompt	Description
start-session	Full bootstrap: briefing → circuit check → task loop
pre-commit	Security review: scan diff → validate deps → circuit check
plan-feature	Spec-driven: assess → spec → hooks → begin
debug-loop	Recovery: circuit → stop → DECISIONS.md → revert → ask human

---

Quick Start

1. Install

cd /path/to/agentic-advisor
pip install -e .

# Optional: enable semantic search (recommended)
pip install -e ".[semantic]"

2. Set your knowledge base path (optional)

export ADVISOR_KB_PATH="/path/to/your/knowledge-base"

Defaults to ~/Developer/notebooklm-agentic-coding/.

3. Register with Claude Code

Add to ~/.claude/mcp_servers.json:

{
  "mcpServers": {
    "agentic-advisor": {
      "command": "python",
      "args": ["-m", "agentic_advisor.server"],
      "cwd": "/path/to/agentic-advisor/src",
      "env": {
        "ADVISOR_KB_PATH": "/path/to/knowledge-base"
      }
    }
  }
}

4. Register with Antigravity

In Antigravity: Settings → MCP Servers → Add Custom Server with the same config above.

---

Architecture

agentic-advisor v0.7.1
  │
  ├── knowledge/       RAG: 30 docs, dual-backend (semantic + TF-IDF)
  │     ├── loader.py         Structure-aware chunking, all-MiniLM-L6-v2
  │     ├── retriever.py      Search + format with backend annotation
  │     └── vector_store.py   VectorStoreAdapter ABC (swap backends easily)
  │
  ├── routing/         3-tier task classification (17 categories)
  │     └── router.py         Keywords → embeddings → token-overlap → default
  │
  ├── setup/           Project detection + config generation
  │     └── generator.py      assess, setup, create_spec, whats_next, mark_done
  │
  ├── proactive/       12 modules
  │     ├── scanner.py         Secrets (regex + entropy) + risky patterns
  │     ├── hooks.py           4 lifecycle hooks (allow-list, audit, tests, bootstrap)
  │     ├── briefing.py        Session health checks (warns on NOTES.md bloat)
  │     ├── circuit_breaker.py Death loop detection (3-strike + semantic loops)
  │     ├── checkpointing.py   Git snapshots + revert
  │     ├── telemetry.py       SQLite analytics (.claude/telemetry.db)
  │     ├── aibom.py           AI Bill of Materials compliance artifact
  │     ├── memory.py          NOTES.md read/write for agentic memory
  │     ├── multiplexer.py     Phase-based tool gating (6 workflow phases)
  │     ├── notifications.py   Proactive alert queue (auto-fires on scan/trip)
  │     ├── approval.py        Human-in-the-loop approval gate (4 risk levels)
  │     └── summarizer.py      NOTES.md compaction (keeps newest, summarizes rest)
  │
  ├── errors.py        Structured error recovery (8 classifiers + LLM hints)
  │
  └── evals/           Evaluation framework (55 cases)
        ├── test_router_evals.py    20 routing accuracy cases
        ├── test_scanner_evals.py   25 scanner detection cases
        ├── test_retriever_evals.py 10 retrieval quality cases
        └── eval_runner.py          CLI quality report

---

Agent Workflows

Three canonical workflows in .agent/workflows/:

• advisor-session — Full session lifecycle: briefing → task loop → analytics
• advisor-setup — New project onboarding: assess → config → spec → hooks
• advisor-security — Pre-commit: scan diff → validate deps → circuit check

---

Environment Variables

Variable	Default	Description
ADVISOR_KB_PATH	~/Developer/notebooklm-agentic-coding	Knowledge base directory
ADVISOR_EMBED_MODEL	all-MiniLM-L6-v2	Sentence-transformer model name
ADVISOR_PROJECT_DIR	.	Project dir for the briefing resource
ADVISOR_AUTO_APPROVE_LEVEL	low	Risk threshold for auto-approval (low/medium/high/critical)

---

Running Tests

pip install -e ".[dev]"

# Unit tests (54 tests)
pytest tests/ -v

# Evaluation suite (55 cases)
pytest evals/ -v

# Full suite
pytest tests/ evals/ -v

# Eval quality report
python evals/eval_runner.py

---

License

MIT — contributions welcome.