macro-agent 0.1.1 → 0.1.2

package/references/openteams/src/generators/package-generator.ts

@@ -0,0 +1,102 @@
+import fs from "fs";
+import path from "path";
+import type { ResolvedTemplate } from "../template/types";
+import { generateSkillMd } from "./skill-generator";
+import { generateCatalog } from "./skill-generator";
+import { generateAllRoleSkillMds } from "./agent-prompt-generator";
+
+export interface PackageGeneratorOptions {
+  /** Team name override (defaults to manifest name) */
+  teamName?: string;
+  /** Output directory for the package */
+  outputDir: string;
+}
+
+export interface PackageResult {
+  /** Path to the generated top-level SKILL.md (catalog) */
+  catalogPath: string;
+  /** Paths to generated per-role SKILL.md files */
+  rolePaths: { role: string; path: string }[];
+  /** Path to the copied team.yaml (if source exists) */
+  manifestPath: string | null;
+}
+
+/**
+ * Generates a complete skill package directory from a resolved template.
+ *
+ * Package structure:
+ *   <outputDir>/
+ *   ├── SKILL.md                 # Team catalog (progressive disclosure)
+ *   ├── team.yaml                # Copy of source manifest
+ *   ├── roles/
+ *   │   ├── <role>/
+ *   │   │   └── SKILL.md         # Standalone role context
+ *   │   └── ...
+ *   └── prompts/                 # Copy of source prompts (if any)
+ *       └── <role>.md
+ */
+export function generatePackage(
+  template: ResolvedTemplate,
+  options: PackageGeneratorOptions
+): PackageResult {
+  const teamName = options.teamName ?? template.manifest.name;
+  const outDir = path.resolve(options.outputDir);
+
+  // Create output directory
+  fs.mkdirSync(outDir, { recursive: true });
+
+  // 1. Generate top-level SKILL.md (catalog)
+  const catalogContent = generateCatalog(template, { teamName });
+  const catalogPath = path.join(outDir, "SKILL.md");
+  fs.writeFileSync(catalogPath, catalogContent, "utf-8");
+
+  // 2. Generate per-role SKILL.md files
+  const roleSkills = generateAllRoleSkillMds(template, { teamName });
+  const rolePaths: { role: string; path: string }[] = [];
+
+  for (const roleSkill of roleSkills) {
+    const roleDir = path.join(outDir, "roles", roleSkill.role);
+    fs.mkdirSync(roleDir, { recursive: true });
+    const rolePath = path.join(roleDir, "SKILL.md");
+    fs.writeFileSync(rolePath, roleSkill.content, "utf-8");
+    rolePaths.push({ role: roleSkill.role, path: rolePath });
+  }
+
+  // 3. Copy team.yaml if source exists
+  let manifestPath: string | null = null;
+  if (template.sourcePath) {
+    const sourceManifest = path.join(template.sourcePath, "team.yaml");
+    if (fs.existsSync(sourceManifest)) {
+      manifestPath = path.join(outDir, "team.yaml");
+      fs.copyFileSync(sourceManifest, manifestPath);
+    }
+  }
+
+  // 4. Copy prompts if source exists (supports both files and directories)
+  if (template.sourcePath) {
+    const sourcePrompts = path.join(template.sourcePath, "prompts");
+    if (fs.existsSync(sourcePrompts)) {
+      const promptsDir = path.join(outDir, "prompts");
+      fs.mkdirSync(promptsDir, { recursive: true });
+      const entries = fs.readdirSync(sourcePrompts, { withFileTypes: true });
+      for (const entry of entries) {
+        const srcPath = path.join(sourcePrompts, entry.name);
+        const destPath = path.join(promptsDir, entry.name);
+        if (entry.isDirectory()) {
+          fs.mkdirSync(destPath, { recursive: true });
+          const subFiles = fs.readdirSync(srcPath);
+          for (const subFile of subFiles) {
+            fs.copyFileSync(
+              path.join(srcPath, subFile),
+              path.join(destPath, subFile)
+            );
+          }
+        } else {
+          fs.copyFileSync(srcPath, destPath);
+        }
+      }
+    }
+  }
+
+  return { catalogPath, rolePaths, manifestPath };
+}

package/references/openteams/src/generators/skill-generator.test.ts

@@ -0,0 +1,246 @@
+import { describe, it, expect } from "vitest";
+import { TemplateLoader } from "../template/loader";
+import { generateSkillMd, generateCatalog } from "./skill-generator";
+import type { TeamManifest, ResolvedTemplate } from "../template/types";
+
+function makeMinimalTemplate(): ResolvedTemplate {
+  const manifest: TeamManifest = {
+    name: "test-team",
+    version: 1,
+    roles: ["lead", "worker"],
+    topology: {
+      root: { role: "lead" },
+    },
+  };
+  return TemplateLoader.loadFromManifest(manifest);
+}
+
+function makeFullTemplate(): ResolvedTemplate {
+  const manifest: TeamManifest = {
+    name: "self-driving",
+    description: "Autonomous codebase development",
+    version: 1,
+    roles: ["planner", "grinder", "judge"],
+    topology: {
+      root: {
+        role: "planner",
+        config: { model: "sonnet" },
+      },
+      companions: [{ role: "judge" }],
+      spawn_rules: {
+        planner: ["grinder", "planner"],
+        judge: [],
+        grinder: [],
+      },
+    },
+    communication: {
+      enforcement: "strict",
+      channels: {
+        task_updates: {
+          description: "Task lifecycle events",
+          signals: ["TASK_CREATED", "TASK_COMPLETED", "TASK_FAILED"],
+        },
+        work_coordination: {
+          signals: ["WORK_ASSIGNED", "WORKER_DONE"],
+        },
+      },
+      subscriptions: {
+        planner: [
+          { channel: "task_updates" },
+          { channel: "work_coordination", signals: ["WORKER_DONE"] },
+        ],
+        judge: [{ channel: "task_updates", signals: ["TASK_FAILED"] }],
+        grinder: [
+          { channel: "work_coordination", signals: ["WORK_ASSIGNED"] },
+        ],
+      },
+      emissions: {
+        planner: ["TASK_CREATED", "WORK_ASSIGNED"],
+        grinder: ["WORKER_DONE"],
+      },
+      routing: {
+        status: "upstream",
+        peers: [
+          {
+            from: "judge",
+            to: "planner",
+            via: "direct",
+            signals: ["FIXUP_CREATED"],
+          },
+        ],
+      },
+    },
+  };
+  return TemplateLoader.loadFromManifest(manifest);
+}
+
+describe("generateSkillMd", () => {
+  it("generates header with team name", () => {
+    const md = generateSkillMd(makeMinimalTemplate());
+    expect(md).toContain("# Team: test-team");
+  });
+
+  it("includes description when present", () => {
+    const md = generateSkillMd(makeFullTemplate());
+    expect(md).toContain("> Autonomous codebase development");
+  });
+
+  it("generates team structure section", () => {
+    const md = generateSkillMd(makeFullTemplate());
+    expect(md).toContain("## Team Structure");
+    expect(md).toContain("**Root**: planner (model: sonnet)");
+    expect(md).toContain("**Companions**: judge");
+    expect(md).toContain("planner, grinder, judge");
+  });
+
+  it("generates roles section", () => {
+    const md = generateSkillMd(makeFullTemplate());
+    expect(md).toContain("## Roles");
+    expect(md).toContain("### planner");
+    expect(md).toContain("### grinder");
+    expect(md).toContain("### judge");
+  });
+
+  it("generates channels table", () => {
+    const md = generateSkillMd(makeFullTemplate());
+    expect(md).toContain("### Channels");
+    expect(md).toContain("| task_updates |");
+    expect(md).toContain("TASK_CREATED, TASK_COMPLETED, TASK_FAILED");
+    expect(md).toContain("| work_coordination |");
+  });
+
+  it("generates subscriptions table", () => {
+    const md = generateSkillMd(makeFullTemplate());
+    expect(md).toContain("### Subscriptions");
+    expect(md).toContain("| planner | task_updates | all |");
+    expect(md).toContain("| planner | work_coordination | WORKER_DONE |");
+    expect(md).toContain("| judge | task_updates | TASK_FAILED |");
+    expect(md).toContain("| grinder | work_coordination | WORK_ASSIGNED |");
+  });
+
+  it("generates emission permissions table", () => {
+    const md = generateSkillMd(makeFullTemplate());
+    expect(md).toContain("### Emission Permissions");
+    expect(md).toContain("| planner | TASK_CREATED, WORK_ASSIGNED |");
+    expect(md).toContain("| grinder | WORKER_DONE |");
+  });
+
+  it("generates peer routes table", () => {
+    const md = generateSkillMd(makeFullTemplate());
+    expect(md).toContain("### Peer Routes");
+    expect(md).toContain("| judge | planner | direct | FIXUP_CREATED |");
+  });
+
+  it("generates spawn rules table", () => {
+    const md = generateSkillMd(makeFullTemplate());
+    expect(md).toContain("## Spawn Rules");
+    expect(md).toContain("| planner | grinder, planner |");
+    expect(md).toContain("| judge | (none) |");
+    expect(md).toContain("| grinder | (none) |");
+  });
+
+  it("generates interaction guidelines with CLI examples", () => {
+    const md = generateSkillMd(makeFullTemplate());
+    expect(md).toContain("## Agent Interaction Guidelines");
+    expect(md).toContain("openteams task list self-driving");
+    expect(md).toContain("openteams message send self-driving");
+    expect(md).toContain("openteams template emit self-driving");
+    expect(md).toContain("openteams template events self-driving");
+  });
+
+  it("respects team name override", () => {
+    const md = generateSkillMd(makeFullTemplate(), {
+      teamName: "my-project",
+    });
+    expect(md).toContain("# Team: my-project");
+    expect(md).toContain("openteams task list my-project");
+  });
+
+  it("omits CLI examples when disabled", () => {
+    const md = generateSkillMd(makeFullTemplate(), {
+      includeCliExamples: false,
+    });
+    expect(md).not.toContain("```bash");
+  });
+
+  it("omits communication section when no communication config", () => {
+    const md = generateSkillMd(makeMinimalTemplate());
+    expect(md).not.toContain("## Communication");
+  });
+
+  it("omits spawn rules section when none defined", () => {
+    const md = generateSkillMd(makeMinimalTemplate());
+    expect(md).not.toContain("## Spawn Rules");
+  });
+
+  it("shows enforcement mode", () => {
+    const md = generateSkillMd(makeFullTemplate());
+    expect(md).toContain("Enforcement: **strict**");
+    expect(md).toContain("Unauthorized emissions will be rejected");
+  });
+
+  it("shows status routing when present", () => {
+    const md = generateSkillMd(makeFullTemplate());
+    expect(md).toContain("### Status Routing: **upstream**");
+  });
+
+  it("includes YAML frontmatter when enabled", () => {
+    const md = generateSkillMd(makeFullTemplate(), {
+      includeFrontmatter: true,
+    });
+    expect(md).toMatch(/^---\n/);
+    expect(md).toContain("name: self-driving");
+    expect(md).toContain("description: Autonomous codebase development");
+    expect(md).toContain("roles: [planner, grinder, judge]");
+    expect(md).toContain("root: planner");
+    expect(md).toContain("\n---\n");
+  });
+
+  it("omits frontmatter by default", () => {
+    const md = generateSkillMd(makeFullTemplate());
+    expect(md).not.toMatch(/^---\n/);
+  });
+});
+
+describe("generateCatalog", () => {
+  it("includes team name and description", () => {
+    const catalog = generateCatalog(makeFullTemplate());
+    expect(catalog).toContain("# Team: self-driving");
+    expect(catalog).toContain("> Autonomous codebase development");
+  });
+
+  it("generates roles table with positions", () => {
+    const catalog = generateCatalog(makeFullTemplate());
+    expect(catalog).toContain("| Role | Description | Position |");
+    expect(catalog).toContain("| planner |");
+    expect(catalog).toContain("| root |");
+    expect(catalog).toContain("| judge |");
+    expect(catalog).toContain("| companion |");
+    expect(catalog).toContain("| grinder |");
+    expect(catalog).toContain("| spawned |");
+  });
+
+  it("includes role loading instructions", () => {
+    const catalog = generateCatalog(makeFullTemplate());
+    expect(catalog).toContain("## Loading a role");
+    expect(catalog).toContain("`roles/planner/SKILL.md`");
+    expect(catalog).toContain("`roles/grinder/SKILL.md`");
+    expect(catalog).toContain("`roles/judge/SKILL.md`");
+  });
+
+  it("respects team name override", () => {
+    const catalog = generateCatalog(makeFullTemplate(), {
+      teamName: "my-project",
+    });
+    expect(catalog).toContain("# Team: my-project");
+  });
+
+  it("works with minimal template", () => {
+    const catalog = generateCatalog(makeMinimalTemplate());
+    expect(catalog).toContain("# Team: test-team");
+    expect(catalog).toContain("| lead |");
+    expect(catalog).toContain("| root |");
+    expect(catalog).toContain("| worker |");
+    expect(catalog).toContain("| spawned |");
+  });
+});