mod-bot 1.0.0

package/README.md

@@ -0,0 +1,103 @@
+# mod-bot
+
+An adaptive code moderation MCP server that learns your preferences, understands your codebase, and tailors guidance to your experience level.
+
+## What is mod-bot?
+
+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:
+
+- 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
+
+## Quick Start
+
+### Add to Claude Code
+
+```bash
+claude mcp add --scope user mod-bot -- npx -y mod-bot@latest
+```
+
+### Initialize in your project
+
+```
+init:setup --experienceLevel senior --name "Your Name"
+```
+
+This scans your codebase, detects your tech stack, and creates a `.mod-bot/` config directory.
+
+## Tools
+
+### Init (3 tools)
+| Tool | Description |
+|------|-------------|
+| `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 |
+
+### Moderation (5 tools)
+| Tool | Description |
+|------|-------------|
+| `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 |
+|------|-------------|
+| `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 |
+
+### Learning (4 tools)
+| Tool | Description |
+|------|-------------|
+| `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 |
+
+### Swarm (3 tools)
+| Tool | Description |
+|------|-------------|
+| `swarm:estimate` | Estimate token cost before spawning |
+| `swarm:analyze` | Spawn a focused analysis swarm |
+| `swarm:refactor` | Coordinate multi-file refactoring |
+
+## Adaptive Output
+
+Mod-bot adapts its output based on your experience level:
+
+| 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." |
+
+## Development
+
+```bash
+pnpm install          # Install dependencies
+pnpm build            # Build all packages
+pnpm test             # Run tests (67 tests)
+```
+
+## 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)
+```
+
+## License
+
+MIT

package/agents/analyzer.yaml

@@ -0,0 +1,12 @@
+type: analyzer
+version: "1.0.0"
+description: Codebase analysis agent for scanning, complexity estimation, and tech detection
+capabilities:
+  - codebase-scanning
+  - tech-detection
+  - complexity-estimation
+  - change-tracking
+  - git-state-analysis
+behavior:
+  max_scan_depth: 8
+  sample_file_limit: 50

package/agents/learner.yaml

@@ -0,0 +1,12 @@
+type: learner
+version: "1.0.0"
+description: Pattern learning agent that detects and remembers user preferences
+capabilities:
+  - pattern-detection
+  - preference-tracking
+  - workflow-suggestion
+  - suppression-management
+behavior:
+  pattern_threshold: 3
+  suppression_threshold: 5
+  max_recent_actions: 100

package/agents/moderator.yaml

@@ -0,0 +1,13 @@
+type: moderator
+version: "1.0.0"
+description: Core moderation agent that adapts guidance to user experience level
+capabilities:
+  - code-review
+  - task-planning
+  - workflow-selection
+  - checkpoint-management
+  - retrospective
+behavior:
+  adapts_to_level: true
+  learns_patterns: true
+  respects_suppressed: true

package/agents/swarm-coordinator.yaml

@@ -0,0 +1,13 @@
+type: swarm-coordinator
+version: "1.0.0"
+description: Token-conscious swarm coordinator that only spawns agents when complexity warrants it
+capabilities:
+  - cost-estimation
+  - analysis-swarm
+  - refactoring-swarm
+  - budget-enforcement
+behavior:
+  default_budget: conservative
+  tokens_per_agent: 5000
+  max_agents: 8
+  require_estimate_before_spawn: true