Add agentic persona standard, manifest schema, and template scaffold#670
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. |
📝 WalkthroughWalkthroughThis PR adds standards for defining, validating, onboarding, evaluating, and promoting agentic personas. It introduces a strict persona manifest schema, a reusable YAML and README scaffold, and starter development and held-out evaluation cases. ChangesPersona standardization
Estimated code review effort: 3 (Moderate) | ~20 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.
Dev-Lead — waiting on PR blockers (intent: fix-reviews)PR: #670 |
Superseded by automated re-review at
|
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 |
donpetry-bot
left a comment
donpetry-bot
left a comment
There was a problem hiding this comment.
Automated review — APPROVED ✓
Risk: LOW
Reviewed commit: 4f59b7ff1c8ab8f4df576b310c403e73abacfb7b
Review mode: triage-approved (single reviewer)
Summary
Adds an org-wide agentic persona standard: persona-standards.md (Definition of Done), a Draft 2020-12 manifest schema (persona.schema.json), and a copy-me TEMPLATE scaffold. 7 files, 738 additions, all new — markdown docs, one JSON schema, one template YAML, two 1-line JSONL eval stubs. No executable code, workflows, or CI logic touched. Both post-triage commits address bot-review feedback (kebab-case placeholders, YAML-safe commented examples, schema conditionals for framework-agent/stable/empty-label cases, corrected template layer homes).
Linked issue analysis
No linked issues (closingIssuesReferences is empty). The PR body and a comment point to discussion #1175 in .github-private as the driving context; the companion worked example (Murat) lands in a separate PR. Nothing to verify against an issue.
Findings
- No blocking findings. Content is documentation + declarative schema/template only.
- The schema enforces the safety posture the standard documents:
mode: writerequiresgate_label;kind: framework-agentrequires theframeworkprovenance block;status: stablerequires anevalsblock;default_modeis restricted toadvisory/off. Conditionals verified present in the head diff. - One review thread (gemini-code-assist, persona.schema.json, medium) still shows unresolved in the UI, but the requested
allOf/if/thenconstraint is verifiably present atlayers.itemsin the head commit and the author replied pointing at the fix commit (3c3332d). Housekeeping only — please toggle it resolved. - Prior cycle-1 review (at a12ac78) listed no specific findings; its tasks (address bot threads, keep CI green) are satisfied at this head.
- Branch is BEHIND main but MERGEABLE; all files are new so no conflict risk. Update the branch before merge if branch protection requires it.
- Secret-scanning MCP tool unavailable in this run; gitleaks CI check passed (SUCCESS).
CI status
All checks green: Lint, ShellCheck, CodeQL, Analyze (actions), Agent Security Scan, AgentShield, Secret scan (gitleaks), npm audit, SonarCloud (quality gate passed), CodeRabbit, dev-lead dispatch, pr-auto-review. Skipped: ecosystem audits not applicable (pip/cargo/go/pnpm), dependabot-automerge, ci-relay.
Reviewed automatically by the PR-review agent (single-reviewer mode: fable 5). Reply if you need a human review.
|
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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/personas/TEMPLATE/README.md`:
- Line 36: Update the “Copy & rename” onboarding instructions in the TEMPLATE
README to use a PERSONA_ID variable, create the destination with mkdir -p, and
quote the source and variable-based destination paths so the command is directly
executable. Retain the instruction to add a short README.md alongside the copied
persona file.
🪄 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: decfabb0-6104-44ec-9d81-c8452449d428
📒 Files selected for processing (2)
standards/personas/TEMPLATE/README.mdstandards/personas/persona.schema.json
|
@coderabbitai resolve |
Dev-Lead — fix-bot-comment (no-changes)Agent reasoning |
✅ Action performedComments resolved and changes approved. |
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