@celsoft/coordinator 0.0.0 → 0.1.0

package/skills/extra/skills/markdown-review/assets/index.html

@@ -0,0 +1,201 @@
+<title>Markdown Review</title>
+<style>
+:root {
+  --bg: #fbfaf8; --fg: #1f1d1a; --muted: #6b665e; --line: #e4e0d8;
+  --code-bg: #f1eee8; --accent: #2f5fbf; --table-head: #f4f1eb;
+  --panel: #f5f3ef; --current: #e8e4dc; --group: #e9eef8;
+}
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    --bg: #17181a; --fg: #e6e3dd; --muted: #9a958c; --line: #2e3033;
+    --code-bg: #222427; --accent: #8fb1ff; --table-head: #1f2123;
+    --panel: #1c1d20; --current: #2a2c30; --group: #22293a;
+  }
+}
+:root[data-theme="dark"] {
+  --bg: #17181a; --fg: #e6e3dd; --muted: #9a958c; --line: #2e3033;
+  --code-bg: #222427; --accent: #8fb1ff; --table-head: #1f2123;
+  --panel: #1c1d20; --current: #2a2c30; --group: #22293a;
+}
+* { box-sizing: border-box; }
+html, body { height: 100%; }
+body {
+  margin: 0; background: var(--bg); color: var(--fg); overflow: hidden;
+  font: 16px/1.65 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+}
+.layout { display: grid; grid-template-columns: 280px 1fr; height: 100vh; height: 100dvh; }
+
+nav {
+  overflow-y: auto; background: var(--panel); border-right: 1px solid var(--line);
+  padding: 24px 12px 48px; font-size: 14px; line-height: 1.4;
+}
+nav .doc-title { font-weight: 600; padding: 0 8px 12px; }
+nav a {
+  display: block; color: var(--muted); text-decoration: none;
+  padding: 5px 8px; border-radius: 6px;
+}
+nav a:hover { color: var(--fg); }
+nav a.current { background: var(--current); color: var(--fg); }
+nav a.level-3 { padding-left: 22px; }
+nav a.level-4 { padding-left: 36px; font-size: 13px; }
+
+#content { overflow-y: auto; }
+main { max-width: 780px; margin: 0 auto; padding: 32px 24px 96px; }
+.file { color: var(--muted); font: 13px ui-monospace, SFMono-Regular, Menlo, monospace; margin-bottom: 24px; }
+.toggle {
+  display: none; position: fixed; top: 12px; right: 12px; z-index: 3;
+  background: var(--panel); color: var(--fg); border: 1px solid var(--line);
+  border-radius: 8px; padding: 6px 12px; font: inherit; font-size: 14px;
+}
+
+h1, h2, h3, h4 { line-height: 1.25; margin: 1.8em 0 0.6em; scroll-margin-top: 16px; }
+h1 { font-size: 2em; margin-top: 0; }
+h2 { font-size: 1.45em; padding-bottom: 0.3em; border-bottom: 1px solid var(--line); }
+h3 { font-size: 1.15em; }
+a { color: var(--accent); }
+p, ul, ol, table, pre, blockquote { margin: 0 0 1em; }
+li { margin: 0.25em 0; }
+code { font: 0.9em ui-monospace, SFMono-Regular, Menlo, monospace; background: var(--code-bg); padding: 0.1em 0.35em; border-radius: 4px; }
+pre { background: var(--code-bg); padding: 14px 16px; border-radius: 8px; overflow-x: auto; }
+pre code { background: none; padding: 0; font-size: 0.85em; }
+blockquote { border-left: 3px solid var(--line); margin-left: 0; padding-left: 16px; color: var(--muted); }
+.table-wrap { overflow-x: auto; margin: 0 0 1em; }
+table { border-collapse: collapse; width: 100%; font-size: 0.93em; margin: 0; }
+th, td { border: 1px solid var(--line); padding: 8px 10px; text-align: left; vertical-align: top; }
+th { background: var(--table-head); }
+td[colspan], th[colspan] { background: var(--group); }
+img { max-width: 100%; }
+hr { border: 0; border-top: 1px solid var(--line); margin: 2em 0; }
+.mermaid { display: flex; justify-content: center; margin: 0 0 1em; overflow-x: auto; }
+.status { color: var(--muted); }
+
+@media (max-width: 760px) {
+  .layout { grid-template-columns: 1fr; }
+  nav {
+    display: none; position: fixed; inset: 0 0 0 auto; width: min(300px, 85vw); z-index: 2;
+    border-right: 0; border-left: 1px solid var(--line); padding-top: 56px;
+  }
+  body.outline-open nav { display: block; }
+  .toggle { display: block; }
+  main { padding: 56px 16px 96px; }
+}
+</style>
+
+<button class="toggle" id="toggle" type="button">Outline</button>
+<div class="layout">
+  <nav id="outline" aria-label="Outline"></nav>
+  <div id="content">
+    <main>
+      <div class="file" id="file"></div>
+      <article id="doc"><p class="status">Loading…</p></article>
+    </main>
+  </div>
+</div>
+
+<script src="https://cdnjs.cloudflare.com/ajax/libs/marked/12.0.2/marked.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/dompurify/3.1.6/purify.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/mermaid/11.4.0/mermaid.min.js"></script>
+<script>
+(async () => {
+  const doc = document.getElementById("doc");
+  const outline = document.getElementById("outline");
+  const content = document.getElementById("content");
+
+  document.getElementById("toggle").addEventListener("click", () => document.body.classList.toggle("outline-open"));
+
+  const fail = (message) => {
+    doc.innerHTML = "";
+    const p = document.createElement("p");
+    p.className = "status";
+    p.textContent = message;
+    doc.append(p);
+  };
+
+  let file;
+  try {
+    const manifest = await (await fetch("document.json", { cache: "no-cache" })).json();
+    file = manifest.file;
+    if (typeof file !== "string" || !file) throw new Error("document.json has no file");
+  } catch (error) {
+    return fail("Could not read document.json: " + error.message);
+  }
+
+  document.getElementById("file").textContent = file;
+  const response = await fetch(encodeURI(file), { cache: "no-cache" }).catch(() => null);
+  if (!response || !response.ok) return fail("Could not load " + file + ".");
+  const markdown = await response.text();
+
+  doc.innerHTML = DOMPurify.sanitize(marked.parse(markdown, { gfm: true }));
+
+  for (const table of doc.querySelectorAll("table")) {
+    const wrap = document.createElement("div");
+    wrap.className = "table-wrap";
+    table.replaceWith(wrap);
+    wrap.append(table);
+  }
+
+  const title = doc.querySelector("h1");
+  document.title = title ? title.textContent : file;
+  buildOutline(title ? title.textContent : file);
+
+  const diagrams = [...doc.querySelectorAll("pre > code.language-mermaid")];
+  if (diagrams.length) {
+    for (const code of diagrams) {
+      const div = document.createElement("div");
+      div.className = "mermaid";
+      div.textContent = code.textContent;
+      code.parentElement.replaceWith(div);
+    }
+    const theme = document.documentElement.dataset.theme;
+    const dark = theme ? theme === "dark" : matchMedia("(prefers-color-scheme: dark)").matches;
+    mermaid.initialize({ startOnLoad: false, theme: dark ? "dark" : "default", securityLevel: "strict" });
+    await mermaid.run({ nodes: doc.querySelectorAll(".mermaid") });
+  }
+
+  function buildOutline(docTitle) {
+    const heading = document.createElement("div");
+    heading.className = "doc-title";
+    heading.textContent = docTitle;
+    outline.append(heading);
+
+    const used = new Set();
+    const entries = [];
+    for (const h of doc.querySelectorAll("h2, h3, h4")) {
+      const base = h.textContent.toLowerCase().trim().replace(/[^\w]+/g, "-").replace(/^-|-$/g, "") || "section";
+      let id = base;
+      for (let n = 2; used.has(id); n++) id = base + "-" + n;
+      used.add(id);
+      h.id = id;
+
+      const link = document.createElement("a");
+      link.href = "#" + id;
+      link.className = "level-" + h.tagName[1];
+      link.textContent = h.textContent;
+      link.addEventListener("click", (event) => {
+        event.preventDefault();
+        h.scrollIntoView({ behavior: "smooth", block: "start" });
+        document.body.classList.remove("outline-open");
+      });
+      outline.append(link);
+      entries.push({ h, link });
+    }
+
+    let current;
+    const mark = () => {
+      const top = content.getBoundingClientRect().top + 24;
+      let active = entries[0];
+      for (const entry of entries) {
+        if (entry.h.getBoundingClientRect().top <= top) active = entry;
+        else break;
+      }
+      if (!active || active === current) return;
+      current?.link.classList.remove("current");
+      active.link.classList.add("current");
+      active.link.scrollIntoView({ block: "nearest" });
+      current = active;
+    };
+    content.addEventListener("scroll", mark, { passive: true });
+    mark();
+  }
+})();
+</script>

package/skills/extra/skills/markdown-review/scripts/stage

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+#
+# stage: prepare the renderer page and document.json for one markdown file.
+#
+# Usage: stage <markdown-file> <out-dir>
+# Prints the three paths to publish, one per line.
+
+set -euo pipefail
+
+if [ $# -ne 2 ]; then
+  echo "usage: stage <markdown-file> <out-dir>" >&2
+  exit 2
+fi
+
+markdown=$1
+out=$2
+here=$(cd "$(dirname "$0")/.." && pwd)
+
+if [ ! -f "$markdown" ]; then
+  echo "NOT_FOUND: $markdown" >&2
+  exit 1
+fi
+
+name=$(basename "$markdown")
+case $name in
+  *\"* | *\\*) echo "BAD_NAME: rename the file without quotes or backslashes" >&2; exit 1 ;;
+  index.html | document.json) echo "BAD_NAME: $name is reserved by the renderer" >&2; exit 1 ;;
+esac
+
+mkdir -p "$out"
+cp "$here/assets/index.html" "$out/index.html"
+printf '{ "file": "%s" }\n' "$name" > "$out/document.json"
+
+echo "PAGE: $out/index.html"
+echo "MANIFEST: $out/document.json"
+echo "MARKDOWN: $name <- $(cd "$(dirname "$markdown")" && pwd)/$name"

package/skills/extra/skills/mise-usage/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: mise-usage
+description: "How to use mise in a project: running commands, managing tools, .env and .venv, Python/uv setup, writing tasks, and driving tasks from Claude."
+verified: 2026-10-16
+---
+
+# Mise Usage
+
+## Claude has no mise environment
+
+When Claude runs a Bash command, it is **not** in an activated mise shell. Tools declared in `mise.toml` (`python`, `uv`, `node`, etc.) are not on PATH, `.venv` is not activated, and `.env` is not loaded.
+
+**Never run raw tool commands** (`python`, `uv`, `pip`, `node`, or anything else managed by
+mise), and **never run `mise exec`.** Every command goes through a mise task:
+
+- **Know the tasks.** Run `mise tasks` at the start of a session, and use a task over the
+  equivalent raw command whenever one exists.
+- **No task fits.** Write a new file task for the command (see [Writing tasks](#writing-tasks))
+  and run it with `mise run`. Tasks carry the full environment: tools, `.env`, `.venv`.
+
+## mise.toml structure
+
+`mise.toml` at the repo root declares tools and environment:
+
+```toml
+[tools]
+python = "3.13"
+uv = "latest"
+node = "22"
+
+[env]
+_.file = ".env"                                              # autoload .env
+_.python.venv = { path = ".venv", create = true }           # manage .venv
+UV_PYTHON = { value = "{{ tools.python.path }}", tools = true }
+```
+
+`mise install` installs all declared tools. After that, `mise run` has the full environment.
+
+**Pin every tool.** Give each one an explicit version or backend (`node = "22"`,
+`ubi:owner/repo`, `npm:pkg`), so `mise install` provisions identical versions on every
+machine. `latest` is acceptable only where drift genuinely does not matter.
+
+**`[env]` holds non-secret values only.** mise exports `[env]` into every interactive
+shell in the repo and every child process, so anything there is far more widely visible
+than it looks: a token in `[env]` can shadow an unrelated tool's own credential. Keep
+`[env]` to identifiers such as account ids, bucket names, and hostnames. Secrets live in
+`.env.secrets` and are sourced inside the one task that needs them, never autoloaded and
+never declared here. See `secrets`.
+
+## .env autoloading
+
+Declare `_.file = ".env"` in the `[env]` block and mise loads it automatically for every `mise run` invocation. Never manually source `.env` before running commands. Gitignore `.env`; commit `.env.example` with placeholder values.
+
+**Never autoload `.env.secrets`.** Autoloading is safe for `.env` precisely because `.env` holds no secrets. `.env.secrets` is different: it is sourced explicitly inside the task that needs it, so the values exist only in that process and never reach an interactive shell. Do not add it to `_.file`.
+
+## .venv management
+
+Declare `_.python.venv = { path = ".venv", create = true, uv_create = true }` in the `[env]` block and mise creates and activates the `.venv` automatically, using `uv` to create it (much faster than the stdlib `venv`). Never run `python -m venv`, `uv venv`, or any manual venv command: mise owns this.
+
+## Python and uv conventions
+
+- Declare `python` and `uv` in `[tools]`; set `UV_PYTHON` so uv uses mise's Python, not system Python
+- Declare dependencies in `pyproject.toml`: never `requirements.txt`
+- Install/sync deps with `uv sync` inside a mise task
+- Commit `uv.lock` for reproducible installs
+
+## Writing tasks
+
+All scripts run by humans or Claude are mise file tasks written in zsh. Never embed script logic in `mise.toml` or skills.
+
+```zsh
+#!/usr/bin/env zsh
+#MISE description="What this task does"
+
+# task logic here
+```
+
+Requirements: `#!/usr/bin/env zsh` on line 1, `#MISE description="..."` on line 2, file executable (`chmod +x`). Add `#MISE depends=["other:task"]` for prerequisites.
+
+**File tasks only. Never an inline `[tasks]` table in `mise.toml`.** One location for every task keeps them discoverable and reviewable, and a task that starts inline never gets moved.
+
+Arguments come after `--` and are read as `"$@"`: `mise run deploy -- --dry-run`. List everything with `mise tasks`.
+
+**Warning:** Some formatters add a space after `#`, turning `#MISE` into `# MISE`, which breaks parsing. Use `# [MISE]` if that happens.
+
+### Naming
+
+A task's name is its path under the tasks directory. Subdirectories create `:`-namespaced names; `_default` makes a namespace directly runnable:
+
+```
+foo              # mise run foo
+group/bar        # mise run group:bar
+group/_default   # mise run group
+```
+
+### Shared helper library
+
+A shared helper must be **non-executable** and named with a leading underscore. mise discovers *executable* files under `mise-tasks/` as tasks, so a `chmod +x` helper shows up as a phantom task that does nothing when run.
+
+Source it at the top of every task: resolve it from the script's own path so it works regardless of where `mise run` is invoked:
+
+```zsh
+source "${0:A:h}/_lib.sh"   # ${0:A} = symlink-resolved absolute path; :h = dirname
+```
+
+A helper library should provide:
+
+```zsh
+header "..."             # bold heading
+info "..."               # informational line
+success "..."            # ✓ line
+warn "..."               # ⚠ warning line
+error "..."              # ✗ to stderr
+dim "..."                # dimmed text (e.g. echoing a command before running it)
+ask "prompt" "default"   # interactive text input → result in $REPLY
+confirm "prompt"         # yes/no prompt → returns 0 for yes, 1 for no
+```
+
+It should also restore the working directory on source, so tasks act on the directory where `mise run` was invoked:
+
+```zsh
+[[ -n "${MISE_ORIGINAL_CWD}" ]] && cd "$MISE_ORIGINAL_CWD"
+```
+
+### Idempotency
+
+Tasks must be safe to re-run. Check before mutating: don't assume state is clean.
+
+## Troubleshooting mise activation
+
+If `mise run` fails because `mise` is not found, the shell is not activated. Check:
+
+```bash
+command -v mise          # should print a path
+echo $MISE_SHELL         # should print "zsh", "bash", etc.; empty means not activated
+```
+
+**Do not activate it yourself.** Tell the user mise is not activated in their shell, and
+point them at mise's own activation docs (https://mise.jdx.dev/getting-started.html). Their
+shell startup files are theirs: a line you append may duplicate one their dotfiles already
+manage.
+
+After it is activated, open a new terminal; the current session will not pick it up.
+Once activated, `mise install` installs the tools declared in `mise.toml` for the current
+project.
+
+## Driving tasks from Claude
+
+When a skill drives a mise task that would otherwise trigger a Bash permission prompt, collapse the two prompts into one with `allowed-tools` in the skill's frontmatter:
+
+```yaml
+allowed-tools: Bash(mise run my:task:*)
+```
+
+The grant is active only while the skill runs and lapses when it finishes. The `AskUserQuestion` in the skill becomes the single decision point. Never blanket-allow mise in `settings.json` (`Bash(mise run:*)`): that silences prompts for tasks that have no approval gate.