xtrm-tools 2.2.0 → 2.4.0

package/README.md

@@ -1,164 +1,187 @@
 # XTRM-Tools
 
-**Claude Code tools installer** — skills, hooks, MCP servers, and project-specific extensions.
+> **Claude Code plugin** — workflow enforcement, code quality gates, issue tracking, and development automation.
 
-> **ARCHITECTURAL DECISION (v2.0.0+):** xtrm-tools supports **Claude Code exclusively**. Hook translation for Gemini CLI and Qwen CLI was removed.
+**Version 2.3.0** | [Complete Guide](XTRM-GUIDE.md) | [Changelog](CHANGELOG.md)
 
-> **MIGRATION NOTICE (v2.1.20+):** Core logic has moved to **Pi Extensions**. See the [Pi Extensions Migration Guide](docs/pi-extensions-migration.md).
-
-This repository contains production-ready extensions to enhance Claude's capabilities with prompt improvement, task delegation, development workflow automation, and quality gates. The `xtrm` CLI provides a robust, modular "Plug & Play" installation engine for project-specific tools.
+---
 
 ## Quick Start
 
 ```bash
 # Install globally (one-time)
-git clone https://github.com/Jaggerxtrm/xtrm-tools.git
-cd xtrm-tools/cli
-npm install && npm run build
-npm link
+npm install -g github:Jaggerxtrm/xtrm-tools@latest
 
-# Initialize a project and register gitnexus MCP
-xtrm project init
-```
+# Install the plugin
+xtrm install all
 
-## Table of Contents
+# Verify
+claude plugin list
+# → xtrm-tools@xtrm-tools  Version: 2.3.0  Status: ✔ enabled
+```
 
-- [Project Skills & Hooks](#project-skills--hooks)
-- [Global Skills](#global-skills)
-- [Installation](#installation)
-- [CLI User Guide](#cli-user-guide)
-- [Configuration](#configuration)
-- [Version History](#version-history)
-- [License](#license)
+**One-line run:**
+```bash
+npx -y github:Jaggerxtrm/xtrm-tools install all
+```
 
 ---
 
-## Project Skills & Hooks
+## What's Included
 
-Project skills are modular, plug-and-play tool packages extending Claude's capabilities for specific workflows. They install into your project's `.claude/` directory and include specific hooks enforcing local workflow rules and quality gates.
+### Core Enforcement
 
-### using-xtrm (Session Operating Manual)
-**The foundational operating manual for an xtrm-equipped session.**
-- **Invocation**: Activates automatically at session start via hook.
-- **Purpose**: Orients the agent on how to work within the xtrm stack: applying prompt improvement, using the beads issue-tracking gate, enforcing PR workflows, and combining the full toolset (gitnexus, Serena, TDD guard, quality gates, delegation).
-- **Core Workflow**: Provides the authoritative guide on feature-branch usage, requiring PRs for merges (with `--squash`), and stopping dangerous git commands on protected branches.
+| Component | Purpose |
+|-----------|---------|
+| **Main Guard** | PR-only workflow — blocks direct commits on `main`/`master` |
+| **Beads Gates** | Issue tracking — edit/commit/stop gates, memory prompts |
+| **Quality Gates** | Auto linting (ESLint, tsc, ruff, mypy) on file edits |
+| **GitNexus** | Knowledge graph context for code exploration |
 
-### TDD Guard & Quality Gates (`tdd-guard` & `using-quality-gates`)
-- **tdd-guard**: Enforces Test-Driven Development by blocking implementation until failing tests exist. Now covers **Serena edit tools** via bridge behavior.
-- **using-quality-gates**: Unified PostToolUse code quality hooks — runs linting, type checking, and formatting (Python + TypeScript with strict mypy/ruff rules) on every edit.
+### Skills
 
-### Service Skills Set (Trinity)
-Task intake and service routing for Docker service projects.
-- **Invocation**: `/scope "task description"` or automatic via SessionStart hook.
-- **Purpose**: Gives Claude persistent, service-specific expertise without re-explaining architecture. Emits structured scope plans and detects codebase drift via PostToolUse hooks.
+| Skill | Type | Purpose |
+|-------|------|---------|
+| `using-xtrm` | Project | Session operating manual |
+| `documenting` | Global | SSOT documentation with drift detection |
+| `delegating` | Global | Task delegation to cost-optimized agents |
+| `orchestrating-agents` | Global | Multi-model collaboration |
 
-### Core Project Hooks
+---
 
-**Main Guard (`main-guard.mjs`)**
-- **Trigger**: PreToolUse (Write|Edit|MultiEdit|Serena edit tools|Bash)
-- **Purpose**: Enforces PR-only merge workflow with full git protection. Blocks direct commits and dangerous `git checkout` / `git push` commands on protected branches (`main/master`).
-- **Post-Push (`main-guard-post-push.mjs`)**: After pushing a feature branch, reminds to use `gh pr merge --squash` and sync local via `git reset --hard origin/main`.
+## Plugin Structure
 
-**GitNexus Graph Context (`gitnexus-hook.cjs`)**
-- **Trigger**: PostToolUse (with Serena support and dedup cache)
-- **Purpose**: Enriches tool output with knowledge graph context via `gitnexus augment`.
-- *Note: `gitnexus-impact-reminder` was removed as impact analysis enforcement is now native.*
+```
+plugins/xtrm-tools/
+├── .claude-plugin/plugin.json   # Manifest
+├── hooks → ../../hooks           # All hook scripts + hooks.json
+├── skills → ../../skills         # Auto-discovered skills
+└── .mcp.json → ../../.mcp.json   # MCP servers
+```
 
-**Beads Issue Tracking Gates**
-- **Trigger**: PreToolUse, PostToolUse, Stop, PreCompact, SessionStart
-- **Purpose**: Ensures all work is tracked to a `bd` issue. Blocks file edits without an active claim.
-- **Compaction**: Newly added `PreCompact` and `SessionStart` hooks preserve `in_progress` beads state across `/compact` events. Hook blocking messages are quieted and compacted to save tokens.
+All hook paths use `${CLAUDE_PLUGIN_ROOT}` — works from any installation location.
 
 ---
 
-## Global Skills
+## Policy System
 
-Global skills are reusable workflows installed to the user-level Claude environment (not tied to one repo). 
+Policies are the **single source of truth** for all enforcement rules. Located in `policies/`, they compile to both Claude hooks and Pi extensions.
 
-### documenting
-Maintains Single Source of Truth (SSOT) documentation system with drift detection.
-- **Invocation**: `/document [task]`
-- **Purpose**: Creates, updates, and validates SSOT documentation. Auto-generates INDEX blocks for rapid navigation. A Stop hook fires at session end to detect stale memories based on the `tracks:` frontmatter field.
+### Policy Files
 
-### delegating
-Proactively delegates tasks to cost-optimized agents before working in main session.
-- **Invocation**: `/delegate [task]` or `/delegating [task]`
-- **Purpose**: Routes simple deterministic tasks (tests, typos, formatting, docs) to GLM/Gemini/Qwen, and complex reasoning tasks to multi-agent orchestration. Interactive 2-step menu helps select the backend. Avoids main session token usage.
+| Policy | Runtime | Purpose |
+|--------|---------|---------|
+| `main-guard.json` | both | PR-only workflow |
+| `beads.json` | both | Issue tracking gates |
+| `quality-gates.json` | pi | Linting/typechecking |
+| `branch-state.json` | claude | Branch context injection |
+| `gitnexus.json` | claude | Knowledge graph enrichment |
 
-### orchestrating-agents
-Orchestrates task handoff and "handshaking" between Gemini and Qwen CLI agents.
-- **Invocation**: `/orchestrate [workflow-type] [task]`
-- **Purpose**: Facilitates multi-model collaboration, adversarial reviews, and deep cross-validation of complex logic. Workflows include collaborative design, adversarial security review, troubleshooting, and single handshakes.
+### Compiler
 
----
+```bash
+node scripts/compile-policies.mjs           # Generate hooks.json
+node scripts/compile-policies.mjs --check   # CI drift detection
+```
 
-## Installation
+---
 
-### 🚀 Quick One-Time Run
+## CLI Commands
 
-```bash
-npx -y github:Jaggerxtrm/xtrm-tools install all
+```
+xtrm <command> [options]
 ```
 
-### 🛠️ Global Installation (Recommended)
+| Command | Description |
+|---------|-------------|
+| `install all` | Full plugin + beads + gitnexus |
+| `install basic` | Plugin + skills (no beads) |
+| `install project <name>` | Install project skill |
+| `project init` | Initialize project (gitnexus + bd) |
+| `status` | Read-only diff view |
+| `clean` | Remove orphaned hooks |
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--yes`, `-y` | Non-interactive mode |
+| `--dry-run` | Preview only |
+| `--prune` | Force-replace hooks |
 
-```bash
-npm install -g github:Jaggerxtrm/xtrm-tools@latest
+---
 
-xtrm install all            # Install to all global targets
-xtrm project init           # Setup current project (runs gitnexus analyze + bd init)
-xtrm install project all    # Install all project-specific skills
-```
+## Hooks Reference
+
+### Event Types
+
+| Event | When |
+|-------|------|
+| `SessionStart` | Session begins |
+| `PreToolUse` | Before tool invocation |
+| `PostToolUse` | After tool completes |
+| `Stop` | Session ends |
+| `PreCompact` | Before compaction |
+
+### Main Guard
+
+- Blocks `git commit`/`push` on protected branches
+- Blocks direct file edits on `main`/`master`
+- Post-push reminder: `gh pr merge --squash`
+
+### Beads Gates
+
+| Hook | Behavior |
+|------|----------|
+| Edit Gate | Requires claimed issue to edit files |
+| Commit Gate | Prompts to close issue before commit |
+| Stop Gate | Blocks session end with unclosed issues |
+| Memory Gate | Prompts to persist insights when closing |
 
 ---
 
-## CLI User Guide
+## MCP Servers
 
-```
-xtrm <command> [options]
-```
+Configured in `.mcp.json`:
 
-| Command | Description |
-|---|---|
-| `install all` | Non-interactive global install to all detected targets (installs `gitnexus` globally) |
-| `install basic` | Interactive global installation |
-| `install project <name>` | Install specific project skills (e.g., `tdd-guard`, `service-skills-set`) |
-| `project init` | Onboarding: runs `gitnexus analyze`, registers MCP, and runs `bd init` |
-| `status` | Read-only diff view showing what would change (with inline sync prompt) |
-| `clean` | Removes orphaned hooks, stale wrappers, and dead skills from your system |
-| `reset` | Clear saved CLI preferences |
+| Server | Purpose |
+|--------|---------|
+| `serena` | Code analysis via LSP |
+| `context7` | Documentation lookup |
+| `gitnexus` | Knowledge graph |
+| `github-grep` | Code search |
 
 ---
 
-## Configuration
+## Issue Tracking (Beads)
 
-### MCP Servers
+```bash
+bd ready                    # Find unblocked work
+bd update <id> --claim      # Claim an issue
+bd close <id> --reason "Done"  # Close when done
+```
 
-Unified CLI sync configures core servers securely.
+---
 
-**Core Servers**:
-- **serena**: Code analysis (requires `uvx`)
-- **context7**: Documentation lookup (requires `CONTEXT7_API_KEY`)
-- **github-grep**: Code search
-- **deepwiki**: Technical documentation
-- **gitnexus**: Knowledge graph code intelligence (registered during `xtrm project init`)
+## Documentation
 
-Configured via `~/.config/xtrm-tools/.env`. Run `xtrm install basic` to sync interactively.
+- **[XTRM-GUIDE.md](XTRM-GUIDE.md)** — Complete reference guide
+- **[CHANGELOG.md](CHANGELOG.md)** — Full version history
+- **[ROADMAP.md](ROADMAP.md)** — Planned features
 
 ---
 
 ## Version History
 
 | Version | Date | Highlights |
-|---|---|---|
-| 2.1.20 | 2026-03-16 | `xtrm clean` command, compact hook messages, `pruneStaleWrappers` fixes |
-| 2.1.18 | 2026-03-16 | `PreCompact` / `SessionStart` hooks to preserve `in_progress` beads state |
-| 2.1.16 | 2026-03-15 | Removed deprecated skill-suggestion, gitnexus-impact-reminder hooks |
-| 2.1.14 | 2026-03-15 | Rewrote gitnexus-hook as PostToolUse with Serena; added `using-xtrm` skill |
-| 2.1.9 | 2026-03-15 | `main-guard` enforced PR-only workflow, `--squash` requirement, npm publish |
+|---------|------|------------|
+| 2.3.0 | 2026-03-17 | Plugin structure, policy compiler, Pi extension parity |
+| 2.2.0 | 2026-03-17 | Pi extensions: quality-gates, beads, main-guard |
+| 2.0.0 | 2026-03-12 | CLI rebrand, project skills engine |
+| 1.7.0 | 2026-02-25 | GitNexus integration |
 
-See [CHANGELOG.md](CHANGELOG.md) for full history.
+---
 
 ## License
 
-MIT License - See LICENSE file for details.
+MIT License