skill-flow 1.0.2 → 1.0.4

package/docs/refrences/README.md

@@ -1,9 +0,0 @@
-# References
-
-This directory stores external path and compatibility references that guide
-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

@@ -1,274 +0,0 @@
-# Agent Skill Paths Reference
-
-Last updated: 2026-03-22
-
-This file separates two things:
-
-1. Current `skill-flow` implementation behavior
-2. Broader ecosystem path references for future support work
-
-The goal is to keep implementation truth and compatibility research in one
-place without mixing them up.
-
-## Current Skill Flow Support
-
-These are the target roots that the current code can detect and project into.
-Targets with missing directories are hidden from the `config` TUI.
-
-| Target | Default detection roots | Env override | Strategy |
-| --- | --- | --- | --- |
-| Claude Code | `~/.claude/skills` | `SKILL_MANAGER_TARGET_CLAUDE_CODE` | `symlink` |
-| OpenAI Codex | `~/.codex/.agents/skills`, `~/.agents/skills` | `SKILL_MANAGER_TARGET_CODEX` | `symlink` |
-| Cursor | `~/.cursor/skills` | `SKILL_MANAGER_TARGET_CURSOR` | `symlink` |
-| GitHub Copilot | `~/.copilot/skills` | `SKILL_MANAGER_TARGET_GITHUB_COPILOT` | `symlink` |
-| Gemini CLI | `~/.gemini/skills` | `SKILL_MANAGER_TARGET_GEMINI_CLI` | `symlink` |
-| OpenCode | `~/.config/opencode/skills`, `~/.opencode/skills` | `SKILL_MANAGER_TARGET_OPENCODE` | `symlink` |
-| OpenClaw | `~/.openclaw/skills` | `SKILL_MANAGER_TARGET_OPENCLAW` | `copy` |
-| Pi | `~/.pi/agent/skills` | `SKILL_MANAGER_TARGET_PI` | `symlink` |
-| Windsurf | `~/.codeium/windsurf/skills` | `SKILL_MANAGER_TARGET_WINDSURF` | `symlink` |
-| Roo Code | `~/.roo/skills` | `SKILL_MANAGER_TARGET_ROO_CODE` | `symlink` |
-| Cline | `~/.cline/skills` | `SKILL_MANAGER_TARGET_CLINE` | `symlink` |
-| Amp | `~/.config/agents/skills`, `~/.config/amp/skills` | `SKILL_MANAGER_TARGET_AMP` | `symlink` |
-| Kiro | `~/.kiro/skills` | `SKILL_MANAGER_TARGET_KIRO` | `symlink` |
-
-Notes:
-
-- Current v1 implementation projects into target roots only. It does not yet
-  model per-agent project skill roots, compatibility reads, or instruction
-  files such as `AGENTS.md`, `CLAUDE.md`, or `GEMINI.md`.
-- Hidden target behavior is intentional: if no detected root exists, the target
-  should not appear in `config`.
-- Shared compatibility roots such as `~/.agents/skills` and `~/.claude/skills`
-  are not reused across multiple new targets yet. This avoids multi-target
-  projection collisions onto the same physical directory.
-
-## Ecosystem Path References
-
-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:
-
-- Personal skills: `~/.claude/skills/<skill-name>/SKILL.md`
-- Project skills: `<repo>/.claude/skills/<skill-name>/SKILL.md`
-
-Instructions and rules:
-
-- User instructions: `~/.claude/CLAUDE.md`
-- Project instructions: `<repo>/CLAUDE.md`
-- Project hidden instructions: `<repo>/.claude/CLAUDE.md`
-- Rules: `<repo>/.claude/rules/*.md`
-
-### 2. OpenAI Codex
-
-Skills:
-
-- Current official user skills: `$HOME/.agents/skills`
-- Project skills: upward scan from current directory for `.agents/skills`
-- System skills: `/etc/codex/skills`
-
-Notes:
-
-- `~/.codex/` is primarily a config directory now, for example
-  `~/.codex/config.toml`.
-- `~/.codex/` should not be treated as the official primary skills root going
-  forward.
-
-### 3. Cursor
-
-Skills:
-
-- Global skills: `~/.cursor/skills/`
-- Project skills: `<repo>/.cursor/skills/`
-
-Compatibility reads:
-
-- `.agents/skills/`
-- `.claude/skills/`
-- `.codex/skills/`
-- Their corresponding home-directory versions
-
-Rules and notes:
-
-- Rules: `<repo>/.cursor/rules/`
-- Cursor skills entered editor and CLI support on `2026-01-22`
-
-### 4. OpenCode
-
-Skills:
-
-- Global skills: `~/.config/opencode/skills/<name>/SKILL.md`
-- Project skills: `<repo>/.opencode/skills/<name>/SKILL.md`
-
-Compatibility reads:
-
-- `.claude/skills`
-- `~/.claude/skills`
-- `.agents/skills`
-- `~/.agents/skills`
-
-Instructions and rules:
-
-- Long-term instructions: `AGENTS.md`
-- Global instructions: `~/.config/opencode/AGENTS.md`
-- Also reads `.cursor/rules/*.md` as one instruction source
-
-### 5. Pi
-
-Skills:
-
-- Global skills: `~/.pi/agent/skills/`
-- Also supports: `~/.agents/skills/`
-- Project skills: `<repo>/.pi/skills/`
-- Also scans current directory and ancestors for `.agents/skills/`
-
-Compatibility reads:
-
-- `~/.claude/skills`
-- `~/.codex/skills`
-
-### 6. GitHub Copilot
-
-Skills:
-
-- Project skills: `.github/skills/`
-- Project compatibility skills: `.claude/skills/`
-- User skills: `~/.copilot/skills/`
-- User compatibility skills: `~/.claude/skills/`
-
-Notes:
-
-- Another official description also lists `.agents/skills/` in the wider
-  priority order.
-- This covers VS Code agent mode and Copilot coding agent usage.
-
-### 7. Gemini CLI
-
-Skills:
-
-- Workspace skills: `<repo>/.gemini/skills/`
-- Workspace alias: `<repo>/.agents/skills/`
-- User skills: `~/.gemini/skills/`
-- User alias: `~/.agents/skills/`
-
-Instructions and extensions:
-
-- User instructions: `~/.gemini/GEMINI.md`
-- Workspace instructions: upward scan for `GEMINI.md`
-- Extensions: `~/.gemini/extensions/`
-
-### 8. Windsurf
-
-Skills:
-
-- Workspace skills: `<repo>/.windsurf/skills/<skill-name>/SKILL.md`
-- User skills: `~/.codeium/windsurf/skills/<skill-name>/SKILL.md`
-- System skills on macOS:
-  `/Library/Application Support/Windsurf/skills/`
-
-Instructions, rules, workflows, memories:
-
-- Long-term instructions: `AGENTS.md`
-- Global rules: `global_rules.md`
-- Project rules: `<repo>/.windsurf/rules/`
-- Project workflows: `<repo>/.windsurf/workflows/`
-- Generated memories: `~/.codeium/windsurf/memories/`
-
-### 9. Roo Code
-
-Skills:
-
-- Project skills: `<repo>/.roo/skills/`
-- Global skills: `~/.roo/skills/`
-
-Rules and commands:
-
-- Project rules: `<repo>/.roo/rules/`
-- Global rules: `~/.roo/rules/`
-- Mode-specific rules: `rules-{modeSlug}`
-- Project commands: `<repo>/.roo/commands/`
-- Global commands: `~/.roo/commands/`
-
-### 10. Cline
-
-Skills:
-
-- Project skills: `<repo>/.cline/skills/`
-- Global skills: `~/.cline/skills/`
-
-Compatibility reads:
-
-- Project compatibility skills: `.clinerules/skills/`
-- Project compatibility skills: `.claude/skills/`
-
-Rules, workflows, local data:
-
-- Project rules: `.clinerules/`
-- Global rules on macOS: `~/Documents/Cline/Rules`
-- Project workflows: `<repo>/.clinerules/workflows/`
-- Global workflows on macOS: `~/Documents/Cline/Workflows`
-- Local data and config: `~/.cline/data/`
-
-### 11. Amp
-
-Skills:
-
-- Project skills: `<repo>/.agents/skills/`
-- User skills: `~/.config/agents/skills/`
-
-Compatibility reads:
-
-- `~/.config/amp/skills/`
-- `.claude/skills/`
-- `~/.claude/skills/`
-
-Instructions:
-
-- Long-term instructions: `AGENTS.md`
-- User `AGENTS` locations:
-  - `~/.config/amp/AGENTS.md`
-  - `~/.config/AGENTS.md`
-
-### 12. Kiro
-
-Skills:
-
-- Global skills: `~/.kiro/skills/`
-- Project skills: `<repo>/.kiro/skills/`
-
-## Suggested Follow-up Optimization Areas
-
-These references imply a few near-term architecture changes:
-
-- Split target support into:
-  - projection targets
-  - project-level compatibility readers
-  - instruction/rules readers
-- Distinguish official roots from compatibility aliases
-- Model user-level, project-level, and system-level roots explicitly
-- Add reference-backed tests for detection precedence and hidden-target behavior
-- Document which roots are used for read, write, or compatibility-only behavior

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

@@ -1,199 +0,0 @@
-# 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.