selftune 0.2.23 → 0.2.25

package/skill/SKILL.md

@@ -4,50 +4,33 @@ description: >
   Self-improving skills toolkit that watches real agent sessions, detects missed
   triggers, grades execution quality, and evolves skill descriptions to match how
   users actually talk. Use when grading sessions, generating evals, evolving skill
-  descriptions or routing tables, checking skill health, viewing the dashboard,
-  ingesting sessions from other platforms, or running autonomous improvement loops.
+  descriptions or routing tables, discovering reusable workflows, scaffolding new
+  workflow skills, checking skill health, viewing the dashboard, ingesting sessions
+  from other platforms, or running autonomous improvement loops.
   Make sure to use this skill whenever the user mentions skill improvement, skill
   performance, skill triggers, skill evolution, skill health, undertriggering,
   overtriggering, session grading, or wants to know how their skills are doing —
   even if they don't say "selftune" explicitly.
 metadata:
   author: selftune-dev
-  version: 0.2.10
+  version: 0.2.25
   category: developer-tools
 ---
 
 # selftune
 
 Observe real agent sessions, detect missed triggers, grade execution quality,
-and evolve skill descriptions toward the language real users actually use.
+evolve skill descriptions toward the language real users actually use, and
+scaffold workflow skills from repeated telemetry patterns.
 
 **You are the operator.** The user installed this skill so YOU can manage their
 skill health autonomously. They will say things like "set up selftune",
 "improve my skills", or "how are my skills doing?" — and you route to the
 correct workflow below. The user does not run CLI commands directly; you do.
 
-## Why this matters
-
-Skills are only useful when they trigger at the right time with the right
-instructions. But user language drifts — the phrases people use to ask for help
-rarely match the trigger keywords a skill author imagined. selftune closes this
-gap by observing real sessions, finding where skills fail to activate or
-execute poorly, and rewriting descriptions to match actual usage patterns. The
-result: skills that get better over time without manual tuning.
-
-## Communicating with the user
-
-Users range from experienced developers who'll say "evolve the pptx description
-using the latest eval set" to non-technical users who'll say "make my skills
-better". Pay attention to context cues:
-
-- If they use terms like "eval set", "routing table", "JSONL" — match their precision
-- If they say "improve my skills" or "how's it going" — explain what you're doing in plain language, summarize results, and suggest next steps
-- When in doubt, briefly explain what a command does before running it
-
 ## Bootstrap
 
-If `~/.selftune/config.json` does not exist, read `Workflows/Initialize.md`
+If `~/.selftune/config.json` does not exist, read `workflows/Initialize.md`
 first. The CLI must be installed (`selftune` on PATH) before other commands
 will work. Do not proceed with other commands until initialization is complete.
 
@@ -57,143 +40,82 @@ will work. Do not proceed with other commands until initialization is complete.
 selftune <command> [options]
 ```
 
-Commands vary in output format. `selftune orchestrate`, `selftune watch`, and
-`selftune evolve --dry-run` emit structured JSON on stdout. `selftune status`,
-`selftune last`, and `selftune doctor` print human-readable text or structured
-JSON depending on the command. For alpha/bootstrap and health remediation, prefer
-machine-readable `guidance.next_command` or top-level `next_command` when present
-instead of inferring the next step from prose. `selftune dashboard` starts a
-local SPA server — it does not emit data.
+Commands vary in output format:
 
-## Quick Reference
+- **JSON by default:** `selftune doctor` and `selftune watch` emit structured JSON on stdout.
+- **Text by default:** `selftune status`, `selftune last`, `selftune orchestrate`, and `selftune evolve` print human-readable text.
+- **JSON opt-in:** `selftune sync --json` enables structured JSON output.
+- **Server:** `selftune dashboard` starts a local SPA server — it does not emit data.
 
-```bash
-# Ingest group
-selftune ingest claude   [--since DATE] [--dry-run] [--force] [--verbose]
-selftune ingest codex                                                          # (experimental)
-selftune ingest opencode                                                       # (experimental)
-selftune ingest openclaw [--agents-dir PATH] [--since DATE] [--dry-run] [--force] [--verbose]  # (experimental)
-selftune ingest pi       [--sessions-dir PATH] [--since DATE] [--dry-run] [--force] [--verbose]  # (experimental)
-selftune ingest wrap-codex -- <codex args>                                     # (experimental)
-
-# Grade group
-selftune grade auto      --skill <name> [--expectations "..."] [--agent <name>]
-selftune grade baseline  --skill <name> --skill-path <path> [--eval-set <path>] [--agent <name>]
-
-# Evolve group
-selftune evolve          --skill <name> --skill-path <path> [--dry-run]
-selftune evolve body     --skill <name> --skill-path <path> --target <body|routing> [--dry-run]
-selftune evolve rollback --skill <name> --skill-path <path> [--proposal-id <id>]
-
-# Eval group
-selftune eval generate      --skill <name> [--list-skills] [--stats] [--max N] [--seed N] [--output PATH]
-selftune eval unit-test      --skill <name> --tests <path> [--run-agent] [--generate]
-selftune eval import         --dir <path> --skill <name> --output <path> [--match-strategy exact|fuzzy]
-selftune eval composability  --skill <name> [--window N] [--telemetry-log <path>]
-selftune eval family-overlap --prefix <family-> | --skills <a,b,c> [--parent-skill <name>] [--min-overlap 0.3] [--min-shared 2]
-
-# Other commands
-selftune watch    --skill <name> --skill-path <path> [--auto-rollback]
-selftune status
-selftune last
-selftune doctor
-selftune dashboard [--port <port>] [--no-open]
-selftune contributions [status|preview <skill>|upload [--dry-run]|approve <skill>|revoke <skill>|default <ask|always|never>|reset]
-selftune creator-contributions [status|enable --skill <name>|enable --all [--prefix <value>]|disable --skill <name>]
-selftune contribute [--skill NAME] [--preview] [--sanitize LEVEL] [--submit]
-selftune cron setup [--dry-run]                         # auto-detect platform (cron/launchd/systemd)
-selftune cron setup --platform openclaw [--dry-run] [--tz <timezone>]  # OpenClaw-specific
-selftune cron list
-selftune cron remove [--dry-run]
-selftune telemetry [status|enable|disable]
-selftune export    [TABLE...] [--output/-o DIR] [--since DATE]
-
-# Autonomous loop
-selftune orchestrate [--dry-run] [--review-required] [--auto-approve] [--skill NAME] [--max-skills N] [--recent-window HOURS] [--sync-force] [--max-auto-grade N] [--loop] [--loop-interval SECS]
-selftune sync        [--since DATE] [--dry-run] [--force] [--no-claude] [--no-codex] [--no-opencode] [--no-openclaw] [--no-pi] [--no-repair] [--json]
-
-# Discovery + badges
-selftune workflows   [--skill NAME] [--skill-path PATH] [--min-occurrences N] [--window N] [--json] [save --skill NAME --skill-path PATH]
-selftune badge       --skill <name> [--format svg|markdown|url] [--output PATH]
-
-# Maintenance
-selftune quickstart
-selftune repair-skill-usage [--since DATE] [--dry-run]
-selftune recover            [--full] [--force] [--since DATE]
-selftune export-canonical   [--out FILE] [--platform NAME] [--record-kind KIND] [--pretty] [--push-payload]
-selftune uninstall          [--dry-run] [--keep-logs] [--npm-uninstall]
-
-# Hook dispatch (for debugging/manual invocation)
-selftune hook <name>   # prompt-log | session-stop | skill-eval | auto-activate | skill-change-guard | evolution-guard
-
-# Platform hooks (non-Claude-Code agents)
-selftune codex hook
-selftune codex install    [--dry-run] [--uninstall]
-selftune opencode hook
-selftune opencode install [--dry-run] [--uninstall]
-selftune cline hook
-selftune cline install    [--dry-run] [--uninstall]
-selftune pi hook
-selftune pi install       [--dry-run] [--uninstall]
-
-# Registry (team skill distribution)
-selftune registry push [name]      [--version=<semver>] [--summary=<text>]
-selftune registry install <name>   [--global]
-selftune registry sync
-selftune registry status
-selftune registry rollback <name>  [--to=<version>] [--reason=<text>]
-selftune registry history <name>
-selftune registry list
-
-# Alpha enrollment (device-code flow — browser opens automatically)
-selftune init --alpha --alpha-email <email>
-selftune alpha upload [--dry-run]
-selftune alpha relink
-selftune status                                                        # shows cloud link state + upload readiness
-```
+For health remediation, prefer machine-readable `guidance.next_command` or
+top-level `next_command` from `selftune doctor` output instead of inferring the
+next step from prose.
+
+Run `selftune <command> --help` for exact flags. Read
+`references/cli-quick-reference.md` when you need the full flag reference.
+
+## Creator Trust Loop
+
+When the user wants to improve a skill, default to this creator loop before
+jumping straight to mutation:
+
+1. `selftune eval generate --skill <name> --skill-path <path>`
+2. `selftune eval unit-test --skill <name> --generate --skill-path <path>`
+3. `selftune evolve --skill <name> --skill-path <path> --dry-run --validation-mode replay`
+4. `selftune grade baseline --skill <name> --skill-path <path>`
+5. `selftune evolve --skill <name> --skill-path <path> --with-baseline`
+6. then `selftune watch --skill <name>`
+
+If the user asks "how do I know this skill works?" or "can I trust this skill
+yet?", start with this loop, then use `selftune status`, the dashboard, or the
+skill report to explain what is still missing, whether the skill is ready to
+deploy, or whether it is already being watched live.
 
 ## 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, pi, wrap codex                                                                          | Ingest            | Workflows/Ingest.md                   |
-| replay, backfill, claude transcripts, historical sessions                                                                               | Replay            | Workflows/Replay.md                   |
-| contributions, sharing preferences, opt in creator sharing, opt out creator sharing, approve contributions, revoke contributions, preview contributions, upload contributions, relay queue, contribution upload, contribution preview        | Contributions     | Workflows/Contributions.md            |
-| creator contributions, bundle contribution config, selftune.contribute.json, enable creator contribution, disable creator contribution, bulk enable creator contribution, enable all creator contributions, creator prefix config, --all, --prefix  | CreatorContributions | Workflows/CreatorContributions.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, family overlap, sibling confusion, consolidate skill family      | 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              |
-| recover, rebuild sqlite, recover db, legacy backfill, restore from export snapshot                                                      | Recover           | Workflows/Recover.md                  |
-| quickstart, getting started, onboard, first time setup, new user                                                                        | Quickstart        | Workflows/Quickstart.md               |
-| uninstall, remove selftune, clean up, teardown                                                                                          | Uninstall         | Workflows/Uninstall.md                |
-| repair, rebuild usage, fix skill usage, trustworthy usage, repair-skill-usage                                                           | RepairSkillUsage  | Workflows/RepairSkillUsage.md         |
-| export canonical, canonical export, canonical telemetry, push payload                                                                   | ExportCanonical   | Workflows/ExportCanonical.md          |
-| hook, run hook, invoke hook, manual hook, debug hook                                                                                    | Hook              | Workflows/Hook.md                     |
-| codex hooks, codex install, codex setup, opencode hooks, opencode install, opencode setup, cline hooks, cline install, cline setup, pi hooks, pi install, pi setup, multi-platform, platform hooks, non-claude hooks, multiple agents, multi-agent | PlatformHooks     | Workflows/PlatformHooks.md            |
-| registry, distribute, push skill, install skill, sync skills, team skills, version control skills, rollback skill                       | Registry          | Workflows/Registry.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 |
+| --- | --- | --- |
+| create test deploy, creator loop, ship skill, ready to deploy, can I trust this skill, how do I know this skill works | CreateTestDeploy | workflows/CreateTestDeploy.md |
+| 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, apply proposal, apply contributor proposal | 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, pi, wrap codex | Ingest | workflows/Ingest.md |
+| replay, backfill, claude transcripts, historical sessions | Replay | workflows/Replay.md |
+| contributions, sharing preferences, opt in/out creator sharing, approve/revoke contributions | Contributions | workflows/Contributions.md |
+| creator contributions, selftune.contribute.json, enable/disable creator contribution | CreatorContributions | workflows/CreatorContributions.md |
+| signals dashboard, contributor signals, signals page, community dashboard, community data, contributor stats, signal health, how are signals, how is community | SignalsDashboard | workflows/SignalsDashboard.md |
+| contribute, share, export bundle, export data, anonymized, give back | Contribute | workflows/Contribute.md |
+| init, setup, set up, bootstrap, first time, install, configure selftune, alpha, enroll | Initialize | workflows/Initialize.md |
+| cron, schedule, automate evolution, run automatically | Cron | workflows/Cron.md |
+| schedule, selftune schedule, launchd, systemd, crontab, automation setup | Schedule | workflows/Schedule.md |
+| auto-activate, suggestions, activation rules, nag, why suggest | AutoActivation | workflows/AutoActivation.md |
+| dashboard, visual, open dashboard, show dashboard, serve 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, family overlap, sibling confusion | 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, scaffold workflow skill, build skill from logs | Workflows | workflows/Workflows.md |
+| alpha upload, upload data, send alpha data, manual upload | AlphaUpload | workflows/AlphaUpload.md |
+| recover, rebuild sqlite, recover db, legacy backfill | Recover | workflows/Recover.md |
+| quickstart, getting started, onboard, first time setup, new user | Quickstart | workflows/Quickstart.md |
+| uninstall, remove selftune, clean up, teardown | Uninstall | workflows/Uninstall.md |
+| repair, rebuild usage, fix skill usage, trustworthy usage | RepairSkillUsage | workflows/RepairSkillUsage.md |
+| export canonical, canonical export, canonical telemetry, push payload | ExportCanonical | workflows/ExportCanonical.md |
+| hook, run hook, invoke hook, manual hook, debug hook | Hook | workflows/Hook.md |
+| codex/opencode/cline/pi hooks, platform hooks, non-claude hooks, multi-agent | PlatformHooks | workflows/PlatformHooks.md |
+| registry, distribute, push/install/sync/rollback skill, team skills | Registry | workflows/Registry.md |
+| export, dump, jsonl, export sqlite, debug export | Export | _(direct: `selftune export`)_ |
+| status, health summary, skill health, how are skills, run selftune | Status | _(direct: `selftune status`)_ |
+| last, last session, recent session, what happened | Last | _(direct: `selftune last`)_ |
 
 Workflows Grade, Evolve, Watch, and Ingest also run autonomously via `selftune orchestrate`.
 
@@ -203,188 +125,64 @@ Before running mutating workflows (evolve, evolve-body, evals, baseline), consul
 `references/interactive-config.md` for the pre-flight configuration pattern, model
 tier reference, and quick-path rules.
 
-## The Feedback Loop
-
-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.
-
-```text
-Observe --> Detect --> Diagnose --> Propose --> Validate --> Audit --> Deploy --> Watch --> Rollback
-   |                                                                    |
-   +--------------------------------------------------------------------+
-```
-
-1. **Observe** — Hooks capture every session (queries, triggers, metrics)
-2. **Detect** — `selftune eval generate` extracts missed-trigger patterns
-3. **Diagnose** — `selftune grade` evaluates session quality with evidence
-4. **Propose** — `selftune evolve` generates description improvements
-5. **Validate** — Evolution is tested against the eval set before deploying
-6. **Audit** — Persist proposal, evidence, and decision metadata for traceability
-7. **Deploy** — Updated description replaces the original (backup kept)
-8. **Watch** — `selftune watch` monitors for regressions post-deploy
-9. **Rollback** — `selftune evolve rollback` restores previous version if needed
-
 ## Specialized Agents
 
-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    |
-
-## Examples
-
-### Scenario 1: First-time setup
-
-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
-
-Result: Config at `~/.selftune/config.json`, hooks active, ready for session capture.
-
-### Scenario 2: Improve a skill
-
-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
-
-Result: Skill description updated to match real user language, with rollback available.
-
-### Scenario 3: Check skill health
-
-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
-
-Result: Pass rates, trend data, and actionable recommendations.
-
-### Scenario 4: Autonomous operation
-
-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
-
-Result: Skills improve continuously without manual intervention.
-
-## Troubleshooting
-
-### CLI not found
-
-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
-
-### No sessions to grade
-
-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
-
-### Evolution proposes no changes
-
-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
-
-### Dashboard won't serve
-
-Error: Port already in use or blank page.
-
-Solution:
+selftune bundles focused agents in `agents/`. Read the relevant agent file and
+follow its instructions — either inline or by spawning a subagent.
 
-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
+| Trigger keywords | Agent file | When to use |
+| --- | --- | --- |
+| diagnose, root cause, why failing, debug performance | `agents/diagnosis-analyst.md` | Recurring low grades or unclear failures after doctor/status |
+| patterns, conflicts, cross-skill, overlap | `agents/pattern-analyst.md` | Skills overlap, misroute, or interfere |
+| review evolution, check proposal, safe to deploy | `agents/evolution-reviewer.md` | Before deploying high-stakes or marginal evolutions |
+| set up selftune, integrate, configure project | `agents/integration-guide.md` | Complex setup: monorepos, multi-skill, mixed-platform |
 
 ## Negative Examples
 
-These should NOT trigger selftune — note that several are near-misses that
-share keywords but need different solutions:
+These should NOT trigger selftune — near-misses that share keywords:
 
 - "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)
+- "Create a PowerPoint about Q3 results" — pptx skill, not selftune
+- "Run my unit tests" — project tests, not skill eval tests
+- "How do I use the Research skill?" — skill _usage_, not _improvement_
 - "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
-descriptions, triggers, and execution quality). If the user is trying to
-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         |
-| `Workflows/Quickstart.md`           | Guided onboarding: init, ingest, status             | First-time setup for new users                  |
-| `Workflows/Uninstall.md`            | Clean removal of selftune data and config           | When removing selftune completely               |
-| `Workflows/RepairSkillUsage.md`     | Rebuild skill usage from source transcripts         | When skill usage data seems inaccurate          |
-| `Workflows/Recover.md`              | Recover SQLite from legacy/exported JSONL           | When rebuilding or backfilling SQLite           |
-| `Workflows/Contributions.md`        | Manage creator-directed sharing preferences         | When approving or revoking creator contribution |
-| `Workflows/CreatorContributions.md` | Manage bundled `selftune.contribute.json` configs   | When preparing a skill package for creator contributions |
-| `Workflows/ExportCanonical.md`      | Export canonical telemetry for downstream use       | When exporting data for external consumption    |
-| `Workflows/Hook.md`                 | Manual hook invocation for debugging                | When debugging or testing hooks manually        |
-| `Workflows/PlatformHooks.md`        | Non-Claude-Code platform hook install/config        | When setting up Codex, OpenCode, Cline, or Pi hooks |
-| `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                  |
-| `Workflows/Registry.md`            | Registry — team skill distribution commands         | When routing to registry workflow               |
-| `settings_snippet.json`             | Claude Code hook configuration template             | During initialization                           |
-| `assets/*.json`                     | Config templates (activation rules, settings)       | During initialization                           |
+- "My build is failing" — project issue, not selftune health
+- "Evaluate this code for security issues" — code review, not session grading
+- "Improve this function's performance" — code optimization, not skill optimization
+
+The key distinction: selftune improves _skills themselves_ (descriptions, triggers,
+execution quality). If the user wants to _use_ a skill, route to that skill instead.
+
+## Creator-Directed Contribution
+
+This skill ships a `selftune.contribute.json` config that enables creator-directed
+signal relay. When users install selftune and approve contribution, anonymous
+usage signals (trigger, grade, miss_category) are relayed to the selftune
+creator to improve the skill for everyone.
+
+- The `creator_id` in the bundled config is the selftune creator's cloud user UUID.
+- Users opt in via `selftune contributions approve selftune`.
+- No raw session content is ever shared -- only privacy-safe aggregate signals.
+- See `workflows/CreatorContributions.md` for creator-side setup.
+- See `workflows/Contributions.md` for end-user opt-in/opt-out.
+
+Routing keywords: creator contribution, selftune signals, dogfood relay,
+community contribution, signal sharing, opt in creator, creator UUID.
+
+## Additional References
+
+Load these on demand — do not read unless needed for the current task:
+
+| Reference | When to read |
+| --- | --- |
+| `references/cli-quick-reference.md` | Need exact CLI flags beyond `--help` |
+| `references/troubleshooting.md` | Diagnosing common errors |
+| `references/examples.md` | Need step-by-step scenario walkthroughs |
+| `references/creator-playbook.md` | Publishing skills others install; before-ship vs after-ship creator loop |
+| `references/interactive-config.md` | Before mutating workflows |
+| `references/grading-methodology.md` | Grading sessions or interpreting grades |
+| `references/invocation-taxonomy.md` | Analyzing trigger coverage |
+| `references/logs.md` | Parsing or debugging log files |
+| `references/setup-patterns.md` | Complex platform-specific setup |
+| `references/version-history.md` | Checking what changed between versions |
+| `settings_snippet.json` | During initialization |

package/skill/agents/diagnosis-analyst.md

@@ -50,9 +50,9 @@ parent. Do not ask the user directly unless the parent explicitly told you to.
 - The target skill's `SKILL.md`
 - Session transcripts referenced from telemetry or grading evidence
 - Relevant workflow docs:
-  - `skill/Workflows/Doctor.md`
-  - `skill/Workflows/Evals.md`
-  - `skill/Workflows/Evolve.md`
+  - `skill/workflows/Doctor.md`
+  - `skill/workflows/Evals.md`
+  - `skill/workflows/Evolve.md`
   - `skill/references/grading-methodology.md`
   - `skill/references/invocation-taxonomy.md`
 

package/skill/agents/evolution-reviewer.md

@@ -45,9 +45,9 @@ parent. Do not ask the user directly unless the parent explicitly told you to.
 - The current `SKILL.md`
 - Existing backup files if present
 - Eval set used for validation
-- `skill/Workflows/Evolve.md`
-- `skill/Workflows/EvolveBody.md`
-- `skill/Workflows/Watch.md`
+- `skill/workflows/Evolve.md`
+- `skill/workflows/EvolveBody.md`
+- `skill/workflows/Watch.md`
 - `skill/references/invocation-taxonomy.md`
 
 ## Review Workflow

package/skill/agents/integration-guide.md

@@ -33,9 +33,9 @@ parent. Do not ask the user directly unless the parent explicitly told you to.
 - `selftune doctor` returns structured health data. Use it after each material
   setup change.
 - Use current workflow docs, especially:
-  - `skill/Workflows/Initialize.md`
-  - `skill/Workflows/Doctor.md`
-  - `skill/Workflows/Ingest.md`
+  - `skill/workflows/Initialize.md`
+  - `skill/workflows/Doctor.md`
+  - `skill/workflows/Ingest.md`
   - `skill/references/setup-patterns.md`
 - Respect platform boundaries:
   - Claude Code prefers hooks installed by `selftune init`

package/skill/agents/pattern-analyst.md

@@ -46,8 +46,8 @@ you to.
 - `~/.claude/session_telemetry_log.jsonl`
 - `~/.claude/evolution_audit_log.jsonl`
 - Relevant `SKILL.md` files in the workspace
-- `skill/Workflows/Composability.md`
-- `skill/Workflows/Evals.md`
+- `skill/workflows/Composability.md`
+- `skill/workflows/Evals.md`
 - `skill/references/invocation-taxonomy.md`
 
 ## Analysis Workflow