Contributing

Thanks for thinking about contributing. This catalogue grows by primitives — packs, skills, subagents — and each kind of contribution has a different shape. Pick the lane that fits your change.

Understand the product before changing it

The technical documentation is the best product-level entry point: it routes by use case and role into the adopter guides and generated pack reference. The source is deliberately split:

• guides/ owns public tutorials, how-tos, reference, and explanation.
• packs/<pack>/README.md owns what each pack ships; the docs build generates the complete pack reference from those sources and pack.toml.
• docs-site/src/content/docs/ owns only the technical-doc entry pages; generated pack and guide pages are not edited there.
• docs/architecture/overview.md maps the repository implementation for contributors.

For a quick orientation, go from technical docs → the relevant pack guide → its source under packs/ → the current architecture or contract. This lets you see the adopter experience before changing the machinery behind it.

How decisions become changes

research or observed problem → RFC → ADR when needed → spec + plan → implementation → adopter docs

The chain is proportional, not ceremonial: small fixes can go straight to a PR, while a new public contract, pack, top-level structure, or substantive charter change starts with an RFC. Research under docs/product/research/ supplies evidence; RFCs record the proposal and trade-offs; ADRs record durable architectural decisions; specs and plans define the accepted behavior and implementation. If the answer is absent from those sources, it has not been decided—ask or open an RFC rather than inferring policy from nearby code.

Before you start

Two reads will save you time:

• AGENTS.md — how this repo expects agents and contributors to work (the plan → execute → verify → review loop, what’s in scope vs out, the non-negotiables).
• docs/CONVENTIONS.md — the single source of truth for how we work in this repo: document hierarchy, commit format, PR shape, and the pack source-of-truth split that every code change in this repo lives under.

One install: the artifact and skill-spec linters parse YAML via PyYAML. Run pip install -r tools/requirements.txt once. The linters also print an actionable install hint with exit code 2 if the import fails, so the first lint run will remind you.

If a change’s direction is still unresolved and more than one owner has to agree, open an RFC first — as does any change to the charter’s mission or scope, to who may approve work, to a security trust model, or that breaks a published compatibility promise. A decision you have already made is an ADR. Everything else, including new directories and contract surfaces whose shape is settled, goes straight to PR.

The pack source-of-truth split

Every adapter-projected file in this repo has an upstream under packs/<pack>/. You edit the upstream; the build regenerates the projection. Direct edits to projected paths (.claude/skills/<name>/SKILL.md, .claude/agents/<name>.md, tools/hooks/<name>.*, the hooks key of .claude/settings.local.json, etc.) are caught by make build-check and bounced with the message naming the source path.

The muscle memory: edit the upstream, run make build-self (add FORCE=1 if your tree is dirty), commit both the upstream and the regenerated projection in the same PR.

Full rule with the projected-paths list: CONVENTIONS.md § Pack source-of-truth split.

Three contribution lanes

Adding a new pack

A new pack is a coherent slice — a workflow, a reviewer lens, a document shape — packaged as a unit. The ceremony exists because a pack adds public contract surface: a name in the published catalogue, an install URI adopters may pin against, and guidance they will rely on.

Start with the portable catalogue-authoring-standards.md hub. It is the canonical contract for pack structure, metadata, composition, public guidance, and verification.

Steps:

0. Design the pack’s workflow arc first. A pack is a set of cohesive workflows for a role’s work — not a list of features. Before writing any SKILL.md, work through the pack workflow design framework at guides/_shared/explanation/pack-workflow-design.md. It takes you through: characterizing whether your pack is episodic, sustained-project, or sustained-derived; mapping the Arrive → Orient → Work → Persist → Collaborate arc to your pack’s skill set; naming your skills against the verb taxonomy; and deciding whether your pack needs a status skill, a *-project-start skill, and config-driven output paths. The RFC reviewers will ask these questions; answering them before you write the skill bodies saves a review cycle.

1. Open an RFC. New packs need RFC review — the contract surface is published, not internal. See docs/rfc/ for the template and recent precedents (RFC-0004 added install-scope-per-pack; RFC-0007 added the user-scope converter pack). The RFC should include your arc mapping from step 0 — which skills cover which arc stages, and why.

2. Create packs/<your-pack>/ with the directory shape:

   • pack.toml — manifest. Conforms to contracts/pack.schema.json. Required tables: [pack], [pack.adapter-contract], [pack.install]. Cross-field invariant default-scope ∈ allowed-scopes is schema-enforced.
   • .apm/ — upstream for adapter-projected primitives (skills/, agents/, hooks/, commands/, hook-wiring/).
   • seeds/ — upstream for seed-projected files (README, governance content). Files prefixed _ are composition fragments, not standalone.

3. Run the pack validator. agentbundle validate packs/<your-pack>; fix anything it reports before opening the PR.

4. If you claim user scope, justify it. The user-scope eligibility test is falsifiable: content must be project-portable (no hooks that wire into a specific repo’s surface, no seeds that name this project).

5. Declare optional composition when it exists. Add [[pack.integrations]] entries to pack.toml for useful cross-pack relationships that are not required dependencies. This convention shipped in Wave 2; the authoring standards carry the complete contract.

6. Complete public discovery at the sources. Add the pack guide home and journey required by the authoring standards and register its curated site group in site.toml. The public catalogue and technical pack index derive from pack metadata; do not add a row to the root README or edit generated site output.

7. Regenerate the catalogue manifest. make build-self updates the projected marketplace and self-hosted outputs.

Adding or modifying a skill

Skills in this catalogue follow the agentskills.io specification. Full authoring rules, spec compliance requirements, and linting guidance live in packs/AGENTS.md § Authoring or editing a skill. Skill changes are the most common contribution.

Steps:

1. Pick the pack. Edit an existing pack’s .apm/skills/ if your skill fits there. If it doesn’t fit any pack, open an issue rather than wedging it in.
2. Edit packs/<pack>/.apm/skills/<name>/SKILL.md (the source). Never edit a projected copy.
3. For credentialed skills, follow guides/credential-brokers/how-to/add-a-credentialed-skill.md; packs/atlassian/.apm/skills/jira/ is a reference consumer.
4. Run make build-self, commit source + projection together.

Adding or modifying a subagent

A subagent is a sharp diff-review or execution lens — currently four: adversarial-reviewer, security-reviewer, quality-engineer, implementer. The bar to add another is high: a new lens needs a differentiable role the existing four don’t cover, with reviewer findings that wouldn’t have surfaced otherwise.

core’s finding-adjudicator sits outside that set and clears the bar a different way: it is not a fifth review lens. It discovers no defects and walks no checklist. It serves the distinct work type of finding adjudication — testing a completed reviewer’s claims against repository evidence so only sustained findings enter the loop’s decision and repair context. Adding a genuine fifth review lens still faces the bar above.

Steps:

1. Pressure-test the addition. A subagent earns its slot by catching something the existing reviewers miss, at a frequency that justifies the runtime. If you can’t name two concrete bugs the proposed lens would have caught in the last quarter of PRs, the answer is probably “extend an existing reviewer’s prompt” instead of “add a new agent.”
2. Edit packs/<pack>/.apm/agents/<name>.md (upstream — typically packs/core/). Never edit .claude/agents/<name>.md.
3. Frontmatter contract. Required: name, description. Recommended: tools, model. The description’s first sentence is what other agents see when picking a reviewer, so make it differentiable in one line.
4. Run make build-self, commit upstream + projection.

Before you open the PR

Three gates, all of which run locally:

• make build-self — regenerates every projected path from its upstream. Catches drift.
• make build-check — fails if any projected path was edited directly without the upstream moving. Run this after build-self to confirm the tree is clean.
• conventions-check — the agent-artifact and conventions linter (also runs via the pre-pr hook). Available as a slash command in the core pack.

Commit format is Conventional Commits — full rules in CONVENTIONS.md § Commits. If your commit implements a spec, RFC, or ADR, cite it in the footer (Spec:, RFC:, ADR:).

Cutting an agentbundle release

Publishing a new agentbundle version to PyPI is a maintainer task, not a contributor lane. The release pipeline is .github/workflows/release-agentbundle.yml (jobs: build-and-smoke → publish-pypi via Trusted Publisher OIDC → publish-artifactory, the last green-skipped unless the corp Artifactory secrets are set). A tag push is the only trigger that publishes — PRs touching packages/agentbundle/** run build-and-smoke as a pre-merge gate, and there’s no manual twine upload.

Per release:

1. Bump the version in packages/agentbundle/pyproject.toml and add a matching entry to packages/agentbundle/CHANGELOG.md, in the same PR. Merge it to main through the normal gates.
2. Tag the tip of main — never a feature branch:

   git checkout main && git pull origin main
   git tag agentbundle-vX.Y.Z          # X.Y.Z must equal the pyproject version
   git push origin agentbundle-vX.Y.Z

3. Watch the run (Actions → release-agentbundle). build-and-smoke and publish-pypi must go green; publish-artifactory shows green-skipped when the corp secrets are unset.
4. Verify from a clean venv, ideally on another machine: python -m pip install agentbundle resolves to the new version and agentbundle --help exits 0.

Caveats the workflow enforces — know them before you tag:

• The tag format is exact: agentbundle-vX.Y.Z. Pre-release / build-metadata suffixes (-rc1, +build) are refused by the version-assertion step.
• The tag’s X.Y.Z must equal the pyproject version, and the tagged commit must be an ancestor of origin/main — both are fail-closed assertions in build-and-smoke, so a wrong tag never publishes.
• A successful publish burns the version number permanently — PyPI does not allow re-uploading the same version. A publish that never reached PyPI leaves the number claimable (delete the tag with git push origin :refs/tags/agentbundle-vX.Y.Z, fix, re-tag) — but a partial publish that did reach PyPI also burns it, so treat any run where publish-pypi started as a burn.
• 1.0.0 or higher is §Ask first — the pre-1.0 stability contract changes at 1.0; record explicit sign-off in the release PR before pushing such a tag.

The one-time PyPI account + Pending Publisher setup is not repeated per release; it lives in the plan’s Rollout § Phase B.

Cutting a credbroker release

Publishing a new credbroker version to PyPI mirrors the agentbundle flow above — same shape, separate package. The pipeline is .github/workflows/release-credbroker.yml (jobs: build-and-smoke → publish-pypi via Trusted Publisher OIDC → publish-artifactory, the last green-skipped unless the corp Artifactory secrets are set). A tag push is the only trigger that publishes; PRs touching packages/credbroker/** run build-and-smoke as a pre-merge gate, and there’s no manual twine upload.

Per release:

1. Bump the version in both places, in the same PR. credbroker carries the version twice: packages/credbroker/pyproject.toml (version) and packages/credbroker/credbroker/__init__.py (__version__, which the wheel-smoke step reads). Keep them equal — a mismatch ships a wheel whose credbroker.__version__ disagrees with its distribution version. (credbroker has no CHANGELOG.md today; add one if the cadence warrants it.) Merge to main through the normal gates.
2. Tag the tip of main — never a feature branch:

   git checkout main && git pull origin main
   git tag credbroker-vX.Y.Z          # X.Y.Z must equal the pyproject version
   git push origin credbroker-vX.Y.Z

3. Watch the run (Actions → release-credbroker). build-and-smoke and publish-pypi must go green; publish-artifactory shows green-skipped when the corp secrets are unset.
4. Verify from a clean venv, ideally on another machine: python -m pip install credbroker resolves to the new version and python -c "import credbroker; print(credbroker.__version__)" prints it.

Caveats the workflow enforces — the same fail-closed assertions as agentbundle:

• The tag format is exact: credbroker-vX.Y.Z. Pre-release / build-metadata suffixes (-rc1, +build) are refused by the version-assertion step.
• The tag’s X.Y.Z must equal the pyproject version, and the tagged commit must be an ancestor of origin/main — both fail-closed in build-and-smoke, so a wrong tag never publishes.
• A successful publish burns the version number permanently — PyPI does not allow re-uploading the same version. A tag whose run never reached publish-pypi leaves the number claimable (delete the tag with git push origin :refs/tags/credbroker-vX.Y.Z, fix, re-tag); treat any run where publish-pypi started as a burn — even a partial upload that reached PyPI claims the version.

The one-time PyPI Trusted Publisher — a Pending Publisher matching release-credbroker.yml’s publish-pypi job (project credbroker, owner eugenelim, repo agent-ready-repo, workflow release-credbroker.yml, environment pypi) — was configured at the 0.1.0 publish and is not repeated per release. The name-registration decision it implements (claim the name on the first real publish, no interim placeholder) is recorded in docs/backlog.md.

Where to find authoritative information

You want to know…	Look here
Mission, scope, principles	docs/CHARTER.md
Public product behavior and task guidance	Technical docs and their source in guides/
Current repository architecture	docs/architecture/overview.md
How we work, document hierarchy	docs/CONVENTIONS.md
Evidence informing a product direction	docs/product/research/
Why we chose X over Y	docs/adr/
In-flight proposals	docs/rfc/
Accepted behavior and build plan	docs/specs/
Current initiative and dependency state	workspace.toml
Per-IDE adapter contract	contracts/adapter.toml
Pack manifest schema	contracts/pack.schema.json
Portable catalogue authoring standards and contracts	guides/_shared/reference/catalogue-authoring-standards.md
Catalogue model rationale	RFC-0001

When this file is wrong

Flag the drift in your PR rather than working around it. Substantive changes to this file go through RFC; small fixes are normal PRs.

License

Contributions are dual-licensed under MIT and Apache 2.0 — the same terms as the catalogue itself. By opening a PR you agree to those terms unless you state otherwise.