Skip to content

[Phase 2] Add the "How to add an agentic role" runbook and a PR-template interaction-contract section #1405

Closed

Description

@github-actions

Story

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

  1. 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.
  2. The repository PR template gains an "Interaction contract" section prompting an author who adds/changes an agentic role to declare or update its contract.
  3. The runbook references the CI enforcement (Story 4) so authors know a non-conforming contract fails CI, without duplicating the validator's rules.
  4. The runbook and PR-template changes are documentation-only and introduce no new schedule.cron or workflow trigger.

Tasks / Subtasks

Dev Notes

  • 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.

Activity

  1. don-petry commented on Aug 2, 2026

    @don-petry
    Collaborator

    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.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.

    Test Command

    bash .dev-lead/scripts/dev-lead-lint.sh

  2. don-petry commented on Aug 2, 2026

    @don-petry
    Collaborator

    Dev-Lead: Implementation Complete

    Plan Execution

    Test Results

    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

  3. added a commit that references this issue on Aug 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    dev-leadFor dev-lead agent pickupinitiativeEpic / initiative tracking issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions