selftune 0.2.8 → 0.2.10

package/skill/SKILL.md

@@ -12,7 +12,7 @@ description: >
   even if they don't say "selftune" explicitly.
 metadata:
   author: selftune-dev
-  version: 0.2.8
+  version: 0.2.10
   category: developer-tools
 ---
 
@@ -104,44 +104,44 @@ selftune cron remove [--dry-run]
 selftune telemetry [status|enable|disable]
 selftune export    [TABLE...] [--output/-o DIR] [--since DATE]
 
-# Alpha enrollment (cloud app is control-plane only, not the main UX)
-selftune init --alpha --alpha-email <email> --alpha-key <st_live_key>
+# Alpha enrollment (device-code flow — browser opens automatically)
+selftune init --alpha --alpha-email <email>
 selftune alpha upload [--dry-run]
 selftune status                                                        # shows cloud link state + upload readiness
 ```
 
 ## Workflow Routing
 
-| Trigger keywords | Workflow | File |
-|------------------|----------|------|
-| grade, score, evaluate, assess session, auto-grade | Grade | Workflows/Grade.md |
-| evals, eval set, undertriggering, skill stats, eval generate | Evals | Workflows/Evals.md |
-| evolve, improve, optimize skills, make skills better, triggers, catch more queries | Evolve | Workflows/Evolve.md |
-| evolve body, evolve routing, full body evolution, rewrite skill, teacher student | EvolveBody | Workflows/EvolveBody.md |
-| evolve rollback, undo, restore, revert evolution, go back, undo last change | Rollback | Workflows/Rollback.md |
-| watch, monitor, regression, post-deploy, keep an eye on | Watch | Workflows/Watch.md |
-| doctor, health, hooks, broken, diagnose, not working, something wrong | Doctor | Workflows/Doctor.md |
-| ingest, import, codex logs, opencode, openclaw, wrap codex | Ingest | Workflows/Ingest.md |
-| replay, backfill, claude transcripts, historical sessions | Replay | Workflows/Replay.md |
-| contribute, share, community, export data, anonymized, give back | Contribute | Workflows/Contribute.md |
-| init, setup, set up, bootstrap, first time, install, configure selftune, alpha, enroll, alpha enrollment, cloud link, upload credential | Initialize | Workflows/Initialize.md |
-| cron, schedule, automate evolution, run automatically | Cron | Workflows/Cron.md |
-| auto-activate, suggestions, activation rules, nag, why suggest | AutoActivation | Workflows/AutoActivation.md |
-| dashboard, visual, open dashboard, show dashboard, serve dashboard, live dashboard | Dashboard | Workflows/Dashboard.md |
-| evolution memory, session continuity, what happened last | EvolutionMemory | Workflows/EvolutionMemory.md |
-| grade baseline, baseline lift, adds value, skill value, no-skill comparison | Baseline | Workflows/Baseline.md |
-| eval unit-test, skill test, test skill, generate tests, run tests | UnitTest | Workflows/UnitTest.md |
-| eval composability, co-occurrence, skill conflicts, skills together | Composability | Workflows/Composability.md |
-| eval import, skillsbench, external evals, benchmark tasks | ImportSkillsBench | Workflows/ImportSkillsBench.md |
-| telemetry, analytics, disable analytics, opt out, tracking, privacy | Telemetry | Workflows/Telemetry.md |
-| orchestrate, autonomous, full loop, improve all skills, run selftune loop | Orchestrate | Workflows/Orchestrate.md |
-| sync, refresh, source truth, rescan sessions | Sync | Workflows/Sync.md |
-| badge, readme badge, skill badge, health badge | Badge | Workflows/Badge.md |
-| workflows, discover workflows, list workflows, multi-skill workflows | Workflows | Workflows/Workflows.md |
-| alpha upload, upload data, send alpha data, manual upload, dry run upload | AlphaUpload | Workflows/AlphaUpload.md |
-| export, dump, jsonl, export sqlite, debug export | Export | *(direct command — no workflow file)* |
-| status, health summary, skill health, how are skills, skills doing, run selftune | Status | *(direct command — no workflow file)* |
-| last, last session, recent session, what happened, what changed | Last | *(direct command — no workflow file)* |
+| Trigger keywords                                                                                                                        | Workflow          | File                                  |
+| --------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------- |
+| grade, score, evaluate, assess session, auto-grade                                                                                      | Grade             | Workflows/Grade.md                    |
+| evals, eval set, undertriggering, skill stats, eval generate                                                                            | Evals             | Workflows/Evals.md                    |
+| evolve, improve, optimize skills, make skills better, triggers, catch more queries                                                      | Evolve            | Workflows/Evolve.md                   |
+| evolve body, evolve routing, full body evolution, rewrite skill, teacher student                                                        | EvolveBody        | Workflows/EvolveBody.md               |
+| evolve rollback, undo, restore, revert evolution, go back, undo last change                                                             | Rollback          | Workflows/Rollback.md                 |
+| watch, monitor, regression, post-deploy, keep an eye on                                                                                 | Watch             | Workflows/Watch.md                    |
+| doctor, health, hooks, broken, diagnose, not working, something wrong                                                                   | Doctor            | Workflows/Doctor.md                   |
+| ingest, import, codex logs, opencode, openclaw, wrap codex                                                                              | Ingest            | Workflows/Ingest.md                   |
+| replay, backfill, claude transcripts, historical sessions                                                                               | Replay            | Workflows/Replay.md                   |
+| contribute, share, community, export data, anonymized, give back                                                                        | Contribute        | Workflows/Contribute.md               |
+| init, setup, set up, bootstrap, first time, install, configure selftune, alpha, enroll, alpha enrollment, cloud link, upload credential | Initialize        | Workflows/Initialize.md               |
+| cron, schedule, automate evolution, run automatically                                                                                   | Cron              | Workflows/Cron.md                     |
+| auto-activate, suggestions, activation rules, nag, why suggest                                                                          | AutoActivation    | Workflows/AutoActivation.md           |
+| dashboard, visual, open dashboard, show dashboard, serve dashboard, live dashboard                                                      | Dashboard         | Workflows/Dashboard.md                |
+| evolution memory, session continuity, what happened last                                                                                | EvolutionMemory   | Workflows/EvolutionMemory.md          |
+| grade baseline, baseline lift, adds value, skill value, no-skill comparison                                                             | Baseline          | Workflows/Baseline.md                 |
+| eval unit-test, skill test, test skill, generate tests, run tests                                                                       | UnitTest          | Workflows/UnitTest.md                 |
+| eval composability, co-occurrence, skill conflicts, skills together                                                                     | Composability     | Workflows/Composability.md            |
+| eval import, skillsbench, external evals, benchmark tasks                                                                               | ImportSkillsBench | Workflows/ImportSkillsBench.md        |
+| telemetry, analytics, disable analytics, opt out, tracking, privacy                                                                     | Telemetry         | Workflows/Telemetry.md                |
+| orchestrate, autonomous, full loop, improve all skills, run selftune loop                                                               | Orchestrate       | Workflows/Orchestrate.md              |
+| sync, refresh, source truth, rescan sessions                                                                                            | Sync              | Workflows/Sync.md                     |
+| badge, readme badge, skill badge, health badge                                                                                          | Badge             | Workflows/Badge.md                    |
+| workflows, discover workflows, list workflows, multi-skill workflows                                                                    | Workflows         | Workflows/Workflows.md                |
+| alpha upload, upload data, send alpha data, manual upload, dry run upload                                                               | AlphaUpload       | Workflows/AlphaUpload.md              |
+| export, dump, jsonl, export sqlite, debug export                                                                                        | Export            | _(direct command — no workflow file)_ |
+| status, health summary, skill health, how are skills, skills doing, run selftune                                                        | Status            | _(direct command — no workflow file)_ |
+| last, last session, recent session, what happened, what changed                                                                         | Last              | _(direct command — no workflow file)_ |
 
 Workflows Grade, Evolve, Watch, and Ingest also run autonomously via `selftune orchestrate`.
 
@@ -155,7 +155,7 @@ tier reference, and quick-path rules.
 
 The core idea: observe how users actually talk, find where skills miss, propose
 better descriptions, validate them, and deploy — with automatic rollback if things
-get worse. Every step produces evidence so you can explain *why* a change was made.
+get worse. Every step produces evidence so you can explain _why_ a change was made.
 
 ```text
 Observe --> Detect --> Diagnose --> Propose --> Validate --> Audit --> Deploy --> Watch --> Rollback
@@ -179,17 +179,22 @@ selftune bundles focused agents in `agents/`. When you need deeper analysis,
 read the relevant agent file and follow its instructions — either inline or
 by spawning a subagent with those instructions as its prompt.
 
+On Claude Code, `selftune init` also syncs compatibility copies into
+`~/.claude/agents/` so native `--agent <name>` calls keep matching these
+bundled definitions.
+
 Treat these as worker-style subagents:
+
 - pass the required inputs from the parent agent
 - expect a structured report back
 - do not have them question the user directly unless you explicitly want that
 
-| Trigger keywords | Agent file | When to use |
-|------------------|-----------|-------------|
-| diagnose, root cause, why failing, debug performance | `agents/diagnosis-analyst.md` | When one skill has recurring low grades, regressions, or unclear failures after basic doctor/status review |
-| patterns, conflicts, cross-skill, overlap, optimize skills | `agents/pattern-analyst.md` | When multiple skills may overlap, misroute, or interfere, especially after composability flags conflict |
-| review evolution, check proposal, safe to deploy | `agents/evolution-reviewer.md` | Before deploying a dry-run or pending proposal, especially for high-stakes skills or marginal improvements |
-| set up selftune, integrate, configure project | `agents/integration-guide.md` | For complex setup and verification work in monorepos, multi-skill repos, or mixed-platform environments |
+| Trigger keywords                                           | Agent file                     | When to use                                                                                                |
+| ---------------------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| diagnose, root cause, why failing, debug performance       | `agents/diagnosis-analyst.md`  | When one skill has recurring low grades, regressions, or unclear failures after basic doctor/status review |
+| patterns, conflicts, cross-skill, overlap, optimize skills | `agents/pattern-analyst.md`    | When multiple skills may overlap, misroute, or interfere, especially after composability flags conflict    |
+| review evolution, check proposal, safe to deploy           | `agents/evolution-reviewer.md` | Before deploying a dry-run or pending proposal, especially for high-stakes skills or marginal improvements |
+| set up selftune, integrate, configure project              | `agents/integration-guide.md`  | For complex setup and verification work in monorepos, multi-skill repos, or mixed-platform environments    |
 
 ## Examples
 
@@ -198,6 +203,7 @@ Treat these as worker-style subagents:
 User says: "Set up selftune" or "Install selftune"
 
 Actions:
+
 1. Read `Workflows/Initialize.md`
 2. Run `selftune init` to bootstrap config (hooks are installed automatically)
 3. Run `selftune doctor` to verify
@@ -209,6 +215,7 @@ Result: Config at `~/.selftune/config.json`, hooks active, ready for session cap
 User says: "Make the pptx skill catch more queries" or "Evolve the Research skill"
 
 Actions:
+
 1. `selftune eval generate --skill pptx` to find missed triggers
 2. `selftune evolve --skill pptx --skill-path <path>` to propose changes
 3. `selftune watch --skill pptx --skill-path <path>` to monitor post-deploy
@@ -220,6 +227,7 @@ Result: Skill description updated to match real user language, with rollback ava
 User says: "How are my skills doing?" or "Run selftune"
 
 Actions:
+
 1. `selftune status` for overall health summary
 2. `selftune last` for most recent session insight
 3. `selftune doctor` if issues detected
@@ -231,6 +239,7 @@ Result: Pass rates, trend data, and actionable recommendations.
 User says: "Set up cron jobs" or "Run selftune automatically"
 
 Actions:
+
 1. `selftune cron setup` to install OS-level scheduling
 2. Orchestrate loop runs: ingest → grade → evolve → watch
 
@@ -245,6 +254,7 @@ Error: `command not found: selftune`
 Cause: CLI not installed or not on PATH.
 
 Solution:
+
 1. Run `npm install -g selftune` or check `bin/selftune.cjs` exists
 2. Verify with `which selftune`
 3. If using bun: `bun link` in the repo root
@@ -256,6 +266,7 @@ Error: `selftune grade` returns empty results.
 Cause: Hooks not capturing sessions, or no sessions since last ingest.
 
 Solution:
+
 1. Run `selftune doctor` to verify hook installation
 2. Run `selftune ingest claude --force` to re-ingest
 3. Check `~/.claude/` for telemetry JSONL files
@@ -265,6 +276,7 @@ Solution:
 Cause: Eval set too small or skill already well-tuned.
 
 Solution:
+
 1. Run `selftune eval generate --skill <name> --max 50` for a larger eval set
 2. Check `selftune status` — if pass rate is >90%, evolution may not be needed
 3. Try `selftune evolve body` for deeper structural changes
@@ -274,6 +286,7 @@ Solution:
 Error: Port already in use or blank page.
 
 Solution:
+
 1. Try a different port: `selftune dashboard --port 3142`
 2. Check if another process holds the port: `lsof -i :3141`
 3. Use `--no-open` to start the server without opening a browser
@@ -285,31 +298,31 @@ share keywords but need different solutions:
 
 - "Fix this React hydration bug" — general debugging, not skill improvement
 - "Create a PowerPoint about Q3 results" — this is pptx skill, not selftune
-- "Run my unit tests" — project tests, not skill eval tests (even though selftune has "eval unit-test", this is about *project* tests)
-- "How do I use the Research skill?" — skill *usage*, not skill *improvement* (route to the Research skill itself)
+- "Run my unit tests" — project tests, not skill eval tests (even though selftune has "eval unit-test", this is about _project_ tests)
+- "How do I use the Research skill?" — skill _usage_, not skill _improvement_ (route to the Research skill itself)
 - "Generate a report from this data" — content generation, not skill evolution
 - "My build is failing" — project issue, not selftune health issue (even though "failing" overlaps with skill diagnostics language)
 - "Evaluate this code for security issues" — "evaluate" here means code review, not session grading
 - "Improve this function's performance" — code optimization, not skill optimization (even though "improve" and "performance" are selftune keywords)
 
-The key distinction: selftune is about improving *skills themselves* (their
+The key distinction: selftune is about improving _skills themselves_ (their
 descriptions, triggers, and execution quality). If the user is trying to
-accomplish a task *using* a skill, route to that skill instead.
+accomplish a task _using_ a skill, route to that skill instead.
 
 ## Resource Index
 
-| Resource | Purpose | When to read |
-|----------|---------|--------------|
-| `SKILL.md` | This file — routing, triggers, quick reference | Always loaded |
-| `Workflows/*.md` | Step-by-step instructions for each workflow | When routing to a workflow |
-| `agents/diagnosis-analyst.md` | Deep-dive skill failure analysis | Spawn when doctor/grades show persistent issues |
-| `agents/pattern-analyst.md` | Cross-skill conflict detection | Spawn when composability flags conflicts |
-| `agents/evolution-reviewer.md` | Safety gate for evolution proposals | Spawn before deploying high-stakes evolutions |
-| `agents/integration-guide.md` | Guided setup for complex projects | Spawn for monorepos, multi-skill setups |
-| `references/logs.md` | Log file formats (telemetry, usage, queries, audit) | When parsing or debugging log files |
-| `references/grading-methodology.md` | 3-tier grading model, evidence standards | When grading sessions or interpreting grades |
-| `references/invocation-taxonomy.md` | 4 invocation types, coverage analysis | When analyzing trigger coverage |
-| `references/interactive-config.md` | Pre-flight config pattern, model tiers | Before running mutating workflows |
-| `references/setup-patterns.md` | Platform-specific setup patterns | During complex setup scenarios |
-| `settings_snippet.json` | Claude Code hook configuration template | During initialization |
-| `assets/*.json` | Config templates (activation rules, settings) | During initialization |
+| Resource                            | Purpose                                             | When to read                                    |
+| ----------------------------------- | --------------------------------------------------- | ----------------------------------------------- |
+| `SKILL.md`                          | This file — routing, triggers, quick reference      | Always loaded                                   |
+| `Workflows/*.md`                    | Step-by-step instructions for each workflow         | When routing to a workflow                      |
+| `agents/diagnosis-analyst.md`       | Deep-dive skill failure analysis                    | Spawn when doctor/grades show persistent issues |
+| `agents/pattern-analyst.md`         | Cross-skill conflict detection                      | Spawn when composability flags conflicts        |
+| `agents/evolution-reviewer.md`      | Safety gate for evolution proposals                 | Spawn before deploying high-stakes evolutions   |
+| `agents/integration-guide.md`       | Guided setup for complex projects                   | Spawn for monorepos, multi-skill setups         |
+| `references/logs.md`                | Log file formats (telemetry, usage, queries, audit) | When parsing or debugging log files             |
+| `references/grading-methodology.md` | 3-tier grading model, evidence standards            | When grading sessions or interpreting grades    |
+| `references/invocation-taxonomy.md` | 4 invocation types, coverage analysis               | When analyzing trigger coverage                 |
+| `references/interactive-config.md`  | Pre-flight config pattern, model tiers              | Before running mutating workflows               |
+| `references/setup-patterns.md`      | Platform-specific setup patterns                    | During complex setup scenarios                  |
+| `settings_snippet.json`             | Claude Code hook configuration template             | During initialization                           |
+| `assets/*.json`                     | Config templates (activation rules, settings)       | During initialization                           |

package/skill/Workflows/AlphaUpload.md

@@ -11,10 +11,10 @@ selftune alpha upload [--dry-run]
 
 ## Flags
 
-| Flag | Meaning | Default |
-|------|---------|---------|
-| `--dry-run` | Stage and summarize the upload without sending the HTTP request | Off |
-| `-h`, `--help` | Show command help | Off |
+| Flag           | Meaning                                                         | Default |
+| -------------- | --------------------------------------------------------------- | ------- |
+| `--dry-run`    | Stage and summarize the upload without sending the HTTP request | Off     |
+| `-h`, `--help` | Show command help                                               | Off     |
 
 ## Behavior
 

package/skill/Workflows/AutoActivation.md

@@ -35,12 +35,12 @@ Detection scans all hook entries in settings for any command containing
 
 ## Default Rules
 
-| Rule ID | Description | Trigger Condition | Suggestion |
-|---------|-------------|-------------------|------------|
-| `post-session-diagnostic` | Suggest diagnostic review | >2 unmatched queries in current session | `selftune last` |
-| `grading-threshold-breach` | Suggest evolution | Session pass rate < 0.6 (60%) | `selftune evolve` |
-| `stale-evolution` | Suggest evolution | >7 days since last evolution AND pending false negatives exist | `selftune evolve` |
-| `regression-detected` | Suggest rollback | Watch snapshot shows `regression_detected: true` | `selftune evolve rollback` |
+| Rule ID                    | Description               | Trigger Condition                                              | Suggestion                 |
+| -------------------------- | ------------------------- | -------------------------------------------------------------- | -------------------------- |
+| `post-session-diagnostic`  | Suggest diagnostic review | >2 unmatched queries in current session                        | `selftune last`            |
+| `grading-threshold-breach` | Suggest evolution         | Session pass rate < 0.6 (60%)                                  | `selftune evolve`          |
+| `stale-evolution`          | Suggest evolution         | >7 days since last evolution AND pending false negatives exist | `selftune evolve`          |
+| `regression-detected`      | Suggest rollback          | Watch snapshot shows `regression_detected: true`               | `selftune evolve rollback` |
 
 ### Rule Details
 
@@ -122,24 +122,29 @@ Delete or comment out the entry to disable all auto-activation suggestions.
 ## Common Patterns
 
 **User wants to disable auto-suggestions**
+
 > Remove the auto-activate hook entry from `~/.claude/settings.json`
 > (see Disabling section above). Each rule fires at most once per session.
 
 **User asks why selftune suggestions appear**
+
 > Explain that the auto-activate hook detected an actionable condition.
 > Parse the suggestion text to identify which rule fired and report the
 > recommended action.
 
 **Suggestions are not appearing when expected**
+
 > Run `selftune doctor` to verify the hook is installed. Check that
 > `UserPromptSubmit` includes the auto-activate hook in settings.
 
 **PAI coexistence conflict**
+
 > Verify PAI's `skill-activation-prompt` hook is in `~/.claude/settings.json`.
 > If present, selftune skips all suggestions automatically. If the user
 > sees duplicates, one of the two hooks is misconfigured.
 
 **User wants custom activation rules**
+
 > Direct the user to `cli/selftune/activation-rules.ts`. New rules must
 > conform to the `ActivationRule` interface: pure filesystem readers with
 > no network calls or heavy imports.

package/skill/Workflows/Badge.md

@@ -16,32 +16,37 @@ selftune badge --skill <name> [--format svg|markdown|url] [--output <path>]
 
 ## Options
 
-| Option | Required | Default | Description |
-|--------|----------|---------|-------------|
-| `--skill` | Yes | -- | Skill name to generate badge for |
-| `--format` | No | `svg` | Output format: `svg`, `markdown`, or `url` |
-| `--output` | No | stdout | Write output to file |
-| `--help` | No | -- | Show usage information |
+| Option     | Required | Default | Description                                |
+| ---------- | -------- | ------- | ------------------------------------------ |
+| `--skill`  | Yes      | --      | Skill name to generate badge for           |
+| `--format` | No       | `svg`   | Output format: `svg`, `markdown`, or `url` |
+| `--output` | No       | stdout  | Write output to file                       |
+| `--help`   | No       | --      | Show usage information                     |
 
 ## Examples
 
 ### Generate SVG badge
+
 ```bash
 selftune badge --skill my-skill --format svg > badge.svg
 ```
 
 ### Get markdown for README
+
 ```bash
 selftune badge --skill my-skill --format markdown
 ```
+
 Output: `![Skill Health: my-skill](https://img.shields.io/badge/Skill%20Health-87%25%20%E2%86%91-4c1)`
 
 ### Get shields.io URL
+
 ```bash
 selftune badge --skill my-skill --format url
 ```
 
 ### Write badge to file
+
 ```bash
 selftune badge --skill my-skill --output badge.svg
 ```
@@ -59,16 +64,17 @@ Markdown and URL formats use shields.io, which renders its own badge — the log
 
 ## Badge Colors
 
-| Pass Rate | Color | Hex |
-|-----------|-------|-----|
-| > 80% | Green | `#4c1` |
-| 60-80% | Yellow | `#dfb317` |
-| < 60% | Red | `#e05d44` |
-| No data | Gray | `#9f9f9f` |
+| Pass Rate | Color  | Hex       |
+| --------- | ------ | --------- |
+| > 80%     | Green  | `#4c1`    |
+| 60-80%    | Yellow | `#dfb317` |
+| < 60%     | Red    | `#e05d44` |
+| No data   | Gray   | `#9f9f9f` |
 
 ## Embedding in README
 
 Add to your skill's README.md:
+
 ```markdown
 ![Skill Health: my-skill](https://img.shields.io/badge/Skill%20Health-87%25%20%E2%86%91-4c1)
 ```
@@ -104,10 +110,10 @@ The hosted badge service at `badge.selftune.dev` aggregates community contributi
 
 ### Endpoints
 
-| Route | Method | Description |
-|-------|--------|-------------|
-| `/badge/:skill` | GET | SVG badge from aggregated community data |
-| `/badge/:org/:skill` | GET | Organization-scoped SVG badge |
+| Route                | Method | Description                              |
+| -------------------- | ------ | ---------------------------------------- |
+| `/badge/:skill`      | GET    | SVG badge from aggregated community data |
+| `/badge/:org/:skill` | GET    | Organization-scoped SVG badge            |
 
 ### Embedding from hosted service
 

package/skill/Workflows/Baseline.md

@@ -7,6 +7,7 @@ improvement in pass rate that the skill provides.
 ## When to Invoke
 
 Invoke this workflow when the user requests any of the following:
+
 - Measuring whether a skill adds value or is worth keeping
 - Comparing skill performance against a no-skill baseline
 - Deciding whether to evolve or rework a skill
@@ -20,12 +21,12 @@ selftune grade baseline --skill <name> --skill-path <path> [options]
 
 ## Options
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--skill <name>` | Skill name | Required |
-| `--skill-path <path>` | Path to the skill's SKILL.md | Required |
-| `--eval-set <path>` | Pre-built eval set JSON | Auto-generated from logs |
-| `--agent <name>` | Agent CLI to use | Auto-detected |
+| Flag                  | Description                  | Default                  |
+| --------------------- | ---------------------------- | ------------------------ |
+| `--skill <name>`      | Skill name                   | Required                 |
+| `--skill-path <path>` | Path to the skill's SKILL.md | Required                 |
+| `--eval-set <path>`   | Pre-built eval set JSON      | Auto-generated from logs |
+| `--agent <name>`      | Agent CLI to use             | Auto-detected            |
 
 ## Output Format
 
@@ -69,36 +70,33 @@ skipped — the skill needs fundamental rework, not description tweaks.
 
 Before running baseline measurement, use the `AskUserQuestion` tool to present structured configuration options.
 
-If the user responds with "use defaults", cancels, or similar shorthand, skip to step 1 using the recommended defaults.
+If the user responds with "use defaults" or similar shorthand, skip to step 1 using the recommended defaults. If the user cancels, stop -- do not proceed with defaults.
 
-Use `AskUserQuestion` with these questions:
+Ask one `AskUserQuestion` at a time in this order:
 
-```json
-{
-  "questions": [
-    {
-      "question": "Eval Set Source",
-      "options": ["Auto-generate from logs (recommended if logs exist)", "Use existing eval set file", "Generate synthetic evals first (for new skills)"]
-    },
-    {
-      "question": "Agent CLI",
-      "options": ["Auto-detect (recommended)", "claude", "codex", "opencode"]
-    }
-  ]
-}
-```
+1. `Eval Set Source`
+   Options:
+   - `Auto-generate from logs (recommended if logs exist)`
+   - `Use existing eval set file`
+   - `Generate synthetic evals first (for new skills)`
+2. `Agent CLI`
+   Options:
+   - `Auto-detect (recommended)`
+   - `claude`
+   - `codex`
+   - `opencode`
 
-If `AskUserQuestion` is not available, fall back to presenting these as inline numbered options.
+If `AskUserQuestion` is not available or Claude does not invoke it, fall back to presenting the same choices as inline numbered options.
 
 After the user responds, parse their selections and map each choice to the corresponding CLI flags:
 
-| Selection | CLI Flag |
-|-----------|----------|
-| 1a (auto-generate) | _(no flag, default)_ |
-| 1b (existing eval set) | `--eval-set <path>` |
-| 1c (synthetic first) | Run Evals workflow with `--synthetic` first, then use output |
-| 2a (auto-detect) | _(no flag, default)_ |
-| 2b (specify agent) | `--agent <name>` |
+| Selection              | CLI Flag                                                     |
+| ---------------------- | ------------------------------------------------------------ |
+| 1a (auto-generate)     | _(no flag, default)_                                         |
+| 1b (existing eval set) | `--eval-set <path>`                                          |
+| 1c (synthetic first)   | Run Evals workflow with `--synthetic` first, then use output |
+| 2a (auto-detect)       | _(no flag, default)_                                         |
+| 2b (specify agent)     | `--agent <name>`                                             |
 
 Show a confirmation summary to the user:
 
@@ -122,12 +120,12 @@ Parse the JSON output and extract `lift` and `adds_value` fields.
 
 ### 2. Interpret Results
 
-| Lift | Interpretation | Action |
-|------|---------------|--------|
-| >= 0.20 | Strong value | Skill is working well |
-| 0.05–0.20 | Moderate value | Consider evolving to improve |
-| < 0.05 | Minimal value | Skill may need rework, not just evolution |
-| < 0 | Negative value | Skill is hurting — investigate or disable |
+| Lift      | Interpretation | Action                                    |
+| --------- | -------------- | ----------------------------------------- |
+| >= 0.20   | Strong value   | Skill is working well                     |
+| 0.05–0.20 | Moderate value | Consider evolving to improve              |
+| < 0.05    | Minimal value  | Skill may need rework, not just evolution |
+| < 0       | Negative value | Skill is hurting — investigate or disable |
 
 Report the interpretation to the user based on the lift value.
 

package/skill/Workflows/Composability.md

@@ -12,11 +12,11 @@ selftune eval composability --skill <name> [options]
 
 ## Options
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--skill <name>` | Skill to analyze | Required |
-| `--window <n>` | Only analyze sessions from last N days | All sessions |
-| `--telemetry-log <path>` | Path to telemetry log | `~/.claude/session_telemetry_log.jsonl` |
+| Flag                     | Description                            | Default                                 |
+| ------------------------ | -------------------------------------- | --------------------------------------- |
+| `--skill <name>`         | Skill to analyze                       | Required                                |
+| `--window <n>`           | Only analyze sessions from last N days | All sessions                            |
+| `--telemetry-log <path>` | Path to telemetry log                  | `~/.claude/session_telemetry_log.jsonl` |
 
 ## Output Format
 
@@ -70,16 +70,17 @@ selftune eval composability --skill Research
 
 ### 2. Interpret Results
 
-| Conflict Score | Interpretation |
-|---------------|---------------|
-| 0.0–0.1 | No conflict — skills work well together |
-| 0.1–0.3 | Minor friction — monitor but no action needed |
-| 0.3–0.6 | Moderate conflict — investigate trigger overlap |
-| 0.6–1.0 | Severe conflict — skills likely interfere with each other |
+| Conflict Score | Interpretation                                            |
+| -------------- | --------------------------------------------------------- |
+| 0.0–0.1        | No conflict — skills work well together                   |
+| 0.1–0.3        | Minor friction — monitor but no action needed             |
+| 0.3–0.6        | Moderate conflict — investigate trigger overlap           |
+| 0.6–1.0        | Severe conflict — skills likely interfere with each other |
 
 ### 3. Address Conflicts
 
 When conflict candidates are identified, present them to the user with recommended actions:
+
 - Check for trigger keyword overlap between the skills
 - Check if one skill's workflow interferes with the other's
 - Consider evolving descriptions to reduce false triggers
@@ -95,13 +96,17 @@ resolution plan with trigger ownership recommendations.
 ## Common Patterns
 
 **"Are there conflicts between my skills?"**
+
 > `selftune eval composability --skill Research`
 
 **"Check composability for recent sessions only"**
+
 > `selftune eval composability --skill pptx --window 7`
 
 **"Which skills conflict with Research?"**
+
 > Run composability and check the `conflict_candidates` array.
 
 **"Why are sessions with multiple skills failing?"**
+
 > Run composability for each skill involved, look for high conflict scores.