{
  "schemaVersion": "1.0",
  "title": "Contributing to AIP",
  "description": "Use this guide to prepare a focused AIP code or documentation change whose implementation, tests, schemas, documentation, and evidence agree. A change is ready for review only when its claims are no broader than the exact artifacts and chec",
  "canonical": "https://getaip.org/docs/project/contributing",
  "route": "/docs/project/contributing",
  "source": "CONTRIBUTING.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Project and Releases",
  "documentType": "Project policy",
  "language": "en",
  "revision": {
    "lastReviewedRevision": "d7cce13d1d555644d04a4d73c66c95b113737635",
    "documentationSourceRevision": "9192fef3695ad294994f2712f6d156241e5e92fb",
    "basis": "frontmatter"
  },
  "downloads": {
    "md": "/docs/download/project/contributing.md",
    "txt": "/docs/download/project/contributing.txt",
    "json": "/docs/download/project/contributing.json",
    "pdf": "/docs/download/project/contributing.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Contributing to AIP\ndescription: Scope, validate, document, and submit an AIP change against the real code and evidence boundaries\nkind: policy\naudience: contributor\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"d7cce13d1d555644d04a4d73c66c95b113737635\"\n---\n\n# Contributing to AIP\n\nUse this guide to prepare a focused AIP code or documentation change whose\nimplementation, tests, schemas, documentation, and evidence agree. A change is\nready for review only when its claims are no broader than the exact artifacts\nand checks supplied with it.\n\nThis guide reflects AIP Core source revision\n`d7cce13d1d555644d04a4d73c66c95b113737635` and the staged documentation v2\nworkflow. It does not define hosting rules that are absent from source.\n\n## Choose the correct repository boundary\n\nAIP Core and the documentation frontend are separate publication surfaces.\n\n| Change | Primary source boundary |\n| --- | --- |\n| Rust model, runtime, transport, profile, connector, host, CLI, schema generator, tests, or deployment code | AIP Core source repository |\n| User-facing guides, reference, architecture, qualification reports, connector documentation, or navigation | Documentation repository |\n| Behavior that changes both | Coordinated code and documentation changes, each reviewed in its owning repository |\n\nThe AIP Core publication intentionally excludes the documentation frontend and\nmost Markdown. Do not add frontend assets to the code repository or treat a\ndocumentation edit as proof that code changed.\n\nThe source-owned hosting signals are limited:\n\n- GitHub CI runs for pull requests and pushes to `main`;\n- Gitea CI runs for pull requests and pushes to `develop`;\n- `CODEOWNERS` assigns every code path to `@getaip-core`.\n\nThese files do not establish branch protection, required approval count, merge\nstrategy, issue workflow, response time, CLA, DCO, or signed-commit enforcement.\nConfirm the target branch and any hosting-only requirements with the repository\nmaintainer before opening the change.\n\n## Complete the participation checks\n\nBefore writing code or documentation:\n\n1. Read the [code of conduct](CODE_OF_CONDUCT.md).\n2. Send vulnerabilities through the private process in\n   [SECURITY.md](SECURITY.md), never through a public contribution.\n3. Review [licensing and usage terms](docs/reference/licensing.md). The root\n   Business Source License states that an intentional contribution is submitted\n   under its terms unless explicitly stated otherwise or covered by a separate\n   agreement.\n4. Confirm that you have authority to submit every source, test vector, schema,\n   example, fixture, image, and data sample in the change.\n5. Keep the implementation clean-room. Do not copy third-party implementation\n   code or documentation without an explicit provenance and license review.\n\nNever commit credentials, tokens, customer data, production identifiers,\nprivate qualification logs, local state, or generated secret files. Stop and\nuse the private security process if sensitive material entered Git history.\n\n## Classify the change before editing\n\n| Change class | Artifacts that normally move together |\n| --- | --- |\n| Documentation only | One Markdown owner page, frontmatter, navigation, local links, source ledger, and applicable examples |\n| Rust implementation | Source, public API documentation, focused tests, compatibility impact, and user-facing behavior documentation |\n| Native wire or semantic model | Rust model, validation, generated native schemas, positive and negative conformance, affected profiles, normative specification, and release impact |\n| Compatibility profile or transport | Profile DTO and mapping, transport framing, version negotiation, positive and negative interoperability tests, and profile documentation |\n| Product connector | Operation mapping, support declaration, trusted context, credentials, host wiring, deterministic tests, conformance, product docs, and exact qualification scope |\n| Deployment, persistence, or release | Configuration, migrations, least privilege, rollback and recovery, operator docs, artifacts, supply-chain evidence, and release notes |\n\nSplit a change that has unrelated outcomes. A protocol correction, connector\nfeature, dependency refresh, and prose cleanup should not share one review\nunless they form one inseparable contract change.\n\n## Preserve the architecture boundaries\n\nRead the [dependency graph](docs/architecture/dependency-graph.md) before adding\na crate edge.\n\n- Native semantic types and validation belong in `aip-core`; product and\n  compatibility DTOs do not.\n- Runtime owns lifecycle, durable state, policy enforcement, recovery, and\n  operational queries.\n- Profiles translate external protocols without redefining native AIP\n  semantics.\n- Connectors translate product behavior and expose only implemented,\n  support-declared operations.\n- Transports frame and carry messages; authenticated gateway and runtime\n  boundaries make authorization decisions.\n- Product-neutral `getaip-server` and fleet infrastructure must not depend on a product\n  connector.\n- Each public product host owns exactly one of Cal.diy, Hermes Agent, Chatwoot,\n  Dify, CrewAI, or Twenty.\n- Credentials remain host-owned and never enter protocol envelopes, generated\n  schemas, logs, or review examples.\n\nSource-owned boundary checks reject product leakage into the core daemon,\ninvalid facade features, and inconsistent private-SDK or connector-repository\nclosures.\n\n## Follow a focused development workflow\n\n1. Record the exact starting revision and verify that unrelated local changes\n   will remain untouched.\n2. Write a one-sentence reader or operator outcome and list the affected\n   architecture, compatibility, security, storage, and deployment boundaries.\n3. Create a focused branch from the confirmed target branch.\n4. Add the smallest failing test or validation that demonstrates the intended\n   behavior, then implement the change.\n5. Run focused formatting, lint, and tests while iterating.\n6. Update every owned schema, compatibility mapping, guide, reference page,\n   and release-facing record required by the change class.\n7. Run the applicable complete gates and prepare exact review evidence.\n\nUse English for source, public APIs, comments, schema descriptions,\ndocumentation, and commit-facing engineering text. Keep commits reviewable and\nexclude generated runtime artifacts and unrelated formatting.\n\n## Keep generated schemas source-owned\n\nNever edit a file under `schemas/aip` as the only implementation of a semantic\nchange. Update the Rust model and validation, then run the source generator:\n\n```sh\ncargo run -p xtask -- schema\ngit diff --exit-code -- schemas/aip\n```\n\nThe second command must be clean after committing the intended generated\nchanges. Add positive and negative conformance coverage and update the\n[AIP 1.0 specification](docs/spec/AIP-1.0.md) when the contract changes.\n\nBackward-incompatible behavior requires an explicit versioning decision. Do\nnot silently change a stable message family while leaving its version and\nschemas unchanged.\n\n## Apply the connector contract\n\nConnector changes must preserve the callable boundary described by the\n[connector contract](docs/spec/connector-contract.md):\n\n- consume trusted server-created execution context;\n- declare only behavior implemented by the connector;\n- keep credential material redacted and outside serializable protocol data;\n- define approval, idempotency, retry, cancellation, transaction, and\n  reconciliation behavior accurately;\n- return typed, redacted failures and retain uncertain-outcome evidence;\n- keep provider DTOs and paths inside the product connector;\n- update standalone host construction and admission evidence when support\n  changes.\n\nFollow [Build a connector](docs/guides/build-a-connector.md) for a new public\nintegration. Deterministic tests prove mappings and failure behavior; they do\nnot prove a live product deployment. Live claims require the exact source,\nimage, configuration, provider revision, time, and retained result defined by\nthe [testing and qualification index](docs/testing/README.md).\n\n## Select the applicable validation level\n\nRun a narrow check first. For a Rust package, substitute its exact Cargo package\nname:\n\n```sh\nPACKAGE=\"aip-core\"\ncargo fmt --all --check\ncargo test -p \"${PACKAGE}\" --all-features\ncargo clippy -p \"${PACKAGE}\" --all-targets --all-features -- -D warnings\n```\n\nThen choose every broader gate affected by the change.\n\n| Boundary | Source-owned gate or evidence |\n| --- | --- |\n| Generated native schemas | `cargo run -p xtask -- schema` plus a clean `schemas/aip` diff |\n| Core and connector repository separation | `xtask` daemon and private-SDK boundary checks |\n| Release-affecting source | `tools/release/check-release-artifacts.sh` |\n| Minimum Rust version | CI check with Rust `1.88.0` |\n| Native NATS | Dedicated NATS workflow job |\n| PostgreSQL runtime, registry, least privilege, and scale | Dedicated PostgreSQL workflow job and retained scale result |\n| CrewAI sidecar | Frozen Python environment, Ruff, and sidecar tests |\n| Fleet images and failures | Migration-image, failure-matrix, and product-image qualification procedures |\n| macOS portability | Selected protocol crates on the macOS workflow runner |\n| Complete history secrets | Immutable Gitleaks workflow image with redacted output |\n| Live external product | Product-specific isolated campaign and retained evidence |\n\nThe release script is broad. It runs publication hygiene, formatting,\narchitecture and repository boundaries, applicable semantic-version checks,\nschema generation, Clippy, all-feature Nextest, no-default tests, dependency\npolicy, vulnerability audit, unused-dependency detection, fuzz compilation, and\nRust documentation.\n\nDo not report a gate as passed unless it ran successfully against the exact\nreview commit. A skipped opt-in test, a workflow definition, or an older run is\nnot current evidence.\n\n## Author documentation sequentially\n\nDocumentation follows the mandatory\n[AIP documentation writing standard](AIP-DOCUMENTATION-WRITING-STANDARD.md).\nOnly one public Markdown document is active at a time. It must move through\nsource audit, outline, complete draft, technical review, editorial review,\nformal validation, and acceptance before the next page starts.\n\nDocumentation changes must:\n\n- cite exact code, schema, manifest, or retained evidence in the acceptance\n  record;\n- use one reader outcome and one canonical owner for each fact;\n- distinguish normative, implemented, conformant, qualified, live, historical,\n  planned, and excluded claims;\n- keep examples fictional, safe, complete, and free of credentials or private\n  identifiers;\n- preserve navigation order and resolve every local link;\n- use only the six maintained public connectors;\n- avoid publishing internal design-process and controlled-validation material.\n\nThe staged v2 Markdown tree is not an input to the current frontend build\nscripts. A passing frontend build therefore does not validate v2 content yet.\nRetain the writing-standard checks and cross-link evidence until the staged\ntree is wired into the site pipeline and its build becomes an additional gate.\n\nRelease-facing changes update `CHANGELOG` during release preparation. Do not\ninvent a released version or date for an untagged source revision.\n\n## Prepare the review evidence\n\nUse a compact summary with no unsupported claim:\n\n```text\nProblem and outcome:\nExact source revision:\nFiles and architecture boundaries:\nProtocol and API compatibility:\nSecurity and tenant isolation:\nStorage, migration, recovery, and rollback:\nCommands and tests run:\nRetained evidence and artifact digests:\nDocumentation and generated schemas:\nKnown gaps, skipped cases, and non-claims:\n```\n\nReviewers need the actual terminal state and artifact identity, not only a\ncommand list. Redact secrets and customer data before attaching logs. Keep raw\nqualification evidence in its protected retention boundary and publish only\nthe reviewed redacted record.\n\n## Check merge readiness\n\nA contribution is ready for owner review when:\n\n- the stated outcome is implemented without unrelated changes;\n- architecture, product-neutrality, tenant, credential, and generated-source\n  boundaries remain intact;\n- every applicable focused and complete gate has exact evidence;\n- schema, specification, compatibility, documentation, and release records\n  agree with code;\n- migrations have verification, rollback, and uncertain-outcome handling;\n- external-product and performance claims cite their exact retained campaigns;\n- local links and navigation resolve and no internal-only material is exposed;\n- remaining risks, skipped checks, and intentionally unsupported behavior are\n  explicit.\n\n`CODEOWNERS` routes source review to `@getaip-core`; it does not replace the\ntechnical, editorial, security, release, or evidence review required by the\nchange.\n\n## Related documentation\n\n- [Documentation home](docs/README.md)\n- [AIP 1.0 specification](docs/spec/AIP-1.0.md)\n- [Documentation writing standard](AIP-DOCUMENTATION-WRITING-STANDARD.md)\n- [Code of conduct](CODE_OF_CONDUCT.md)\n- [Security policy](SECURITY.md)\n",
    "text": "Contributing to AIP\n\nUse this guide to prepare a focused AIP code or documentation change whose\nimplementation, tests, schemas, documentation, and evidence agree. A change is\nready for review only when its claims are no broader than the exact artifacts\nand checks supplied with it.\n\nThis guide reflects AIP Core source revision\nd7cce13d1d555644d04a4d73c66c95b113737635 and the staged documentation v2\nworkflow. It does not define hosting rules that are absent from source.\n\nChoose the correct repository boundary\n\nAIP Core and the documentation frontend are separate publication surfaces.\n\n| Change | Primary source boundary |\n\n| Rust model, runtime, transport, profile, connector, host, CLI, schema generator, tests, or deployment code | AIP Core source repository |\n| User-facing guides, reference, architecture, qualification reports, connector documentation, or navigation | Documentation repository |\n| Behavior that changes both | Coordinated code and documentation changes, each reviewed in its owning repository |\n\nThe AIP Core publication intentionally excludes the documentation frontend and\nmost Markdown. Do not add frontend assets to the code repository or treat a\ndocumentation edit as proof that code changed.\n\nThe source-owned hosting signals are limited:\n• GitHub CI runs for pull requests and pushes to main;\n• Gitea CI runs for pull requests and pushes to develop;\n• CODEOWNERS assigns every code path to @getaip-core.\n\nThese files do not establish branch protection, required approval count, merge\nstrategy, issue workflow, response time, CLA, DCO, or signed-commit enforcement.\nConfirm the target branch and any hosting-only requirements with the repository\nmaintainer before opening the change.\n\nComplete the participation checks\n\nBefore writing code or documentation:\n1. Read the code of conduct (CODEOFCONDUCT.md).\n2. Send vulnerabilities through the private process in\n   SECURITY.md (SECURITY.md), never through a public contribution.\n3. Review licensing and usage terms (docs/reference/licensing.md). The root\n   Business Source License states that an intentional contribution is submitted\n   under its terms unless explicitly stated otherwise or covered by a separate\n   agreement.\n4. Confirm that you have authority to submit every source, test vector, schema,\n   example, fixture, image, and data sample in the change.\n5. Keep the implementation clean-room. Do not copy third-party implementation\n   code or documentation without an explicit provenance and license review.\n\nNever commit credentials, tokens, customer data, production identifiers,\nprivate qualification logs, local state, or generated secret files. Stop and\nuse the private security process if sensitive material entered Git history.\n\nClassify the change before editing\n\n| Change class | Artifacts that normally move together |\n\n| Documentation only | One Markdown owner page, frontmatter, navigation, local links, source ledger, and applicable examples |\n| Rust implementation | Source, public API documentation, focused tests, compatibility impact, and user-facing behavior documentation |\n| Native wire or semantic model | Rust model, validation, generated native schemas, positive and negative conformance, affected profiles, normative specification, and release impact |\n| Compatibility profile or transport | Profile DTO and mapping, transport framing, version negotiation, positive and negative interoperability tests, and profile documentation |\n| Product connector | Operation mapping, support declaration, trusted context, credentials, host wiring, deterministic tests, conformance, product docs, and exact qualification scope |\n| Deployment, persistence, or release | Configuration, migrations, least privilege, rollback and recovery, operator docs, artifacts, supply-chain evidence, and release notes |\n\nSplit a change that has unrelated outcomes. A protocol correction, connector\nfeature, dependency refresh, and prose cleanup should not share one review\nunless they form one inseparable contract change.\n\nPreserve the architecture boundaries\n\nRead the dependency graph (docs/architecture/dependency-graph.md) before adding\na crate edge.\n• Native semantic types and validation belong in aip-core; product and\n  compatibility DTOs do not.\n• Runtime owns lifecycle, durable state, policy enforcement, recovery, and\n  operational queries.\n• Profiles translate external protocols without redefining native AIP\n  semantics.\n• Connectors translate product behavior and expose only implemented,\n  support-declared operations.\n• Transports frame and carry messages; authenticated gateway and runtime\n  boundaries make authorization decisions.\n• Product-neutral getaip-server and fleet infrastructure must not depend on a product\n  connector.\n• Each public product host owns exactly one of Cal.diy, Hermes Agent, Chatwoot,\n  Dify, CrewAI, or Twenty.\n• Credentials remain host-owned and never enter protocol envelopes, generated\n  schemas, logs, or review examples.\n\nSource-owned boundary checks reject product leakage into the core daemon,\ninvalid facade features, and inconsistent private-SDK or connector-repository\nclosures.\n\nFollow a focused development workflow\n1. Record the exact starting revision and verify that unrelated local changes\n   will remain untouched.\n2. Write a one-sentence reader or operator outcome and list the affected\n   architecture, compatibility, security, storage, and deployment boundaries.\n3. Create a focused branch from the confirmed target branch.\n4. Add the smallest failing test or validation that demonstrates the intended\n   behavior, then implement the change.\n5. Run focused formatting, lint, and tests while iterating.\n6. Update every owned schema, compatibility mapping, guide, reference page,\n   and release-facing record required by the change class.\n7. Run the applicable complete gates and prepare exact review evidence.\n\nUse English for source, public APIs, comments, schema descriptions,\ndocumentation, and commit-facing engineering text. Keep commits reviewable and\nexclude generated runtime artifacts and unrelated formatting.\n\nKeep generated schemas source-owned\n\nNever edit a file under schemas/aip as the only implementation of a semantic\nchange. Update the Rust model and validation, then run the source generator:\n\ncargo run -p xtask -- schema\ngit diff --exit-code -- schemas/aip\n\nThe second command must be clean after committing the intended generated\nchanges. Add positive and negative conformance coverage and update the\nAIP 1.0 specification (docs/spec/AIP-1.0.md) when the contract changes.\n\nBackward-incompatible behavior requires an explicit versioning decision. Do\nnot silently change a stable message family while leaving its version and\nschemas unchanged.\n\nApply the connector contract\n\nConnector changes must preserve the callable boundary described by the\nconnector contract (docs/spec/connector-contract.md):\n• consume trusted server-created execution context;\n• declare only behavior implemented by the connector;\n• keep credential material redacted and outside serializable protocol data;\n• define approval, idempotency, retry, cancellation, transaction, and\n  reconciliation behavior accurately;\n• return typed, redacted failures and retain uncertain-outcome evidence;\n• keep provider DTOs and paths inside the product connector;\n• update standalone host construction and admission evidence when support\n  changes.\n\nFollow Build a connector (docs/guides/build-a-connector.md) for a new public\nintegration. Deterministic tests prove mappings and failure behavior; they do\nnot prove a live product deployment. Live claims require the exact source,\nimage, configuration, provider revision, time, and retained result defined by\nthe testing and qualification index (docs/testing/README.md).\n\nSelect the applicable validation level\n\nRun a narrow check first. For a Rust package, substitute its exact Cargo package\nname:\n\nPACKAGE=\"aip-core\"\ncargo fmt --all --check\ncargo test -p \"${PACKAGE}\" --all-features\ncargo clippy -p \"${PACKAGE}\" --all-targets --all-features -- -D warnings\n\nThen choose every broader gate affected by the change.\n\n| Boundary | Source-owned gate or evidence |\n\n| Generated native schemas | cargo run -p xtask -- schema plus a clean schemas/aip diff |\n| Core and connector repository separation | xtask daemon and private-SDK boundary checks |\n| Release-affecting source | tools/release/check-release-artifacts.sh |\n| Minimum Rust version | CI check with Rust 1.88.0 |\n| Native NATS | Dedicated NATS workflow job |\n| PostgreSQL runtime, registry, least privilege, and scale | Dedicated PostgreSQL workflow job and retained scale result |\n| CrewAI sidecar | Frozen Python environment, Ruff, and sidecar tests |\n| Fleet images and failures | Migration-image, failure-matrix, and product-image qualification procedures |\n| macOS portability | Selected protocol crates on the macOS workflow runner |\n| Complete history secrets | Immutable Gitleaks workflow image with redacted output |\n| Live external product | Product-specific isolated campaign and retained evidence |\n\nThe release script is broad. It runs publication hygiene, formatting,\narchitecture and repository boundaries, applicable semantic-version checks,\nschema generation, Clippy, all-feature Nextest, no-default tests, dependency\npolicy, vulnerability audit, unused-dependency detection, fuzz compilation, and\nRust documentation.\n\nDo not report a gate as passed unless it ran successfully against the exact\nreview commit. A skipped opt-in test, a workflow definition, or an older run is\nnot current evidence.\n\nAuthor documentation sequentially\n\nDocumentation follows the mandatory\nAIP documentation writing standard (AIP-DOCUMENTATION-WRITING-STANDARD.md).\nOnly one public Markdown document is active at a time. It must move through\nsource audit, outline, complete draft, technical review, editorial review,\nformal validation, and acceptance before the next page starts.\n\nDocumentation changes must:\n• cite exact code, schema, manifest, or retained evidence in the acceptance\n  record;\n• use one reader outcome and one canonical owner for each fact;\n• distinguish normative, implemented, conformant, qualified, live, historical,\n  planned, and excluded claims;\n• keep examples fictional, safe, complete, and free of credentials or private\n  identifiers;\n• preserve navigation order and resolve every local link;\n• use only the six maintained public connectors;\n• avoid publishing internal design-process and controlled-validation material.\n\nThe staged v2 Markdown tree is not an input to the current frontend build\nscripts. A passing frontend build therefore does not validate v2 content yet.\nRetain the writing-standard checks and cross-link evidence until the staged\ntree is wired into the site pipeline and its build becomes an additional gate.\n\nRelease-facing changes update CHANGELOG during release preparation. Do not\ninvent a released version or date for an untagged source revision.\n\nPrepare the review evidence\n\nUse a compact summary with no unsupported claim:\n\nProblem and outcome:\nExact source revision:\nFiles and architecture boundaries:\nProtocol and API compatibility:\nSecurity and tenant isolation:\nStorage, migration, recovery, and rollback:\nCommands and tests run:\nRetained evidence and artifact digests:\nDocumentation and generated schemas:\nKnown gaps, skipped cases, and non-claims:\n\nReviewers need the actual terminal state and artifact identity, not only a\ncommand list. Redact secrets and customer data before attaching logs. Keep raw\nqualification evidence in its protected retention boundary and publish only\nthe reviewed redacted record.\n\nCheck merge readiness\n\nA contribution is ready for owner review when:\n• the stated outcome is implemented without unrelated changes;\n• architecture, product-neutrality, tenant, credential, and generated-source\n  boundaries remain intact;\n• every applicable focused and complete gate has exact evidence;\n• schema, specification, compatibility, documentation, and release records\n  agree with code;\n• migrations have verification, rollback, and uncertain-outcome handling;\n• external-product and performance claims cite their exact retained campaigns;\n• local links and navigation resolve and no internal-only material is exposed;\n• remaining risks, skipped checks, and intentionally unsupported behavior are\n  explicit.\n\nCODEOWNERS routes source review to @getaip-core; it does not replace the\ntechnical, editorial, security, release, or evidence review required by the\nchange.\n\nRelated documentation\n• Documentation home (docs/README.md)\n• AIP 1.0 specification (docs/spec/AIP-1.0.md)\n• Documentation writing standard (AIP-DOCUMENTATION-WRITING-STANDARD.md)\n• Code of conduct (CODEOFCONDUCT.md)\n• Security policy (SECURITY.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "064d40e110e83fec8e3052bc7c00ab93ec2a791cf88de34870148eba091bff9a"
  }
}