community.md

Community Extensibility

Start Here

Most contributions touch one of two surfaces. Try these before reading the full matrix below:

1. Add guidance to an existing workflow -> drop a topic-scoped Markdown file in skills/<skill>/references/ (or shared references/). No code, no schema; just stable headings and a link/path check.
2. Add a report style -> add a directive-only templates/style/<style>.md and route it in templates/style/routing.md. Style files own visual grammar, not runnable skeletons.

Reach for the full surface matrix only when you add executable behavior (scripts, hooks), a maturity model or detector, a host adapter, or packaging.

To add a Coding Agent host, start with Contributing a New Coding Agent Host. It turns the matrix row into an evidence, implementation, cross-platform, and review workflow without making every support slice mandatory.

Extensible Surfaces

This is the complete reference. For the common cases, see Start Here above.

Surface	Extensible by community	Canonical owner	Contract required	Activation path	Validation evidence
Shared workflow	Yes	skills/<skill>/	SKILL.md frontmatter and concise workflow; optional references/ for conditional detail	Triggered by the host skill loader or packaged plugin	quick_validate.py, realistic prompt smoke, path checks
Skill detail and reusable guidance	Yes	skills/<skill>/references/ or shared references/	Topic-scoped Markdown with stable headings and source boundaries	Loaded only when the skill or agent task needs it	Link/path check; consumer grep for any 2+ consumer claim
Maturity model	Yes, additive only	models/<model>.md plus models/routing.md	Stable model_id, aliases, audience, levels, dimensions, evidence sources, scoring and confidence rules	Selectable through model routing after routing-file registration	Model-routing checks, fixture/report sample, no mutation of built-in defaults unless intentional
Detector or analysis signal	Yes	owning models/<model>.md, scripts/<business-capability>/, or skills/<skill>/references/	Detector or signal id when stable, source evidence, emitted fields, false-positive and downgrade rules	Selected through model, capability, or skill routing; shared prose needs two visible workflow consumers	Fixtures or sample evidence ledger plus behavior, report-quality, or model-routing checks
Executable analysis capability	Yes, but only with tests	scripts/<business-capability>/cli.mjs	CLI contract, JSON output shape, fixtures, scoped helpers	Called by skills, hooks, reports, or host adapters	node --test, fixture assertions, cross-platform command construction
Host evidence adapter	Yes	scripts/<capability>/platforms/<host>.mjs and docs/adapters/README.md	Matrix row with discovery paths, normalized evidence shape, smoke command, and split trigger if needed	Capability-specific host collection; not packaging	Host matrix entry, smoke command or explicit unavailable note
Lifecycle enforcement	Yes, narrowly	hooks/hooks.json.template and hooks/git-scripts/<hook>/	Hook event, mode, command contract, expected failure behavior	Installed from the template into host lifecycle points	Hook fixture/test or dry-run output; no shell-specific assumptions
Reporting template family	Yes, with routing and runtime tests	templates/reporting/	report-structure.md owns Markdown structure; mode files own metadata, companion rules, imports/props, and validation	Selected by report generation and output mode	Template tests, parser checks, path checks, and visual preview/smoke when relevant
Style grammar	Yes	templates/style/	Directive-only visual language; no runnable skeletons	Selected by report/style routing	Style-template tests and no copied runtime skeletons
Structured knowledge	Candidate only	knowledge-base/{official,community}/...	knowledge.md, interim schema.json, fixtures, namespace uniqueness	Docs-only until registry spec, compiler, and binding tests exist	Namespace check, schema/fixture review, migration note
Examples and operating models	Yes	case-studies/	Named example, scope, evidence boundary, non-runtime status	Reference material only unless separately bound	Link/path check; no runtime-policy claims
Host shell and packaging	Thin, or generated only after a split trigger	.claude-plugin/, .qoder-plugin/, .cursor-plugin/, .codex-plugin/, .github/plugin/, qwen-extension.json, .kimi-plugin/, the pi manifest in package.json, future lifecycle shells	Install/discovery metadata and pointers to canonical owners	Public npm package includes all seven current metadata roots; the Qoder runtime bundle includes only .qoder-plugin/, and generated host artifacts stay source-local	scripts/npm-package/ verification, or split adapter note plus target builder

Non-Extension Boundaries

Do not use community extensibility as a reason to:

• fork built-in models or templates for small preference changes;
• put product judgment inside .claude-plugin/, .qoder-plugin/, .cursor-plugin/, .codex-plugin/, future host shells, or .agents/skills/;
• activate knowledge-base/ assets without the registry, compiler, fixture, and consumer-binding gates;
• add scripts/core/ or broad umbrella modules;
• store raw transcripts, private logs, or impressionistic review commentary as durable assets;
• claim a second consumer from casual prose mentions.

Contributor Intake Matrix

Contributor says	Route first	Ask for	Reject or delay when
"Add a new workflow for agents"	skills/<skill>/	Trigger conditions, inputs, outputs, failure modes, validation prompt	It is only a one-off prompt or belongs in an existing skill reference
"Add a new maturity lens"	models/	Model id, levels, dimensions, evidence and confidence rules, index entry	It mutates built-in defaults without saying so
"Add a new detector signal"	Owning model, executable capability, or skill-local reference	Signal id, source evidence, false-positive boundary, projection target, and visible consumer	It has no evidence field, runtime or workflow owner, or consumer
"Add language/framework knowledge"	references/ first; knowledge-base/ only with schema and fixtures	Source boundary, examples, fixture expectations	It is docs-only but tries to become runtime-active
"Add host support"	new Coding Agent guide, then docs/adapters/README.md matrix row	Native host/version evidence, supported slices, discovery paths, evidence sources, smoke command, packaging status, split trigger if needed	It copies another adapter, mixes host evidence collection with package generation, or overstates partial support
"Add a script"	scripts/<business-capability>/	CLI contract, JSON shape, fixtures, tests	It is ad-hoc debugging that belongs in dev/
"Add an enforcement rule"	hooks/	Lifecycle event, expected blocking behavior, dry-run or fixture proof	A prompt reminder would be enough
"Add a report or visual mode"	templates/reporting/	Parser contract, consumer path, preview or static check	It duplicates runtime rules into the base report template
"Package this for another agent host"	Host matrix first; split adapter note and builder only after a trigger	Canonical source pointers, lifecycle evidence, and generated shell boundaries	The package would own canonical logic

Review Checklist

Before merging a community extensibility change, confirm:

• The change starts from AGENTS.md and this file, then follows the ADR owner.
• New behavior has an explicit contract and validation evidence.
• Runtime-active changes include tests or fixtures, not only prose.
• Docs-only candidates say they are not runtime-active.
• Generated or host-specific shells stay thin and point back to canonical source.
• Cross-platform commands avoid shell-specific syntax and use argv-style execution where code is involved.
• The review evidence names changed modules, activation state, risk, and any unknowns.