xtrm-tools 0.7.3 → 0.7.4

package/.xtrm/skills/default/planning/SKILL.md

@@ -0,0 +1,405 @@
+---
+name: planning
+description: >
+  Structured planning skill for xtrm ecosystem projects. Creates a well-documented
+  bd issue board from any task, feature, spec, or idea — with phases, dependencies,
+  rich descriptions, and integrated test coverage via test-planning. MUST activate
+  whenever the user wants to "plan", "design", "architect", "break down", "structure",
+  "scope out", or "start" a feature or epic. Also activate when: the user describes
+  a complex task without existing issues, pastes a spec or PRD to decompose, asks
+  "how should I approach X" or "where do I start", mentions wanting to create
+  implementation issues, or starts a new worktree session without a claimed issue.
+  Activate even when the user says something like "I want to implement X" — if there's
+  no existing issue board for X, planning comes first. Never skip planning when a
+  task spans more than 2 files or 3 steps — that's when a structured board saves hours.
+---
+
+# Planning
+
+Transform intent into a bd issue board: each issue self-contained, documented
+enough for any agent or human to work independently.
+
+## When This Fires
+
+- `plan`, `design`, `architect`, `scope out`, `break down`, `how should I approach`
+- Starting a new feature/epic from scratch
+- Decomposing a spec, PRD, or long description into tasks
+- Reviewing existing issues that lack documentation or structure
+- Before `bd update --claim` — plan first, then claim
+
+---
+
+## Workflow
+
+```
+Phase 1  Clarify intent          → understand what, why, constraints
+Phase 2  Explore codebase        → GitNexus + Serena, read-only
+Phase 3  Structure the plan      → phases, deps, CoT reasoning
+Phase 4  Create bd issues        → epic + tasks, rich descriptions
+Phase 5  test-planning           → companion test issues per layer
+Phase 6  Handoff                 → claim first issue, ready to build
+```
+
+---
+
+## Phase 1 — Clarify Intent
+
+Before touching any code, nail down:
+
+<clarification_checklist>
+  <item>What is being built? (feature, fix, refactor, migration)</item>
+  <item>Why — what problem does it solve?</item>
+  <item>Constraints (must not break X, must use pattern Y, deadline)</item>
+  <item>Known unknowns — what needs investigation?</item>
+  <item>Priority (P0 critical → P4 backlog)</item>
+</clarification_checklist>
+
+If the request is under 8 words or the scope is unclear, ask **one** clarifying question before exploring. Don't ask two.
+
+---
+
+## Phase 2 — Explore Codebase (Read-Only)
+
+Use GitNexus and Serena to understand the landscape. No file edits.
+
+### GitNexus-first protocol (mandatory when available)
+
+```bash
+# 1) Find relevant execution flows by concept
+gitnexus_query({query: "<concept related to task>"})
+
+# 2) Get full caller/callee/process context for likely symbols
+gitnexus_context({name: "<affected symbol>"})
+
+# 3) Assess blast radius before locking the implementation plan
+gitnexus_impact({target: "<symbol to change>", direction: "upstream"})
+```
+
+### Refactor planning checks (when rename/extract/move is in scope)
+
+```bash
+# Preview safe multi-file rename plan first
+gitnexus_rename({symbol_name: "<old>", new_name: "<new>", dry_run: true})
+
+# Confirm context before extraction/split plans
+gitnexus_context({name: "<symbol to extract/split>"})
+gitnexus_impact({target: "<symbol to extract/split>", direction: "upstream"})
+```
+
+### Serena symbol-level inspection (targeted reads)
+
+```bash
+# Map a file without reading all of it
+get_symbols_overview("path/to/relevant/file.ts")
+
+# Read just the relevant function
+find_symbol("SymbolName", include_body=true)
+```
+
+### Fallback when GitNexus MCP tools are unavailable
+
+If MCP GitNexus tools are unavailable, use the GitNexus CLI first, then Serena symbol exploration if needed.
+
+```bash
+# Verify index freshness / repository indexing
+npx gitnexus status
+npx gitnexus list
+
+# Concept and architecture exploration
+npx gitnexus query "<concept or symptom>" --limit 5
+npx gitnexus context "<symbolName>"
+
+# Blast radius before committing to a plan
+npx gitnexus impact "<symbolName>" --direction upstream --depth 3
+
+# If index is stale
+npx gitnexus analyze
+```
+
+Notes:
+- In this environment, `detect_changes` and `rename` are available via MCP tools, not GitNexus CLI subcommands.
+- If both MCP and CLI are unavailable, fall back to Serena search + symbols and state this explicitly in your plan output.
+
+```bash
+search_for_pattern("<concept or symbol>")
+get_symbols_overview("path/to/relevant/file.ts")
+find_symbol("<candidate symbol>", include_body=true)
+find_referencing_symbols("<symbol>", "path/to/file.ts")
+```
+
+**Capture from exploration:**
+- Which files/symbols will be affected
+- Which execution flows/processes are involved (from `gitnexus_query`/`gitnexus_context`)
+- What existing patterns to follow (naming, structure, error handling)
+- Any d=1 dependents that require updates when you change a symbol
+- Risk level from impact analysis: if CRITICAL or HIGH → warn user before proceeding
+- If GitNexus fallback path was used, explicitly call it out in the handoff
+
+---
+
+## Phase 3 — Structure the Plan
+
+Think through the plan before writing any bd commands. Use structured CoT:
+
+<thinking>
+1. What are the distinct units of work? (group by: what can change together without breaking other things)
+2. What phases make sense?
+   - P0: Scaffold (types, interfaces, file structure) — others depend on this
+   - P1: Core (pure logic, no I/O) — depends on scaffold
+   - P2: Boundary/Integration (HTTP, DB, CLI wiring) — depends on core
+   - P3: Tests — companion issues, see Phase 5
+3. What are the dependencies? (what must be done before X can start?)
+4. What can run in parallel? (independent tasks → no deps between them)
+5. What are the risks? (complex areas, unclear spec, risky refactors)
+6. What is the blast-radius summary from GitNexus? (direct callers, affected processes, risk level)
+</thinking>
+
+<plan>
+  <phase name="P0: Scaffold" issues="N">
+    Setup that unblocks all other work
+  </phase>
+  <phase name="P1: Core" issues="N">
+    Pure logic, data transforms, parsers
+  </phase>
+  <phase name="P2: Integration" issues="N">
+    CLI wiring, API clients, I/O
+  </phase>
+</plan>
+
+**Sizing guidance:**
+- Prefer tasks completable in one session (1-4 hours of focused work)
+- If a task has 5+ unrelated deliverables → split it
+- If two tasks always ship together → merge them
+
+---
+
+## Phase 4 — Create bd Issues
+
+### Determine epic scope
+
+If the work fits under an **existing open epic** (`bd ready` to check), create tasks
+under it with `--parent=<existing-epic-id>` and skip creating a new epic.
+
+If this is genuinely new work with no parent, create the epic first.
+
+### Create the epic (new work only)
+
+```bash
+bd create \
+  --title="<Feature name — concise verb phrase>" \
+  --description="$(cat <<'EOF'
+## Overview
+
+<2-3 sentences: what this is and why it exists>
+
+## Goals
+
+- Goal 1: measurable outcome
+- Goal 2: measurable outcome
+
+## Non-goals
+
+- What we are explicitly NOT doing
+
+## Success criteria
+
+- [ ] Criteria 1 (observable, testable)
+- [ ] Criteria 2
+
+## Context / background
+
+<Links to specs, related issues, existing code paths>
+EOF
+)" \
+  --type=epic \
+  --priority=<0-4>
+```
+
+### Create child task issues
+
+```bash
+bd create \
+  --title="<Action phrase — what gets built>" \
+  --description="$(cat <<'EOF'
+## Context
+
+<Why does this task exist? What does it enable? What comes before/after?>
+
+## What to build
+
+<Specific deliverables. Not "implement X" — "X that does Y when Z">
+
+## Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Tests pass / lint clean
+
+## Approach notes
+
+<Relevant code paths (file:line), patterns to follow, discovered risks>
+EOF
+)" \
+  --type=task \
+  --priority=<same or +1 from epic> \
+  --parent=<epic-id>
+```
+
+### Wire dependencies
+
+```bash
+# B depends on A (A blocks B)
+bd dep add <B-id> <A-id>
+
+# Non-blocking relationship
+bd dep relate <issue-a> <issue-b>
+```
+
+### Issue description quality bar
+
+Every task issue description must answer:
+1. **Why** — why does this exist? (not obvious from the title)
+2. **What** — specific deliverables (not vague)
+3. **When done** — acceptance criteria as checkboxes
+4. **How** — approach hints, relevant code paths, patterns to follow
+
+If you can't fill in all four, the scope is still unclear — go back to Phase 1.
+
+---
+
+## Phase 5 — Test Planning Integration
+
+After the implementation issues are created, invoke **test-planning**:
+
+```
+/test-planning
+```
+
+test-planning will:
+1. Classify each implementation issue by layer (core / boundary / shell)
+2. Pick the right testing strategy per layer
+3. Create companion test issues batched by layer and phase
+4. Gate next-phase issues on test completion
+
+**When to call it:**
+- Always after creating an epic with 3+ implementation tasks
+- When closing an implementation issue (test-planning checks for gaps)
+- When you realize tests weren't planned upfront
+
+**Layer signals to include in your issue descriptions** (helps test-planning classify correctly):
+- Core layer: "transforms", "computes", "parses", "validates", no HTTP/DB/filesystem
+- Boundary layer: "API", "endpoint", "client", "query", "fetch", URLs, ports
+- Shell layer: "CLI command", "subcommand", "orchestrates", "wires together"
+
+---
+
+## Phase 6 — Handoff
+
+Present the board and transition to implementation.
+
+Include a short **Architecture & Impact Summary** in your handoff message:
+- Key execution flows/processes involved
+- Top d=1 dependents to watch
+- Highest observed risk (LOW/MEDIUM/HIGH/CRITICAL)
+- Whether GitNexus-first or fallback exploration was used
+
+```bash
+# Show the full board
+bd show <epic-id>
+
+# Claim the first implementation issue
+bd update <first-task-id> --claim
+```
+
+Then begin work on the first task. The planning phase is complete.
+
+---
+
+## Examples
+
+### Example 1 — New CLI command
+
+<example>
+  <scenario>User: "add a `xtrm audit` command that checks for stale hooks"</scenario>
+
+  <exploration>
+    gitnexus_query({query: "hook wiring audit clean"})
+    → finds: cleanOrphanedHookEntries, pruneStaleWrappers in clean.ts
+    gitnexus_impact({target: "cleanOrphanedHookEntries", direction: "upstream"})
+    → 2 callers, LOW risk
+  </exploration>
+
+  <plan>
+    Phase 1: Add audit command skeleton (new file, register in index.ts)
+    Phase 2: Implement hook validation logic (read config/hooks.json, compare installed)
+    Phase 3: Add --fix flag to auto-remediate drift
+    Phase 4: Tests — CLI integration test (shell layer)
+  </plan>
+
+  <bd_commands>
+    bd create --title="xtrm audit: detect and report stale hook wiring" --type=epic
+    bd create --title="Scaffold xtrm audit command" --description="Context: ..." --type=task
+    bd create --title="Implement hook validation — compare config/hooks.json to settings.json" ...
+    bd create --title="Add --fix flag for auto-remediation" ...
+    bd dep add <wiring-id> <scaffold-id>    # wiring depends on scaffold
+    bd dep add <fix-id> <wiring-id>         # fix depends on wiring
+  </bd_commands>
+</example>
+
+### Example 2 — Bug fix with investigation
+
+<example>
+  <scenario>User: "bd close doesn't commit my changes"</scenario>
+
+  <exploration>
+    gitnexus_query({query: "bd close commit workflow"})
+    → finds: beads-claim-sync.mjs, close event handler
+    find_symbol("main", include_body=true)
+    → discovers: bd close sets closed-this-session KV only; no git commit
+  </exploration>
+
+  <thinking>
+    bd close does NOT auto-commit (removed in xtrm-wr0o).
+    Correct workflow: bd close <id>, then git add + git commit separately, then xt end.
+    No issue needed — this is expected behavior.
+  </thinking>
+
+  <bd_command>
+    # No issue needed — explain the correct workflow to the user:
+    # 1. bd close <id> --reason="..."   ← closes issue
+    # 2. git add . && git commit -m "..." ← commit changes manually
+    # 3. xt end                           ← push, PR, merge, worktree cleanup
+  </bd_command>
+</example>
+
+### Example 3 — Greenfield feature from spec
+
+<example>
+  <scenario>User provides a 3-paragraph spec for a new xtrm status command</scenario>
+
+  <approach>
+    Phase 0: Define TypeScript interfaces (StatusReport, HealthCheck)
+    Phase 1: Implement each health check function (hooks, settings, bd, mcp)
+    Phase 2: Implement CLI command, output formatting, --json flag
+    Phase 3: Tests — unit for each check fn (core), integration for CLI (shell)
+
+    Create epic first, then 4 implementation tasks, then call /test-planning.
+  </approach>
+</example>
+
+---
+
+## Self-Check Before Finishing
+
+Before presenting the plan to the user:
+
+- [ ] Every issue has context / what / AC / notes
+- [ ] Dependencies are correct (A blocks B when B needs A's output)
+- [ ] No task is more than "one session" of work (split if needed)
+- [ ] GitNexus evidence captured (query/context/impact) or fallback path explicitly stated
+- [ ] If refactor scope exists, rename/extract safety checks were included in plan
+- [ ] test-planning was invoked (or scheduled as next step)
+- [ ] First implementation issue is ready to claim
+
+If any issue description is empty or just restates the title — it's not ready.
+The test of a good issue: could another agent pick it up cold and succeed?

package/.xtrm/skills/default/planning/evals/evals.json

@@ -0,0 +1,19 @@
+{
+  "skill_name": "planning",
+  "evals": [
+    {
+      "id": 1,
+      "eval_name": "docs-list-command",
+      "prompt": "Plan the implementation of the `xtrm docs list` command (xtrm-vwp0). The command should list all project docs with metadata, support filtering, table output, and JSON mode. It needs to be a subcommand of the existing `xtrm docs` CLI group in cli/src/. There's already a partially-implemented docs.ts somewhere. Break this into a proper phased issue board.",
+      "expected_output": "An epic with phased child tasks (scaffold/core/integration), each with rich descriptions containing context, what to build, AC, and approach notes. test-planning invoked after issue board created. Dependencies wired between phases.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "eval_name": "docs-crosscheck-command",
+      "prompt": "Plan the implementation of the `xtrm docs cross-check` command (xtrm-uc0e). This validates docs against PRs and bd issues — detects stale docs, coverage gaps, open issue references. Uses gh CLI for GitHub data. Needs to be a subcommand of `xtrm docs`. Break this into a well-structured bd issue board with proper phasing.",
+      "expected_output": "An epic with phased child tasks covering: GitHub data fetching (boundary layer), cross-check logic (core layer), CLI command wiring (shell layer). test-planning invoked. High-quality issue descriptions that another agent could work from independently.",
+      "files": []
+    }
+  ]
+}

package/.xtrm/skills/default/prompt-improving/README.md

@@ -0,0 +1,162 @@
+# prompt-improving
+
+Automatically improves user prompts using Claude's XML best practices before execution.
+
+## Purpose
+
+Transforms raw, unstructured prompts into well-formatted requests that leverage Claude's capabilities more effectively. Applies semantic XML tags, multishot examples, chain-of-thought reasoning, and contextual structure based on task type.
+
+## Invocation
+
+```
+/prompt-improving "raw prompt text"
+```
+
+The skill analyzes the input prompt and enhances it with:
+- Semantic XML structure
+- Relevant examples from reference library
+- Chain-of-thought scaffolding
+- Context-appropriate formatting
+
+## Associated Hooks
+
+**skill-suggestion.sh**
+
+Proactively suggests using `/prompt-improving` when detecting:
+- Very short prompts (less than 35 characters)
+- Generic requests without specificity
+- Analysis or explanation tasks
+- Prompts in Italian or English
+
+Configuration in `~/.claude/settings.json`:
+```json
+{
+  "skillSuggestions": {
+    "enabled": true
+  }
+}
+```
+
+## Execution Flow
+
+1. **Detect Context**: Analyze prompt for task type (analysis, development, refactoring)
+2. **Apply Core XML**: Structure prompt with semantic tags from reference library
+3. **Add Examples**: Include multishot examples when beneficial
+4. **Handle Ambiguity**: If prompt is very vague, use AskUserQuestion dialog to clarify intent
+5. **Execute Improved**: Run the enhanced prompt through Claude
+
+## Reference Files
+
+The skill uses these reference documents to inform improvements:
+
+- `xml_core.md` - Semantic XML tags and prefill patterns
+- `multishot.md` - Example-based learning patterns
+- `chain_of_thought.md` - Reasoning scaffolds
+- `mcp_definitions.md` - MCP-specific structures
+- `analysis_commands.md` - Analysis task patterns
+
+## Configuration
+
+No additional configuration required beyond hook setup.
+
+## Examples
+
+### Example 1: Short Analysis Prompt
+
+**Before:**
+```
+analyze logs
+```
+
+**After:**
+```xml
+<log_analysis>
+  <thinking>
+    To analyze the logs effectively, I should:
+    1. Identify error patterns
+    2. Check timestamps for incident correlation
+    3. Look for system warnings
+    4. Summarize critical issues
+  </thinking>
+  <description>Analyze application logs for errors and issues</description>
+  <constraints>
+    - Focus on ERROR and WARN level entries
+    - Provide actionable recommendations
+  </constraints>
+</log_analysis>
+```
+
+### Example 2: Development Task
+
+**Before:**
+```
+implement oauth
+```
+
+**After:**
+```xml
+<implementation>
+  <description>Implement OAuth 2.0 authentication</description>
+  <parameters>
+    <param name="flow">Authorization Code flow with PKCE</param>
+    <param name="provider">To be specified</param>
+  </parameters>
+  <examples>
+    <example>Standard OAuth flow with JWT tokens</example>
+  </examples>
+  <instructions>
+    1. Setup OAuth client configuration
+    2. Implement authorization endpoint
+    3. Handle token exchange
+    4. Validate and refresh tokens
+  </instructions>
+  <constraints>
+    - Follow OAuth 2.0 security best practices
+    - Use HTTPS for all endpoints
+    - Implement proper CSRF protection
+  </constraints>
+</implementation>
+```
+
+## Ambiguity Handling
+
+When the prompt is too vague (less than 8 words, no specifics), the skill presents an interactive dialog:
+
+```
+Clarify: The prompt is ambiguous. What would you like me to focus on?
+
+Options:
+1. Add more detail - I'll provide more context
+2. Execute as-is - Apply basic XML structure and proceed
+3. Cancel - Skip prompt improvement
+```
+
+## Version History
+
+- **v5.1.0** (2026-01-30): Renamed from `p` to `prompt-improving` following Claude naming conventions
+- **v5.0.0** (2026-01-30): Simplified from 118 to 64 lines, removed complex quality metrics
+- **v4.2.0** (Pre-2026): Original feature-rich version with detailed scoring
+
+## Related Documentation
+
+- [Main README](../../README.md)
+- [CHANGELOG](../../CHANGELOG.md)
+- [ROADMAP](../../ROADMAP.md) - See Programmatic Tool Calling integration plans
+- [Hook Documentation](../../hooks/README.md)
+
+## Troubleshooting
+
+**Skill not triggering**
+- Verify skill directory is in `~/.claude/skills/`
+- Check SKILL.md frontmatter has correct name
+- Restart Claude Code if recently installed
+
+**No suggestions from hook**
+- Check `settings.json` has `skillSuggestions.enabled: true`
+- Verify `skill-suggestion.sh` is executable
+- Check hook timeout is sufficient (default: 1s)
+
+**Prompts not being improved**
+- Try explicit invocation: `/prompt-improving "your prompt"`
+- Check reference files exist in `references/` directory
+- Verify no errors in Claude Code console

package/.xtrm/skills/default/prompt-improving/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: prompt-improving
+description: 'Prompt Improver (Trigger: /prompt-improving "raw prompt"). Applies Claude XML best practices to user prompts before execution. Use when the user specifically invokes /prompt-improving.'
+gemini-command: prompt
+gemini-prompt: |
+  1. Detect context: ANALYSIS (thinking), DEV (examples), or REFACTOR (constraints).
+  2. Apply core XML tags (<description>, <parameters>, <instructions>).
+  3. Add enhancements (Chain of Thought, Multishot examples) based on context.
+  4. Execute ONLY the improved prompt version.
+---
+
+# Prompt Improver ( /prompt-improving )
+
+Automatically improves raw prompts using Claude's XML best practices (semantic tags, multishot examples, chain-of-thought) and then executes the improved version.
+
+## When to Use
+
+**Trigger:** User types `/prompt-improving "raw prompt"` or `/prompt-improving <raw prompt>`
+
+## Execution Flow
+
+1.  **Detect Context:**
+    *   Scan prompt for task type keywords
+    *   **ANALYSIS** (contains: analyze, investigate, research) → needs thinking space
+    *   **DEV** (contains: implement, create, build, add) → needs examples
+    *   **REFACTOR** (contains: refactor, improve, optimize) → needs constraints
+
+2.  **Apply Core XML:**
+    *   Consult [references/xml_core.md](references/xml_core.md)
+    *   Wrap the prompt in a semantic root tag (e.g., `<task_name>`)
+    *   Use tags like `<description>`, `<parameters>`, `<instructions>` by default
+
+3.  **Add Context-Specific Enhancements:**
+    *   **ANALYSIS tasks:**
+        *   Consult [references/chain_of_thought.md](references/chain_of_thought.md)
+        *   Add `<thinking>` section with prefill
+        *   Define structured `<outputs>`
+    *   **DEV tasks:**
+        *   Consult [references/multishot.md](references/multishot.md)
+        *   Add 1-2 `<example>` blocks
+    *   **REFACTOR tasks:**
+        *   Add `<constraints>` section (preserve behavior, tests must pass)
+        *   Add `<current_state>` context if helpful
+
+4.  **Handle Ambiguity:**
+    *   If prompt is very vague (<8 words, no specifics)
+    *   Use **AskUserQuestion** to clarify:
+
+```typescript
+AskUserQuestion({
+  questions: [{
+    header: "Clarify",
+    question: "The prompt is ambiguous. What would you like me to focus on?",
+    multiSelect: false,
+    options: [
+      { label: "Add more detail", description: "I'll provide more context" },
+      { label: "Execute as-is", description: "Apply basic XML structure and proceed" },
+      { label: "Cancel", description: "Skip prompt improvement" }
+    ]
+  }]
+});
+```
+
+5.  **Execute:**
+    *   **EXECUTE ONLY THE IMPROVED PROMPT.**
+    *   Act as if the user entered the improved XML prompt directly.
+
+## Reference Library
+
+*   **Core XML:** [references/xml_core.md](references/xml_core.md) - Basic XML structure and semantic tags
+*   **Multishot:** [references/multishot.md](references/multishot.md) - Adding concrete examples
+*   **Chain of Thought:** [references/chain_of_thought.md](references/chain_of_thought.md) - Thinking space for analysis
+*   **Tool Definitions:** [references/mcp_definitions.md](references/mcp_definitions.md) - MCP tool structure
+*   **Analysis Frameworks:** [references/analysis_commands.md](references/analysis_commands.md) - Structured analysis

package/.xtrm/skills/default/prompt-improving/references/analysis_commands.md

@@ -0,0 +1,24 @@
+# Analysis Frameworks
+
+## When to Use
+When the user wants to perform a deep dive analysis (e.g., "analyze employment data", "review logs").
+
+## Structure
+```xml
+<analysis_task>
+  <requirements>
+    <data>Required inputs.</data>
+    <format>Input format.</format>
+  </requirements>
+  <instructions>
+    1. Step 1
+    2. Step 2
+  </instructions>
+  <outputs>
+    <output_1>Executive Summary</output_1>
+    <output_2>Detailed Findings</output_2>
+  </outputs>
+  <!-- Always include CoT for analysis -->
+  <thinking>...</thinking>
+</analysis_task>
+```