@coordiation/agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Coordiation contributors
+
+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,14 @@
+# @coordiation/agent
+
+Compact, deterministic project context for AI agents using Coordiation.
+
+```js
+import { createContextPack, inspectProject } from "@coordiation/agent";
+
+const manifest = await inspectProject({ cwd: process.cwd() });
+const pricingContext = createContextPack("pricing", manifest);
+```
+
+The compact manifest reports the active framework, Coordiation packages, utility families, frequent literal classes, project rules, and trackable warnings without sending the entire source tree to an agent.
+
+Available context packs: `page`, `navigation`, `form`, `dashboard`, `pricing`, `component`, and `theme`.

package/agent-manifest.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://coordiation.com/schemas/agent-manifest.json",
+  "title": "Coordiation Agent Manifest",
+  "type": "object",
+  "required": ["schemaVersion", "kind", "project", "coordiation", "contracts", "tracking"],
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "kind": { "const": "coordiation-agent-manifest" },
+    "project": {
+      "type": "object",
+      "required": ["name", "framework", "packageManager"],
+      "properties": {
+        "name": { "type": "string" },
+        "framework": { "type": "string" },
+        "packageManager": { "type": "string" }
+      }
+    },
+    "coordiation": {
+      "type": "object",
+      "required": ["prefix", "packages", "utilityCount", "utilityFamilies"],
+      "properties": {
+        "prefix": { "type": "string" },
+        "packages": { "type": "array", "items": { "type": "string" } },
+        "utilityCount": { "type": "integer", "minimum": 0 },
+        "utilityFamilies": { "type": "object", "additionalProperties": { "type": "integer" } }
+      }
+    },
+    "contracts": { "type": "object" },
+    "tracking": { "type": "object" },
+    "contextBudget": { "type": "object" }
+  },
+  "additionalProperties": true
+}

package/context-packs.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "./agent-manifest.schema.json",
+  "schemaVersion": "1.0",
+  "packs": {
+    "page": {
+      "intent": "Build a complete responsive page from semantic sections.",
+      "components": ["button", "card", "separator", "typography"],
+      "utilityHints": ["co-grid", "co-flex", "co-gap-6", "co-w-full", "co-max-w-screen-xl"],
+      "checks": ["semantic landmarks", "responsive layout", "visible focus", "no horizontal overflow"]
+    },
+    "navigation": {
+      "intent": "Build accessible desktop and mobile navigation.",
+      "components": ["button", "navigation-menu", "sheet"],
+      "utilityHints": ["co-flex", "co-items-center", "co-justify-between", "co-hidden", "md:co-flex"],
+      "checks": ["keyboard access", "mobile trigger label", "active state", "focus return"]
+    },
+    "form": {
+      "intent": "Build an accessible validated form with literal styling states.",
+      "components": ["button", "field", "input", "label", "select", "textarea"],
+      "utilityHints": ["co-grid", "co-gap-4", "focus:co-ring-2", "disabled:co-opacity-50"],
+      "checks": ["label association", "error description", "disabled state", "keyboard submission"]
+    },
+    "dashboard": {
+      "intent": "Build a dense responsive application workspace.",
+      "components": ["avatar", "badge", "card", "data-table", "progress", "sidebar"],
+      "utilityHints": ["co-grid", "lg:co-grid-cols-12", "co-gap-4", "co-overflow-x-auto"],
+      "checks": ["mobile sidebar", "table overflow", "status semantics", "readable data density"]
+    },
+    "pricing": {
+      "intent": "Build a comparable pricing section with a clear recommended plan.",
+      "components": ["badge", "button", "card", "separator"],
+      "utilityHints": ["co-grid", "md:co-grid-cols-3", "co-gap-5", "co-border", "co-ring-2"],
+      "checks": ["comparable features", "recommended label", "CTA contrast", "maximum three-line titles"]
+    },
+    "component": {
+      "intent": "Create one reusable Coordiation-native UI primitive.",
+      "components": ["button", "label"],
+      "utilityHints": ["co-inline-flex", "co-items-center", "co-transition", "focus-visible:co-ring-2"],
+      "checks": ["typed API", "all interaction states", "accessible name", "reduced motion"]
+    },
+    "theme": {
+      "intent": "Create an installable open-code application theme.",
+      "components": ["button", "card", "ThemeIcon"],
+      "utilityHints": ["co-grid", "co-flex", "co-transition", "motion-reduce:co-animate-none"],
+      "checks": ["namespaced CSS", "Coordiation icons", "Coordiation copyright", "registry contract", "responsive preview"]
+    }
+  }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@coordiation/agent",
+  "version": "0.1.0",
+  "description": "Compact project manifests and task context packs for AI agents using Coordiation",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.js",
+    "./context-packs.json": "./context-packs.json",
+    "./agent-manifest.schema.json": "./agent-manifest.schema.json"
+  },
+  "files": [
+    "src",
+    "context-packs.json",
+    "agent-manifest.schema.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://coordiation.com/docs/tooling/agent-context",
+  "author": "Wiryo Saputra <wiryosaputra@coordiation.com>"
+}

package/src/index.js

@@ -0,0 +1,207 @@
+import { constants } from "node:fs";
+import { access, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { dirname, extname, join, relative, resolve, sep } from "node:path";
+import contextPackRegistry from "../context-packs.json" with { type: "json" };
+
+export const AGENT_SCHEMA_VERSION = "1.0";
+export const AGENT_MANIFEST_PATH = ".coordiation/agent-manifest.json";
+export const contextPacks = contextPackRegistry.packs;
+
+const SOURCE_EXTENSIONS = new Set([".astro", ".blade.php", ".coord", ".css", ".html", ".htm", ".js", ".jsx", ".md", ".mdx", ".php", ".svelte", ".ts", ".tsx", ".vue"]);
+const DEFAULT_SOURCE_ROOTS = ["app", "src", "pages", "components", "resources", "templates", "packages", "site/app"];
+const IGNORED_DIRECTORIES = new Set([".git", ".next", ".output", ".vinext", "build", "coverage", "dist", "node_modules", "vendor"]);
+const UTILITY_PATTERN = /(?:[a-z0-9-]+:)*!?-?co-[a-z0-9][a-z0-9_./:[\]()%#,-]*/gi;
+
+async function exists(pathname) {
+  try { await access(pathname, constants.F_OK); return true; } catch { return false; }
+}
+
+async function readJson(pathname, fallback = {}) {
+  try { return JSON.parse(await readFile(pathname, "utf8")); } catch { return fallback; }
+}
+
+function allDependencies(packageJson) {
+  return { ...(packageJson.dependencies ?? {}), ...(packageJson.devDependencies ?? {}), ...(packageJson.peerDependencies ?? {}) };
+}
+
+function detectFramework(dependencies) {
+  if (dependencies.next) return "Next.js";
+  if (dependencies.astro) return "Astro";
+  if (dependencies["@sveltejs/kit"] || dependencies.svelte) return "SvelteKit";
+  if (dependencies.nuxt || dependencies.vue) return dependencies.nuxt ? "Nuxt" : "Vue";
+  if (dependencies["@angular/core"]) return "Angular";
+  if (dependencies.react) return "React";
+  if (dependencies.vite) return "Vite";
+  return "framework-agnostic";
+}
+
+async function detectPackageManager(cwd) {
+  if (await exists(join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (await exists(join(cwd, "yarn.lock"))) return "yarn";
+  if (await exists(join(cwd, "bun.lock")) || await exists(join(cwd, "bun.lockb"))) return "bun";
+  if (await exists(join(cwd, "package-lock.json"))) return "npm";
+  return "unknown";
+}
+
+function isSourceFile(name) {
+  if (name.endsWith(".blade.php")) return true;
+  return SOURCE_EXTENSIONS.has(extname(name).toLowerCase());
+}
+
+async function collectSourceFiles(cwd, maxFiles) {
+  const files = [];
+  async function walk(directory) {
+    if (files.length >= maxFiles) return;
+    let entries;
+    try { entries = await readdir(directory, { withFileTypes: true }); } catch { return; }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (files.length >= maxFiles) return;
+      if (entry.isDirectory()) {
+        if (!IGNORED_DIRECTORIES.has(entry.name) && !entry.name.startsWith(".")) await walk(join(directory, entry.name));
+      } else if (entry.isFile() && isSourceFile(entry.name)) files.push(join(directory, entry.name));
+    }
+  }
+  for (const root of DEFAULT_SOURCE_ROOTS) {
+    const directory = join(cwd, root);
+    if (await exists(directory)) await walk(directory);
+  }
+  return files;
+}
+
+function utilityFamily(candidate) {
+  const base = candidate.slice(candidate.lastIndexOf(":") + 1).replace(/^!/, "").replace(/^-/, "").replace(/^co-/, "");
+  if (base.startsWith("bg-")) return "backgrounds";
+  if (base.startsWith("text-") || base.startsWith("font-") || base.startsWith("leading-") || base.startsWith("tracking-")) return "typography";
+  if (/^(m|p|gap|space)-/.test(base)) return "spacing";
+  if (/^(w|h|min-|max-|size-)/.test(base)) return "sizing";
+  if (/^(grid|col-|row-|flex|items-|justify-|content-|place-)/.test(base)) return "flex-grid";
+  if (/^(border|rounded|ring)/.test(base)) return "borders-rings";
+  if (/^(shadow|opacity|mix-blend|blur|filter)/.test(base)) return "effects";
+  if (/^(transition|duration|ease|animate|delay)/.test(base)) return "transitions";
+  if (/^(translate|rotate|scale|skew|transform)/.test(base)) return "transforms";
+  if (/^(cursor|pointer-events|select-|resize|scroll|touch)/.test(base)) return "interaction";
+  return "layout";
+}
+
+function compactPath(cwd, pathname) {
+  return relative(cwd, pathname).split(sep).join("/");
+}
+
+export async function inspectProject({ cwd = process.cwd(), full = false, maxFiles = 2000 } = {}) {
+  const root = resolve(cwd);
+  const packageJson = await readJson(join(root, "package.json"), { name: root.split(sep).at(-1) });
+  const dependencies = allDependencies(packageJson);
+  const files = await collectSourceFiles(root, maxFiles);
+  const utilityFrequency = new Map();
+  const componentImports = new Set();
+  let dynamicCandidateCount = 0;
+  let unreadableFileCount = 0;
+
+  for (const filename of files) {
+    let source;
+    try { source = await readFile(filename, "utf8"); } catch { unreadableFileCount += 1; continue; }
+    for (const match of source.matchAll(UTILITY_PATTERN)) {
+      const preceding = source[(match.index ?? 0) - 1];
+      if (preceding === "-" || preceding === "@") continue;
+      if (match[0].endsWith("-")) continue;
+      const candidate = match[0].replace(/[),.;]+$/, "");
+      utilityFrequency.set(candidate, (utilityFrequency.get(candidate) ?? 0) + 1);
+    }
+    dynamicCandidateCount += (source.match(/class(?:Name)?\s*=\s*[^\n]{0,80}co-[^\n]{0,32}\$\{/g) ?? []).length;
+    for (const match of source.matchAll(/from\s+["'](@coordiation\/[^"']+)["']/g)) componentImports.add(match[1]);
+  }
+
+  const utilities = [...utilityFrequency.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+  const utilityFamilies = {};
+  for (const [candidate] of utilities) {
+    const family = utilityFamily(candidate);
+    utilityFamilies[family] = (utilityFamilies[family] ?? 0) + 1;
+  }
+  const packages = [...new Set([
+    ...Object.keys(dependencies).filter((name) => name.startsWith("@coordiation/")),
+    ...[...componentImports].map((name) => name.split("/").slice(0, 2).join("/")),
+  ])].sort();
+  const manifest = {
+    schemaVersion: AGENT_SCHEMA_VERSION,
+    kind: "coordiation-agent-manifest",
+    project: {
+      name: packageJson.name ?? root.split(sep).at(-1),
+      framework: detectFramework(dependencies),
+      packageManager: await detectPackageManager(root),
+    },
+    coordiation: {
+      prefix: "co-",
+      packages,
+      componentImports: [...componentImports].sort(),
+      utilityCount: utilities.length,
+      utilityFamilies: Object.fromEntries(Object.entries(utilityFamilies).sort(([a], [b]) => a.localeCompare(b))),
+      frequentUtilities: utilities.slice(0, 30).map(([candidate, count]) => ({ candidate, count })),
+    },
+    contracts: {
+      sourceOwnership: "open-code",
+      classStrategy: "literal-static-candidates",
+      browserRuntime: 0,
+      responsive: "required",
+      accessibility: "required",
+      motion: "respect-prefers-reduced-motion",
+      icons: "use-Coordiation-icon-components",
+      copyright: "Coordiation",
+    },
+    tracking: {
+      scannedFiles: files.length,
+      scanLimitReached: files.length >= maxFiles,
+      unreadableFiles: unreadableFileCount,
+      dynamicCandidateCount,
+      warnings: dynamicCandidateCount ? ["Dynamic co-* candidates may be invisible to the compiler. Replace interpolation with literal lookup values."] : [],
+    },
+    commands: {
+      addComponent: "coordiation add component <name>",
+      addTheme: "coordiation add theme <name>",
+      context: "coordiation context <topic> --json",
+      refreshManifest: "coordiation inspect --write",
+    },
+  };
+  if (full) {
+    manifest.coordiation.utilities = utilities.map(([candidate, count]) => ({ candidate, count }));
+    manifest.tracking.sourceFiles = files.map((filename) => compactPath(root, filename));
+  }
+  const bytes = Buffer.byteLength(JSON.stringify(manifest));
+  manifest.contextBudget = { mode: full ? "full" : "compact", bytes, estimatedTokens: Math.ceil(bytes / 4) };
+  return manifest;
+}
+
+export function createContextPack(topic, manifest) {
+  const normalized = String(topic ?? "").trim().toLowerCase();
+  const definition = contextPacks[normalized];
+  if (!definition) throw new Error(`Unknown context topic: ${topic}. Available: ${Object.keys(contextPacks).join(", ")}`);
+  const currentUtilities = manifest?.coordiation?.frequentUtilities ?? [];
+  const relevantUtilities = currentUtilities.filter(({ candidate }) => definition.utilityHints.some((hint) => candidate.includes(hint.replace(/^.*:/, "").replace(/^co-/, "")))).slice(0, 15);
+  return {
+    schemaVersion: AGENT_SCHEMA_VERSION,
+    kind: "coordiation-context-pack",
+    topic: normalized,
+    intent: definition.intent,
+    project: manifest ? { name: manifest.project.name, framework: manifest.project.framework, prefix: manifest.coordiation.prefix } : undefined,
+    components: definition.components,
+    utilityHints: definition.utilityHints,
+    currentUtilities: relevantUtilities,
+    rules: manifest?.contracts ?? {
+      classStrategy: "literal-static-candidates",
+      responsive: "required",
+      accessibility: "required",
+      icons: "use-Coordiation-icon-components",
+    },
+    checks: definition.checks,
+    workflow: ["inspect project", "reuse registered primitives", "generate literal classes", "validate checks", "run project build"],
+  };
+}
+
+export async function writeAgentManifest(manifest, { cwd = process.cwd(), output = AGENT_MANIFEST_PATH } = {}) {
+  const destination = resolve(cwd, output);
+  const root = resolve(cwd);
+  if (destination !== root && !destination.startsWith(`${root}${sep}`)) throw new Error(`Manifest output leaves the project: ${output}`);
+  await mkdir(dirname(destination), { recursive: true });
+  await writeFile(destination, `${JSON.stringify(manifest, null, 2)}\n`);
+  return compactPath(root, destination);
+}