skill-flow 1.0.1 → 1.0.2

package/docs/plan/PLAN_v1.0.1.md

@@ -17,8 +17,9 @@ State root: `~/.skillflow/`
 This release does not try to become a full ecosystem registry.
 It stays narrow:
 - Git sources still matter
+- built-in Git catalogs provide a fixed discovery corpus
 - ClawHub becomes the only new remote structured source
-- `find` only merges local inventory and ClawHub search
+- `find` merges local inventory, built-in Git catalogs, and ClawHub search
 
 The engineering goal is not "support every source."
 The engineering goal is:
@@ -178,7 +179,7 @@ Track A: Source expansion
 
 Track B: Discovery
   - find/search
-  - local + ClawHub result merge
+  - local + built-in Git + ClawHub result merge
   - ranking
   - candidate -> add command bridge
 ```
@@ -289,6 +290,7 @@ This is the smallest seam that cleanly supports:
 
 `find` aggregates:
 - local installed inventory
+- built-in Git catalogs
 - ClawHub search metadata
 
 It does not:
@@ -300,7 +302,34 @@ Search fetch policy:
 - `find` requests metadata only
 - `add` downloads source content
 
-### 7.7 Candidate-To-Command Bridge Is A First-Class Boundary
+### 7.7 Built-In Git Catalogs Are Fixed And Curated
+
+`find` includes a fixed built-in Git catalog list.
+
+This list merges the original default catalog and the expanded catalog set, de-duplicated by repository:
+
+| Repository | Branch |
+| --- | --- |
+| `anthropics/skills` | `main` |
+| `obra/superpowers` | `main` |
+| `affaan-m/everything-claude-code` | `main` |
+| `msitarzewski/agency-agents` | `main` |
+| `nextlevelbuilder/ui-ux-pro-max-skill` | `main` |
+| `sickn33/antigravity-awesome-skills` | `main` |
+| `coreyhaines31/marketingskills` | `main` |
+| `agentskills/agentskills` | `main` |
+| `Leonxlnx/taste-skill` | `main` |
+| `Affitor/affiliate-skills` | `main` |
+| `luongnv89/skills` | `main` |
+| `ComposioHQ/awesome-claude-skills` | `master` |
+| `cexll/myclaude` | `master` |
+| `JimLiu/baoyu-skills` | `main` |
+| `dontbesilent2025/dbskill` | `main` |
+| `garrytan/gstack` | `main` |
+| `pbakaus/impeccable` | `main` |
+| `zarazhangrui/frontend-slides` | `main` |
+
+### 7.8 Candidate-To-Command Bridge Is A First-Class Boundary
 
 `find` output must not hand-build `add` command strings in CLI formatting code.
 
@@ -355,6 +384,8 @@ query
   |
   +--> local inventory matcher
   |
+  +--> built-in git catalog matcher
+  |
   +--> clawhub search metadata
   |
   v

package/docs/refrences/README.md

@@ -5,3 +5,5 @@ future `skill-flow` target support.
 
 - [agent-skill-paths.md](/Users/Vint/仓库/03%20Project/skill-flow/docs/refrences/agent-skill-paths.md)
   Current implementation paths and broader ecosystem path references.
+- [config-state-reconciliation.md](/Users/Vint/仓库/03%20Project/skill-manager/docs/refrences/config-state-reconciliation.md)
+  Config, manifest, lock, and disk-state reconciliation rules.

package/docs/refrences/agent-skill-paths.md

@@ -47,6 +47,28 @@ Notes:
 These references are for future compatibility and target-expansion work. They
 should not be read as "already implemented".
 
+### Ecosystem Default Path Matrix
+
+This matrix is broader than current `skill-flow` support. It is a planning and compatibility reference, not an implementation promise.
+
+| Tool | Global Path | Project Path | Default |
+| --- | --- | --- | :---: |
+| Claude Code | `~/.claude/skills/` | `.claude/skills/` | enabled |
+| Codex | `~/.codex/skills/` | `.codex/skills/` | enabled |
+| OpenClaw | `~/.openclaw/skills/` | `.openclaw/skills/` | enabled |
+| Agents (generic) | `~/.agents/skills/` | `.agents/skills/` | enabled |
+| Cursor | `~/.cursor/rules/` | `.cursor/rules/` | enabled |
+| Windsurf | `~/.windsurf/rules/` | `.windsurf/rules/` | enabled |
+| Cline | `~/Documents/Cline/Rules/` | `.clinerules/` | enabled |
+| Roo Code | `~/.roo/rules/` | `.roo/rules/` | enabled |
+| Continue | `~/.continue/rules/` | `.continue/rules/` | enabled |
+| GitHub Copilot | `~/.github/instructions/` | `.github/instructions/` | enabled |
+| Aider | `~/.aider/skills/` | `.aider/skills/` | enabled |
+| OpenCode | `~/.config/opencode/skills/` | `.opencode/skills/` | enabled |
+| Zed | `~/.config/zed/prompt_overrides/` | `.zed/rules/` | enabled |
+| Augment | `~/.augment/rules/` | `.augment/rules/` | enabled |
+| Amp | `~/.amp/skills/` | `.amp/skills/` | enabled |
+
 ### 1. Claude Code
 
 Skills:

package/docs/refrences/config-state-reconciliation.md

@@ -0,0 +1,199 @@
+# Config State Reconciliation
+
+Last updated: 2026-03-22
+
+This document explains how `skill-flow` maps config state to persisted state,
+why state could look inconsistent before, and what the current normalization
+rules are.
+
+## Four State Layers
+
+`skill-flow` currently has four relevant state layers:
+
+1. TUI draft state
+2. `manifest.json`
+3. `lock.json`
+4. Target disk state
+
+They are related, but they do not serve the same purpose.
+
+## Layer Responsibilities
+
+### 1. TUI draft state
+
+The config UI uses this shape:
+
+- `enabledTargets: DeploymentTargetName[]`
+- `selectedLeafIds: string[]`
+
+This is the editing model used by `ConfigApp`.
+
+Important constraint:
+
+- the TUI has one shared selected skill set per workflow group
+- it does not model different `leafIds` per target
+
+So from the UI's perspective, a workflow group means:
+
+- these targets are enabled
+- these skills are selected for all enabled targets
+
+### 2. `manifest.json`
+
+`manifest.json` stores user intent.
+
+Relevant structure:
+
+```json
+{
+  "bindings": {
+    "<sourceId>": {
+      "targets": {
+        "<target>": {
+          "enabled": true,
+          "leafIds": ["<sourceId>:browse"]
+        }
+      }
+    }
+  }
+}
+```
+
+Even though `manifest` stores `leafIds` per target, current config behavior
+expects all enabled targets for one source to share the same `leafIds`.
+
+That means the persisted manifest shape is more expressive than the TUI model.
+
+### 3. `lock.json`
+
+`lock.json` stores actual scanned and applied state.
+
+It contains:
+
+- `sources`: checked out source snapshots
+- `leafInventory`: currently discovered valid skills
+- `deployments`: saved projections to targets
+
+This file is not the source of user intent. It is the source of actual known
+inventory and deployment state.
+
+### 4. Target disk state
+
+This is the real directory or symlink on each target root.
+
+Planner and doctor logic compare disk state against `lock.json`.
+
+Disk state is the final truth for whether a projection exists right now.
+
+## Main Read/Write Flow
+
+### Config open
+
+When `skill-flow config` starts:
+
+1. `getConfigData()` forces inventory reconciliation
+2. `manifest` and `lock` are loaded
+3. bindings are normalized into the same model the TUI uses
+4. summaries are derived from normalized data
+
+This makes config rendering depend on one consistent state model.
+
+### Preview
+
+When the user changes selection in the TUI:
+
+1. the draft stays in memory only
+2. `previewDraft()` loads `manifest` and `lock`
+3. bindings are normalized first
+4. the draft is applied to an in-memory manifest copy
+5. a deployment plan is calculated
+
+Preview does not write filesystem state.
+
+### Save
+
+When the user saves:
+
+1. `applyDraft()` reconciles inventory for the source
+2. `manifest` and `lock` are loaded
+3. bindings are normalized first
+4. the current draft is written into manifest intent
+5. planner computes actions
+6. applier updates target disk state and `lock.deployments`
+7. normalized manifest and updated lock are written back
+
+## Why State Could Look Wrong Before
+
+The main mismatch was this:
+
+- TUI draft model: one shared `selectedLeafIds`
+- persisted manifest model: separate `leafIds` per target
+
+If persisted data ever contained different `leafIds` for different enabled
+targets, config had no exact way to represent that state.
+
+Typical bad outcome:
+
+1. persisted `manifest` had target A and target B enabled
+2. target A had one skill selected
+3. target B had another skill selected
+4. config loaded that into one shared draft
+5. after save or refresh, the visible state looked different from what the
+   user expected
+
+That is not a rendering bug by itself. It is a state-model mismatch.
+
+## Current Normalization Rule
+
+Before config-related reads and writes, bindings are normalized per source:
+
+1. collect all enabled targets
+2. union all `leafIds` across those enabled targets
+3. drop any `leafId` not present in current `lock.leafInventory`
+4. write the same final `leafIds` back to every enabled target
+
+So for current behavior, this:
+
+```json
+{
+  "claude-code": { "enabled": true, "leafIds": ["group:browse"] },
+  "codex": { "enabled": true, "leafIds": ["group:review"] }
+}
+```
+
+is normalized to:
+
+```json
+{
+  "claude-code": { "enabled": true, "leafIds": ["group:browse", "group:review"] },
+  "codex": { "enabled": true, "leafIds": ["group:browse", "group:review"] }
+}
+```
+
+This matches the only state shape the current TUI can represent.
+
+## Relationship With Inventory Reconciliation
+
+`reconcileInventory()` may remove stale `leafIds` from bindings when those
+skills are no longer present in `lock.leafInventory`.
+
+That behavior is expected and necessary.
+
+The important part is ordering:
+
+- reconcile inventory first
+- normalize bindings second
+- render or save third
+
+Without that ordering, config can show stale selections or write back an
+incompatible state shape.
+
+## Current Invariant
+
+For the current config implementation, one workflow group should satisfy this
+invariant:
+
+- every enabled target under the same source has the same `leafIds`
+
+If product requirements later need per-target skill selection, the TUI state
+model must change first. Until then, normalization is the correct behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-flow",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Workflow-first management for AI agent skills. Group, project, and sync skills across multiple agents with explicit state tracking.",
   "type": "module",
   "main": "dist/cli.js",