skillcaddy 0.27.0

package/skills/skillcaddy-manager/references/OPERATIONS.md

@@ -0,0 +1,315 @@
+# Skillcaddy Operations
+
+Use this reference for discovery, source acquisition, project links, audits, source updates, migration, bootstrap, and Web/TUI access. Start from the core loop in `SKILL.md`.
+
+## State and Identity
+
+Prefer `GET /api/state?projectPath=<encoded-path>`. It returns `skills`, `enabled`, `global`, `claude`, and `advice` in one scan.
+
+For acquisition, update, and migration, also read the sidecar source registry through:
+
+```bash
+npm run source -- list
+npm run source -- inspect <source-id>
+```
+
+State answers which skills are discoverable and enabled. The source registry answers whether a source identity is registered and therefore whether the Manager may route to `update`. A physical destination collision is not registry identity and never authorizes replacement.
+
+After natural-language intent is resolved into acquisition and/or enablement fields, use the repository adapter in `lib/managerSourceWorkflow.js` for the shared plan/apply sequence. Its plan reports `add` versus `update`, and its apply path runs the shared enablement preflight after the required rescan. The npm commands below are the repository-local user-facing equivalents.
+
+For each skill identity, retain:
+
+- `source`, `collection`, `name`, and absolute `path`;
+- `description`, human-facing `note`, `tags`, and `autoEnable`;
+- project alias, global presence, Hermes presence, Claude compatibility, and advice.
+
+Match requests in this order:
+
+1. exact enabled alias or skill name;
+2. exact `source/collection/name` or path-like ID;
+3. exact collection for a library-level request;
+4. fuzzy name, collection, source, and description match.
+
+When multiple results remain, show their full IDs, paths, and descriptions for user selection. Matching is complete only when one target or one explicitly requested collection remains.
+
+## Advice
+
+| Type | Meaning | Required handling |
+|---|---|---|
+| `project-unmanaged-entry` | Non-symlink under project skills | Leave intact; require explicit manual handling |
+| `project-unmanaged-symlink` | Link points outside Skillcaddy sources | Report ownership before removal |
+| `project-broken-link` | Target is missing | Show target; offer cleanup or re-enable |
+| `global-shadowed-by-project` | Same alias exists globally and in project | Surface precedence risk |
+| `global-alias-conflict` | Candidate alias exists globally | Surface before enabling |
+| `library-duplicate-name` | Multiple source skills share a name | Use full ID and confirmed alias |
+| `collection-setup-required` | Enabled skills depend on incomplete required setup | Offer the declared setup skill; do not report the collection ready |
+| `collection-setup-recommended` | Enabled skills would benefit from optional setup | Surface without blocking activation |
+| `collection-setup-invalid` | The tracked setup contract is invalid | Report the contract path and error; never guess or execute commands |
+
+If the API is unavailable, inspect `<project>/.agents/skills`, `<project>/.claude/skills`, and `~/.agents/skills`, then compare aliases and link targets. `~/.claude/skills` is an external Agent directory and is not a Skillcaddy global write target.
+
+## Source Acquisition and Enablement
+
+Classify the user's request before mutation:
+
+| User intent | Route |
+|---|---|
+| “Download/add this skill” / “下载这个 skill” | Acquisition only |
+| “Enable IMA knowledge-base” / “启用 IMA knowledge-base” | Enablement only; require an already acquired exact skill |
+| “Download and enable it in this project” / “下载并启用到当前项目” | Explicit combined workflow |
+| “Install this new URL for `<source-id>`” / “给 `<source-id>` 安装这个新版 URL” | Update only when that registry identity exists |
+
+For a new identity, preview and apply:
+
+```bash
+npm run source -- add <input>
+npm run source -- add <input> --yes
+```
+
+Inputs may be a hosted Git URL, GitHub tree URL, public HTTP(S) ZIP URL, stable direct HTTP(S) `/SKILL.md` URL, local ZIP, or local directory. A Remote file source requires `--name`, installs as `official/<name>/SKILL.md`, and does not accept `--namespace`. `add` is idempotent only for identical registered content. If identity or destination collision is reported, stop; use `--name` or `--namespace` where supported for a distinct new source, or select an existing registered source explicitly for update.
+
+For a registered source, preview and apply. The source update CLI requires an explicit `--project`; it also scans global `~/.agents/skills` links automatically:
+
+```bash
+npm run source -- update <source-id> [input] --project <project-dir>
+npm run source -- update <source-id> [input] --yes --project <project-dir>
+```
+
+Archive and Local replacement require a new input. Git and Remote file updates reuse the registered origin when input is omitted. Supplying a new stable direct `/SKILL.md` URL for a Remote file update migrates its registered origin. Plans and errors report `affectedProjectLinks` and `affectedGlobalLinks` separately. When either list is non-empty, stop unless the user explicitly authorizes:
+
+```bash
+npm run source -- update <source-id> [input] --allow-breaking --yes --project <project-dir>
+```
+
+Acquisition-only requests complete after a source-registry inspection and fresh state scan prove the source is present; do not create project links.
+
+Enablement-only requests resolve one exact existing skill and follow **Enable** below; do not run source acquisition.
+
+For an explicit combined request:
+
+1. preview and apply the acquisition plan;
+2. rescan `GET /api/state`;
+3. restrict matching to skill paths reported by the acquired source;
+4. if more than one remains, show full skill IDs and wait for selection;
+5. run the existing enable preflight with the requested scope and enable only the selected skill;
+6. rescan and verify both source presence and the one requested project or global link.
+
+Unknown setup readiness creates neither a reminder nor a gate. Surface a declared setup reminder after enablement without blocking the link. Never infer credentials or publisher setup from prose; the acquired skill's runtime preflight remains responsible for requirements such as IMA credentials.
+
+TUI can acquire complete Git repositories through HTTPS/SSH/SCP, public HTTP(S) ZIP files, and stable direct HTTP(S) `/SKILL.md` files through the `sourceManager` lifecycle. TUI acquisition writes the central library only; it does not create project links, run setup, or invoke runtime preflight. Web still does not expose source acquisition, replacement, or removal, while TUI source replacement and removal remain deferred. Source removal, automatic latest Archive selection, and non-ZIP archives are also deferred. The optional clone-backed global `skillcaddy` command keeps the existing no-argument TUI and additionally exposes Web lifecycle commands plus `-u` for the existing safe registered-Git batch update and read-only `-a` analysis. These CLI additions do not change source-management or enablement boundaries.
+
+## Source Registry Migration and Recovery
+
+Preview before applying:
+
+```bash
+npm run source -- migrate
+npm run source -- migrate --yes
+```
+
+Migration writes only `.skillcaddy/sources/`; it does not move source directories or edit project links. Leave ambiguous entries unresolved. For recovery, restore a pre-operation copy of `.skillcaddy/sources/`. Add and update already clean up or roll back failed publication; after an interruption, inspect registry and active content before retrying.
+
+## Query Skills
+
+Scan bundled and central sources, project links, global links, Hermes links, Claude links, and advice. Group output by source/collection and mark available, enabled, global, Hermes, and advised states.
+
+Complete when every returned item can be identified without relying on a bare folder name and the active advice is represented.
+
+## Enable
+
+Every enablement request has an explicit scope:
+
+| Scope | Link target | Project path | Claude sync |
+|---|---|---|---|
+| `project` | `<project>/.agents/skills/<alias>` | Required | Best-effort to `<project>/.claude/skills/` |
+| `global` | `~/.agents/skills/<alias>` | Not required | Never writes `~/.claude/skills/` |
+| `hermes` | `~/.hermes/skills/<alias>` | Not required | Independent; only `official`/`github`/`personal` sources |
+
+### Single skill
+
+1. Resolve one source skill and an alias; default the alias to the folder name.
+2. Skip `archived/` unless explicitly selected.
+3. Select `project` or `global` explicitly. A project alias may coexist with a global alias of the same name; it does not block the other scope.
+4. Run the mutation gate against the selected scope and advice.
+5. Prefer the shared API or CLI:
+
+```bash
+curl -sS -X POST http://127.0.0.1:4173/api/enable \
+  -H 'Content-Type: application/json' \
+  -d '{"scope":"project","projectPath":"/path/to/project","skillPath":"/path/to/skill","alias":"skill-name"}'
+
+skillcaddy enable <skill-id> --project /path/to/project [--alias <name>]
+skillcaddy enable <skill-id> --global [--alias <name>]
+skillcaddy enable <skill-id> --hermes [--alias <name>]
+```
+
+For global enablement, omit `projectPath`; the only managed destination is `~/.agents/skills/<alias>`:
+
+```bash
+curl -sS -X POST http://127.0.0.1:4173/api/enable \
+  -H 'Content-Type: application/json' \
+  -d '{"scope":"global","skillPath":"/path/to/skill","alias":"skill-name"}'
+```
+
+For Hermes enablement, omit `projectPath`; `official`, `github`, and `personal` sources may target `~/.hermes/skills/<alias>`:
+
+```bash
+curl -sS -X POST http://127.0.0.1:4173/api/enable \
+  -H 'Content-Type: application/json' \
+  -d '{"scope":"hermes","skillPath":"/path/to/skill","alias":"skill-name"}'
+```
+
+Verify the selected scope target. Project scope may report Claude sync; global and Hermes scopes must report no Claude write.
+
+Complete when the rescan reports the expected alias and target, with remaining advice stated.
+
+### Source or collection
+
+Expand the collection and request the shared enable plan. Exclude archived skills and skip `autoEnable: false`, except for a setup skill added by the plan because affected skills require it. Before mutation, show every pending setup with its status, missing artifacts, and setup skill.
+
+After confirmation, execute the shared Collection enablement lifecycle with an explicit scope:
+
+```bash
+curl -sS -X POST http://127.0.0.1:4173/api/enable-collection \
+  -H 'Content-Type: application/json' \
+  -d '{"scope":"project","projectPath":"/path/to/project","skillIds":["source/collection/skill-a","source/collection/skill-b"]}'
+```
+
+For a global collection, use `{"scope":"global",...}` and omit `projectPath`. The lifecycle owns link application, classifies every candidate as enabled, unchanged, skipped, or failed, and refreshes setup reminders only for project scope. Do not reproduce that loop in an adapter or Agent workflow.
+
+For interactive setup, offer:
+
+1. enable and continue into setup guidance;
+2. enable only and keep the collection marked as pending;
+3. cancel.
+
+Activation remains reversible and may proceed without setup, but never report the collection as ready until `state.setups` reports `ready`.
+
+Complete when every candidate is classified as enabled, unchanged, skipped, or failed.
+
+## Collection Setup Lifecycle
+
+`GET /api/state` returns `setups`. The tracked contract under `collection-metadata/` is the policy source; project artifacts are the readiness source. Status meanings:
+
+| Status | Handling |
+|---|---|
+| `missing` | No required artifacts exist; offer the setup skill |
+| `partial` | Some artifacts exist; inspect and resume instead of blindly overwriting |
+| `ready` | Required artifacts exist; no setup warning |
+| `invalid` | Contract validation failed; report it and do not infer a fallback |
+
+When the user confirms setup in an Agent conversation, invoke the declared `setupSkillId` and follow that skill's own exploration and confirmation process. After it finishes, rescan state and require `ready`. Web or TUI surfaces without an Agent execution channel may only show the setup instruction; they must not claim to have run it.
+
+Setup contracts are declarative and may reference only a setup skill, affected skill IDs, and project-relative artifacts. Never execute shell commands supplied by collection metadata.
+
+## Disable
+
+Resolve enabled aliases from the selected scope. Remove only managed project symlinks and matching Claude compatibility links. For global or Hermes scope, remove only a symlink whose target is provably inside the current Skillcaddy source folders; ordinary entries, foreign links, and ambiguous ownership are read-only. A non-symlink or external target goes back through the mutation gate.
+
+Prefer:
+
+```bash
+curl -sS -X POST http://127.0.0.1:4173/api/disable \
+  -H 'Content-Type: application/json' \
+  -d '{"scope":"project","projectPath":"/path/to/project","alias":"skill-name"}'
+```
+
+```bash
+skillcaddy disable <alias> --project /path/to/project
+skillcaddy disable <alias> --global
+```
+
+For a collection, map enabled targets back to source paths and select only aliases owned by that collection.
+
+Complete when removed aliases are absent, source directories still exist, and unaffected aliases remain unchanged.
+
+## Initialize, Audit, and Health
+
+An audit is read-only unless the user separately authorizes changes. Summarize project links, Claude links, globals, and advice by severity. Recommend the smallest correction: repair broken links, disambiguate duplicate sources, or inspect unmanaged entries.
+
+Health checks verify:
+
+- source skill directories contain `SKILL.md` with usable frontmatter;
+- project and Claude links have the expected type and existing target;
+- global/project aliases and duplicate source names are surfaced;
+- metadata descriptions remain useful for discovery.
+
+For an edited skill, run:
+
+```bash
+python3 /Users/chenweilong/.codex/skills/.system/skill-creator/scripts/quick_validate.py /path/to/skill
+```
+
+Complete when every discovered anomaly is reported with identity, path, and proposed owner/action.
+
+## Version and GitHub Source Updates
+
+Check recommendation-data version alignment with:
+
+```bash
+node skills/skillcaddy-manager/scripts/version-manager.cjs check
+```
+
+Use `sync` only when the user requests a version update, then verify the changed version fields before reporting completion.
+
+For registered Git sources, use the unified updater. It fetches the tracked ref, skips dirty worktrees, advances only by fast-forward, and blocks breaking updates that affect known current-project links. Never stash, reset, or overwrite source edits.
+
+Prefer:
+
+```bash
+npm run source -- update-git [--project <project-dir>]
+```
+
+The batch updater requires a current project path. Pass `--project`, set
+`SKILLCADDY_PROJECT`, or provide `context.projectPath` through the public
+source-management seam; missing context is an error rather than an implicit
+"no project links" result. The Web lifecycle uses the clone's own root, while
+`--root` is for central-library source and analysis operations.
+
+If a user manually advances a registered Git checkout with `git pull`, use the
+explicit registry-repair flow rather than editing the sidecar record directly:
+
+```bash
+npm run source -- repair <source-id> --project <project-dir>
+npm run source -- repair <source-id> --project <project-dir> --yes
+```
+
+Repair adopts only a clean checkout on the registered ref and remote whose
+current commit is a fast-forward of the registered commit. It validates the
+current skill inventory and applies the same current-project link protection;
+`--allow-breaking` is required for an affected link. Dirty checkouts remain
+untouched and are reported as reminders. Batch failures now include their
+category and reason, while dirty outcomes include a non-mutating reminder.
+
+Complete when updated, current, dirty, breaking, failed, and repair outcomes
+are reported separately.
+
+## Bootstrap and Web/TUI
+
+The clone-backed CLI + TUI command can be linked globally without publishing or downloading a global npm package:
+
+```bash
+npm run install:cli
+npm run check:cli
+```
+
+`install:cli` uses local `npm link`, so the global `skillcaddy` command resolves back to the current clone and uses that clone as the central library. It exposes both CLI and TUI behavior; `install:tui` / `check:tui` remain compatibility aliases. The same operation is available as `npm run tui -- install cli` or TUI option 11. It refuses a global package link owned by another clone. From another project, run `skillcaddy` to manage the current directory or `skillcaddy /path/to/project` to select a target explicitly. This is a user-level mutation, so obtain approval before running it.
+
+Global manager installation writes to a user-level directory, so obtain approval first. From the repository:
+
+```bash
+npm run install:manager
+npm run check:manager
+```
+
+Installation is complete only when `~/.agents/skills/skillcaddy-manager` is a managed symlink to this bundled skill. Existing files, directories, or links to another target are conflicts.
+
+For Web access, start or reuse `npm start`, encode the target project path, and open:
+
+```text
+http://127.0.0.1:4173/?projectPath=<encoded-project-path>
+```
+
+Use `PORT=<other-port> npm start` only when `4173` is occupied or the user requests it. The TUI uses the same state model; prefer its browse-first library and skill actions over manual alias entry.
+
+Complete when the manager reports the intended project and a fresh state scan succeeds.

package/skills/skillcaddy-manager/references/RECOMMENDATION_GUIDE.md

@@ -0,0 +1,51 @@
+# Skillcaddy Recommendation Branch
+
+Use this branch only for recommendation requests. Recommendation is analysis-first: observed state selects the mode; static catalog data supplies candidates.
+
+## Sources of Truth
+
+- `/api/state?projectPath=...`: current library, project enablement, globals, metadata, and advice.
+- `featured-skills.json`: modes, signals, scenarios, candidates, and recommendation limit.
+- `skill-platforms.json`: discovery platforms.
+- `scripts/view-recommendations.cjs`: deterministic catalog views.
+- `scripts/check-conflicts.cjs`: comparable name, description, tag, and capability profiles for agent review.
+- `scripts/check-global-skills.cjs`: global skill scan.
+
+Do not duplicate candidate lists or conflict policy in prose; read the current JSON for each recommendation run.
+
+## Steps
+
+1. Read `/api/state` and inspect repository skills, enabled aliases, globals, notes/tags, source distribution, and advice.
+   - Complete when the current capability footprint and likely overlap candidates are observable.
+2. Classify one mode from `featured-skills.json`:
+   - `discovery`: the library is empty or the use case is unclear;
+   - `starter`: the project or request provides a clear scenario;
+   - `gap-based`: an existing mixed library has an identifiable missing category.
+   - Complete when one mode is justified by specific state signals.
+3. Read only the matching scenario/category data. Compare each candidate with installed collections using names, descriptions, tags, and contained skills. Treat similarity output as evidence for agent judgment, never as an automatic conflict verdict.
+   - Complete when each likely overlap has concrete shared terms or capabilities and has been classified as complementary, redundant, or uncertain.
+4. Recommend no more than the catalog's `maxRecommendations`. Bind every item to an observed gap or scenario and avoid same-shape additions.
+   - Complete when removing any item would leave a stated need uncovered and every item explains why it fits now.
+
+## Deterministic Views
+
+```bash
+node skills/skillcaddy-manager/scripts/view-recommendations.cjs onboarding
+node skills/skillcaddy-manager/scripts/view-recommendations.cjs workflows
+node skills/skillcaddy-manager/scripts/view-recommendations.cjs scenario new-project
+node skills/skillcaddy-manager/scripts/view-recommendations.cjs category development
+node skills/skillcaddy-manager/scripts/view-recommendations.cjs platforms
+node skills/skillcaddy-manager/scripts/check-conflicts.cjs <collection> --against <installed-id,installed-id>
+node skills/skillcaddy-manager/scripts/check-global-skills.cjs
+```
+
+Use `onboarding` for an empty library. A code repository alone is a weak signal; prefer discovery until the request, existing skills, or project contents establish a development workflow need.
+
+## Output
+
+Use a compact table:
+
+| Recommendation | Mode | Observed fit | Overlap evidence/status | Next action |
+|---|---|---|---|---|
+
+Distinguish recommendation from installation. Apply the mutation gate in `SKILL.md` before enabling anything. Recommendation is complete when the state evidence, selected mode, candidate rationale, exclusions, and next action are all explicit.