@triedotdev/mcp 1.0.44 → 1.0.46

package/README.md

@@ -14,13 +14,19 @@ The last mile of shipping is where things break—not because your code doesn't
 
 ## What's New (latest updates)
 
-- **External Skills**: Install reusable capabilities from Vercel, Anthropic, Expo, Stripe, Supabase, or any GitHub repository. Skills are applied by the skill-review agent during scans and tracked in your project context. Browse available skills at [skills.sh](https://skills.sh).
+- **Bootstrap System**: Run `trie init` to auto-detect your stack (framework, language, database). Optionally customize `.trie/RULES.md` for coding standards. Works out of the box - no config required.
+
+- **Issue Memory & Cross-Project Learning**: Issues are now stored in `.trie/memory/` with BM25 search (same algorithm as Elasticsearch). Intelligent compaction summarizes old issues instead of deleting them, tracking trends and recurring patterns over time.
+
+- **Extended Skill Gating**: Skills can now declare requirements for npm dependencies, environment variables, binaries in PATH, and config files. Only skills whose requirements match your project environment are loaded.
+
+- **External Skills**: Install reusable capabilities from Vercel, Anthropic, Expo, Stripe, Supabase, or any GitHub repository. Skills are applied by the skill-review agent during scans and tracked in your project context.
 
 - **Project Info Registry**: Store important project context in `.trie/PROJECT.md` that travels with you across Claude Code, Cursor, GitHub Actions, and CLI. Define your project description, tech stack, conventions, architecture, and custom AI instructions—all in one place.
 
 - **Accessibility Agent (v2.0)**: Comprehensive WCAG 2.1 AA compliance. Detects icon-only buttons, touch targets, skipped headings, positive tabIndex, ARIA validation, color-only indicators, and 20+ more checks with WCAG criterion references.
 
-- **Health Score Triaging**: Your health score (0-100) now actively controls what agents run. Below 50%? All agents run automatically. Agents that found issues before get boosted priority in future scans.
+- **Memory-Influenced Triaging**: The triager now uses issue memory to boost agent priority. Agents that found issues before, have recurring patterns, or have cross-project patterns get boosted confidence. If your codebase trend is "declining", all agents get a slight boost.
 
 - **Moneybags Agent**: Estimates dollar cost of bugs using IBM/NIST research. Costs scale with your user count—use `--users 10000` to match your scale (default: 250 users).
 
@@ -41,8 +47,10 @@ The last mile of shipping is where things break—not because your code doesn't
 - [Legal Agent (v2.0)](#legal-agent-v20)
 - [Design Engineer (v2.0)](#design-engineer-v20)
 - [Special Agents](#special-agents)
-- [Custom Agents](#custom-agents)
+- [Custom Skills](#custom-skills)
 - [External Skills](#external-skills)
+- [Bootstrap System](#bootstrap-system)
+- [Issue Memory](#issue-memory)
 - [Project Info Registry](#project-info-registry)
 - [AI-Enhanced Mode](#ai-enhanced-mode)
 - [CI/CD Integration](#cicd-integration)
@@ -63,7 +71,7 @@ The last mile of shipping is where things break—not because your code doesn't
 | **22 Built-in Agents** | Security, Privacy, SOC 2, Legal, Architecture, Performance, E2E, Visual QA, Data Flow, Moneybags, Production Ready, and more |
 | **Parallel Execution** | True parallel execution with worker threads—3-5x faster scans |
 | **Result Caching** | File-based caching with SHA256 hashing—70% faster repeated scans |
-| **Smart Triaging** | Only activates relevant agents based on code context |
+| **Smart Triaging** | Activates agents based on code context, issue history, and memory patterns |
 | **Streaming Progress** | Real-time progress updates as agents complete |
 
 ### Developer Experience
@@ -71,7 +79,7 @@ The last mile of shipping is where things break—not because your code doesn't
 | Feature | Description |
 |---------|-------------|
 | **Watch Mode** | Automatically scan files as you code |
-| **Custom Agents** | Create agents from PDFs, docs, or style guides |
+| **Custom Skills** | Create skills from PDFs, docs, or style guides |
 | **External Skills** | Install capabilities from Vercel, Anthropic, Expo, Stripe, or any GitHub repo |
 | **Works Everywhere** | Auto-detects Cursor, Claude Code, OpenCode, VS Code—adapts output automatically |
 | **AI-Enhanced Mode** | Optional deeper analysis with `ANTHROPIC_API_KEY` |
@@ -232,13 +240,30 @@ Once set up, here's how to use Trie day-to-day.
 | What type of code you have | Runs the right checks (payments, auth, etc.) automatically |
 | Scan history | See if issues are getting better or worse |
 
-**This works everywhere automatically:**
-- ✅ Cursor remembers between sessions
-- ✅ Claude Code picks up where you left off
-- ✅ CLI shows the same status
-- ✅ GitHub Actions uses the same context
+**How context sharing works:**
+
+Think of `trie scan` and `trie checkpoint` as saving your game. Context is captured when you run them:
+
+```
+trie scan (full analysis) or trie checkpoint (quick save)
+    ↓
+Saves to .trie/AGENTS.md, .trie/memory/
+    ↓
+Open same project in Claude Code
+    ↓
+Claude Code reads trie://context → sees your history
+```
+
+| Command | What It Does |
+|---------|--------------|
+| `trie scan` | Full analysis - runs agents, finds issues, updates health score |
+| `trie checkpoint "message"` | Quick save - saves your current context without running agents |
+
+- Context persists in `.trie/` files in your project directory
+- Any MCP client (Cursor, Claude Code) can read `trie://context`
+- CLI and GitHub Actions read the same `.trie/` files
 
-**Where it's stored:** A file called `.trie/AGENTS.md` in your project. You can look at it anytime to see your project's health status.
+**Where it's stored:** `.trie/AGENTS.md` contains your health score and checkpoints. `.trie/memory/` contains searchable issue logs.
 
 ### Health Score: The Priority System
 
@@ -253,24 +278,26 @@ Your **health score** isn't just a number—it actively controls how Trie works
 **How it works across tools:**
 
 ```
-Cursor: Scan finds 14 issues → Health drops to 56%
+Cursor: Run trie scan → finds 14 issues → Health drops to 56%
                     ↓
-Claude Code: Opens same project → Sees 56% health
+        Saved to .trie/AGENTS.md
                     ↓
-Trie automatically runs more thorough checks
+Claude Code: Open same project → read trie://context → sees 56% health
                     ↓
-GitHub Actions: Same health score → Stricter CI gates
+        Run trie scan → more thorough checks (low health = all agents)
+                    ↓
+GitHub Actions: Reads .trie/ → same health score → stricter CI gates
 ```
 
 **Why this matters:**
 
-| Scenario | Without Health Score | With Health Score |
-|----------|---------------------|-------------------|
-| Quick fix in Cursor | Might skip security check | Knows security found issues → runs it |
-| Switch to Claude Code | Starts fresh, no context | Picks up your 56% health, stays vigilant |
-| Push to GitHub | Generic checks | Focused on your known problem areas |
+| Scenario | Without Trie | With Trie |
+|----------|--------------|-----------|
+| Quick fix in Cursor | No history | Run `trie scan` → knows security found issues → runs it |
+| Switch to Claude Code | Starts fresh | Reads `.trie/` → picks up your 56% health |
+| Push to GitHub | Generic checks | Reads `.trie/` → focused on known problem areas |
 
-The health score ensures your project's context **travels with you** across every tool.
+The `.trie/` directory ensures your project's context **travels with you** across every tool. Just run `trie scan` to capture it.
 
 ---
 
@@ -396,14 +423,17 @@ These tools are available when using Trie via MCP (Cursor, Claude Code, etc.).
 | `trie_fix` | Generate fix recommendations for detected issues |
 | `trie_explain` | Explain code, issues, or changes in plain language |
 | `trie_project` | View and manage project info (.trie/PROJECT.md) |
+| `trie_init` | Initialize bootstrap files, detect stack, suggest skills |
+| `trie_memory` | Search and manage issue memory across projects |
+| `trie_checkpoint` | Quick save context without running a full scan |
 
-### Custom Agent Tools
+### Custom Skill Tools
 
 | Tool | Description |
 |------|-------------|
-| `trie_create_agent` | Create a custom agent from a PDF, TXT, or MD document |
-| `trie_save_agent` | Save a custom agent configuration |
-| `trie_list_agents` | List all registered agents (built-in and custom) |
+| `trie_create_skill` | Create a custom skill from a PDF, TXT, or MD document |
+| `trie_save_skill` | Save a custom skill configuration |
+| `trie_list_skills` | List all skills (external and custom) |
 
 ### Individual Agent Tools
 
@@ -464,6 +494,24 @@ trie-agent skills add vercel-labs/agent-skills react-best-practices
 
 # List installed skills
 trie-agent skills list
+
+# Initialize bootstrap files
+trie-agent init
+
+# Search issue memory
+trie-agent memory search "SQL injection"
+
+# View cross-project patterns
+trie-agent memory global patterns
+
+# Quick save (checkpoint without full scan)
+trie-agent checkpoint "finished auth flow"
+
+# List checkpoints
+trie-agent checkpoint list
+
+# View skills
+trie-agent skills list
 ```
 
 ### CLI vs MCP Tools
@@ -927,35 +975,35 @@ Run trie_agent_smith on this codebase
 
 ---
 
-## Custom Agents
+## Custom Skills
 
-Create your own agents from PDFs, style guides, or documentation.
+Create your own skills from PDFs, style guides, or documentation. Custom skills are portable review rules that travel with your project—they work in Cursor, Claude Code, CI/CD, and everywhere in between.
 
-### Create a Custom Agent
+### Create a Custom Skill
 
 ```
-Create a custom agent from my-style-guide.pdf called "brand_guidelines"
+Create a custom skill from my-style-guide.pdf called "brand_guidelines"
 ```
 
 Or use the MCP tool directly:
 
 ```
-trie_create_agent with filePath: "./docs/style-guide.pdf", agentName: "brand_guidelines"
+trie_create_skill with filePath: "./docs/style-guide.pdf", skillName: "brand_guidelines"
 ```
 
 ### How It Works
 
 1. **Parse** — Trie extracts text from your document (PDF, TXT, MD)
 2. **Compress** — AI distills the document into actionable rules
-3. **Register** — The agent is saved to `.trie/agents/` and loaded automatically
+3. **Register** — The skill is saved to `.trie/skills/custom/` and runs automatically during scans
 
-### List Custom Agents
+### List Custom Skills
 
 ```
-trie_list_agents
+trie_list_skills
 ```
 
-Custom agents are stored in `.trie/agents/` in your project directory.
+Custom skills are stored in `.trie/skills/custom/` in your project directory.
 
 ---
 
@@ -965,14 +1013,18 @@ Install reusable capabilities from Vercel, Anthropic, Expo, Stripe, Supabase, or
 
 ### Key Concept: Agents vs Skills
 
-| | Agent (Brain) | Skill (Hands) |
-|---|---------------|---------------|
+| | Agent (Brain) | Skill (Knowledge) |
+|---|---------------|-------------------|
 | **Decides when to run** | Yes | No - invoked by agent |
-| **Has its own logic** | Yes | No - just instructions |
-| **Makes decisions** | Yes | No - follows instructions |
-| **Examples** | SecurityAgent, CustomAgent | react-best-practices SKILL.md |
+| **Has its own logic** | Yes | No - detection patterns |
+| **Makes decisions** | Yes | No - follows rules |
+| **Examples** | SecurityAgent, TriagerAgent | react-best-practices, brand_guidelines |
+
+**Two types of skills:**
+- **External Skills** — Installed from GitHub repos (e.g., `vercel-labs/agent-skills`)
+- **Custom Skills** — Created from your documents (PDFs, style guides, books)
 
-Skills are applied by the **skill-review agent** during scans.
+Both skill types are applied by the **skill-review agent** during scans and travel with your project.
 
 ### Install a Skill
 
@@ -1081,6 +1133,198 @@ Skills can come from any GitHub repository with a SKILL.md file:
 
 Browse all available skills at [skills.sh](https://skills.sh)
 
+### Skill Gating
+
+Skills can declare requirements in their frontmatter. Only skills whose requirements are met are loaded.
+
+**Simple (backwards compatible):**
+
+```yaml
+---
+name: react-best-practices
+description: React and Next.js optimization
+requires: [react, next]
+---
+```
+
+**Extended requirements:**
+
+```yaml
+---
+name: docker-deploy-skill
+description: Docker deployment best practices
+requirements:
+  deps: [docker-compose]          # npm deps (all required)
+  anyDeps: [react, vue, svelte]   # At least one required
+  env: [DOCKER_HOST, CI]          # Environment variables
+  bins: [docker, kubectl]         # Binaries in PATH
+  configFiles: [Dockerfile]       # Files that must exist
+---
+```
+
+| Check | What It Does |
+|-------|--------------|
+| `deps` | All listed npm packages must be in package.json |
+| `anyDeps` | At least one must be present (OR condition) |
+| `env` | Environment variables must be set |
+| `bins` | Binaries must be available in PATH |
+| `configFiles` | Files must exist in project root |
+
+When you install skills, they're automatically filtered based on your project:
+- A React skill with `requires: [react]` only loads in React projects
+- A Docker skill with `requirements.bins: [docker]` only loads when Docker is installed
+- Skills without requirements always load
+
+This prevents irrelevant skills from cluttering your scans.
+
+---
+
+## Bootstrap System
+
+Trie works out of the box - no setup required. Run `trie init` to optionally create context files for customization.
+
+### Files (all optional)
+
+| File | Purpose |
+|------|---------|
+| `.trie/RULES.md` | Your coding standards (edit to customize) |
+| `.trie/TEAM.md` | Team ownership and escalation paths |
+| `.trie/PROJECT.md` | Project overview and conventions |
+| `.trie/BOOTSTRAP.md` | First-run checklist (auto-deleted when complete) |
+
+### Initialize
+
+**CLI:**
+```bash
+trie init
+```
+
+**MCP:**
+```
+trie_init
+```
+
+This auto-detects your stack and creates optional templates:
+
+```
+Detected Stack:
+  Framework: Next.js 14.0.0
+  Language: TypeScript
+  Database: Prisma ORM
+  Auth: NextAuth.js
+
+Suggested Skills:
+  trie skills add vercel-labs/agent-skills react-best-practices
+```
+
+### Commands
+
+```bash
+# Initialize bootstrap files
+trie init
+
+# Check bootstrap status
+trie init status
+
+# Mark bootstrap complete (deletes BOOTSTRAP.md)
+trie init complete
+```
+
+### MCP Resources
+
+```
+trie://bootstrap    # Bootstrap status
+trie://rules        # User-defined coding standards
+trie://team         # Team ownership info
+```
+
+---
+
+## Issue Memory
+
+Trie stores all detected issues for search and cross-project learning. Uses BM25 ranking (same algorithm as Elasticsearch) for intelligent search.
+
+### Local Memory (`.trie/memory/`)
+
+Issues from each scan are stored locally:
+- `issues.json` - Searchable issue index with BM25 ranking
+- `YYYY-MM-DD.md` - Daily issue logs
+- `compacted-summaries.json` - Historical summaries (auto-generated)
+
+### Search Issues
+
+**CLI:**
+```bash
+# Search by keyword
+trie memory search "SQL injection"
+
+# View recent issues
+trie memory recent
+
+# Show statistics
+trie memory stats
+
+# Mark issue resolved
+trie memory resolve <issue-id>
+```
+
+**MCP:**
+```
+trie_memory action="search" query="SQL injection"
+trie_memory action="stats"
+trie_memory action="recent" limit=10
+```
+
+### Cross-Project Memory (`~/.trie/memory/`)
+
+Patterns are tracked across all your projects:
+
+```bash
+# View patterns across projects
+trie memory global patterns
+
+# List tracked projects
+trie memory global projects
+
+# Search global patterns
+trie memory global search "authentication"
+```
+
+### MCP Resources
+
+```
+trie://memory         # Local issue stats and recent issues
+trie://memory/global  # Cross-project patterns and stats
+```
+
+### How It Works
+
+1. **BM25 Search**: Uses term frequency, inverse document frequency, and document length normalization for ranking
+2. **Pattern Detection**: Issues are normalized and hashed to detect patterns
+3. **Cross-Project Tracking**: Same pattern in multiple projects is tracked
+4. **Fix Propagation**: When you fix a pattern, it's recorded for other projects
+5. **Smart Suggestions**: Global patterns inform local scans
+
+### Intelligent Compaction
+
+Instead of deleting old issues, Trie summarizes them:
+
+- **Automatic**: When issues exceed 500, old ones (>30 days) are compacted
+- **Summaries**: Top patterns, hot files, severity breakdown preserved
+- **Trends**: Tracks if codebase is improving, stable, or declining
+- **Recurring Patterns**: Identifies issues that keep appearing across periods
+- **12 Month History**: Keeps up to 12 compacted summaries
+
+```bash
+# View stats including historical data
+trie memory stats
+
+# Output includes:
+#   Total Issues: 150
+#   Historical: 1,200 (from compacted summaries)
+#   Trend: improving
+```
+
 ---
 
 ## Project Info Registry