xtrm-tools 0.7.0 → 0.7.1

package/skills/orchestrating-agents/references/agent-context-integration.md

@@ -1,37 +0,0 @@
-# AgentContext Integration
-
-To ensure the response from another agent is correctly ingested by the primary agent, use the `AgentContext` pattern.
-
-## Using `AgentContext`
-
-The `AgentContext` class (located in `hooks/agent_context.py`) provides a unified way to inject `additionalContext` into the agent's reasoning.
-
-### Workflow
-
-1. **Capture Output:** Run the target agent's command and capture stdout to a temporary file.
-   ```bash
-   gemini -p "Analyze this code..." > agent_review.log
-   ```
-
-2. **Inject via Hook:** A hook script can then use `AgentContext` to read this log and provide it back to the primary agent.
-
-### Python Example
-
-```python
-from hooks.agent_context import AgentContext
-
-ctx = AgentContext()
-with open("agent_review.log", "r") as f:
-    review_content = f.read()
-
-ctx.allow(
-    system_message="Review from Gemini agent ingested.",
-    additional_context=f"The other agent provided the following review:
-
-{review_content}"
-)
-```
-
-## Progressive Disclosure
-
-Do not load this entire reference unless the agent is actively setting up a hook or needs detailed implementation specifics for `AgentContext`.

package/skills/orchestrating-agents/references/examples.md

@@ -1,45 +0,0 @@
-# Handshake Examples
-
-These examples demonstrate the correct syntax and flow for orchestrating handshakes between agents.
-
-## Example 1: Code Review Handshake (Qwen)
-
-**Phase 1: Initial Proposal**
-```bash
-qwen "Review the security of this session handling logic: $(cat lib/auth.js)" > review_proposal.txt
-```
-
-**Phase 2: Refinement (Handshake)**
-```bash
-qwen -c "The previous review mentioned a potential race condition. Can you provide a specific code fix for that?" > review_fix.txt
-```
-
-## Example 2: Architecture Discussion (Gemini)
-
-**Phase 1: Initial Proposal**
-```bash
-gemini -p "Analyze the dependency graph for our new 'orchestrating-agents' skill." > arch_proposal.txt
-```
-
-**Phase 2: Refinement (Handshake)**
-```bash
-gemini --resume latest -p "Now, suggest how we could integrate this with the 'delegating' skill without creating a circular dependency." > arch_refinement.txt
-```
-
-## Example 3: Integration via AgentContext
-
-**Ingestion Workflow**
-```python
-from hooks.agent_context import AgentContext
-
-ctx = AgentContext()
-with open("review_fix.txt", "r") as f:
-    content = f.read()
-
-ctx.allow(
-    system_message="Qwen's suggested fix ingested.",
-    additional_context=f"Qwen provided this specific fix:
-
-{content}"
-)
-```

package/skills/orchestrating-agents/references/handover-protocol.md

@@ -1,31 +0,0 @@
-# Handover Protocol
-
-This protocol defines how to "hand off" a task to another agent for a second opinion or specialized review.
-
-## Headless Execution
-
-To interact with other agents without blocking the current session, use headless commands.
-
-### Gemini
-- **Initial Query:** `gemini -p "Your prompt here"`
-- **Follow-up (Resume):** `gemini -r latest -p "Your follow-up here"`
-  - `-r latest` resumes the most recent session
-  - `-r 5` resumes session index 5 (use `gemini --list-sessions` to see available sessions)
-
-### Qwen
-- **Initial Query:** `qwen "Your prompt here"`
-- **Follow-up (Continue):** `qwen -c "Your follow-up here"`
-- **Note:** Qwen uses positional prompts. The `-c` flag automatically resumes the most recent session for the current project.
-
-## Handshaking Strategies
-
-### 1. Standard (2-Phase)
-1. **Proposal**: Send initial context and question to the target agent.
-2. **Refinement**: Use `-r latest` (Gemini) or `-c` (Qwen) to ask for specific corrections or clarifications.
-
-### 2. Deep (Multi-Turn)
-Used for "Design," "Bug Hunt," and "Troubleshoot" workflows.
-1. **Agent A (Draft)**: Request an initial solution or hypothesis.
-2. **Agent B (Audit)**: Pass Agent A's output to Agent B for critique.
-3. **Agent A (Iterate)**: Resume Agent A's session with Agent B's critique using `-r latest` or `-c`.
-4. **Final Synthesis**: Ingest the final result using `AgentContext`.

package/skills/orchestrating-agents/references/workflows.md

@@ -1,42 +0,0 @@
-# Multi-Turn Orchestration Workflows
-
-These workflows define deep, multi-turn interactions between agents for complex scenarios.
-
-## 1. Collaborative Design (`collaborative-design`)
-**Scenario**: Building a new feature or architecting a component.
-
-| Turn | Agent | Action |
-| :--- | :--- | :--- |
-| **1** | **Primary** | Send requirements and initial constraints to Agent A. |
-| **2** | **Agent A** | Propose a high-level design. |
-| **3** | **Primary** | Pipe Agent A's proposal to Agent B. |
-| **4** | **Agent B** | Critique the design for edge cases and complexity. |
-| **5** | **Primary** | Return Agent B's critique to Agent A via `-r latest` (Gemini) or `-c` (Qwen). |
-| **6** | **Agent A** | Refine the design to address critiques. |
-
-## 2. Adversarial Review (`adversarial-review`)
-**Scenario**: Security audits, "red teaming," or finding hidden flaws.
-
-| Turn | Agent | Action |
-| :--- | :--- | :--- |
-| **1** | **Primary** | Send the code/logic to Agent A for a "safe" review. |
-| **2** | **Agent B** | Act as a "Skeptic/Attacker": "Find 3 ways to break this logic." |
-| **3** | **Primary** | Pipe "attacks" to Agent A via `-r latest` (Gemini) or `-c` (Qwen). |
-| **4** | **Agent A** | Defend the logic or provide patches for the identified flaws. |
-
-## 3. Troubleshoot Session (`troubleshoot-session`)
-**Scenario**: "Getting out of trouble," emergency production errors, or ghost bugs.
-
-| Turn | Agent | Action |
-| :--- | :--- | :--- |
-| **1** | **Primary** | Provide symptoms to Agent A and ask for 3 hypotheses. |
-| **2** | **Agent A** | Propose hypotheses and verification steps. |
-| **3** | **Primary** | Ask Agent B to verify Hypothesis #1 using current logs/code. |
-| **4** | **Agent B** | Provide verification result (Confirmed/Refuted). |
-| **5** | **Primary** | Update Agent A with the findings and ask for the final root cause. |
-
-## Automatic Triggering
-The primary agent should suggest these workflows when:
-- **Complexity is high**: Changes affecting >3 files or core infrastructure.
-- **Risk is high**: Security, authentication, or payment logic.
-- **Agent is "stuck"**: When a single-agent approach fails to find a bug.

package/skills/orchestrating-agents/scripts/detect_neighbors.py

@@ -1,23 +0,0 @@
-#!/usr/bin/env python3
-import shutil
-import json
-import sys
-
-def check_command(cmd):
-    return shutil.which(cmd) is not None
-
-def main():
-    agents = ["gemini", "qwen"]
-    found = {agent: check_command(agent) for agent in agents}
-    
-    if any(found.values()):
-        print("Available Agents:")
-        for agent, is_available in found.items():
-            status = "AVAILABLE" if is_available else "NOT FOUND"
-            print(f"- {agent}: {status}")
-    else:
-        print("No neighboring agents (gemini, qwen) found in PATH.")
-        sys.exit(1)
-
-if __name__ == "__main__":
-    main()

package/skills/planning/SKILL.md

@@ -1,405 +0,0 @@
----
-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/skills/planning/evals/evals.json

@@ -1,19 +0,0 @@
-{
-  "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": []
-    }
-  ]
-}