awesome-agents 0.1.0 → 0.1.3

package/AGENTS.md

@@ -7,10 +7,16 @@ 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/profiles/*.agent.yaml`: preferred YAML profile definitions.
+- `agents/profiles/*.agf.yaml`: Agent Format-style YAML profile definitions.
+- `agents/profiles/*.md`: Markdown profile definitions with YAML frontmatter.
+- `agents/adapters/<harness>/*`: optional harness-specific metadata and notes.
+
+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
 

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+This file is maintained by `npm run changelog` and `npm run release`. Release entries are generated from git commit history.
+
+## 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.
+
+## 0.1.1 - 2026-07-05
+
+Initial tracked release.
+
+### Added
+
+- Add release and changelog automation.
+- Add chief of staff profile install support (e683a72)
+
+### Fixed
+
+- Fix npm bin metadata (085e6ee)
+
+### Changed
+
+- Split product notes by area (1d24611)
+- Scaffold awesome-agents CLI (e1ec6a4)

package/README.md

@@ -4,33 +4,34 @@
 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
+Supported sources are GitHub repos, Git URLs, or local checkouts that use the
+agent-profile source layout. Profiles are read from YAML or Markdown files under
+`agents/profiles/`, adapted for the selected harness, and installed into the
 right place for Codex, Claude Code, or OpenCode.
 
 ## Install And Run
 
-From this repo:
+Use the CLI with `npx`:
 
 ```bash
-npm install
-npm test
-node ./bin/awesome-agents.js add /Users/customer/touch-grass --agent codex --profile ios-tester --dry-run
+npx awesome-agents add owner/repo --agent triage-agent
+npx awesome-agents add owner/repo --agent triage-agent --harness opencode
 ```
 
-Once published, the intended entrypoint is:
+From this repo during development:
 
 ```bash
-npx awesome-agents add pablof7z/touch-grass --agent codex --profile ios-tester
+npm install
+npm test
+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]
@@ -39,25 +40,32 @@ awesome-agents init [name]
 
 Useful install options:
 
-- `--agent codex|claude-code|opencode|*`
-- `--profile <slug>` or `--profile '*'`
+- `--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
 - `--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`
 
@@ -66,6 +74,15 @@ 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:
@@ -73,24 +90,44 @@ An agent-profile source should look like:
 ```text
 agents/
   profiles/
-    ios-tester.md
+    triage-agent.agent.yaml
+    ops-agent.agf.yaml
+    legacy-agent.md
   adapters/
     codex/
-      ios-tester.md
+      optional-agent.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. Adapters are optional and can provide harness-specific metadata, but a
+profile should stand on its own without requiring an adapter.
 
 ## 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
+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 triage-agent --agent codex
+npx awesome-agents update triage-agent --agent codex --dry-run
+```
+
+## Release Workflow
+
+Changes are tracked in `CHANGELOG.md` from git commit history.
+
+```bash
+npm run changelog
+npm run release:dry-run -- patch
+npm run release -- patch
+npm run release -- minor --push
 ```
+
+`npm run release` bumps `package.json`, `package-lock.json`, and
+`src/constants.js`, refreshes `CHANGELOG.md`, runs lint/tests, commits
+`Release vX.Y.Z`, and creates an annotated tag. Passing `--push` pushes the
+branch and tag. It does not publish to npm.

package/docs/cli.md

@@ -12,19 +12,59 @@
 
 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`.
 
+There is no default source. `add`, `install`, and `use` require the caller to
+provide a source explicitly.
+
+## Install Syntax
+
+The preferred remote install form is:
+
+```bash
+npx awesome-agents add owner/repo --agent <profile-slug>
+```
+
+For example:
+
+```bash
+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 owner/repo --agent triage-agent --harness opencode
+```
+
+For backward compatibility, `--agent codex`, `--agent claude-code`, and
+`--agent opencode` are still accepted as harness selectors.
+
+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/README.md

@@ -8,5 +8,16 @@ unless the user confirms them.
 
 ## Files
 
-- `awesome-agents-flow-notes.md`: living notes about command shape, source
-  format, harness targets, and open questions.
+- `product-scope.md`: What `awesome-agents` is for and how it differs from skills.
+- `command-model.md`: Command shape, `npx skills` parity, defaults, and scriptability.
+- `profile-source-format.md`: Source repositories, canonical profiles, adapters, and install sources.
+- `harness-targets.md`: Codex, Claude Code, and OpenCode rendering/target behavior.
+- `safety-and-publishing.md`: Install safety, registry behavior, verification, and npm/GitHub publish state.
+- `open-questions.md`: Unresolved product questions.
+
+## Note-Taking Rules
+
+- Split notes by product area instead of appending everything to one flow file.
+- Preserve explicit user direction and accepted implementation decisions.
+- Keep implementation details separate from product intent when possible.
+- Mark inferred future direction as an open question or proposal.

package/docs/product/command-model.md

@@ -0,0 +1,63 @@
+# Command Model
+
+These notes capture the intended command shape.
+
+## `npx skills` Parity
+
+The user requested "the exact same command structure as `npx skills`" for installing agent profiles.
+
+Accepted direction:
+
+- `add` is the primary install command because `npx skills` uses `add`.
+- `install` is also supported because the user explicitly requested an install command.
+- `use` renders one profile without installing it.
+- `list` and `ls` show installed profiles.
+- `remove` and `rm` remove installed generated profiles.
+- `update` and `upgrade` reinstall from the recorded source.
+- `init` creates a starter profile source layout.
+
+## Selectors And Compatibility
+
+The CLI supports:
+
+- `--agent <slug>` as the preferred profile selector, matching user-facing
+  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.
+- `--agent <codex|claude-code|opencode|*>` remains accepted as a legacy harness
+  selector when the value is a known harness or harness alias.
+- `--all` to install every profile.
+- `--list` to inspect source profiles before installing.
+
+## Defaults
+
+Accepted implementation decision:
+
+- 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.
+- Codex is the default harness when no `--harness` or legacy harness-valued
+  `--agent` is provided.
+- The CLI is noninteractive in the initial scaffold.
+- `--yes` is accepted for command-shape parity, but prompts are not currently required.
+
+## Scriptability
+
+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

@@ -0,0 +1,59 @@
+# Harness Targets
+
+These notes capture how `awesome-agents` targets agent harnesses.
+
+## Initial Harnesses
+
+Initial harness targets:
+
+- Codex
+- Claude Code
+- OpenCode
+
+## Codex
+
+Generated Codex profiles install to:
+
+- 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`
+
+## Claude Code
+
+Generated Claude Code subagents install to:
+
+- Project: `.claude/agents/<profile>.md`
+- Global: `$CLAUDE_HOME/agents/<profile>.md`, or `~/.claude/agents/<profile>.md`
+
+Claude Code output is Markdown with frontmatter and a generated marker.
+
+## OpenCode
+
+Generated OpenCode agents install to:
+
+- Project: `.opencode/agents/<profile>.md`
+- Global: `$OPENCODE_CONFIG_DIR/agents/<profile>.md`, or `~/.config/opencode/agents/<profile>.md`
+
+OpenCode output is Markdown with frontmatter and a generated marker.
+
+## Adapter Gaps
+
+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

@@ -0,0 +1,21 @@
+# Open Questions
+
+These are unresolved product questions for `awesome-agents`.
+
+## Command Experience
+
+- Should future versions include interactive prompts like `npx skills`?
+- Should there be a `find` or search command?
+- Should `--skill` remain permanently as a compatibility alias or eventually become a warning?
+
+## Source And Versioning
+
+- Should a neutral profile schema be formalized independently of Markdown frontmatter?
+- Should remote installs record commit pins or lockfiles for reproducible updates?
+- Should there eventually be a registry or curated index of profile sources?
+
+## Harness Support
+
+- 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

@@ -0,0 +1,42 @@
+# Product Scope
+
+These notes capture what `awesome-agents` is and why it exists.
+
+## 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 any explicit source repository that follows
+  the `agents/profiles` source layout.
+- Initial harness targets are Codex, Claude Code, and OpenCode.
+- The package should be published after the scaffold works.
+
+## Product Boundary
+
+The user asked whether there is something like `npx skills` for agent profiles. The answer was effectively no: skills and profiles are adjacent but different layers.
+
+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.
+
+## 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.

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

@@ -0,0 +1,64 @@
+# Profile Source Format
+
+These notes capture how profile source repositories are organized.
+
+## Canonical Layout
+
+The source format is intentionally repo-neutral:
+
+```text
+agents/
+  profiles/
+    <profile>.agent.yaml
+    <profile>.agf.yaml
+    <profile>.md
+  adapters/
+    <harness>/
+      <profile>.md
+```
+
+Canonical profiles live at:
+
+```text
+agents/profiles/*.{agent.yaml,agent.yml,agf.yaml,agf.yml,yaml,yml,agent.md,md}
+```
+
+Optional harness adapters live at:
+
+```text
+agents/adapters/<harness>/*
+```
+
+## Profile Files
+
+YAML profile files are preferred. The loader should support a pragmatic subset
+of emerging YAML agent-definition shapes:
+
+- 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.
+
+The CLI should preserve canonical profile content and generate harness-specific install files. A profile is reusable product content, not local machine setup.
+
+Adapters are optional. A profile should be useful without a harness adapter; an
+adapter is only an override for harness-specific metadata or instructions.
+
+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 `/path/to/agent-profiles`.
+- GitHub shorthand such as `owner/repo`.
+- GitHub URLs.
+
+The package must not hard-code any source repository. `add`, `install`, and
+`use` require an explicit source from the caller.
+
+## Registry Or Search
+
+No registry or search command exists yet. This is an open product area, not part of the initial scaffold.

package/docs/product/safety-and-publishing.md

@@ -0,0 +1,64 @@
+# Safety And Publishing
+
+These notes capture install safety, verification, and publish state.
+
+## Install Safety
+
+Default behavior should not overwrite or delete unmanaged harness files.
+
+Accepted safety behavior:
+
+- Generated files contain a `Generated by awesome-agents` marker.
+- The CLI refuses to overwrite unmanaged target files unless `--force` is passed.
+- The CLI refuses to remove unmanaged target files unless `--force` is passed.
+- `--dry-run` should be available for install, remove, update, and init flows.
+- Tests should use fake homes and fixture sources instead of writing to real user harness directories.
+
+## Registry
+
+The CLI keeps an `awesome-agents` registry so `list`, `remove`, and `update` operate only on files the CLI generated.
+
+Registry locations:
+
+- Project installs: `.awesome-agents/installed.json`
+- Global installs: `~/.awesome-agents/installed.json`
+
+The registry is not intended to discover or manage hand-written harness profiles.
+
+## Verification
+
+The initial scaffold was verified with:
+
+- `npm run lint`
+- `npm test`
+- `npm pack --dry-run`
+- local source install smoke tests
+- GitHub source dry-run install smoke tests
+
+## Release Workflow
+
+Release metadata is local and deterministic:
+
+- `npm run changelog` refreshes `CHANGELOG.md` from git commit history.
+- `npm run release -- patch|minor|major|x.y.z` bumps `package.json`,
+  `package-lock.json`, and `src/constants.js`.
+- The release script refreshes `CHANGELOG.md`, runs lint/tests, commits
+  `Release vX.Y.Z`, and creates annotated tag `vX.Y.Z`.
+- `npm run release -- patch --push` also pushes the current branch and tag.
+- The release script does not publish to npm.
+
+## Publishing State
+
+GitHub repository:
+
+- `https://github.com/pablof7z/awesome-agents`
+- Public
+- `main` pushed
+
+npm state:
+
+- Package name `awesome-agents` was available when checked.
+- Publish is blocked because npm is not authenticated on the machine.
+- `npm whoami` returns `E401`.
+- `npm publish --access public` returns npm's "not found or no permission" error.
+- This is not an OTP blocker yet; npm auth or token setup must happen first.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "awesome-agents",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Install reusable agent profiles into Codex, Claude Code, and OpenCode.",
   "type": "module",
   "bin": {
@@ -9,12 +9,17 @@
   "files": [
     "bin",
     "src",
+    "scripts",
     "docs",
     "README.md",
+    "CHANGELOG.md",
     "AGENTS.md"
   ],
   "scripts": {
-    "lint": "node --check bin/awesome-agents.js && node --check src/*.js && node --check test/*.test.js",
+    "changelog": "node scripts/changelog.js --write",
+    "lint": "node --check bin/awesome-agents.js && node --check src/*.js && node --check scripts/*.js && node --check test/*.test.js",
+    "release": "node scripts/release.js",
+    "release:dry-run": "node scripts/release.js --dry-run",
     "test": "node --test"
   },
   "keywords": [