awesome-agents 0.1.0

package/AGENTS.md

@@ -0,0 +1,60 @@
+# AGENTS.md
+
+## Project Overview
+
+`awesome-agents` is a Node.js CLI package for installing reusable operational
+agent profiles into agent harnesses. It intentionally mirrors the command shape
+of `npx skills`, but installs profile artifacts for Codex, Claude Code, and
+OpenCode.
+
+The canonical source format is the `touch-grass` layout:
+
+- `agents/profiles/*.md`: Markdown profile with YAML frontmatter.
+- `agents/adapters/<harness>/*.md`: optional harness-specific metadata and notes.
+
+## Setup Commands
+
+- Install dependencies: `npm install`
+- Run tests: `npm test`
+- Check syntax: `npm run lint`
+- Try the CLI locally: `node ./bin/awesome-agents.js --help`
+
+## Development Workflow
+
+- Keep runtime code in `src/` and the executable shim in `bin/`.
+- Use `node --test` for tests under `test/`.
+- Use `--dry-run` in examples that would otherwise write to real user agent
+  directories.
+- Do not publish the npm package from this repository unless explicitly asked.
+
+## Testing Instructions
+
+- Run the full suite with `npm test`.
+- Add or update tests when changing command behavior, path resolution,
+  frontmatter parsing, renderer output, registry writes, or safety checks.
+- Tests should use temporary HOME directories and fixtures, not the user's real
+  `~/.codex`, `~/.claude`, or `~/.config/opencode` directories.
+
+## Code Style
+
+- Use ESM modules.
+- Prefer Node standard library APIs unless a focused dependency is already in
+  `package.json`.
+- Keep generated files marked with `Generated by awesome-agents` so remove and
+  overwrite safety checks remain reliable.
+- Keep command output stable enough for humans and use `--json` for scripts.
+
+## Safety
+
+- Never overwrite or delete unmanaged harness files by default.
+- Keep install behavior deterministic and noninteractive. `--yes` exists for
+  parity with `npx skills`, but the CLI should not require prompts to complete.
+- Do not mutate harness configuration beyond writing the selected generated
+  profile files and the `awesome-agents` registry.
+
+## Pull Request Guidelines
+
+- Keep changes scoped to one command, renderer, or source-format behavior at a
+  time when practical.
+- Run `npm run lint` and `npm test` before handing off changes.
+- Document user-visible CLI behavior in `README.md` when it changes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pablo Fernandez
+
+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,96 @@
+# awesome-agents
+
+`awesome-agents` is an `npx`-compatible installer for reusable agent profiles.
+It mirrors the useful parts of `npx skills`, but the unit is an operational
+agent profile instead of a skill.
+
+The first supported source is `touch-grass`: local at `/Users/customer/touch-grass`
+or remote as `pablof7z/touch-grass`. Profiles are read from
+`agents/profiles/*.md`, adapted for the selected harness, and installed into the
+right place for Codex, Claude Code, or OpenCode.
+
+## Install And Run
+
+From this repo:
+
+```bash
+npm install
+npm test
+node ./bin/awesome-agents.js add /Users/customer/touch-grass --agent codex --profile ios-tester --dry-run
+```
+
+Once published, the intended entrypoint is:
+
+```bash
+npx awesome-agents add pablof7z/touch-grass --agent codex --profile ios-tester
+```
+
+## Commands
+
+```bash
+awesome-agents add [source] [options]
+awesome-agents install [source] [options]   # alias for add
+awesome-agents use <source@profile> [options]
+awesome-agents list [options]
+awesome-agents remove <profile...> [options]
+awesome-agents update [profile...] [options]
+awesome-agents init [name]
+```
+
+Useful install options:
+
+- `--agent codex|claude-code|opencode|*`
+- `--profile <slug>` or `--profile '*'`
+- `--all` to install all profiles to all supported harnesses
+- `--dry-run` to preview writes
+- `--project` for project-level install, the default
+- `--global` for user-level install
+- `--list` to inspect available source profiles without installing
+
+## Harness Targets
+
+Project installs write to:
+
+- Codex: `.codex/agents/<profile>.toml`
+- Claude Code: `.claude/agents/<profile>.md`
+- OpenCode: `.opencode/agents/<profile>.md`
+
+Global installs write to:
+
+- Codex: `$CODEX_HOME/agents/<profile>.toml`, or `~/.codex/agents/<profile>.toml`
+- Claude Code: `$CLAUDE_HOME/agents/<profile>.md`, or `~/.claude/agents/<profile>.md`
+- OpenCode: `$OPENCODE_CONFIG_DIR/agents/<profile>.md`, or `~/.config/opencode/agents/<profile>.md`
+
+The CLI keeps its own registry at `.awesome-agents/installed.json` for project
+installs or `~/.awesome-agents/installed.json` for global installs. `list`,
+`remove`, and `update` use this registry and refuse to overwrite or delete files
+that do not contain the generated marker unless `--force` is passed.
+
+## Source Format
+
+An agent-profile source should look like:
+
+```text
+agents/
+  profiles/
+    ios-tester.md
+  adapters/
+    codex/
+      ios-tester.md
+```
+
+Profile files are Markdown with YAML frontmatter. Adapters are optional and can
+provide harness-specific metadata such as model and reasoning effort.
+
+## Examples
+
+```bash
+awesome-agents add /Users/customer/touch-grass --list
+awesome-agents add /Users/customer/touch-grass --agent codex --profile ios-tester
+awesome-agents add /Users/customer/touch-grass --agent codex --profile ios-tester --global
+awesome-agents add pablof7z/touch-grass --all --dry-run
+awesome-agents use pablof7z/touch-grass@ios-ux-ui-critic --agent claude-code
+awesome-agents list --json
+awesome-agents remove ios-tester --agent codex
+awesome-agents update ios-tester --agent codex --dry-run
+```

package/bin/awesome-agents.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { run } from "../src/cli.js";
+
+run(process.argv).catch((error) => {
+  const message = error && error.message ? error.message : String(error);
+  console.error(`ERROR: ${message}`);
+  process.exitCode = 1;
+});

package/docs/cli.md

@@ -0,0 +1,34 @@
+# CLI Design
+
+`awesome-agents` uses `npx skills` as the command-shape reference:
+
+- `add` installs a source package.
+- `install` is an alias for `add`.
+- `use` renders a single profile without installing.
+- `list` / `ls` shows installed profiles.
+- `remove` / `rm` removes installed profiles.
+- `update` / `upgrade` reinstalls from the recorded source.
+- `init` creates a profile source skeleton.
+
+The CLI is noninteractive for the initial scaffold. Options such as `--yes` are
+accepted for parity, but command behavior should be fully scriptable. Installs
+default to project scope; pass `--global` for user-level installs.
+
+## Source Resolution
+
+Supported source values:
+
+- Local path: `/Users/customer/touch-grass`, `~/touch-grass`, `.`
+- GitHub shorthand: `pablof7z/touch-grass`
+- GitHub URL: `https://github.com/pablof7z/touch-grass`
+
+For GitHub sources, the CLI clones a shallow temporary copy and reads
+`agents/profiles`.
+
+## Install Safety
+
+Generated files contain the marker `Generated by awesome-agents`. The CLI refuses
+to overwrite or delete unmarked target files unless `--force` is passed.
+
+The registry records only what this CLI installed. It is not intended to discover
+or manage hand-written harness profiles.

package/docs/product/README.md

@@ -0,0 +1,12 @@
+# Product Notes
+
+This folder captures product thinking for `awesome-agents`.
+
+Keep these notes grounded in explicit user requests and accepted implementation
+direction. Do not turn incidental implementation choices into product strategy
+unless the user confirms them.
+
+## Files
+
+- `awesome-agents-flow-notes.md`: living notes about command shape, source
+  format, harness targets, and open questions.

package/docs/product/awesome-agents-flow-notes.md

@@ -0,0 +1,45 @@
+# Awesome Agents Flow Notes
+
+These are factual notes from the implementation request and current scaffold.
+
+## Core Direction
+
+- The package is named `awesome-agents`.
+- It should be installable with `npx`.
+- Its command structure should mirror `npx skills`, but for agent profiles.
+- It should install profiles from `touch-grass`, both local
+  `/Users/customer/touch-grass` and GitHub `pablof7z/touch-grass`.
+- Initial harness targets are Codex, Claude Code, and OpenCode.
+- The package should be published after the scaffold works.
+
+## Source Model
+
+- Canonical profiles live at `agents/profiles/*.md`.
+- Harness adapters live at `agents/adapters/<harness>/*.md`.
+- Current touch-grass profiles include `ios-tester` and `ios-ux-ui-critic`.
+- The CLI should preserve canonical profile content and generate harness-specific
+  install files.
+
+## Command Model
+
+- `add` is the primary install command because `npx skills` uses `add`.
+- `install` is an alias because the user explicitly requested an install command.
+- `use` renders one profile without installing it.
+- `list`, `remove`, and `update` operate from an `awesome-agents` registry so
+  the CLI manages only its own generated files.
+- `init` creates a starter profile source layout.
+- Install scope defaults to project to match the `npx skills` mental model.
+
+## Safety Constraints
+
+- Default behavior should not overwrite or delete unmanaged harness files.
+- `--dry-run` should be available for install, remove, update, and init flows.
+- Tests should exercise fake homes and fixture sources instead of writing to real
+  user harness directories.
+
+## Open Questions
+
+- Whether future versions should also generate Codex `--profile` config layers in addition to Codex custom agents.
+- Whether touch-grass should add native Claude Code and OpenCode adapters instead
+  of relying on generated defaults.
+- Whether future versions should include interactive prompts like `npx skills`.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "awesome-agents",
+  "version": "0.1.0",
+  "description": "Install reusable agent profiles into Codex, Claude Code, and OpenCode.",
+  "type": "module",
+  "bin": {
+    "awesome-agents": "bin/awesome-agents.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "docs",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "scripts": {
+    "lint": "node --check bin/awesome-agents.js && node --check src/*.js && node --check test/*.test.js",
+    "test": "node --test"
+  },
+  "keywords": [
+    "agents",
+    "agent-profiles",
+    "codex",
+    "claude-code",
+    "opencode",
+    "cli"
+  ],
+  "author": "Pablo Fernandez",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pablof7z/awesome-agents.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "yaml": "^2.9.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,208 @@
+import { Command } from "commander";
+import { PACKAGE_NAME, PACKAGE_VERSION, SUPPORTED_AGENTS } from "./constants.js";
+import {
+  initProfile,
+  installFromSource,
+  listAvailable,
+  listInstalled,
+  removeInstalled,
+  updateInstalled,
+  useFromSource
+} from "./installer.js";
+
+export async function run(argv = process.argv) {
+  const program = new Command();
+  program
+    .name(PACKAGE_NAME)
+    .description("Install reusable agent profiles into Codex, Claude Code, and OpenCode.")
+    .version(PACKAGE_VERSION, "-v, --version")
+    .helpOption("-h, --help", "Show this help message")
+    .showHelpAfterError();
+
+  addInstallCommand(program, "add");
+  addInstallCommand(program, "install");
+
+  program
+    .command("use")
+    .argument("[source]", "Source plus profile, for example pablof7z/touch-grass@ios-tester")
+    .description("Print one rendered agent profile without installing it")
+    .option("-s, --profile <profile>", "Profile slug to use")
+    .option("--skill <profile>", "Compatibility alias for --profile")
+    .option("-a, --agent <agent>", `Target agent harness (${SUPPORTED_AGENTS.join(", ")})`)
+    .option("--json", "Output JSON")
+    .option("--home <dir>", "Override HOME for path expansion")
+    .action(async (source = undefined, options) => {
+      const result = await useFromSource(source, options);
+      if (options.json) {
+        printJson(result);
+      } else {
+        process.stdout.write(result.content);
+      }
+    });
+
+  program
+    .command("list")
+    .alias("ls")
+    .description("List installed agent profiles")
+    .option("-g, --global", "List global installs")
+    .option("-p, --project", "List project installs")
+    .option("-a, --agent <agents...>", "Filter by agent harness")
+    .option("--json", "Output JSON")
+    .option("--home <dir>", "Override HOME for path expansion")
+    .action(async (options) => {
+      const result = await listInstalled(options);
+      if (options.json) {
+        printJson(result);
+      } else {
+        printInstalled(result);
+      }
+    });
+
+  program
+    .command("remove")
+    .alias("rm")
+    .argument("[profiles...]", "Installed profile slugs to remove")
+    .description("Remove installed agent profiles")
+    .option("-g, --global", "Remove global installs")
+    .option("-p, --project", "Remove project installs")
+    .option("-a, --agent <agents...>", "Filter by agent harness")
+    .option("-y, --yes", "Accepted for npx skills parity; prompts are not used")
+    .option("--all", "Remove all matching installed profiles")
+    .option("--dry-run", "Print planned removals without deleting files")
+    .option("--force", "Allow removing files without the generated marker")
+    .option("--json", "Output JSON")
+    .option("--home <dir>", "Override HOME for path expansion")
+    .action(async (profiles, options) => {
+      const result = await removeInstalled(profiles, options);
+      if (options.json) {
+        printJson(result);
+      } else {
+        printOperations(result.operations, result.registryPath);
+      }
+    });
+
+  program
+    .command("update")
+    .alias("upgrade")
+    .argument("[profiles...]", "Installed profile slugs to update")
+    .description("Update installed agent profiles from their original source")
+    .option("-g, --global", "Update global installs")
+    .option("-p, --project", "Update project installs")
+    .option("-a, --agent <agents...>", "Filter by agent harness")
+    .option("-y, --yes", "Accepted for npx skills parity; prompts are not used")
+    .option("--dry-run", "Print planned updates without writing files")
+    .option("--json", "Output JSON")
+    .option("--home <dir>", "Override HOME for path expansion")
+    .action(async (profiles, options) => {
+      const result = await updateInstalled(profiles, options);
+      if (options.json) {
+        printJson(result);
+      } else {
+        printOperations(result.operations, result.registryPath);
+      }
+    });
+
+  program
+    .command("init")
+    .argument("[name]", "New profile slug")
+    .description("Initialize a profile source layout in the current directory")
+    .option("--dry-run", "Print planned files without writing")
+    .option("--force", "Overwrite existing initialized files")
+    .option("--json", "Output JSON")
+    .action(async (name, options) => {
+      const result = await initProfile(name, { ...options, cwd: process.cwd() });
+      if (options.json) {
+        printJson(result);
+      } else {
+        console.log(`${result.action}:`);
+        for (const file of result.files) {
+          console.log(`  ${file}`);
+        }
+      }
+    });
+
+  if (argv.length <= 2) {
+    program.help();
+    return;
+  }
+
+  await program.parseAsync(argv);
+}
+
+function addInstallCommand(program, commandName) {
+  program
+    .command(commandName)
+    .argument("[source]", "Local path, GitHub owner/repo, or GitHub URL")
+    .description(commandName === "install" ? "Alias for add" : "Install agent profiles from a source")
+    .option("-g, --global", "Install globally")
+    .option("-p, --project", "Install into the current project (default)")
+    .option("-a, --agent <agents...>", `Target agent harnesses (${SUPPORTED_AGENTS.join(", ")}, or *)`)
+    .option("-s, --profile <profiles...>", "Profile slugs to install (or *)")
+    .option("--skill <profiles...>", "Compatibility alias for --profile")
+    .option("-l, --list", "List available profiles in the source without installing")
+    .option("-y, --yes", "Accepted for npx skills parity; prompts are not used")
+    .option("--all", "Install all profiles to all supported agents")
+    .option("--dry-run", "Print planned installs without writing files")
+    .option("--force", "Allow overwriting files without the generated marker")
+    .option("--json", "Output JSON")
+    .option("--home <dir>", "Override HOME for path expansion")
+    .action(async (source = undefined, options) => {
+      if (options.list) {
+        const profiles = await listAvailable(source, options);
+        if (options.json) {
+          printJson({ profiles });
+        } else {
+          printAvailable(profiles);
+        }
+        return;
+      }
+
+      const result = await installFromSource(source, options);
+      if (options.json) {
+        printJson(result);
+      } else {
+        printOperations(result.operations, result.registryPath);
+      }
+    });
+}
+
+function printAvailable(profiles) {
+  if (profiles.length === 0) {
+    console.log("No profiles found.");
+    return;
+  }
+  for (const profile of profiles) {
+    console.log(`${profile.slug}  ${profile.summary || profile.name}`);
+  }
+}
+
+function printInstalled(result) {
+  if (result.installs.length === 0) {
+    console.log(`No ${result.scope} profiles installed.`);
+    return;
+  }
+
+  for (const install of result.installs) {
+    const missing = install.exists ? "" : " (missing target)";
+    console.log(`${install.profile}  ${install.harness}  ${install.target}${missing}`);
+  }
+  console.log(`Registry: ${result.registryPath}`);
+}
+
+function printOperations(operations, registryPath) {
+  if (operations.length === 0) {
+    console.log("No matching profiles.");
+    return;
+  }
+
+  for (const operation of operations) {
+    console.log(`${operation.action}: ${operation.profile} -> ${operation.harness} at ${operation.target}`);
+  }
+  if (registryPath) {
+    console.log(`Registry: ${registryPath}`);
+  }
+}
+
+function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}

package/src/constants.js

@@ -0,0 +1,19 @@
+export const PACKAGE_NAME = "awesome-agents";
+export const PACKAGE_VERSION = "0.1.0";
+export const DEFAULT_SOURCE = "pablof7z/touch-grass";
+export const DEFAULT_AGENT = "codex";
+export const SUPPORTED_AGENTS = ["codex", "claude-code", "opencode"];
+export const REGISTRY_DIRNAME = ".awesome-agents";
+export const REGISTRY_FILENAME = "installed.json";
+export const GENERATED_MARKER = "Generated by awesome-agents";
+
+export const AGENT_ALIASES = new Map([
+  ["codex", "codex"],
+  ["openai", "codex"],
+  ["openai-codex", "codex"],
+  ["claude", "claude-code"],
+  ["claude-code", "claude-code"],
+  ["claudecode", "claude-code"],
+  ["opencode", "opencode"],
+  ["open-code", "opencode"]
+]);

package/src/frontmatter.js

@@ -0,0 +1,33 @@
+import YAML from "yaml";
+
+export function parseFrontmatter(text, filePath = "document") {
+  if (!text.startsWith("---")) {
+    return { attributes: {}, body: text };
+  }
+
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?/);
+  if (!match) {
+    throw new Error(`Invalid YAML frontmatter in ${filePath}`);
+  }
+
+  let attributes;
+  try {
+    attributes = YAML.parse(match[1]) ?? {};
+  } catch (error) {
+    throw new Error(`Could not parse YAML frontmatter in ${filePath}: ${error.message}`);
+  }
+
+  return {
+    attributes,
+    body: text.slice(match[0].length).trimStart()
+  };
+}
+
+export function stringifyFrontmatter(attributes, body) {
+  const yaml = YAML.stringify(attributes, {
+    collectionStyle: "block",
+    lineWidth: 0
+  }).trimEnd();
+
+  return `---\n${yaml}\n---\n\n${body.trimStart()}`;
+}