skill-flow 1.0.1 → 1.0.3

package/docs/plan/PLAN_v1.0.0.md

@@ -1,663 +0,0 @@
-# Skill Flow Implementation Plan
-
-Version: v1.0.0
-Status: APPROVED FOR IMPLEMENTATION
-Date: 2026-03-21
-Product mode: Workflow Control Tower MVP
-Platform: macOS
-CLI entry: `skill-flow`
-State root: `~/.skillflow/`
-
-## 1. Executive Summary
-
-This plan replaces the earlier broad PRD for a discovery-heavy skills platform.
-
-The first release of `skill-flow` is a terminal-first workflow control tower for skills:
-- add one Git source
-- see it as a grouped workflow, not a flat dump
-- inspect contained skills
-- project selected skills into multiple agent targets
-- update that grouped workflow later without losing structure
-- diagnose drift and broken projections clearly
-
-This version is intentionally narrower than the original PRD:
-- Git only
-- grouped workflow management only
-- no discovery / ranking / search platform
-- no ClawHub in v1
-- no physical canonical skill store
-
-The goal is not "manage everything eventually."
-The goal is "ship the smallest complete product that makes grouped skills finally make sense."
-
-## 2. Problem Statement
-
-Current skills tooling flattens related skills into target directories. That destroys the user's mental model.
-
-The real user problem is:
-- one source often contains several related skills
-- those skills belong to one workflow
-- after install, they are scattered across hidden directories
-- later updates, reconfiguration, and troubleshooting become harder than the original install
-
-`skill-flow` should treat the workflow group as the primary unit the user understands, while preserving `Source -> SkillLeaf` as the core domain model internally.
-
-## 3. Product Scope
-
-### In scope for v1
-- Git source add/update/remove
-- source-level grouped workflow view
-- leaf skill discovery from source contents
-- workflow-first TUI for config
-- multi-target projection to supported agent directories
-- `manifest.json + lock.json`
-- grouped update and re-apply
-- minimal `doctor`
-- full test coverage for happy path plus known failure branches
-
-### NOT in scope for v1
-- discovery / `find` / ranking / candidate schema
-- ClawHub adapter
-- well-known discovery URLs
-- physical canonical skill store
-- new `WorkflowGroup` persistence entity
-- GUI / desktop app
-- plugin SDK
-- project-scope management beyond target channel realities already required
-- remote registry trust / stars / installs / leaderboards
-
-## 4. What Already Exists
-
-Existing inputs this plan reuses:
-- [`PRD/PRD-1.0.0.md`](/Users/Vint/仓库/03%20Project/skill-flow/PRD/PRD-1.0.0.md)
-  Reuse:
-  - `Source / SkillLeaf / Channel / Deployment` domain vocabulary
-  - `manifest + lock` split
-  - channel-specific projection idea
-  - tree TUI direction
-- [`DESIGN.md`](/Users/Vint/仓库/03%20Project/skill-flow/DESIGN.md)
-  Reuse:
-  - workflow-first information architecture
-  - operator-style terminal design
-  - state coverage and copy rules
-- [`Vint-main-design-20260321-182259.md`](/Users/Vint/.gstack/projects/skill-flow/Vint-main-design-20260321-182259.md)
-  Reuse:
-  - approved product direction
-  - grouped workflow framing
-  - design decisions and constraints
-- [`Vint-main-test-plan-20260321-103600.md`](/Users/Vint/.gstack/projects/skill-flow/Vint-main-test-plan-20260321-103600.md)
-  Reuse:
-  - critical paths
-  - edge cases
-  - QA surface
-
-Existing plan content explicitly not reused:
-- discovery workflow
-- `SkillCandidate` domain object
-- ranking / cache / registry tiers
-- inventory cache as a standalone state file
-- first-release ClawHub scope
-
-## 5. Architecture Decisions
-
-### 5.1 Source of Truth
-
-The system has two sources of truth:
-
-- `manifest.json`
-  User intent
-- `lock.json`
-  Resolved source snapshots, discovered leafs, deployment state
-
-Disk targets are projections only. They are never the truth.
-
-```text
-user intent
-   |
-   v
-manifest.json
-   |
-   v
-resolve source + scan leafs
-   |
-   v
-lock.json
-   |
-   v
-plan deployments
-   |
-   v
-target directories (projection only)
-```
-
-### 5.2 Domain Model
-
-The internal model remains:
-
-```text
-Source -> SkillLeaf -> DeploymentTarget -> DeploymentState
-```
-
-User-facing language:
-
-```text
-Workflow Group -> Contained Skills -> Projects To
-```
-
-There is no separate persisted `WorkflowGroup` entity in v1.
-
-### 5.3 Source Strategy
-
-v1 only implements Git sources.
-
-Do not build a generalized source plugin framework yet.
-Instead:
-- keep Git implementation concrete
-- keep data contracts future-compatible
-
-Supported source locators:
-- `owner/repo`
-- `https://...git`
-- `git@...`
-- local git path
-
-### 5.4 Channel Strategy
-
-Channels are real current differences, so they do get a lightweight adapter boundary.
-
-Required adapter responsibilities:
-- `detect()`
-- `plan()`
-- `apply()`
-- `doctor()`
-
-Common file operations must live in shared deployment core code.
-Do not duplicate symlink/copy/conflict logic per adapter.
-
-### 5.5 Storage Strategy
-
-Do not create a physical canonical skill store for v1.
-
-Use:
-- raw source checkout in `~/.skillflow/source/...`
-- leaf inventory stored in `lock.json`
-- projection paths pointing directly to source leaf roots
-
-This removes a full sync layer and reduces blast radius.
-
-## 6. Filesystem Layout
-
-```text
-~/.skillflow/
-├── source/
-│   └── git/
-│       └── <source-id>/
-├── manifest.json
-└── lock.json
-```
-
-No `channels.json`
-No `inventory-index.json`
-No `discovery-cache.json`
-No physical `skills/` store in v1
-
-## 7. Core Flows
-
-### 7.1 Add Source
-
-```text
-parse locator
-  ->
-fetch git source
-  ->
-scan source for valid leaf skills
-  ->
-write manifest intent
-  ->
-write lock snapshot + leaf inventory
-  ->
-show grouped workflow in UI
-```
-
-### 7.2 Configure Workflow
-
-```text
-load manifest + lock
-  ->
-render workflow groups
-  ->
-expand one group
-  ->
-select contained skills
-  ->
-select targets
-  ->
-build apply preview
-  ->
-persist intent
-  ->
-apply projection
-  ->
-persist deployment state
-```
-
-### 7.3 Update Workflow
-
-```text
-fetch source
-  ->
-rescan leaf inventory
-  ->
-diff old vs new leafs
-  ->
-recompute deployment plan
-  ->
-apply changed items only
-  ->
-update lock state
-```
-
-### 7.4 Doctor
-
-```text
-load manifest + lock
-  ->
-inspect targets
-  ->
-check channel availability
-  ->
-check foreign conflicts
-  ->
-check broken projections
-  ->
-check drift
-  ->
-report healthy / partial / blocked
-```
-
-## 8. UX and TUI Plan
-
-The TUI is part of the product, not a thin shell.
-
-### Default wide layout
-
-```text
-+------------------------+--------------------------+----------------------+
-| WORKFLOW GROUPS        | GROUP DETAIL             | AGENT PROJECTION     |
-|                        |                          |                      |
-| frontend-workflow      | Purpose                  | Claude Code          |
-| agent-ops              | Contained Skills         | Codex (.agents)      |
-| pdf-toolchain          | Health / Warnings        | OpenCode             |
-|                        | Update State             | OpenClaw             |
-+------------------------+--------------------------+----------------------+
-```
-
-### Top-level hierarchy
-1. workflow group name
-2. group health and update status
-3. contained skill count
-4. projection coverage
-
-### Required states
-- loading
-- empty
-- error
-- success
-- partial
-
-### Required interaction rules
-- preview before mutation
-- no hidden auto-apply
-- keyboard-only complete flow
-- visible shortcuts in current screen
-- warnings inline and in preview
-
-## 9. Commands
-
-v1 command surface:
-
-```bash
-skill-flow add <source>
-skill-flow list
-skill-flow config
-skill-flow update [<sourceId> | --all]
-skill-flow doctor
-skill-flow uninstall [<sourceId>...]
-```
-
-### Command notes
-- `add`
-  Fetch + scan + write state
-- `list`
-  Show grouped workflow summary
-- `config`
-  Main workflow-first TUI
-- `update`
-  Source-level update and incremental re-apply
-- `doctor`
-  Drift/conflict/broken target inspection
-- `uninstall`
-  Remove source and associated deployment state
-
-Commands not in v1:
-- `find`
-- `search`
-- `install` as a separate discovery-driven flow
-
-## 10. Data Contracts
-
-### 10.1 Manifest
-
-Purpose:
-- store user intent only
-
-Contents:
-- schema version
-- registered sources
-- selected leafs by target
-- user overrides
-
-Example shape:
-
-```json
-{
-  "schemaVersion": 1,
-  "sources": [],
-  "bindings": {}
-}
-```
-
-### 10.2 Lock
-
-Purpose:
-- store resolved source snapshot
-- store discovered leaf inventory
-- store deployment state
-
-Example shape:
-
-```json
-{
-  "schemaVersion": 1,
-  "sources": [],
-  "leafInventory": [],
-  "deployments": []
-}
-```
-
-### 10.3 Explicit rule
-
-If data can be derived from `manifest + lock + disk inspection`, do not create a new state file for it.
-
-## 11. Module Plan
-
-Keep the implementation small and explicit.
-
-```text
-src/
-├── commands/
-├── domain/
-├── services/
-├── adapters/
-├── state/
-├── tui/
-└── tests/
-```
-
-### Required service boundaries
-- `SourceService`
-  Parse/fetch/update Git sources
-- `InventoryService`
-  Scan sources and resolve leaf inventory
-- `DeploymentPlanner`
-  Compute create/update/remove/noop
-- `DeploymentApplier`
-  Execute projection changes
-
-### Required adapter boundaries
-- `ChannelAdapter`
-  - `detect`
-  - `plan`
-  - `apply`
-  - `doctor`
-
-### TUI-specific rule
-Tree selection state should be implemented as a pure state machine that can be tested outside terminal rendering.
-
-## 12. Channel Plan
-
-v1 targets:
-- Claude Code
-- Codex (`.agents/skills`)
-- OpenCode
-- OpenClaw
-
-### Default strategies
-- Claude Code: symlink
-- Codex (`.agents/skills`): symlink
-- OpenCode: symlink
-- OpenClaw: copy
-
-### Important simplification
-Surface `Codex (.agents/skills)` as one target in the first UX.
-Do not split generic `.agents/skills` into another parallel mental model in v1.
-
-## 13. Error Handling Strategy
-
-Core services return explicit results:
-
-```text
-Result<T>:
-- ok
-- data
-- warnings[]
-- errors[]
-```
-
-Only throw exceptions for true programming errors or impossible states.
-
-### Why
-This tool has many user-facing failures that should be recoverable:
-- bad source locator
-- invalid leaf
-- target unavailable
-- foreign file conflict
-- drift
-
-Those should not become uncontrolled exception flow.
-
-## 14. Test Strategy
-
-### Test diagram
-
-```text
-add source
-  |
-  v
-fetch git source
-  |
-  +--> fetch fails
-  |
-  v
-scan source
-  |
-  +--> 0 valid leafs
-  +--> some invalid leafs
-  |
-  v
-write manifest + lock
-  |
-  v
-config workflow group
-  |
-  +--> parent/child state transitions
-  +--> target unavailable
-  |
-  v
-plan projection
-  |
-  +--> foreign conflict
-  +--> unsupported strategy
-  |
-  v
-apply projection
-  |
-  +--> broken projection later
-  |
-  v
-update source
-  |
-  +--> added leaf
-  +--> removed leaf
-  +--> invalidated leaf
-  |
-  v
-doctor
-  |
-  +--> healthy / partial / blocked / drift
-```
-
-### Required automated coverage
-- add happy path
-- invalid source fetch
-- zero valid leafs
-- mixed valid/invalid leafs
-- foreign target conflict
-- broken symlink detection
-- unavailable target path
-- update adds leaf
-- update removes leaf
-- update invalidates leaf
-- tree selection state machine
-- doctor drift detection
-
-### Test artifact dependency
-This plan consumes and aligns with:
-- [`Vint-main-test-plan-20260321-103600.md`](/Users/Vint/.gstack/projects/skill-flow/Vint-main-test-plan-20260321-103600.md)
-
-## 15. Performance Strategy
-
-This is not a high-scale server, but careless implementation will still feel bad.
-
-### Required performance rules
-- inventory is tied to source snapshot in `lock.json`
-- do not full-rescan and full-hash on every command if snapshot unchanged
-- `DeploymentPlanner` must produce diffs:
-  - create
-  - update
-  - remove
-  - noop
-- `DeploymentApplier` only executes changed items
-
-### Explicitly avoid in v1
-- standalone cache infrastructure
-- eager full rebuild of all projections on every update
-
-## 16. Security and Safety
-
-This tool does not execute skills.
-
-It still needs to treat third-party content as untrusted input.
-
-Required protections:
-- validate `SKILL.md`
-- never mutate upstream source content
-- never overwrite foreign target files silently
-- show source locator clearly in detail metadata
-- surface copy vs symlink strategy explicitly in preview
-
-## 17. Milestones
-
-### Milestone 1: State + Git + Scanner
-- initialize project skeleton
-- implement `manifest.json + lock.json`
-- implement Git source parsing/fetch/update
-- implement leaf scanner
-- write initial tests for add/scanner/state
-
-### Milestone 2: Workflow Tree + Selection State
-- implement grouped workflow list model
-- build tree selection state machine
-- render TUI workflow list and detail pane
-- persist bindings in manifest
-- test parent/child/partial selection behavior
-
-### Milestone 3: Projection + Preview
-- implement channel detection
-- implement channel adapters
-- implement deployment planner
-- implement apply preview
-- implement deployment applier
-- test conflict and partial projection flows
-
-### Milestone 4: Update + Doctor + Hardening
-- implement source update diff flow
-- implement doctor
-- implement drift detection
-- finalize error handling and edge cases
-- complete full regression test matrix
-
-## 18. Failure Modes
-
-| Failure mode | Test required | Error handling required | User sees |
-|---|---|---|---|
-| Git fetch fails | Yes | Yes | Clear source fetch error |
-| Source has no valid leafs | Yes | Yes | Empty state with context |
-| One leaf invalid, others valid | Yes | Yes | Partial state, skipped leafs shown |
-| Target path unavailable | Yes | Yes | Blocked target with repair guidance |
-| Foreign file exists at target | Yes | Yes | Conflict, no silent overwrite |
-| Broken symlink found later | Yes | Yes | Doctor surfaces repair action |
-| Update removes a previously active leaf | Yes | Yes | Partial / changed state, explicit diff |
-| Manifest and disk disagree | Yes | Yes | Drift surfaced via doctor |
-
-Critical rule:
-No codepath may fail silently if it mutates or is expected to mutate user-visible projection state.
-
-## 19. Diagram Targets For Inline Code Comments
-
-When implementation starts, add inline ASCII diagrams in:
-- `DeploymentPlanner`
-  diff pipeline
-- tree selection state machine
-  parent/child/partial transitions
-- `doctor`
-  health and drift decision tree
-- update flow service
-  fetch -> scan -> diff -> replan -> reapply
-
-## 20. TODO Capture Rules
-
-Only create TODOs for work that is genuinely deferred and still valuable after v1.
-
-Candidates:
-- ClawHub adapter
-- discovery / search
-- broader source adapter framework
-- richer design system beyond terminal-first UI
-
-Do not create vague TODOs like "improve UX later."
-
-## 21. Definition of Done
-
-v1 is done when:
-- one Git source can be added and scanned
-- grouped workflow view is usable
-- leaf selection works
-- at least two projection targets work reliably
-- update preserves grouped mental model
-- doctor catches drift and broken projections
-- required test matrix passes
-- no critical gap remains with no test, no error handling, and silent user failure
-
-## 22. Final Recommendation
-
-Build this as a complete small product, not a cut-down platform.
-
-The correct v1 is:
-- narrow in scope
-- complete in behavior
-- explicit in state
-- strong in grouped workflow UX
-- aggressively tested on edge cases
-
-That is the lake to boil.