@bovinphang/craft-common 0.0.0-stage → 1.0.0

package/skills/cc-drawio-studio/scripts/shape-query.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { formatResult, parseArgs, skillDir } from "./studio-core.mjs";
+
+const INDEX = path.join(skillDir, "data", "shape-index.json");
+const ALIASES = new Map([
+  ["亚马逊", "aws"],
+  ["阿里云", "alibaba cloud"],
+  ["微软云", "azure"],
+  ["谷歌云", "gcp"],
+  ["云", "cloud"],
+  ["数据库", "database"],
+  ["队列", "queue"],
+  ["网关", "gateway"],
+  ["服务", "service"],
+  ["用户", "user"],
+  ["角色", "actor"],
+  ["流程", "flowchart"],
+  ["容器", "container"],
+  ["网络", "network"],
+  ["交换机", "switch"],
+  ["路由器", "router"],
+  ["函数", "lambda"],
+  ["对象存储", "storage"],
+  ["消息", "message"],
+]);
+
+export function loadShapes() {
+  return JSON.parse(fs.readFileSync(INDEX).toString("utf8"));
+}
+
+export function queryShapes(shapes, query, options = {}) {
+  const terms = expandTerms(query);
+  const category = options.category
+    ? String(options.category).toLowerCase()
+    : "";
+  const scored = [];
+  for (const [index, shape] of shapes.entries()) {
+    const haystack =
+      `${shape.title ?? ""} ${shape.tags ?? ""} ${shape.style ?? ""}`.toLowerCase();
+    if (category && !haystack.includes(category)) continue;
+    let score = 0;
+    const title = String(shape.title ?? "").toLowerCase();
+    const tags = String(shape.tags ?? "").toLowerCase();
+    for (const term of terms) {
+      if (title === term) score += 80;
+      else if (title.includes(term)) score += 45;
+      if (tags.split(/\s+/).includes(term)) score += 30;
+      else if (tags.includes(term)) score += 12;
+      if (fuzzyContains(haystack, term)) score += 4;
+    }
+    if (score > 0)
+      scored.push({
+        index,
+        score,
+        titleHits: terms.filter((term) => title.includes(term)).length,
+        shape,
+      });
+  }
+  return scored
+    .sort(
+      (a, b) =>
+        b.score - a.score ||
+        b.titleHits - a.titleHits ||
+        String(a.shape.title).localeCompare(String(b.shape.title)) ||
+        a.index - b.index,
+    )
+    .slice(0, Number(options.limit ?? 10))
+    .map(({ shape, score }) => ({
+      title: shape.title,
+      w: shape.w,
+      h: shape.h,
+      style: shape.style,
+      score,
+    }));
+}
+
+function expandTerms(query) {
+  const normalized = String(query ?? "").toLowerCase();
+  const raw = normalized.match(/[\p{L}\p{N}._-]+/gu) ?? [];
+  const expanded = [];
+  for (const term of raw) {
+    expanded.push(ALIASES.get(term) ?? term);
+    if (term.includes("-")) expanded.push(...term.split("-"));
+  }
+  return [
+    ...new Set(
+      expanded.join(" ").match(/[a-z0-9._-]+|[\u4e00-\u9fff]+/g) ?? [],
+    ),
+  ].filter((term) => term.length >= 2);
+}
+
+function fuzzyContains(text, term) {
+  if (term.length < 4) return false;
+  let cursor = 0;
+  for (const ch of text) {
+    if (ch === term[cursor]) cursor += 1;
+    if (cursor === term.length) return true;
+  }
+  return false;
+}
+
+const args = parseArgs(process.argv.slice(2));
+const query = args._.join(" ");
+if (!query) {
+  console.error(
+    "usage: node shape-query.mjs <keywords> [--limit 10] [--category aws] [--format markdown|json]",
+  );
+  process.exit(2);
+}
+const results = queryShapes(loadShapes(), query, args);
+if (results.length === 0) {
+  console.error(`no shapes matched ${JSON.stringify(query)}`);
+  process.exit(1);
+}
+if ((args.format ?? (args.json ? "json" : "markdown")) === "json") {
+  process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);
+} else {
+  process.stdout.write(formatResult({ title: "Shape Query", query, results }));
+}

package/skills/cc-drawio-studio/scripts/studio-core.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+export const skillDir = path.resolve(scriptDir, "..");
+
+export function readText(filePath) {
+  return fs.readFileSync(filePath, "utf8");
+}
+
+export function writeText(filePath, body) {
+  fs.mkdirSync(path.dirname(path.resolve(filePath)), { recursive: true });
+  fs.writeFileSync(filePath, body, "utf8");
+}
+
+export function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith("--")) {
+      args._.push(token);
+      continue;
+    }
+    const [rawKey, inline] = token.slice(2).split("=", 2);
+    const key = rawKey.replace(/-([a-z])/g, (_, ch) => ch.toUpperCase());
+    if (inline !== undefined) {
+      args[key] = inline;
+    } else if (argv[i + 1] && !argv[i + 1].startsWith("--")) {
+      args[key] = argv[i + 1];
+      i += 1;
+    } else {
+      args[key] = true;
+    }
+  }
+  return args;
+}
+
+export function formatResult(result, format = "markdown") {
+  if (format === "json") return `${JSON.stringify(result, null, 2)}\n`;
+  const lines = [`# ${result.title ?? "Drawio Studio Result"}`, ""];
+  for (const [key, value] of Object.entries(result)) {
+    if (key === "title") continue;
+    if (Array.isArray(value)) {
+      lines.push(`## ${label(key)}`, "");
+      if (value.length === 0) lines.push("- None");
+      else for (const item of value) lines.push(`- ${typeof item === "string" ? item : JSON.stringify(item)}`);
+      lines.push("");
+    } else if (value && typeof value === "object") {
+      lines.push(`## ${label(key)}`, "", "```json", JSON.stringify(value, null, 2), "```", "");
+    } else {
+      lines.push(`- ${label(key)}: ${String(value)}`);
+    }
+  }
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+export function label(value) {
+  return value.replace(/([A-Z])/g, " $1").replace(/^./, (ch) => ch.toUpperCase());
+}
+
+export function xmlEscape(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+export function snap(value, grid = 10) {
+  return Math.round(value / grid) * grid;
+}
+
+export function walkFiles(root, predicate) {
+  const out = [];
+  const skip = new Set([".git", "node_modules", "dist", "target", "vendor", ".next", ".nuxt", "coverage"]);
+  function visit(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (skip.has(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) visit(full);
+      else if (!predicate || predicate(full)) out.push(full);
+    }
+  }
+  visit(path.resolve(root));
+  return out.sort();
+}
+
+export function toPosix(value) {
+  return value.split(path.sep).join("/");
+}
+
+export function commonPrefix(values) {
+  if (values.length === 0) return "";
+  let prefix = values[0];
+  for (const value of values.slice(1)) {
+    while (prefix && !value.startsWith(prefix)) prefix = prefix.slice(0, -1);
+  }
+  return prefix.replace(/[^/]*$/, "");
+}
+
+export function reduceTransitive(nodes, edges) {
+  const ids = new Set(nodes.map((node) => node.id));
+  const unique = [];
+  const seen = new Set();
+  for (const edge of edges) {
+    if (!ids.has(edge.source) || !ids.has(edge.target) || edge.source === edge.target) continue;
+    const key = `${edge.source}\0${edge.target}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      unique.push({ source: edge.source, target: edge.target });
+    }
+  }
+  const adjacency = new Map();
+  for (const edge of unique) {
+    if (!adjacency.has(edge.source)) adjacency.set(edge.source, new Set());
+    adjacency.get(edge.source).add(edge.target);
+  }
+  return unique.filter((edge) => !hasAlternatePath(edge.source, edge.target, adjacency, edge));
+}
+
+function hasAlternatePath(source, target, adjacency, skipped) {
+  const stack = [...(adjacency.get(source) ?? [])].filter((next) => !(source === skipped.source && next === skipped.target));
+  const seen = new Set();
+  while (stack.length) {
+    const next = stack.pop();
+    if (next === target) return true;
+    if (!next || seen.has(next)) continue;
+    seen.add(next);
+    for (const child of adjacency.get(next) ?? []) stack.push(child);
+  }
+  return false;
+}
+
+export function printOrWrite(body, output) {
+  if (output) writeText(output, body);
+  else process.stdout.write(body);
+}

package/skills/cc-drawio-studio/styles/built-in/corporate.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "../schema.json",
+  "name": "corporate",
+  "version": 1,
+  "default": false,
+  "source": { "type": "built-in" },
+  "confidence": "high",
+  "palette": {
+    "primary":   { "fillColor": "#e3f2fd", "strokeColor": "#1565c0" },
+    "success":   { "fillColor": "#e8f5e9", "strokeColor": "#2e7d32" },
+    "warning":   { "fillColor": "#fff9c4", "strokeColor": "#f57c00" },
+    "accent":    { "fillColor": "#fff3e0", "strokeColor": "#e65100" },
+    "danger":    { "fillColor": "#ffebee", "strokeColor": "#c62828" },
+    "neutral":   { "fillColor": "#eceff1", "strokeColor": "#455a64" },
+    "secondary": { "fillColor": "#f3e5f5", "strokeColor": "#6a1b9a" }
+  },
+  "roles": {
+    "service":  "primary",
+    "database": "success",
+    "queue":    "warning",
+    "gateway":  "accent",
+    "error":    "danger",
+    "external": "neutral",
+    "security": "secondary"
+  },
+  "shapes": {
+    "service":   "rounded=0",
+    "database":  "shape=cylinder3",
+    "queue":     "rounded=0",
+    "decision":  "rhombus",
+    "external":  "rounded=0;dashed=1",
+    "container": "swimlane;startSize=30"
+  },
+  "font": {
+    "fontFamily": "Arial",
+    "fontSize": 11,
+    "titleFontSize": 13,
+    "titleBold": true
+  },
+  "edges": {
+    "style": "edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1",
+    "arrow": "endArrow=classic;endFill=1",
+    "dashedFor": ["optional", "async"]
+  },
+  "extras": {
+    "sketch": false,
+    "globalStrokeWidth": 1
+  }
+}

package/skills/cc-drawio-studio/styles/built-in/default.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "../schema.json",
+  "name": "default",
+  "version": 1,
+  "default": false,
+  "source": { "type": "built-in" },
+  "confidence": "high",
+  "palette": {
+    "primary":   { "fillColor": "#dae8fc", "strokeColor": "#6c8ebf" },
+    "success":   { "fillColor": "#d5e8d4", "strokeColor": "#82b366" },
+    "warning":   { "fillColor": "#fff2cc", "strokeColor": "#d6b656" },
+    "accent":    { "fillColor": "#ffe6cc", "strokeColor": "#d79b00" },
+    "danger":    { "fillColor": "#f8cecc", "strokeColor": "#b85450" },
+    "neutral":   { "fillColor": "#f5f5f5", "strokeColor": "#666666" },
+    "secondary": { "fillColor": "#e1d5e7", "strokeColor": "#9673a6" }
+  },
+  "roles": {
+    "service":  "primary",
+    "database": "success",
+    "queue":    "warning",
+    "gateway":  "accent",
+    "error":    "danger",
+    "external": "neutral",
+    "security": "secondary"
+  },
+  "shapes": {
+    "service":   "rounded=1",
+    "database":  "shape=cylinder3",
+    "queue":     "rounded=1",
+    "decision":  "rhombus",
+    "external":  "rounded=1;dashed=1",
+    "container": "swimlane;startSize=30"
+  },
+  "font": {
+    "fontFamily": "Helvetica",
+    "fontSize": 12,
+    "titleFontSize": 14,
+    "titleBold": true
+  },
+  "edges": {
+    "style": "edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1",
+    "arrow": "endArrow=classic;endFill=1",
+    "dashedFor": []
+  },
+  "extras": {
+    "sketch": false,
+    "globalStrokeWidth": 1
+  }
+}

package/skills/cc-drawio-studio/styles/built-in/handdrawn.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "../schema.json",
+  "name": "handdrawn",
+  "version": 1,
+  "default": false,
+  "source": { "type": "built-in" },
+  "confidence": "high",
+  "palette": {
+    "primary":   { "fillColor": "#ffe4b5", "strokeColor": "#b8651e" },
+    "success":   { "fillColor": "#def0dc", "strokeColor": "#5c8a49" },
+    "warning":   { "fillColor": "#fff4cc", "strokeColor": "#b8901a" },
+    "accent":    { "fillColor": "#ffd9b3", "strokeColor": "#c25100" },
+    "danger":    { "fillColor": "#ffcdbf", "strokeColor": "#a53d3d" },
+    "neutral":   { "fillColor": "#f5e6d3", "strokeColor": "#8b7355" },
+    "secondary": { "fillColor": "#e6d7e8", "strokeColor": "#7b4397" }
+  },
+  "roles": {
+    "service":  "primary",
+    "database": "success",
+    "queue":    "warning",
+    "gateway":  "accent",
+    "error":    "danger",
+    "external": "neutral",
+    "security": "secondary"
+  },
+  "shapes": {
+    "service":   "rounded=1",
+    "database":  "shape=cylinder3",
+    "queue":     "rounded=1",
+    "decision":  "rhombus",
+    "external":  "rounded=1;dashed=1",
+    "container": "swimlane;startSize=30"
+  },
+  "font": {
+    "fontFamily": "Helvetica",
+    "fontSize": 12,
+    "titleFontSize": 14,
+    "titleBold": true
+  },
+  "edges": {
+    "style": "edgeStyle=orthogonalEdgeStyle;curved=1;rounded=1;orthogonalLoop=1;jettySize=auto;html=1",
+    "arrow": "endArrow=classic;endFill=1",
+    "dashedFor": ["optional"]
+  },
+  "extras": {
+    "sketch": true,
+    "globalStrokeWidth": 2
+  }
+}

package/skills/cc-drawio-studio/styles/schema.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/Agents365-ai/drawio-skill/styles/schema.json",
+  "title": "drawio-skill preset",
+  "type": "object",
+  "required": ["name", "version", "palette", "roles", "shapes", "font", "edges"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema":    { "type": "string" },
+    "name":       { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$" },
+    "version":    { "type": "integer", "const": 1 },
+    "default":    { "type": "boolean" },
+    "confidence": { "type": "string", "enum": ["low", "medium", "high"] },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type":          { "type": "string", "enum": ["xml", "image", "built-in", "hand-authored"] },
+        "path":          { "type": "string" },
+        "extracted_at":  { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }
+      }
+    },
+    "palette": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["primary", "success", "warning", "accent", "danger", "neutral", "secondary"],
+      "properties": {
+        "primary":   { "$ref": "#/$defs/colorPair" },
+        "success":   { "$ref": "#/$defs/colorPair" },
+        "warning":   { "$ref": "#/$defs/colorPair" },
+        "accent":    { "$ref": "#/$defs/colorPair" },
+        "danger":    { "$ref": "#/$defs/colorPair" },
+        "neutral":   { "$ref": "#/$defs/colorPair" },
+        "secondary": { "$ref": "#/$defs/colorPair" }
+      }
+    },
+    "roles": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "service":  { "$ref": "#/$defs/slotName" },
+        "database": { "$ref": "#/$defs/slotName" },
+        "queue":    { "$ref": "#/$defs/slotName" },
+        "gateway":  { "$ref": "#/$defs/slotName" },
+        "error":    { "$ref": "#/$defs/slotName" },
+        "external": { "$ref": "#/$defs/slotName" },
+        "security": { "$ref": "#/$defs/slotName" }
+      }
+    },
+    "shapes": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "properties": {
+        "service":   { "type": "string" },
+        "database":  { "type": "string" },
+        "queue":     { "type": "string" },
+        "decision":  { "type": "string" },
+        "external":  { "type": "string" },
+        "container": { "type": "string" }
+      }
+    },
+    "font": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["fontFamily", "fontSize"],
+      "properties": {
+        "fontFamily":    { "type": "string" },
+        "fontSize":      { "type": "integer", "minimum": 8, "maximum": 36 },
+        "titleFontSize": { "type": "integer", "minimum": 8, "maximum": 48 },
+        "titleBold":     { "type": "boolean" }
+      }
+    },
+    "edges": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["style", "arrow"],
+      "properties": {
+        "style":      { "type": "string" },
+        "arrow":      { "type": "string" },
+        "dashedFor":  { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "extras": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "sketch":            { "type": "boolean" },
+        "globalStrokeWidth": { "type": "number", "minimum": 0.5, "maximum": 6 }
+      }
+    }
+  },
+  "$defs": {
+    "colorPair": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["fillColor", "strokeColor"],
+          "properties": {
+            "fillColor":   { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
+            "strokeColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }
+          }
+        }
+      ]
+    },
+    "slotName": {
+      "type": "string",
+      "enum": ["primary", "success", "warning", "accent", "danger", "neutral", "secondary"]
+    }
+  }
+}

package/skills/cc-refactoring-core/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: cc-refactoring-core
+description: Use when reorganizing existing code, extracting responsibilities, moving modules, or simplifying structure while preserving observable behavior. Do not use for new functionality, behavior-changing defect fixes, or dependency upgrades.
+---
+
+# Behavior-preserving refactoring
+
+Read and follow the [shared method](references/method.md). Select project-specific tools and domain checks from the actual repository; this workflow does not require a frontend stack.

package/skills/cc-refactoring-core/references/method.md

@@ -0,0 +1,16 @@
+# Behavior-preserving refactoring
+
+Refactoring changes internal organization while preserving the observable contract. Use GREEN → REFACTOR → GREEN; do not manufacture a failing behavioral requirement for a structural change.
+
+1. Classify whether this is structural work, a new behavior, a defect fix, or a dependency migration. Keep behavior changes in a separate workflow.
+2. Read affected implementation, callers, exports, registration, persistence and tests. Define observable results, errors, side effects and ordering, state transitions, public names and protocols before editing.
+3. Establish the green baseline or record existing failures. If a relevant behavior lacks coverage, add characterization tests that describe current behavior; these may start green.
+4. Diagnose structural evidence and check false positives. Line count and complexity metrics alone do not justify a rewrite. Prefer the smallest safe, reversible transformation.
+5. Plan prerequisite steps. Each records target, structural intent, technique, risk, expected files/functions, expected public API/behavior changes (zero for pure refactoring), verification and rollback boundary.
+6. Change one primary structural concern, then run the nearest meaningful check and inspect the diff. Stop and reassess if the actual scope exceeds the planned diff budget.
+7. A new regression invalidates the current step: restore only that step, verify the previous baseline and shrink or reorder the transformation before retrying. Do not revert unrelated user edits or spread repairs across unrelated modules.
+8. Broaden verification as the changed contract requires: local/static checks, unit/integration, full lint/types/tests, build and relevant specialty checks. Use existing project tools rather than impose a framework.
+
+Risk is contextual: SAFE for local/private changes with strong evidence; CAUTION for cross-module/shared-state/lifecycle changes; DANGER for public APIs, schemas, persistence, authentication, permission, protocols or architecture-wide changes. A technique name alone never makes a change safe.
+
+Deliver a proof verdict: PASS when the relevant behavior is adequately covered and checks pass; PARTIAL when checks pass but coverage has important gaps; NOT PROVEN when evidence or environment prevents a credible preservation claim. Include executed commands, rollback decisions and remaining risks.

package/skills/cc-source-driven-development/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: cc-source-driven-development
+description: Use when engineering decisions depend on version-sensitive packages, runtimes, platform behavior, public API assumptions, official documentation, source code, or a specified local knowledge base.
+---
+
+# Source-driven development
+
+Read and follow the [shared method](references/method.md). Select project-specific tools and domain checks from the actual repository; this workflow does not require a frontend stack.

package/skills/cc-source-driven-development/references/method.md

@@ -0,0 +1,19 @@
+# Source-driven development
+
+Use project facts, authoritative sources and version-specific evidence to make engineering decisions.
+
+1. Establish the question, affected version and local contract. Read the project's manifests, configuration, implementation, callers and tests before proposing changes. Stable local transformations can rely on those facts; changing runtime, package or public API assumptions need authoritative verification.
+2. Collect official documentation, source, type definitions, release notes, specifications and migration guides for the actual version. Third-party discussions provide clues, not the final basis. Record source paths/URLs, versions, dates and relevant conclusions.
+3. Compare recommendations with the running project. State compatibility, maintenance cost, migration scope and rollback. Isolate unstable external assumptions behind a small boundary; do not overturn stable conventions just to use a newer pattern.
+4. Prove key assumptions using the project's existing checks or a minimal reproduction. Select checks for the actual stack. Record commands and observed outcomes; if verification is unavailable, report the uncertainty rather than claim support.
+5. Update a lightweight ADR, migration record or factual documentation when public interfaces, dependencies or team conventions change. Do not copy long external documents.
+
+## Local knowledge requests
+
+When a user restricts evidence to a local repository or knowledge directory, search that source first and do not fill gaps with online guesses. Use the explicit path, otherwise check whether `knowledge/` exists. If absent, identify the missing source instead of inventing one.
+
+Read `data_structure.md` navigation where available, choose relevant branches, and search progressively instead of loading the entire corpus. Default to at most five keyword refinement rounds. Record file paths, sections/pages/sheets, version range and evidence gaps. For PDF or spreadsheets choose an appropriate extraction tool before reading large content. Use external sources only when the user's scope permits them.
+
+## Evidence priority and delivery
+
+Project implementation/configuration/tests establish the local contract; official versioned documentation/source establishes external behavior; specifications establish platform constraints; issues and articles only supplement these. Deliver the decision, sources, implementation impact, verification results and remaining uncertainty. "Checked the docs" without traceable evidence is insufficient.

package/skills/cc-tdd-methodology/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: cc-tdd-methodology
+description: Use when implementing new observable behavior or fixing a behavioral defect through tests, or when deciding whether a change is test-driven development or pure behavior-preserving refactoring.
+---
+
+# Test-driven development
+
+Read and follow the [shared method](references/method.md). Select project-specific tools and domain checks from the actual repository; this workflow does not require a frontend stack.

package/skills/cc-tdd-methodology/references/method.md

@@ -0,0 +1,13 @@
+# Test-driven development
+
+For new behavior and behavior-changing defect fixes use RED → GREEN → REFACTOR. The test describes an observable contract, not private implementation structure.
+
+1. Identify one behavior: inputs, output/error, state transition or externally observable side effect. Choose the closest meaningful test level using existing project tooling.
+2. Write the smallest test that distinguishes the missing or wrong behavior. Run it first and observe failure for the expected behavior, not a syntax, import or environment problem. For a defect, the test must fail against the original defect.
+3. Implement only enough to pass that test. Do not refactor during the red phase or add unrelated features.
+4. Run the test and relevant surrounding tests, then improve naming and structure while preserving green. New requirements enter the next cycle.
+5. Report the observed red/green commands, covered behavior and untested boundaries. Do not infer success from a diff or unexecuted tests.
+
+Pure structural refactoring has a different contract: establish current behavior through existing or characterization coverage and keep GREEN → REFACTOR → GREEN. Do not invent a failure merely to satisfy a ritual.
+
+Test logic close to the risk; use integration tests for real boundaries and end-to-end tests for journeys that need them. Do not make E2E the default or assert fragile private state. Do not introduce a new testing framework merely for TDD. If infrastructure is absent, explain the minimum test setup and obtain a decision before introducing it; use the actual stack rather than require frontend tools.

package/skills/cc-technical-diagrams/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: cc-technical-diagrams
+description: Use when creating or exporting structured technical diagrams, including architecture, workflows, sequence diagrams, data flows, lifecycle diagrams, agent or memory flows, local interactive previews, and PNG quality checks. Use editable draw.io sources when long-term manual editing or vendor shapes matter. Do not use for UI mockups, product imagery, posters, or raster image editing.
+---
+
+# Technical diagrams
+
+Create complete, readable technical diagrams from editable structured sources. This workflow applies across frontend, backend, infrastructure, and agent systems.
+
+## Choose the source
+
+Read [diagram workflows](references/diagram-workflows.md). Prefer locally available Mermaid for standard sequence and flowcharts. Use HTML technical diagrams for self-contained browser viewing, semantic architecture and agent/memory flows; read [HTML technical diagrams](references/html-technical-diagrams.md). Choose editable draw.io sources for official vendor shapes or long-term manual editing.
+
+Use a local interactive preview when the user benefits from incremental explanation; keep JSON/SVG/PNG exports as deliverables. The live server is [interactive-diagram-server.mjs](scripts/interactive-diagram-server.mjs) and the local page is [interactive-diagram.html](assets/interactive-diagram.html).
+
+## Render and export
+
+Keep every node, relationship, complete label and explicit geometry. The renderer supports workflow, sequence, dataflow, lifecycle and architecture. Never silently simplify advanced sequence semantics; prefer Mermaid for activation and alt/loop/par fragments.
+
+```sh
+node skills/cc-technical-diagrams/scripts/tech-diagram-render.mjs --input diagram.json --type architecture --output diagram.html --manifest diagram.layout.json
+node skills/cc-technical-diagrams/scripts/export-diagram.mjs --input diagram.html --format png --output diagram.png --theme light --scale 2 --manifest diagram.layout.json --output-manifest diagram.actual.json
+node skills/cc-technical-diagrams/scripts/png-qa.mjs --png diagram.png --manifest diagram.actual.json --format json
+```
+
+Standard Mermaid sources use [mermaid-render.mjs](scripts/mermaid-render.mjs). Reuse [diagram-layout.mjs](scripts/diagram-layout.mjs) and [diagram-browser.mjs](scripts/diagram-browser.mjs); do not invent another renderer or add required browser libraries, remote scripts or downloaded icon packs.
+
+## Verify and deliver
+
+Inspect the actual exported image for clipping, text truncation, crossing labels, overlaps and missing content. PNG QA uses the actual scaled export manifest, not the source's estimated coordinates. Successful export alone does not prove visual acceptance. Read [PNG repair guidance](references/png-qa-autofix.md); repair the source or layout, not the output pixels. Default to at most two repair rounds and report unresolved issues.
+
+Deliver JSON/Mermaid source, HTML where relevant, exports and QA evidence. Record tool versions, theme, scale, repair rounds and partial acceptance. Optional Mermaid/Graphviz/browser tools must fail clearly or use an available fallback; do not install them automatically or claim a missing export succeeded. Retain complete labels instead of hiding overflow at higher resolution.
+
+Examples and fixtures: [quality examples](assets/quality-examples/README.md), [sequence JSON](assets/quality-examples/sequence.json), [workflow JSON](assets/quality-examples/workflow.json), [architecture JSON](assets/quality-examples/architecture.json), [invalid explicit geometry](assets/quality-examples/invalid-explicit.json).