xtrm-tools 0.5.29 → 0.5.31

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xtrm-tools",
-  "version": "0.5.29",
+  "version": "0.5.31",
   "description": "xtrm-tools: dual-runtime workflow enforcement (Claude Code + Pi) — hooks, extensions, skills, and MCP servers",
   "author": {
     "name": "jaggers"

package/CHANGELOG.md

@@ -12,13 +12,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - gitnexus hook now fires on Grep/Read/Glob tools (parity with Pi); quality-check covers .cjs/.mjs files; quality gate env pre-check at SessionStart; policies.md rewritten from scaffold; using-xtrm SKILL.md rewritten; worktree-session migrated to bd worktree; branch state + xt end reminders in gate messages
 
----
-
-
 ### Changed
 - v0.5.26 docs sync and Pi parity updates: quality gates, beads/session-flow lifecycle, using-xtrm loader parity, and policy-path normalization
 - Pi installer parity: `xt pi setup` now matches `xt pi install/reload` for extension deployment; managed extensions use sync + auto-discovery and no longer use duplicate `pi install -l` registration
 - Pi custom-footer now tracks Claude statusline parity with richer runtime/git snapshots and a two-line footer layout (metadata + issue row), including pi-dex-safe reapply behavior.
+
+---
+
+## [0.5.29] - 2026-03-22
+
+### Added
+- `skills/merge-prs/SKILL.md` and `specialists/merge-prs.specialist.yaml` for PR merge workflow
+- Release script now encodes `--tag latest` for npm publish
+
+### Changed
+- Detect default branch via `symbolic-ref` + master fallback, replaced 9 hardcoded `origin/main` references
+- Optimized Pi installer with pre-check and diff-based sync
+- Statusline improvements: fixed sessionId fallback, fixed hardcoded icons, added statusline-claim to .gitignore
+
+### Fixed
+- **Autocommit now uses `--no-verify`**: both Claude hook (`beads-claim-sync.mjs`) and Pi extension (`beads/index.ts`) skip pre-commit hooks on automated `bd close` commits
+
+---
+
 ## [0.5.20] - 2026-03-21
 
 ### Added

package/README.md

@@ -1,8 +1,52 @@
 # XTRM-Tools
 
-> **Dual-runtime workflow system** — Claude Code plugin + Pi extension suite for workflow enforcement, code quality gates, issue tracking, and development automation.
+**xtrm** (`xt`) is an agentic workflow system that turns Claude Code and Pi into disciplined, self-managing development agents. Every session is structured, every change is tracked, and every agent knows exactly what to do next.
 
-**Version 0.5.24** | [Complete Guide](XTRM-GUIDE.md) | [Changelog](CHANGELOG.md)
+### Beads — issue tracking built for agents
+
+[Beads](https://github.com/Jaggerxtrm/beads) is a Dolt-backed issue tracker designed for agentic workflows. Issues are first-class citizens: agents claim them before editing, close them before committing, and carry context forward across sessions and machines via persistent memory. The full `bd` CLI is available inside every session — `bd ready`, `bd update <id> --claim`, `bd close <id>`, `bd remember`.
+
+### Hooks — enforcement gates that run automatically
+
+A policy compiler produces hooks for both Claude Code and Pi from a single source. These gates enforce the workflow without relying on the agent to remember: the **Edit gate** blocks writes without an active claim, the **Commit gate** blocks `git commit` until the issue is closed, the **Stop gate** checks for unclosed work at session end, and the **Memory gate** prompts the agent to persist insights before exiting. Quality gates run ESLint, tsc, ruff, and mypy automatically on every file save.
+
+### Skills — reusable agent behaviors
+
+A library of composable skills covers the full development lifecycle: session management (`using-xtrm`), structured planning (`planning`), test coverage strategy (`test-planning`), autonomous session close (`xt-end`), PR queue management (`xt-merge`), documentation maintenance (`documenting`), and domain expertise (backend, devops, security, data science). Skills are injected into the agent context on demand and work identically in Claude Code and Pi.
+
+### Planning mode
+
+The `planning` skill generates a structured issue board from any spec or idea — epics, tasks, dependencies, test coverage annotations — using `bd create` in parallel. Agents can pick up and continue planned work across sessions with full context. GitNexus impact analysis and Serena code intelligence are integrated into the planning flow so blast radius is assessed before a single line is written.
+
+### Statusline
+
+A live statusline renders in every Claude Code session: active claim, open issue count, model, context window health (color-coded truecolor gradient), and token usage — all in a single line below the prompt. No configuration required after `xtrm install`.
+
+### Specialists *(upcoming)*
+
+Native integration with the [specialists](https://github.com/Jaggerxtrm/specialists) framework — spawning purpose-built sub-agents for parallel workloads, code review, and long-running background tasks directly from within a session.
+
+---
+
+**Version 0.5.30** | [Complete Guide](XTRM-GUIDE.md) | [Changelog](CHANGELOG.md)
+
+---
+
+## Documentation
+
+| Doc | Contents |
+|-----|----------|
+| [XTRM-GUIDE.md](XTRM-GUIDE.md) | Complete reference — architecture, concepts, full workflow |
+| [docs/hooks.md](docs/hooks.md) | All hooks — event wiring, gate logic, order, authoring |
+| [docs/policies.md](docs/policies.md) | Policy system — compiler, schema, Claude/Pi parity |
+| [docs/skills.md](docs/skills.md) | Skills catalog — all skills, categories, how they load |
+| [docs/pi-extensions.md](docs/pi-extensions.md) | Pi extensions — managed sync, authoring, parity notes |
+| [docs/worktrees.md](docs/worktrees.md) | xt worktrees — `xt claude/pi`, `xt end`, isolation model |
+| [docs/mcp-servers.md](docs/mcp-servers.md) | MCP servers — gitnexus, github-grep, deepwiki, official plugins |
+| [docs/cli-architecture.md](docs/cli-architecture.md) | CLI internals — install flow, diff/sync engine, config merge |
+| [docs/project-skills.md](docs/project-skills.md) | Project-scoped skills — install, layout, Pi/Claude symlinks |
+| [docs/testing.md](docs/testing.md) | Live testing checklist — integration, gates, worktree flows |
+| [CHANGELOG.md](CHANGELOG.md) | Full version history |
 
 ---
 
@@ -17,7 +61,7 @@ xtrm install
 
 # Verify
 claude plugin list
-# → xtrm-tools@xtrm-tools  Version: 0.5.10  Status: ✔ enabled
+# → xtrm-tools@xtrm-tools  Version: 0.5.30  Status: enabled
 ```
 
 **One-line run:**
@@ -41,58 +85,78 @@ npx -y github:Jaggerxtrm/xtrm-tools install
 
 ### Skills
 
-| Skill | Type | Purpose |
-|-------|------|---------|
-| `using-xtrm` | Global | Session operating manual |
-| `documenting` | Global | SSOT documentation with drift detection |
-| `delegating` | Global | Task delegation to cost-optimized agents |
-| `orchestrating-agents` | Global | Multi-model collaboration |
-| `using-quality-gates` | Global | Quality gate configuration and usage guide |
-| `using-service-skills` | Global | Territory-based service skill activation |
-| `creating-service-skills` | Global | Scaffold new service skills via Serena LSP deep dive |
-| `scoping-service-skills` | Global | Define territory globs for service skill routing |
-| `updating-service-skills` | Global | Drift detection and sync for service skill definitions |
-
----
-
-## Plugin Structure
-
-```
-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
-```
-
-All hook paths use `${CLAUDE_PLUGIN_ROOT}` — works from any installation location.
+Skills are organized into two categories: **xtrm workflow** skills built specifically for the xtrm stack, and **general-purpose** expert skills that work in any project.
+
+#### xtrm Workflow Skills
+
+These skills implement the xtrm-specific development workflow — session management, issue tracking, planning, quality, and documentation patterns.
+
+| Skill | Purpose |
+|-------|---------|
+| `using-xtrm` | Session operating manual — when to use which tool |
+| `using-quality-gates` | Quality gate workflow — TDD guard, lint/typecheck cycle |
+| `using-serena-lsp` | Code exploration and surgical edits via Serena LSP |
+| `using-tdd` | Test-driven development with 80%+ coverage enforcement |
+| `using-service-skills` | Service catalog discovery and expert persona activation |
+| `xt-end` | Autonomous session close — rebase, push, PR, cleanup |
+| `xt-merge` | FIFO PR merge queue for xt worktree sessions |
+| `planning` | Structured issue board from any spec, with phases and deps |
+| `test-planning` | Test coverage planning alongside implementation work |
+| `delegating` | Cost-optimized task delegation to background agents |
+| `orchestrating-agents` | Multi-model orchestration (Gemini, Qwen handshake) |
+| `documenting` | SSOT doc maintenance with drift detection |
+| `sync-docs` | Doc audit and structural sync across a sprint |
+| `skill-creator` | Create, improve, and evaluate skills |
+| `find-skills` | Discover and install skills on demand |
+| `creating-service-skills` | Generate operational service skill packages |
+| `scoping-service-skills` | Task intake and service routing |
+| `updating-service-skills` | Detect drift and sync expert persona docs |
+| `prompt-improving` | Apply Claude XML best practices to prompts |
+
+#### General-Purpose Expert Skills
+
+Domain expert skills that can be used in any project, independent of the xtrm workflow.
+
+| Skill | Purpose |
+|-------|---------|
+| `senior-backend` | NodeJS, Express, Go, Python, Postgres, REST/GraphQL |
+| `senior-devops` | CI/CD, infrastructure as code, cloud platforms |
+| `senior-security` | AppSec, pen testing, threat modeling, crypto |
+| `senior-data-scientist` | Statistics, ML, A/B testing, causal inference |
+| `docker-expert` | Multi-stage builds, Compose, container security |
+| `python-testing` | pytest, TDD, fixtures, mocking, coverage |
+| `hook-development` | PreToolUse/PostToolUse hook authoring |
+| `clean-code` | Pragmatic coding standards, no over-engineering |
+| `gitnexus-exploring` | Navigate unfamiliar code via knowledge graph |
+| `gitnexus-impact-analysis` | Blast radius before making code changes |
+| `gitnexus-debugging` | Trace bugs through call chains |
+| `gitnexus-refactoring` | Plan safe refactors via dependency mapping |
+| `obsidian-cli` | Interact with Obsidian vaults via CLI |
 
 ---
 
 ## Policy System
 
-Policies are the **single source of truth** for all enforcement rules. Located in `policies/`, they compile to both Claude hooks and Pi extensions.
-
-### Policy Files
+Policies in `policies/` are the single source of truth for all enforcement rules. They compile to both Claude hooks and Pi extensions.
 
 | Policy | Runtime | Purpose |
 |--------|---------|---------|
-| `session-flow.json` | both | Claim sync, stop gate, `xt end` reminder |
 | `beads.json` | both | Issue tracking gates |
-| `quality-gates.json` | both | Linting/typechecking |
+| `session-flow.json` | both | Claim sync, stop gate, `xt end` reminder |
+| `quality-gates.json` | both | Linting/typechecking on file edits |
 | `quality-gates-env.json` | both | Warns if tsc/ruff/eslint missing at session start |
-| `using-xtrm.json` | claude | Injects using-xtrm session manual at SessionStart |
 | `gitnexus.json` | claude | Knowledge graph enrichment |
-| `worktree-boundary.json` | claude | Blocks edits outside worktree when in `.xtrm/worktrees` |
+| `using-xtrm.json` | claude | Injects session manual at SessionStart |
+| `worktree-boundary.json` | claude | Blocks edits outside active worktree |
 | `service-skills.json` | pi | Territory-based skill activation |
 
-### Compiler
-
 ```bash
 node scripts/compile-policies.mjs           # Generate hooks.json
 node scripts/compile-policies.mjs --check   # CI drift detection
 ```
 
+See [docs/policies.md](docs/policies.md) for full schema and authoring reference.
+
 ---
 
 ## CLI Commands
@@ -104,91 +168,46 @@ xtrm <command> [options]
 | Command | Description |
 |---------|-------------|
 | `install` | Install plugin + beads + gitnexus (interactive target selection) |
-| `init` | Initialize project data (bd, gitnexus, service-registry) |
+| `init` | Initialize project (bd, gitnexus, service-registry) |
 | `status` | Read-only diff view |
 | `clean` | Remove orphaned hooks |
 | `end` | Close worktree session: rebase, push, PR, cleanup |
 | `worktree list` | List all active `xt/*` worktrees |
-| `worktree clean` | Remove worktrees whose branch has been merged |
+| `worktree clean` | Remove merged worktrees |
 | `claude` | Launch Claude Code in a sandboxed worktree |
-| `pi` | Launch Pi in a sandboxed worktree; includes `install/setup/status/doctor/reload` runtime management |
+| `pi` | Launch Pi in a sandboxed worktree |
 | `docs show` | Display frontmatter for README, CHANGELOG, docs/*.md |
-| `debug` | Watch xtrm hook and bd lifecycle events in real time |
-
-### Pi Extension Loading
-
-- `xt pi setup`, `xt pi install`, and `xt pi reload` share the same managed extension sync behavior.
-- Extensions from `config/pi/extensions/<name>/` are synced to `~/.pi/agent/extensions/<name>/` and loaded by Pi auto-discovery.
-- Managed extensions are not re-registered with `pi install -l` (prevents duplicate command/flag/shortcut registration conflicts).
-- `custom-footer` now mirrors Claude statusline information density with a two-line parity layout (session metadata + claim/open issue row), while remaining compatible with `pi-dex` footer refresh behavior.
-
-### Flags
-
-| Flag | Description |
-|------|-------------|
-| `--yes`, `-y` | Non-interactive mode |
-| `--dry-run` | Preview only |
-| `--prune` | Force-replace hooks |
-
----
-
-## Hooks Reference
-
-### Event Types
+| `debug` | Watch hook and bd lifecycle events in real time |
 
-| Event | When |
-|-------|------|
-| `SessionStart` | Session begins |
-| `UserPromptSubmit` | After user submits prompt |
-| `PreToolUse` | Before tool invocation |
-| `PostToolUse` | After tool completes |
-| `Stop` | Session ends |
-| `PreCompact` | Before compaction |
+**Flags:** `--yes / -y` (non-interactive), `--dry-run` (preview), `--prune` (force-replace hooks)
 
-### 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 |
+See [docs/cli-architecture.md](docs/cli-architecture.md) for internals.
 
 ---
 
 ## MCP Servers
 
-Configured in `.mcp.json` (xtrm-managed only):
-
 | Server | Purpose |
 |--------|---------|
 | `gitnexus` | Knowledge graph |
 | `github-grep` | Code search |
-| `deepwiki` | DeepWiki docs search |
+| `deepwiki` | Repository documentation |
+
+Official Claude plugins installed by `xtrm install`: `serena`, `context7`, `github`, `ralph-loop`.
 
-Official Claude plugins are installed during `xtrm install`:
-- `serena@claude-plugins-official`
-- `context7@claude-plugins-official`
-- `github@claude-plugins-official`
-- `ralph-loop@claude-plugins-official`
+See [docs/mcp-servers.md](docs/mcp-servers.md) for configuration details.
 
 ---
 
 ## Issue Tracking (Beads)
 
 ```bash
-bd ready                    # Find unblocked work
-bd update <id> --claim      # Claim an issue
-bd close <id> --reason "Done"  # Close when done
+bd ready                           # Find unblocked work
+bd update <id> --claim             # Claim an issue
+bd close <id> --reason "Done"      # Close when done
 ```
 
----
-
-## Documentation
-
-- **[XTRM-GUIDE.md](XTRM-GUIDE.md)** — Complete reference guide
-- **[CHANGELOG.md](CHANGELOG.md)** — Full version history
-- **[ROADMAP.md](ROADMAP.md)** — Planned features
+See [XTRM-GUIDE.md](XTRM-GUIDE.md) for the full `bd` command reference.
 
 ---
 
@@ -196,17 +215,13 @@ bd close <id> --reason "Done"  # Close when done
 
 | Version | Date | Highlights |
 |---------|------|------------|
-| 0.5.24 | 2026-03-21 | Hash-based docs drift detection; CLI docs cleanup; `docs` and `debug` commands documented |
-| 0.5.23 | 2026-03-21 | `xtrm debug` command for real-time event monitoring |
-| 0.5.20 | 2026-03-21 | `xtrm docs show` command; worktree-boundary hook; statusline injection |
-| 0.5.10 | 2026-03-21 | Install cleanup: removes stale `~/.claude/hooks/` + `~/.claude/skills/`; Qwen/Gemini dead code removed |
-| 0.5.9 | 2026-03-20 | Worktrees moved inside repo under `.xtrm/worktrees/` |
-| 0.5.8 | 2026-03-20 | session-flow rewrite: claim sync, stop gate, `xt end` reminder |
-| 0.5.7 | 2026-03-20 | Dead hooks removed; dead CLI removed (`finish.ts`, `session-state.ts`) |
-| 0.5.6 | 2026-03-20 | `xt` CLI commands; plugin-only delivery for Claude; deprecated `xtrm finish` |
+| 0.5.30 | 2026-03-22 | Fix statusline on fresh installs; `xt end --dry-run` |
+| 0.5.29 | 2026-03-22 | Statusline truecolor gradient; `--no-verify` autocommit; xt-merge skill |
+| 0.5.24 | 2026-03-21 | Hash-based docs drift detection; CLI docs cleanup |
+| 0.5.20 | 2026-03-21 | `xtrm docs show`; worktree-boundary hook; statusline injection |
 
----
+See [CHANGELOG.md](CHANGELOG.md) for full history.
 
-## License
+---
 
 MIT License