Agency GithubAction and NPM

[el-j]

What does this PR do?

This pull request introduces comprehensive improvements to agent loading and orchestration for the Agency Agents project, including a new TypeScript/Node.js npm package, a GitHub Action for workflow integration, and robust test coverage for core functionality. The most important changes are grouped below by theme.

New Integration Options and Documentation

• Added instructions in README.md for using the new agency-agents npm package, including example code for loading agents, listing agents, and building swarms programmatically, as well as CLI usage examples. Also documented the GitHub Action usage and its inputs/outputs.
• Introduced a new GitHub Action via action.yml for loading agents or swarms in workflows, exposing system prompts and agent metadata as outputs. The action is implemented as an inline Node.js script with no dependencies, supporting single-agent and swarm modes, and providing detailed input/output descriptions.

Testing and Reliability

• Added vitest test suites for agent loading (loader.test.ts), registry functions (registry.test.ts), and swarm orchestration (swarm.test.ts), covering slugification, file collection, agent parsing, caching, filtering, and prompt generation. These tests ensure correctness and reliability of all core features. [1] [2] [3]

Agent Loading and Swarm Orchestration

• Implemented agent loading, filtering, and swarm prompt generation logic in the GitHub Action, including slugification, frontmatter parsing, and orchestration rules for multi-agent coordination. The action outputs are compatible with LLM workflows and enable seamless integration.

Summary

These changes make it much easier to integrate Agency Agents into Node.js, TypeScript, and GitHub Actions workflows, while ensuring correctness through extensive tests and clear documentation.

checkout:
#118

[msitarzewski]

Hey @el-j — appreciate the effort here, the code quality is genuinely solid.

Before I can evaluate this properly, I'd love to understand the use case better. Is this related to your work on magic-agent-helix or nexus-orchestrator? What's the workflow where you'd reach for npm install agency-agents vs. just grabbing the markdown files?

A few things on my mind:

1. Contributor simplicity is sacred. Right now someone can add an agent by opening a PR with a single markdown file. I don't want anything in the repo that makes a new contributor think they need to understand TypeScript, npm, or a build system to participate.

2. Package namespace — I've already claimed agency-agents on npm and PyPI, so the packaging story will ultimately come from upstream when the time is right.

3. Repo/fork references — the package.json repository URL and README Action examples currently point to el-j/agency-agents rather than this repo.

4. A few technical notes — the CJS wrapper (require() on an ESM module) would fail at runtime, and the AgentFrontmatter type is missing emoji, vibe, and services from the current spec.

I'm not opposed to eventually having a programmatic API for loading agents — but I want to understand who needs it and why before committing to that direction. What does your usage look like?

[el-j]

Hi @msitarzewski thank you for responding. so for me personally i tinker around with some agents here and there.
the use is very nice - i would call them: identities for agent's - so now i realized my self copying files from a to b all the time to give every project the agent identities it needs for it's workflow is very unhandy.

on the other side i started myself a kind of "VA" virtual agency a while ago: means concierge chat to full workflow via productowner to create detailed planning to pass to full filling correct agent's. the aim was to specialize on selfhosted ollama so all is possible, but nowadays i extracted the orchestrator into the nexus orchestrator and let the VA use it.

... i raised the question on another day where you want to go (as the outlined steps seemed very in what i do currently).

so to make it short:
having the source of the indenities handy as npm or github action would allow to easily pull in the needed agent-profiles much more easy then doing the "c+p" business all the time. 🚀

edit: sure all the links and items will be updated! u claim the name etc. me beeing contributor ... (see where all leads when we talk more ?)

edit2: and a nice gh-page lading would help that easy contributing is to refine the md. the rest must not be this "present" in first place

edit3: and sure i thought of "why not integrating in the nexus" as pull or maybe also into the planned agency the roadmap drafted...

edit4: lastest merge should restore all links and nameings back to u

[mhc222]

Code Review

PR: Agency GithubAction and NPM

This PR introduces a substantial amount of well-crafted work: a typed TypeScript API (src/loader.ts, src/registry.ts, src/swarm.ts), a CLI (src/cli.ts), an npm package with dual CJS/ESM output, a GitHub Action (action.yml), and a full Vitest test suite. The implementation quality is high — the frontmatter parser correctly mirrors the bash get_field logic, the _resetCache pattern for test isolation is well-designed, the setOutput function uses the correct GITHUB_OUTPUT file-based approach, and the dual CJS/ESM build via build-cjs.mjs is handled cleanly.

That said, there are significant process and design concerns that need to be addressed before this can merge.

---

Critical — CONTRIBUTING.md requires a Discussion before tooling PRs

CONTRIBUTING.md explicitly states:

Start a Discussion first: New tooling, build systems, or CI workflows — Changes that touch many files across the repo — New integration formats or platforms

This PR touches 20 files across the entire repo and introduces a package.json, TypeScript build pipeline, test runner, and GitHub Action — all from scratch. Discussion #118 exists but appears to have been opened at the same time as (or after) this PR rather than before, and does not contain maintainer sign-off on the approach. The CONTRIBUTING.md process exists specifically for changes of this scope. The maintainer should confirm alignment before review proceeds.

---

Critical — package-lock.json is committed (3000+ line addition)

The diff includes package-lock.json being committed to the repository. While the PR justifies this as "reproducible CI installs", this is a major repo change: it adds noise to every future diff, creates merge conflicts whenever deps change, and is inconsistent with the existing .gitignore (which was explicitly ignoring package-lock.json before this PR modifies it). The project currently has no CI that runs npm install, so there is no reproducibility benefit yet. This should be discussed with the maintainer.

---

Important — AGENT_CATEGORIES hardcoded in three separate places

The category list appears in:

1. src/loader.ts — AGENT_CATEGORIES export
2. action.yml — inline Node.js AGENT_CATEGORIES constant
3. __tests__/loader.test.ts — implicit assumption via AGENT_CATEGORIES import

These three must stay in sync manually. When a new category directory is added to the repo (which happens frequently, per the open PR list), all three locations need updating. The action.yml inline script is particularly easy to miss. A single source of truth (e.g., a JSON file read by both the TS source and the inline script) would prevent drift.

---

Important — action.yml uses shell: node {0} with inline CommonJS

The action uses shell: node {0} with require() calls. This works on GitHub-hosted runners today but:

• It assumes Node.js is available on the runner (not guaranteed for self-hosted runners without pre-setup)
• It uses CommonJS syntax (require, module.exports) inconsistently with the rest of the codebase which uses ESM throughout
• If the src/ TypeScript code is ever updated, the duplicate inline logic in action.yml will silently diverge

A cleaner approach would be to use a post step that runs the compiled dist/ output, or to split this into a dedicated action/ subdirectory with its own package.json and prebuilt bundle. The inline approach is fragile at this scale.

---

Minor — author field in package.json lists msitarzewski without their involvement in this PR

The package.json sets "author": "msitarzewski", which implies the maintainer authored this package. This should either be el-j (the actual PR author) or should be confirmed with the maintainer before publishing to npm.

---

Minor — No CI workflow added to run tests

A full Vitest test suite is added but there is no .github/workflows/ update to run npm test on PRs. Without CI enforcement, the tests provide no ongoing protection. This is likely intentional if the npm/tooling approach hasn't been formally approved yet, but it should be noted as a gap.

---

The technical implementation quality is genuinely strong and the idea of a typed TypeScript API for agent loading is valuable. The main blockers are the process question (Discussion alignment with maintainer) and the package-lock.json inclusion. I'd recommend resolving the Discussion alignment first, then addressing the category-list duplication and action.yml inline script concerns before requesting a final review.

[el-j]

@mhc222 what about Kimi Code? Nexus also needs removal, so I guess advertising for Kimi is also not wanted here ;)

[msitarzewski]

Hey @el-j — the TypeScript API (loader, registry, swarm, CLI) here is genuinely well-crafted, and the code review confirmed that.

However, per CONTRIBUTING.md, new tooling, build systems, and CI workflows should start as a Discussion before a PR. This adds a full npm package with TypeScript runtime, GitHub Action, tests, and build config — exactly the kind of architectural addition that needs community alignment first.

Could you open a Discussion? Key questions worth answering:

1. Should this live in the main repo or a separate agency-agents-sdk repo?
2. What's the target audience — end users or tool authors building on top of the agents?
3. How does this relate to the existing bash-based convert/install workflow?

This PR has been open since the early days and the repo has evolved a lot since. A Discussion would be the best way to revisit the approach with fresh context. Thanks for the work here!