data-vizard 0.0.1 → 0.1.0

package/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "data-vizard",
+  "interface": {
+    "displayName": "Data Vizard"
+  },
+  "plugins": [
+    {
+      "name": "data-vizard",
+      "source": {
+        "source": "local",
+        "path": "./plugins/data-vizard"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

package/.claude-plugin/marketplace.json

@@ -0,0 +1,30 @@
+{
+  "name": "data-vizard",
+  "owner": {
+    "name": "Trine"
+  },
+  "description": "Data Vizard agent workflow plugins.",
+  "version": "0.1.0",
+  "plugins": [
+    {
+      "name": "data-vizard",
+      "source": "./plugins/data-vizard",
+      "displayName": "Data Vizard",
+      "description": "Guide data visualization projects from dataset intake to analysis, narrative, design, and HTML story output.",
+      "version": "0.1.0",
+      "author": {
+        "name": "Trine"
+      },
+      "repository": "https://github.com/inosaint/data-vizard",
+      "license": "MIT",
+      "keywords": [
+        "data-visualization",
+        "storytelling",
+        "csv",
+        "analysis",
+        "html"
+      ],
+      "category": "Productivity"
+    }
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# Data Vizard
+
+Data Vizard is a WIP agent plugin for building data visualization stories with a staged workflow. The workflow moves from data intake to analysis, narrative framing, visual design, and a final HTML artifact while keeping user decisions explicit.
+
+## Workflow
+
+Most projects follow this path:
+
+1. `data-vizard` coordinates the project and decision gates.
+2. `data-curator` finds, evaluates, cleans, joins, and documents data.
+3. `data-analyst` explores the curated data and proposes evidence-backed story directions.
+4. `narrator` turns the selected analytical direction into a story brief, copy, caveats, and annotation plan.
+5. `designer` chooses the visual form with the user, then builds and verifies the HTML artifact.
+
+Project folders use lowercase hyphen-case slugs, for example `nyc-taxi-weather-jan-2026`.
+
+## Skills
+
+The local skills live in `skills/`.
+
+- `skills/data-vizard/` - Orchestrates the full visualization workflow, routes between role skills, and maintains decision gates.
+- `skills/data-curator/` - Handles dataset discovery, data fitness checks, cleaning, reshaping, joins, enrichment, and curator handoff notes.
+- `skills/data-analyst/` - Profiles curated datasets, finds patterns and caveats, and proposes possible story directions without choosing the final story silently.
+- `skills/narrator/` - Shapes the selected analysis into audience-facing structure: story spine, titles, section copy, annotations, and caveats.
+- `skills/designer/` - Designs and produces HTML-based visualization artifacts, including chart choice, layout, interaction, accessibility, visual style, and motion behavior.
+
+Each skill has a `SKILL.md` file with its operating rules. Some skills also include `references/` for playbooks and reusable guidance, or `assets/` for starter files.
+
+## Install
+
+Install the published package with npm, pnpm, or Bun:
+
+```bash
+npx data-vizard install
+pnpm dlx data-vizard install
+bunx data-vizard install
+```
+
+The installer copies the bundled plugin into a stable local marketplace at `~/.data-vizard/marketplace`, then registers and installs it for Codex and Claude Code when their CLIs are available.
+
+After installing, start a new agent session and invoke the orchestrator:
+
+```text
+Codex: $data-vizard:data-vizard
+Claude Code: /data-vizard:data-vizard
+```
+
+## Manual Plugin Install
+
+The plugin source lives in `plugins/data-vizard/`, with repo-local marketplace files for Codex and Claude Code. From a fresh clone, install it manually with:
+
+```bash
+codex plugin marketplace add "$(pwd)"
+codex plugin add data-vizard@data-vizard
+
+claude plugin marketplace add "$(pwd)"
+claude plugin install data-vizard@data-vizard
+```
+
+See `plugins/data-vizard/README.md` for full install, usage, update, and troubleshooting notes.
+
+## Folder Guide
+
+- `outcome/` - Final or in-progress public-facing visualization artifacts. Each project gets its own folder, usually with an `index.html` and supporting files such as story briefs, design notes, SVG favicons, or map assets.
+- `data/` - Curated data, raw source snapshots, transformation notes, and intermediate datasets used to build a visualization.
+- `scripts/` - Reproducible data preparation scripts. For example, `scripts/build_nyc_taxi_weather_hourly.py` builds the NYC taxi/weather dataset.
+- `skills/` - Local role skills used by the Data Vizard workflow.
+- `project-ledgers/` - Project ledgers that record stage progress, skill handoffs, decisions, caveats, and important files.
+- `outcome/<project-name>/PRODUCT.md` - Project-specific product context: audience, purpose, brand personality, anti-references, design principles, and accessibility goals.
+
+
+## Current Projects
+
+- `outcome/nyc-taxi-weather-jan-2026/` - A map-led scrollytelling story about how the January 25, 2026 snow day affected NYC yellow taxi pickups.
+- `outcome/india-state-choropleth/` - An India state choropleth visualization workspace.
+
+## Working Notes
+
+- Keep user-facing visualization outputs under `outcome/<project-name>/`.
+- Keep curated data and transformation artifacts under `data/<project-name>/`.
+- Keep project progress notes in `project-ledgers/<project-name>.md`.
+- When adding new skills, include a clear `SKILL.md` and keep supporting guidance in that skill's `references/` folder.
+- For chart and map animations, prefer semantic data transitions: animate heights, bases, segment boundaries, filters, and scales rather than relying on opacity-only color swaps.

package/bin/data-vizard.js

@@ -1,2 +1,362 @@
 #!/usr/bin/env node
-console.log("Data Vizard installer coming soon.");
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+const PLUGIN_NAME = "data-vizard";
+const MARKETPLACE_NAME = "data-vizard";
+const DISPLAY_NAME = "Data Vizard";
+
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (!command || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+
+  if (command === "--version" || command === "-v") {
+    console.log(readPackageJson().version);
+    return;
+  }
+
+  if (command === "install") {
+    install(args.slice(1));
+    return;
+  }
+
+  console.error(`Unknown command: ${command}`);
+  printHelp();
+  process.exitCode = 1;
+}
+
+function printHelp() {
+  console.log(`Data Vizard
+
+Usage:
+  data-vizard install [options]
+
+Options:
+  --root <path>      Stable marketplace root to write. Default: ~/.data-vizard/marketplace
+  --no-codex        Stage files but skip Codex CLI registration/install.
+  --no-claude       Stage files but skip Claude Code CLI registration/install.
+  --dry-run         Print planned actions without writing files or running CLIs.
+  -h, --help        Show this help.
+  -v, --version     Show package version.
+`);
+}
+
+function install(args) {
+  const options = parseInstallOptions(args);
+  const packageJson = readPackageJson();
+  const marketplaceRoot = path.resolve(
+    expandHome(options.root || path.join(os.homedir(), ".data-vizard", "marketplace")),
+  );
+  const sourcePluginDir = path.join(PACKAGE_ROOT, "plugins", PLUGIN_NAME);
+  const targetPluginDir = path.join(marketplaceRoot, "plugins", PLUGIN_NAME);
+
+  if (!fs.existsSync(sourcePluginDir)) {
+    throw new Error(`Bundled plugin not found at ${sourcePluginDir}`);
+  }
+
+  const codexMarketplacePath = path.join(marketplaceRoot, ".agents", "plugins", "marketplace.json");
+  const claudeMarketplacePath = path.join(marketplaceRoot, ".claude-plugin", "marketplace.json");
+
+  console.log(`${DISPLAY_NAME} installer ${packageJson.version}`);
+  console.log(`Marketplace root: ${marketplaceRoot}`);
+
+  if (options.dryRun) {
+    console.log(`Would copy ${sourcePluginDir} -> ${targetPluginDir}`);
+    console.log(`Would write ${codexMarketplacePath}`);
+    console.log(`Would write ${claudeMarketplacePath}`);
+  } else {
+    copyPlugin(sourcePluginDir, targetPluginDir);
+    writeJson(codexMarketplacePath, createCodexMarketplace());
+    writeJson(claudeMarketplacePath, createClaudeMarketplace(packageJson.version));
+    console.log("Staged Data Vizard marketplace files.");
+  }
+
+  const stagedOnly = options.noCodex && options.noClaude;
+  if (!options.noCodex) {
+    installCodex(marketplaceRoot, options.dryRun);
+  }
+
+  if (!options.noClaude) {
+    installClaude(marketplaceRoot, options.dryRun);
+  }
+
+  if (stagedOnly) {
+    printManualCommands(marketplaceRoot);
+  }
+
+  console.log("");
+  console.log("Start a new Codex thread and use $data-vizard:data-vizard.");
+  console.log("Start a new Claude Code session and use /data-vizard:data-vizard.");
+}
+
+function parseInstallOptions(args) {
+  const options = {
+    root: null,
+    noCodex: false,
+    noClaude: false,
+    dryRun: false,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--root") {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error("--root requires a path");
+      }
+      options.root = value;
+      index += 1;
+    } else if (arg === "--no-codex") {
+      options.noCodex = true;
+    } else if (arg === "--no-claude") {
+      options.noClaude = true;
+    } else if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (arg === "--help" || arg === "-h") {
+      printHelp();
+      process.exit(0);
+    } else {
+      throw new Error(`Unknown install option: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function copyPlugin(sourcePluginDir, targetPluginDir) {
+  fs.rmSync(targetPluginDir, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(targetPluginDir), { recursive: true });
+  fs.cpSync(sourcePluginDir, targetPluginDir, {
+    recursive: true,
+    dereference: true,
+    filter: (source) => !source.includes(`${path.sep}.DS_Store`),
+  });
+}
+
+function createCodexMarketplace() {
+  return {
+    name: MARKETPLACE_NAME,
+    interface: {
+      displayName: DISPLAY_NAME,
+    },
+    plugins: [
+      {
+        name: PLUGIN_NAME,
+        source: {
+          source: "local",
+          path: `./plugins/${PLUGIN_NAME}`,
+        },
+        policy: {
+          installation: "AVAILABLE",
+          authentication: "ON_INSTALL",
+        },
+        category: "Productivity",
+      },
+    ],
+  };
+}
+
+function createClaudeMarketplace(version) {
+  return {
+    name: MARKETPLACE_NAME,
+    owner: {
+      name: "Trine",
+    },
+    description: "Data Vizard agent workflow plugins.",
+    version,
+    plugins: [
+      {
+        name: PLUGIN_NAME,
+        source: `./plugins/${PLUGIN_NAME}`,
+        displayName: DISPLAY_NAME,
+        description:
+          "Guide data visualization projects from dataset intake to analysis, narrative, design, and HTML story output.",
+        version,
+        author: {
+          name: "Trine",
+        },
+        repository: "https://github.com/inosaint/data-vizard",
+        license: "MIT",
+        keywords: ["data-visualization", "storytelling", "csv", "analysis", "html"],
+        category: "Productivity",
+      },
+    ],
+  };
+}
+
+function installCodex(marketplaceRoot, dryRun) {
+  console.log("");
+  console.log("Codex");
+
+  const addArgs = ["plugin", "marketplace", "add", marketplaceRoot];
+  const installArgs = ["plugin", "add", `${PLUGIN_NAME}@${MARKETPLACE_NAME}`];
+
+  if (dryRun) {
+    console.log(`Would run: codex ${addArgs.map(shellQuote).join(" ")}`);
+    console.log(`Would run: codex ${installArgs.join(" ")}`);
+    return;
+  }
+
+  if (!commandExists("codex")) {
+    console.log("Codex CLI was not found on PATH.");
+    printCodexCommands(marketplaceRoot);
+    return;
+  }
+
+  const add = run("codex", addArgs);
+  if (!add.ok) {
+    console.warn("Could not register the Codex marketplace automatically.");
+    printCommandOutput(add);
+    console.warn("Continuing in case the marketplace was already registered.");
+  }
+
+  const pluginInstall = run("codex", installArgs);
+  if (pluginInstall.ok) {
+    console.log("Installed data-vizard@data-vizard in Codex.");
+  } else {
+    console.warn("Could not install the Codex plugin automatically.");
+    printCommandOutput(pluginInstall);
+    printCodexCommands(marketplaceRoot);
+  }
+}
+
+function installClaude(marketplaceRoot, dryRun) {
+  console.log("");
+  console.log("Claude Code");
+
+  const marketplaceArgs = ["plugin", "marketplace", "add", marketplaceRoot];
+  const installArgs = ["plugin", "install", `${PLUGIN_NAME}@${MARKETPLACE_NAME}`];
+
+  if (dryRun) {
+    console.log(`Would run: claude ${marketplaceArgs.map(shellQuote).join(" ")}`);
+    console.log(`Would run: claude ${installArgs.join(" ")}`);
+    return;
+  }
+
+  if (!commandExists("claude")) {
+    console.log("Claude Code CLI was not found on PATH.");
+    printClaudeCommands(marketplaceRoot);
+    return;
+  }
+
+  const add = run("claude", marketplaceArgs);
+  if (!add.ok) {
+    console.warn("Could not register the Claude Code marketplace automatically.");
+    printCommandOutput(add);
+    console.warn("Continuing in case the marketplace was already registered.");
+  }
+
+  const pluginInstall = run("claude", installArgs);
+  if (pluginInstall.ok) {
+    console.log("Installed data-vizard@data-vizard in Claude Code.");
+  } else {
+    console.warn("Could not install the Claude Code plugin automatically.");
+    printCommandOutput(pluginInstall);
+    printClaudeCommands(marketplaceRoot);
+  }
+}
+
+function printManualCommands(marketplaceRoot) {
+  printCodexCommands(marketplaceRoot);
+  printClaudeCommands(marketplaceRoot);
+}
+
+function printCodexCommands(marketplaceRoot) {
+  console.log("");
+  console.log("To finish Codex installation manually:");
+  console.log(`  codex plugin marketplace add ${shellQuote(marketplaceRoot)}`);
+  console.log(`  codex plugin add ${PLUGIN_NAME}@${MARKETPLACE_NAME}`);
+}
+
+function printClaudeCommands(marketplaceRoot) {
+  console.log("");
+  console.log("To finish Claude Code installation manually:");
+  console.log(`  claude plugin marketplace add ${shellQuote(marketplaceRoot)}`);
+  console.log(`  claude plugin install ${PLUGIN_NAME}@${MARKETPLACE_NAME}`);
+  console.log("");
+  console.log("Or inside an interactive Claude Code session:");
+  console.log(`  /plugin marketplace add ${marketplaceRoot}`);
+  console.log(`  /plugin install ${PLUGIN_NAME}@${MARKETPLACE_NAME}`);
+  console.log("  /reload-plugins");
+}
+
+function commandExists(command) {
+  const result = spawnSync(command, ["--version"], { encoding: "utf8" });
+  return !(result.error && result.error.code === "ENOENT");
+}
+
+function run(command, args) {
+  const result = spawnSync(command, args, { encoding: "utf8" });
+  return {
+    ok: !result.error && result.status === 0,
+    status: result.status,
+    error: result.error,
+    stdout: result.stdout,
+    stderr: result.stderr,
+  };
+}
+
+function printCommandOutput(result) {
+  if (result.error) {
+    console.warn(`  ${result.error.message}`);
+  }
+  if (result.stderr && result.stderr.trim()) {
+    console.warn(indent(result.stderr.trim()));
+  }
+  if (result.stdout && result.stdout.trim()) {
+    console.warn(indent(result.stdout.trim()));
+  }
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function readPackageJson() {
+  return JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8"));
+}
+
+function expandHome(inputPath) {
+  if (inputPath === "~") {
+    return os.homedir();
+  }
+
+  if (inputPath.startsWith(`~${path.sep}`)) {
+    return path.join(os.homedir(), inputPath.slice(2));
+  }
+
+  return inputPath;
+}
+
+function shellQuote(value) {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) {
+    return value;
+  }
+
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function indent(value) {
+  return value
+    .split("\n")
+    .map((line) => `  ${line}`)
+    .join("\n");
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/package.json

@@ -1,16 +1,37 @@
 {
   "name": "data-vizard",
-  "version": "0.0.1",
-  "description": "Data Vizard installer",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "version": "0.1.0",
+  "description": "Installer for the Data Vizard agent workflow plugin.",
+  "license": "MIT",
+  "author": {
+    "name": "Trine"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "type": "commonjs",
+  "homepage": "https://github.com/inosaint/data-vizard#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/inosaint/data-vizard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/inosaint/data-vizard/issues"
+  },
+  "keywords": [
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "data-visualization",
+    "plugin"
+  ],
   "bin": {
-    "data-vizard": "./bin/data-vizard.js"
+    "data-vizard": "bin/data-vizard.js"
+  },
+  "files": [
+    "bin/",
+    "plugins/data-vizard/",
+    ".agents/plugins/marketplace.json",
+    ".claude-plugin/marketplace.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
   }
 }

package/plugins/data-vizard/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "data-vizard",
+  "displayName": "Data Vizard",
+  "version": "0.1.0",
+  "description": "Guide data visualization projects from dataset intake to analysis, narrative, design, and HTML story output.",
+  "author": {
+    "name": "Trine",
+    "url": "https://github.com/inosaint"
+  },
+  "repository": "https://github.com/inosaint/data-vizard",
+  "license": "MIT",
+  "keywords": [
+    "data-visualization",
+    "storytelling",
+    "csv",
+    "analysis",
+    "html"
+  ],
+  "skills": "./skills/"
+}

package/plugins/data-vizard/.codex-plugin/plugin.json

@@ -0,0 +1,36 @@
+{
+  "name": "data-vizard",
+  "version": "0.1.0",
+  "description": "A staged data visualization workshop for moving from dataset intake to analysis, narrative, design, and an HTML artifact.",
+  "author": {
+    "name": "Trine"
+  },
+  "license": "MIT",
+  "keywords": [
+    "data-visualization",
+    "storytelling",
+    "csv",
+    "analysis",
+    "html"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Data Vizard",
+    "shortDescription": "Guide data visualization projects from dataset to HTML story.",
+    "longDescription": "Data Vizard bundles five Codex skills for a complete data visualization workflow: orchestration, data curation, exploratory analysis, narrative framing, and HTML visualization design.",
+    "developerName": "Trine",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive",
+      "Write",
+      "Data Analysis",
+      "Visualization"
+    ],
+    "brandColor": "#2563EB",
+    "defaultPrompt": [
+      "Use Data Vizard to build a visualization from this CSV.",
+      "Guide me from dataset intake to an HTML data story.",
+      "Help me choose the best story direction for this dataset."
+    ]
+  }
+}