feat: implement issue #1405 — [Phase 2] Add the "How to add an agentic role" runbook and a PR-template interaction-contract section - #1421
Conversation
…c role" runbook and a PR-template interaction-contract section
🤖 CodeAnt AI — Review Status
|
|
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: 48 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 Plus Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughThe PR adds an agentic-role runbook, links it from the interaction model, and updates the pull request template with interaction-contract and validation prompts. ChangesAgentic role contribution guidance
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related issues
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 |
codeant-ai
Bot
added
the
size:L
PR Summary by QodoAdd agentic-role runbook and PR template interaction-contract checklist
AI Description
Diagram
High-Level Assessment
Files changed (3)
|
Dev-Lead — review-changes (no-changes)No changes were needed for this PR. |
|
Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-08-02T03:57:42Z. |
![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 a new runbook docs/adding-an-agentic-role.md detailing the step-by-step process for adding an agentic role, updates docs/agentic-interaction-model.md to link to this runbook, and adds a pull request template containing an interaction contract checklist. The review feedback highlights two minor issues in the new runbook: a broken Markdown anchor link caused by an em-dash, and a reference to a non-existent dev-lead persona interaction file that should be replaced with a generic placeholder.
Code Review by Qodo
Context used✅ Compliance rules (platform):
48 rules 1.
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
![graphite-app[bot]](https://avatars.githubusercontent.com/in/158384?s=60&v=4){kind=small}
donpetry-bot
left a comment
donpetry-bot
left a comment
There was a problem hiding this comment.
Automated review — APPROVED ✓
Risk: LOW
Reviewed commit: d9592d2483553e85be7f3f0caaea4191455785e3
Review mode: triage-approved (single reviewer)
Summary
Docs-only PR (3 files, +176/-0) implementing issue #1405: adds the 'How to add an agentic role' runbook (docs/adding-an-agentic-role.md), a new PR template with an interaction-contract section, and a pointer to the runbook from the interaction-model standard. No workflow, trigger, or shell-script changes. Triage assessment confirmed.
Linked issue analysis
Issue #1405 (Phase 2 of epic #1402) — all four acceptance criteria are substantively met: (1) the runbook covers trigger-class selection, contract authoring, event-vs-sanctioned-bridge choice, and the timer contract; (2) the PR template gains an Interaction contract section — verified no pre-existing template exists in .github/, so creating .github/pull_request_template.md extends rather than competes, per the dev notes; (3) enforcement is a pointer to the Story 4 validator (#1406) without duplicating its rules; (4) the change is documentation-only with no new schedule.cron or workflow trigger.
Findings
No blocking findings. Two unresolved low-priority gemini-code-assist threads were verified as false positives: (a) the §8.2 anchor '#82-file-location--decision-...' is correct — GitHub's slugger removes the em-dash and converts the two surrounding spaces to two hyphens, so gemini's three-hyphen suggestion is wrong; (b) personas/dev-lead/interaction.yml exists at the reviewed SHA (verified via the contents API), so the link is not broken. The dev-lead agent already posted a fix-reviews status=no-changes assessment for these threads. Secret scan: the run_secret_scanning MCP tool is not available in this environment; diff is markdown-only and the gitleaks CI check passed.
CI status
All checks green at the reviewed SHA: Lint, ShellCheck, CodeQL (actions + python), SonarCloud quality gate, gitleaks secret scan, Agent Security Scan, agent-shield, holdout-guard, unit-tests, and workflow compilation all SUCCESS. CANCELLED/SKIPPED entries are superseded dev-lead dispatch/ci-relay runs and inapplicable dependency-audit jobs, not failures.
Reviewed automatically by the PR-review agent (single-reviewer mode: fable 5). Reply if you need a human review.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Dev-Lead — fix-reviews (applied)Changes committed and pushed. |
a708afe
Dev-Lead — review-changes (applied)Changes committed and pushed. |
|
CI checks on this PR are still running. Once they complete, re-mention Posted by the donpetry-bot PR-review cascade. |
|
Note @don-petry I reviewed this PR and no code changes were needed, but it still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews), so I cannot mark it done yet. I'll re-check automatically. |
Dev-Lead — waiting on PR blockers (intent: review-changes)PR: #1421 |
|
Note @don-petry I reviewed this PR and no code changes were needed, but it still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews), so I cannot mark it done yet. I'll re-check automatically. |
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 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 @.github/pull_request_template.md:
- Around line 28-30: Update the machine-readable interaction contract checklist
in the pull request template to require every applicable contract lens,
including both the persona manifest and deployed workflow when a role has both.
Replace the “or” wording with explicit independent requirements while retaining
the listed required contract fields.
In `@docs/adding-an-agentic-role.md`:
- Around line 124-134: Update the timer requirements in
docs/adding-an-agentic-role.md at lines 124-134 so role and event_fast_path are
explicitly required only for Class 2, while Class 3 may validly omit timer_role
and use event_fast_path: null without being considered a leak. Update the timer
checklist in .github/pull_request_template.md at lines 34-36 to apply these
checks conditionally based on the trigger class.
- Around line 42-48: Revise the “Then add a classification row” guidance in
docs/adding-an-agentic-role.md to remove the claim that missing §4 rows
currently fail CI. Describe the bidirectional completeness check as planned for
Story 4/validate-interaction-model, while preserving the instructions for adding
exactly one row or an exclusion-list entry.
- Around line 96-115: The GITHUB_TOKEN event-boundary guidance incorrectly
treats repository_dispatch as requiring a PAT. Update the relevant section
around Bridge A and the surrounding suppression wording to acknowledge
repository_dispatch and workflow_dispatch as permitted exceptions, and only
require a PAT when an explicit repository identity policy mandates it; preserve
the remaining bridge and timer guidance.
🪄 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 Plus
Run ID: cedf66d9-8932-4567-a5eb-31e99ecf0862
📒 Files selected for processing (3)
.github/pull_request_template.mddocs/adding-an-agentic-role.mddocs/agentic-interaction-model.md
Superseded by automated re-review at
|
|
Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-08-02T06:43:44Z. |
Dev-Lead — fix-reviews (applied)Changes committed and pushed. |
Auto-dismissed (#617): coderabbitai[bot] CHANGES_REQUESTED on a superseded commit. The bot re-reviews the new head automatically — a valid concern will return as a fresh review.
|
Dev-Lead — waiting on PR blockers (intent: review-changes)PR: #1421 |
|
Note @don-petry I reviewed this PR and no code changes were needed, but it still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews), so I cannot mark it done yet. I'll re-check automatically. |
|
@donpetry-bot review Re-requesting: the runbook contradiction Graphite raised is fixed in Current state: 0 unresolved threads, no genuine check failures, Human-initiated ( |
|
@don-petry I'm on it — starting a fresh review now. Results will appear in a few minutes. |
donpetry-bot
left a comment
donpetry-bot
left a comment
There was a problem hiding this comment.
Automated review — APPROVED ✓
Risk: LOW
Reviewed commit: a7b021719ea9a2d9066939bc1cf6129608facdda
Review mode: triage-approved (single reviewer)
Summary
Docs-only PR (3 markdown files, +208/-0) implementing #1405: an 'adding an agentic role' runbook, an interaction-contract section in the PR template, and a link from the interaction-model standard. Triage cleared it as low-risk and this confirmation review agrees. The fix commit a7b0217 resolves all 4 findings from the prior cycle-1 review at d1063f6 (the Step-1 enforcement contradiction, the overbroad GITHUB_TOKEN guidance, the event_fast_path null-is-leak scoping, and the template lens wording). All 9 review threads are resolved, CodeRabbit's latest review is APPROVED, and all quality CI checks are green.
Linked issue analysis
Issue #1405 acceptance criteria: (1) runbook exists at docs/adding-an-agentic-role.md covering trigger-class choice, contract authoring, event-vs-bridge, and timer contract — met; (2) PR template gains an Interaction contract section — met (.github/pull_request_template.md); (3) runbook references Story 4 / #1406 CI enforcement without duplicating validator rules — met (Enforcement section); (4) documentation-only, no new schedule.cron or workflow trigger — met (diff touches only 3 markdown files).
Findings
- Prior finding (major, Step 1 contradiction): RESOLVED — the §4-row completeness check is now described as planned for Story 4 / #1406, not currently enforced, consistent with the Enforcement section.
- Prior finding (minor, GITHUB_TOKEN boundary overbroad): RESOLVED — repository_dispatch and workflow_dispatch are now documented as permitted exceptions; the PAT requirement for Bridge A is correctly attributed to the repo identity policy rather than a platform restriction.
- Prior finding (minor, event_fast_path null-is-leak): RESOLVED — the null-marks-a-leak rule is now scoped to Class 2 only; Class 3 explicitly omits or nulls it without being a leak.
- Prior finding (minor, template 'or' understates requirement): RESOLVED — template now reads 'every applicable lens (…and/or…); include both when both lenses apply', matching the runbook.
- No new issues introduced by the fix commit; the delta touches only the runbook and the PR template.
- Review threads: all 9 threads (gemini, qodo, graphite-app, coderabbitai, don-petry) are resolved; CodeRabbit's prior CHANGES_REQUESTED was superseded by an APPROVED review.
- MCP run_secret_scanning tool was not available in this environment; skipped per instructions. Docs-only diff contains no credentials and the gitleaks CI check passed.
CI status
All quality checks green at a7b0217: Lint, ShellCheck, unit-tests, CodeQL (actions + python), SonarCloud (quality gate passed, 0 issues), gitleaks secret scan, AgentShield, Agent Security Scan, holdout-guard, Compile agentic workflows, dependency-audit (ecosystem detection SUCCESS, per-ecosystem audits skipped — no matching manifests). The CANCELLED entries (review/review, dev-lead/dispatch, dev-lead/ci-relay) are the review-cascade and dev-lead automation runs superseded by newer pushes or [skip ci-relay], not code-quality checks.
Reviewed automatically by the PR-review agent (single-reviewer mode: fable 5). Reply if you need a human review.
|
Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-08-02T06:49:36Z. |
2 participants
User description
Closes #1405
Implemented by dev-lead agent. Please review.
CodeAnt-AI Description
Add a runbook and required pull request guidance for agentic roles
What Changed
Impact
✅ Clearer agentic-role contribution requirements✅ Fewer invalid workflow configurations✅ Safer timer and self-trigger behavior💡 Usage Guide
Checking Your Pull Request
Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.
Talking to CodeAnt AI
Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:
This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.
Example
Preserve Org Learnings with CodeAnt
You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:
This helps CodeAnt AI learn and adapt to your team's coding style and standards.
Example
Retrigger review
Ask CodeAnt AI to review the PR again, by typing:
Check Your Repository Health
To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.
Summary by CodeRabbit