cyber-aced 0.3.0

package/skills/contribute-skill/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: contribute-skill
+description: Use this skill when contributing local improvements to an installed skill back to its source repo via PR.
+---
+
+# Contribute Skill
+
+When you have improved a skill you installed from another repo, this skill guides you through contributing that improvement back to the source via a pull request.
+
+## When to use
+
+- You modified a skill (global `~/.agents/skills/<name>/` or repo-internal `.agents/skills/<name>/`) and want to send the improvement upstream
+- The skill was installed from a public repo tracked in `skills-lock.json`
+
+Do NOT use for repo-native skills under this repo's `skills/<name>/` — if you're the author here, this repo IS the source.
+
+## Source repository scope (required)
+
+Only update files under the source repo's canonical skills tree:
+
+```text
+<repo-root>/skills/<skill-name>/
+  SKILL.md
+  scripts/          ← include when changed
+  …                 ← any other files in that skill folder
+```
+
+Rules:
+
+- **Always** map upstream paths to `skills/<skill-name>/…`, even when `skills-lock.json` `skillPath` points at `.agents/skills/…` or another layout in the consumer repo.
+- **Never** update `.agents/skills/`, duplicate trees, or paths outside `skills/<skill-name>/` in the source repository.
+- Include every changed file under that skill folder (e.g. `scripts/*.mjs`), not only `SKILL.md`.
+- Never include `SKILL.local.md` — machine-local augmentations stay local.
+
+Derive paths:
+
+| Input | Upstream path |
+| --- | --- |
+| Lock key / folder name `skillify` | `skills/<skill-name>/` |
+| `skillPath`: `.agents/skills/skillify/SKILL.md` | `skills/<skill-name>/SKILL.md` |
+| `skillPath`: `skills/fix-security-pr/SKILL.md` | `skills/fix-security-pr/SKILL.md` |
+
+## Steps
+
+### 1. Identify the skill(s) to patch
+
+From context or ask the user. Look up origin using this skill's own `source.mts` script, which resolves in a fixed order: the repo-local lock, then the global lock, then `npx skills find`, returning the FIRST hit:
+
+```bash
+node "<this-skill's-dir>/scripts/source.mts" <skill-name> --format json
+```
+
+Output is JSON: `{ name, source, sourceUrl, skillPath, foundIn }`. Extract `source` (`owner/repo`). `foundIn` tells you which rung resolved it (`repo`, `global`, or `npx-skills`).
+
+If the script exits non-zero (`foundIn: null`), fall back to reading the lockfiles by hand, in the same order:
+
+```bash
+# 1. Repo-local (committed, version 1 schema):
+jq '.skills["<skill-name>"]' skills-lock.json
+
+# 2. Global (version 3 schema, has sourceUrl):
+jq '.skills["<skill-name>"]' ~/.agents/.skill-lock.json
+
+# 3. npx skills find <skill-name>
+```
+
+If none of the three resolve, ask the user for `owner/repo` and the skill folder name — never guess.
+
+For multiple related skills (user confirms one PR), repeat file discovery for each `skills/<name>/` directory.
+
+### 2. Find the local skill directory
+
+| Kind | Local directory |
+| --- | --- |
+| Global | `~/.agents/skills/<name>/` |
+| Repo internal | `.agents/skills/<name>/` |
+
+Collect files to contribute (exclude machine-local files):
+
+```bash
+find "<local-dir>" -type f ! -name 'SKILL.local.md' | sort
+```
+
+### 3. Diff against source
+
+For each local file, map to `skills/<skill-name>/<relative-path>` and compare to upstream on the default branch.
+
+List upstream skill folder (optional sanity check):
+
+```bash
+gh api "repos/<owner>/<repo>/contents/skills/<skill-name>?ref=<default-branch>" \
+  --jq '.[] | .path'
+# If scripts/ exists, list nested files too:
+gh api "repos/<owner>/<repo>/contents/skills/<skill-name>/scripts?ref=<default-branch>" \
+  --jq '.[]? | .path' 2>/dev/null
+```
+
+Per-file diff:
+
+```bash
+UPSTREAM="skills/<skill-name>/SKILL.md"
+gh api "repos/<owner>/<repo>/contents/${UPSTREAM}" --jq '.content' | base64 -d > /tmp/upstream.md
+diff /tmp/upstream.md "<local-dir>/SKILL.md"
+```
+
+- **No diffs** across all mapped files → nothing to contribute; stop
+- **Any diff** → show unified diffs and get user confirmation before proceeding
+
+### 4. Check write access
+
+```bash
+gh api repos/<owner>/<repo> --jq '{push: .permissions.push, default: .default_branch}'
+```
+
+- `push: true` → branch on `owner/repo`
+- `push: false` → `gh repo fork <owner>/<repo> --clone=false`, then use `<your-username>/<repo>`
+
+### 5. Create branch and push (single commit — Git Data API)
+
+Use the **Git Data API** so all files land in **one commit**. Do not use `PUT /contents/{path}` per file (that creates one commit per file).
+
+Set variables:
+
+```bash
+OWNER=<owner>
+REPO=<repo>
+REPO_FULL="${OWNER}/${REPO}"
+DEFAULT_BRANCH=main   # from step 4
+BRANCH="patch/<skill-name>-<short-slug>"   # or shared slug for multi-skill PR
+MSG="fix(<skill-name>): <description>"
+SKILL_NAME=<skill-name>
+LOCAL_DIR="<absolute-local-skill-dir>"
+```
+
+#### 5a. Create branch ref from default branch tip
+
+```bash
+BASE_SHA=$(gh api "repos/${REPO_FULL}/git/refs/heads/${DEFAULT_BRANCH}" --jq '.object.sha')
+BASE_TREE=$(gh api "repos/${REPO_FULL}/git/commits/${BASE_SHA}" --jq '.tree.sha')
+
+gh api "repos/${REPO_FULL}/git/refs" \
+  --method POST \
+  --field ref="refs/heads/${BRANCH}" \
+  --field sha="${BASE_SHA}"
+```
+
+If the branch already exists, skip creation and set `BASE_SHA` to the branch tip instead (for amending, prefer a fresh branch).
+
+#### 5b. Create blobs and tree entries for each local file
+
+Build a JSON array of tree items. Each local file maps to `skills/${SKILL_NAME}/<relative-path>`.
+
+**Use temp files for `--input`**, not inline `$(jq …)`. Embedding file content in the shell argument hits `ARG_MAX` and fails with errors like `file name too long` on typical `SKILL.md` sizes.
+
+```bash
+TREE_ITEMS='[]'
+while IFS= read -r -d '' file; do
+  rel="${file#${LOCAL_DIR}/}"
+  upstream_path="skills/${SKILL_NAME}/${rel}"
+
+  jq -n --rawfile content "$file" '{content: $content, encoding: "utf-8"}' > /tmp/patch-blob-input.json
+  blob_sha=$(gh api "repos/${REPO_FULL}/git/blobs" \
+    --method POST \
+    --input /tmp/patch-blob-input.json \
+    --jq '.sha')
+
+  TREE_ITEMS=$(jq -n \
+    --argjson items "$TREE_ITEMS" \
+    --arg path "$upstream_path" \
+    --arg sha "$blob_sha" \
+    '$items + [{path: $path, mode: "100644", type: "blob", sha: $sha}]')
+done < <(find "$LOCAL_DIR" -type f ! -name 'SKILL.local.md' -print0)
+```
+
+Repeat the loop for additional skills in the same PR (append to `TREE_ITEMS` with each skill's `SKILL_NAME` and `LOCAL_DIR`).
+
+#### 5c. Create tree, commit, update branch ref
+
+Write tree and commit payloads to temp files as well (large multi-skill `TREE_ITEMS` can also exceed shell limits):
+
+```bash
+jq -n \
+  --arg base "$BASE_TREE" \
+  --argjson tree "$TREE_ITEMS" \
+  '{base_tree: $base, tree: $tree}' > /tmp/patch-tree-input.json
+NEW_TREE=$(gh api "repos/${REPO_FULL}/git/trees" \
+  --method POST \
+  --input /tmp/patch-tree-input.json \
+  --jq '.sha')
+
+jq -n \
+  --arg msg "$MSG" \
+  --arg tree "$NEW_TREE" \
+  --arg parent "$BASE_SHA" \
+  '{message: $msg, tree: $tree, parents: [$parent]}' > /tmp/patch-commit-input.json
+COMMIT_SHA=$(gh api "repos/${REPO_FULL}/git/commits" \
+  --method POST \
+  --input /tmp/patch-commit-input.json \
+  --jq '.sha')
+
+gh api "repos/${REPO_FULL}/git/refs/heads/${BRANCH}" \
+  --method PATCH \
+  --field sha="${COMMIT_SHA}"
+```
+
+Result: exactly **one commit** on the patch branch containing all updated paths under `skills/<skill-name>/`.
+
+### 6. Open PR
+
+```bash
+gh pr create \
+  --repo "${REPO_FULL}" \
+  --base "${DEFAULT_BRANCH}" \
+  --head "${BRANCH}" \
+  --title "fix(<skill-name>): <description>" \
+  --body "$(cat <<'EOF'
+## Summary
+
+<what changed and why — only under `skills/<skill-name>/`>
+
+## Test plan
+
+- [ ] Run improve-skill / `audit validate` against the updated skill(s)
+- [ ] Confirm no files outside `skills/` were modified
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+### 7. Report
+
+Output the PR URL. After merge, run `npx skills update` in the consumer repo to refresh `skills-lock.json` hashes.
+
+## What NOT to do
+
+- Do not include `SKILL.local.md` content in the PR
+- Do not push without showing diffs and getting user confirmation
+- Do not create a PR if every mapped file is identical to upstream
+- Do not update `.agents/skills/` or any path outside `skills/<skill-name>/` in the source repo
+- Do not use Contents API `PUT` per file (multi-commit noise); use Git Data API (section 5)

package/skills/contribute-skill/scripts/source.mts

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// source — the concrete skill-source-resolution engine for contribute-skill. Given a skill name,
+// answers where its upstream repo lives so the skill's "Locating the source repo" step never
+// guesses: it walks a fixed precedence ladder — repo-local lock, then global lock, then
+// `npx skills find` — and returns the FIRST hit; nothing downstream of a hit is consulted. When
+// none of the three resolve, every field comes back null so the caller surfaces the gap to the
+// user instead of fabricating an owner/repo.
+//
+// Resolution order (frozen, do not reorder):
+//   1. <root>/skills-lock.json                — repo-local lock (version 1 schema)
+//   2. <homeDir>/.agents/.skill-lock.json      — global lock (version 3 schema, carries sourceUrl)
+//   3. `npx --yes skills find <skillName>`     — shells out, parses "owner/repo@skillName" hits
+//   4. not found                                — source/sourceUrl/skillPath/foundIn all null
+//
+// Pure functions are exported for node:test; running the file directly drives the CLI. No deps
+// (the repo's node-≥23.6 convention). Imports node:* only.
+
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+export interface SkillSourceResult {
+	name: string
+	source: string | null
+	sourceUrl: string | null
+	skillPath: string | null
+	foundIn: 'repo' | 'global' | 'npx-skills' | null
+}
+
+export type NpxFindFn = (skillName: string) => string
+
+// ── lockfile reads ──
+
+export function readLock(lockPath: string): Record<string, unknown> | null {
+	if (!existsSync(lockPath)) return null
+	try {
+		return JSON.parse(readFileSync(lockPath, 'utf8'))
+	} catch {
+		return null
+	}
+}
+
+// ── npx skills find output parsing ──
+
+// Strips ANSI color codes, then scans for "owner/repo@skillName" tokens; returns the first whose
+// found name equals skillName.
+export function parseNpxSkillsOutput(raw: string, skillName: string): { source: string } | null {
+	const ansiRe = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g')
+	const clean = raw.replace(ansiRe, '')
+	const regex = /([a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+)@([a-zA-Z0-9_-]+)/g
+	let match: RegExpExecArray | null
+	while ((match = regex.exec(clean)) !== null) {
+		const [, ownerRepo, foundName] = match
+		if (foundName === skillName) return { source: ownerRepo! }
+	}
+	return null
+}
+
+// Real shellout: `npx --yes skills find <skillName>`, combined stdout+stderr, empty on any
+// failure (npx missing, timeout, non-zero exit with no parseable output).
+export function defaultNpxFind(skillName: string): string {
+	try {
+		const result = spawnSync('npx', ['--yes', 'skills', 'find', skillName], {
+			encoding: 'utf8',
+			timeout: 4_000,
+			env: { ...process.env, NO_COLOR: '1', CI: '1' },
+		})
+		return (result.stdout ?? '') + (result.stderr ?? '')
+	} catch {
+		return ''
+	}
+}
+
+// ── resolution ladder ──
+
+// Resolves a skill's source repo by walking repo-local lock -> global lock -> npx skills find,
+// returning the FIRST hit (nothing downstream of a hit is consulted). `homeDir` and `npxFind` are
+// injectable for deterministic node:test coverage; production callers can omit both.
+export function findSkillSource(
+	skillName: string,
+	root: string,
+	homeDir: string = homedir(),
+	npxFind: NpxFindFn = defaultNpxFind,
+): SkillSourceResult {
+	const repoLock = readLock(join(root, 'skills-lock.json'))
+	if (repoLock) {
+		const entry = (repoLock as { skills?: Record<string, Record<string, string>> }).skills?.[skillName]
+		if (entry?.source) {
+			return {
+				name: skillName,
+				source: entry.source,
+				sourceUrl: `https://github.com/${entry.source}`,
+				skillPath: entry.skillPath ?? null,
+				foundIn: 'repo',
+			}
+		}
+	}
+
+	const globalLock = readLock(join(homeDir, '.agents', '.skill-lock.json'))
+	if (globalLock) {
+		const entry = (globalLock as { skills?: Record<string, Record<string, string>> }).skills?.[skillName]
+		if (entry?.source) {
+			return {
+				name: skillName,
+				source: entry.source,
+				sourceUrl: entry.sourceUrl ?? `https://github.com/${entry.source}`,
+				skillPath: entry.skillPath ?? null,
+				foundIn: 'global',
+			}
+		}
+	}
+
+	const out = npxFind(skillName)
+	const parsed = parseNpxSkillsOutput(out, skillName)
+	if (parsed) {
+		return {
+			name: skillName,
+			source: parsed.source,
+			sourceUrl: `https://github.com/${parsed.source}`,
+			skillPath: `skills/${skillName}/SKILL.md`,
+			foundIn: 'npx-skills',
+		}
+	}
+
+	return {
+		name: skillName,
+		source: null,
+		sourceUrl: null,
+		skillPath: null,
+		foundIn: null,
+	}
+}
+
+// ── CLI ──
+
+function flag(argv: string[], name: string): string | undefined {
+	const i = argv.indexOf(name)
+	return i === -1 ? undefined : argv[i + 1]
+}
+
+// The lone positional arg: any token that isn't a known flag or a known flag's value.
+function positional(argv: string[]): string | undefined {
+	const consumed = new Set<number>()
+	for (const name of ['--root', '--format']) {
+		const i = argv.indexOf(name)
+		if (i !== -1) {
+			consumed.add(i)
+			consumed.add(i + 1)
+		}
+	}
+	for (let i = 0; i < argv.length; i++) {
+		if (!consumed.has(i)) return argv[i]
+	}
+	return undefined
+}
+
+export function main(argv: string[]): number {
+	const root = flag(argv, '--root') ?? '.'
+	const format = flag(argv, '--format') ?? 'text'
+	const skillName = positional(argv)
+
+	if (!skillName) {
+		process.stdout.write('usage: source <skill-name> [--root <path>] [--format json|text]\n')
+		return 1
+	}
+
+	const result = findSkillSource(skillName, root)
+
+	if (format === 'json') {
+		process.stdout.write(`${JSON.stringify(result)}\n`)
+	} else {
+		if (result.foundIn) {
+			process.stdout.write(`${result.name}: ${result.source} (found in ${result.foundIn})\n`)
+			if (result.skillPath) process.stdout.write(`  skillPath: ${result.skillPath}\n`)
+			process.stdout.write(`  sourceUrl: ${result.sourceUrl}\n`)
+		} else {
+			process.stdout.write(`${result.name}: not found in repo lock, global lock, or npx skills find\n`)
+		}
+	}
+
+	return result.foundIn ? 0 : 1
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+	process.exit(main(process.argv.slice(2)))
+}

package/skills/define-agent/README.md

@@ -0,0 +1,40 @@
+# define-agent
+
+Create or improve an agent definition — a named, reusable role that can be delegated as a subagent, loaded in-context as a persona, or both.
+
+## When to use
+
+Use this skill when you want to author a new agent definition or improve an existing one.
+
+Good triggers include:
+
+- Building a conductor, orchestrator, or persona for a workflow
+- Adding a reusable role to a plugin or project
+- Deciding between a delegated worker and an interactive in-context persona
+- Scaffolding the canonical file + runtime symlinks + companion command in one pass
+
+## What it does
+
+The skill walks you through three decisions before writing anything:
+
+1. **Mode** — Delegated (subagent only), Invokable (dual-mode: subagent + in-context via a companion command), or In-context only
+2. **Placement** — user-global (`~/.agents/agents/`), project (`.agents/agents/`), or inside a plugin (`plugins/<name>/agents/`)
+3. **Runtimes** — which runtime symlinks to create (Claude Code, Cursor, Codex)
+
+It then collects the role, responsibilities, output format, human-in-the-loop rules, and out-of-scope list — drafts the agent definition, runs quality checks (F1–F9, B1–B8), and for Invokable mode scaffolds a thin companion command file that loads the agent into the current session.
+
+## Dual-mode (Invokable) pattern
+
+The Invokable mode implements the **dual-mode persona** pattern:
+
+- The agent definition file is the single source of truth for the role
+- A companion command reads that file into the current context at session start
+- The same role body backs both delegation (subagent spawn) and in-context adoption (interactive steering)
+
+This lets you hand off work to the agent autonomously, or step into its role yourself and operate at the same level.
+
+## Install
+
+```bash
+npx skills add cyberuni/cyberplace --skill aced/define-agent
+```