srobroek/agentic-packages

Shared agentic tooling for AI coding assistants -- installable through APM, the Agent Package Manager.

This repository is an APM marketplace: a curated catalog of agents, skills, hooks, steering instructions, MCP server definitions, and a SpecKit-driven orchestration system. Everything is authored once under .apm/ and compiled to whatever runtime you use -- Claude Code, Codex, Copilot, Cursor, Gemini, OpenCode, or Windsurf.

• 22 bundles -- opinionated dependency-aggregator packages grouping skills, agents, and steering for a domain (frontend, security, a language toolchain, SpecKit, ...)
• 33 skills -- reusable workflows, each its own package (catchup, code-review, research, verify, ...)
• 11 agents -- sub-agents with model/tool/permission profiles (coder, pr-reviewer, adversarial-challenger, external-repo-worker)
• 17 steering packages -- opt-in opinionated conventions (per domain and per language)
• 7 MCP server packages -- pre-wired Model Context Protocol servers (context7, playwright, serena, ...)
• 12 hook packages -- opt-in lifecycle hooks and guards (bash/git safety, branch check, git workflow, quality, merge policies, tool prefs, worktrees), cross-tool for Claude and Codex

Many packages also ship hooks directly: code-intelligence (indexing/discovery), agent-builder (delegation reminder), the MCP packages (version/snapshot refresh), and speckit (workflow guards). Hooks deploy per package and target whichever runtime supports the event.

---

Table of contents

• Quick start
• Installing APM
• Adding the marketplace
• Consuming as a native plugin marketplace (no APM CLI)
• Installing a bundle, package, or tool
• Installing globally (user scope)
• How bundles work
• Compiling for different targets
• SpecKit orchestration
• Documentation
• Developing this repository

---

Quick start

# 1. Install the APM CLI (see next section for alternatives)
uv tool install apm-cli

# 2. Register this marketplace
apm marketplace add srobroek/agentic-packages --name srobroek-agentic

# 3. Browse what's available
apm marketplace browse srobroek-agentic

# 4. Install the baseline bundle into your project
apm install core@srobroek-agentic --target claude,codex

# 5. Compile steering into your runtime's native context files
apm compile --target codex,claude --no-constitution

core is the deterministic baseline -- core agents, code-intelligence skills, project-lifecycle skills, agentic-maintenance skills, and the Matt Pocock diagnose/grill workflows. Add domain bundles (frontend, security, language-python, ...) on top as needed.

---

Installing APM

APM is a Python CLI. Any of these work:

uv tool install apm-cli                   # isolated, recommended
mise use -g "pipx:apm-cli"                # if you use mise

No-install one-shot (handy in CI or before committing to an install):

uv tool run --from apm-cli apm --version

Verify:

apm --version    # Agent Package Manager (APM) CLI version 0.21.0+

This repository targets APM 0.21 or newer. (Semver caret ranges on first-party deps and local-package metadata inheritance both require >= 0.18; 0.21 is the recommended floor.)

---

Adding the marketplace

A marketplace is a catalog APM can resolve packages from. Register this one once per machine:

apm marketplace add srobroek/agentic-packages --name srobroek-agentic
apm marketplace browse srobroek-agentic

You can then install any catalog entry with the name@marketplace form (see below).

Direct from GitHub -- if you'd rather skip the marketplace and pin the repo directly, add it to your project apm.yml:

dependencies:
  apm:
    - srobroek/agentic-packages            # whole repo
    - srobroek/agentic-packages#v1.2.0     # pinned to a tag

---

Consuming as a native plugin marketplace (no APM CLI)

apm pack generates native plugin-marketplace manifests committed at the repo root, and each package ships committed target manifests (.claude-plugin/plugin.json and .codex-plugin/plugin.json) plus its supported skills, agents, hooks, and MCP files, generated by .apm/scripts/build-native-plugins.py. So this catalog works as a first-class plugin marketplace for Claude Code and Codex without installing the APM CLI:

• .claude-plugin/marketplace.json -- Claude Code plugin marketplace
• .agents/plugins/marketplace.json -- Codex plugin marketplace

Plugin source values are repo-relative (./packages/<name>), resolved against the cloned marketplace repo, so native install works out of the box on a fresh clone.

Claude Code

/plugin marketplace add srobroek/agentic-packages
/plugin install core@srobroek-agentic

/plugin marketplace add accepts the owner/repo GitHub shorthand (append @<ref> to pin a branch or tag); /plugin install <name>@srobroek-agentic installs any catalog entry. Run /plugin for the interactive Discover menu.

Non-interactively, in project .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "srobroek-agentic": {
      "source": { "source": "github", "repo": "srobroek/agentic-packages" }
    }
  },
  "enabledPlugins": [
    { "marketplace": "srobroek-agentic", "plugin": "core" }
  ]
}

Codex

Codex (0.137+) reads the same catalog from .agents/plugins/marketplace.json via its native plugin system:

codex plugin marketplace add srobroek/agentic-packages
codex plugin list                       # browse the catalog
codex plugin add core@srobroek-agentic  # install a plugin

Entries resolve to the same ./packages/<name> native layout; an installed plugin is cached under $CODEX_HOME/plugins/cache/.

Codex plugin hooks are not trusted automatically. Review new or changed plugin hooks with /hooks. APM deploys agents from hybrid packages to both Claude and Codex: Claude receives Markdown and Codex receives TOML. Raw and semantic Codex profiles are separate agent-* packages rather than one all-agents bundle. Dependency bundles still require the APM flow to resolve members. MCP packages use a Codex-specific direct server map rather than Claude's mcpServers wrapper.

⚠️ Steering packages do NOT work via native /plugin install

This is the one gotcha. Claude/Codex plugin components are skills, agents, hooks, MCP servers -- there is no native component for rules / instructions / always-on steering. A plugin's CLAUDE.md is not loaded, and skills are model-invoked (loaded only on demand), so they can't carry always-on guidance.

Consequence: installing a steering package (steering-*, language-steering-*) -- or the steering content inside a few mixed packages -- via native /plugin install / codex plugin add installs only metadata and any other supported components; it contributes no rules. Steering is delivered only by the APM CLI, which maps .apm/instructions to Claude rules and compiled Codex AGENTS.md:

apm install steering-pragmatic@srobroek-agentic --target claude,codex

Specifically, native install does not deliver:

• all steering-* and language-steering-* packages (steering only);
• agent-hook-contract (reference instructions only);
• the architecture context carried by language-rust / language-typescript;
• the always-on instruction inside hooks-subagent-worktree (the hook itself works; the "declare isolation" guidance is APM-only);
• the Tauri instruction/context inside mcp-tauri (the MCP runtime is configured separately; the steering is APM-only).

If you rely on steering, use the APM CLI flow for those packages (or for everything). Bundles that aggregate external plugins (e.g. developer-tools, security, matt-skills) likewise resolve their members only through APM.

The APM CLI flow and the native plugin flow install the same native packages from the same catalog -- pick whichever fits your setup. The APM flow additionally delivers steering (apm compile → native rules) and resolves external/aggregator bundles; native plugins are consumed directly by the runtime but skip steering.

---

Installing a bundle, package, or tool

All three are installed the same way -- by name from the marketplace, or by subdir from the repo.

# A bundle (group of skills/agents/steering)
apm install frontend@srobroek-agentic

# A single skill
apm install code-review@srobroek-agentic

# A single agent
apm install agent-pr-reviewer@srobroek-agentic

# An MCP server package
apm install mcp-serena@srobroek-agentic

--target is optional -- plain apm install and apm compile auto-detect which runtimes to deploy for from what's already in your project (.claude/, .codex/, etc.). Only pass --target when you want to force a specific set, e.g. on a fresh project that doesn't have those dirs yet:

apm install core@srobroek-agentic --target claude,codex

After installing, compile steering into your runtime's context files:

apm install --target claude,codex
apm compile --target codex,claude --no-constitution

Then audit the installed runtime assets:

apm run inject-agent-models # restore package-owned Codex model settings
apm run check-agent-models  # reject missing mappings and generated drift
apm run audit-agentic-tools   # report runtime parity + agent metadata completeness

A ready-made apm.yml for consuming projects lives in templates/project-apm.yml -- it wires installation, compilation, and audit as apm run setup-agentic-tools.

Each agent-bearing package owns .apm/agent-models.yml. APM 0.26 drops model metadata while producing Codex TOML, so the consuming project's trusted post-install and post-update lifecycle hooks run the shared injector after deployment. The check fails when a source or deployed agent lacks a mapping, when a mapping omits model or reasoning effort, or when generated TOML drifts.

---

Installing globally (user scope)

Some packages here are reusable across every project, not specific to one repo -- the working-style steering, the safety/guard hooks, the bootstrap skills. Install those once at user scope with --global instead of per-project:

# A single always-on steering package, for every session on this machine
apm install steering-pragmatic@srobroek-agentic --global --target claude,codex

# Guard hooks, deployed to both runtimes globally
apm install hooks-bash-safety@srobroek-agentic --global --target claude,codex

apm install --global writes to ~/.apm/ and deploys into the per-tool user dirs (~/.claude/, ~/.codex/) rather than the current project. It merges into existing ~/.claude/settings.json and ~/.codex/hooks.json (tagging its blocks with _apm_source), so it composes with hand-authored config; apm uninstall <pkg>@srobroek-agentic --global removes exactly those blocks.

User-scope support varies by runtime: fully supported for claude, codex, and agent-skills (the cross-client ~/.agents/skills/ dir, which Codex also reads); MCP servers at global scope only target Copilot/Codex CLI. Skills, agents, hooks, and instructions all deploy globally for Claude and Codex.

Recommended global set: granular safety hooks, steering-pragmatic, bootstrap skills, and chezmoi-editor. Pin one package list in user-scope ~/.apm/apm.yml, target both claude,codex, then run install/update and apm compile --global. Target-specific packages such as hooks-subagent-worktree remain in the shared declaration but emit only their supported runtime component. See the Codex compatibility audit for the current 51-package global set and deployment gaps.

Caveat -- symlinked targets. If ~/.claude/settings.json or ~/.codex/hooks.json is a symlink (e.g. into a dotfiles manager), apm install --global writes through the symlink or replaces it with a real file. If you manage those files with a dotfiles tool, have the tool seed a real base file (non-apm config only) and let apm merge its hook blocks on top, rather than symlinking them.

---

Updating and cleaning up after releases

When a release retires or renames packages (see each release's CHANGELOG), refresh installs and prune stale content.

Global (per machine):

apm update --global --yes    # bare form ONLY -- the single-package form
                             # ("apm update --global <pkg>") plans "1 updated,
                             # N removed" and prunes every other global package

Retired packages disappear from ~/.claude/skills / ~/.claude/agents automatically. If a hook or agent misbehaves after the update, check for locally-edited installed files (apm run audit-agentic-assets) and re-deploy with apm install --force -- never hand-edit installed copies; APM skips locally-modified files on every future install.

Per project:

apm update --yes                  # re-resolve; prunes retired packages
apm run audit-agentic-assets      # flags stale or hand-edited installed files
apm compile                       # refresh AGENTS.md / CLAUDE.md

Then check for stragglers:

1. rg '<retired-skill-name>' .claude/ .apm/ AGENTS.md CLAUDE.md -- stale references in project-local steering or docs; edit them out.
2. ls .claude/skills/ -- orphaned directories from pre-lockfile installs are not pruned automatically; delete them manually.
3. SpecKit projects: retired extensions keep their rendered /speckit.<ext>.* command files until removed -- specify extension remove <name> per extension, or re-run scripts/setup-speckit.sh --force to converge on the current set.

---

How bundles work

A bundle is a hand-authored APM package that installs a coherent set of primitives. Each is a directory under packages/ whose apm.yml is a dependency aggregator -- a dependencies.apm: list referencing member packages (and external third-party packages) rather than copying their content. So a change to a member propagates to every bundle that pins it.

Members are referenced as a virtual subdirectory of the marketplace repo, using a caret semver range (srobroek/agentic-packages/packages/<name>#^<version>) so apm update automatically picks up compatible patch releases tracked by the lockfile. Externals (mattpocock and others) stay pinned to #main. Each package is versioned independently via release-please.

core now layers the three sub-bundles (project-lifecycle, code-intelligence, agentic-maintenance) plus resume-session and the Matt Pocock and Hobson plugins explicitly -- so a single apm install core@srobroek-agentic brings in all baseline skills transitively.

Full detail -- the member-reference syntax, the caret-range workflow, and how hooks ship with their owning package -- is in docs/bundles.md.

---

Compiling for different targets

apm compile reads your instructions (local .apm/ + installed apm_modules/) and writes the root context file each runtime loads at startup. One source, many targets:

apm compile --target codex            # AGENTS.md only
apm compile --target claude           # CLAUDE.md only
apm compile --target codex,claude     # both (default for this project)
apm compile --all                     # every canonical target

This project declares targets: [claude, codex] and generates claude/codex marketplace outputs (the only values marketplace.outputs supports). apm compile/install can still target other harnesses (cursor, gemini, copilot, …) on a per-command basis, but they do not produce a generated marketplace artifact.

compilation.strategy: distributed (set in apm.yml) places scoped instructions next to the code they apply to via applyTo: globs; single-file collapses everything into one root file.

--no-constitution excludes any SpecKit memory/constitution.md block -- both the <!-- SPEC-KIT CONSTITUTION --> markers and the constitution body -- from a clean compile. (An existing block already on disk is preserved, not regenerated.)

---

SpecKit orchestration

SpecKit turns ad-hoc "vibe coding" into a gated, spec-driven pipeline: the bugfix and setup skills, four task agents, workflow steering, a guard that keeps task state in beads, and the speckit-feature beads formula whose poured molecule is the phase DAG with human gates at clarify approval, analyze approval, and verify sign-off.

It lives in its own repository now, srobroek/speckit-conductor, and pulls beads and adr-as-beads back from here as cross-repo dependencies. See docs/speckit.md for why it moved and why APM install is the supported path.

Quick start: apm install srobroek/speckit-conductor --target claude,codex, then invoke the speckit-setup skill ("set up SpecKit") to bootstrap .specify/ and the extensions.

Full setup, the agent roster, the DAG node store, and the hook-dispatcher architecture (how/why) live in docs/speckit.md.

---

Documentation

The full inventory lives in docs/:

• docs/bundles.md -- all bundles, what each gives you, and what it includes (plus how bundles work + external sources)
• docs/skills.md -- the standalone skills
• docs/agents.md -- the sub-agents (+ the SpecKit agents)
• docs/steering.md -- the opt-in steering packages
• docs/hooks-and-mcp.md -- the hook packages and MCP server packages
• docs/external-repos.md -- how a catalog entry can live in its own git repo and be fetched on install rather than vendored
• docs/speckit.md -- the SpecKit orchestration system: setup, the DAG, the hook dispatcher, and the how/why
• docs/orchestrate.md -- the multi-agent orchestration system: roles, the bead/wisp object model, claim-then-linked-worktree dispatch, the merge path, and the enforcement hooks

---

Developing this repository

Every installable asset -- each skill, agent, MCP package, bundle, steering package, and hook package -- is a hand-authored package directory under packages/ with its own apm.yml. Edit packages directly; do not edit generated runtime directories (.claude/, .codex/, .agents/, compiled AGENTS.md/CLAUDE.md) by hand. All primitives live under a package's .apm/: agents in .apm/agents/<name>.agent.md, skills in .apm/skills/<name>/SKILL.md, hooks in .apm/hooks/ with their scripts in scripts/ (referenced via ${PLUGIN_ROOT}/scripts/).

Each package has its own apm.yml and is versioned independently via release-please. The marketplace is hand-authored in the root apm.yml marketplace: block and generated to JSON via apm pack. After changing a package manifest or the marketplace block, regenerate artifacts and validate:

apm run build-artifacts                                   # release-please config, indexes, README tables, apm pack
apm compile --validate --local-only --target codex,claude # validate primitives without writing

The README inventory tables are regenerated as part of build-artifacts. CI runs apm run check-readme-tables and apm run check-release-please to fail the build if the committed tables or release-please config are stale.

Adding a new package

Start from a template. templates/ holds one complete, minimal, working example per package type (templates/<type>-package/ for skill, hooks, agent, instructions, bundle, hybrid) plus the project-apm.yml manifest starter. Copy the matching <type>-package/ into packages/<your-name>/, drop the -package suffix, rename the inner files, and fill in the content; templates/README.md documents the canonical layout and the per-type gotchas. Then:

1. Create packages/<name>/apm.yml (type: one of skill | instructions | hooks | hybrid; explicit target; includes: auto) plus its primitives under packages/<name>/.apm/ (skills/<name>/SKILL.md, agents/<name>.agent.md, instructions/*.instructions.md + context/*.context.md, or hooks/<name>-{claude,codex}-hooks.json + scripts/). Agent packages use type: hybrid; use target: all for portable task agents and target: codex for Codex-only raw/semantic profiles. Add .apm/agent-models.yml beside every agent source so post-deploy injection can restore the Codex model and reasoning effort. Use type: hooks for a package whose only primitive is hooks.
2. Register it in the root apm.yml marketplace.packages: block (entries are alphabetical: name, source: ./packages/<name>, category, tags). This block is the marketplace source of truth -- apm pack compiles it into the committed .claude-plugin/marketplace.json + .agents/plugins/marketplace.json. release-please and the README tables auto-discover from packages/, but the marketplace JSON does never -- an unregistered package installs from a subdir ref but won't resolve as <name>@srobroek-agentic.
3. Run apm run build-artifacts and commit the regenerated artifacts alongside the package.

Gotchas worth knowing:

• build-artifacts needs pyyaml. The generator scripts import yaml; if your toolchain Python lacks it, run them via uv run --with pyyaml python3 .apm/scripts/<script>.py. CI gets it transitively from pip install apm-cli.
• Root apm.yml uses targets: (a list), not target: all. apm pack (0.17.x) rejects the all scalar; the list form (targets: [claude, codex]) matches the marketplace outputs: block and is what pack/compile both accept.
• Intra-repo bundle deps pin exact release tags (srobroek/agentic-packages/packages/<name>#<name>-v<version>), not #main or semver ranges. A brand-new member package has no tag until release-please cuts one on merge -- so a bundle that depends on a new package must land after that package is released.

Consuming this repo's own tooling. A project that depends on this marketplace wires the install flow as apm run setup-agentic-tools (see templates/project-apm.yml): trust preflight -> apm install -> apm compile -> model injection -> audit-agentic-tools. Run apm lifecycle trust once after reviewing the template's lifecycle block. Both install-agentic-tools and update-agentic-tools run the preflight and exit non-zero with the failing check named when that exact block is not trusted. APM only discovers lifecycle configuration from the consuming project, not dependency manifests, and lifecycle failures do not abort raw APM operations; the supported wrapper scripts therefore remain the strict path.

License: Apache-2.0 (see LICENSE). Bundles that only aggregate third-party MIT-licensed packages retain their upstream MIT license, declared per package in apm.yml.