Add agentic persona standard, manifest schema, and template scaffold#670
Add agentic persona standard, manifest schema, and template scaffold#670don-petry wants to merge 4 commits into
Conversation
Introduce a reusable "Persona Definition of Done" for onboarding new agentic personas across the fleet: - standards/persona-standards.md — the standard: manifest-as-index-of-record, advisory-by-default trigger matrix (write opt-in per surface with a gate label + trust floor), definition layers that unify over (not replace) the vendored frameworks, held-out eval gate before stable, and single-source-of- truth canary onboarding (register once in canary-rings.json; the "*" stable member resolves at runtime now that all repos are public). - standards/personas/persona.schema.json — Draft 2020-12 schema for persona.yml. - standards/personas/TEMPLATE/ — copy-me scaffold (manifest + README + layer stubs + a starter dev/holdout eval pair to move under evals/<id>/). Builds on agent-standards.md, ci-standards.md, and github-settings.md rather than restating them. Murat (Test Architect) is the worked example, added in the .github-private companion PR. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LJbMoZ6RmWFEAhQA56Zxc4
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Warning Review limit reached
Next review available in: 53 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughAdds standards for defining, validating, onboarding, and promoting agentic personas, including a strict manifest schema, reusable scaffold, trigger and trust controls, held-out eval requirements, and canary-ring registration rules. ChangesPersona standardization
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related PRs
Suggested labels: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Add the 'text' language to the two fenced directory-tree blocks flagged by markdownlint-cli2 (MD040/fenced-code-language) in persona-standards.md and the TEMPLATE README. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LJbMoZ6RmWFEAhQA56Zxc4
Dev-Lead — fix-bot-comment (no-changes)Agent reasoning |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@standards/persona-standards.md`:
- Line 80: Update the fenced code block around the personas/<id>/ directory
example in persona-standards.md to specify text as its language identifier,
resolving the MD040 lint failure while preserving the example content.
In `@standards/personas/TEMPLATE/README.md`:
- Line 10: Update the fenced code block in the TEMPLATE README.md to specify
text as its language, preserving the existing block contents.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 3c38583c-f3c4-4b8e-83b4-1203420de3fc
📒 Files selected for processing (9)
standards/persona-standards.mdstandards/personas/TEMPLATE/README.mdstandards/personas/TEMPLATE/agents/README.mdstandards/personas/TEMPLATE/evals/README.mdstandards/personas/TEMPLATE/evals/dev/cases.jsonlstandards/personas/TEMPLATE/evals/holdout/cases.jsonlstandards/personas/TEMPLATE/persona.ymlstandards/personas/TEMPLATE/prompts/README.mdstandards/personas/persona.schema.json
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces the Agentic Persona Standards, which establish a structured process for defining, onboarding, and rolling out agentic personas. It includes a comprehensive markdown standard, a JSON schema for validating persona manifests, and a template scaffold for new personas. The code review feedback highlights several critical validation and syntax issues: the uppercase CHANGE-ME placeholders for id and canary.agent in the template manifest violate the schema's lowercase kebab-case regex constraint; the commented-out block sequences for skills and references directly below inline empty arrays will cause YAML parsing errors if uncommented; and the JSON schema lacks a conditional constraint to enforce that the framework property is required when the layer kind is framework-agent.
| "items": { | ||
| "type": "object", | ||
| "additionalProperties": false, | ||
| "required": ["kind", "path"], | ||
| "properties": { | ||
| "kind": { | ||
| "type": "string", | ||
| "enum": ["framework-agent", "copilot-profile", "workflow-prompts", "gh-aw"], | ||
| "description": "framework-agent: a vendored framework agent (BMAD etc.). copilot-profile: an agents/<name>.md profile. workflow-prompts: a prompts/<persona>/ library driven by a shell orchestrator. gh-aw: a GitHub Agentic Workflow .md compiled to a .lock.yml." | ||
| }, | ||
| "path": { | ||
| "type": "string", | ||
| "description": "Repo-relative path to the layer's root (the SKILL.md dir, the profile .md, the prompts dir, or the gh-aw .md)." | ||
| }, | ||
| "framework": { | ||
| "type": "object", | ||
| "additionalProperties": false, | ||
| "description": "Required when kind == 'framework-agent'. Records the upstream provenance and pin so the manifest can point INTO the framework rather than fork it.", | ||
| "required": ["name", "upstream_repo", "vendor_pin"], | ||
| "properties": { | ||
| "name": {"type": "string", "description": "Framework directory under frameworks/ (e.g. 'bmad-test-architecture')."}, | ||
| "upstream_repo": {"type": "string", "description": "Upstream source repo (e.g. 'bmad-code-org/bmad-method-test-architecture-enterprise')."}, | ||
| "vendor_pin": {"type": "string", "description": "Vendored version/tag, MUST match the framework's VENDOR.md (e.g. 'v1.19.0')."}, | ||
| "skill": {"type": "string", "description": "The framework skill/agent id backing this persona (e.g. 'bmad-tea')."} | ||
| } | ||
| }, | ||
| "local_overrides": { | ||
| "type": "object", | ||
| "additionalProperties": false, | ||
| "description": "Local customization applied on top of a vendored layer (never hand-edit vendored files). Overrides that would benefit upstream should be flagged for contribution back.", | ||
| "required": ["path", "upstream_candidate"], | ||
| "properties": { | ||
| "path": {"type": "string", "description": "Repo-relative path to the override file(s) (e.g. a customize.toml overlay or an orchestration wrapper)."}, | ||
| "upstream_candidate": {"type": "boolean", "description": "true if this override is a general improvement that SHOULD be proposed back to the upstream framework rather than kept local forever."}, | ||
| "notes": {"type": "string"} | ||
| } | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
The schema description for framework states that it is required when kind == 'framework-agent'. However, there is currently no schema constraint enforcing this conditional requirement. Adding an allOf conditional check with if/then will ensure the schema validates this correctly.
"items": {
"type": "object",
"additionalProperties": false,
"required": ["kind", "path"],
"properties": {
"kind": {
"type": "string",
"enum": ["framework-agent", "copilot-profile", "workflow-prompts", "gh-aw"],
"description": "framework-agent: a vendored framework agent (BMAD etc.). copilot-profile: an agents/<name>.md profile. workflow-prompts: a prompts/<persona>/ library driven by a shell orchestrator. gh-aw: a GitHub Agentic Workflow .md compiled to a .lock.yml."
},
"path": {
"type": "string",
"description": "Repo-relative path to the layer's root (the SKILL.md dir, the profile .md, the prompts dir, or the gh-aw .md)."
},
"framework": {
"type": "object",
"additionalProperties": false,
"description": "Required when kind == 'framework-agent'. Records the upstream provenance and pin so the manifest can point INTO the framework rather than fork it.",
"required": ["name", "upstream_repo", "vendor_pin"],
"properties": {
"name": {"type": "string", "description": "Framework directory under frameworks/ (e.g. 'bmad-test-architecture')."},
"upstream_repo": {"type": "string", "description": "Upstream source repo (e.g. 'bmad-code-org/bmad-method-test-architecture-enterprise')."},
"vendor_pin": {"type": "string", "description": "Vendored version/tag, MUST match the framework's VENDOR.md (e.g. 'v1.19.0')."},
"skill": {"type": "string", "description": "The framework skill/agent id backing this persona (e.g. 'bmad-tea')."}
}
},
"local_overrides": {
"type": "object",
"additionalProperties": false,
"description": "Local customization applied on top of a vendored layer (never hand-edit vendored files). Overrides that would benefit upstream should be flagged for contribution back.",
"required": ["path", "upstream_candidate"],
"properties": {
"path": {"type": "string", "description": "Repo-relative path to the override file(s) (e.g. a customize.toml overlay or an orchestration wrapper)."},
"upstream_candidate": {"type": "boolean", "description": "true if this override is a general improvement that SHOULD be proposed back to the upstream framework rather than kept local forever."},
"notes": {"type": "string"}
}
}
},
"allOf": [
{
"if": {
"properties": {
"kind": {
"const": "framework-agent"
}
}
},
"then": {
"required": ["framework"]
}
}
]
}There was a problem hiding this comment.
Fixed in commit 3c3332d: added an allOf conditional to standards/personas/persona.schema.json at the layers.items level (lines 93-98). The constraint uses if: {properties: {kind: {const: "framework-agent"}}} / then: {required: ["framework"]} so JSON Schema Draft 2020-12 validators will now enforce that framework is required whenever kind is framework-agent.
Dev-Lead — waiting on PR blockers (intent: fix-reviews)PR: #670 |
Review — fix requested (cycle 1/3)The automated review identified the following issues. Please address each one: Findings to fixAutomated review — NEEDS HUMAN REVIEWRisk: MEDIUM SummaryFindings
Reviewed by the PR-review cascade (triage: haiku 4.5 → deep: opus 4.8 + duck: o4-mini → audit: fable 5). Reply if you need a human review. Additional tasks
The review cascade will automatically re-review after new commits are pushed. |
Apply reviewer feedback on the persona template and schema: - persona.yml template: lowercase the id / canary.agent placeholders to `change-me` so they satisfy the schema's kebab-case pattern; restructure the `skills` / `references` commented examples so uncommenting can't yield invalid YAML; give the illustrative `mention` surface a concrete `events: [created]`. - persona.schema.json: add an allOf if/then that requires the `framework` block when a layer's kind is `framework-agent` (previously only stated in prose). Validated: schema is valid Draft 2020-12, the Murat manifest and the template both validate, and a framework-agent layer missing `framework` is now rejected. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LJbMoZ6RmWFEAhQA56Zxc4
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (4)
standards/personas/persona.schema.json (2)
128-130: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick winReject empty opt-out and write-gate labels.
Both fields currently accept
""; therefore awritesurface can satisfy the schema without a usable gate label, and the requiredopt_out_labelcan be effectively undefined. AddminLength: 1to both string schemas.Also applies to: 156-174
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@standards/personas/persona.schema.json` around lines 128 - 130, Add minLength: 1 to the opt_out_label and write-gate label string schemas in the persona schema, ensuring both required labels reject empty strings while preserving their existing types and descriptions.
8-8: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winRequire
evalsbeforestable.
standards/personas/persona.schema.jsonallowsstatus: stablewithout anyevalsblock, even though the schema/docs say a persona must not reachstablewithout a passing held-out eval set. Makeevalsrequired for stable manifests, or require it universally if that’s the intended contract.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@standards/personas/persona.schema.json` at line 8, Update the persona schema’s required-field rules so manifests with status stable must include the evals block, while preserving the intended requirements for other statuses. Use the existing status and evals schema definitions to enforce this condition rather than only listing evals unconditionally unless the contract requires it universally.standards/personas/TEMPLATE/README.md (2)
3-6: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winFix links after the scaffold is copied.
These relative links resolve inside
standards/personas/TEMPLATE/, but break once the README is copied into the separate.github-private/personas/<id>/repository. Use stable cross-repository links or document the destination-specific paths.Also applies to: 45-46
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@standards/personas/TEMPLATE/README.md` around lines 3 - 6, Update the README links in the TEMPLATE onboarding instructions so they remain valid after copying into .github-private/personas/<id>/, using stable cross-repository URLs or explicitly documenting the destination-specific paths for persona-standards.md and persona.schema.json.
11-17: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winPlace optional layer files in their canonical homes.
After copying, this README instructs users to keep Copilot profiles and prompt libraries under
personas/<id>/agents/andpersonas/<id>/prompts/, but the standard defines their homes as.github-private/agents/<id>.mdand.github-private/prompts/<id>/. Update the scaffold instructions to move these starter files to those paths, or revise the standard and all consumers consistently.Also applies to: 27-30
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@standards/personas/TEMPLATE/README.md` around lines 11 - 17, Update the scaffold guidance in the README template to direct optional Copilot profiles and prompt libraries to .github-private/agents/<id>.md and .github-private/prompts/<id>/ instead of persona-local agents/ and prompts/ directories. Keep the existing optional-file behavior clear and align the referenced starter layout with the canonical homes.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@standards/personas/persona.schema.json`:
- Around line 128-130: Add minLength: 1 to the opt_out_label and write-gate
label string schemas in the persona schema, ensuring both required labels reject
empty strings while preserving their existing types and descriptions.
- Line 8: Update the persona schema’s required-field rules so manifests with
status stable must include the evals block, while preserving the intended
requirements for other statuses. Use the existing status and evals schema
definitions to enforce this condition rather than only listing evals
unconditionally unless the contract requires it universally.
In `@standards/personas/TEMPLATE/README.md`:
- Around line 3-6: Update the README links in the TEMPLATE onboarding
instructions so they remain valid after copying into
.github-private/personas/<id>/, using stable cross-repository URLs or explicitly
documenting the destination-specific paths for persona-standards.md and
persona.schema.json.
- Around line 11-17: Update the scaffold guidance in the README template to
direct optional Copilot profiles and prompt libraries to
.github-private/agents/<id>.md and .github-private/prompts/<id>/ instead of
persona-local agents/ and prompts/ directories. Keep the existing optional-file
behavior clear and align the referenced starter layout with the canonical homes.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 4bbce2f4-79e6-4fc8-9050-51c1ac56a37d
📒 Files selected for processing (4)
standards/persona-standards.mdstandards/personas/TEMPLATE/README.mdstandards/personas/TEMPLATE/persona.ymlstandards/personas/persona.schema.json
Address CodeRabbit review of the persona schema and template scaffold: - persona.schema.json: reject empty opt_out_label and gate_label (minLength 1); require the evals block when status is `stable` (matches the DoD's no-stable-without-evals rule) via an allOf if/then. - TEMPLATE/README.md: use absolute cross-repo doc links (they broke once copied into .github-private); correct the layer homes — Copilot profiles and prompt libraries live at the repo-level `.github-private/agents/<id>.md` and `prompts/<id>/`, not nested under personas/<id>/. - Remove the misleading persona-local TEMPLATE/agents and TEMPLATE/prompts starter dirs; a persona instance dir is persona.yml + README.md only. Validated: schema valid Draft 2020-12; Murat and the template both validate; status:stable-without-evals and empty opt_out_label are now rejected. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LJbMoZ6RmWFEAhQA56Zxc4
|
Dev-Lead — fix-bot-comment (no-changes)Agent reasoning |
|
📌 Driving idea: the concept and need behind this work are captured in petry-projects/.github-private discussion #1175. This PR is one of its two work items (the standard + manifest schema + template); the worked example (Murat) is petry-projects/.github-private#1174. Generated by Claude Code |
3 participants
Summary
Introduces a reusable "Persona Definition of Done" — a standard, a manifest schema, and a copy-me template — for onboarding any new agentic persona (QA architect, SRE, DevOps, …) across the fleet. It extracts the pattern already implicit across dev-lead, pr-review, Bob, and the ideation agents into one explicit, lintable onboarding path.
The worked example (Murat, the Test Architect) lands in the companion PR on
petry-projects/.github-private.What's added
standards/persona-standards.md— the standard:persona.ymlper persona ties together identity, definition layer(s), skills, triggers, trust, evals, and a pointer to its canary entry. It references; it does not duplicate.default_modeis advisory; write is opt-in per surface and must carry agate_label+ trust floor.stable— reuses the existing held-outevals/discipline (validate-cases.py,holdout-guard.yml).canary-rings.json;release/registry.ymlis derived, not maintained in parallel;stable's"*"resolves at runtime (all repos are public, so there's no topology to hide).standards/personas/persona.schema.json— Draft 2020-12 schema for the manifest (validated).standards/personas/TEMPLATE/— copy-me scaffold: heavily-commentedpersona.yml, README with the onboarding order, layer-dir stubs, and a starter dev/holdout eval pair (moved toevals/<id>/on use).Design decisions baked in
canary-rings.jsonis the single hand-authored ring registry; the two-registry drift (divergentrun_workflownames + soak encodings) is eliminated by construction.evals/<id>/, not beside the manifest, so they inherit the existing validator + immutability guard rather than forking them.Verification
persona.schema.jsonis a valid Draft 2020-12 schema; the Murat manifest (companion PR) validates against it..markdownlint-cli2.yamllimits.Notes for reviewers
Builds on
agent-standards.md,ci-standards.md, andgithub-settings.md— it adds the persona-level wrapper and defers to them for agent files, stub/reusable tiers, canary mechanics, and labels.🤖 Generated with Claude Code
Generated by Claude Code
Summary by CodeRabbit
Documentation
New Standards