Metadata-Version: 2.4
Name: agentic-advisor
Version: 0.7.1
Summary: A proactive AI coding advisor MCP server — orchestration layer for agentic development workflows
License: MIT
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: semantic
Requires-Dist: numpy>=1.26; extra == 'semantic'
Requires-Dist: sentence-transformers>=2.7; extra == 'semantic'
Description-Content-Type: text/markdown

# 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

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

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

### 2. Set your knowledge base path (optional)

```bash
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`:

```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

```bash
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.
