@lythos/skill-deck 0.9.3 → 0.9.14

package/README.md

@@ -1,6 +1,6 @@
 # @lythos/skill-deck
 
-![Coverage](https://img.shields.io/badge/coverage-82%25-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-82%25-brightgreen) ![CI](https://img.shields.io/badge/CI-71%20unit%20%2B%2021%20CLI%20BDD-brightgreen) ![Agent BDD](https://img.shields.io/badge/Agent%20BDD-5%20local-blue) ![Intent/Plan](https://img.shields.io/badge/arch-intent%2Fplan%2Fexecute-8A2BE2)
 
 > Declarative skill deck governance. Reconcile declared skills against your cold pool via symlinks — deny-by-default, max-cards budgeting, transient expiry.
 
@@ -68,7 +68,7 @@ expires = "2026-05-01"    # ISO date; warns at ≤14 days
 |---------|------|-------------|
 | `link` | `[--deck <path>] [--workdir <dir>]` | Sync working set. Removes undeclared skills (deny-by-default). |
 | `validate` | `[deck.toml] [--workdir <dir>]` | Validate deck config without modifying files. |
-| `add` | `<locator> [--via <backend>] [--as <alias>] [--type <type>] [--deck <path>]` | Download skill to cold pool and append to skill-deck.toml. |
+| `add` | `<locator> [--alias <alias>] [--type <type>] [--deck <path>]` | Git clone skill to cold pool and append to skill-deck.toml. |
 | `refresh` | `[<fq|alias>] [--deck <path>]` | Pull latest versions of declared skills from upstream git repos. Pass a name to refresh one skill. |
 | `remove` | `<fq|alias> [--deck <path>]` | Remove skill from deck.toml and working set. Cold pool untouched. |
 | `prune` | `[--yes] [--deck <path>]` | GC cold pool repos no longer referenced. Interactive confirm (skip with `--yes`). |
@@ -79,8 +79,8 @@ expires = "2026-05-01"    # ISO date; warns at ≤14 days
 |------|-------------|---------|
 | `--deck <path>` | Path to skill-deck.toml | Find upward from cwd |
 | `--workdir <dir>` | Working directory | cwd |
-| `--via <backend>` | Download backend for `add`: `git` or `skills.sh` | `git` |
-| `--as <alias>` | Explicit alias for the skill (default: basename of path) | — |
+
+| `--alias <alias>` | Explicit alias for the skill (default: basename of path) | — |
 | `--type <type>` | Target section for `add`: `innate`, `tool`, or `combo` | `tool` |
 
 ### Safety guards
@@ -157,6 +157,92 @@ Different agents look for skills in different directories. `skill-deck.toml` con
 | `deck add` fails with 404 | Locator format wrong or repo doesn't exist | Format: `github.com/owner/repo/skill-name` (path to skill directory inside repo) |
 | `skill-deck.toml not found` | Running `link` outside project tree | Run from project root, or use `--deck ./path/to/skill-deck.toml` |
 
+## K8s-Style Reconciliation: Agent as Controller
+
+Deck follows Kubernetes' reconciliation model. The agent (Claude, Cursor, etc.) is the **controller manager** — it reads state, builds a plan, shows it to the user, then executes:
+
+```
+scan (observe state)  →  plan (compute diff)  →  confirm  →  execute  →  verify
+     ↑                                                              │
+     └──────────────────── reconciliation loop ─────────────────────┘
+```
+
+| K8s Concept | Deck Equivalent |
+|-------------|-----------------|
+| Desired state (YAML manifest) | `skill-deck.toml` |
+| Actual state (running pods) | Working set (`~/.claude/skills/`) |
+| Controller manager (reconcile loop) | Agent reads state → builds plan → user confirms |
+| `kubectl apply` | `deck link` |
+| Namespace (isolation) | Per-project deck file |
+| PersistentVolume | Cold pool (`~/.agents/skill-repos/`) |
+
+The loop doesn't run automatically (no daemon). The agent is the loop — it observes, plans, confirms, and executes on demand. This is K8s-style **declarative governance**: declare what you want, reconcile to match.
+
+## Multi-Agent POSSE Syndication
+
+Not "switching between agents" — **syndicating everywhere simultaneously**. Like IndieWeb's POSSE (Publish on your Own Site, Syndicate Elsewhere):
+
+```
+Cold Pool (~/.agents/skill-repos/)     ← canonical "own site"
+    ↓ deck link --workdir
+├── .claude/skills/                    ← syndicate to Claude Code
+├── .cursor/skills/                    ← syndicate to Cursor
+├── .codex/skills/                     ← syndicate to Codex
+└── .windsurf/skills/                  ← syndicate to Windsurf
+```
+
+One cold pool, one deck declaration, synced to every agent you use. Adding a new platform is updating a key-value registry — no code changes needed. See [multi-agent-posse-syndication](https://github.com/lythos-labs/lythoskill/blob/main/cortex/wiki/01-patterns/2026-05-05-multi-agent-posse-syndication.md).
+
+## Migration: For Existing Skill Users
+
+If you already have skills installed (in working set, globally, or mixed), deck respects your existing state:
+
+```
+1. SCAN    Agent surveys: what's in ~/.claude/skills/? What's global? What's mixed?
+           curator scan helps — indexes cold pool or existing working set.
+
+2. PLAN    Agent shows: "We found 12 skills. After migration:
+           - 2 → innate (deck infrastructure)
+           - 4 → tool section
+           - 3 → cold pool (already there, just link)
+           - 3 → backup only (unused, stale)
+           All 12 backed up to ~/.agents/lythos/backups/<date>.tar.gz"
+
+3. BACKUP  Always. `link` creates tar backups for non-symlink entries before removal.
+           Use `--no-backup` only if you're certain.
+
+4. EXECUTE deck link — creates symlinks, removes undeclared, leaves real files untouched.
+
+5. VERIFY  Agent checks: all declared skills resolve? Working set clean?
+           If unhappy: tar xf backup → rollback to pre-migration state.
+```
+
+**Key principle**: existing skill users aren't beginners. They have working setups. Migration is a conversation — scan, show the plan, confirm before acting. Backup is non-negotiable.
+
+## Architecture: Intent / Plan / Execute
+
+Deck commands separate pure logic from IO:
+
+```
+deck.toml  →  RefreshPlan / PrunePlan (pure)  →  execute with injectable IO
+```
+
+- **Plan**: `buildRefreshPlan()`, `buildPrunePlan()` — pure functions, unit-testable
+- **Execute**: `executeRefreshPlan(plan, io)`, `executePrunePlan(plan, io)` — IO injected (`gitPull`, `delete`, `log`)
+- **Config**: `workdir`, `coldPool`, `deckPath` all accept explicit overrides, defaults are fallback
+
+This enables testing without real git operations — inject mock `gitPull`, capture `log` output, assert expected behavior.
+
+## Test Coverage
+
+| Layer | Count | CI | Notes |
+|-------|-------|----|-------|
+| Unit tests | 71 | ✅ | Plan generation, link, add, remove, schema |
+| CLI BDD | 21 | ✅ | End-to-end via real CLI invocations in tmpdir |
+| Agent BDD | 5 | ❌ | Requires `claude -p` CLI; `.agent.test.ts` convention |
+
+Coverage is honest — no gate, no inflation. Agent BDD scenarios run locally only.
+
 ## More Documentation
 
 - **Skill layer** (agent-facing instructions):  

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lythos/skill-deck",
-  "version": "0.9.3",
+  "version": "0.9.14",
   "description": "Declarative skill deck governance — cold pool, working set, deny-by-default",
   "keywords": [
     "ai-agent",

package/src/add.test.ts

@@ -137,7 +137,7 @@ describe('addSkill', () => {
 
     try {
       const { addSkill } = await import('./add.ts')
-      await addSkill('github.com/owner/repo-b', { workdir: projectDir, deck: deckPath, as: 'foo' })
+      await addSkill('github.com/owner/repo-b', { workdir: projectDir, deck: deckPath, alias: 'foo' })
       expect(false).toBe(true) // should not reach here
     } catch (err: any) {
       expect(exitCode).toBe(1)

package/src/add.ts

@@ -3,8 +3,8 @@
  * deck-add.ts — Skill acquisition command
  *
  * Downloads a skill to the cold pool, updates skill-deck.toml, and links.
- * Supports multiple backends (git clone, skills.sh) without locking users
- * into a single download method.
+ * Single backend: git clone. For feed-based discovery with decision tracking,
+ * use curator add instead.
  */
 
 import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync, readFileSync, readdirSync } from 'node:fs'
@@ -16,7 +16,6 @@ import { parse as parseToml, stringify as stringifyToml } from '@iarna/toml'
 import { findDeckToml, expandHome } from './link.js'
 import { parseDeck } from './parse-deck.js'
 
-const CLAUDE_SKILLS_DIR = join(homedir(), '.claude', 'skills')
 
 interface ParsedLocator {
   host: string
@@ -76,7 +75,7 @@ function resolvePath(p: string): string {
   return resolve(p)
 }
 
-export async function addSkill(locator: string, options: { via?: string; deck?: string; workdir?: string; as?: string; type?: string }) {
+export async function addSkill(locator: string, options: { deck?: string; workdir?: string; alias?: string; type?: string }) {
   const workdir = options.workdir ? resolvePath(options.workdir) : process.cwd()
   const deckPath = options.deck
     ? resolvePath(options.deck)
@@ -89,8 +88,6 @@ export async function addSkill(locator: string, options: { via?: string; deck?:
     process.exit(1)
   }
 
-  const backend = options.via || 'git'
-
   let coldPool = join(homedir(), '.agents', 'skill-repos')
   if (existsSync(deckPath)) {
     try {
@@ -117,47 +114,10 @@ export async function addSkill(locator: string, options: { via?: string; deck?:
   const tmpRepo = join(tmpDir, 'repo')
 
   try {
-    let skillSourceDir: string
-
-    if (backend === 'skills.sh' || backend === 'vercel') {
-      const skillsShLocator = `${parsed.owner}/${parsed.repo}`
-      console.log(`📦 Downloading via skills.sh: ${skillsShLocator}`)
-
-      // Snapshot existing directories in ~/.claude/skills/
-      const beforeDirs = existsSync(CLAUDE_SKILLS_DIR)
-        ? new Set(readdirSync(CLAUDE_SKILLS_DIR, { withFileTypes: true })
-            .filter(e => e.isDirectory())
-            .map(e => e.name))
-        : new Set<string>()
-
-      execFileSync('npx', ['skills', 'add', skillsShLocator, '-g'], { cwd: tmpDir, stdio: 'inherit' })
-
-      // Detect the newly installed directory
-      const afterDirs = existsSync(CLAUDE_SKILLS_DIR)
-        ? readdirSync(CLAUDE_SKILLS_DIR, { withFileTypes: true })
-            .filter(e => e.isDirectory())
-            .map(e => e.name)
-        : []
-      const newDirs = afterDirs.filter(d => !beforeDirs.has(d))
-
-      if (newDirs.length === 0) {
-        console.error(`❌ skills.sh installed nothing new to ~/.claude/skills/`)
-        console.error(`   The skill may already be installed, or the install failed.`)
-        process.exit(1)
-      }
-      if (newDirs.length > 1) {
-        console.warn(`⚠️  Multiple new directories detected in ~/.claude/skills/`)
-        console.warn(`   Using the first one: ${newDirs[0]}`)
-      }
-      const installedName = newDirs[0]
-      skillSourceDir = join(CLAUDE_SKILLS_DIR, installedName)
-      console.log(`   Detected install: ${installedName}`)
-    } else {
-      const gitUrl = `https://${parsed.host}/${parsed.owner}/${parsed.repo}.git`
-      console.log(`📦 Cloning: ${gitUrl}`)
-      execFileSync('git', ['clone', '--depth', '1', gitUrl, tmpRepo], { stdio: 'inherit' })
-      skillSourceDir = tmpRepo
-    }
+    const gitUrl = `https://${parsed.host}/${parsed.owner}/${parsed.repo}.git`
+    console.log(`📦 Cloning: ${gitUrl}`)
+    execFileSync('git', ['clone', '--depth', '1', gitUrl, tmpRepo], { stdio: 'inherit' })
+    let skillSourceDir = tmpRepo
 
     if (!existsSync(skillSourceDir)) {
       console.error(`❌ Download failed: expected output not found at ${skillSourceDir}`)
@@ -175,7 +135,7 @@ export async function addSkill(locator: string, options: { via?: string; deck?:
     }
 
     const skillName = parsed.skill ? basename(parsed.skill) : parsed.repo
-    const alias = options.as || skillName
+    const alias = options.alias || skillName
     const skillType = (options.type || 'tool').toLowerCase()
 
     if (!['innate', 'tool', 'combo'].includes(skillType)) {

package/src/cli.ts

@@ -14,14 +14,12 @@ const command = args[0]
 
 const deckFlagIdx = args.indexOf('--deck')
 const workdirFlagIdx = args.indexOf('--workdir')
-const viaFlagIdx = args.indexOf('--via')
-const asFlagIdx = args.indexOf('--as')
+const aliasFlagIdx = args.indexOf('--alias')
 const typeFlagIdx = args.indexOf('--type')
 
 const deckPath = deckFlagIdx >= 0 ? args[deckFlagIdx + 1] : undefined
 const workdir = workdirFlagIdx >= 0 ? args[workdirFlagIdx + 1] : undefined
-const via = viaFlagIdx >= 0 ? args[viaFlagIdx + 1] : undefined
-const as = asFlagIdx >= 0 ? args[asFlagIdx + 1] : undefined
+const alias = aliasFlagIdx >= 0 ? args[aliasFlagIdx + 1] : undefined
 const type = typeFlagIdx >= 0 ? args[typeFlagIdx + 1] : undefined
 const noBackup = args.includes('--no-backup')
 const yes = args.includes('--yes')
@@ -42,8 +40,8 @@ const HELP_CONFIG = {
     { flag: '--deck <path>', description: 'Specify skill-deck.toml path (default: find upward from cwd)' },
     { flag: '--workdir <dir>', description: 'Specify working directory (default: cwd)' },
     { flag: '--no-backup', description: 'Skip tar backup when removing non-symlink entries' },
-    { flag: '--via <backend>', description: 'Download backend: git (default) | skills.sh' },
-    { flag: '--as <alias>', description: 'Explicit alias for the skill (default: basename of path)' },
+
+    { flag: '--alias <name>', description: 'Explicit alias for the skill (default: basename of path)' },
     { flag: '--type <type>', description: 'Target section: innate | tool | combo (default: tool)' },
     { flag: '--yes', description: 'Skip interactive confirmation (for prune)' },
   ],
@@ -63,7 +61,7 @@ switch (command) {
       console.error('❌ Missing locator. Usage: deck add <github.com/owner/repo[/skill]>')
       process.exit(1)
     }
-    await addSkill(locator, { via, deck: deckPath, workdir, as, type })
+    await addSkill(locator, { deck: deckPath, workdir, alias, type })
     break
   }
   case 'refresh': {

package/src/link.ts

@@ -244,7 +244,7 @@ for (const d of declared) {
 for (const [alias, types] of aliasToTypes) {
   if (types.length > 1) {
     errors.push(
-      `Alias collision: "${alias}" appears in [${types.join('], [')}]. Use --as to specify different aliases.`
+      `Alias collision: "${alias}" appears in [${types.join('], [')}]. Use --alias to specify different aliases.`
     );
   }
 }