agentic-advisor 0.7.1__tar.gz

agentic_advisor-0.7.1/.agent/workflows/advisor-security.md

@@ -0,0 +1,51 @@
+---
+description: Pre-commit security review — scan diffs, validate deps, check circuit breaker
+---
+
+# Advisor Security Workflow
+
+Run this workflow before every commit to catch secrets, risky patterns, and hallucinated packages.
+
+## Steps
+
+### 1. Scan the Diff
+// turbo
+Run `scan_diff(diff_text)` with the output of `git diff --cached`.
+
+The scanner checks:
+- **17 regex patterns** — Anthropic, OpenAI, AWS, Google, GitHub, Stripe, Twilio, Slack keys
+- **Shannon entropy** — High-randomness strings (>4.5 bits/char) in hex/base64 charset
+- **10 risky patterns** — `eval()`, `exec()`, `shell=True`, SQL injection, `pickle.loads()`, disabled SSL
+
+If `is_clean` is `false`, fix the findings before committing.
+
+### 2. Validate Dependencies
+For each new dependency added in this commit, run:
+```
+validate_dependency(package_name)
+```
+
+Verdicts:
+- `confirmed_real` — Exists on PyPI or npm (live verified)
+- `likely_real` — Matches known-real prefix list
+- `suspicious` — Heuristic flags (long name, AI SDK combo, gibberish)
+- `not_found` — **Does NOT exist on any registry. Do NOT install.**
+
+### 3. Check Circuit Breaker
+// turbo
+Call `get_circuit_status()` to verify you haven't been stuck in a death loop.
+
+If `tripped` is `true`:
+1. Do NOT commit
+2. Write a summary of the failure to `DECISIONS.md`
+3. Call `reset_circuit()` only after the human has reviewed and provided guidance
+
+### 4. Commit
+If all checks pass, proceed with the commit. The `post_tool_use` hook will automatically log this action to `.claude/audit.log`.
+
+### 5. Revert if Needed
+If the commit breaks something critical, call:
+```
+revert_to_checkpoint(directory)
+```
+This hard-resets to the last advisor checkpoint commit.

agentic_advisor-0.7.1/.agent/workflows/advisor-session.md

@@ -0,0 +1,59 @@
+---
+description: Full agentic-advisor session lifecycle — from briefing to ROI dashboard
+---
+
+# Advisor Session Workflow
+
+The canonical execution loop for any AI coding session using the agentic-advisor MCP.
+
+## Steps
+
+### 1. Session Briefing
+// turbo
+Call `get_session_briefing()` to check project health, verify MCP connections, and get session tips.
+
+### 2. Check Circuit Breaker
+// turbo
+Call `get_circuit_status()` to verify you are not in a tripped state from a previous session.
+
+### 3. Get Next Task
+// turbo
+Call `whats_next()` to read the next unchecked task from `tasks.md`. This returns:
+- `next_task` — the task description
+- `phase` — which phase of the plan you're in
+- `progress_pct` — completion percentage
+- `completed` / `total` — task counts
+
+If `status` is `"all_done"`, skip to step 7.
+
+### 4. Implement the Task
+Use your native IDE tools (file edits, terminal, browser) to implement the task described in step 3. Follow the `requirements.md` and `design.md` specs.
+
+If a test fails after modifying a file, call:
+```
+record_loop_event(file_path, test_command, error_output)
+```
+Check the response — if `tripped` is `true`, STOP immediately and write a failure summary to `DECISIONS.md`.
+
+### 5. Pre-Commit Security Review
+Before committing, run:
+```
+scan_diff(git diff --cached)
+```
+If any secrets or HIGH-severity patterns are found, fix them before proceeding.
+
+For any new dependencies, validate them:
+```
+validate_dependency(package_name)
+```
+
+### 6. Mark Task Complete
+Call `mark_done()` to check off the task in `tasks.md`. Then loop back to step 3.
+
+### 7. Session Analytics
+// turbo
+At session end, call `get_session_analytics()` to review:
+- Loop velocity (time per task)
+- Circuit breaker trips
+- Knowledge gaps (low-score RAG queries)
+- Estimated hours saved

agentic_advisor-0.7.1/.agent/workflows/advisor-setup.md

@@ -0,0 +1,18 @@
+---
+description: Set up an optimal agentic coding environment for the current project
+---
+
+# Setup Agentic Environment
+
+1. Call the `assess_project` tool on the agentic-advisor MCP with the current directory
+2. Review the recommended configuration (MCP stack, CLAUDE.md / AGENTS.md)
+3. Call `setup_project` to write the configuration files (CLAUDE.md, AGENTS.md, Skills, Workflows)
+4. Install the recommended MCP servers from the install commands provided
+// turbo
+5. Run `git add CLAUDE.md AGENTS.md .skills/ .agent/` and commit "chore: add agentic advisor config"
+
+## Optional: Spec-Driven Setup for New Features
+After setup, if starting a new feature:
+6. Call `create_spec(feature_name)` to generate requirements.md, design.md, tasks.md
+7. Review and fill in the spec files before asking an agent to implement
+8. Run `git add requirements.md design.md tasks.md` and commit "docs: add spec for {feature}"

agentic_advisor-0.7.1/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+*.egg
+.venv/
+venv/
+.env
+*.db
+*.sqlite3
+.chroma/

agentic_advisor-0.7.1/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "agentic-advisor": {
+      "command": "/Users/kenthall/Developer/agentic-advisor/.venv/bin/python",
+      "args": ["-m", "agentic_advisor.server"],
+      "cwd": "/Users/kenthall/Developer/agentic-advisor/src"
+    }
+  }
+}

agentic_advisor-0.7.1/.skills/agentic-advisor.md

@@ -0,0 +1,46 @@
+---
+name: agentic-advisor
+description: >
+  Consult the agentic-advisor MCP to get routing recommendations, best-practice guidance,
+  spec-driven development support, and project setup help. Use this when you need to know
+  which tool to use, how to structure a workflow, want a session briefing, or need to
+  generate spec files before starting implementation.
+---
+
+# Agentic Advisor Skill
+
+When this skill is active, consult the agentic-advisor MCP server at key decision points:
+
+## At Session Start
+1. Read the `advisor://briefing` resource for a project health summary
+2. Or call `get_session_briefing()` with the current project directory to receive:
+   - Project type and recommended MCP stack
+   - Missing configuration warnings
+   - Recommended approach for today's work
+
+## Before Starting a New Feature
+Call `create_spec(feature_name)` to generate:
+- `requirements.md` — what to build (user stories, acceptance criteria)
+- `design.md` — how to build it (architecture, key decisions)
+- `tasks.md` — ordered implementation checklist
+
+## When Choosing a Tool
+Call `route_task` with a description of what you need to do.
+The advisor will tell you exactly which MCP and tool to use, including new categories:
+- Memory/persistence → mcp-memory-service
+- Multi-agent coordination → Agent-MCP / git worktrees
+- Task tracking → linear-mcp
+- Code health → codescene-mcp
+
+## When Unsure About Best Practice
+Call `ask_advisor` with your question to get knowledge-base-grounded guidance.
+
+## Trigger Phrases
+This skill activates when the user says:
+- "set up this project"
+- "what's the best way to..."
+- "which MCP should I use"
+- "ask the advisor"
+- "get a session briefing"
+- "create a spec for..."
+- "generate requirements for..."

agentic_advisor-0.7.1/AGENTS.md

@@ -0,0 +1,58 @@
+# AGENTS.md — python
+
+This file configures AI agents (Antigravity, OpenAI Codex, GitHub Copilot agent mode) for this project.
+It is the authoritative contract between humans and agents — read it before every task.
+
+## Role & Goal
+You are an expert python + python developer. Your goal is to implement the requested task
+with correctness, security, and minimal scope. Implement what is asked; do not add unrequested features.
+
+## Capabilities
+- Read, write, and refactor python code
+- Run `pytest` to validate changes
+- Use the MCP servers listed below to perform specialist tasks
+- Generate and follow spec files (`requirements.md`, `design.md`, `tasks.md`)
+
+## Active MCPs
+  - context7
+
+For task routing decisions, call `route_task()` on `agentic-advisor` MCP.
+For best-practice questions, call `ask_advisor()` on `agentic-advisor` MCP.
+
+## Spec-Driven Workflow
+If `requirements.md` and `tasks.md` exist in the project root:
+1. Read them before writing any code
+2. Work through `tasks.md` items in order, checking off each when complete
+3. Do not deviate from the spec without surfacing the conflict to the user
+
+## Boundaries
+- Only modify files in the directories specified in each task
+- Do not install new packages without asking first
+- Do not run destructive shell commands (`rm -rf`, `DROP TABLE`, etc.) without explicit confirmation
+- Do not commit or push to `main`/`master` directly — create a branch and open a PR
+- Do not modify CI/CD configs, deployment manifests, or `.env` files without explicit instruction
+
+## Human-in-the-Loop
+Surface to the user and wait for confirmation before:
+- Deleting or renaming files
+- Making schema migrations
+- Changing authentication or authorization logic
+- Adding new external dependencies
+
+## Security
+- Never write hardcoded secrets, tokens, or passwords — not even as `TODO` placeholders
+- All user input must be validated and sanitized before use
+- Use environment variables for all configuration values
+- When installing packages, verify the exact name on the registry (typosquat prevention)
+
+## Output Format
+After completing a task:
+1. List files changed and the nature of each change
+2. Confirm tests pass: `pytest`
+3. Summarize what behavior changed and why
+
+## Code Style
+- Language: python
+- Tests required for all new functions
+- Comments in English only
+- Keep commits atomic: one logical change per commit

agentic_advisor-0.7.1/CHANGELOG.md

@@ -0,0 +1,195 @@
+# Changelog — agentic-advisor
+
+All notable changes to this project will be documented here.
+Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+---
+
+## [0.7.1] — 2026-02-26
+
+### Added
+
+- **`summarize_memory(directory, max_entries)`** — Compacts NOTES.md by summarizing older entries into a single section. Keeps the N newest entries verbatim (default: 10).
+- **`knowledge/vector_store.py`** — Formal `VectorStoreAdapter` ABC for knowledge base backends. Makes adding ChromaDB, FAISS, or Pinecone trivial by inheriting from the interface.
+- **`errors.py`** — Structured error recovery with 8 error type classifiers (`file_not_found`, `network_error`, `permission_denied`, `parse_error`, `validation_error`, `dependency_missing`, `data_structure_error`, `path_type_error`). Returns actionable recovery hints to help LLMs self-correct.
+
+### Improved
+
+- **All 13 tool error handlers** now return structured `advisor_error()` responses instead of bare `{"error": str(e)}`.
+- **Session briefing** warns when NOTES.md exceeds 50 entries, suggesting `summarize_memory()`.
+- `SemanticKnowledgeBase` and `TFIDFKnowledgeBase` now document their adherence to the `VectorStoreAdapter` interface.
+
+### Infrastructure
+
+- Version bumped to `0.7.1`. Total: **27 tools, 4 prompts, 9 resources**.
+- Unit tests expanded with `TestSummarizer`, `TestVectorStoreAdapter`, and `TestErrorRecovery` (13 new tests).
+
+---
+
+### Added — 5 new tools
+
+- **`request_approval(action, risk_level, details)`** — Submit high-stakes actions for human approval. Risk levels: `low` (auto-approve), `medium`, `high` (blocks), `critical` (blocks + notification).
+- **`check_approval(approval_id)`** — Check the status of a pending approval request.
+- **`list_pending_approvals()`** — List all pending approval requests awaiting human review.
+- **`grant_approval(approval_id, note)`** — Grant approval for a pending request (human-facing).
+- **`deny_approval(approval_id, note)`** — Deny a pending approval request (human-facing).
+
+### Added — 5 new MCP Resources
+
+- **`advisor://memory`** — Current NOTES.md contents served as a resource (avoids tool call overhead).
+- **`advisor://circuit-status`** — Circuit breaker state as a readable resource.
+- **`advisor://aibom`** — Last generated AIBOM compliance artifact.
+- **`advisor://alerts`** — Proactive alerts from scanner and circuit breaker (poll-based notifications).
+- **`advisor://pending-approvals`** — Pending human approval requests.
+
+### Added — 2 new modules
+
+- `proactive/notifications.py` — Notification queue + manager for proactive alerts. Integrated into circuit_breaker and scanner for auto-queuing.
+- `proactive/approval.py` — Human-in-the-loop approval gate with risk-based auto-approve logic.
+
+### Added — Evaluation Framework
+
+- `evals/` directory with 45+ evaluation cases:
+  - `test_router_evals.py` — 20+ routing accuracy cases across 8 task categories
+  - `test_scanner_evals.py` — 15+ scanner detection cases (secrets, entropy, diffs, dependencies)
+  - `test_retriever_evals.py` — 10+ retrieval quality and relevance cases
+  - `eval_runner.py` — CLI tool for running all evals with quality report
+
+### Improved
+
+- **Circuit Breaker** — Now auto-queues notifications on both test-failure and semantic loop trips.
+- **Scanner** — Now auto-queues critical alerts when secrets are detected.
+- Unit tests expanded with `TestNotifications` and `TestApprovalGate` classes (12 new tests).
+
+### Infrastructure
+
+- Version bumped to `0.7.0`. Total: **26 tools, 4 prompts, 9 resources**.
+- `pyproject.toml` updated: evals added to testpaths.
+
+---
+
+## [0.6.0] — 2026-02-26
+
+### Added — 3 new tools & Protocols
+
+- **A2A Protocol Support** — `agent-card.json` generation and Orchestrator role scaffolding for multi-agent workflows.
+- **`read_agentic_memory()`** and **`write_agentic_memory(topic, content)`** — Persistent `NOTES.md` storage to manage long-horizon context.
+- **`record_semantic_event(reasoning, tool_calls)`** — New semantic layer for the circuit breaker tracking repeating thoughts/actions. Trips after 4 identical cycles into a `DEGRADED` state.
+
+### Improved
+
+- **Architecture Enforcement** — Integrated SOLID/Clean Architecture scanning directly into `scan_diff` (detects Arrow Anti-patterns, SRP violations).
+- Prompts updated to incorporate Agentic Memory checks and semantic decision logging.
+
+---
+
+## [0.5.0] — 2026-02-24
+
+### Added — 6 new tools
+
+- **`record_loop_event(file, command, error)`** — Circuit breaker telemetry. Tracks (file, error) pairs. Trips after 3 identical failures.
+- **`get_circuit_status()`** — Check if the death-loop breaker has tripped.
+- **`reset_circuit()`** — Clear the breaker after human intervention.
+- **`revert_to_checkpoint(directory)`** — Hard-reset to last advisor git checkpoint.
+- **`get_session_analytics()`** — Session ROI: loop velocity, tool usage, knowledge gaps, hours saved.
+- **`generate_aibom(directory)`** — AI Bill of Materials compliance artifact (Commit → Task → Scans).
+
+### Added — 4 MCP Prompts
+
+- **`start-session`** — Full bootstrap: briefing → circuit check → task loop → analytics.
+- **`pre-commit`** — Security: scan_diff → validate_dependency → circuit check.
+- **`plan-feature`** — Spec-driven: assess → create_spec → hooks → whats_next.
+- **`debug-loop`** — Recovery: circuit → stop → DECISIONS.md → revert → ask human.
+
+### Added — 3 Agent Workflows + 4 New Modules
+
+- `.agent/workflows/advisor-session.md`, `advisor-setup.md`, `advisor-security.md`
+- `proactive/circuit_breaker.py` — Death loop detection (3-strike, 5-min window)
+- `proactive/checkpointing.py` — Git snapshots + revert
+- `proactive/telemetry.py` — SQLite analytics at `.claude/telemetry.db`
+- `proactive/aibom.py` — AIBOM with traceability matrix
+
+### Improved
+
+- **`scan_for_secrets`** — Two-pass: 17 regex + Shannon entropy (4.5 bit threshold).
+- **`pre_tool_use` hook** — Allow-list model: shlex parsing, 45+ safe binaries, directory sandboxing.
+- **Routing** — Tier 2 now uses sentence-transformer embeddings (reuses MiniLM model).
+- **Chunking** — Structure-aware: splits on headers, never breaks code blocks.
+- **`retriever.py`** — Annotates results with active backend info.
+
+### Infrastructure
+
+- Version bumped to `0.5.0`. Total: **18 tools, 4 prompts, 4 resources**.
+- `pyproject.toml` has `[semantic]` extras group (`sentence-transformers`, `numpy`).
+
+---
+
+## [0.3.0] — 2026-02-24
+
+### Added — 5 new tools
+
+- **`whats_next(directory)`** — Returns the next unchecked task from `tasks.md` as a
+  structured dict with `phase`, `completed`, `total`, and `progress_pct`. Previously
+  returned a bare string.
+
+- **`mark_done(task_text, directory)`** — Marks the first matching unchecked task in
+  `tasks.md` as complete (`[x]`). Accepts partial, case-insensitive text match.
+  Closes the spec-driven execution loop: `whats_next → implement → mark_done → repeat`.
+
+- **`scan_for_secrets(text)`** — Detects hardcoded secrets in any text using 17 regex
+  patterns covering Anthropic, OpenAI, AWS, Google, GitHub, Stripe, Twilio, Slack,
+  RSA private keys, generic assignments, and Bearer tokens.
+
+- **`scan_diff(diff_text)`** — Full git diff review scanning only added lines (`+`) for
+  secrets (17 patterns) and risky code patterns: `eval()`, `exec()`, `shell=True`,
+  SQL injection via string formatting, `pickle.loads()`, disabled SSL, and more.
+
+- **`generate_hook_script(hook_type, directory, dry_run)`** — Writes production-ready
+  Claude Code lifecycle hook scripts to `.claude/hooks/`. Supports:
+  - `pre_tool_use` — Blocks dangerous bash commands and secrets in file writes (exit 2)
+  - `post_tool_use` — Audit logging + auto-format Python files with ruff
+  - `stop` — Self-verification: runs pytest/npm test before agent can stop
+  - `session_start` — Injects tasks.md status and DECISIONS.md alerts at session start
+  - `all` — Installs all four hooks at once
+
+### Improved
+
+- **`validate_dependency`** now runs a **live PyPI + npm registry lookup** (2s timeout,
+  stdlib only, no new dependencies). Returns `confirmed_real` (live verified),
+  `not_found` (hallucinated package), or heuristic fallbacks when offline.
+
+- **`route_task` / `detect_task_type`** now has a **Tier 2 semantic fallback** using
+  cosine similarity against routing map descriptions. Queries like *"run tests in a
+  real browser"* now correctly route to `browser_testing` even without hitting keywords.
+  Routing decisions include a `reasoning` field describing which tier matched.
+
+### Infrastructure
+
+- Version bumped to `0.3.0` in `server.py` (FastMCP) and `pyproject.toml`.
+- Knowledge base expanded from 14 to 30 documents (docs 14-29 added).
+- All new docs optimized for TF-IDF section chunking with `##`/`###` headers.
+- `00-master-index.md` updated with full TOC, FAQ table, and cross-reference guide
+  covering all 30 documents.
+
+---
+
+## [0.2.0] — 2026-02-23
+
+### Added
+
+- Core MCP server with 6 tools: `ask_advisor`, `assess_project`, `setup_project`,
+  `create_spec`, `route_task`, `get_session_briefing`
+- TF-IDF knowledge base with 14 seed documents
+- 4 resources: `advisor://briefing`, `advisor://routing-guide`,
+  `advisor://spec-templates`, `advisor://patterns-guide`
+- Project detector, CLAUDE.md/AGENTS.md generator, spec file templates
+- Session briefing with project health checks and session tips
+- 17-category routing map with keyword classification
+
+---
+
+## [0.1.0] — 2026-02-22 (Initial Release)
+
+- Initial FastMCP server scaffold
+- Basic RAG over knowledge base using TF-IDF
+- `ask_advisor` tool with knowledge base retrieval

agentic_advisor-0.7.1/CLAUDE.md

@@ -0,0 +1,98 @@
+# CLAUDE.md — python
+
+This file configures Claude Code for this project. Read it at the start of every session.
+
+## Project Overview
+- **Type**: python + python
+- **Language**: python
+- **Test framework**: pytest
+- **Database**: unknown
+
+## Build & Run Commands
+<!-- Add your build, dev, test, and lint commands here -->
+
+## Active MCP Servers
+- context7
+> Tip: Use MCP lazy loading (`defer_loading: true` in .mcp.json) to reduce context overhead.
+> With 5+ MCP servers active, upfront tool definitions can consume 50K+ tokens before any work begins.
+
+## Core Rules
+
+## Security Rules (Always Active)
+- NEVER hardcode API keys, secrets, tokens, or passwords in any file
+- NEVER use `eval()`, `exec()`, or `Function()` with user-provided data
+- ALWAYS use parameterized queries — never interpolate user input into SQL strings
+- NEVER execute shell commands that include unvalidated user input
+- When adding a new npm/pip package, confirm the exact package name on the registry before installing
+- If you're unsure whether an action is safe, ask before proceeding
+
+## Context Management
+- Use `/clear` between major tasks to keep context focused
+- When the task list is complete, run a wrap-up: summarize what changed and commit
+- Always read existing code before modifying it — don't assume
+- If you've tried the same approach 3 times and it's failing, stop and ask for guidance
+- MCP tool definitions consume context — only connect MCPs you'll actually use in this session
+- Use `advisor://routing-guide` resource once per session instead of calling route_task() repeatedly
+
+## Spec-Driven Development
+Before writing any significant new feature or module:
+1. Create `requirements.md` — what the feature must do (user stories, acceptance criteria)
+2. Create `design.md` — how it will be built (architecture, key decisions, constraints)
+3. Create `tasks.md` — ordered checklist of implementation steps
+These files are the source of truth. The agent implements against them, not against vague prompts.
+Run: `route_task("create spec files")` → the advisor will generate these for you.
+
+## Persistent Memory
+- If `mcp-memory-service` or `mcp-knowledge-graph` is connected, store key architectural decisions
+  after each session: `store_memory("We chose X over Y because Z")`
+- Important decisions should also be appended to `DECISIONS.md` in the project root
+- At session start, search memories for relevant context: `search_memories("project architecture")`
+
+
+
+## Workflow
+
+### Starting a session
+1. Read `advisor://briefing` resource (or call `get_session_briefing()`) for project health
+2. If spec files exist (`requirements.md`, `design.md`, `tasks.md`), read them before touching code
+3. Search persistent memory for relevant context: `search_memories("this project")`
+
+### Starting a task
+1. Read the relevant source files before making changes
+2. State your plan in 3 bullet points before writing any code
+3. Check for existing utilities before adding new dependencies
+4. For significant new features, generate spec files first with `create_spec()`
+
+### During a task
+- Make small, atomic commits after each working increment
+- Run tests after every significant change: `pytest`
+- Never modify files outside the agreed scope without asking
+- Claude Code auto-saves checkpoints before each change — use `/rewind` to undo if needed
+
+### Ending a session
+1. Run the full test suite
+2. Summarize what changed (what files, what behavior)
+3. Commit with a descriptive message
+4. Store key decisions in memory: `store_memory("Decision: ...")`
+
+## Human-in-the-Loop Triggers
+Stop and ask the user before proceeding when:
+- About to delete files, drop database tables, or remove more than 10 lines from a critical module
+- Installing a new package not already in the project
+- Making changes to CI/CD pipelines, deployment configs, or environment variables
+- Unsure whether a destructive operation is reversible
+
+## Parallel Agents & Git Worktrees
+To run multiple agents simultaneously on independent tasks:
+```bash
+git worktree add ../feature-branch -b feature/your-feature-name
+```
+Each worktree is an isolated working copy — agents can't conflict.
+Use Agent-MCP or claude-flow to coordinate agents via shared context.
+After parallel work, merge back: `git merge --no-ff feature/your-feature-name`
+
+## Custom Slash Commands
+- `/review` — Review recent changes for security and correctness
+- `/route [task]` — Ask the agentic-advisor which MCP to use for a task
+- `/ask-advisor [question]` — Query the agentic coding knowledge base
+- `/spec [feature]` — Generate requirements.md + design.md + tasks.md for a new feature

agentic_advisor-0.7.1/DEEP_THINK_PROMPT.md

@@ -0,0 +1,109 @@
+# Deep Analysis Request — agentic-advisor MCP Server (v0.3.0)
+
+## Context
+
+I have built an MCP (Model Context Protocol) server called `agentic-advisor` — a proactive AI coding advisor that acts as an orchestration layer for agentic development workflows. It's built with FastMCP (Python) and is designed to be the "resident expert" that sits alongside any AI coding tool (Claude Code, Cursor, Copilot, Windsurf, etc.) and provides guardrails, best practices, and workflow automation.
+
+The server runs fully local via STDIO transport. No cloud calls except optional live PyPI/npm registry lookups (2s timeout, stdlib urllib only).
+
+---
+
+## Architecture Overview
+
+### Knowledge Layer (RAG)
+- **30 markdown documents** covering agentic coding best practices (foundations, tools, MCP ecosystem, security, workflows, multi-agent orchestration, failure modes, etc.)
+- **Dual-backend search engine** — auto-selects at import time:
+  - **Semantic**: `sentence-transformers/all-MiniLM-L6-v2` (25MB local model, cosine similarity on 384-dim embeddings)
+  - **TF-IDF fallback**: pure Python, zero dependencies, keyword matching with IDF weighting + section/doc-name bonuses
+- Documents are chunked into 300-word overlapping windows with section header metadata
+- Singleton pattern for the knowledge base instance
+
+### Routing Layer
+- **17-category task router** that maps natural language task descriptions to the best MCP/tool
+- **3-tier classification**: Tier 1 keyword matching (deterministic) → Tier 2 cosine similarity on routing descriptions (semantic fallback) → Tier 3 default to `knowledge_question`
+- Returns structured `RoutingDecision` with confidence level, reasoning, install commands, and doc references
+
+### Setup Engine
+- **Project detector**: scans directory for `package.json`, `pyproject.toml`, `Cargo.toml`, etc. to auto-detect project type, language, framework, and test runner
+- **Config generator**: writes `CLAUDE.md`, `AGENTS.md`, `.skills/`, `.agent/workflows/` based on detected project profile
+- **Spec-driven development**: `create_spec()` generates `requirements.md`, `design.md`, `tasks.md` scaffolds
+
+### Execution Loop (Spec-Driven)
+- `whats_next(directory)` → reads `tasks.md`, returns structured dict: `{next_task, phase, completed, total, progress_pct}`
+- `mark_done(task_text, directory)` → fuzzy-matches and checks off the first matching `[ ]` item in `tasks.md`
+- This closes the autonomous execution loop: `whats_next → implement → mark_done → whats_next → repeat`
+
+### Security Scanner
+- `scan_for_secrets(text)` — 17 regex patterns (Anthropic, OpenAI, AWS, Google, GitHub, Stripe, Twilio, Slack, RSA, generic assignments, Bearer tokens)
+- `scan_diff(diff_text)` — scans only added `+` lines for secrets + 10 risky code patterns (`eval`, `exec`, `shell=True`, SQL injection, `pickle.loads`, disabled SSL, etc.)
+- `validate_dependency(package)` — two-stage: offline heuristics (80+ known-real prefixes, 5 suspicion patterns) + live PyPI/npm 404 check (2s timeout). Verdicts: `confirmed_real`, `likely_real`, `suspicious`, `not_found`
+
+### Hook Generator
+- `generate_hook_script(hook_type)` — writes production-ready Python scripts to `.claude/hooks/`:
+  - `pre_tool_use`: blocks dangerous bash commands + secrets in file writes (exit code 2)
+  - `post_tool_use`: audit logging to `.claude/audit.log` + auto-format Python with ruff
+  - `stop`: runs `pytest` or `npm test` before agent can stop — blocks if tests fail
+  - `session_start`: injects `tasks.md` status + `DECISIONS.md` alerts at session start
+
+### Resources (4 static endpoints)
+- `advisor://briefing` — session health summary
+- `advisor://routing-guide` — full 17-category routing reference
+- `advisor://spec-templates` — spec-driven development template reference
+- `advisor://patterns-guide` — multi-agent patterns, context engineering, MCP security
+
+### Tool Count: 12
+`ask_advisor`, `assess_project`, `setup_project`, `create_spec`, `whats_next`, `mark_done`, `scan_for_secrets`, `scan_diff`, `validate_dependency`, `generate_hook_script`, `route_task`, `get_session_briefing`
+
+---
+
+## Deep Probing Questions
+
+### 1. Architectural Critique
+The server currently operates as a monolith — RAG, routing, security scanning, hook generation, and the spec execution loop are all in one FastMCP process. At what scale (number of tools, knowledge base size, concurrent agent sessions) does this architecture start to show cracks? Would you recommend decomposing into multiple coordinated MCP servers, and if so, what's the natural boundary for splitting? How would that affect the `instructions` prompt that introduces the server's capabilities to agents?
+
+### 2. RAG Quality at Scale
+We have 30 documents (~200 chunks at 300 words each). The semantic backend uses `all-MiniLM-L6-v2` with a flat cosine similarity search (no index, just `np.dot`). At what chunk count does this become a latency problem? Should we switch to FAISS, Annoy, or HNSW at some point? More importantly — is 300 words the right chunk size for code-heavy documents? Would a hybrid chunking strategy (e.g., section-level for prose, function-level for code examples) improve retrieval quality?
+
+### 3. Routing Robustness  
+The Tier 2 semantic fallback in `detect_task_type` uses a token-overlap cosine sim against ROUTING_MAP description strings (one sentence each). This is a very thin semantic surface. Would generating synthetic paraphrases for each routing category (e.g., 5-10 per category) and matching against those improve accuracy? Or would it be better to embed the routing descriptions using the same sentence-transformer model and do proper vector similarity?
+
+### 4. Security Scanner Completeness
+The secret scanner uses 17 regexes. Real-world secret scanners (TruffleHog, GitLeaks, Gitleaks) use 500+ patterns and entropy-based detection. Is our regex-only approach a false sense of security? Should we integrate entropy scoring for high-randomness strings? What about multi-line secrets (e.g., PEM keys split across lines, YAML blocks with base64-encoded secrets)?
+
+### 5. Spec-Driven Loop Integrity
+The `whats_next` / `mark_done` loop assumes `tasks.md` is the single source of truth. But what happens when:
+- Two agents are running in parallel via `git worktree` and both read the same `tasks.md`?
+- An agent marks a task done but the implementation is actually wrong (false completion)?
+- The user manually edits `tasks.md` mid-session, reordering or removing tasks?
+Should we add file locking, checksums, or a lightweight state machine to make this more robust?
+
+### 6. Hook Security Model
+The `pre_tool_use` hook uses string matching (`if pattern.lower() in command.lower()`) to block dangerous commands. An adversarial agent could trivially bypass this with encoding tricks (`echo cm0gLXJmIC8= | base64 -d | bash`), variable expansion, or multi-step command chaining. Is there a more robust approach? Should we parse the command AST instead, or is defense-in-depth (multiple weak layers > one strong layer) the right philosophy for agentic hooks?
+
+### 7. Token Economy
+Every tool call costs tokens. With 12 tools, the tool descriptions alone consume ~2,500 tokens of context window in every agent session. The `instructions` string adds another ~200. For a model with a 128k context window this is fine, but for 8k-context models it's significant. Should we implement lazy tool loading (only expose tools relevant to the detected project type)? Or is the cognitive overhead of a smaller tool surface worth the token savings?
+
+### 8. Knowledge Base Maintenance
+The 30 documents are static markdown files. AI coding best practices are evolving weekly in 2026 — new MCP servers ship, tool capabilities change, workflow patterns emerge. What's the best approach for keeping this knowledge base current? Should we add a `refresh_knowledge_base()` tool that fetches updates from a curated source? Or is manual curation the only way to maintain quality in a RAG system?
+
+### 9. Observability Gap
+We have `post_tool_use` audit logging and `scan_diff` for pre-commit checks, but we have no way to measure:
+- How often agents actually call `whats_next` vs. ignoring it
+- Which `ask_advisor` queries return low-relevance results (indicating knowledge gaps)
+- Whether `route_task` is sending agents to the wrong MCP
+What telemetry or feedback loops would you add to close this observability gap, while respecting the local-only, privacy-first design?
+
+---
+
+## Open-Ended: What Are We Missing?
+
+Given the full architecture above, what capabilities, failure modes, or architectural patterns are we NOT thinking about that would make this MCP server significantly more valuable? 
+
+Think about:
+- What would make this the default MCP that every agentic IDE ships with?
+- What would make an enterprise team adopt this over building their own?
+- What failure modes could cause a team to REMOVE this MCP from their stack?
+- Are there interaction patterns between the 12 tools that we should be encoding as higher-level workflows rather than leaving up to the agent to figure out?
+- What would a "v1.0" of this server need to have that v0.3.0 doesn't?
+
+Please be specific and opinionated. Give concrete recommendations, not generic advice.