@agent-teams/docs-protocol-agent-teams 0.0.0

package/schemas/docs-protocol-profile/v1.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/docs-protocol-profile/v1",
+  "title": "Agent Teams Docs Protocol Profile",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "protocol", "foundationProfile", "agentWorkflow", "semanticValidatorIds"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocol": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "version"],
+      "properties": {
+        "id": { "const": "agent-teams.docs-protocol" },
+        "version": { "const": 1 }
+      }
+    },
+    "foundationProfile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "schemaVersion", "metadataSidecarPolicy"],
+      "properties": {
+        "path": { "$ref": "#/$defs/repositoryPath" },
+        "schemaVersion": { "const": 2 },
+        "metadataSidecarPolicy": { "const": "foundation-profile-v2-strict-merge" }
+      }
+    },
+    "agentWorkflow": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["skillPath"],
+      "properties": { "skillPath": { "$ref": "#/$defs/repositoryPath" } }
+    },
+    "semanticValidatorIds": {
+      "type": "array",
+      "maxItems": 256,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/lowerId" }
+    }
+  },
+  "$defs": {
+    "lowerId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-z0-9][a-z0-9._/-]*$" },
+    "repositoryPath": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^(?!.*(?:^|/)\\.{1,2}(?:/|$))[A-Za-z0-9._@-]{1,255}(?:/[A-Za-z0-9._@-]{1,255})*$" }
+  }
+}

package/schemas/docs-protocol-profile/v2.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/docs-protocol-profile/v2",
+  "title": "Agent Teams Docs Protocol Profile",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "protocol", "foundationProfile", "agentWorkflow", "semanticValidatorIds"],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "protocol": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "version"],
+      "properties": {
+        "id": { "const": "agent-teams.docs-protocol" },
+        "version": { "const": 1 }
+      }
+    },
+    "foundationProfile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "schemaVersion", "metadataSidecarPolicy"],
+      "properties": {
+        "path": { "$ref": "#/$defs/repositoryPath" },
+        "schemaVersion": { "const": 3 },
+        "metadataSidecarPolicy": { "const": "foundation-profile-v3-strict-merge" }
+      }
+    },
+    "agentWorkflow": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["skillPath"],
+      "properties": { "skillPath": { "$ref": "#/$defs/repositoryPath" } }
+    },
+    "semanticValidatorIds": {
+      "type": "array",
+      "maxItems": 256,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/lowerId" }
+    }
+  },
+  "$defs": {
+    "lowerId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-z0-9][a-z0-9._/-]*$" },
+    "repositoryPath": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^(?!.*(?:^|/)\\.{1,2}(?:/|$))[A-Za-z0-9._@-]{1,255}(?:/[A-Za-z0-9._@-]{1,255})*$" }
+  }
+}

package/schemas/docs-protocol-qualification/v2.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/docs-protocol-qualification/v2",
+  "title": "Docs Protocol consumer qualification v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "scenarios"],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "scenarios": {
+      "type": "array", "minItems": 1, "maxItems": 32,
+      "items": { "$ref": "#/$defs/scenario" }
+    }
+  },
+  "$defs": {
+    "lowerId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-z0-9][a-z0-9._/-]*$" },
+    "opaqueId": { "type": "string", "minLength": 1, "maxLength": 214, "pattern": "^[A-Za-z0-9@][A-Za-z0-9@._/-]*$" },
+    "repositoryPath": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^(?!.*(?:^|/)\\.{1,2}(?:/|$))[A-Za-z0-9._@-]{1,255}(?:/[A-Za-z0-9._@-]{1,255})*$" },
+    "jsonValue": {
+      "oneOf": [
+        { "type": "boolean" }, { "type": "null" }, { "type": "number" }, { "type": "string" },
+        { "type": "array", "maxItems": 256, "items": { "$ref": "#/$defs/jsonValue" } },
+        { "type": "object", "maxProperties": 256, "additionalProperties": { "$ref": "#/$defs/jsonValue" } }
+      ]
+    },
+    "anchor": {
+      "type": "object", "additionalProperties": false, "required": ["enforcement", "pattern"],
+      "properties": { "enforcement": { "enum": ["advisory", "required"] }, "pattern": { "type": "string", "minLength": 1, "maxLength": 1000 } }
+    },
+    "intent": {
+      "type": "object", "additionalProperties": false,
+      "required": ["id", "title", "owner", "summary"],
+      "properties": {
+        "id": { "$ref": "#/$defs/opaqueId" },
+        "title": { "type": "string", "minLength": 1, "maxLength": 240 },
+        "owner": { "$ref": "#/$defs/opaqueId" },
+        "summary": { "type": "string", "minLength": 1, "maxLength": 1000 },
+        "slug": { "type": "string", "minLength": 1, "maxLength": 160 },
+        "destination": { "$ref": "#/$defs/repositoryPath" },
+        "related": { "type": "array", "maxItems": 256, "uniqueItems": true, "items": { "$ref": "#/$defs/opaqueId" } },
+        "blockedBy": { "type": "array", "maxItems": 256, "uniqueItems": true, "items": { "$ref": "#/$defs/opaqueId" } },
+        "codeAnchors": { "type": "array", "maxItems": 256, "items": { "$ref": "#/$defs/anchor" } },
+        "metadata": { "type": "object", "maxProperties": 256, "additionalProperties": { "$ref": "#/$defs/jsonValue" } }
+      }
+    },
+    "reachability": {
+      "oneOf": [
+        { "type": "object", "additionalProperties": false, "required": ["state", "indexPath", "markdownLink"], "properties": { "state": { "const": "manual-required" }, "indexPath": { "$ref": "#/$defs/repositoryPath" }, "markdownLink": { "type": "string", "minLength": 1, "maxLength": 1024 } } },
+        { "type": "object", "additionalProperties": false, "required": ["state", "reason"], "properties": { "state": { "const": "not-required" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } } }
+      ]
+    },
+    "expected": {
+      "type": "object", "additionalProperties": false,
+      "required": ["documentPath", "metadataStorage", "reachability"],
+      "properties": {
+        "documentPath": { "$ref": "#/$defs/repositoryPath" },
+        "metadataStorage": { "const": "frontmatter" },
+        "reachability": { "$ref": "#/$defs/reachability" },
+        "goldenFile": { "$ref": "#/$defs/repositoryPath" },
+        "goldenDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+      },
+      "oneOf": [
+        { "not": { "anyOf": [{ "required": ["goldenFile"], "properties": { "goldenFile": true } }, { "required": ["goldenDigest"], "properties": { "goldenDigest": true } }] } },
+        { "required": ["goldenFile"], "properties": { "goldenFile": true }, "not": { "required": ["goldenDigest"], "properties": { "goldenDigest": true } } },
+        { "required": ["goldenDigest"], "properties": { "goldenDigest": true }, "not": { "required": ["goldenFile"], "properties": { "goldenFile": true } } }
+      ]
+    },
+    "scenario": {
+      "type": "object", "additionalProperties": false, "required": ["id", "type", "intent", "expected"],
+      "properties": {
+        "id": { "$ref": "#/$defs/lowerId" },
+        "type": { "$ref": "#/$defs/lowerId" },
+        "intent": { "$ref": "#/$defs/intent" },
+        "expected": { "$ref": "#/$defs/expected" }
+      }
+    }
+  }
+}

package/schemas/docs-protocol-qualification-receipt/v2.schema.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/docs-protocol-qualification-receipt/v2",
+  "title": "Docs Protocol qualification receipt v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "receiptDigest", "cohortAdmissible", "evidenceClass", "projectId", "scenarios", "checks", "derived", "evidence"],
+  "allOf": [
+    {
+      "if": { "properties": { "evidenceClass": { "const": "local-development" } }, "required": ["evidenceClass"] },
+      "then": { "properties": { "cohortAdmissible": { "const": false } } }
+    },
+    {
+      "if": { "properties": { "evidenceClass": { "const": "released-cohort" } }, "required": ["evidenceClass"] },
+      "then": { "properties": { "cohortAdmissible": { "const": true } } }
+    }
+  ],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "receiptDigest": { "$ref": "#/$defs/digest" },
+    "cohortAdmissible": { "type": "boolean" },
+    "evidenceClass": { "enum": ["local-development", "released-cohort"] },
+    "projectId": { "$ref": "#/$defs/lowerId" },
+    "scenarios": {
+      "type": "array", "minItems": 1, "maxItems": 32,
+      "items": {
+        "type": "object", "additionalProperties": false,
+        "required": ["id", "type", "documentPath", "outputDigest"],
+        "properties": {
+          "id": { "$ref": "#/$defs/lowerId" },
+          "type": { "$ref": "#/$defs/lowerId" },
+          "documentPath": { "$ref": "#/$defs/repositoryPath" },
+          "outputDigest": { "$ref": "#/$defs/digest" }
+        }
+      }
+    },
+    "checks": { "$ref": "#/$defs/checks" },
+    "derived": {
+      "type": "object", "additionalProperties": false,
+      "required": ["contractPath", "gateCommand", "packageVersions", "profilePath"],
+      "properties": {
+        "contractPath": { "$ref": "#/$defs/repositoryPath" },
+        "gateCommand": { "const": "pnpm docs:protocol:check" },
+        "packageVersions": {
+          "type": "object", "additionalProperties": false,
+          "required": ["docsProtocol", "engineeringFoundation"],
+          "properties": {
+            "docsProtocol": { "$ref": "#/$defs/version" },
+            "engineeringFoundation": { "$ref": "#/$defs/version" }
+          }
+        },
+        "profilePath": { "$ref": "#/$defs/repositoryPath" }
+      }
+    },
+    "evidence": {
+      "type": "object", "additionalProperties": false,
+      "required": ["sourceDigest", "integration", "contract", "profile", "skill", "packageManifestDigest", "lockfileDigest", "executingDocsProtocol", "executingFoundation", "cohort"],
+      "properties": {
+        "sourceDigest": { "$ref": "#/$defs/digest" },
+        "integration": { "$ref": "#/$defs/pathEvidence" },
+        "contract": { "$ref": "#/$defs/pathEvidence" },
+        "profile": { "$ref": "#/$defs/pathEvidence" },
+        "skill": { "$ref": "#/$defs/pathEvidence" },
+        "packageManifestDigest": { "$ref": "#/$defs/digest" },
+        "lockfileDigest": { "$ref": "#/$defs/digest" },
+        "executingDocsProtocol": {
+          "type": "object", "additionalProperties": false,
+          "required": ["version", "buildDigest"],
+          "properties": { "version": { "$ref": "#/$defs/version" }, "buildDigest": { "$ref": "#/$defs/digest" } }
+        },
+        "executingFoundation": {
+          "type": "object", "additionalProperties": false,
+          "required": ["version", "buildIdentity"],
+          "properties": { "version": { "$ref": "#/$defs/version" }, "buildIdentity": { "$ref": "#/$defs/digest" } }
+        },
+        "cohort": { "$ref": "https://agent-teams.ai/schemas/docs-consumer-integration-profile/v2#/$defs/cohortBinding" }
+      }
+    }
+  },
+  "$defs": {
+    "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "lowerId": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[a-z0-9][a-z0-9._/-]*$" },
+    "repositoryPath": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^(?!.*(?:^|/)\\.{1,2}(?:/|$))[A-Za-z0-9._@-]{1,255}(?:/[A-Za-z0-9._@-]{1,255})*$" },
+    "version": { "type": "string", "minLength": 1, "maxLength": 100 },
+    "pathEvidence": {
+      "type": "object", "additionalProperties": false,
+      "required": ["path", "digest"],
+      "properties": { "path": { "$ref": "#/$defs/repositoryPath" }, "digest": { "$ref": "#/$defs/digest" } }
+    },
+    "checks": {
+      "oneOf": [
+        {
+          "type": "array", "minItems": 10, "maxItems": 10,
+          "prefixItems": [
+            { "const": "info" }, { "const": "find" }, { "const": "check" }, { "const": "doctor" },
+            { "const": "recover" }, { "const": "preview" }, { "const": "apply" }, { "const": "path" },
+            { "const": "reachability" }, { "const": "source-unchanged" }
+          ],
+          "items": false
+        },
+        {
+          "type": "array", "minItems": 11, "maxItems": 11,
+          "prefixItems": [
+            { "const": "info" }, { "const": "find" }, { "const": "check" }, { "const": "doctor" },
+            { "const": "recover" }, { "const": "preview" }, { "const": "apply" }, { "const": "path" },
+            { "const": "reachability" }, { "const": "golden" }, { "const": "source-unchanged" }
+          ],
+          "items": false
+        }
+      ]
+    }
+  }
+}

package/schemas/qualified-docs-cohort/v1.schema.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-teams.ai/schemas/qualified-docs-cohort/v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "cohortId", "channel", "recordDigest", "qualificationEventDigest", "lifecycleState", "eligibleAfter", "upgradeFrom", "rollbackTo", "canaryRepositoryIds", "packages", "workflow", "assets", "schemas", "runtime"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "cohortId": { "type": "string", "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$" },
+    "channel": { "enum": ["rc", "stable"] },
+    "recordDigest": { "$ref": "#/$defs/nonzeroSha256" },
+    "qualificationEventDigest": { "$ref": "#/$defs/nonzeroSha256" },
+    "lifecycleState": { "enum": ["QUALIFIED", "CANARY", "RECOMMENDED"] },
+    "eligibleAfter": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$" },
+    "upgradeFrom": { "$ref": "#/$defs/cohortIds" },
+    "rollbackTo": { "$ref": "#/$defs/cohortIds" },
+    "canaryRepositoryIds": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 32,
+      "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^[1-9][0-9]*$" }
+    },
+    "packages": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["docsProtocol", "engineeringFoundation"],
+      "properties": {
+        "docsProtocol": { "$ref": "#/$defs/package" },
+        "engineeringFoundation": { "$ref": "#/$defs/package" }
+      }
+    },
+    "workflow": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["repository", "path", "revision", "blobSha"],
+      "properties": {
+        "repository": { "const": "agent-teams-ai/.github" },
+        "path": { "const": ".github/workflows/docs-protocol-check.yml" },
+        "revision": { "$ref": "#/$defs/nonzeroSha" },
+        "blobSha": { "$ref": "#/$defs/nonzeroSha" }
+      }
+    },
+    "assets": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["skillDigest", "callerWorkflowDigest", "assetCatalogDigest", "transitionCatalogDigest"],
+      "properties": {
+        "skillDigest": { "$ref": "#/$defs/sha256" },
+        "callerWorkflowDigest": { "$ref": "#/$defs/sha256" },
+        "assetCatalogDigest": { "$ref": "#/$defs/sha256" },
+        "transitionCatalogDigest": { "$ref": "#/$defs/sha256" }
+      }
+    },
+    "schemas": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["consumerIntegration", "managedState", "docsProtocol"],
+      "properties": {
+        "consumerIntegration": { "const": 1 },
+        "managedState": { "const": 1 },
+        "docsProtocol": { "const": 1 }
+      }
+    },
+    "runtime": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["node", "pnpm", "runtimeClosureDigest"],
+      "properties": {
+        "node": { "const": ">=24.18.0 <25" },
+        "pnpm": { "const": ">=11.17.0 <12" },
+        "runtimeClosureDigest": { "$ref": "#/$defs/nonzeroSha256" }
+      }
+    }
+  },
+  "$defs": {
+    "nonzeroSha": { "type": "string", "pattern": "^(?!0{40}$)[0-9a-f]{40}$" },
+    "sha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "nonzeroSha256": { "type": "string", "pattern": "^sha256:(?!0{64}$)[0-9a-f]{64}$" },
+    "cohortIds": {
+      "type": "array",
+      "maxItems": 32,
+      "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$" }
+    },
+    "package": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "integrity"],
+      "properties": {
+        "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(?:-[0-9A-Za-z.-]+)?$" },
+        "integrity": { "type": "string", "pattern": "^sha512-[A-Za-z0-9+/]{86}==$" }
+      }
+    }
+  }
+}

package/skills/docs/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: docs-authoring
+description: Use when creating, changing, reorganizing, or reviewing governed documentation in this repository.
+---
+
+# Documentation Authoring
+
+Protocol: `agent-teams.docs-protocol/v1`.
+
+## Required workflow
+
+- Read the current types, owners, placement, metadata, and index policy with `pnpm docs:info`.
+- Search first with `pnpm docs:find -- --text query`.
+- Reuse or relate existing authority instead of creating a competing source.
+- Preview with `pnpm docs:new -- --type TYPE --id ID --title TITLE --owner OWNER --summary SUMMARY --dry-run`.
+- Review the exact destination, metadata, relations, anchors, and diagnostics.
+- Apply with `pnpm docs:new -- --type TYPE --id ID --title TITLE --owner OWNER --summary SUMMARY --apply` after review.
+- Manually update the reported index/link exactly when reachability requires it.
+- For edits, preserve canonical frontmatter and sidecar ownership; use the repository's governed review flow rather than bypassing the create-only writer.
+- For accepted authority, record supersession explicitly instead of silently rewriting history.
+- Finish with the full consumer gate `pnpm docs:protocol:check` after the index is current.
+
+## Rules
+- Never invent owners, types, statuses, paths, or metadata outside `docs:info`.
+- If dependencies are absent, use only `pnpm install --frozen-lockfile`; never use npx, dlx, or latest tags.
+- Keep preview and apply inputs identical.
+- Stop when recovery is required; use `pnpm docs:doctor` before `pnpm docs:recover`.
+- Resolve required anchors and blockers before apply.
+- Do not bypass repository scripts or hand-edit transaction evidence.