xtrm-tools 0.5.36 → 0.5.38

package/plugins/xtrm-tools/skills/xt-end/SKILL.md

@@ -4,125 +4,265 @@ description: |
   Autonomous session close flow for xt worktree sessions. Use this skill whenever
   the user says "done", "finished", "wrap up", "close session", "ship it", "I'm done",
   "ready to merge", or similar. Also activate when all beads issues in the session
-  are closed, or when the user explicitly runs /xt-end. This skill guides the agent
-  through pre-flight checks, commit cleanup, PR creation via 'xt end', conflict
-  resolution, and worktree cleanup — handling every edge case so the agent doesn't
-  need to figure it out from scratch.
+  are closed, or when the user explicitly runs /xt-end. This skill is designed for
+  headless/specialist use: it must make deterministic decisions, auto-remediate common
+  anomalies, and avoid clarification questions unless execution is truly blocked.
 ---
 
-# xt-end — Session Close Flow
+# xt-end — Autonomous Session Close Flow
 
-You are closing an `xt` worktree session. The canonical CLI is `xt end`, but it has preconditions you need to satisfy first. Work through these stages in order.
+You are closing an `xt` worktree session. The canonical CLI is `xt end`, but you must normalize the session first and automatically handle common anomalies.
 
-## Stage 1 — Pre-flight: close all open work
+## Operating Mode
+
+Default to **autonomous execution**:
+- do not ask the user routine clarification questions
+- prefer deterministic fallbacks over conversational review
+- only stop when a real blocker prevents safe progress
+
+## Success States
+
+Use these mental result classes while operating:
+- `SUCCESS_PR_CREATED`
+- `SUCCESS_PR_CREATED_WITH_WARNINGS`
+- `BLOCKED_UNCLOSED_SESSION_WORK`
+- `BLOCKED_NO_COMMITS`
+- `BLOCKED_AUTH`
+- `BLOCKED_CONFLICTS`
+- `BLOCKED_DIRTY_UNCLASSIFIED_CHANGES`
+
+---
+
+## Stage 1 — Session Work Audit
 
 Run:
 ```bash
 bd list --status=in_progress
 bd list --status=open
+git log --oneline @{upstream}..HEAD 2>/dev/null || git log --oneline origin/main..HEAD 2>/dev/null || git log --oneline
 ```
 
-If any issues are still open or in_progress, **do not proceed**. Guide the user to finish them first:
-- For in-progress work: complete it, then `bd close <id> --reason "what was done"`
-- For open issues that won't be done in this session: ask the user — close as deferred, or leave for next session?
+Rules:
+- **Block** on `in_progress` issues
+- **Do not block** on unrelated open backlog issues
+- infer **session-touched issues** from commit messages and recent session work
+- if a touched issue is still not closed, close it if the work is complete; otherwise stop with `BLOCKED_UNCLOSED_SESSION_WORK`
 
-Only continue when `bd list --status=in_progress` returns empty (or the user explicitly says to skip unfinished issues).
+This skill is stricter about unfinished session work than about unrelated backlog.
 
-## Stage 2 — Uncommitted changes
+---
 
+## Stage 2 — Tree Normalization
+
+Run:
 ```bash
-git status
+git status --short
 ```
 
-If the working tree is dirty:
-- If the changes belong to a beads issue you just closed: `git add -A && git commit -m "<close_reason> (<id>)"` (or a descriptive summary)
-- If the changes are unrelated WIP: consider stashing with `git stash` and noting what was stashed
-- Never run `xt end` with a dirty working tree — it will abort with an error
+If clean, continue.
 
-## Stage 3 — Dry run (preview the PR)
+If dirty:
+- if the changes clearly belong to the just-finished session work, commit them automatically
+- if they look like unrelated WIP, stash them with a labeled stash message
+- never run `xt end` with a dirty tree
 
+Preferred automatic actions:
+```bash
+git add -A && git commit -m "<descriptive summary> (<issue-id>)"
+# or
+
+git stash push -m "xt-end:auto-stash before session close"
+```
+
+If changes cannot be classified safely, stop with `BLOCKED_DIRTY_UNCLASSIFIED_CHANGES`.
+
+---
+
+## Stage 3 — Dry Run and Anomaly Detection
+
+Run:
 ```bash
 xt end --dry-run
 ```
 
-This shows the PR title, body, files changed, and issues that will be linked. Review with the user:
-- Does the PR title accurately reflect the work?
-- Are all the right issues captured?
-- Is the scope correct?
+Parse the preview and check for anomalies:
+
+### A. Generic PR title
+Treat these as invalid:
+- `session changes`
+- `update`
+- `updates`
+- `misc`
+- `wip`
+- `work in progress`
+
+Auto-remediation:
+- prefer closed issue titles from this session
+- otherwise infer from changed files / dominant area
+- examples:
+  - `Add docs cross-check command and tests`
+  - `Integrate docs workflow with sync-docs`
+  - `Update docs workflow and CLI help`
+
+### B. Missing beads linkage
+If dry-run says no beads issues were found, but commit messages contain issue-like IDs, treat that as a tooling mismatch.
+
+Auto-remediation:
+- extract issue IDs directly from commit messages
+- continue with those IDs as manually inferred linkage
+- report the mismatch in the final summary
+
+### C. Generated artifacts in scope
+If files like `dist/` are included:
+- keep them if the repo conventionally commits built artifacts
+- otherwise revert them before continuing
+
+Use repository history/common practice as the heuristic; do not ask.
+
+### D. Overscoped PR
+Classify the PR scope into buckets:
+- source
+- tests
+- docs
+- skills
+- generated artifacts
+
+If all buckets support one coherent feature/change, continue.
+If they look unrelated, continue but mark the PR as `WITH_WARNINGS` and mention overscope in the final report.
+
+After auto-remediating anomalies, re-run:
+```bash
+xt end --dry-run
+```
 
-If something looks wrong, adjust (e.g., add a missing commit message or close a forgotten issue) and re-run the dry run.
+Repeat until the preview is acceptable or a hard blocker appears.
 
-## Stage 4 — Run xt end
+---
+
+## Stage 4 — No-Commit / Session-Sanity Gate
 
+Before actual execution, ensure the branch really has changes:
 ```bash
-xt end
+git log --oneline @{upstream}..HEAD 2>/dev/null || git log --oneline origin/main..HEAD 2>/dev/null
 ```
 
-### If it succeeds
-You'll see:
-- ✓ Rebased onto origin/<default-branch>
-- ✓ Pushed branch
-- ✓ PR created: <url>
-- ✓ Linked PR to N issue(s)
+If there are no commits ahead of base, stop with `BLOCKED_NO_COMMITS`.
 
-Capture the PR URL for Stage 6.
+---
 
-### If rebase conflicts occur
+## Stage 5 — Run xt end
 
-`xt end` will abort cleanly with a list of conflicted files. Guide the agent through:
+Run:
+```bash
+xt end --yes
+```
+
+Use non-interactive mode by default for autonomous execution.
 
+### If it succeeds
+Capture:
+- rebase success
+- push success
+- PR URL
+- linked issue count
+
+### If rebase conflicts occur
+Run:
+```bash
+git status
+```
+
+Resolve all conflict markers, then:
 ```bash
-git status                          # see conflicted files
-# Edit each conflicted file to resolve <<<< ==== >>>> markers
 git add <resolved-files>
 git rebase --continue
+xt end --yes
 ```
 
-Then re-run `xt end`. If the conflicts are complex, explain what each file conflict is about before resolving.
-
-### If the push fails
+If conflicts are too complex to resolve safely, stop with `BLOCKED_CONFLICTS`.
 
-Usually a stale remote ref. Try:
+### If push fails
+Try:
 ```bash
 git fetch origin
-xt end
+xt end --yes
+```
+
+### If `gh` auth fails
+Stop with `BLOCKED_AUTH` and report:
+```bash
+gh auth login
 ```
 
-## Stage 5 — Worktree cleanup
+---
 
-After a clean PR creation, ask the user:
+## Stage 6 — Autonomous Cleanup
 
-> "PR is open at <url>. Should I remove this worktree? (Recommended: yes, since the branch is pushed and the PR is open. Keep only if you plan to do follow-up work here.)"
+Default behavior: **remove the worktree automatically** after a successful PR creation.
 
-Default recommendation: **remove** (the branch is safe on remote, the worktree is just disk space).
+Rationale:
+- branch is pushed
+- PR is open
+- worktree is disposable local state
 
-If removing:
+If cleanup is needed after `xt end --yes`:
 ```bash
-xt end --keep   # was already run; use git worktree remove directly
 git worktree remove <path> --force
 ```
 
-Or if `xt end` was run interactively, it already prompted for this — just confirm.
+Keep the worktree only if an explicit keep policy exists (for example, known immediate follow-up work on the same branch).
+
+---
 
-## Stage 6 — Report
+## Stage 7 — Final Report
 
-Tell the user:
+Always report:
+- final result class (`SUCCESS_PR_CREATED` or `SUCCESS_PR_CREATED_WITH_WARNINGS`)
 - PR URL
-- Which issues were linked
-- Reminder: "Monitor CI — merge when green. No auto-merge."
+- linked or inferred issues
+- whether anomalies were auto-remediated
+- whether the worktree was removed
+- reminder: monitor CI and merge when green; no auto-merge assumption
 
-If the worktree was removed: confirm that too.
+If linkage had to be inferred from commits rather than detected by `xt end`, say so explicitly.
 
 ---
 
-## Edge cases
+## Edge Cases
+
+**Already on main/master/default branch**
+- stop immediately; this is not an xt worktree session
+
+**No commits yet on branch**
+- stop with `BLOCKED_NO_COMMITS`
+
+**Dirty tree with unclear ownership**
+- stop with `BLOCKED_DIRTY_UNCLASSIFIED_CHANGES`
 
-**Already on main/master branch**: `xt end` will error — you're not in an xt session. Don't run it from the default branch.
+**`gh` not authenticated**
+- stop with `BLOCKED_AUTH`
 
-**No commits yet on branch**: The PR will have no changes. This usually means something went wrong earlier. Verify with `git log origin/<default-branch>..HEAD` (where default-branch is main or master).
+**beads unavailable**
+- continue PR creation if possible
+- infer issues from commit messages when available
+- report linkage as unavailable/manual
 
-**`gh` CLI not authenticated**: `gh pr create` will fail. Fix: `gh auth login`, then re-run `xt end`.
+**Multiple anomalies at once**
+- remediate in order:
+  1. dirty tree
+  2. missing commits
+  3. generic title
+  4. missing issue linkage
+  5. generated artifacts
+  6. overscope warning
 
-**Multiple conflicts**: Resolve all files before `git rebase --continue`. If `git status` shows unmerged paths, keep resolving.
+## Policy Summary
 
-**beads not available**: `xt end` gracefully skips beads linkage if `bd` isn't running. The PR still gets created. Let the user know.
+The autonomous rule is simple:
+- normalize the session
+- dry-run
+- auto-fix predictable anomalies
+- rerun dry-run
+- execute non-interactively
+- clean up automatically
+- stop only on genuine safety blockers

package/skills/sync-docs/SKILL.md

@@ -4,11 +4,12 @@ description: >-
   Doc audit and structural sync for xtrm projects. Use whenever the README
   feels too long, docs are out of sync after a sprint, the CHANGELOG is behind,
   or the user asks to "sync docs", "doc audit", "split readme", "check docs
-  health", or "detect drift". Reads bd issues and git history, then runs
-  docs-only drift detection on README.md, CHANGELOG.md, and docs/ — creating
-  missing focused files instead of a monolithic README.
+  health", or "detect drift". Prefer the xtrm docs command suite (`xtrm docs
+  list`, `xtrm docs show`, `xtrm docs cross-check`) for operator-facing
+  inspection, then use docs-only drift detection on README.md, CHANGELOG.md,
+  and docs/ plus the Python analyzers as validation/backstop tools.
 gemini-command: sync-docs
-version: 1.2.0
+version: 1.3.0
 ---
 
 # sync-docs
@@ -19,18 +20,37 @@ Keeps project documentation in sync with code reality.
 
 ```
 Phase 1: Gather context     — what changed recently?
-Phase 2: Detect docs drift  — which docs/ files are stale?
-Phase 3: Analyze structure  — what belongs outside README?
-Phase 4: Plan + execute     — fix docs and changelog
-Phase 5: Validate           — schema-check all docs/
+Phase 2: Inspect with xtrm  — what does the docs suite already report?
+Phase 3: Detect docs drift  — which docs/ files are stale?
+Phase 4: Analyze structure  — what belongs outside README?
+Phase 5: Plan + execute     — fix docs and changelog
+Phase 6: Validate           — schema-check all docs/
 ```
 
-**Audit vs Execute mode:** If the user asked for an audit/report/check-only task, stop after Phase 3. Only run fixes when the user explicitly asks for changes.
+**Preferred workflow:** use the `xtrm docs` command suite first for human/operator-facing inspection, then use the Python scripts for drift validation, structure analysis, metadata checks, and sync checkpoints.
+
+**Audit vs Execute mode:** If the user asked for an audit/report/check-only task, stop after Phase 4. Only run fixes when the user explicitly asks for changes.
 
 ---
 
 ## Phase 1: Gather Context
 
+Start with the user-facing docs suite so the agent sees the same command surfaces users do:
+
+```bash
+xtrm docs list
+xtrm docs list --json
+xtrm docs show --json
+xtrm docs cross-check --json --days 30
+```
+
+Use these commands for:
+- `xtrm docs list` — inventory docs files, paths, titles, types, and cache-backed scans
+- `xtrm docs show --json` — inspect frontmatter for README, CHANGELOG, and `docs/*.md`
+- `xtrm docs cross-check --json` — gather stale-doc, coverage-gap, and open-issue-ref signals
+
+Then gather deeper repository context if needed:
+
 ```bash
 # Global install
 python3 "$HOME/.agents/skills/sync-docs/scripts/context_gatherer.py" [--since=30]
@@ -47,7 +67,30 @@ Outputs JSON with:
 
 ---
 
-## Phase 2: Detect docs/ Drift
+## Phase 2: Inspect with `xtrm docs`
+
+Treat the CLI docs suite as the primary operator workflow:
+
+```bash
+xtrm docs --help
+xtrm docs list --json
+xtrm docs show --json
+xtrm docs cross-check --json --days 30
+```
+
+Use it to answer:
+- what docs currently exist?
+- which docs have missing or outdated metadata?
+- are there coverage gaps between recent work and docs?
+- do docs reference open issues?
+
+If the xtrm docs suite already isolates the problem clearly, proceed directly to fixes. If you need machine-level drift validation for `docs/*.md`, continue to the Python drift detector.
+
+---
+
+## Phase 3: Detect docs/ Drift
+
+Use the Python detector as the authoritative drift/backstop check for tracked `docs/*.md` pages:
 
 ```bash
 python3 "skills/sync-docs/scripts/drift_detector.py" scan --since 30
@@ -82,7 +125,7 @@ This sets `synced_at` to current HEAD, marking the doc as synced.
 
 ---
 
-## Phase 3: Analyze Document Structure
+## Phase 4: Analyze Document Structure
 
 ```bash
 python3 "skills/sync-docs/scripts/doc_structure_analyzer.py"
@@ -96,11 +139,13 @@ Checks:
 
 Statuses: `BLOATED`, `EXTRACTABLE`, `MISSING`, `STALE`, `INVALID_SCHEMA`, `OK`.
 
-If this is audit-only, stop here and report.
+If this is audit-only, stop here and report. In the report, include both:
+- `xtrm docs` findings (operator-facing)
+- Python analyzer findings (drift/structure enforcement)
 
 ---
 
-## Phase 4: Execute Fixes
+## Phase 5: Execute Fixes
 
 | Situation | Action |
 |---|---|
@@ -131,6 +176,16 @@ python3 "skills/sync-docs/scripts/validate_doc.py" --generate docs/hooks.md \
 python3 "skills/sync-docs/scripts/validate_metadata.py" docs/
 ```
 
+### Re-run xtrm docs suite after fixes
+
+```bash
+xtrm docs list --json
+xtrm docs show --json
+xtrm docs cross-check --json --days 30
+```
+
+Use this pass to confirm the user-facing docs workflow now reflects the repaired state before final validation.
+
 ### Add changelog entry
 
 ```bash
@@ -140,13 +195,20 @@ python3 "skills/sync-docs/scripts/changelog/add_entry.py" \
 
 ---
 
-## Phase 5: Final Validation
+## Phase 6: Final Validation
+
+Run both layers:
 
 ```bash
+xtrm docs list --json
+xtrm docs show --json
+xtrm docs cross-check --json --days 30
 python3 "skills/sync-docs/scripts/validate_doc.py" docs/
 python3 "skills/sync-docs/scripts/drift_detector.py" scan --since 30
 ```
 
+The `xtrm docs` commands confirm the end-user/operator view; the Python tools confirm schema and tracked-doc drift guarantees.
+
 ---
 
 ## Frontmatter Schema
@@ -208,3 +270,17 @@ title: What's New in v2.0
 `docs/` is the only source of truth for project documentation in this workflow.
 Scripts validate `docs/*.md` only — subdirectories (`docs/plans/`, `docs/reference/`) are ignored.
 Use frontmatter (`source_of_truth_for`) to link docs pages to code areas and detect drift.
+
+## Command Selection Rules
+
+Use `xtrm docs` commands first when the task is about understanding the current docs state:
+- `xtrm docs list --json` → inventory and filtering
+- `xtrm docs show --json` → frontmatter inspection
+- `xtrm docs cross-check --json` → recent-work drift, coverage gaps, open issue refs
+
+Use Python scripts when the task is about enforcement or synchronization internals:
+- `drift_detector.py` → `synced_at` / `source_of_truth_for` drift checks for `docs/*.md`
+- `doc_structure_analyzer.py` → README bloat, missing focused docs, changelog version gaps
+- `validate_metadata.py` / `validate_doc.py` → schema/index validation
+
+Do not replace the Python tools with `xtrm docs`; use the CLI for operator-facing inspection and the scripts for authoritative structural validation.

package/skills/using-xtrm/SKILL.md

@@ -19,10 +19,12 @@ priority: high
 ```bash
 bd prime                          # load workflow context + active claims
 bd memories <today's topic>       # retrieve relevant past context
-bd ready                          # find available work
+bv --robot-triage                 # graph-ranked picks, quick wins, unblock targets
 bd update <id> --claim            # claim before any edit
 ```
 
+> Use `bv --robot-next` for the single top pick. Use `bv --robot-triage --format toon` to save context tokens. **Never run bare `bv` — it launches an interactive TUI.**
+
 ---
 
 ## Trigger Patterns
@@ -30,6 +32,7 @@ bd update <id> --claim            # claim before any edit
 | Situation | Action |
 |-----------|--------|
 | User prompt contains `?` | `bd memories <keywords>` before answering — check stored context first |
+| "What should I work on?" | `bv --robot-triage` — ranked picks with dependency context |
 | "What was I working on?" | `bd list --status=in_progress` |
 | Unfamiliar area of code | `gitnexus_query({query: "concept"})` before opening any file |
 | About to edit a symbol | `gitnexus_impact({target: "name", direction: "upstream"})` |