awesome-agents 0.1.1 → 0.1.3

package/src/installer.js

@@ -21,11 +21,11 @@ export async function installFromSource(sourceSpec, options = {}) {
   const split = splitSourceSpec(sourceSpec);
   const source = split.source;
   const { selectors, harnessInput } = resolveInstallSelection(split, options);
-  const scope = resolveScope(options);
   const harnesses = normalizeAgentList(harnessInput, {
     all: options.all,
     defaultAgent: DEFAULT_AGENT
   });
+  const scope = resolveScope(options, harnesses);
 
   const materialized = await materializeSource(source, options);
   try {
@@ -71,7 +71,11 @@ export async function installFromSource(sourceSpec, options = {}) {
       await writeRegistry(registry, registryOptions);
     }
 
-    return { operations, registryPath: registryPath(registryOptions) };
+    return {
+      operations,
+      registryPath: registryPath(registryOptions),
+      runInstructions: buildRunInstructions(operations)
+    };
   } finally {
     await materialized.cleanup();
   }
@@ -104,10 +108,11 @@ export async function useFromSource(sourceSpec, options = {}) {
 }
 
 export async function listInstalled(options = {}) {
-  const scope = resolveScope(options);
-  const registry = await readRegistry({ ...options, scope });
   const harnessInput = options.agents ?? options.agent;
-  const harnessFilter = harnessInput ? new Set(normalizeAgentList(harnessInput)) : undefined;
+  const harnesses = harnessInput ? normalizeAgentList(harnessInput) : [];
+  const scope = resolveScope(options, harnesses);
+  const registry = await readRegistry({ ...options, scope });
+  const harnessFilter = harnesses.length > 0 ? new Set(harnesses) : undefined;
   const installs = registry.installs
     .filter((install) => !harnessFilter || harnessFilter.has(install.harness))
     .map((install) => ({
@@ -123,7 +128,9 @@ export async function listInstalled(options = {}) {
 }
 
 export async function removeInstalled(profileArgs = [], options = {}) {
-  const scope = resolveScope(options);
+  const harnessInput = options.agents ?? options.agent;
+  const harnesses = harnessInput ? normalizeAgentList(harnessInput) : [];
+  const scope = resolveScope(options, harnesses);
   const registryOptions = { ...options, scope };
   const registry = await readRegistry(registryOptions);
   const selectors = normalizeProfileSelectors(profileArgs);
@@ -132,8 +139,7 @@ export async function removeInstalled(profileArgs = [], options = {}) {
     throw new Error("Specify at least one profile to remove, or pass --all.");
   }
 
-  const harnessInput = options.agents ?? options.agent;
-  const harnessFilter = harnessInput ? new Set(normalizeAgentList(harnessInput)) : undefined;
+  const harnessFilter = harnesses.length > 0 ? new Set(harnesses) : undefined;
   const operations = [];
   const matched = registry.installs.filter((install) => {
     const profileMatch = removeAll || selectors.includes(install.profile);
@@ -172,12 +178,13 @@ export async function removeInstalled(profileArgs = [], options = {}) {
 }
 
 export async function updateInstalled(profileArgs = [], options = {}) {
-  const scope = resolveScope(options);
+  const harnessInput = options.agents ?? options.agent;
+  const harnesses = harnessInput ? normalizeAgentList(harnessInput) : [];
+  const scope = resolveScope(options, harnesses);
   const registryOptions = { ...options, scope };
   const registry = await readRegistry(registryOptions);
   const selectors = normalizeProfileSelectors(profileArgs);
-  const harnessInput = options.agents ?? options.agent;
-  const harnessFilter = harnessInput ? new Set(normalizeAgentList(harnessInput)) : undefined;
+  const harnessFilter = harnesses.length > 0 ? new Set(harnesses) : undefined;
   const candidates = registry.installs.filter((install) => {
     const profileMatch = selectors.length === 0 || selectors.includes(install.profile);
     const harnessMatch = !harnessFilter || harnessFilter.has(install.harness);
@@ -185,6 +192,7 @@ export async function updateInstalled(profileArgs = [], options = {}) {
   });
 
   const operations = [];
+  const runInstructions = [];
   for (const install of candidates) {
     const result = await installFromSource(install.source, {
       ...options,
@@ -198,42 +206,126 @@ export async function updateInstalled(profileArgs = [], options = {}) {
       ...operation,
       action: options.dryRun ? "would-update" : "updated"
     })));
+    runInstructions.push(...result.runInstructions);
   }
 
-  return { operations, registryPath: registryPath(registryOptions) };
+  return { operations, registryPath: registryPath(registryOptions), runInstructions };
 }
 
 export async function initProfile(name, options = {}) {
   const slug = slugify(name || "new-agent-profile");
   const root = options.cwd ?? process.cwd();
-  const profilePath = path.join(root, "agents", "profiles", `${slug}.md`);
-  const adapterPath = path.join(root, "agents", "adapters", "codex", `${slug}.md`);
+  const profilePath = path.join(root, "agents", "profiles", `${slug}.agent.yaml`);
 
   if (!options.force) {
-    for (const target of [profilePath, adapterPath]) {
-      if (existsSync(target)) {
-        throw new Error(`${target} already exists. Pass --force to overwrite.`);
-      }
+    if (existsSync(profilePath)) {
+      throw new Error(`${profilePath} already exists. Pass --force to overwrite.`);
     }
   }
 
   const title = titleCase(slug);
-  const profileContent = `---\nslug: ${slug}\nname: ${title}\nkind: operational-agent-profile\nsummary: Describe when to use this agent profile.\nrecommended_model: inherit\nrecommended_reasoning_effort: medium\nhome_notes_template: "~/.agents/homes/${slug}/<project>/notes"\n---\n\n# ${title}\n\nDescribe the agent's mission, boundaries, tools, coordination model, notes, and reporting style.\n`;
-  const adapterContent = `---\nslug: ${slug}\nprofile: ../../profiles/${slug}.md\nharness: codex\nmodel: inherit\nreasoning_effort: medium\nrequired_skills: []\n---\n\n# Codex Adapter: ${title}\n\nLoad the canonical profile at \`agents/profiles/${slug}.md\`.\n`;
+  const profileContent = `schema: awesome-agents/v1\nid: ${slug}\nname: ${title}\ndescription: Describe when to use this agent profile.\nmodel: inherit\nreasoning_effort: medium\nhome_notes_template: "~/.agents/homes/${slug}/<project>/notes"\ninstructions: |\n  Describe the agent's mission, boundaries, tools, coordination model, notes,\n  and reporting style.\n`;
 
   if (!options.dryRun) {
     await fs.mkdir(path.dirname(profilePath), { recursive: true });
-    await fs.mkdir(path.dirname(adapterPath), { recursive: true });
     await fs.writeFile(profilePath, profileContent);
-    await fs.writeFile(adapterPath, adapterContent);
   }
 
   return {
     action: options.dryRun ? "would-init" : "initialized",
-    files: [profilePath, adapterPath]
+    files: [profilePath]
   };
 }
 
+function buildRunInstructions(operations, env = process.env) {
+  const instructions = [];
+  const seen = new Set();
+
+  for (const operation of operations) {
+    if (String(operation.action).startsWith("would-")) {
+      continue;
+    }
+
+    const instruction = runInstructionForOperation(operation, env);
+    if (!instruction) {
+      continue;
+    }
+
+    const key = `${instruction.harness}:${instruction.profile}:${instruction.command}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    instructions.push(instruction);
+  }
+
+  return instructions;
+}
+
+function runInstructionForOperation(operation, env) {
+  if (operation.harness === "codex") {
+    if (!commandExists("codex", env)) {
+      return undefined;
+    }
+    return {
+      profile: operation.profile,
+      harness: operation.harness,
+      command: `codex --profile ${shellWord(operation.profile)}`,
+      note: "Starts Codex with this installed profile."
+    };
+  }
+
+  if (operation.harness === "claude-code") {
+    if (!commandExists("claude", env)) {
+      return undefined;
+    }
+    return {
+      profile: operation.profile,
+      harness: operation.harness,
+      command: `claude --agent ${shellWord(operation.profile)}`,
+      note: "Starts Claude Code with this installed agent profile."
+    };
+  }
+
+  if (operation.harness === "opencode") {
+    if (!commandExists("opencode", env)) {
+      return undefined;
+    }
+    return {
+      profile: operation.profile,
+      harness: operation.harness,
+      command: "opencode",
+      note: `Start OpenCode, then invoke @${operation.profile} in the session.`
+    };
+  }
+
+  return undefined;
+}
+
+function commandExists(command, env) {
+  const pathValue = env.PATH ?? "";
+  if (!pathValue) {
+    return false;
+  }
+
+  const extensions = process.platform === "win32"
+    ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")
+    : [""];
+
+  return pathValue
+    .split(path.delimiter)
+    .filter(Boolean)
+    .some((directory) => extensions.some((extension) => existsSync(path.join(directory, `${command}${extension}`))));
+}
+
+function shellWord(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9._/@:-]+$/.test(text)) {
+    return text;
+  }
+  return `'${text.replaceAll("'", "'\\''")}'`;
+}
+
 function selectProfiles(profiles, selectors, all = false) {
   if (all || selectors.length === 0 || selectors.includes("*")) {
     return profiles;
@@ -268,11 +360,23 @@ async function writeManagedFile(target, content, options = {}) {
   await fs.writeFile(target, content);
 }
 
-function resolveScope(options = {}) {
+function resolveScope(options = {}, harnesses = []) {
   if (options.project && options.global) {
     throw new Error("Use either --global or --project, not both.");
   }
-  return options.global ? "global" : "project";
+  if (options.project && harnesses.includes("codex")) {
+    throw new Error("Codex profiles are loaded from $CODEX_HOME/<name>.config.toml and cannot be installed project-locally. Use --global or choose a different harness.");
+  }
+  if (options.global) {
+    return "global";
+  }
+  if (options.project) {
+    return "project";
+  }
+  if (harnesses.includes("codex")) {
+    return "global";
+  }
+  return "project";
 }
 
 function normalizeProfileSelectors(values) {

package/src/renderers.js

@@ -56,12 +56,7 @@ export function resolveTargetPath(profile, agent, options = {}) {
       : process.env.CODEX_HOME
         ? path.resolve(expandHome(process.env.CODEX_HOME, home))
         : path.join(home, ".codex");
-
-    if (scope === "project") {
-      return path.join(cwd, ".codex", "agents", `${profile.slug}.toml`);
-    }
-
-    return path.join(codexHome, "agents", `${profile.slug}.toml`);
+    return path.join(codexHome, `${profile.slug}.config.toml`);
   }
 
   if (normalized === "claude-code") {
@@ -170,9 +165,11 @@ function buildInstructionBody(profile, adapter, harness) {
     "",
     "## Installed Profile Context",
     "",
-    `- Canonical profile slug: \`${profile.slug}\``,
+    `- Installed identity: \`${profile.slug}\``,
+    `- Role/name: \`${profile.name}\``,
     `- Installed for: \`${harness}\``,
-    "- This profile is a reusable operational agent profile, not local machine setup.",
+    "- When asked who you are, what agent is running, or what role you are acting as, answer with this identity and role.",
+    "- This profile is a reusable operational agent profile, not a skill or local machine setup.",
     "- The runtime agent manages any profile-specific home directory and notes at task time."
   ];
 

package/src/source.js

@@ -4,14 +4,24 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { DEFAULT_SOURCE } from "./constants.js";
+import YAML from "yaml";
 import { parseFrontmatter } from "./frontmatter.js";
 
 const GITHUB_SHORTHAND = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const PROFILE_SUFFIXES = [
+  ".agent.yaml",
+  ".agent.yml",
+  ".agf.yaml",
+  ".agf.yml",
+  ".yaml",
+  ".yml",
+  ".agent.md",
+  ".md"
+];
 
 export function splitSourceSpec(spec) {
   if (!spec) {
-    return { source: DEFAULT_SOURCE, profile: undefined };
+    return { source: undefined, profile: undefined };
   }
 
   const atIndex = spec.lastIndexOf("@");
@@ -57,13 +67,17 @@ export function normalizeGithubUrl(source) {
   return undefined;
 }
 
-export async function materializeSource(sourceInput = DEFAULT_SOURCE, options = {}) {
+export async function materializeSource(sourceInput, options = {}) {
   const home = options.home ?? os.homedir();
-  const source = sourceInput || DEFAULT_SOURCE;
+  const source = sourceInput;
+
+  if (!source) {
+    throw new Error("Specify a source. Use a local path, owner/repo, or GitHub URL.");
+  }
 
   if (isLocalSource(source, home)) {
     const sourcePath = path.resolve(expandHome(source, home));
-    await assertTouchGrassLayout(sourcePath);
+    await assertAgentProfileLayout(sourcePath);
     return {
       kind: "local",
       source: sourcePath,
@@ -89,7 +103,7 @@ export async function materializeSource(sourceInput = DEFAULT_SOURCE, options =
     throw new Error(`Could not clone ${source}: ${detail}`);
   }
 
-  await assertTouchGrassLayout(cloneDir);
+  await assertAgentProfileLayout(cloneDir);
 
   return {
     kind: "git",
@@ -102,7 +116,7 @@ export async function materializeSource(sourceInput = DEFAULT_SOURCE, options =
   };
 }
 
-async function assertTouchGrassLayout(sourcePath) {
+async function assertAgentProfileLayout(sourcePath) {
   const profilesDir = path.join(sourcePath, "agents", "profiles");
   if (!existsSync(profilesDir)) {
     throw new Error(`No agents/profiles directory found in ${sourcePath}`);
@@ -116,25 +130,15 @@ export async function loadCatalog(sourcePath) {
   const profiles = [];
 
   for (const file of files) {
-    if (!file.isFile() || !file.name.endsWith(".md")) {
+    if (!file.isFile() || !isProfileFile(file.name)) {
       continue;
     }
 
     const filePath = path.join(profilesDir, file.name);
-    const raw = await fs.readFile(filePath, "utf8");
-    const parsed = parseFrontmatter(raw, filePath);
-    const slug = parsed.attributes.slug ?? path.basename(file.name, ".md");
-
+    const profile = await loadProfileFile(filePath, sourcePath);
     profiles.push({
-      slug,
-      name: parsed.attributes.name ?? slug,
-      summary: parsed.attributes.summary ?? "",
-      attributes: parsed.attributes,
-      body: parsed.body,
-      raw,
-      filePath,
-      relativePath: path.relative(sourcePath, filePath),
-      adapters: await loadAdapters(adapterRoot, slug, sourcePath)
+      ...profile,
+      adapters: await loadAdapters(adapterRoot, profile.slug, sourcePath)
     });
   }
 
@@ -154,13 +158,13 @@ async function loadAdapters(adapterRoot, slug, sourcePath) {
       continue;
     }
 
-    const adapterPath = path.join(adapterRoot, harnessDir.name, `${slug}.md`);
+    const adapterPath = await findProfileLikeFile(path.join(adapterRoot, harnessDir.name), slug);
     if (!existsSync(adapterPath)) {
       continue;
     }
 
     const raw = await fs.readFile(adapterPath, "utf8");
-    const parsed = parseFrontmatter(raw, adapterPath);
+    const parsed = await loadDefinitionFile(adapterPath, raw);
     adapters[harnessDir.name] = {
       harness: harnessDir.name,
       attributes: parsed.attributes,
@@ -174,6 +178,179 @@ async function loadAdapters(adapterRoot, slug, sourcePath) {
   return adapters;
 }
 
+async function loadProfileFile(filePath, sourcePath) {
+  const raw = await fs.readFile(filePath, "utf8");
+  const parsed = await loadDefinitionFile(filePath, raw);
+  const fallbackSlug = profileSlugFromFilename(path.basename(filePath));
+  const slug = parsed.attributes.slug ?? parsed.attributes.id ?? fallbackSlug;
+  const name = parsed.attributes.name ?? titleize(slug);
+  const summary = parsed.attributes.summary ?? parsed.attributes.description ?? "";
+
+  return {
+    slug,
+    name,
+    summary,
+    attributes: {
+      ...parsed.attributes,
+      slug,
+      name,
+      summary
+    },
+    body: parsed.body,
+    raw,
+    filePath,
+    relativePath: path.relative(sourcePath, filePath),
+    format: parsed.format
+  };
+}
+
+async function loadDefinitionFile(filePath, rawInput) {
+  const raw = rawInput ?? await fs.readFile(filePath, "utf8");
+  if (isMarkdownProfile(filePath)) {
+    const parsed = parseFrontmatter(raw, filePath);
+    return {
+      attributes: normalizeFlatAttributes(parsed.attributes),
+      body: parsed.body,
+      format: "markdown-frontmatter"
+    };
+  }
+
+  let document;
+  try {
+    document = YAML.parse(raw) ?? {};
+  } catch (error) {
+    throw new Error(`Could not parse YAML profile in ${filePath}: ${error.message}`);
+  }
+  if (!isObject(document)) {
+    throw new Error(`YAML profile in ${filePath} must be a mapping/object.`);
+  }
+
+  const normalized = normalizeYamlProfile(document, filePath);
+  return {
+    attributes: normalized.attributes,
+    body: normalized.body,
+    format: normalized.format
+  };
+}
+
+function normalizeYamlProfile(document, filePath) {
+  const metadata = isObject(document.metadata) ? document.metadata : {};
+  const executionPolicy = isObject(document.execution_policy) ? document.execution_policy : {};
+  const executionConfig = isObject(executionPolicy.config) ? executionPolicy.config : {};
+
+  const id = firstString(
+    document.slug,
+    document.id,
+    metadata.id,
+    profileSlugFromFilename(path.basename(filePath))
+  );
+  const name = firstString(document.name, metadata.name, titleize(id));
+  const description = firstString(document.summary, document.description, metadata.description, "");
+  const instructions = firstString(
+    document.instructions,
+    document.instruction,
+    document.prompt,
+    document.system_prompt,
+    executionConfig.instructions,
+    ""
+  );
+  const model = firstString(document.recommended_model, document.model, executionConfig.model, "");
+  const reasoningEffort = firstString(
+    document.recommended_reasoning_effort,
+    document.reasoning_effort,
+    document.model_reasoning_effort,
+    executionConfig.reasoning_effort,
+    ""
+  );
+  const recommendedModels = document.recommended_models ?? document.models ?? undefined;
+
+  const attributes = {
+    ...document,
+    slug: id,
+    id,
+    name,
+    summary: description,
+    description,
+    kind: document.kind ?? document.type ?? "operational-agent-profile"
+  };
+
+  if (model && !attributes.recommended_model) {
+    attributes.recommended_model = model;
+  }
+  if (reasoningEffort && !attributes.recommended_reasoning_effort) {
+    attributes.recommended_reasoning_effort = reasoningEffort;
+  }
+  if (recommendedModels && !attributes.recommended_models) {
+    attributes.recommended_models = recommendedModels;
+  }
+
+  return {
+    attributes,
+    body: renderYamlProfileBody(name, description, instructions),
+    format: isAgentFormat(document) ? "agent-format-yaml" : "yaml"
+  };
+}
+
+function normalizeFlatAttributes(attributes) {
+  return {
+    ...attributes,
+    summary: attributes.summary ?? attributes.description ?? ""
+  };
+}
+
+function renderYamlProfileBody(name, description, instructions) {
+  const body = instructions || description || "No instructions provided.";
+  return `# ${name}\n\n${body}`.trimEnd();
+}
+
+async function findProfileLikeFile(directory, slug) {
+  for (const suffix of PROFILE_SUFFIXES) {
+    const candidate = path.join(directory, `${slug}${suffix}`);
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return path.join(directory, `${slug}.md`);
+}
+
+function isProfileFile(filename) {
+  return PROFILE_SUFFIXES.some((suffix) => filename.endsWith(suffix));
+}
+
+function isMarkdownProfile(filePath) {
+  return filePath.endsWith(".md");
+}
+
+function profileSlugFromFilename(filename) {
+  const suffix = PROFILE_SUFFIXES.find((value) => filename.endsWith(value));
+  return suffix ? filename.slice(0, -suffix.length) : path.basename(filename, path.extname(filename));
+}
+
+function isAgentFormat(document) {
+  return isObject(document.metadata) && isObject(document.execution_policy);
+}
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+  return "";
+}
+
+function titleize(slug) {
+  return String(slug)
+    .split(/[-_]+/)
+    .filter(Boolean)
+    .map((part) => `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}`)
+    .join(" ");
+}
+
 export function resolvePackageRoot() {
   return path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 }