awesome-agents 0.1.1 → 0.1.5

package/AGENTS.md

@@ -7,10 +7,17 @@ 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:
+The canonical source format is repo-neutral:
 
-- `agents/profiles/*.md`: Markdown profile with YAML frontmatter.
-- `agents/adapters/<harness>/*.md`: optional harness-specific metadata and notes.
+- `agents/<slug>/agent.yaml`: preferred YAML profile definition.
+- `agents/<slug>/agent.agf.yaml`: Agent Format-style YAML profile definition.
+- `agents/<slug>/agent.md`: Markdown profile definition with YAML frontmatter.
+- `agents/<slug>/scripts/`: agent-owned scripts installed into the agent home.
+- `agents/<slug>/references/`: agent-owned references installed into the agent home.
+
+Never hard-code a particular source repository into runtime behavior, tests, or
+examples. Use neutral fixture/source names unless a test is explicitly about
+source resolution.
 
 ## Setup Commands
 
@@ -47,6 +54,8 @@ The canonical source format is the `touch-grass` layout:
 ## Safety
 
 - Never overwrite or delete unmanaged harness files by default.
+- Install agent-owned support files into `~/.agents/homes/<slug>/`, not into
+  harness configuration directories.
 - 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

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 This file is maintained by `npm run changelog` and `npm run release`. Release entries are generated from git commit history.
 
+## 0.1.5 - 2026-07-06
+
+Changes since `v0.1.4`.
+
+- No commits found for this release.
+
+## 0.1.4 - 2026-07-06
+
+Changes since `v0.1.3`.
+
+### Added
+
+- Add justfile for lint/test/release/publish workflows (7fe04ba)
+- Add agent detail page and visual treatment explorations (7d29557)
+- Add Claude Code plugin for browsing and installing agent profiles (5a11e6f)
+- Add awesome-agents.com marketing/directory site (9ce50cd)
+
+### Changed
+
+- Link leaderboard rows to per-agent pages (6f2c471)
+- Default install to every detected harness on PATH (b5af687)
+- Render Codex profile metadata as comments (59395cc)
+- Install agent-owned support files (3ede3ce)
+
+## 0.1.3 - 2026-07-05
+
+Initial tracked release.
+
+### Added
+
+- Add release automation (3ee72ed)
+- Add chief of staff profile install support (e683a72)
+
+### Fixed
+
+- Fix flaky color-sensitive assertions in CLI tests (5262811)
+- Fix agent profile install UX (961497c)
+- Fix npm bin metadata (085e6ee)
+
+### Changed
+
+- Polish CLI help and profile source support (d931ae9)
+- Split product notes by area (1d24611)
+- Scaffold awesome-agents CLI (e1ec6a4)
+
+## 0.1.2 - 2026-07-05
+
+### Fixed
+
+- Require an explicit source for `add`, `install`, and `use`; remove the hardcoded default source fallback.
+- Replace source-specific help and documentation examples with neutral `owner/repo` examples.
+- Parse repo-neutral YAML profile files in addition to Markdown frontmatter files.
+- Replace source-specific test fixtures with neutral profile-source fixtures.
+- Prefer `agents/<slug>/agent.yaml` source directories and install colocated
+  `scripts/` and `references/` into the agent home.
+
 ## 0.1.1 - 2026-07-05
 
 Initial tracked release.

package/README.md

@@ -5,18 +5,17 @@ It mirrors the useful parts of `npx skills`, but the unit is an operational
 agent profile instead of a skill.
 
 Supported sources are GitHub repos, Git URLs, or local checkouts that use the
-`touch-grass` layout. Profiles are read from `agents/profiles/*.md`, adapted for
-the selected harness, and installed into the right place for Codex, Claude Code,
-or OpenCode.
+agent-profile source layout. Profiles are read from YAML or Markdown files under
+`agents/<slug>/`, adapted for the selected harness, and installed into the
+right place for Codex, Claude Code, or OpenCode.
 
 ## Install And Run
 
 Use the CLI with `npx`:
 
 ```bash
-npx awesome-agents add pablof7z/touch-grass --agent ios-tester
-npx awesome-agents add pablof7z/touch-grass --agent chief-of-staff
-npx awesome-agents add pablof7z/touch-grass --agent ios-tester --harness opencode
+npx awesome-agents add owner/repo --agent triage-agent
+npx awesome-agents add owner/repo --agent triage-agent --harness opencode
 ```
 
 From this repo during development:
@@ -24,15 +23,15 @@ From this repo during development:
 ```bash
 npm install
 npm test
-node ./bin/awesome-agents.js add pablof7z/touch-grass --agent ios-tester --dry-run
+node ./bin/awesome-agents.js add ./test/fixtures/profile-source --agent triage-agent --dry-run
 ```
 
 ## Commands
 
 ```bash
-awesome-agents add [source] [options]
-awesome-agents install [source] [options]   # alias for add
-awesome-agents use <source@profile> [options]
+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]
@@ -41,27 +40,34 @@ awesome-agents init [name]
 
 Useful install options:
 
-- `--agent <slug>` to select an agent profile, for example `--agent ios-tester`
+- `--agent <slug>` to select an agent profile, for example `--agent triage-agent`
 - `--profile <slug>` or `--skill <slug>` as explicit profile aliases; `--skill`
   is command-shape compatibility and does not mean the artifact is a skill
-- `--harness codex|claude-code|opencode|*` to select target harnesses
+- `--harness codex|claude-code|opencode|*` to select target harnesses; without
+  it, the CLI installs to every harness whose CLI it finds on `PATH`
+  (falling back to Codex if none are found)
 - `--all` to install all profiles to all supported harnesses
 - `--dry-run` to preview writes
-- `--project` for project-level install, the default
+- `--project` for project-level install where supported; Codex profiles install globally
 - `--global` for user-level install
 - `--list` to inspect available source profiles without installing
 
+Human-readable output uses subtle ANSI color. Set `NO_COLOR=1` to disable color,
+or pass `--json` for machine-readable output. After an install, the CLI also
+prints run commands for target harness CLIs it finds on `PATH`, such as
+`codex --profile <profile>` or `claude --agent <profile>`.
+
 ## Harness Targets
 
 Project installs write to:
 
-- Codex: `.codex/agents/<profile>.toml`
+- Codex: not supported; Codex profiles load from user config
 - 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`
+- Codex: `$CODEX_HOME/<profile>.config.toml`, or `~/.codex/<profile>.config.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`
 
@@ -70,34 +76,47 @@ 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.
 
+Run Codex profiles with:
+
+```bash
+codex --profile <profile>
+```
+
+Codex expects a plain profile name. It does not accept a path passed to
+`--profile`.
+
 ## Source Format
 
 An agent-profile source should look like:
 
 ```text
 agents/
-  profiles/
-    ios-tester.md
-  adapters/
-    codex/
-      ios-tester.md
+  triage-agent/
+    agent.yaml
+  ops-agent/
+    agent.agf.yaml
+    scripts/
+      heartbeat.sh
+    references/
+      runbook.md
 ```
 
-Profile files are Markdown with YAML frontmatter. Adapters are optional and can
-provide harness-specific metadata such as model and reasoning effort.
+YAML profile files are preferred. The loader also accepts Markdown files with
+YAML frontmatter for compatibility with tools that use `.agent.md`-style
+profiles. Agent-owned `scripts/` and `references/` are installed into
+`~/.agents/homes/<slug>/scripts` and `~/.agents/homes/<slug>/references`.
 
 ## Examples
 
 ```bash
-npx awesome-agents add pablof7z/touch-grass --list
-npx awesome-agents add pablof7z/touch-grass --agent ios-tester
-npx awesome-agents add pablof7z/touch-grass --agent chief-of-staff
-npx awesome-agents add pablof7z/touch-grass --agent ios-tester --harness codex --global
-npx awesome-agents add pablof7z/touch-grass --all --dry-run
-npx awesome-agents use pablof7z/touch-grass --agent ios-ux-ui-critic --harness claude-code
+npx awesome-agents add owner/repo --list
+npx awesome-agents add owner/repo --agent triage-agent
+npx awesome-agents add owner/repo --agent triage-agent --harness codex --global
+npx awesome-agents add owner/repo --all --dry-run
+npx awesome-agents use owner/repo --agent triage-agent --harness claude-code
 npx awesome-agents list --json
-npx awesome-agents remove ios-tester --agent codex
-npx awesome-agents update ios-tester --agent codex --dry-run
+npx awesome-agents remove triage-agent --agent codex
+npx awesome-agents update triage-agent --agent codex --dry-run
 ```
 
 ## Release Workflow

package/docs/cli.md

@@ -12,18 +12,23 @@
 
 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.
+default to project scope where the selected harness supports project-local
+profiles. Codex is the exception: Codex `--profile` loads named config layers
+from `CODEX_HOME`, so Codex profile installs are user-level.
 
 ## 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`
+- Local path: `/path/to/agent-profiles`, `~/agent-profiles`, `.`
+- GitHub shorthand: `owner/repo`
+- GitHub URL: `https://github.com/owner/repo`
 
 For GitHub sources, the CLI clones a shallow temporary copy and reads
-`agents/profiles`.
+`agents/<slug>/agent.yaml` style definitions.
+
+There is no default source. `add`, `install`, and `use` require the caller to
+provide a source explicitly.
 
 ## Install Syntax
 
@@ -36,15 +41,14 @@ npx awesome-agents add owner/repo --agent <profile-slug>
 For example:
 
 ```bash
-npx awesome-agents add pablof7z/touch-grass --agent ios-tester
-npx awesome-agents add pablof7z/touch-grass --agent chief-of-staff
+npx awesome-agents add owner/repo --agent triage-agent
 ```
 
 `--agent` selects the reusable agent profile. `--harness` selects where the
 generated profile is installed:
 
 ```bash
-npx awesome-agents add pablof7z/touch-grass --agent ios-tester --harness opencode
+npx awesome-agents add owner/repo --agent triage-agent --harness opencode
 ```
 
 For backward compatibility, `--agent codex`, `--agent claude-code`, and
@@ -53,6 +57,14 @@ For backward compatibility, `--agent codex`, `--agent claude-code`, and
 The `--skill` flag is accepted only as a command-shape alias for `--profile`.
 Installed artifacts remain operational agent profiles.
 
+After install, human-readable output should show the CLI command to run each
+installed profile through any matching harness CLI found on `PATH`. Examples:
+
+```bash
+codex --profile triage-agent
+claude --agent triage-agent
+```
+
 ## Install Safety
 
 Generated files contain the marker `Generated by awesome-agents`. The CLI refuses

package/docs/product/command-model.md

@@ -21,7 +21,7 @@ Accepted direction:
 The CLI supports:
 
 - `--agent <slug>` as the preferred profile selector, matching user-facing
-  language such as `npx awesome-agents add owner/repo --agent ios-tester`.
+  language such as `npx awesome-agents add owner/repo --agent triage-agent`.
 - `--profile <slug>` to select profiles explicitly.
 - `--skill <slug>` as a compatibility alias, even though the artifact is a profile.
 - `--harness <codex|claude-code|opencode|*>` to select target harnesses.
@@ -34,9 +34,16 @@ The CLI supports:
 
 Accepted implementation decision:
 
-- Install scope defaults to project to match the `npx skills` mental model and avoid surprising user-global mutation.
-- Codex is the default harness when no `--harness` or legacy harness-valued
-  `--agent` is provided.
+- Install scope defaults to project where the target harness supports project-local profiles.
+- Codex is an exception because `codex --profile <name>` loads
+  `$CODEX_HOME/<name>.config.toml`. Codex profile installs should use that
+  user-level config-layer target.
+- When no `--harness` or legacy harness-valued `--agent` is provided, the CLI
+  installs to every supported harness whose CLI is detected on `PATH` (checks
+  for `codex`, `claude`, `opencode`). If none are detected, it falls back to
+  Codex only.
+- `--harness <harness>` (or a harness-valued `--agent`) narrows the install to
+  that single harness, overriding detection.
 - The CLI is noninteractive in the initial scaffold.
 - `--yes` is accepted for command-shape parity, but prompts are not currently required.
 
@@ -45,5 +52,16 @@ Accepted implementation decision:
 The CLI should be useful from automation:
 
 - Human-readable output should include clear target paths.
+- Human-readable install output should show how to run the installed profile
+  through harness CLIs detected on the user's machine.
 - `--json` should be available for scripts.
 - `--dry-run` should preview writes without touching target files or registries.
+
+## Profile Identity
+
+User correction:
+
+- Each installed profile should instruct the harness to identify itself by its
+  installed name and role. If the user asks the running agent "who are you?" or
+  asks for `triage-agent`, it should know it is the `triage-agent` profile or at
+  least that its role is Triage Agent.

package/docs/product/harness-targets.md

@@ -12,21 +12,28 @@ Initial harness targets:
 
 ## Codex
 
-Generated Codex custom agents install to:
+Generated Codex profiles install to:
 
-- Project: `.codex/agents/<profile>.toml`
-- Global: `$CODEX_HOME/agents/<profile>.toml`, or `~/.codex/agents/<profile>.toml`
+- Project: not supported; Codex profiles load from user config
+- Global: `$CODEX_HOME/<profile>.config.toml`, or `~/.codex/<profile>.config.toml`
+
+Run with:
+
+```bash
+codex --profile <profile>
+```
+
+Codex profiles are not project-local in the same way Claude Code and OpenCode
+agents are. `--profile` expects a plain name and layers the corresponding config
+file from `CODEX_HOME`.
 
 The generated TOML includes:
 
-- `name`
-- `description`
 - optional model settings
 - `developer_instructions`
 
-Open question:
-
-- Whether future versions should also generate Codex `--profile` config layers in addition to Codex custom agents.
+Profile name and summary are emitted as comments, not TOML keys, because Codex
+rejects unknown configuration fields under strict config parsing.
 
 ## Claude Code
 
@@ -48,4 +55,6 @@ OpenCode output is Markdown with frontmatter and a generated marker.
 
 ## Adapter Gaps
 
-Current `touch-grass` profiles have Codex adapters. Claude Code and OpenCode currently use generated defaults unless source repositories add native adapters for those harnesses.
+Some source repositories may provide Codex adapters first. Claude Code and
+OpenCode use generated defaults unless a source repository adds native adapters
+for those harnesses.

package/docs/product/open-questions.md

@@ -16,5 +16,6 @@ These are unresolved product questions for `awesome-agents`.
 
 ## Harness Support
 
-- Should future versions generate Codex `--profile` config layers in addition to Codex custom agents?
-- Should `touch-grass` add native Claude Code and OpenCode adapters instead of relying on generated defaults?
+- Should future versions also support Codex custom-agent files in addition to
+  Codex `--profile` config layers?
+- Should source repositories add native Claude Code and OpenCode adapters instead of relying on generated defaults?

package/docs/product/product-scope.md

@@ -7,7 +7,8 @@ These notes capture what `awesome-agents` is and why it exists.
 - 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`.
+- It should install profiles from any explicit source repository that follows
+  the `agents/<slug>/agent.yaml` source layout.
 - Initial harness targets are Codex, Claude Code, and OpenCode.
 - The package should be published after the scaffold works.
 
@@ -20,18 +21,27 @@ Product distinction:
 - `npx skills` installs reusable task workflows and instructions.
 - `awesome-agents` installs reusable operational agent identities.
 - A profile can define prompt, model preference, tool boundaries, notes, coordination style, and harness-specific configuration.
+- Installed profiles should preserve explicit self-identity. A running
+  profile should know its installed slug and role.
 
 The CLI should not pretend profiles are skills. It can mirror `npx skills` command shape where that helps user memory, but the artifact remains an agent profile.
 
-## First Source
-
-The first real source repository is `touch-grass`, which currently carries reusable operational agent profiles such as:
-
-- `ios-tester`
-- `ios-ux-ui-critic`
-- `chief-of-staff`
-
-`awesome-agents` should install those profiles without requiring the user to copy profile files manually.
-
-The `chief-of-staff` profile is an explicit category-boundary example: it is an
-operational agent identity, not a skill.
+## Source Independence
+
+`awesome-agents` is independent of any particular profile repository. It should
+not know about or default to one source. Users must name the local path, GitHub
+shorthand, or Git URL they want to install from.
+
+Product correction:
+
+- Do not intertwine source-repository concepts into the `awesome-agents`
+  codebase.
+- Source repositories provide profile artifacts; `awesome-agents` understands
+  the artifact shape and target harnesses.
+- Examples and tests should use neutral source names unless they are testing
+  source resolution itself.
+- Source repositories should use one agent definition format per agent directory:
+  `agents/<slug>/agent.yaml` plus colocated support material.
+- `awesome-agents` installs that local support material into
+  `~/.agents/homes/<slug>/` and transcribes the agent definition to the target
+  harness.

package/docs/product/profile-source-format.md

@@ -4,54 +4,59 @@ These notes capture how profile source repositories are organized.
 
 ## Canonical Layout
 
-The initial source format follows the `touch-grass` layout:
+The source format is intentionally repo-neutral:
 
 ```text
 agents/
-  profiles/
-    <profile>.md
-  adapters/
-    <harness>/
-      <profile>.md
+  <profile>/
+    agent.yaml
+    scripts/
+    references/
 ```
 
 Canonical profiles live at:
 
 ```text
-agents/profiles/*.md
+agents/<profile>/{agent.yaml,agent.yml,agent.agf.yaml,agent.agf.yml,agent.md}
 ```
 
-Harness adapters live at:
+Optional agent-owned support material lives at:
 
 ```text
-agents/adapters/<harness>/*.md
+agents/<profile>/scripts/*
+agents/<profile>/references/*
 ```
 
 ## Profile Files
 
-Profile files are Markdown with YAML frontmatter.
+YAML profile files are preferred. The loader should support a pragmatic subset
+of emerging YAML agent-definition shapes:
 
-The CLI should preserve canonical profile content and generate harness-specific install files. A profile is reusable product content, not local machine setup.
+- simple profile YAML with `id`, `name`, `description`, `model`, and
+  `instructions`;
+- Agent Format-style YAML with `metadata` and `execution_policy.config`;
+- Markdown files with YAML frontmatter for compatibility with `.agent.md`
+  ecosystems.
 
-Current `touch-grass` profiles include:
+The CLI should preserve canonical profile content and generate harness-specific install files. A profile is reusable product content, not local machine setup.
 
-- `chief-of-staff`
-- `ios-tester`
-- `ios-ux-ui-critic`
+Agent-owned scripts and references should be installed into
+`~/.agents/homes/<profile>/scripts` and
+`~/.agents/homes/<profile>/references`.
 
-The `chief-of-staff` source files are intentionally under `agents/`, not
-`skills/`, because the source format models agent profiles separately from
-loadable skills.
+Profile source files are intentionally under `agents/`, not `skills/`, because
+the source format models agent profiles separately from loadable skills.
 
 ## Source Resolution
 
 The CLI should support:
 
-- Local paths such as `/Users/customer/touch-grass`.
-- GitHub shorthand such as `pablof7z/touch-grass`.
+- Local paths such as `/path/to/agent-profiles`.
+- GitHub shorthand such as `owner/repo`.
 - GitHub URLs.
 
-The first source repository is `touch-grass`, but the format should not be hard-coded only to that repository.
+The package must not hard-code any source repository. `add`, `install`, and
+`use` require an explicit source from the caller.
 
 ## Registry Or Search
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "awesome-agents",
-  "version": "0.1.1",
+  "version": "0.1.5",
   "description": "Install reusable agent profiles into Codex, Claude Code, and OpenCode.",
   "type": "module",
   "bin": {