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).
• AGENTS.md — how we work in this repo: 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: pack-layout.md § The 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 AGENTS.md § Coding conventions. 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	AGENTS.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.

Scaling profiles — how this template adapts to different repo sizes

This template is designed for single applications, components, microservices, and medium-sized platforms or engines — repos with roughly 1 to 50 contributors. It is not designed for sprawling monorepos with hundreds of contributors and SIG-style governance; if that’s your context, look at Kubernetes’ or CNCF’s models instead.

The structure stays the same at every supported size. What changes is which folders you actively populate and how much ceremony each kind of doc carries. An empty folder is not a problem — it’s a placeholder for content that will arrive when it’s needed.

Profile A — Microservice / single component (1-3 contributors)

The minimum viable set. Many of the template’s folders sit empty until something forces them to fill.

Keep	Delete or leave empty
AGENTS.md, CLAUDE.md (symlink)	packages/, apps/ (no monorepo split)
docs/CHARTER.md (a few lines is fine)	rfc/ (almost never fires at this size)
AGENTS.md (trim aggressively)	docs/architecture/ (the README is enough)
docs/adr/ (write when you make a real tradeoff)	docs/product/personas.md
docs/specs/ (one spec at a time, or none)	Per-package AGENTS.md (no packages)
docs/product/changelog.md	the adversarial-reviewer subagent (overhead at this size)
guides/reference/ (API/config docs)	Other Diátaxis buckets — fill as needed
the work-loop skill

Rule of thumb: if your README + an OpenAPI/schema file would have been enough, you’re at this profile. The template gives you ADRs and specs for when a decision or feature gets non-trivial — not as mandatory ceremony.

Profile B — Single library or app (4-10 contributors)

Most folders start carrying content.

• All of Profile A, plus:
• docs/architecture/overview.md becomes useful (one file).
• docs/specs/ typically has 1-3 active features at a time.
• guides/ grows: at least reference/ and probably one tutorials/ entry (a quickstart) and a few how-to/ recipes.
• ADRs accumulate slowly — maybe 5-15 over the project’s first year.
• rfc/ may still be unused; PRs are enough for most decisions.
• adversarial-reviewer subagent is worth using. security-reviewer and quality-engineer are worth reaching for when a PR warrants them — see the work-loop skill’s REVIEW step.

Profile C — Medium platform / engine (10-50 contributors)

This is the design target — everything in the template is in active use.

• All of Profile B, plus:
• apps/ and/or packages/ populated, each with its own AGENTS.md.
• rfc/ actively used for cross-cutting changes.
• docs/architecture/ contains an overview plus per-subsystem files.
• guides/ has substantive content in all four Diátaxis buckets.
• docs/product/roadmap.md reviewed quarterly with real stakes.
• ADRs are routine — likely 30+ in the project’s history.
• Multiple specs in flight; spec/plan/review discipline carries weight.

Multi-agent shape by profile

The mechanisms — supervisor mode, parallel reviewer dispatch, the knowledge base — are defined in their own sections above. The mapping below says which of them you actually use at each profile, so a template adopter knows when to wire each one up.

• Profile A — sequential work-loop. Each plan task still dispatches to one implementer at a time; what rarely triggers at this size is parallel fan-out, because most plans have sequential Depends on: chains and the parallel-dispatch payoff doesn’t beat the coordination overhead. Specialist reviewers are usually skipped, and adversarial-reviewer itself is optional at this size.
• Profile B — supervisor mode runs every multi-task plan in topological order (sequential by default); its parallel-write fan-out earns its keep only when a wave of independent tasks clears the safe-category ∧ git merge-tree gate. Reviewer fan-out follows the Parallel dispatch discipline section in the work-loop skill: one tool-call message, one Agent use per reviewer, barrier-wait, merge in the orchestrator’s context.
• Profile C — same as B, plus the knowledge base is actively populated (docs/knowledge/patterns.jsonl). The session-start hook is shipped pre-wired by the install pipeline, but knowledge remains out of automatic session context; explicit --show-knowledge rendering is available for curation.

Above Profile C

If your repo is heading past ~50 active contributors with multiple teams working in parallel, the template starts to underspecify what you need. At that scale you typically need:

• A GOVERNANCE.md describing roles, decision processes, and how authority is granted.
• A formal RFC process with comment periods and final-comment-period rules (Rust’s RFC process is the reference).
• Sub-team boundaries (CNCF SIGs, Kubernetes-style).
• CODEOWNERS-driven review routing.

Adopt those when the friction of not having them exceeds the friction of adopting them — not as a precaution.

Anti-patterns at every size

• Bootstrapping at Profile C when you’re at Profile A. Empty ceremony degrades into ignored ceremony. Start at the right profile and grow into the next one when you actually need it.
• Skipping Profile A entirely because “we’ll be a platform someday.” You’ll get there faster if early decisions are recorded honestly than if they’re hidden inside a structure too big for the team to maintain.