@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/validate-skill.sh

@@ -0,0 +1,257 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+target="${1:-.}"
+
+if [[ ! -e "$target" ]]; then
+  echo "target_not_found: $target" >&2
+  exit 2
+fi
+
+for required_cmd in ruby rg; do
+  if ! command -v "$required_cmd" >/dev/null 2>&1; then
+    echo "missing_required_command: $required_cmd" >&2
+    exit 2
+  fi
+done
+
+if [[ -f "$target/SKILL.md" ]]; then
+  roots=("$target")
+else
+  roots=()
+  while IFS= read -r skill_file; do
+    roots+=("$(dirname "$skill_file")")
+  done < <({ find "$target" -mindepth 2 -maxdepth 2 -name SKILL.md -type f
+             # Repo-root runs over a skills/<name>/SKILL.md layout: pick up depth-3
+             # roots ONLY under a literal skills/ directory (never nested fixtures).
+             [ -d "$target/skills" ] && find "$target/skills" -mindepth 2 -maxdepth 2 -name SKILL.md -type f
+           } | sort -u)
+fi
+
+if [[ "${#roots[@]}" -eq 0 ]]; then
+  echo "no_skill_roots_found: $target" >&2
+  exit 2
+fi
+
+echo "validating ${#roots[@]} skill root(s)"
+
+ruby -ryaml -e '
+ARGV.each do |root|
+  data = YAML.load_file(File.join(root, "SKILL.md"))
+  %w[name description].each do |key|
+    if data[key].to_s.strip.empty?
+      warn "missing_frontmatter_#{key}: #{File.join(root, "SKILL.md")}"
+      exit 1
+    end
+  end
+  Dir[File.join(root, "agents", "*.yaml")].each { |f| YAML.load_file(f) }
+end
+puts "yaml_ok"
+' "${roots[@]}"
+
+ruby -e '
+roots = ARGV
+missing = []
+roots.each do |root|
+  files = [File.join(root, "SKILL.md")] + Dir[File.join(root, "references", "*.md")]
+  files.each do |path|
+    next unless File.file?(path)
+    text = File.read(path)
+    text.scan(/`([^`]+\.md)`/).flatten.each do |ref|
+      next if ref.include?("*")
+      # Cross-package reference: `<pkg>/references/...` resolves against the
+      # skills/ parent (sibling skill package). Checked only when the sibling
+      # package directory exists — a dangling FILE inside an existing package
+      # is flagged; an absent package dir is out of recall (the path may point
+      # outside the skills tree). Brace-glob refs (`{a,b}-dev.md`) are skipped
+      # like `*` patterns: they name a set, not one file.
+      cross = ref.match(/\A([a-z0-9][a-z0-9-]*)\/(references\/.+\.md)\z/)
+      if cross && !ref.start_with?("references/") && !ref.include?("{")
+        pkg_root = File.expand_path(cross[1], File.expand_path("..", root))
+        if File.directory?(pkg_root) && !File.exist?(File.join(pkg_root, cross[2]))
+          missing << [File.basename(root), path.sub(root + "/", ""), ref]
+        end
+        next
+      end
+      next unless ref.start_with?("references/") || ref.start_with?("../")
+      candidate =
+        if ref.start_with?("../")
+          File.expand_path(ref, root)
+        else
+          File.join(root, ref)
+        end
+      missing << [File.basename(root), path.sub(root + "/", ""), ref] unless File.exist?(candidate)
+    end
+  end
+end
+if missing.empty?
+  puts "markdown_references_ok"
+else
+  warn "missing_markdown_references:"
+  missing.each { |skill, path, ref| warn "  #{skill}/#{path} -> #{ref}" }
+  exit 1
+end
+' "${roots[@]}"
+
+leak_status=0
+# Leak-detector machinery is excluded because it MUST embed the very patterns it
+# hunts (literal `/Users/`, `glpat-`, token prefixes) as detection rules — the
+# same reason this scanner self-excludes validate-skill.sh. generic-r0-leak-scan.sh
+# is the public R0 fallback detector and test_generic_r0_leak_scan.sh is its
+# fixture test; test_validate_skill_credential_cwd.sh is this scanner's own
+# cwd-independence regression test and likewise plants `/Users/` fixtures. All are
+# independently regression-covered by the detector's `--self-test` and their
+# integration tests, so excluding them here does not weaken real leak coverage of
+# authored skill content. (Rationale recorded per the scripts/ AGENTS.md allowlist
+# rule.)
+for root in "${roots[@]}"; do
+  # rg matches --glob patterns relative to its working directory, so running this
+  # gate from a subdirectory (e.g. scripts/, as the tests and the mandated
+  # worktree workflow do) would stop the self-exclusion globs from matching and
+  # the detector scripts would flag their OWN embedded pattern literals (a
+  # cwd-dependent false positive). cd into the root and search '.' so the globs
+  # are always anchored to the search root. Roots are always skill dirs (each has
+  # SKILL.md), never the repo root, so '.' never pulls in a top-level .git file.
+  # `cd "$root" || exit 3` distinguishes a vanished/inaccessible root (exit 3 ->
+  # fail closed below) from a genuine rg no-match (exit 1); scanning "." keeps the
+  # globs anchored to the search root regardless of the caller's cwd.
+  if leak_output="$(cd "$root" || exit 3; rg -n --hidden \
+    --glob '!**/scripts/validate-skill.sh' \
+    --glob '!**/scripts/generic-r0-leak-scan.sh' \
+    --glob '!**/scripts/test_generic_r0_leak_scan.sh' \
+    --glob '!**/scripts/test_validate_skill_credential_cwd.sh' \
+    'glpat-|PRIVATE-TOKEN: ?[a-zA-Z0-9]|oauth2:[^[:space:]@]+@|/Users/[^/[:space:]]+|\bsk-[A-Za-z0-9_-]{20,}' \
+    .)"; then
+    # Re-attach the root so offenders stay locatable across multiple skill roots.
+    # Pure bash (no sed) so a root path containing sed-special chars (& #) cannot
+    # corrupt the reported offender path or abort the pipeline.
+    while IFS= read -r line; do
+      printf '%s\n' "${root%/}/${line#./}"
+    done <<<"$leak_output"
+    leak_status=1
+  else
+    rg_status=$?
+    # 1 = rg clean (no matches). 2 = rg error, 3 = cd into root failed: both fail
+    # closed so an unscannable root is never silently reported clean.
+    if [[ "$rg_status" -ne 1 ]]; then
+      echo "credential_path_scan_error: scan exited $rg_status for $root" >&2
+      exit 1
+    fi
+  fi
+done
+if [[ "$leak_status" -eq 0 ]]; then
+  echo "credential_path_scan_ok"
+else
+  echo "credential_or_personal_path_scan_failed" >&2
+  exit 1
+fi
+
+ruby -e '
+roots = ARGV
+warnings = []
+roots.each do |root|
+  files = [File.join(root, "SKILL.md")] + Dir[File.join(root, "references", "*.md")]
+  files.each do |path|
+    next unless File.file?(path)
+    lines = File.readlines(path, chomp: true)
+    in_fence = false
+    fence_start = nil
+    fence_lines = 0
+    blockquote_lines = 0
+    timestamp_lines = 0
+    placeholder_urls = []
+
+    lines.each_with_index do |line, index|
+      if line.start_with?("```")
+        if in_fence
+          if fence_lines > 80
+            warnings << "#{path.sub(root + "/", "")}:#{fence_start}: long_fenced_block_lines=#{fence_lines}"
+          end
+          in_fence = false
+          fence_start = nil
+          fence_lines = 0
+        else
+          in_fence = true
+          fence_start = index + 1
+          fence_lines = 0
+        end
+        next
+      end
+
+      fence_lines += 1 if in_fence
+      blockquote_lines += 1 if line.start_with?("> ")
+      timestamp_lines += 1 if line.match?(/\b\d{1,2}:\d{2}:\d{2}\b/)
+      line.scan(%r{https?://[^\s)>\]]+}).flatten.each do |url|
+        placeholder_urls << "#{index + 1}:#{url}" if url.match?(%r{/(search|topics?|tags?|explore)([/?#]|$)}) || url.match?(%r{https?://[^/]+/?$})
+      end
+    end
+
+    warnings << "#{path.sub(root + "/", "")}: blockquote_heavy_lines=#{blockquote_lines}" if blockquote_lines > 40
+    warnings << "#{path.sub(root + "/", "")}: timestamp_like_lines=#{timestamp_lines}" if timestamp_lines > 20
+    placeholder_urls.first(5).each { |item| warnings << "#{path.sub(root + "/", "")}:#{item}: placeholder_or_generic_url" }
+  end
+end
+
+if warnings.empty?
+  puts "source_dump_heuristics_ok"
+else
+  warn "source_dump_heuristics_warn:"
+  warnings.each { |warning| warn "  #{warning}" }
+end
+' "${roots[@]}"
+
+if [[ "${CHECK_INSTALL_VISIBILITY:-0}" = "1" ]]; then
+  visible_count=0
+  IFS=: read -r -a host_skill_dirs <<< "${HOST_SKILL_DIRS:-${CODEX_HOME:-$HOME/.codex}/skills:$HOME/.claude/skills}"
+  for root in "${roots[@]}"; do
+    name="$(ruby -ryaml -e 'puts YAML.load_file(ARGV[0])["name"]' "$root/SKILL.md")"
+    for skill_home in "${host_skill_dirs[@]}"; do
+      if [[ -e "$skill_home/$name" ]]; then
+        if [[ -e "$skill_home/$name/SKILL.md" ]]; then
+          echo "install_visible: $skill_home/$name"
+          visible_count=$((visible_count + 1))
+        else
+          echo "install_broken: $skill_home/$name" >&2
+          exit 1
+        fi
+      fi
+    done
+  done
+  if [[ "$visible_count" -eq 0 ]]; then
+    echo "install_visibility_not_found"
+  fi
+else
+  echo "install_visibility_skipped: set CHECK_INSTALL_VISIBILITY=1 to verify host skill symlinks"
+fi
+
+if git -C "$target" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  # Scan git remotes for an embedded credential / leaked token. Per remote URL:
+  #  - any glpat- / PRIVATE-TOKEN / oauth2: anywhere is always a failure;
+  #  - a `://user:pass@` credential is a failure UNLESS the password is the live
+  #    ephemeral CI job token (GitLab CI checks out via
+  #    `gitlab-ci-token:<CI_JOB_TOKEN>@host`, which is not a committed secret).
+  # The password is parsed from the authority and compared LITERALLY to CI_JOB_TOKEN
+  # (no regex on the token — URL-safe is not regex-safe), and only the authority
+  # (before the first `/`) is inspected, so a token echoed into a path/query can't
+  # suppress scanning of the real credential. Outside CI, CI_JOB_TOKEN is unset, so
+  # every `user:pass@` fails — the original strict behavior.
+  remote_fail=0
+  while read -r _ url _; do
+    [[ -z "${url:-}" ]] && continue
+    if printf '%s' "$url" | rg -q 'oauth2:|glpat-|PRIVATE-TOKEN'; then remote_fail=1; break; fi
+    rest="${url#*://}"; [[ "$rest" == "$url" ]] && continue       # no scheme:// → no inline credential
+    authority="${rest%%/*}"; [[ "$authority" != *@* ]] && continue
+    userinfo="${authority%@*}"; [[ "$userinfo" != *:* ]] && continue
+    pass="${userinfo#*:}"; [[ -z "$pass" ]] && continue
+    [[ -n "${CI_JOB_TOKEN:-}" && "$pass" == "$CI_JOB_TOKEN" ]] && continue
+    remote_fail=1; break
+  done < <(git -C "$target" remote -v)
+  if [[ "$remote_fail" -eq 1 ]]; then
+    echo "remote_token_scan_failed" >&2
+    exit 1
+  fi
+  git -C "$target" diff --check
+  echo "git_checks_ok"
+fi
+
+echo "skill_validation_ok"

package/dist/assets/marketplace/plugins/ccl-skills/skills/terminal-cli-dev/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: terminal-cli-dev
+description: Use when designing, implementing, reviewing, debugging, testing, or shipping command-line, terminal, text UI, PTY, ANSI-rendered, keyboard-driven, or console product surfaces, including the command/subcommand/flag/help contract (owned here even when nothing is rendered), layout, input, color, wrapping, selection, scrollback, accessibility, performance, and real terminal verification. Triggers also include "命令行/TUI 界面怎么做", "CLI 界面怎么写", "重构这个终端/TUI 命令或界面(局部)", "refactor a terminal command / TUI view". Skip when the ask is CLI/tooling implementation in a language whose dev skill owns it, without terminal-UI concerns ("用 Python 写个命令行工具" → python-service-dev, Go CLI → go-microservice-dev); a CLI in a language with no such owner stays here.
+---
+
+# Terminal CLI Dev
+
+Use this skill for terminal and command-line product surfaces. It owns implementation mechanics for text UIs, console workflows, ANSI-rendered output, PTY-backed interaction, keyboard input, terminal capability handling, and real terminal verification. It does not own web browsers, mobile apps, mini-program hosts, backend services, or product design judgment.
+
+## Routing
+
+- Use `product-rd-workflow` first when the work spans product intent, design, implementation, testing, release, or postmortem follow-up.
+- Use `product-ui-ux-design` before or alongside coding when the terminal surface is user-facing: hierarchy, density, interaction model, copy, states, accessibility, and visual acceptance.
+- Use `testing-strategy` to choose unit, snapshot, PTY, integration, and real-terminal evidence; return here for terminal-specific implementation mechanics.
+- Use `defect-diagnosis` first for rendering regressions, input bugs, flicker, selection/copy issues, broken resize behavior, color/readability defects, or flaky terminal tests.
+- Use `platform-observability` for telemetry/log schema and `platform-release-engineering` for rollout of behavior-changing defaults, persisted settings migrations, or terminal capability fallbacks. Do not treat CLI package distribution, installer, or updater mechanics as covered unless the release skill has explicit terminal distribution guidance.
+
+## Core Workflow
+
+Before editing terminal UI code, output formatting, keyboard handling, PTY integration, layout, color/theme logic, or terminal tests, complete enough analysis and planning for the change to be reviewable. Scale the plan to risk: a small copy or formatting change can use a short note; a new interactive surface, renderer, input mode, terminal capability change, high-risk action, release behavior, or bug fix needs explicit scenarios, target terminal environments, verification commands, and stop conditions.
+
+Repo-local agent contracts (`AGENTS.md` at the repo root and in source directories) are part of the delivery contract: when a change moves a stable boundary, generated surface, workflow, or directory-local rule, update the nearest contract in the same MR and keep coverage in sync per `product-rd-workflow`'s spec / repo-contract sync gate.
+
+When checking a terminal/CLI project against team standards, split conformance into deterministic and agent review evidence. Deterministic checks cover exit-code conventions (0 on success / non-zero on failure; `os.Exit`/`process.exit`/`sys.exit` only in the entrypoint, not the library layer), stdout-vs-stderr routing (primary/machine-readable output to stdout, logs/diagnostics/progress/prompts to stderr), `--help`/`--version`/`--json` (or `--plain`) flag presence in the parser tree, signal-handler registration, `NO_COLOR`/isatty handling, and absence of hardcoded ANSI escape literals outside the rendering module. Agent review checks cover terminal-state restoration on every exit path, capability-fallback completeness, the `NO_COLOR`/non-TTY/`TERM=dumb`/`--no-color` color-disable matrix, prompt-only-on-TTY (`--no-input` honored), error actionability, and whether tests prove real-terminal behavior rather than only string snapshots. For the per-language deterministic executor list (Go `errcheck`/`forbidigo`, Rust Clippy `print_stdout`/`exit`/`unwrap_used`, Ruff `T201`/`PLR1722`) and the shipped `client-terminal-ansi-check.py` (CB-1: flags hardcoded ANSI escape literals outside an allowlisted rendering module), see `testing-strategy/references/fitness-functions.md` §4.1.3 (client language-basics; spec 006). CLI/TUI invariants have almost no off-the-shelf CLI-aware linter, so most of this contract is agent-review plus a few repository checks — prefer a capability-aware lib over hand-emitted escapes.
+
+1. Classify the terminal surface.
+   - One-shot CLI output, interactive prompt, full-screen TUI, embedded terminal panel, log/status stream, diff/code viewer, installer/updater, or background task display.
+   - Output-only, input-driven, mouse/selection-aware, PTY-backed, or mixed.
+   - Plain text, ANSI-styled, hyperlink-capable, alternate-screen, scrollback-preserving, or terminal-query-dependent.
+
+2. Define the terminal contract before coding.
+   - Supported terminals, shells, OS families, remote/headless behavior, CI behavior, and fallback mode.
+   - Whether the feature requires a TTY, raw mode, cursor control, bracketed paste, mouse reporting, focus reporting, hyperlinks, truecolor, or scrollback control.
+   - Behavior when capabilities are missing, disabled by user preference, blocked by a multiplexer, proxied through a remote shell, or unavailable in CI.
+   - State ownership for input focus, modal overlays, selection, scroll position, unseen output, pending operations, and resize recovery.
+   - For UI/UX redesign slices meeting `product-ui-ux-design`'s page-slice trigger conditions — that gate's trigger list is authoritative and must be checked, not paraphrased, whenever a screen/surface change could be a redesign, restyle, new-style declaration, structural/visual-system change, continuation, or redesigned-surface reference — apply its cross-stack page-slice gate before terminal mechanics: RED-first focused assertion, IA regrouping by user intent/consequence, behavior-contract preservation, state matrix, rendered evidence, and the design verdict (`accepted` / `rejected` / `pending`; missing = `pending`, and `design-rejected` blocks complete/MR-ready/normal/draft MR per the **Rejected-surface rule**). Translate Web/App examples into terminal cell-grid proof instead of copying browser or device commands.
+   - For any user-facing visible terminal UI change, also record `product-ui-ux-design`'s implementation-owner checkpoint before the first edit — its field list (design/stack/test owners, entry-rule evidence, rendered/device evidence status) and copy-only path are authoritative there; load the named owner skills rather than only naming them, and treat a completion claim without `captured/verified` rendered evidence as incomplete — an explicitly accepted gap closes the slice only as `pre-runtime-test ready` / handoff, never as complete/done.
+
+3. Render by terminal cells, not string length.
+   - Measure display width with ANSI-stripped, Unicode-aware logic. Cover combining marks, emoji, East Asian width, zero-width code points, variation selectors, and control characters.
+   - Preserve grapheme and wide-character boundaries when wrapping, truncating, slicing, highlighting, cursoring, or copying. Never split the trailing cell of a wide character into visible content.
+   - Keep a screen-buffer model for interactive surfaces: cell char, style, width, hyperlink, selectable/non-selectable status, soft-wrap continuation, and damage bounds.
+   - Treat soft-wrapped rows differently from hard newlines so selection/copy reconstructs logical text instead of copying padded screen rows.
+
+4. Handle color and ANSI state deliberately.
+   - Respect explicit no-color or reduced-color settings.
+   - Choose truecolor, 256-color, or plain fallback from actual capability and user preference; avoid assuming environment variables are complete truth.
+   - Keep color as enhancement, not the only state carrier. Important states need text, symbols, underline, inverse, or another readable fallback.
+   - Strip or replace background/inverse styles intentionally for overlays such as selection and search highlights so existing syntax or status colors do not make the current target unreadable.
+   - Reset style transitions cleanly; avoid leaking style state across lines, prompts, streamed chunks, or restored screen regions.
+
+5. Make input, focus, and selection stateful.
+   - Parse keys and terminal responses separately; response sequences should not be mistaken for user keypresses.
+   - Gate shortcuts, mouse events, paste, focus, modal priority, and text input by active mode.
+   - Treat terminal paste/clipboard ingress as a stateful input boundary, configurable keybindings as an input-to-action control boundary, and modal (vi-like) text editing as a command-language state machine — never as ordinary text handling or independent shortcuts. Before touching any of these three surfaces, load `references/input-state-machines.md`; its per-surface bullets (bracketed-paste parser state, keymap schema/generation binding, operator/motion/register semantics, and each surface's bounded-diagnostics rule) are obligations, not advice.
+   - Model selection as anchor plus focus, not a transient highlight. Preserve copied text when scroll movement pushes selected rows out of the visible buffer.
+   - Support word/line selection with Unicode-aware boundaries where applicable, and mark gutters, borders, status chrome, or generated line numbers as non-selectable when copying content.
+   - Fence stale callbacks after mode changes, resize, unmount, stream finality, interrupted prompts, or screen replacement.
+
+6. Layout for constrained terminals.
+   - Define minimum width/height behavior, truncation strategy, collapse order, and non-interactive fallback.
+   - Keep primary task content readable before decorative status, helper text, or secondary panels.
+   - Recompute layout on resize and clamp scroll/selection/cursor coordinates to valid bounds.
+   - Preserve scrollback intentionally: clear only the intended region, avoid destroying history unless the command contract says so, and use platform-specific clear behavior conservatively.
+   - For streaming output, keep user scroll position stable when they are reading history; show a jump/new-output affordance instead of force-pinning every frame.
+   - When streaming **rich/markdown** output into append-only scrollback, split the stream into a committed *stable* region and a mutable *tail*, because a later token can retroactively reshape earlier output and scrollback cannot be un-printed. The invariant: **never commit reshape-prone content to an irreversible surface; hold it mutable until it is stable** — and **sanitize terminal control sequences out of streamed content before rendering (a security boundary: untrusted content must not be able to deceive through the terminal)**. Before implementing or reviewing any streaming-rich-output path, load `references/streaming-rich-output.md` for the full contract: structural-boundary commits with one-line lookbehind, deferred-resolution construct holdback, bounded tail and re-render cost (CPU-DoS cap), finalize flush, the control-sequence/chrome-spoofing/Trojan-source defenses, adaptive drain pacing, and the no-baked-width rule.
+   - Terminal side channels — secondary guidance chrome (tips/nudges/notices), custom status lines and footers, progress indicators and notifications, terminal/tab titles and chrome metadata, host sleep-prevention leases, delay/polling command backgrounding, and session-background shortcuts — are never primary stdout, protocol output, transcript content, or proof of completion. Each carries capability/policy gating, generation-bound staleness rules, no-focus-theft/no-copy-pollution obligations, and a bounded-diagnostics rule (categories and counts, never raw bodies/paths/credentials). Before touching any of these surfaces, load `references/terminal-side-channels.md` for the per-surface contracts and their routing to `llm-inference-integration` / `platform-observability` / `platform-release-engineering` / `defect-diagnosis`.
+
+7. Optimize without changing semantics.
+   - Use damage bounds, scroll hints, buffer reuse, lazy syntax/highlight loading, and bounded caches only when they preserve visible output, selection, copy text, and terminal state.
+   - Do not let performance shortcuts skip non-selectable marks, soft-wrap metadata, style resets, hyperlink state, or wide-character spacer cells.
+   - Bound queue sizes, redraw cost, and memory growth for long sessions or large output.
+
+8. Verify on the real terminal surface.
+   - Unit-test width, wrapping, truncation, ANSI parsing, key parsing, state transitions, and capability fallback.
+   - Snapshot at the cell/screen-buffer layer when possible; raw string snapshots alone are insufficient for interactive terminal behavior.
+   - Use a PTY or equivalent integration test for raw mode, resize, key/mouse/paste sequences, terminal responses, and process lifecycle.
+   - Run at least one real terminal smoke for visible interactive changes when lower layers cannot prove color, cursor, scrollback, focus, selection, or resize behavior.
+   - For UI/UX redesign evidence, include target terminal class, size and narrow/short stress size, color mode or no-color fallback, keyboard-only path, empty/loading/error/final states, scrollback behavior, selection/copy boundary, resize behavior, and screenshot/transcript/PTY artifact; mark each dimension covered or `N/A` with a one-line reason. `N/A` is valid only when the reason names a verifiable structural fact, explains why that fact makes the dimension unreachable or unchanged for this slice, and includes a checkable pointer such as a file path, config key, or commit that resolves at review time. Persist evidence artifacts where reviewers can access them after redacting tokens, PII, credentials, private paths, command secrets, and raw personal data; remove temporary smoke files or PTY capture helpers before commit unless the repo intentionally owns them.
+   - Capture evidence: command, terminal class, size, color mode, before/after screenshot or transcript, and any unavailable capability with attempted remediation.
+
+## Reference Loading
+
+- `references/input-state-machines.md` — full contracts for paste/clipboard ingress, configurable keybindings, and modal text editing. Load before touching any of those input surfaces (Core Workflow step 5).
+- `references/streaming-rich-output.md` — full contract for streaming rich/markdown output into scrollback, including the untrusted-content sanitization security boundary. Load before implementing or reviewing any streaming-rich-output path (step 6).
+- `references/terminal-side-channels.md` — per-surface contracts for guidance chrome, status lines, progress/notifications, title/chrome metadata, sleep leases, delay/backgrounding, and session-background shortcuts. Load before touching any side-channel surface (step 6).
+
+## Non-Negotiable Rules
+
+- Do not treat terminal strings as layout truth; terminal cells are the layout truth.
+- Do not ship a terminal UI that only works in one color depth, one width, or one local shell unless the product explicitly scopes it that way.
+- Do not rely on color alone for warnings, errors, selection, current match, disabled state, or destructive action confirmation.
+- Do not claim terminal behavior is verified from static code inspection or string snapshots when the change affects cursoring, focus, raw mode, resize, scrollback, selection, or color.
+- Do not let generated chrome, gutters, hidden prompts, or status lines pollute copied user content.
+- Do not destroy scrollback or clear the screen as a side effect of refresh unless that behavior is part of the command contract and has a fallback.
+- Do not leave the terminal in raw mode, alternate screen, hidden cursor, mouse reporting, bracketed paste, focus reporting, modified keyboard mode, or non-default style state after normal exit, error, interrupt, termination signal, child crash, resize race, unmount, parent cancellation, or crash recovery.
+- Do not crash or dump a traceback when a downstream consumer closes the pipe early (piping to `head`, or to a pager then quitting): a write to a closed stdout/stderr raises `EPIPE` / `BrokenPipeError`. Exit quietly with the conventional status — in Python restore the default `SIGPIPE` disposition (`signal(SIGPIPE, SIG_DFL)`) or handle `BrokenPipeError` at the top level; in Node/JS catch the stream write `EPIPE` / `ERR_STREAM_DESTROYED` error (do not rely on a portable default-signal reset). Do not let it surface as an error stack to the user. (POSIX `SIGPIPE` / `write(2)` `EPIPE`.)
+- Do not write a durable file output in place when an interrupt (Ctrl-C / `SIGTERM`) or crash mid-write would leave a truncated or corrupt file: write to a temp file **in the same directory** (same filesystem — a cross-filesystem `rename` fails `EXDEV` and a copy-across-volume move is not atomic), flush and close it, then `rename(2)` onto the target — atomic replace on POSIX; on Windows use `MoveFileEx(..., MOVEFILE_REPLACE_EXISTING)` or the runtime's atomic-replace API. The reader then sees either the old file or the complete new one, never a half-written one. Streaming stdout is exempt; this is about durable file artifacts the command promises to produce.

package/dist/assets/marketplace/plugins/ccl-skills/skills/terminal-cli-dev/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Terminal CLI Dev"
+  short_description: "Build CLI, TUI, and terminal surfaces"
+  default_prompt: "Use $terminal-cli-dev to design, implement, or test command-line, TUI, PTY, and ANSI-rendered terminal product surfaces."

package/dist/assets/marketplace/plugins/ccl-skills/skills/terminal-cli-dev/references/input-state-machines.md

@@ -0,0 +1,36 @@
+# Input State Machines: Paste, Keybindings, Modal Editing
+
+Full contracts for the three stateful input boundaries named in `SKILL.md`
+Core Workflow step 5. Load this file whenever the change touches terminal
+paste/clipboard ingress, configurable keybindings, or modal (vi-like) text
+editing. Every bullet is an obligation, not advice.
+
+## Paste And Clipboard Ingress
+
+Treat terminal paste and clipboard ingress as a stateful input boundary before normal text handling.
+
+- Bracketed paste needs parser state that treats embedded escape sequences as literal content, emits explicit empty-paste events when the platform can paste non-text media, and flushes or cancels incomplete paste state deliberately.
+- Large-paste and dragged-file fallbacks need bounded chunk aggregation, completion timeout, synchronous pending state so a following key cannot submit stale input before the paste lands, and cleanup of orphan focus or terminal-response fragments without dropping valid user text.
+- Clipboard media probing must be opt-in by capability and platform, debounced across focus changes, rate-limited for hints, fenced by mounted/input generation, and separated from ordinary text submit.
+- File-path or media-path paste handling must normalize quoting and shell escapes, preserve non-media text, reject unverifiable or unsupported files before media insertion, enforce size/dimension/type budgets after reading trusted bytes, delete temporary artifacts best-effort, and route model-visible insertion through the runtime input/attachment gate.
+- Diagnostics may expose bounded categories, counts, capability states, and sanitized failure classes, but not clipboard text, filenames, local paths, raw media bytes, platform command strings, credentials, or free-form native errors.
+
+## Configurable Keybindings
+
+Treat configurable keybindings as an input-to-action control boundary.
+
+- Validate the user keymap schema before merging with defaults; user overrides must be ordered, explicit null/unbind entries must shadow defaults, and duplicate raw keys must be detected before permissive parsers collapse them.
+- Bind every resolved shortcut to context stack, active mode, terminal capability, platform-reserved and application-reserved shortcut set, key-parser generation, keymap generation, handler registration generation, pending-chord generation, and command-dispatch generation when a shortcut invokes a command.
+- Reserved or non-rebindable shortcuts need fail-closed errors or visible warnings instead of appearing supported.
+- Chords require prefix capture, timeout, escape/cancel, unbind shadowing, and stale-pending cleanup so chord keystrokes cannot leak into the prompt or another focused control.
+- Hot reload must publish only a complete parsed generation, reset to defaults on deletion or invalid config according to product policy, and close watchers/timers/handler registrations on unmount, exit, and shutdown.
+- Diagnostics may expose bounded warning categories, counts, and display labels, but not raw local config paths, binding bodies, command names, prompt text, credentials, or free-form parse errors.
+
+## Modal Text Editing
+
+Treat modal text editing as a command-language state machine, not as independent shortcuts.
+
+- Bind mode, parse state, bounded count prefix, pending operator, pending motion, text-object scope and type, find/replace literal, last-find state, last-change state, register contents plus linewise flag, insert-buffer snapshot, undo generation, active input identity, cursor/text snapshot, and grapheme/display-width model.
+- Cancel, focus loss, mode switch, submit, history search, paste, composition input, external insertion, prompt replacement, unmount, and resize that invalidates cursor geometry must either reset pending command state or fence it to the original input generation.
+- Operators that combine with motions or text objects must define inclusive, exclusive, and linewise ranges; logical-line versus wrapped-row behavior; missing-target and unmatched-delimiter no-ops; cursor clamping after mutation; register/yank/paste linewise behavior; and grapheme-safe boundaries.
+- Repeat commands may replay only successful mutations against a compatible snapshot/generation, and diagnostics may expose bounded state categories but not prompt text, registers, raw command bodies, local paths, credentials, or free-form parser errors.

package/dist/assets/marketplace/plugins/ccl-skills/skills/terminal-cli-dev/references/streaming-rich-output.md

@@ -0,0 +1,130 @@
+# Streaming Rich/Markdown Output Into Scrollback
+
+Full contract for streaming rich (markdown) content into append-only
+scrollback, referenced from `SKILL.md` Core Workflow step 6. Load this file
+whenever the change streams model output, fetched text, or any progressively
+arriving rich content into a terminal.
+
+The general invariant: **never commit reshape-prone content to an
+irreversible surface; hold it mutable until it is stable.** Split the stream
+into a committed *stable* region and a mutable *tail*, because a later token
+can retroactively reshape earlier output and scrollback cannot be
+un-printed. (In a DOM/web or app chat UI the whole subtree re-renders
+cheaply, so this discipline is terminal-specific — the append-only
+scrollback constraint is what forces it.)
+
+## Commit At Structural Boundaries, Not On Every Token — With One-Line Lookbehind
+
+Buffer the incoming delta and only re-render/commit *complete lines* (gate on
+newline); keep the trailing incomplete line in the tail. A complete line is
+still not safe to commit until the *next* line proves it is not the start of
+a construct that reinterprets it: a `Title` line followed by `---` becomes a
+setext heading, and a line followed by a pipe-table delimiter becomes a table
+header. So hold at least one settled line of lookbehind — commit line N only
+once line N+1 shows N is not a setext/table/continuation anchor. Re-render
+the still-mutable prefix from accumulated source rather than appending raw
+deltas, so inline markdown that completes mid-line renders correctly.
+
+## Hold Back Deferred-Resolution Constructs Until They Resolve
+
+Hold back any construct whose later content reshapes earlier output, until it
+resolves. This is a *class*, not a fixed list — markdown has several
+deferred-resolution constructs, and committing early prints something the
+later tokens prove wrong: a table's column widths change when a new row
+arrives; a setext heading rewrites its title line; a reference-style link
+(`[docs]` … later `[docs]: https://…`) should have been a hyperlink; a
+list's tight/loose spacing flips when a later blank line or sub-paragraph
+appears.
+
+- You will not enumerate them all, so prefer one of two strategies over
+  per-construct hacks: (a) render in a **streaming-invariant** form that does
+  not depend on not-yet-arrived content (e.g. resolve only inline/closed
+  constructs; do not attempt reference-link or setext resolution mid-stream);
+  or (b) when you do want the rich form, **detect the construct as it opens
+  and keep it in the mutable tail until it resolves or the stream
+  finalizes**, under the bounded-tail rule below.
+- Committing a half-built table or a premature paragraph to scrollback prints
+  output you cannot un-print.
+- Scan for these patterns only outside open code fences.
+
+## Bound The Held Tail And The Re-Render Cost
+
+Never hold or re-parse unboundedly. A minutes-long table or an unclosed code
+fence would otherwise hold from block-start forever: nothing commits, the
+buffer grows without bound, and the user sees a frozen tail.
+
+- Cap the held region by lines / bytes / elapsed time; on exceeding the cap,
+  stop holding and commit the oversized block degraded to streaming-safe
+  plain or preformatted text (accept a non-reflowed table over an infinite
+  tail and a memory leak).
+- The same cap protects against a re-render **CPU** DoS: because the mutable
+  tail is re-rendered from accumulated source on every delta, adversarial
+  markdown (deeply nested brackets/emphasis, pathological reference or table
+  syntax) can drive O(n²)-or-worse parsing/regex work each tick and freeze
+  the terminal. Use a linear-time/bounded parser and cap per-tick render
+  size/time, falling back to plain text when exceeded — never re-run an
+  unbounded parse over an ever-growing tail on every token.
+
+## Finalize Flushes The Remainder
+
+On stream end, render and commit whatever is left in the tail (including a
+last line with no trailing newline and any still-open held-back block,
+rendered best-effort).
+
+## Sanitize Terminal Control Sequences Out Of Streamed Content — A Security Boundary
+
+Streamed primary content (model output, fetched/user text) is untrusted and
+can embed raw escape/control bytes: `ESC[2J` clears the screen,
+cursor-movement sequences overwrite earlier output, OSC 52 writes the user's
+clipboard, OSC 8 injects hyperlinks, and a forged sequence can spoof a
+prompt or approval line.
+
+- Rendering those bytes as if they were the renderer's own gives the content
+  author control of the terminal. Before rendering streamed content, strip
+  or visibly escape all control sequences and only emit renderer-owned,
+  allowlisted styling (the SGR/colors *you* chose, the hyperlinks *you*
+  constructed).
+- This is distinct from ANSI-stripping for width measurement — here the goal
+  is to deny the content any terminal capability, not just to count cells.
+- Stripping control bytes is necessary but not sufficient.
+- The general rule is **untrusted streamed content must not be able to
+  deceive through the terminal**, and that has several instances beyond raw
+  escapes: plain-text chrome spoofing (printing `Approve command? [y/N]` or
+  `Password:` that reads as a real prompt), and Unicode display/byte
+  mismatches — bidirectional-override controls, zero-width/invisible format
+  characters, and confusable homoglyphs that make the *displayed* line differ
+  from the *copied/actual* bytes (the "Trojan-source" class: a command that
+  looks safe on screen hides or reorders a malicious suffix when pasted).
+- Defenses: render untrusted streamed output inside a clearly delimited
+  content region and reserve prompts/approvals/status chrome for
+  renderer-owned styling/layout the content cannot reproduce (so the user can
+  always tell agent/remote output from the terminal's own UI); and neutralize
+  the display/byte-mismatch vectors — visibly escape bidi-override controls
+  and zero-width/invisible format characters (these are unambiguously
+  deceptive in a command/code context), and *flag or annotate* suspicious
+  confusable homoglyphs rather than silently normalizing them (homoglyphs are
+  legitimate Unicode; blanket normalization corrupts real content and still
+  can't guarantee display==copy across fonts/locales).
+- Treat any new "content influences the terminal" vector as the same
+  boundary, not a fresh special case.
+
+## Pace The Commit Drain Adaptively, Source-Agnostically
+
+Drive commits from a FIFO queue of settled lines stamped with arrival time.
+Under light load drain ~one line per display tick for smooth pacing; when
+queue depth or oldest-queued age crosses a threshold, switch to catch-up and
+drain the backlog so visible lag converges. Decide from queue pressure alone,
+not from the producer's identity or a hardcoded throughput target.
+
+## Don't Bake Width Into Committed Rich Output
+
+You cannot rewrite width artifacts you already emitted into scrollback: a
+line hard-wrapped or column-padded at 120 columns stays mis-aligned and
+copies wrong after a shrink to 80. (Soft-wrapped output is different — many
+terminal emulators reflow soft-wrapped scrollback on resize; the stuck case
+is renderer-baked hard wraps/padding, not all committed text.) So prefer
+soft-wrap-friendly output and let the terminal reflow, or treat the render
+width as part of the committed artifact and accept that a later resize won't
+re-align that block. The still-mutable tail *does* re-render on resize; only
+the committed region is stuck, which is the more reason to keep
+width-sensitive blocks (tables) in the tail until finalize.