mod-bot 1.0.0 → 1.1.0

package/README.md

@@ -1,103 +1,280 @@
-# mod-bot
+<p align="center">
+  <img src="assets/mascot.png" alt="mod-bot mascot" width="200" />
+</p>
 
-An adaptive code moderation MCP server that learns your preferences, understands your codebase, and tailors guidance to your experience level.
+<h1 align="center">mod-bot</h1>
 
-## What is mod-bot?
+<p align="center">
+  <strong>An adaptive code moderation MCP server that learns your style.</strong>
+</p>
 
-Mod-bot is a **code moderator** — not just another orchestrator or skill system. It sits between you and your codebase like a senior tech lead who:
+<p align="center">
+  <a href="https://www.npmjs.com/package/mod-bot"><img src="https://img.shields.io/npm/v/mod-bot.svg" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/mod-bot"><img src="https://img.shields.io/npm/dm/mod-bot.svg" alt="npm downloads" /></a>
+  <a href="https://github.com/MiguelSeglias/mod-bot/actions/workflows/ci.yml"><img src="https://github.com/MiguelSeglias/mod-bot/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://github.com/MiguelSeglias/mod-bot/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/mod-bot.svg" alt="license" /></a>
+  <a href="https://github.com/MiguelSeglias/mod-bot"><img src="https://img.shields.io/github/stars/MiguelSeglias/mod-bot.svg?style=social" alt="GitHub stars" /></a>
+</p>
 
-- Knows your codebase inside out and keeps that knowledge current
-- Knows your skill level and adjusts guidance accordingly
-- Learns your patterns and preferences over time
-- Manages context so nothing falls through the cracks
-- Deploys multi-agent swarms only when genuinely needed
+<p align="center">
+  <a href="#install">Install</a> &bull;
+  <a href="#what-it-does">What it does</a> &bull;
+  <a href="#tools">Tools</a> &bull;
+  <a href="#adaptive-output">Adaptive output</a> &bull;
+  <a href="#how-it-works">How it works</a> &bull;
+  <a href="#contributing">Contributing</a>
+</p>
 
-## Quick Start
+---
+
+## Why mod-bot?
+
+Most AI coding tools treat every developer the same. A junior writing their first API gets the same terse response as a staff engineer. Mod-bot fixes that.
 
-### Add to Claude Code
+It's a **[Model Context Protocol](https://modelcontextprotocol.io/)** server for **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** that acts as your personal senior tech lead — one who knows your codebase, remembers your preferences, and adjusts their communication style to match your experience level.
+
+## Install
 
 ```bash
 claude mcp add --scope user mod-bot -- npx -y mod-bot@latest
 ```
 
-### Initialize in your project
+That's it. Restart Claude Code and you're ready to go.
+
+## What it does
+
+**Adapts to you.** Tell mod-bot your experience level and it adjusts everything — a junior gets step-by-step walkthroughs with explanations, a senior gets terse one-liners. Working in a language you're learning? It automatically provides more detail.
+
+**Learns your patterns.** Use early returns consistently? Prefer functional style? Skip reviews on small changes? Mod-bot notices and adapts. After enough sessions, it suggests workflow adjustments based on what it's learned.
+
+**Knows your project.** On first run, mod-bot scans your codebase — languages, frameworks, test setup, CI/CD, project maturity. It keeps a living knowledge graph that updates as your project evolves.
+
+**Manages context.** It tracks your current branch, task, decisions, and open questions across sessions. Pick up exactly where you left off.
+
+**Respects your tokens.** Unlike tools that eagerly spawn agent swarms, mod-bot estimates cost first and asks before spending. Default budget is conservative.
+
+## Quick Start
+
+### 1. Initialize in your project
 
 ```
-init:setup --experienceLevel senior --name "Your Name"
+> init_setup --name "Alex" --experienceLevel senior
 ```
 
-This scans your codebase, detects your tech stack, and creates a `.mod-bot/` config directory.
+Mod-bot scans your project and creates a `.mod-bot/` config directory with your preferences.
+
+### 2. Get suggestions
+
+```
+> mod_suggest --task "Add rate limiting to the API"
+```
+
+### 3. Review before committing
+
+```
+> mod_review --changes "$(git diff --staged)"
+```
+
+### 4. Teach it your preferences
+
+```
+> learn_pattern --id "early-returns" --type code_style --description "Always use early returns over nested if/else"
+```
 
 ## Tools
 
-### Init (3 tools)
-| Tool | Description |
+### Init
+| Tool | What it does |
 |------|-------------|
-| `init:setup` | Initialize mod-bot: scan project, set preferences, get recommendations |
-| `init:reconfig` | Update your preferences without re-scanning |
-| `init:migrate` | Migrate config to latest version |
+| `init_setup` | Scan project, set your preferences, get tailored recommendations |
+| `init_reconfig` | Update preferences without re-scanning |
+| `init_migrate` | Migrate config when mod-bot updates |
 
-### Moderation (5 tools)
-| Tool | Description |
+### Moderation
+| Tool | What it does |
 |------|-------------|
-| `mod:suggest` | Get approach suggestions adapted to your level |
-| `mod:review` | Review changes before committing |
-| `mod:plan` | Create an implementation plan |
-| `mod:checkpoint` | Save progress, decisions, and open questions |
-| `mod:retro` | Run a brief retrospective |
-
-### Context (4 tools)
-| Tool | Description |
+| `mod_suggest` | Suggest an approach for a task, adapted to your level |
+| `mod_review` | Review staged changes — catches issues calibrated to your skill |
+| `mod_plan` | Create an implementation plan with appropriate detail |
+| `mod_checkpoint` | Snapshot progress, decisions made, and open questions |
+| `mod_retro` | Quick retrospective after completing a task |
+
+### Context
+| Tool | What it does |
 |------|-------------|
-| `ctx:status` | Show current project state (branch, task, health) |
-| `ctx:refresh` | Force full context refresh |
-| `ctx:focus` | Set current focus area |
-| `ctx:history` | Show session history and decision log |
+| `ctx_status` | Current state: branch, task, health metrics, recent commits |
+| `ctx_refresh` | Force a full codebase re-scan |
+| `ctx_focus` | Set a focus area (e.g., "auth module") for prioritized context |
+| `ctx_history` | Session history and decision log |
 
-### Learning (4 tools)
-| Tool | Description |
+### Learning
+| Tool | What it does |
 |------|-------------|
-| `learn:pattern` | Teach mod-bot a pattern or preference |
-| `learn:show` | Show what mod-bot has learned |
-| `learn:reset` | Reset specific or all patterns |
-| `learn:suggest-workflow` | Get workflow adjustment suggestions |
+| `learn_pattern` | Teach a coding pattern or preference |
+| `learn_show` | See everything mod-bot has learned about you |
+| `learn_reset` | Remove specific patterns or reset all |
+| `learn_suggest-workflow` | Get workflow adjustment suggestions based on your habits |
 
-### Swarm (3 tools)
-| Tool | Description |
+### Swarm
+| Tool | What it does |
 |------|-------------|
-| `swarm:estimate` | Estimate token cost before spawning |
-| `swarm:analyze` | Spawn a focused analysis swarm |
-| `swarm:refactor` | Coordinate multi-file refactoring |
+| `swarm_estimate` | Estimate token cost before spawning agents |
+| `swarm_analyze` | Spawn a focused analysis swarm (code + tests + architecture) |
+| `swarm_refactor` | Coordinate multi-file refactoring with one agent per concern |
 
 ## Adaptive Output
 
-Mod-bot adapts its output based on your experience level:
+The same tool produces different output depending on who's using it:
 
-| Scenario | Junior | Senior |
-|----------|--------|--------|
-| New endpoint | Full step-by-step with code snippets | "Add POST /users in routes/users.ts, follow posts.ts pattern" |
-| Bug in auth | "Let's debug together. First, check the error..." | "Race condition in token refresh. Check auth/refresh.ts:47" |
-| PR review | Explains each issue with "why" and docs links | "L23: null check. L45: extract helper. L67: add test." |
+<table>
+<tr><th>Scenario</th><th>Junior</th><th>Senior</th></tr>
+<tr>
+<td><strong>New endpoint</strong></td>
+<td>
 
-## Development
+Step-by-step walkthrough:
+1. Create route file
+2. Add handler with validation
+3. Write tests first
+4. Register the route
+5. Test manually
+
+Each step includes code snippets and explanations of *why*.
+
+</td>
+<td>
+
+`Add POST /users in routes/users.ts, follow the pattern from routes/posts.ts. Don't forget validation middleware.`
+
+</td>
+</tr>
+<tr>
+<td><strong>Bug in auth</strong></td>
+<td>
+
+"Let's debug this together. First, let's look at the error message and trace it back to the source..."
+
+</td>
+<td>
+
+"Race condition in token refresh. Check `auth/refresh.ts:47` — the mutex doesn't cover the full critical section."
+
+</td>
+</tr>
+<tr>
+<td><strong>Code review</strong></td>
+<td>
+
+Explains each issue with *why it matters*, links to relevant docs, and suggests how to fix it.
+
+</td>
+<td>
+
+`L23: null check missing. L45: extract to helper. L67: add test.`
+
+</td>
+</tr>
+</table>
+
+Working in a language you're learning? Mod-bot automatically downshifts one level — a senior learning Rust gets mid-level guidance for Rust code.
+
+## How it works
 
-```bash
-pnpm install          # Install dependencies
-pnpm build            # Build all packages
-pnpm test             # Run tests (67 tests)
+```
+Input (task/question)
+  -> User Profile Lookup (experience level, preferences)
+  -> Project State Lookup (branch, focus area, recent changes)
+  -> Complexity Assessment (trivial -> epic, scored 0-100)
+  -> Strategy Selection (junior / mid / senior)
+  -> Response Generation (adapted to user)
+  -> Pattern Recording (update learning memory)
+  -> Output
 ```
 
-## Architecture
+### Architecture
 
 ```
 packages/
-  core/         -- Types, config, moderator engine, workflow engine
-  server/       -- MCP server, 17 tool definitions
-  memory/       -- File-based persistent storage
-  analyzer/     -- Codebase scanner, complexity estimator
-  strategies/   -- Adaptive output (junior/mid/senior)
+  core/         Types, config (YAML + Zod), moderator engine, workflow engine
+  server/       MCP server entry point, 17 tool definitions
+  memory/       File-based persistent storage (project, user, session)
+  analyzer/     Codebase scanner, tech detector, complexity estimator
+  strategies/   Adaptive output formatting (junior, mid, senior)
+```
+
+### What gets stored
+
+All data lives in `.mod-bot/` at your project root (add to `.gitignore`):
+
+```
+.mod-bot/
+  config.yaml           # Your preferences
+  state.json            # Current project state
+  memory/
+    project.json        # Codebase knowledge
+    user.json           # Learned patterns
+    sessions.json       # Session history
+```
+
+No databases. No external services. Everything is local JSON and YAML.
+
+## Configuration
+
+After `init_setup`, your `.mod-bot/config.yaml` looks like:
+
+```yaml
+version: "1.0.0"
+user:
+  name: Alex
+  experienceLevel: senior        # junior | mid | senior | lead
+  primaryLanguages:
+    - TypeScript
+    - Python
+  learningLanguages:
+    - Rust                       # Gets extra guidance here
+  visualPreference: minimal      # minimal | moderate | verbose
+  explanationDepth: terse        # terse | standard | detailed
+  workflowPreference: autonomous # guided | autonomous | adaptive
+
+project:
+  status: brownfield             # greenfield | brownfield | fork
+  type: team                     # personal | team | enterprise
+  priorities:
+    - quality
+    - speed
+
+moderation:
+  autoSuggest: true
+  learnPatterns: true
+  swarmBudget: conservative      # conservative | moderate | unlimited
+  tddEnforcement: suggest        # off | suggest | enforce
+  reviewBeforeCommit: true
+```
+
+Edit it directly or use `init_reconfig` to update specific fields.
+
+## Contributing
+
+```bash
+git clone https://github.com/MiguelSeglias/mod-bot.git
+cd mod-bot
+pnpm install
+pnpm build
+pnpm test          # 67 tests across 4 packages
+```
+
+### Project structure
+
+This is a pnpm monorepo. The `tsup` bundler produces a single `dist/index.js` for npm distribution.
+
+```bash
+pnpm build         # Build all packages (tsc)
+pnpm build:dist    # Bundle for distribution (tsup)
+pnpm test          # Run all tests (vitest)
 ```
 
+PRs welcome. Please include tests for new tools.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mod-bot",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "Adaptive code moderation MCP server that learns your preferences and tailors guidance to your experience level",
   "author": "Miguel Seglias",