@crafter/cli-tree 0.1.0

package/skill/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: clitree
+description: Explore and map any CLI tool deeply. Parses --help trees, mines the user's shell history for repeated workflows, and uses your own knowledge as the coding agent to surface hidden flags and canonical patterns — validating every finding against the real CLI so nothing is hallucinated. Use this proactively whenever the user wants to understand a CLI more deeply than --help alone, asks about workflows they could automate from their shell history, mentions hidden/undocumented flags, wants to skillify repeated commands, or explores an unfamiliar tool like docker/kubectl/stripe/bun/gh. Also triggers on explicit invocations like "/clitree docker", "/clitree git", or asks like "map docker fully", "what git workflows do I repeat", "what can I automate from my history", "deep dive into kubectl".
+---
+
+# clitree — CLI Archaeology
+
+You help the user understand a command-line tool by combining three sources:
+
+1. **`--help` parsing** — what's documented
+2. **Shell history mining** — what the user actually does
+3. **Your own knowledge + validation** — hidden/undocumented/canonical patterns, verified against the real binary
+
+You're not just running a tool. You're acting as an **archaeologist**: proposing hypotheses from your training knowledge, then excavating the real CLI to confirm or reject them. Hallucinations are the #1 failure mode, so every proposed flag gets validated before making it into the report.
+
+## Why this exists
+
+`--help` is shallow. Users don't know what they don't know. They run the same 4 git commands every day and never discover `--fixup`. They learn docker from one tutorial and miss `--platform` or `--gpus`. They install kubectl and stare at 106 commands with no idea where to start.
+
+This skill fixes that by producing a personalized report: *"here's the tool, here's how YOU use it, here's what you're missing, here's what you could automate."*
+
+## The pipeline
+
+All phases run in sequence. Each phase's output feeds the next.
+
+```
+[1] parse --help        → documented tree
+[2] mine shell history  → usage patterns + workflow suggestions
+[3] propose (you)       → hidden flags + canonical workflows
+[4] validate (code)     → run --help / man to confirm proposals
+[5] render report       → full picture
+```
+
+Phase 3 is your unique contribution as the agent. Phases 1, 2, 4 are handled by the cli-tree library — you just call it.
+
+## Setup
+
+The skill depends on a local install of the `cli-tree` library. On installation, the install script substitutes the real path into this file:
+
+```bash
+CLITREE_LIB=CLITREE_LIB_PATH
+```
+
+At the start of every run, verify setup:
+
+```bash
+test -d "$CLITREE_LIB" && which bun && which "$TARGET_BINARY"
+```
+
+If any check fails, explain what's missing and stop. Don't try to guess paths — tell the user clearly.
+
+## Phase 1 — Parse the --help tree
+
+```bash
+cd "$CLITREE_LIB" && bun src/cli.ts "$TARGET_BINARY" --format json --depth 2
+```
+
+Read the JSON. Note: total commands, top subcommands, total flags. This gives you the documented surface area.
+
+If the parse fails completely (empty output, error), try:
+- `$TARGET_BINARY help --help`
+- `$TARGET_BINARY -h`
+- `man $TARGET_BINARY` as last resort
+
+## Phase 2 — Mine shell history
+
+```bash
+cd "$CLITREE_LIB" && bun src/cli.ts mine "$TARGET_BINARY" --format json
+```
+
+Read the result. You get:
+- `stats.totalInvocations` — how much the user uses this CLI
+- `stats.topSubcommands` — their most-used commands
+- `workflows` — sequences that repeat (≥3 times)
+- `suggestions` — candidate skills to create
+
+Three scenarios from the invocation count:
+
+| Invocations | What it means | What to do |
+|---|---|---|
+| `> 50` | Heavy user, rich signal | Use real workflows as ground truth |
+| `10–50` | Casual user | Present workflows tentatively, augment with canonical patterns |
+| `< 10` | New tool, no signal | Skip mined workflows, present canonical patterns from your knowledge |
+
+## Phase 3 — Archaeology (your part)
+
+This is where you earn your keep. For the top 5 most-used subcommands (or the 5 most interesting commands if history is sparse), think:
+
+**"What exists for this command that the user doesn't see in `--help`?"**
+
+Categories to hunt for:
+- **Hidden flags** — work but undocumented (e.g. `docker run --gpus`, `git commit --fixup`)
+- **Experimental flags** — gated, marked as experimental in source
+- **Deprecated flags** — still functional, hidden from new docs
+- **Man-page-only flags** — visible in `man <cli>` but not `<cli> --help`
+- **Canonical workflows** — patterns that aren't in any help but every experienced user knows (e.g. `git stash → pull → stash pop`)
+
+Only propose things you're **confident** about (>70%). Your training contains blog posts, PRs, issues, source code — draw on the signal, not guesses. Omit rather than invent.
+
+For detailed prompt templates that help you think through each category systematically, read `references/archaeology-guide.md`.
+
+## Phase 4 — Validate every proposal
+
+This is the step that separates archaeology from hallucination. For each flag you propose, verify it exists:
+
+```bash
+# Primary check: is it in --help?
+"$TARGET_BINARY" "$SUBCOMMAND" --help 2>&1 | grep -E "(--<flag>|-<short>\\b)"
+
+# Fallback: man page
+man "$TARGET_BINARY" 2>/dev/null | grep -E "(--<flag>|-<short>\\b)" | head -5
+```
+
+Mark each finding:
+- **`verified`** — appears in `--help`
+- **`verified-by-man`** — not in help, but man confirms
+- **`unconfirmed`** — neither confirms; keep only if you're highly confident AND can explain the evidence (e.g. "shown in docker/docker#12345")
+- **`rejected`** — fail to validate → drop it silently, never include in final output
+
+Better to surface 3 verified flags than 10 unconfirmed ones. **Your credibility is built on rejection rate.** When you mark something unconfirmed, explain why you still believe it.
+
+## Phase 5 — Render the report
+
+Produce this exact structure. Consistency matters — the user learns the shape and scans it quickly on future runs.
+
+```
+# <binary> — archaeology report
+
+## Tree
+<one-line summary: N commands, M flags>
+
+## Your usage
+<from history: invocations, top subcommands, sessions>
+<or: "No usage detected — showing canonical patterns from my knowledge">
+
+## Workflows you repeat
+<from mining — top 5, with frequency>
+<or omit section entirely if no history>
+
+## Hidden / undocumented findings
+✓ --flag-a  (verified) — what it does
+✓ --flag-b  (verified by man) — what it does
+? --flag-c  (unconfirmed) — evidence: "..."
+
+## Canonical workflows
+<from your knowledge — patterns every expert knows>
+<e.g. "git: rebase-interactive → squash → force-with-lease-push">
+
+## Skill suggestions
+<from mining + your analysis>
+💡 /ship — <what it does> — seen N times
+💡 /deploy — <what it does> — seen N times
+```
+
+Five sections, in this order. Omit sections that are empty (no workflows → skip the section, don't write "none found").
+
+After rendering, **offer to create the top skill suggestion**. If the user says yes:
+
+- Write `~/.claude/skills/<name>/SKILL.md` using the template in `references/skill-template.md`
+- Substitute the command sequence from the mined workflow
+- Tell the user the file path and how to invoke it (e.g., "type `/ship` in any conversation")
+
+## Output modes
+
+Support these argument flavors. If the user didn't specify, default to full report.
+
+| Invocation | Behavior |
+|---|---|
+| `/clitree <binary>` | Full report (all 5 sections) |
+| `/clitree <binary> tree` | Only the --help tree, skip mining + archaeology |
+| `/clitree <binary> flows` | Only mined workflows, skip tree + archaeology |
+| `/clitree <binary> suggest` | Only skill suggestions, minimal context |
+| `/clitree <binary> raw` | JSON output, no narrative |
+
+## Principles
+
+These exist because specific failure modes were observed while building the skill. Break them only if you have a specific reason.
+
+- **Validate everything.** Unvalidated LLM proposals poison the output. Always prefer verified over comprehensive.
+- **Mark provenance.** Every finding gets tagged `help`, `history`, `verified`, `verified-by-man`, or `unconfirmed`. The user deserves to know the confidence of each fact.
+- **Fail phase-by-phase.** If phase 1 fails, still run 2. If 2 fails, still run 3. A partial report is more useful than no report.
+- **Be honest about absence.** If the user has 0 shell history for this CLI, say so. Don't fabricate "probable workflows" — use canonical patterns and mark them clearly.
+- **Respect the user's time.** The report should be scannable in 30 seconds. Use the 5-section structure exactly, with short bullets, no prose walls.
+
+## Cache
+
+Archaeology is slow. The library caches enriched trees at `~/.clitree/cache/<binary>.json` with CLI version as part of the key. If the cache is fresh and the user isn't passing `--no-cache`, use it. Version mismatch invalidates automatically.
+
+## Edge cases
+
+- **Binary wraps another** (e.g. `npm` runs `node` scripts) — analyze the wrapper, not the wrapped runtime.
+- **Aliases in history** (`g` for `git`, `k` for `kubectl`) — check the user's shell config if the history seems sparse for a CLI they should be using heavily.
+- **HISTFILE disabled or empty** — skip phase 2 gracefully, say so in the report.
+- **Binary not found** — don't try to install. Tell the user the binary isn't available and suggest `brew install <name>` or equivalent.
+- **Wrapper binaries** (e.g. `docker` is a symlink, `git` uses an extensive system) — run the actual `--help`, the library handles it.
+
+## Examples
+
+### Full report — `/clitree git`
+
+```
+# git — archaeology report
+
+## Tree
+23 top-level commands, 91 documented flags, 3 archaeology findings
+
+## Your usage
+1,257 invocations across 483 sessions
+Top commands: commit (277), checkout (237), push (183), add (167), pull (124)
+
+## Workflows you repeat
+1. add → commit → push       (64×)
+2. checkout → pull           (38×)
+3. stash → pull → stash pop  (12×)
+
+## Hidden / undocumented findings
+✓ --no-verify       (verified)       — skip pre-commit hooks
+✓ commit --fixup=<ref>  (verified by man) — create a fixup commit for rebase
+? push --force-with-lease (unconfirmed) — safer force push, confirmed in git docs but not in this version's --help
+
+## Canonical workflows
+• rebase-interactive → squash → force-with-lease-push   (clean up feature branch)
+• bisect start → good → bad → reset                     (find regressions)
+• worktree add → cd → work → worktree remove            (parallel branches)
+
+## Skill suggestions
+💡 /ship — git add + commit + push   seen 64 times — create this skill? [y/n]
+```
+
+### Sparse history — `/clitree kubectl`
+
+```
+# kubectl — archaeology report
+
+## Tree
+106 commands, 787 documented flags
+
+## Your usage
+No usage detected in shell history — showing canonical patterns instead.
+
+## Canonical workflows
+• deploy        : apply → rollout status → logs
+• debug pod     : get → describe → logs → exec
+• scale         : scale → get → top
+
+## Hidden / undocumented findings
+✓ get -o=custom-columns  (verified) — pick exact columns to show
+✓ logs --since-time      (verified by man) — logs after a timestamp
+? drain --delete-emptydir-data (unconfirmed) — known safe in v1.24+
+
+## Skill suggestions
+No suggestions — no repeated usage detected yet.
+```
+
+## Follow-up behavior
+
+After the user sees the report, they'll often ask:
+- *"Create the /ship skill"* → write `~/.claude/skills/ship/SKILL.md` per `references/skill-template.md`
+- *"Tell me more about --fixup"* → run `git help commit` or `man git-commit | grep -A5 fixup`
+- *"Do this for docker too"* → re-run the pipeline with the new binary
+- *"Show me just the workflows"* → re-run with `flows` mode
+
+Handle these inline without making the user re-invoke the skill.

package/skill/evals/evals.json

@@ -0,0 +1,26 @@
+{
+  "skill_name": "clitree",
+  "evals": [
+    {
+      "id": 0,
+      "name": "direct-git",
+      "prompt": "/clitree git",
+      "expected_output": "A 5-section archaeology report for git: tree summary, shell history usage, repeated workflows (add→commit→push should appear), hidden findings with verified status, canonical workflows, and skill suggestions (ship or similar) — matching the exact section order and naming in the skill spec.",
+      "files": []
+    },
+    {
+      "id": 1,
+      "name": "indirect-bun",
+      "prompt": "I've been using bun a ton lately and I feel like I'm typing the same 3 commands over and over. Is there any pattern I could turn into a one-shot skill? I want you to actually look at what I'm doing, not guess.",
+      "expected_output": "The skill should trigger without /clitree being mentioned. The agent should (1) recognize this is a job for clitree, (2) run the pipeline against bun, (3) produce the full report, (4) identify the repeated bun workflows from shell history (install → dev or similar), (5) offer to create a skill from the top suggestion.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "name": "unknown-stripe",
+      "prompt": "I just installed the stripe CLI. Can you help me understand everything it can do — including hidden or advanced stuff I wouldn't get from just running `stripe --help`?",
+      "expected_output": "The agent should trigger clitree, detect that shell history has little or no stripe usage, skip the 'workflows you repeat' section, produce canonical workflows from training knowledge, and surface hidden/advanced findings with validation against the real binary. No hallucinated commands.",
+      "files": []
+    }
+  ]
+}

package/skill/install.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# Detect the coding agent config dir
+AGENT_DIRS=(
+  "$HOME/.claude/skills"
+  "$HOME/.cursor/skills"
+  "$HOME/.config/codex/skills"
+)
+
+TARGET=""
+for dir in "${AGENT_DIRS[@]}"; do
+  if [ -d "$(dirname "$dir")" ]; then
+    TARGET="$dir/clitree"
+    break
+  fi
+done
+
+if [ -z "$TARGET" ]; then
+  echo "Error: could not detect a coding agent config directory."
+  echo "Tried: ${AGENT_DIRS[*]}"
+  exit 1
+fi
+
+mkdir -p "$TARGET"
+
+# Copy SKILL.md with CLITREE_LIB_PATH substituted
+sed "s|CLITREE_LIB_PATH|$REPO_ROOT|g" "$SCRIPT_DIR/SKILL.md" > "$TARGET/SKILL.md"
+
+# Copy helper scripts
+cp "$SCRIPT_DIR"/*.ts "$TARGET/" 2>/dev/null || true
+
+echo "✓ clitree skill installed at: $TARGET"
+echo ""
+echo "Try it with: /clitree git"

package/skill/references/archaeology-guide.md

@@ -0,0 +1,157 @@
+# Archaeology guide — prompt templates for each phase
+
+Read this when you're doing phase 3 (archaeology) and need structured help thinking through flag discovery.
+
+## When to use this file
+
+- You just ran phases 1 and 2 and have the --help tree + mining results
+- You're about to propose hidden/undocumented flags for the top subcommands
+- You want a mental checklist to avoid missing categories of findings
+
+## Phase 3a — Hidden flag hunt
+
+For each of the top 5 subcommands, run through this mental checklist:
+
+### Question 1: What does this command do in one sentence?
+
+Write it in your head. If you can't, look up `<cli> <sub> --help`. This grounds you.
+
+### Question 2: What are the 3 most common real-world use cases?
+
+Think about blog posts, tutorials, and Stack Overflow answers you've seen. For each use case, what flags does it typically use?
+
+### Question 3: What flags would an expert use that a beginner wouldn't?
+
+- Performance: `-j`, `--parallel`, `--workers`
+- Safety: `--dry-run`, `--no-verify`, `--force-with-lease`
+- Debug: `--verbose`, `--trace`, `--debug`
+- Power: `--interactive`, `--patch`, `--amend`
+
+### Question 4: What's been added recently?
+
+Newer flags often aren't in `--help` well. Check: has this CLI had a major release in the last year? Are there known flags from the release notes?
+
+### Question 5: What's been deprecated?
+
+Still-functional but hidden flags are goldmines. Check your memory for "the old way to do X".
+
+### Output format for proposals
+
+For each subcommand, produce a block like:
+
+```json
+{
+  "subcommand": "<name>",
+  "proposedFlags": [
+    {
+      "name": "flag-name",
+      "short": "f",
+      "type": "boolean|string|number|enum",
+      "description": "<one line>",
+      "confidence": 0.85,
+      "evidence": "source-code|blog|official-docs|man-page|pr-thread|personal-experience",
+      "category": "hidden|experimental|deprecated|man-only|power-user"
+    }
+  ]
+}
+```
+
+Skip flags with confidence < 0.7. Empty proposals are fine — don't pad.
+
+## Phase 3b — Canonical workflow hunt
+
+This is different from mined workflows (phase 2). Mined workflows come from the user's shell history. Canonical workflows come from your training knowledge — they're patterns every expert knows, even if the user has never run them.
+
+### Categories of canonical workflows
+
+For each CLI, think about workflows in these categories:
+
+1. **Bootstrap** — how you start using the tool from scratch
+2. **Daily driver** — the 3-4 commands that make up 80% of expert usage
+3. **Cleanup / hygiene** — commands experts run periodically
+4. **Recovery** — commands for when things go wrong
+5. **Power user** — non-obvious combos that unlock significant productivity
+
+### Example — git
+
+| Category | Workflow |
+|---|---|
+| Bootstrap | `init → add → commit → remote add → push -u` |
+| Daily driver | `add → commit → push` |
+| Cleanup | `fetch --prune → branch -d <merged>` |
+| Recovery | `reflog → reset --hard <sha>` |
+| Power user | `rebase -i → squash → force-with-lease` |
+
+### Example — docker
+
+| Category | Workflow |
+|---|---|
+| Bootstrap | `pull → run → exec` |
+| Daily driver | `build → run` |
+| Cleanup | `system prune -a` |
+| Recovery | `logs → inspect → exec` |
+| Power user | `buildx build --platform linux/amd64,linux/arm64 --push` |
+
+### Rules for canonical workflows
+
+- Only include patterns you're confident are canonical (seen in multiple independent sources)
+- Omit workflows specific to one framework/ecosystem unless it's mainstream
+- Keep to 3-5 workflows per CLI, not an exhaustive list
+- Order by how frequently an expert would use them
+
+## Phase 3c — Flag constraint hunt
+
+Last, think about interactions between flags. Which flags:
+
+- Are **mutually exclusive** (can't use together)?
+- **Require** another flag?
+- **Imply** another flag?
+
+These rarely appear in `--help`. They come from source code comments, issue threads, or trial and error.
+
+Example for `docker run`:
+- `--detach` and `--interactive` → mutually exclusive (one is fg, one is bg)
+- `--gpus` → requires `--runtime=nvidia` in older versions
+- `--privileged` → implies `--cap-add=ALL`
+
+Format:
+
+```json
+{
+  "constraints": [
+    {
+      "type": "mutually-exclusive|requires|implies",
+      "flags": ["--flag-a", "--flag-b"],
+      "description": "<human explanation>",
+      "confidence": 0.9
+    }
+  ]
+}
+```
+
+Only include high-confidence constraints. Uncertain → omit.
+
+## Validation workflow
+
+After you have proposals from 3a/3b/3c, validate them in this order:
+
+1. **Flags from 3a** — highest value, highest hallucination risk. Run:
+   ```bash
+   <cli> <sub> --help 2>&1 | grep -E "(--<flag>|-<short>\b)"
+   ```
+   If no match, try man page:
+   ```bash
+   man <cli> 2>/dev/null | grep -A2 -E "(--<flag>|-<short>\b)" | head -10
+   ```
+
+2. **Workflows from 3b** — these don't need validation; they're composed of commands that already validated in phase 1.
+
+3. **Constraints from 3c** — hardest to validate programmatically. Mark as `unconfirmed` unless you have specific evidence.
+
+## Common mistakes to avoid
+
+- **Listing `--help` / `-h` as hidden** — it's not. Every tool has it.
+- **Listing flags that are in `--help` but you missed reading** — always read the help output carefully before proposing.
+- **Proposing flags from a different CLI** — `docker -v` and `git -v` both exist but mean different things. Be precise.
+- **Confusing subcommands with flags** — `docker ps -a` uses flag `-a`, not subcommand `a`.
+- **Outdated flags** — a flag that existed in `git 1.x` may have been removed in `2.x`. When possible, check `<cli> --version` and match your knowledge to that major version.

package/skill/references/skill-template.md

@@ -0,0 +1,120 @@
+# Template for skills generated from clitree workflow detection
+
+When the user accepts a skill suggestion from clitree, write a new SKILL.md file using this template.
+
+## File location
+
+```
+~/.claude/skills/<name>/SKILL.md
+```
+
+## Template
+
+```markdown
+---
+name: <name>
+description: <one-line description>. Use when the user says "/<name>" or asks to <action verb that captures the workflow>.
+---
+
+# <name>
+
+<one-paragraph description of what this skill automates and why it exists>
+
+## The workflow
+
+This skill automates this sequence:
+
+```bash
+<command 1>
+<command 2>
+<command 3>
+```
+
+## When to trigger
+
+- User types `/<name>`
+- User asks "<natural phrasing 1>"
+- User asks "<natural phrasing 2>"
+
+## Steps
+
+When invoked, run these commands in order. Stop and ask the user if any step is ambiguous.
+
+1. **<step 1 name>** — `<command>`
+2. **<step 2 name>** — `<command>`
+3. **<step 3 name>** — `<command>`
+
+## Error handling
+
+- If step 1 fails, explain to the user what went wrong and don't proceed.
+- If any step produces unexpected output, show it to the user and ask before continuing.
+
+## Provenance
+
+Created by clitree on <YYYY-MM-DD>.
+Based on a sequence seen <N> times in the user's shell history (confidence: <support/total>).
+```
+
+## Example — generated /ship skill
+
+```markdown
+---
+name: ship
+description: Stage all changes, commit with a message, and push in one step. Use when the user says "/ship" or asks to "commit and push", "ship this", "push the latest", or describes finishing a piece of work.
+---
+
+# ship
+
+Automates the git add → commit → push sequence that you repeat frequently.
+
+## The workflow
+
+```bash
+git add .
+git commit -m "<message>"
+git push
+```
+
+## When to trigger
+
+- User types `/ship`
+- User asks "commit and push this"
+- User says "ship it"
+- User asks to "push my latest changes"
+
+## Steps
+
+1. **Check for changes** — `git status --porcelain` (if empty, tell the user there's nothing to ship and stop)
+2. **Stage** — `git add .`
+3. **Commit** — ask the user for a commit message, then `git commit -m "<message>"`
+4. **Push** — `git push` (if no upstream is set, run `git push -u origin HEAD` instead)
+
+## Error handling
+
+- If there are no changes, say so and stop.
+- If the commit fails (e.g., pre-commit hook), show the error and don't push.
+- If push is rejected (diverged branch), show the error and suggest `git pull --rebase` but don't run it automatically.
+
+## Provenance
+
+Created by clitree on 2026-04-10.
+Based on a sequence seen 64 times in shell history (confidence: 64/1257 = 5.1% of all git usage).
+```
+
+## Fields to customize
+
+When generating a skill, fill in:
+
+- `<name>` — short, snake-case or kebab-case (e.g. `ship`, `push-latest`, `deploy-web`)
+- `<description>` — one line, "Use when..." part is critical for triggering
+- `<command N>` — the actual shell commands from the mined workflow
+- `<natural phrasing>` — 2-3 ways the user might ask for this
+- `<YYYY-MM-DD>` — today's date
+- `<N>` — the number of times this sequence appeared in history
+
+## Principles
+
+- **Always include "When to trigger"** — this is how Claude decides to invoke the skill
+- **Error handling matters** — users hate skills that blow through failures
+- **Be honest about provenance** — users should know the skill came from their own usage, not from canned templates
+- **Keep it minimal** — a skill with 3 clear steps beats one with 20 configurations