You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[Phase 2] Add the "How to add an agentic role" runbook and a PR-template interaction-contract section #1405
As a engineer introducing a new agentic role,
I want a runbook that walks through declaring a conforming interaction contract, plus a PR-template section that prompts for it,
so that a new role cannot be added without consciously declaring its triggers/timers/bridges, closing the tribal-knowledge gap the standard formalizes.
Acceptance Criteria
A "How to add an agentic role" runbook exists (co-located with or linked from docs/agentic-interaction-model.md) covering: pick the trigger class, declare the contract, choose event-first vs sanctioned bridge, and the timer contract if a timer is used.
The repository PR template gains an "Interaction contract" section prompting an author who adds/changes an agentic role to declare or update its contract.
The runbook references the CI enforcement (Story 4) so authors know a non-conforming contract fails CI, without duplicating the validator's rules.
The runbook and PR-template changes are documentation-only and introduce no new schedule.cron or workflow trigger.
Locate the existing PR template first (check .github/pull_request_template.md and .github/PULL_REQUEST_TEMPLATE*); extend it, do not create a competing one.
This story is documentation-only. Do NOT add the CI check here — that is Story 4 (validate-interaction-model). The runbook only points at that enforcement.
Keep the runbook's enforcement description a one-line pointer to Story 4's validator so the two never drift (single source of truth is the validator + the standard).
Testing standard: docs-only; a link/markdown check suffices. No bats.
Project Structure Notes
Runbook sits with docs/agentic-interaction-model.md; the PR-template edit lands in the repo's existing pull-request template. Both are inert docs — no trigger surface.
References
AGENTS.md
Story prepared by the BMAD Scrum Master (Bob) for epic #1402. Status: ready-for-dev.
Issue:#1405 — [Phase 2] Add the "How to add an agentic role" runbook and a PR-template interaction-contract section
Scope
Documentation-only: add a "How to add an agentic role" runbook co-located with the interaction-model standard, link it from that standard, and add an "Interaction contract" section to the repository PR template. No new schedule.cron or workflow trigger.
Implementation Checklist
docs/adding-an-agentic-role.md — new runbook: (1) classify the role / pick the trigger class (§2/§3), (2) author the contract in the Story-1 §8.1 shape, (3) choose the event path vs a sanctioned bridge (§5), (4) declare the timer contract if a timer is used (§6), plus a one-line pointer to CI enforcement (Story 4 validate-interaction-model, [Phase 3] Add scripts/validate-interaction-model.sh + bats, wired into lint.yml as a PR-triggered check #1406).
docs/agentic-interaction-model.md — add a link to the runbook from the standard.
.github/pull_request_template.md — new repo PR template (none exists today) with an "Interaction contract" section prompting authors who add/change an agentic role to declare/update its contract.
Tests to Write
None (docs-only per Dev Notes; Phase-2 TDD exception). Verification is a markdown/link sanity check + the required repo lint.
Wrote the "How to add an agentic role" runbook (docs/adding-an-agentic-role.md) — 4 steps: classify the role / pick the trigger class (§2/§3), author the contract in the §8.1 shape (§8), choose the event path vs a sanctioned bridge (§5), declare the timer contract if a timer is used (§6). Each step links back to the governing section of the standard. (AC test issue from agent #1)
Linked the runbook from docs/agentic-interaction-model.md (callout under the intro). (AC test issue from agent #1)
Added an Interaction contract section to the repo PR template. No PR template existed (checked .github/pull_request_template.md, .github/PULL_REQUEST_TEMPLATE*, and repo root), so .github/pull_request_template.md was created rather than competing with an existing one. (AC Go-live improvements for PR review agent #2)
Docs-only story (per Dev Notes: "a link/markdown check suffices. No bats") — Phase-2 TDD skipped under the documentation exception.
# Required repo lint
$ bash .dev-lead/scripts/dev-lead-lint.sh
[lint] shellcheck on 99 file(s)...
[lint] validating 4 agent profile(s)...
[lint] validating .github/CODEOWNERS...
[lint] all checks passed
# Markdown link + section-anchor sanity check (custom, GitHub slug algorithm)
All relative file links resolve OK.
All 14 referenced section anchors into agentic-interaction-model.md exist.
Files Changed
docs/adding-an-agentic-role.md (new): the "How to add an agentic role" runbook.
docs/agentic-interaction-model.md: added a callout linking the runbook from the standard.
.github/pull_request_template.md (new): repo PR template with an "Interaction contract" section prompting an author who adds/changes an agentic role to declare/update its contract.
Notes
No PR template previously existed in this repo, so one was created (not a competing second template).
Activity
don-petry commentedon Aug 2, 2026
Dev-Lead Implementation Plan
Issue: #1405 — [Phase 2] Add the "How to add an agentic role" runbook and a PR-template interaction-contract section
Scope
Documentation-only: add a "How to add an agentic role" runbook co-located with the interaction-model standard, link it from that standard, and add an "Interaction contract" section to the repository PR template. No new
schedule.cronor workflow trigger.Implementation Checklist
docs/adding-an-agentic-role.md— new runbook: (1) classify the role / pick the trigger class (§2/§3), (2) author the contract in the Story-1 §8.1 shape, (3) choose the event path vs a sanctioned bridge (§5), (4) declare the timer contract if a timer is used (§6), plus a one-line pointer to CI enforcement (Story 4validate-interaction-model, [Phase 3] Add scripts/validate-interaction-model.sh + bats, wired into lint.yml as a PR-triggered check #1406).docs/agentic-interaction-model.md— add a link to the runbook from the standard..github/pull_request_template.md— new repo PR template (none exists today) with an "Interaction contract" section prompting authors who add/change an agentic role to declare/update its contract.Tests to Write
Test Command
bash .dev-lead/scripts/dev-lead-lint.shdon-petry commentedon Aug 2, 2026
Dev-Lead: Implementation Complete
Plan Execution
docs/adding-an-agentic-role.md) — 4 steps: classify the role / pick the trigger class (§2/§3), author the contract in the §8.1 shape (§8), choose the event path vs a sanctioned bridge (§5), declare the timer contract if a timer is used (§6). Each step links back to the governing section of the standard. (AC test issue from agent #1)validate-interaction-model(Story 4 / [Phase 3] Add scripts/validate-interaction-model.sh + bats, wired into lint.yml as a PR-triggered check #1406) that defers the exact rules to the validator — no duplication. (AC Add @claude delegation, auto-merge, and rebase handling #3)docs/agentic-interaction-model.md(callout under the intro). (AC test issue from agent #1).github/pull_request_template.md,.github/PULL_REQUEST_TEMPLATE*, and repo root), so.github/pull_request_template.mdwas created rather than competing with an existing one. (AC Go-live improvements for PR review agent #2)schedule.cronor workflow trigger introduced. (AC Optimize review: small-PR and incremental fast paths #4)Test Results
Docs-only story (per Dev Notes: "a link/markdown check suffices. No bats") — Phase-2 TDD skipped under the documentation exception.
Files Changed
docs/adding-an-agentic-role.md(new): the "How to add an agentic role" runbook.docs/agentic-interaction-model.md: added a callout linking the runbook from the standard..github/pull_request_template.md(new): repo PR template with an "Interaction contract" section prompting an author who adds/changes an agentic role to declare/update its contract.Notes
validate-interaction-model(Story 4 / [Phase 3] Add scripts/validate-interaction-model.sh + bats, wired into lint.yml as a PR-triggered check #1406) is referenced by name only; that validator remains the single source of truth for the exact rules, kept out of the runbook to avoid drift.feat: implement issue #1405 — [Phase 2] Add the "How to add an agenti…