@codepassion/skills 1.5.0 → 1.6.0

package/README.md

@@ -1,21 +1,57 @@
 # C9N Agent Skills
 
-Agent skills (SKILL.md) based on the CodePassion (C9N) conventions.
+Agent skills (SKILL.md) based on the CodePassion (C9N) conventions, plus the `c9n` CLI
+that installs them and drives tag-based deployments.
 
 ## Install
 
-    npx @codepassion/skills install claude     # ~/.claude/skills
-    npx @codepassion/skills install codex      # ~/.codex/skills
-    npx @codepassion/skills install project    # ./.agents/skills
-    npx @codepassion/skills install combined   # one combined skill
-    npx @codepassion/skills install cowork     # zip skills for claude.ai/Cowork upload (UI, no API)
+    npm i -g @codepassion/skills   # provides the c9n command
+    c9n skill install claude       # ~/.claude/skills (default target)
+
+Or without a global install:
+
+    npx -p @codepassion/skills c9n skill install claude
 
 Or: ./install.sh {claude|codex|project|combined|cowork}
 
-claude.ai and Claude Cowork share a personal skill library with no upload API, so `cowork`
-packages upload-ready zips into dist/cowork/ — upload them at
+## CLI
+
+### c9n skill
+
+    c9n skill install   [target]   # copy package skills into the target (skips existing; --force overwrites)
+    c9n skill list      [target]   # per-skill state: ok | drift | missing
+    c9n skill update    [target]   # overwrite drifted skills from the package (confirms; --yes skips)
+    c9n skill uninstall [target]   # remove installed c9n skills (confirms; --yes skips)
+    c9n skill doctor    [target]   # diagnose skills dirs, drift, frontmatter, gh/zip tooling
+
+Targets: `claude` (default, ~/.claude/skills) | `codex` (~/.codex/skills) |
+`project` (./.agents/skills) | `combined` (one merged skill) | `cowork` (upload zips).
+`--dest <dir>` overrides the directory; `--dry-run` previews any write.
+
+State is a runtime content-hash comparison against the package — "drift" covers both
+stale and hand-edited copies (see docs/adr/0001). `update` treats the package as the
+source of truth; skill edits belong in this repo, not in installed copies.
+
+claude.ai and Claude Cowork share a personal skill library with no upload API, so
+`c9n skill install cowork` packages upload-ready zips into dist/cowork/ — upload them at
 claude.ai → Settings → Capabilities → Upload skill.
 
+`c9n-skills` (the old bin) still works as a deprecated alias for `c9n skill`.
+
+### c9n deploy
+
+Creates and pushes an annotated tag in any C9N project with a tag-driven pipeline —
+the CLI never builds or ships artifacts itself.
+
+    c9n deploy -e alpha                # tags vX.Y.Z-alpha.N (version from package.json, N auto-increments)
+    c9n deploy -e alpha -v 1.2.3       # explicit version — always bare X.Y.Z, never the -alpha.N suffix
+    c9n deploy -e production -v 1.2.3  # tags v1.2.3 (requires a prior alpha of the same version)
+
+Guards (all must pass before the tag is pushed): clean working tree, on `main` and in
+sync with origin, tag ordering (production requires a prior alpha; versions must move
+forward), CI green on HEAD via `gh` (`--skip-ci` to bypass), and a confirmation prompt
+(`--yes` for CI). `--dry-run` runs every guard and shows the tag without creating it.
+
 ## Edit
 
 Per-topic SKILL.md files in skills/c9n-* are the source of truth.

package/SKILLS.md

@@ -1,21 +1,57 @@
 # C9N Agent Skills
 
-Agent skills (SKILL.md) based on the CodePassion (C9N) conventions.
+Agent skills (SKILL.md) based on the CodePassion (C9N) conventions, plus the `c9n` CLI
+that installs them and drives tag-based deployments.
 
 ## Install
 
-    npx @codepassion/skills install claude     # ~/.claude/skills
-    npx @codepassion/skills install codex      # ~/.codex/skills
-    npx @codepassion/skills install project    # ./.agents/skills
-    npx @codepassion/skills install combined   # one combined skill
-    npx @codepassion/skills install cowork     # zip skills for claude.ai/Cowork upload (UI, no API)
+    npm i -g @codepassion/skills   # provides the c9n command
+    c9n skill install claude       # ~/.claude/skills (default target)
+
+Or without a global install:
+
+    npx -p @codepassion/skills c9n skill install claude
 
 Or: ./install.sh {claude|codex|project|combined|cowork}
 
-claude.ai and Claude Cowork share a personal skill library with no upload API, so `cowork`
-packages upload-ready zips into dist/cowork/ — upload them at
+## CLI
+
+### c9n skill
+
+    c9n skill install   [target]   # copy package skills into the target (skips existing; --force overwrites)
+    c9n skill list      [target]   # per-skill state: ok | drift | missing
+    c9n skill update    [target]   # overwrite drifted skills from the package (confirms; --yes skips)
+    c9n skill uninstall [target]   # remove installed c9n skills (confirms; --yes skips)
+    c9n skill doctor    [target]   # diagnose skills dirs, drift, frontmatter, gh/zip tooling
+
+Targets: `claude` (default, ~/.claude/skills) | `codex` (~/.codex/skills) |
+`project` (./.agents/skills) | `combined` (one merged skill) | `cowork` (upload zips).
+`--dest <dir>` overrides the directory; `--dry-run` previews any write.
+
+State is a runtime content-hash comparison against the package — "drift" covers both
+stale and hand-edited copies (see docs/adr/0001). `update` treats the package as the
+source of truth; skill edits belong in this repo, not in installed copies.
+
+claude.ai and Claude Cowork share a personal skill library with no upload API, so
+`c9n skill install cowork` packages upload-ready zips into dist/cowork/ — upload them at
 claude.ai → Settings → Capabilities → Upload skill.
 
+`c9n-skills` (the old bin) still works as a deprecated alias for `c9n skill`.
+
+### c9n deploy
+
+Creates and pushes an annotated tag in any C9N project with a tag-driven pipeline —
+the CLI never builds or ships artifacts itself.
+
+    c9n deploy -e alpha                # tags vX.Y.Z-alpha.N (version from package.json, N auto-increments)
+    c9n deploy -e alpha -v 1.2.3       # explicit version — always bare X.Y.Z, never the -alpha.N suffix
+    c9n deploy -e production -v 1.2.3  # tags v1.2.3 (requires a prior alpha of the same version)
+
+Guards (all must pass before the tag is pushed): clean working tree, on `main` and in
+sync with origin, tag ordering (production requires a prior alpha; versions must move
+forward), CI green on HEAD via `gh` (`--skip-ci` to bypass), and a confirmation prompt
+(`--yes` for CI). `--dry-run` runs every guard and shows the tag without creating it.
+
 ## Edit
 
 Per-topic SKILL.md files in skills/c9n-* are the source of truth.

package/bin/c9n-skills.js

@@ -1,61 +1,5 @@
 #!/usr/bin/env node
-import { cp, mkdir, readdir, rm, stat } from 'node:fs/promises'
-import { existsSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { dirname, join, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { execFile } from 'node:child_process'
-const SRC = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'skills')
-const [,, cmd='install', target='claude', ...rest] = process.argv
-if (cmd==='help'||cmd==='--help'||cmd==='-h'){ help(); process.exit(0) }
-if (cmd!=='install'){ help(); process.exit(1) }
-const flags={dest:null,force:false,dryRun:false}
-for (let i=0;i<rest.length;i++){ const a=rest[i]
-  if (a==='--force') flags.force=true
-  else if (a==='--dry-run') flags.dryRun=true
-  else if (a==='--dest'){ const v=rest[++i]
-    if (!v){ console.error('--dest requires a value'); process.exit(1) }
-    flags.dest=resolve(v) } }
-// cowork: claude.ai / Cowork share a personal skill library with NO upload API —
-// this packages upload-ready zips for manual drag-drop in Settings → Capabilities.
-if (target==='cowork'){ await packageForCowork(flags); process.exit(0) }
-const dest = flags.dest ?? defaultDest(target)
-if (!dest){ help(); process.exit(1) }
-const sources = await resolveSources(target)
-if (!sources.length){ console.error('No skills found'); process.exit(1) }
-console.log(`Installing ${sources.length} skill(s) into ${dest}${flags.dryRun?' (dry-run)':''}`)
-if (!flags.dryRun) await mkdir(dest,{recursive:true})
-for (const src of sources){ const n=src.split(/[\\/]/).pop(); const t=join(dest,n)
-  if (existsSync(t) && !flags.force){ console.log(`  skip  ${n}`); continue }
-  console.log(`  copy  ${n}`); if (!flags.dryRun) await cp(src,t,{recursive:true,force:true}) }
-console.log('Done.')
-async function resolveSources(t){
-  if (t==='combined'){ const c=join(SRC,'c9n'); return existsSync(c)?[c]:[] }
-  const out=[]; for (const e of await readdir(SRC)){ if (!e.startsWith('c9n-')) continue
-    const f=join(SRC,e); if ((await stat(f)).isDirectory()) out.push(f) }
-  return out }
-function defaultDest(t){ const h=homedir()
-  if (t==='claude'||t==='combined') return join(h,'.claude','skills')
-  if (t==='codex') return join(h,'.codex','skills')
-  if (t==='project') return join(process.cwd(),'.agents','skills')
-  return null }
-async function packageForCowork(flags){
-  const ROOT=resolve(SRC,'..')
-  // only auto-clean the default output dir — never delete a user-supplied --dest
-  const isDefaultOut=!flags.dest
-  const out=flags.dest ?? join(ROOT,'dist','cowork')
-  const sources=[...await resolveSources('combined'), ...await resolveSources('cowork')]
-  if (!sources.length){ console.error('No skills found'); process.exit(1) }
-  console.log(`Packaging ${sources.length} skill zip(s) into ${out}${flags.dryRun?' (dry-run)':''}`)
-  if (!flags.dryRun){ if (isDefaultOut) await rm(out,{recursive:true,force:true}); await mkdir(out,{recursive:true}) }
-  for (const src of sources){ const n=src.split(/[\\/]/).pop()
-    console.log(`  zip   ${n}.zip`)
-    if (!flags.dryRun) await zipDir(SRC,n,join(out,`${n}.zip`)) }
-  console.log('Done. Upload at claude.ai → Settings → Capabilities → Upload skill (shared with Cowork).')
-  console.log('Action skills (c9n-spec, c9n-deliverables) bundle their templates/scripts in the zip.')
-}
-function zipDir(cwd,name,outFile){
-  return new Promise((res,rej)=>{ execFile('zip',['-qr',outFile,name],{cwd},(e)=>{
-    if (e && e.code==='ENOENT') rej(new Error("'zip' command not found — install zip and retry"))
-    else if (e) rej(e); else res() }) }) }
-function help(){ console.log('c9n-skills install [claude|codex|project|combined|cowork] [--dest <dir>] [--force] [--dry-run]') }
+// Deprecated alias: `c9n-skills <cmd> ...` → `c9n skill <cmd> ...`
+console.error('note: `c9n-skills` is deprecated — use `c9n skill <command>` instead')
+process.argv.splice(2, 0, 'skill')
+await import('./c9n.js')

package/bin/c9n.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { skillCommand, skillHelp } from './skill.js'
+import { deployCommand, deployHelp } from './deploy.js'
+
+const [, , cmd, ...rest] = process.argv
+try {
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') help(cmd ? 0 : 1)
+  else if (cmd === 'skill') await skillCommand(rest)
+  else if (cmd === 'deploy') await deployCommand(rest)
+  else { console.error(`unknown command: ${cmd}`); help(1) }
+} catch (e) {
+  console.error(`error: ${e.message}`)
+  process.exit(1)
+}
+
+function help(code) {
+  console.log(`c9n — CodePassion (C9N) engineering CLI
+
+Usage:
+  c9n skill <install|list|update|uninstall|doctor> [target] [options]
+  c9n deploy -e <alpha|production> [-v <X.Y.Z>] [options]
+
+Run \`c9n skill help\` or \`c9n deploy help\` for details.`)
+  process.exit(code)
+}

package/bin/deploy.js

@@ -0,0 +1,114 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { confirm, has, parseArgs, run } from './util.js'
+
+const RELEASE_BRANCH = 'main'
+
+export async function deployCommand(argv) {
+  if (['help', '--help', '-h'].includes(argv[0])) return deployHelp(0)
+  const flags = parseArgs(argv, { flags: ['yes', 'skip-ci', 'dry-run'], values: { env: 'e', version: 'v' } })
+  if (flags._.length) return deployHelp(1)
+  const env = flags.env
+  if (!env) throw new Error('missing -e <alpha|production>')
+  if (env !== 'alpha' && env !== 'production') throw new Error(`unknown environment: ${env} (use alpha | production)`)
+
+  const root = await git('rev-parse', '--show-toplevel').catch(() => { throw new Error('not inside a git repository') })
+  const version = await resolveVersion(flags.version, root)
+
+  // Guards: clean tree, on release branch, in sync with origin
+  const branch = await git('rev-parse', '--abbrev-ref', 'HEAD')
+  if (branch !== RELEASE_BRANCH) throw new Error(`deploy runs from ${RELEASE_BRANCH} — you are on ${branch}`)
+  if (await git('status', '--porcelain')) throw new Error('working tree is not clean — commit or stash first')
+  await git('fetch', 'origin', RELEASE_BRANCH, '--tags')
+  const head = await git('rev-parse', 'HEAD')
+  const remote = await git('rev-parse', `origin/${RELEASE_BRANCH}`)
+  if (head !== remote) throw new Error(`${RELEASE_BRANCH} is not in sync with origin/${RELEASE_BRANCH} — pull or push first`)
+
+  // Guard: tag ordering
+  const tags = (await git('tag', '-l', 'v*')).split('\n').filter(Boolean)
+  const prod = tags.filter((t) => /^v\d+\.\d+\.\d+$/.test(t)).map((t) => t.slice(1))
+  const latestProd = prod.sort(cmpVer).at(-1)
+  let tag
+  if (env === 'alpha') {
+    if (prod.includes(version)) throw new Error(`v${version} is already released to production — bump the version`)
+    if (latestProd && cmpVer(version, latestProd) < 0) throw new Error(`v${version} is older than latest production release v${latestProd}`)
+    const ns = tags.map((t) => t.match(new RegExp(`^v${version.replaceAll('.', '\\.')}-alpha\\.(\\d+)$`))).filter(Boolean).map((m) => Number(m[1]))
+    tag = `v${version}-alpha.${Math.max(0, ...ns) + 1}`
+  } else {
+    tag = `v${version}`
+    if (tags.includes(tag)) throw new Error(`${tag} already exists`)
+    if (!tags.some((t) => t.startsWith(`${tag}-alpha.`))) throw new Error(`no alpha of ${version} found — deploy \`-e alpha\` first`)
+    if (latestProd && cmpVer(version, latestProd) <= 0) throw new Error(`v${version} is not newer than latest production release v${latestProd}`)
+  }
+
+  // Guard: CI green on HEAD
+  if (!flags['skip-ci']) await checkCi(head)
+  else console.log('· CI check skipped (--skip-ci)')
+
+  const subject = await git('log', '-1', '--format=%h %s')
+  console.log(`\nDeploy ${env}`)
+  console.log(`  tag     ${tag}`)
+  console.log(`  commit  ${subject}`)
+  if (flags['dry-run']) { console.log('\n(dry-run) would create and push the tag.'); return }
+  if (!flags.yes && !(await confirm(`\nCreate and push ${tag}?`))) { console.log('Aborted.'); return }
+
+  await git('tag', '-a', tag, '-m', tag)
+  try {
+    await git('push', 'origin', tag)
+  } catch (e) {
+    throw new Error(`tag ${tag} created locally but push failed — retry with \`git push origin ${tag}\`\n${e.stderr ?? e.message}`)
+  }
+  console.log(`Pushed ${tag} — the pipeline takes it from here.`)
+}
+
+async function resolveVersion(raw, root) {
+  let v = raw
+  if (!v) {
+    const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8').catch(() => { throw new Error('no -v given and no package.json at repo root') }))
+    v = pkg.version
+    if (!v) throw new Error('no -v given and package.json has no version')
+  }
+  v = v.replace(/^v/, '')
+  if (!/^\d+\.\d+\.\d+$/.test(v)) throw new Error(`version must be bare X.Y.Z (got ${raw ?? v}) — the CLI appends -alpha.N itself`)
+  return v
+}
+
+async function checkCi(sha) {
+  if (!(await has('gh'))) throw new Error('gh CLI required for the CI check — install GitHub CLI or pass --skip-ci')
+  let runs
+  try {
+    runs = JSON.parse(await run('gh', ['run', 'list', '--commit', sha, '--json', 'name,status,conclusion', '--limit', '50']))
+  } catch (e) {
+    throw new Error(`could not query CI runs via gh — ${String(e.stderr ?? e.message).trim()} (or pass --skip-ci)`)
+  }
+  if (!runs.length) throw new Error('no CI runs found for HEAD — wait for CI to start or pass --skip-ci')
+  const pending = runs.filter((r) => r.status !== 'completed')
+  if (pending.length) throw new Error(`CI still running for HEAD: ${pending.map((r) => r.name).join(', ')}`)
+  const failed = runs.filter((r) => !['success', 'skipped', 'neutral'].includes(r.conclusion))
+  if (failed.length) throw new Error(`CI not green for HEAD: ${failed.map((r) => `${r.name} (${r.conclusion})`).join(', ')}`)
+  console.log(`· CI green on HEAD (${runs.length} run(s))`)
+}
+
+function cmpVer(a, b) {
+  const [ax, ay, az] = a.split('.').map(Number); const [bx, by, bz] = b.split('.').map(Number)
+  return ax - bx || ay - by || az - bz
+}
+
+function git(...args) {
+  return run('git', args)
+}
+
+export function deployHelp(code) {
+  console.log(`Usage: c9n deploy -e <alpha|production> [-v <X.Y.Z>] [options]
+
+Creates and pushes an annotated tag — the tag-driven pipeline does the rest.
+  alpha       tags vX.Y.Z-alpha.N (N auto-increments)
+  production  tags vX.Y.Z (requires a prior alpha of the same version)
+
+Options:
+  -v <X.Y.Z>  version to deploy (default: package.json version; never include -alpha.N)
+  --yes       skip the confirmation prompt
+  --skip-ci   skip the CI-green check (no gh needed)
+  --dry-run   run all guards, show the tag, don't create it`)
+  process.exit(code)
+}

package/bin/skill.js

@@ -0,0 +1,207 @@
+import { cp, mkdir, readdir, readFile, rm, stat } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { execFile } from 'node:child_process'
+import { confirm, has, parseArgs } from './util.js'
+
+const SRC = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'skills')
+const TARGETS = ['claude', 'codex', 'project', 'combined', 'cowork']
+
+export async function skillCommand(argv) {
+  if (['help', '--help', '-h'].includes(argv[0])) return skillHelp(0)
+  const flags = parseArgs(argv, { flags: ['force', 'dry-run', 'yes'], values: { dest: null } })
+  const [sub = 'install', target = 'claude'] = flags._
+  if (!TARGETS.includes(target)) throw new Error(`unknown target: ${target} (use ${TARGETS.join(' | ')})`)
+  const cmds = { install, list, update, uninstall, doctor }
+  if (!cmds[sub]) { console.error(`unknown skill command: ${sub}`); return skillHelp(1) }
+  if (sub !== 'install' && target === 'cowork') {
+    throw new Error(`cowork is packaged as zips, not installed — only \`c9n skill install cowork\` applies`)
+  }
+  await cmds[sub](target, { ...flags, dryRun: flags['dry-run'], dest: flags.dest ? resolve(flags.dest) : null })
+}
+
+async function install(target, flags) {
+  if (target === 'cowork') return packageForCowork(flags)
+  const dest = flags.dest ?? defaultDest(target)
+  const sources = await resolveSources(target)
+  if (!sources.length) throw new Error('No skills found')
+  console.log(`Installing ${sources.length} skill(s) into ${dest}${flags.dryRun ? ' (dry-run)' : ''}`)
+  if (!flags.dryRun) await mkdir(dest, { recursive: true })
+  for (const src of sources) {
+    const n = src.split(/[\\/]/).pop(); const t = join(dest, n)
+    if (existsSync(t) && !flags.force) { console.log(`  skip  ${n}`); continue }
+    console.log(`  copy  ${n}`)
+    if (!flags.dryRun) await cp(src, t, { recursive: true, force: true })
+  }
+  console.log('Done.')
+}
+
+async function list(target, flags) {
+  const dest = flags.dest ?? defaultDest(target)
+  const rows = await status(target, dest)
+  console.log(`Skills in ${dest}:`)
+  for (const r of rows) console.log(`  ${r.state.padEnd(9)} ${r.name}`)
+  const drifted = rows.filter((r) => r.state === 'drift').length
+  if (drifted) console.log(`\n${drifted} skill(s) differ from the package — \`c9n skill update ${target}\` overwrites them.`)
+}
+
+async function update(target, flags) {
+  const dest = flags.dest ?? defaultDest(target)
+  const drifted = (await status(target, dest)).filter((r) => r.state === 'drift')
+  if (!drifted.length) { console.log('All installed skills match the package — nothing to update.'); return }
+  console.log(`Package differs from ${drifted.length} installed skill(s) in ${dest}:`)
+  for (const r of drifted) console.log(`  ${r.name}`)
+  console.log('Local edits will be overwritten — the package is the source of truth.')
+  if (flags.dryRun) { console.log('(dry-run) no changes made.'); return }
+  if (!flags.yes && !(await confirm(`Overwrite ${drifted.length} skill(s)?`))) { console.log('Aborted.'); return }
+  for (const r of drifted) {
+    console.log(`  copy  ${r.name}`)
+    await cp(join(SRC, r.name), join(dest, r.name), { recursive: true, force: true })
+  }
+  console.log('Done.')
+}
+
+async function uninstall(target, flags) {
+  const dest = flags.dest ?? defaultDest(target)
+  const installed = (await status(target, dest)).filter((r) => r.state !== 'missing')
+  if (!installed.length) { console.log(`No c9n skills installed in ${dest}.`); return }
+  console.log(`Removing ${installed.length} skill(s) from ${dest}:`)
+  for (const r of installed) console.log(`  ${r.name}`)
+  if (flags.dryRun) { console.log('(dry-run) no changes made.'); return }
+  if (!flags.yes && !(await confirm(`Remove ${installed.length} skill(s)?`))) { console.log('Aborted.'); return }
+  for (const r of installed) await rm(join(dest, r.name), { recursive: true, force: true })
+  console.log('Done.')
+}
+
+async function doctor(target, flags) {
+  const dest = flags.dest ?? defaultDest(target)
+  let problems = 0
+  const check = (ok, label, hint) => {
+    console.log(`  ${ok ? '✓' : '✗'} ${label}${ok || !hint ? '' : ` — ${hint}`}`)
+    if (!ok) problems++
+  }
+  console.log(`Doctor (target: ${target})`)
+  check(existsSync(dest), `skills dir exists: ${dest}`, `run \`c9n skill install ${target}\``)
+  if (existsSync(dest)) {
+    const rows = await status(target, dest)
+    const fresh = rows.filter((r) => r.state === 'ok').length
+    const drift = rows.filter((r) => r.state === 'drift')
+    const missing = rows.filter((r) => r.state === 'missing')
+    check(!drift.length, `installed skills match package (${fresh}/${rows.length} fresh)`,
+      `${drift.length} differ (${drift.map((r) => r.name).join(', ')}) — \`c9n skill update ${target}\``)
+    if (missing.length) console.log(`  · ${missing.length} not installed (${missing.map((r) => r.name).join(', ')})`)
+    for (const r of rows) {
+      if (r.state === 'missing') continue
+      const f = join(dest, r.name, 'SKILL.md')
+      const ok = existsSync(f) && /^---\r?\n[\s\S]*?\bname:/.test(await readFile(f, 'utf8'))
+      if (!ok) check(false, `${r.name}/SKILL.md has valid frontmatter`, 'reinstall with --force')
+    }
+  }
+  check(await has('gh'), 'gh CLI available (needed by `c9n deploy` CI check)', 'install GitHub CLI or use --skip-ci')
+  check(await hasZip(), 'zip available (needed by `c9n skill install cowork`)', 'install zip')
+  if (problems) { console.log(`\n${problems} problem(s) found.`); process.exitCode = 1 }
+  else console.log('\nAll good.')
+}
+
+async function status(target, dest) {
+  const rows = []
+  for (const src of await resolveSources(target)) {
+    const name = src.split(/[\\/]/).pop(); const t = join(dest, name)
+    if (!existsSync(t)) { rows.push({ name, state: 'missing' }); continue }
+    rows.push({ name, state: (await hashDir(src)) === (await hashDir(t)) ? 'ok' : 'drift' })
+  }
+  return rows
+}
+
+async function hashDir(dir) {
+  const h = createHash('sha256')
+  for (const rel of (await walk(dir)).sort()) {
+    h.update(rel); h.update('\0'); h.update(await readFile(join(dir, rel))); h.update('\0')
+  }
+  return h.digest('hex')
+}
+
+async function walk(dir, prefix = '') {
+  const out = []
+  for (const e of await readdir(dir)) {
+    if (e === '.DS_Store') continue
+    const f = join(dir, e); const rel = prefix ? `${prefix}/${e}` : e
+    if ((await stat(f)).isDirectory()) out.push(...await walk(f, rel))
+    else out.push(rel)
+  }
+  return out
+}
+
+async function resolveSources(t) {
+  if (t === 'combined') { const c = join(SRC, 'c9n'); return existsSync(c) ? [c] : [] }
+  const out = []
+  for (const e of await readdir(SRC)) {
+    if (!e.startsWith('c9n-')) continue
+    const f = join(SRC, e); if ((await stat(f)).isDirectory()) out.push(f)
+  }
+  return out
+}
+
+function defaultDest(t) {
+  const h = homedir()
+  if (t === 'claude' || t === 'combined') return join(h, '.claude', 'skills')
+  if (t === 'codex') return join(h, '.codex', 'skills')
+  if (t === 'project') return join(process.cwd(), '.agents', 'skills')
+  return null
+}
+
+// cowork: claude.ai / Cowork share a personal skill library with NO upload API —
+// this packages upload-ready zips for manual drag-drop in Settings → Capabilities.
+async function packageForCowork(flags) {
+  const ROOT = resolve(SRC, '..')
+  // only auto-clean the default output dir — never delete a user-supplied --dest
+  const isDefaultOut = !flags.dest
+  const out = flags.dest ?? join(ROOT, 'dist', 'cowork')
+  const sources = [...await resolveSources('combined'), ...await resolveSources('cowork')]
+  if (!sources.length) throw new Error('No skills found')
+  console.log(`Packaging ${sources.length} skill zip(s) into ${out}${flags.dryRun ? ' (dry-run)' : ''}`)
+  if (!flags.dryRun) { if (isDefaultOut) await rm(out, { recursive: true, force: true }); await mkdir(out, { recursive: true }) }
+  for (const src of sources) {
+    const n = src.split(/[\\/]/).pop()
+    console.log(`  zip   ${n}.zip`)
+    if (!flags.dryRun) await zipDir(SRC, n, join(out, `${n}.zip`))
+  }
+  console.log('Done. Upload at claude.ai → Settings → Capabilities → Upload skill (shared with Cowork).')
+  console.log('Action skills (c9n-spec, c9n-deliverables) bundle their templates/scripts in the zip.')
+}
+
+function zipDir(cwd, name, outFile) {
+  return new Promise((res, rej) => {
+    execFile('zip', ['-qr', outFile, name], { cwd }, (e) => {
+      if (e && e.code === 'ENOENT') rej(new Error("'zip' command not found — install zip and retry"))
+      else if (e) rej(e); else res()
+    })
+  })
+}
+
+async function hasZip() {
+  return new Promise((res) => execFile('zip', ['-v'], (e) => res(!e || e.code !== 'ENOENT')))
+}
+
+export function skillHelp(code) {
+  console.log(`Usage: c9n skill <command> [target] [options]
+
+Commands:
+  install    copy package skills into the target (default command)
+  list       show installed/missing/drift state per skill
+  update     overwrite drifted installed skills from the package
+  uninstall  remove installed c9n skills from the target
+  doctor     diagnose skills dirs and required tooling
+
+Targets: ${TARGETS.join(' | ')}   (default: claude)
+
+Options:
+  --dest <dir>   override the target directory
+  --force        install: overwrite existing skills
+  --yes          update/uninstall: skip confirmation
+  --dry-run      show what would happen without writing`)
+  process.exit(code)
+}

package/bin/util.js

@@ -0,0 +1,45 @@
+import { execFile } from 'node:child_process'
+import { createInterface } from 'node:readline'
+
+export function run(cmd, args, opts = {}) {
+  return new Promise((res, rej) => {
+    execFile(cmd, args, opts, (e, stdout, stderr) => {
+      if (e) { e.stdout = stdout; e.stderr = stderr; rej(e) }
+      else res(String(stdout).trim())
+    })
+  })
+}
+
+export async function has(cmd) {
+  try { await run(cmd, ['--version']); return true } catch { return false }
+}
+
+export async function confirm(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  const answer = await new Promise((r) => rl.question(`${question} [y/N] `, r))
+  rl.close()
+  return /^y(es)?$/i.test(answer.trim())
+}
+
+export function parseArgs(argv, spec) {
+  // spec: { flags: ['force', ...], values: { dest: null, env: 'e', version: 'v' } }
+  const out = { _: [] }
+  for (const k of spec.flags ?? []) out[k] = false
+  for (const k of Object.keys(spec.values ?? {})) out[k] = null
+  const shorts = Object.fromEntries(Object.entries(spec.values ?? {}).filter(([, s]) => s).map(([k, s]) => [`-${s}`, k]))
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    const flag = a.startsWith('--') ? a.slice(2) : null
+    if (flag && (spec.flags ?? []).includes(flag)) { out[flag] = true; continue }
+    const key = flag && flag in (spec.values ?? {}) ? flag : shorts[a]
+    if (key) {
+      const v = argv[++i]
+      if (v === undefined) throw new Error(`${a} requires a value`)
+      out[key] = v
+      continue
+    }
+    if (a.startsWith('-')) throw new Error(`unknown option: ${a}`)
+    out._.push(a)
+  }
+  return out
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@codepassion/skills",
-  "version": "1.5.0",
-  "description": "Agent skills (SKILL.md) for CodePassion (C9N) engineering conventions.",
+  "version": "1.6.0",
+  "description": "Agent skills (SKILL.md) for CodePassion (C9N) engineering conventions, plus the c9n CLI for skill installs and tag-based deploys.",
   "license": "MIT",
   "type": "module",
   "bin": {
+    "c9n": "./bin/c9n.js",
     "c9n-skills": "./bin/c9n-skills.js"
   },
   "files": [