xtrm-tools 0.7.2 → 0.7.4

package/.xtrm/skills/default/service-skills-set/service-skills-readme.md

@@ -0,0 +1,236 @@
+# Service Skills
+
+A system that gives Claude persistent, project-specific operational knowledge about your Docker services. Instead of re-explaining your architecture every session, each service has a dedicated skill package that Claude loads on demand.
+
+---
+
+## What It Does
+
+**Three workflow skills** form the trinity:
+
+| Skill | Role | When it runs |
+|---|---|---|
+| `creating-service-skills` | Builds new skill packages via 3-phase workflow (scaffold + Serena deep dive + hook registration) | Manually via `/creating-service-skills` |
+| `using-service-skills` | Discovers and activates expert personas | Automatically at session start |
+| `updating-service-skills` | Detects drift when code changes | Automatically on every file write |
+
+**Five hooks** keep everything wired together:
+
+| Hook | Type | Trigger | Effect |
+|---|---|---|---|
+| `SessionStart` | Claude Code | Session opens | Injects lightweight service catalog into context (~150 tokens) |
+| `PreToolUse` | Claude Code | Any Read/Write/Edit/Grep/Glob/Bash | Checks if the operation touches a service territory; injects skill load reminder and enforcement |
+| `PostToolUse` | Claude Code | Any Write/Edit | Checks if modified file belongs to a registered service; notifies Claude to sync docs |
+| `pre-commit` | Git | `git commit` | Warns if source files changed without SSOT documentation update (non-blocking) |
+| `pre-push` | Git | `git push` | Warns if service skills are older than the source files being pushed (non-blocking) |
+
+**Each generated skill package** for a service contains:
+
+```
+.claude/skills/<service-name>/
+├── SKILL.md                  — architecture, data flows, failure modes, common operations
+├── scripts/
+│   ├── health_probe.py       — container status + table freshness check
+│   ├── log_hunter.py         — service-specific log pattern analysis
+│   ├── data_explorer.py      — read-only DB inspection
+│   └── <specialist>.py       — service-type-specific inspector
+└── references/
+    ├── deep_dive.md          — Phase 2 research notes
+    └── architecture_ssot.md  — link to project SSOT if available
+```
+
+---
+
+## Installation
+
+Run once, from inside your target project directory:
+
+```bash
+cd ~/projects/my-project
+python3 /path/to/jaggers-agent-tools/project-skills/service-skills-set/install-service-skills.py
+```
+
+This installs the three workflow skills, wires `settings.json` hooks, and activates git hooks. Idempotent — safe to re-run after updates.
+
+---
+
+## Creating a Service Skill
+
+```bash
+# In Claude Code, invoke the skill:
+/creating-service-skills
+```
+
+The skill runs a **mandatory three-phase workflow**:
+
+### Phase 1 — Automated Skeleton
+
+```bash
+python3 "$CLAUDE_PROJECT_DIR/.claude/skills/creating-service-skills/scripts/scaffolder.py" \
+  create <service-id> <territory-path> "<description>"
+```
+
+Reads `docker-compose*.yml`, `Dockerfile`, and dependency files. Produces:
+- `SKILL.md` with `[PENDING RESEARCH]` markers
+- Script stubs in `scripts/`
+- Official documentation links auto-detected from image tags and package files
+- Entry in `.claude/skills/service-registry.json`
+
+### Phase 2 — Agentic Deep Dive
+
+Claude reads the actual source code to fill every `[PENDING RESEARCH]` marker.
+Uses Serena LSP tools (not raw file reads) for efficiency:
+
+```
+get_symbols_overview   → map module structure
+find_symbol            → read specific functions
+search_for_pattern     → find log strings, SQL queries, env vars
+find_referencing_symbols → trace data flows
+```
+
+### Phase 3 — Hook Registration
+
+After the deep dive is complete, Claude verifies the auto-activation infrastructure:
+
+1. Confirms the `PreToolUse` hook is present in `.claude/settings.json` (pointing to `skill_activator.py`)
+2. Verifies the service entry in `.claude/skills/service-registry.json` has territory globs set
+3. Informs you that the skill will now auto-activate whenever Claude:
+   - Operates on a file matching the service's territory globs
+   - Runs a Bash command that mentions the service name or container name
+
+No manual registration step is needed — the installer wires the hooks at project setup time. Phase 3 is a verification and communication step only.
+
+A skill is **complete** only when:
+- No `[PENDING RESEARCH]` markers remain
+- `health_probe.py` queries real tables with correct stale thresholds
+- `log_hunter.py` patterns sourced from actual codebase error strings
+- Troubleshooting table has ≥5 rows from real failure modes
+- All scripts support `--json` output
+- `PreToolUse` skill activator hook confirmed in `.claude/settings.json`
+- Service territory globs verified in `.claude/skills/service-registry.json`
+- You have been informed: skill auto-activates on territory file access and service-name commands
+
+---
+
+## Using a Service Skill
+
+At session start, Claude receives:
+
+```xml
+<project_service_catalog>
+Available expert personas:
+- db-expert: SQL & schema optimization (Path: .claude/skills/db-expert/SKILL.md)
+- auth-service: JWT authentication expert (Path: .claude/skills/auth-service/SKILL.md)
+</project_service_catalog>
+```
+
+Claude automatically loads the relevant skill when you ask about a covered service. You can also invoke explicitly:
+
+```
+Read .claude/skills/<service-name>/SKILL.md
+```
+
+### Auto-activation
+
+Once a service skill is registered, you don't need to load it manually.
+The `PreToolUse` hook (`skill_activator.py`) fires automatically whenever
+Claude operates on a file in the service's territory or runs a Bash command
+mentioning the service name. It injects:
+
+```
+[Service Skill] You are about to work with the 'auth-service' service territory.
+  Load the expert skill before proceeding: Read .claude/skills/auth-service/SKILL.md
+  Do not use ad-hoc approaches (raw SQL, improvised docker commands) when the
+  skill defines the correct method.
+```
+
+This enforces that Claude uses the skill's defined diagnostic scripts and
+operational procedures rather than improvising — e.g. running `health_probe.py`
+instead of issuing direct `psql` queries, or checking `log_hunter.py` patterns
+before reading raw docker logs.
+
+### Run scripts directly
+
+```bash
+python3 .claude/skills/<service-name>/scripts/health_probe.py
+python3 .claude/skills/<service-name>/scripts/log_hunter.py --errors-only
+python3 .claude/skills/<service-name>/scripts/data_explorer.py --limit 20 --json
+```
+
+---
+
+## Updating a Service Skill
+
+When you modify service source code, the `PostToolUse` hook fires automatically and Claude sees:
+
+```
+[Skill Sync]: Implementation drift detected in 'auth-service'.
+File 'src/auth/jwt.py' was modified.
+Use '/updating-service-skills' to sync the Auth Service documentation.
+```
+
+To sync:
+
+```bash
+/updating-service-skills
+```
+
+To mark a service as synced after manual update:
+
+```bash
+python3 .claude/skills/updating-service-skills/scripts/drift_detector.py sync <service-id>
+```
+
+To scan all services for drift:
+
+```bash
+python3 .claude/skills/updating-service-skills/scripts/drift_detector.py scan
+```
+
+---
+
+## Registry
+
+`.claude/skills/service-registry.json` is the source of truth for registered services:
+
+```json
+{
+  "services": {
+    "auth-service": {
+      "name": "Auth Service",
+      "territory": ["src/auth/**/*.py"],
+      "skill_path": ".claude/skills/auth-service/SKILL.md",
+      "description": "JWT authentication and session management",
+      "last_sync": "2026-02-23T19:00:00Z"
+    }
+  }
+}
+```
+
+The `territory` globs determine which file paths trigger drift detection and skill auto-activation.
+
+---
+
+## Project Structure
+
+```
+project-skills/service-skills-set/      — this repository's source
+├── install-service-skills.py           — installer (run from inside target project)
+└── .claude/
+    ├── settings.json                   — settings template with all 3 hook events
+    ├── git-hooks/
+    │   ├── doc_reminder.py             — pre-commit: SSOT reminder
+    │   └── skill_staleness.py          — pre-push: stale skill warning
+    ├── creating-service-skills/        — workflow skill: build new service skills
+    ├── using-service-skills/           — workflow skill: catalog injection + skill activation
+    └── updating-service-skills/        — workflow skill: drift detection
+
+.claude/                                — installed into your project
+├── settings.json                       — SessionStart + PreToolUse + PostToolUse hooks
+└── skills/
+    ├── service-registry.json
+    ├── creating-service-skills/
+    ├── using-service-skills/
+    ├── updating-service-skills/
+    └── <generated-service-skills>/
+```

package/.xtrm/skills/default/service-skills-set/settings.json

@@ -0,0 +1,37 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/skills/using-service-skills/scripts/cataloger.py\""
+          }
+        ]
+      }
+    ],
+        "PreToolUse": [
+      {
+        "matcher": "Read|Write|Edit|Glob|Grep|Bash|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/skills/using-service-skills/scripts/skill_activator.py\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/skills/updating-service-skills/scripts/drift_detector.py\" check-hook",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/.xtrm/skills/default/session-close-report/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: session-close-report
+description: |
+  Generate a structured technical handoff report at session close.
+  You run `xt report generate` to get the data skeleton, then fill every
+  <!-- FILL --> section from your own session context. The result is the
+  definitive handoff contract for the next agent.
+---
+
+# session-close-report
+
+## When to use
+
+Invoke this skill at the end of a productive session — after issues are closed,
+code is committed, but before final push. It produces the handoff report that
+the next agent reads to start cold without losing context.
+
+## Workflow
+
+### 1. Generate the skeleton
+
+```bash
+xt report generate
+```
+
+This collects data from git log, bd, .specialists/jobs/ and writes a skeleton
+to `.xtrm/reports/<date>-<hash>.md` with YAML frontmatter and pre-filled tables.
+
+### 2. Read the skeleton
+
+Read the generated file. It has `<!-- FILL -->` markers in every section that
+needs your input.
+
+### 3. Fill every section from your context
+
+You are the orchestrator. You have the full session context. The CLI only
+collected raw data — you provide the meaning.
+
+**For each section, here is exactly what to write:**
+
+#### Summary
+One dense paragraph. What was accomplished, key decisions made, discoveries,
+outcomes. Technical prose — no filler, no "in this session we...". Lead with
+the most important result.
+
+#### Issues Closed
+The skeleton has a flat table. Restructure it:
+- Group by category: bugs discovered, backlog items, cleanup/closures, features
+- If specialists were used, add Specialist and Wave columns
+- Expand terse close reasons into useful context
+
+#### Issues Filed
+Add every issue you created this session. The **Why** column is mandatory —
+explain the rationale for filing, not just what the issue says.
+
+Update the `issues_filed` count in frontmatter.
+
+#### Specialist Dispatches
+If specialists were dispatched:
+- Build a Wave summary table: Wave number, specialists, models, outcomes
+- Add a Problems sub-table for any failed/stalled dispatches
+- Update `specialist_dispatches` and `models_used` in frontmatter
+
+If no specialists were used, delete this section.
+
+#### Problems Encountered
+Every problem hit during the session. Root Cause and Resolution columns are
+mandatory. Include: bugs discovered, wrong approaches tried, blockers hit,
+tooling failures. If no problems, delete this section entirely.
+
+#### Code Changes
+The skeleton lists files. Add narrative:
+- Explain key modifications (not every file — focus on the important ones)
+- Group logically if many changes (e.g., "CLI commands", "Hook changes")
+- Note architectural decisions embedded in the changes
+
+#### Documentation Updates
+List doc changes, skill updates, memory saves, CHANGELOG entries.
+Delete if no doc work happened.
+
+#### Open Issues with Context
+This is the most valuable handoff section. For each open issue:
+- **Context / Suggestions**: What the next agent needs to know. Current state,
+  blockers discovered, suggested approach, files to look at, gotchas.
+- Group into "Ready for next session" and "Backlog" subsections
+- Put the most actionable items first
+
+#### Memories Saved
+List all `bd remember` calls made this session. If the skeleton missed any,
+add them. If none were saved, note why (nothing novel, or deferred).
+
+#### Suggested Next Priority
+Ordered list of 1-4 items with rationale for each. Based on:
+- Dependency order (what unblocks the most)
+- User's stated intent (if they mentioned what's next)
+- Urgency of discovered issues
+- Blocked items about to unblock
+
+### 4. Update frontmatter
+
+Ensure all frontmatter counts are accurate after filling:
+- `issues_filed` — actual count
+- `specialist_dispatches` — actual count
+- `models_used` — list of models that did work this session
+
+### 5. Commit the report
+
+```bash
+git add .xtrm/reports/
+git commit -m "session report: <date>"
+```
+
+## Quality bar
+
+The reference is `~/projects/specialists/.xtrm/reports/2026-03-30-orchestration-session.md`.
+Every report must match that level of detail. Specifically:
+
+- No empty `<!-- FILL -->` markers left in the final output
+- Every closed issue has context, not just an ID
+- Every open issue has actionable handoff suggestions
+- Problems section captures root causes, not just symptoms
+- Summary is a dense technical paragraph, not a list of bullet points
+
+## CLI commands
+
+| Command | Purpose |
+|---------|---------|
+| `xt report generate` | Collect data, write skeleton |
+| `xt report show [target]` | Display latest or specified report |
+| `xt report list` | List all reports with frontmatter summary |
+| `xt report diff <a> <b>` | Compare two reports |

package/.xtrm/skills/default/skill-creator/LICENSE.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.