Repository navigation
Closed
Labels
dev-leadFor dev-lead agent pickupFor dev-lead agent pickupinitiativeEpic / initiative tracking issueEpic / initiative tracking issue
Description
Story
As a engineer navigating the agentic docs,
I want AGENTS.md and each agent doc linking the interaction model, and the stale ci-failure-analyst spec reconciled to its deployed reality,
so that the standard is discoverable from every entry point and the one known spec/deploy divergence no longer misleads implementers.
Acceptance Criteria
- AGENTS.md gains an "Agentic interaction model" section linking docs/agentic-interaction-model.md.
- Each agent doc (docs/dev-lead/, docs/pr-review-agent/, docs/aw/ci-failure-analyst.md) gains an "Interaction contract" subsection linking the role's contract and the standard.
- The ci-failure-analyst spec/deploy divergence is reconciled: the deployed thin caller ci-failure-analyst.lock.yml triggers on check_run:completed and posts live (issues: write), while the ci-failure-analyst.md gh-aw source declares workflow_run + staged: true + max: 1 — the docs/spec are corrected to describe the deployed behaviour (or the orphaned source is removed), so they agree.
- The reconciliation does not change the deployed ci-failure-analyst runtime behaviour; it only makes the spec/doc match reality (the .lock.yml stub is a byte-frozen ring-0 caller and is not edited).
- No new schedule.cron or trigger is introduced by this documentation/reconciliation story.
Tasks / Subtasks
- Add an "Agentic interaction model" section to AGENTS.md linking the standard, consistent with the existing standards sections. (AC: test issue from agent #1)
- Add an "Interaction contract" subsection to docs/dev-lead/spec.md, docs/pr-review-agent/pr-review-agent.md, and docs/aw/ci-failure-analyst.md linking each role's contract + the standard. (AC: Go-live improvements for PR review agent #2)
- Reconcile the ci-failure-analyst divergence: compare .github/workflows/ci-failure-analyst.md (workflow_run, staged:true, max:1, models: sonnet-4-6) against the deployed .github/workflows/ci-failure-analyst.lock.yml (check_run:completed, live, calls ci-failure-analyst-reusable.yml) and docs/aw/ci-failure-analyst.md; correct the stale spec/doc to the deployed reality or remove the orphaned source, without editing the frozen .lock.yml stub. (AC: Add @claude delegation, auto-merge, and rebase handling #3, Optimize review: small-PR and incremental fast paths #4)
Dev Notes
- The divergence is concrete: ci-failure-analyst.md (gh-aw source) declares on: workflow_run + safe-outputs.add-comment{max:1, staged:true} + models.claude:[sonnet-4-6]; the deployed ci-failure-analyst.lock.yml is a thin caller triggering on check_run:completed with issues: write (live) delegating to ci-failure-analyst-reusable.yml pinned at ci-failure-analyst/v1-stable. The .md/doc is the stale artifact — reconcile to the deployed thin-caller reality.
- ci-failure-analyst.lock.yml is a byte-frozen ring-0 caller stub (caller-stub-freeze covers ci-failure-analyst.lock.yml -> ci-failure-analyst.block). Do NOT edit its on:/with: block. The reconciliation corrects the SPEC/DOC (.md and docs/aw/ci-failure-analyst.md), not the deployed runtime.
- If .github/workflows/ci-failure-analyst.md is an orphaned gh-aw source with no matching deployed compile, the lint.yml gh-aw-compile job's orphaned-lock detector and the caller architecture indicate it should be removed or corrected — decide based on whether it is still a live source; document the decision.
- Verify doc paths before linking: docs/dev-lead/spec.md, docs/pr-review-agent/pr-review-agent.md, docs/aw/ci-failure-analyst.md all exist.
- Testing standard: docs/spec-only; a link check + confirming the spec now matches the deployed on:/safe-output posture. No runtime behaviour change to assert.
Project Structure Notes
Touches AGENTS.md, docs/dev-lead/spec.md, docs/pr-review-agent/pr-review-agent.md, docs/aw/ci-failure-analyst.md, and the ci-failure-analyst gh-aw source/spec. The deployed ci-failure-analyst.lock.yml stub is untouched.
References
- AGENTS.md
- docs/dev-lead/spec.md
- docs/pr-review-agent/pr-review-agent.md
- docs/aw/ci-failure-analyst.md
- .github/workflows/ci-failure-analyst.md
- .github/workflows/ci-failure-analyst.lock.yml
- .github/workflows/ci-failure-analyst-reusable.yml
Likely target surface
AGENTS.mddocs/aw/ci-failure-analyst.md.github/workflows/ci-failure-analyst.md
Story prepared by the BMAD Scrum Master (Bob) for epic #1402. Status: ready-for-dev.
Metadata
Metadata
Assignees
Labels
dev-leadFor dev-lead agent pickupFor dev-lead agent pickupinitiativeEpic / initiative tracking issueEpic / initiative tracking issue
Activity
don-petry commentedon Aug 2, 2026
Dev-Lead Implementation Plan
Issue: #1409 — [Phase 5] Wire the standard into AGENTS.md and per-agent docs, and reconcile the ci-failure-analyst spec vs deployed divergence
Scope
Make the agentic interaction model discoverable from AGENTS.md and every per-agent doc, and correct the stale
ci-failure-analyst.mdgh-aw source so its declared trigger/posture matches the deployed thin-caller reality — without editing the byte-frozen.lock.yml.Implementation Checklist
docs/agentic-interaction-model.md(AC test issue from agent #1)interaction-contracts/dev-lead.yml+personas/dev-lead/interaction.yml+ the standard (AC Go-live improvements for PR review agent #2)interaction-contracts/pr-review.yml+personas/pr-review/interaction.yml+ the standard (AC Go-live improvements for PR review agent #2)interaction-contracts/ci-failure-analyst.yml+ the standard (AC Go-live improvements for PR review agent #2)on: workflow_run→check_run:[completed], dropstaged: true(deployed posts live), align the body/guard to the deployed check_run flow, and add a note that the deployed runtime is the thin caller.lock.yml→ reusable (AC Add @claude delegation, auto-merge, and rebase handling #3, Optimize review: small-PR and incremental fast paths #4)Reconciliation decision (AC #3/#4)
The
.mdis corrected, not removed:ci-failure-analyst.lock.ymlis the only committed*.lock.yml, and thegh-aw-compilejob's orphaned-lock detector (lint.yml) fails a.lock.ymlwith no sibling.md. Removing the source would orphan the frozen ring-0 stub. The.lock.ymlis untouched (caller-stub-freeze); only the spec/doc changes. No newschedule.cron/trigger is introduced (AC #5).Tests to Write
on:/safe-output posture.Test Command
bash .dev-lead/scripts/dev-lead-lint.sh+gh aw compile --no-emit(via the lint.yml gh-aw-compile job)don-petry commentedon Aug 2, 2026
Dev-Lead: Implementation Complete
Plan Execution
docs/agentic-interaction-model.md+ thedocs/adding-an-agentic-role.mdrunbook, cross-referencing the adjacent "Scheduled workflows" and "Ring-0 caller-stub freeze" sections (AC test issue from agent #1)interaction-contracts/dev-lead.yml(runtime lens) +personas/dev-lead/interaction.yml(role lens) + the standard (AC Go-live improvements for PR review agent #2)interaction-contracts/pr-review.yml+personas/pr-review/interaction.yml+ the standard (AC Go-live improvements for PR review agent #2)interaction-contracts/ci-failure-analyst.yml+ the standard (AC Go-live improvements for PR review agent #2)Reconciliation decision (AC #3/#4)
Corrected the spec, did not remove the source.
ci-failure-analyst.lock.ymlis the only committed*.lock.ymlin the repo, and thegh-aw-compilejob's orphaned-lock detector (lint.yml) fails any.lock.ymllacking a sibling.md. Removingci-failure-analyst.mdwould orphan the byte-frozen ring-0 stub and break CI — so the.mdis retained and corrected instead:on: workflow_run: {workflows:[CI,Lint,Tests]}→on: check_run: types:[completed](matches the deployed stub)safe-outputs.add-comment.staged: true→ deployed posts live (issues: write)github.event.workflow_run.*→github.event.check_run.*, added the anti-loop name guard + non-fork/commits-to-pulls fallback that the deployed reusable performs.lock.yml→ci-failure-analyst-reusable.yml@ci-failure-analyst/v1-stable, that this.mdis the orphan-detector companion kept in sync with the stub, and that the frozen.lock.ymlmust not be edited (caller-stub-freeze)The deployed
ci-failure-analyst.lock.ymlis untouched (git diffshows no change). No newschedule.cronor automation trigger is introduced (AC #5).Test Results
Testing standard per the issue: docs/spec-only — link check + confirming the spec matches the deployed
on:/safe-output posture. Phase 2 (TDD) skipped per the doc-only exception (no observable runtime behaviour change to assert).Files Changed
AGENTS.md: new "Agentic interaction model" standards section (AC test issue from agent #1)docs/dev-lead/spec.md: "Interaction contract" subsection (AC Go-live improvements for PR review agent #2)docs/pr-review-agent/pr-review-agent.md: "Interaction contract" subsection (AC Go-live improvements for PR review agent #2)docs/aw/ci-failure-analyst.md: "Interaction contract" subsection (AC Go-live improvements for PR review agent #2).github/workflows/ci-failure-analyst.md: reconciled gh-aw source to deployed check_run/live posture + "Deployed runtime" note (AC Add @claude delegation, auto-merge, and rebase handling #3, Optimize review: small-PR and incremental fast paths #4)Notes
.lock.ymlandci-failure-analyst-reusable.ymlalready reflected the correct behaviour;docs/aw/ci-failure-analyst.mdalready described the check_run/reusable reality — the only stale artifact was.github/workflows/ci-failure-analyst.md, which is now consistent.ci-failure-analyst.mdand the hand-maintained.lock.ymlare structurally distinct by design; the new note makes that explicit so the retained source no longer misleads implementers.feat: implement issue #1409 — [Phase 5] Wire the standard into AGENTS…
feat: implement issue #1409 — [Phase 5] Wire the standard into AGENTS…
feat: implement issue #1409 — [Phase 5] Wire the standard into AGENTS…
feat: implement issue #1409 — [Phase 5] Wire the standard into AGENTS…
feat: implement issue #1409 — [Phase 5] Wire the standard into AGENTS…
feat: implement issue #1409 — [Phase 5] Wire the standard into AGENTS…
feat: implement issue #1409 — [Phase 5] Wire the standard into AGENTS…
feat: implement issue #1409 — [Phase 5] Wire the standard into AGENTS…
feat: implement issue #1409 — [Phase 5] Wire the standard into AGENTS…
feat: implement issue #1409 — [Phase 5] Wire the standard into AGENTS…