awesome-agents 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+This file is maintained by `npm run changelog` and `npm run release`. Release entries are generated from git commit history.
+
+## 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,25 +4,27 @@
 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.
+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.
 
 ## 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 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
 ```
 
-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 pablof7z/touch-grass --agent ios-tester --dry-run
 ```
 
 ## Commands
@@ -39,8 +41,10 @@ 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 ios-tester`
+- `--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
@@ -85,12 +89,29 @@ 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
+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 list --json
+npx awesome-agents remove ios-tester --agent codex
+npx awesome-agents update ios-tester --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

@@ -25,6 +25,34 @@ Supported source values:
 For GitHub sources, the CLI clones a shallow temporary copy and reads
 `agents/profiles`.
 
+## 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 pablof7z/touch-grass --agent ios-tester
+npx awesome-agents add pablof7z/touch-grass --agent chief-of-staff
+```
+
+`--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
+```
+
+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.
+
 ## 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,49 @@
+# 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 ios-tester`.
+- `--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 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.
+- 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.
+- `--json` should be available for scripts.
+- `--dry-run` should preview writes without touching target files or registries.

package/docs/product/harness-targets.md

@@ -0,0 +1,51 @@
+# Harness Targets
+
+These notes capture how `awesome-agents` targets agent harnesses.
+
+## Initial Harnesses
+
+Initial harness targets:
+
+- Codex
+- Claude Code
+- OpenCode
+
+## Codex
+
+Generated Codex custom agents install to:
+
+- Project: `.codex/agents/<profile>.toml`
+- Global: `$CODEX_HOME/agents/<profile>.toml`, or `~/.codex/agents/<profile>.toml`
+
+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.
+
+## 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
+
+Current `touch-grass` profiles have Codex adapters. Claude Code and OpenCode currently use generated defaults unless source repositories add native adapters for those harnesses.

package/docs/product/open-questions.md

@@ -0,0 +1,20 @@
+# 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 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?

package/docs/product/product-scope.md

@@ -0,0 +1,37 @@
+# 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 `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.
+
+## 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.
+
+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.

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

@@ -0,0 +1,58 @@
+# Profile Source Format
+
+These notes capture how profile source repositories are organized.
+
+## Canonical Layout
+
+The initial source format follows the `touch-grass` layout:
+
+```text
+agents/
+  profiles/
+    <profile>.md
+  adapters/
+    <harness>/
+      <profile>.md
+```
+
+Canonical profiles live at:
+
+```text
+agents/profiles/*.md
+```
+
+Harness adapters live at:
+
+```text
+agents/adapters/<harness>/*.md
+```
+
+## Profile Files
+
+Profile files are Markdown with YAML frontmatter.
+
+The CLI should preserve canonical profile content and generate harness-specific install files. A profile is reusable product content, not local machine setup.
+
+Current `touch-grass` profiles include:
+
+- `chief-of-staff`
+- `ios-tester`
+- `ios-ux-ui-critic`
+
+The `chief-of-staff` 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`.
+- GitHub URLs.
+
+The first source repository is `touch-grass`, but the format should not be hard-coded only to that repository.
+
+## 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.1",
   "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": [

package/scripts/changelog.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(scriptDir, "..");
+const changelogPath = path.join(root, "CHANGELOG.md");
+const packagePath = path.join(root, "package.json");
+const changelogHeader = "# Changelog\n\nThis file is maintained by `npm run changelog` and `npm run release`. Release entries are generated from git commit history.\n\n";
+const categoryOrder = ["Breaking", "Added", "Fixed", "Changed", "Documentation", "Tests", "Maintenance"];
+
+export async function updateChangelog(options = {}) {
+  const version = options.version ?? await readPackageVersion();
+  const date = options.date ?? new Date().toISOString().slice(0, 10);
+  const from = options.from ?? latestVersionTag();
+  const to = options.to ?? "HEAD";
+  const commits = readCommits(from, to);
+  const entry = formatEntry({ version, date, from, commits });
+
+  if (!options.write) {
+    return { changelogPath, entry, commits, from, to, version };
+  }
+
+  const existing = await readExistingChangelog();
+  await fs.writeFile(changelogPath, upsertEntry(existing, entry, version));
+  return { changelogPath, entry, commits, from, to, version };
+}
+
+function readCommits(from, to) {
+  const range = from ? `${from}..${to}` : to;
+  const output = git(["log", "--no-merges", "--pretty=format:%H%x1f%s", range], { allowEmpty: true });
+  if (!output) {
+    return [];
+  }
+
+  return output.split("\n").map((line) => {
+    const [hash, subject] = line.split("\x1f");
+    return {
+      hash,
+      shortHash: hash.slice(0, 7),
+      subject: subject.trim()
+    };
+  }).filter((commit) => commit.subject);
+}
+
+function formatEntry({ version, date, from, commits }) {
+  const lines = [`## ${version} - ${date}`, ""];
+  lines.push(from ? `Changes since \`${from}\`.` : "Initial tracked release.");
+  lines.push("");
+
+  if (commits.length === 0) {
+    lines.push("- No commits found for this release.");
+    return `${lines.join("\n")}\n`;
+  }
+
+  const groups = new Map(categoryOrder.map((category) => [category, []]));
+  for (const commit of commits) {
+    groups.get(categoryFor(commit.subject)).push(commit);
+  }
+
+  for (const category of categoryOrder) {
+    const entries = groups.get(category);
+    if (entries.length === 0) {
+      continue;
+    }
+
+    lines.push(`### ${category}`, "");
+    for (const commit of entries) {
+      lines.push(`- ${cleanSubject(commit.subject)} (${commit.shortHash})`);
+    }
+    lines.push("");
+  }
+
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+function upsertEntry(existing, entry, version) {
+  const body = normalizeBody(existing);
+  const escapedVersion = escapeRegExp(version);
+  const existingEntry = new RegExp(`^## ${escapedVersion} - [^\\n]*\\n[\\s\\S]*?(?=^## \\d+\\.\\d+\\.\\d+ - |(?![\\s\\S]))`, "m");
+
+  if (existingEntry.test(body)) {
+    return `${changelogHeader}${body.replace(existingEntry, entry.trimEnd()).trimStart()}`;
+  }
+
+  return `${changelogHeader}${entry.trimEnd()}\n\n${body.trimStart()}`.trimEnd() + "\n";
+}
+
+function normalizeBody(existing) {
+  if (!existing) {
+    return "";
+  }
+
+  if (existing.startsWith(changelogHeader)) {
+    return existing.slice(changelogHeader.length);
+  }
+
+  return existing.replace(/^# Changelog\s*/i, "").trimStart();
+}
+
+function categoryFor(subject) {
+  const normalized = subject.toLowerCase();
+  if (/^[a-z]+(?:\([^)]+\))?!:/.test(normalized) || normalized.includes("breaking")) {
+    return "Breaking";
+  }
+  if (/^(feat|add)(?:\([^)]+\))?:?\s/.test(normalized)) {
+    return "Added";
+  }
+  if (/^(fix|repair)(?:\([^)]+\))?:?\s/.test(normalized)) {
+    return "Fixed";
+  }
+  if (/^(docs?|readme)(?:\([^)]+\))?:?\s/.test(normalized)) {
+    return "Documentation";
+  }
+  if (/^(test|tests)(?:\([^)]+\))?:?\s/.test(normalized)) {
+    return "Tests";
+  }
+  if (/^(build|chore|ci|release|bump)(?:\([^)]+\))?:?\s/.test(normalized)) {
+    return "Maintenance";
+  }
+  return "Changed";
+}
+
+function cleanSubject(subject) {
+  return subject
+    .replace(/^[a-z]+(?:\([^)]+\))?!?:\s*/i, "")
+    .trim();
+}
+
+function latestVersionTag() {
+  return git(["tag", "--list", "v[0-9]*", "--sort=-version:refname"], { allowEmpty: true })
+    .split("\n")
+    .find(Boolean);
+}
+
+async function readPackageVersion() {
+  const pkg = JSON.parse(await fs.readFile(packagePath, "utf8"));
+  return pkg.version;
+}
+
+async function readExistingChangelog() {
+  try {
+    return await fs.readFile(changelogPath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return "";
+    }
+    throw error;
+  }
+}
+
+function git(args, options = {}) {
+  const result = spawnSync("git", args, {
+    cwd: root,
+    encoding: "utf8"
+  });
+
+  if (result.status !== 0 && !(options.allowEmpty && result.status === 128)) {
+    const detail = result.stderr.trim() || result.stdout.trim() || `git exited with ${result.status}`;
+    throw new Error(detail);
+  }
+
+  return result.stdout.trim();
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function parseArgs(argv) {
+  const options = { write: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--write") {
+      options.write = true;
+    } else if (arg === "--version") {
+      options.version = argv[++index];
+    } else if (arg === "--from") {
+      options.from = argv[++index];
+    } else if (arg === "--to") {
+      options.to = argv[++index];
+    } else if (arg === "--date") {
+      options.date = argv[++index];
+    } else if (arg === "-h" || arg === "--help") {
+      options.help = true;
+    } else {
+      throw new Error(`Unknown option ${arg}`);
+    }
+  }
+  return options;
+}
+
+function printHelp() {
+  console.log(`Usage: node scripts/changelog.js [options]
+
+Options:
+  --write              Update CHANGELOG.md instead of printing the next entry
+  --version <version>  Release version to write; defaults to package.json
+  --from <ref>         Starting git ref; defaults to latest v* tag
+  --to <ref>           Ending git ref; defaults to HEAD
+  --date <date>        Release date; defaults to today
+`);
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  const result = await updateChangelog(options);
+  if (options.write) {
+    console.log(`Updated ${path.relative(root, result.changelogPath)} for ${result.version} with ${result.commits.length} commit(s).`);
+  } else {
+    process.stdout.write(result.entry);
+  }
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/scripts/release.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { updateChangelog } from "./changelog.js";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(scriptDir, "..");
+const packagePath = path.join(root, "package.json");
+const lockPath = path.join(root, "package-lock.json");
+const constantsPath = path.join(root, "src", "constants.js");
+const trackedReleaseFiles = [
+  "package.json",
+  "package-lock.json",
+  "src/constants.js",
+  "CHANGELOG.md"
+];
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  const currentVersion = await readPackageVersion();
+  const nextVersion = resolveNextVersion(currentVersion, options.bump);
+  const tag = `v${nextVersion}`;
+
+  if (!options.dryRun) {
+    assertCleanWorktree();
+  }
+
+  console.log(`Release plan: ${currentVersion} -> ${nextVersion}`);
+
+  if (options.dryRun) {
+    const changelog = await updateChangelog({ version: nextVersion, write: false });
+    console.log("\nFiles that would be updated:");
+    for (const file of trackedReleaseFiles) {
+      console.log(`- ${file}`);
+    }
+    console.log("\nChangelog entry preview:\n");
+    process.stdout.write(changelog.entry);
+    return;
+  }
+
+  await updatePackageJson(nextVersion);
+  await updatePackageLock(nextVersion);
+  await updateConstants(nextVersion);
+  await updateChangelog({ version: nextVersion, write: true });
+
+  if (!options.skipChecks) {
+    run("npm", ["run", "lint"]);
+    run("npm", ["test"]);
+  }
+
+  git(["add", ...trackedReleaseFiles]);
+  git(["commit", "-m", `Release ${tag}`]);
+  git(["tag", "-a", tag, "-m", `Release ${tag}`]);
+
+  if (options.push) {
+    const branch = git(["branch", "--show-current"], { capture: true });
+    if (!branch) {
+      throw new Error("Cannot push from a detached HEAD.");
+    }
+    git(["push", "origin", branch]);
+    git(["push", "origin", tag]);
+  }
+
+  console.log(`Cut ${tag}.`);
+  if (!options.push) {
+    console.log(`Push with: git push origin HEAD && git push origin ${tag}`);
+  }
+}
+
+function parseArgs(argv) {
+  const options = {
+    bump: "patch",
+    dryRun: false,
+    push: false,
+    skipChecks: false
+  };
+  const positional = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (arg === "--push") {
+      options.push = true;
+    } else if (arg === "--skip-checks") {
+      options.skipChecks = true;
+    } else if (arg === "-h" || arg === "--help") {
+      options.help = true;
+    } else if (arg.startsWith("-")) {
+      throw new Error(`Unknown option ${arg}`);
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  if (positional.length > 1) {
+    throw new Error(`Expected one bump argument, received: ${positional.join(", ")}`);
+  }
+  if (positional[0]) {
+    options.bump = positional[0];
+  }
+
+  return options;
+}
+
+function resolveNextVersion(currentVersion, bump) {
+  const explicit = bump.replace(/^v/, "");
+  if (/^\d+\.\d+\.\d+$/.test(explicit)) {
+    return explicit;
+  }
+
+  const match = currentVersion.match(/^(\d+)\.(\d+)\.(\d+)$/);
+  if (!match) {
+    throw new Error(`Cannot bump non-standard version ${currentVersion}. Pass an explicit x.y.z version.`);
+  }
+
+  const parts = match.slice(1).map(Number);
+  if (bump === "major") {
+    return `${parts[0] + 1}.0.0`;
+  }
+  if (bump === "minor") {
+    return `${parts[0]}.${parts[1] + 1}.0`;
+  }
+  if (bump === "patch") {
+    return `${parts[0]}.${parts[1]}.${parts[2] + 1}`;
+  }
+
+  throw new Error(`Unsupported release bump "${bump}". Use patch, minor, major, or x.y.z.`);
+}
+
+async function readPackageVersion() {
+  const pkg = JSON.parse(await fs.readFile(packagePath, "utf8"));
+  return pkg.version;
+}
+
+async function updatePackageJson(version) {
+  const pkg = JSON.parse(await fs.readFile(packagePath, "utf8"));
+  pkg.version = version;
+  await writeJson(packagePath, pkg);
+}
+
+async function updatePackageLock(version) {
+  const lock = JSON.parse(await fs.readFile(lockPath, "utf8"));
+  lock.version = version;
+  if (lock.packages?.[""]) {
+    lock.packages[""].version = version;
+  }
+  await writeJson(lockPath, lock);
+}
+
+async function updateConstants(version) {
+  const content = await fs.readFile(constantsPath, "utf8");
+  const next = content.replace(
+    /export const PACKAGE_VERSION = "[^"]+";/,
+    `export const PACKAGE_VERSION = "${version}";`
+  );
+  if (next === content) {
+    throw new Error("Could not find PACKAGE_VERSION in src/constants.js.");
+  }
+  await fs.writeFile(constantsPath, next);
+}
+
+async function writeJson(filePath, value) {
+  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function assertCleanWorktree() {
+  const status = git(["status", "--short"], { capture: true });
+  if (status) {
+    throw new Error(`Release requires a clean worktree:\n${status}`);
+  }
+}
+
+function run(command, args) {
+  const result = spawnSync(command, args, {
+    cwd: root,
+    stdio: "inherit"
+  });
+  if (result.status !== 0) {
+    throw new Error(`${command} ${args.join(" ")} failed with ${result.status}`);
+  }
+}
+
+function git(args, options = {}) {
+  const result = spawnSync("git", args, {
+    cwd: root,
+    encoding: "utf8",
+    stdio: options.capture ? ["ignore", "pipe", "pipe"] : "inherit"
+  });
+  if (result.status !== 0) {
+    const detail = result.stderr?.trim() || result.stdout?.trim() || `git exited with ${result.status}`;
+    throw new Error(detail);
+  }
+  return options.capture ? result.stdout.trim() : "";
+}
+
+function printHelp() {
+  console.log(`Usage: npm run release -- [patch|minor|major|x.y.z] [options]
+
+Cuts a release commit and annotated git tag. It does not publish to npm.
+
+Options:
+  --dry-run       Preview version and changelog changes
+  --push          Push the current branch and release tag after tagging
+  --skip-checks   Skip npm run lint and npm test
+`);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/src/cli.js

@@ -28,7 +28,9 @@ export async function run(argv = process.argv) {
     .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("-a, --agent <agent>", "Agent profile slug to use; accepts a harness name for backward compatibility")
+    .option("--harness <harness>", `Target harness (${SUPPORTED_AGENTS.join(", ")})`)
+    .option("--target <harness>", "Compatibility alias for --harness")
     .option("--json", "Output JSON")
     .option("--home <dir>", "Override HOME for path expansion")
     .action(async (source = undefined, options) => {
@@ -136,7 +138,9 @@ function addInstallCommand(program, commandName) {
     .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("-a, --agent <agents...>", "Agent profile slugs to install; accepts harness names for backward compatibility")
+    .option("--harness <harnesses...>", `Target harnesses (${SUPPORTED_AGENTS.join(", ")}, or *)`)
+    .option("--target <harnesses...>", "Compatibility alias for --harness")
     .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")

package/src/constants.js

@@ -1,5 +1,5 @@
 export const PACKAGE_NAME = "awesome-agents";
-export const PACKAGE_VERSION = "0.1.0";
+export const PACKAGE_VERSION = "0.1.1";
 export const DEFAULT_SOURCE = "pablof7z/touch-grass";
 export const DEFAULT_AGENT = "codex";
 export const SUPPORTED_AGENTS = ["codex", "claude-code", "opencode"];

package/src/installer.js

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { DEFAULT_AGENT, SUPPORTED_AGENTS } from "./constants.js";
+import { AGENT_ALIASES, DEFAULT_AGENT, SUPPORTED_AGENTS } from "./constants.js";
 import { contentHash, isGeneratedContent, normalizeAgentList, renderForAgent, resolveTargetPath } from "./renderers.js";
 import { loadCatalog, materializeSource, splitSourceSpec } from "./source.js";
 import { readRegistry, registryPath, removeInstall, upsertInstall, writeRegistry } from "./registry.js";
@@ -20,10 +20,9 @@ export async function listAvailable(sourceInput, options = {}) {
 export async function installFromSource(sourceSpec, options = {}) {
   const split = splitSourceSpec(sourceSpec);
   const source = split.source;
-  const optionProfiles = normalizeProfileSelectors(options.profiles ?? options.profile ?? options.skills ?? options.skill);
-  const selectors = split.profile ? [...optionProfiles, split.profile] : optionProfiles;
+  const { selectors, harnessInput } = resolveInstallSelection(split, options);
   const scope = resolveScope(options);
-  const harnesses = normalizeAgentList(options.agents ?? options.agent, {
+  const harnesses = normalizeAgentList(harnessInput, {
     all: options.all,
     defaultAgent: DEFAULT_AGENT
   });
@@ -80,12 +79,12 @@ export async function installFromSource(sourceSpec, options = {}) {
 
 export async function useFromSource(sourceSpec, options = {}) {
   const split = splitSourceSpec(sourceSpec);
-  const profileSelector = options.profile ?? options.skill ?? split.profile;
+  const { profileSelector, harnessInput } = resolveUseSelection(split, options);
   if (!profileSelector) {
     throw new Error("Specify a profile with source@profile or --profile <profile>.");
   }
 
-  const harness = normalizeAgentList(options.agent ? [options.agent] : options.agents, {
+  const harness = normalizeAgentList(harnessInput, {
     defaultAgent: DEFAULT_AGENT
   })[0];
   const materialized = await materializeSource(split.source, options);
@@ -285,6 +284,72 @@ function normalizeProfileSelectors(values) {
     .filter(Boolean);
 }
 
+function resolveInstallSelection(split, options = {}) {
+  const selectors = [
+    ...normalizeProfileSelectors(options.profiles ?? options.profile ?? options.skills ?? options.skill)
+  ];
+  const explicitHarnessInput = firstDefined(options.harnesses, options.harness, options.targets, options.target);
+  const agentValues = normalizeProfileSelectors(options.agents ?? options.agent);
+  const agentHarnesses = [];
+
+  for (const value of agentValues) {
+    if (isHarnessSelector(value)) {
+      agentHarnesses.push(value);
+    } else {
+      selectors.push(value);
+    }
+  }
+
+  if (split.profile) {
+    selectors.push(split.profile);
+  }
+
+  return {
+    selectors,
+    harnessInput: explicitHarnessInput ?? (agentHarnesses.length > 0 ? agentHarnesses : undefined)
+  };
+}
+
+function resolveUseSelection(split, options = {}) {
+  const selectors = [
+    ...normalizeProfileSelectors(options.profiles ?? options.profile ?? options.skills ?? options.skill)
+  ];
+  const explicitHarnessInput = firstDefined(options.harnesses, options.harness, options.targets, options.target);
+  const agentValues = normalizeProfileSelectors(options.agents ?? options.agent);
+  const agentHarnesses = [];
+
+  for (const value of agentValues) {
+    if (isHarnessSelector(value)) {
+      agentHarnesses.push(value);
+    } else {
+      selectors.push(value);
+    }
+  }
+
+  if (split.profile) {
+    selectors.push(split.profile);
+  }
+
+  const uniqueSelectors = [...new Set(selectors)];
+  if (uniqueSelectors.length > 1) {
+    throw new Error(`Use renders one profile at a time. Received: ${uniqueSelectors.join(", ")}`);
+  }
+
+  return {
+    profileSelector: uniqueSelectors[0],
+    harnessInput: explicitHarnessInput ?? (agentHarnesses.length > 0 ? agentHarnesses : undefined)
+  };
+}
+
+function isHarnessSelector(value) {
+  const normalized = String(value).toLowerCase();
+  return normalized === "*" || AGENT_ALIASES.has(normalized);
+}
+
+function firstDefined(...values) {
+  return values.find((value) => value !== undefined);
+}
+
 function profileSummary(profile, source) {
   return {
     slug: profile.slug,

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

@@ -1,45 +0,0 @@
-# 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`.