Add ADO Services support to respond-to-pr-comments + new human-voice-fidelity protocol

[abeltrano]

Note

This PR supersedes #253. It bundles the Azure DevOps Services
support for respond-to-pr-comments with the new
human-voice-fidelity guardrail protocol. Both sets of changes are
in this branch; #253 is now closed.

This PR delivers two related improvements to how PromptKit handles
externally visible text on the user's behalf:

1. respond-to-pr-comments now supports Azure DevOps Services
   alongside GitHub. The workflow shape is shared and only the API
   recipes branch per platform; users do not need to pass a new
   parameter or pick a platform.
2. A new opt-in guardrail protocol — human-voice-fidelity —
   preserves the user's communication style when an agent drafts
   externally visible text on their behalf (PR replies, issue
   comments, review comments, emails, chat messages). It is wired
   into the two templates that post text under the user's identity
   today: respond-to-pr-comments and review-pull-request.

---

Part 1 — ADO Services support for respond-to-pr-comments

What's new

• Auto-detect platform from the PR URL (github.com vs
  dev.azure.com / *.visualstudio.com), with fallback to
  git remote -v (handles SSH remotes including
  git@ssh.dev.azure.com:v3/... and
  {org}@vs-ssh.visualstudio.com:v3/...). Prompts on ambiguity —
  does not guess.
• ADO auth via az login + az rest --resource <ADO GUID> on
  every call. No Personal Access Token path.
• Native status vocabulary preserved — no cross-platform
  normalization. ADO uses fixed (not resolved) per the official
  CommentThreadStatus REST enum.
• ADO reply payload uses content + parentCommentId +
  commentType: "text". parentCommentId is always set, including
  for PR-wide threads (reply to the latest text comment).
• System threads are filtered (commentType: "system" or system
  CodeReviewThreadType properties); threads with no text comments
  are flagged for the user, not auto-skipped.
• Conservative outdated detection — prefer the ADO iterations +
  items APIs; fall back to the local working tree only when HEAD
  matches the iteration's source-branch tip; otherwise mark
  "unknown / not verified" and ask. PR-wide threads (null
  threadContext) skip outdated detection.
• GitHub recipe paginates both outer reviewThreads and inner
  comments via follow-up cursored queries.
• Out of scope, fail fast: ADO Server / on-prem / TFS / custom
  hostnames stop with a clear message rather than attempting
  unsupported API calls.

Files changed (Part 1)

• templates/respond-to-pr-comments.md — added Phase 1 platform
  detection and per-platform branches in Phase 2 (gather) and Phase
  5 (apply); ADO edge cases in Phase 6; expanded Quality Checklist.
• .github/skills/respond-to-pr-comments/SKILL.md — mirrors the
  template with compact per-platform recipes side-by-side.
• formats/pr-comment-responses.md — generalized status tables and
  the Action Summary to use platform-native vocabulary; tables use
  the exact API enum literals (active, fixed, wontFix,
  byDesign, etc.) for consistency with surrounding text.
• manifest.yaml — updated entry description to mention ADO
  Services.

---

Part 2 — human-voice-fidelity guardrail protocol

The protocol is scoped narrowly to user-authored prose. Internal
analysis, code, command output, format scaffolding, and quoted
reviewer text are all exempt by design.

Protocol features

• Pluggable voice sources in priority order: explicit samples in
  the current session, prior repo PRs/MRs by the user (with
  per-platform recipes for GitHub, Azure DevOps Services, GitLab,
  Bitbucket Cloud, Gitea/Forgejo, plus a fallback for unspecified
  SCMs), prior agent session history (Copilot CLI, Claude Code,
  Cursor, etc.), organization-specific tools (e.g. Microsoft 365
  Copilot / WorkIQ MCP), explicit style notes (STYLE.md,
  CLAUDE.md, AGENTS.md, .cursorrules, etc.).
• Calibrated style extraction — sentence length distribution,
  hedging frequency, technical density, openers/closers,
  characteristic phrases, punctuation habits.
• Per-output self-check with conditional rules: AI-tell patterns
  (em-dash, formulaic phrases, etc.) are flagged unless they appear
  in the user's own samples, plus soft rules covering length budget,
  greeting/sign-off, and opener.
• Neutral collaborative default + explicit disclosure when no
  samples are available. Never claims voice match without evidence.
• Output annotation — a brief Voice Calibration note (internal,
  not posted externally).

Integration

• protocols/guardrails/human-voice-fidelity.md (new).
  applicable_to: [respond-to-pr-comments, review-pull-request].
• manifest.yaml — register protocol under protocols.guardrails;
  add to both consuming templates' protocols lists.
• templates/respond-to-pr-comments.md — add to frontmatter;
  reference the protocol when drafting reviewer replies, with
  explicit scope note that exempts surrounding analysis, code, and
  quoted text. Points to the protocol's Phase 4 self-check rather
  than restating rules inline (avoids drift).
• templates/review-pull-request.md — add to frontmatter; reference
  the protocol in Phase 5 action-mode where inline review comment
  bodies and the overall review summary body are drafted before
  being POSTed to the GitHub Reviews API.
• .github/skills/respond-to-pr-comments/SKILL.md — mirrors the
  template's draft-reply guidance.

Other candidate consumers (not in this PR)

A scan of the manifest identified additional templates where this
protocol may be appropriate as follow-up work:

• generate-commit-message — commit messages are
  git-history-attributed under the user's identity. The conditional
  self-check catches common AI commit-message tells, though
  calibrated voice extraction has limited surface area given the
  heavy structural conventions (Conventional Commits,
  Problem/Solution). Worth applying in a follow-up PR after we see
  how the protocol performs in real PR-review use.

Templates intentionally not considered candidates:

• Internal-artifact templates (triage-issues,
  triage-pull-requests, author-session-handoff, all
  audit/review/investigate reports) — output goes to the user, not
  posted externally on their behalf.
• Document-authoring templates (author-rfc,
  author-architecture-spec, author-presentation,
  author-design-doc, etc.) — institutional voice with strict
  structural conventions; calibrated personal voice is not the right
  model.
• Code/spec/test/hardware generation templates — produce code,
  schematics, specs, plans, not user-voice prose.

Out of scope (Part 2)

Deferred to potential follow-up PRs (intentionally not included
here):

• Delegation matrix for action-mode confirmations
• Work-item proposal phase
• Format schema expansion (disposition / target-state / work-item
  breakdowns / Voice Calibration section)
• SKILL rewrite for compactness

---

Validation

• python tests/validate-manifest.py passes (manifest ↔ template
  protocol sync check).
• Protocol's applicable_to and both templates' protocols
  frontmatter are in sync with the manifest entries.
• Two rubber-duck critique passes were applied to the ADO recipes;
  ADO REST shape verified against MS Learn docs
  (CommentThreadStatus, threads/comments endpoints, payload field
  names).
• Three rounds of copilot-pull-request-reviewer feedback on this
  branch addressed across commits 8e4ff0d, 7650489, and
  8359da0.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a new opt-in human-voice-fidelity guardrail protocol and wires it into the templates that draft externally posted PR text under the user’s identity.

Changes:

• Introduces protocols/guardrails/human-voice-fidelity.md and registers it in manifest.yaml.
• Applies the protocol to externally posted prose in review-pull-request and respond-to-pr-comments.
• Expands respond-to-pr-comments (and related format/skill docs) to support Azure DevOps Services alongside GitHub, including native status vocabulary guidance.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
templates/review-pull-request.md	Adds human-voice-fidelity to frontmatter and instructs applying it to posted review bodies.
templates/respond-to-pr-comments.md	Adds the protocol and significantly expands workflow to support GitHub + Azure DevOps Services.
protocols/guardrails/human-voice-fidelity.md	New guardrail protocol defining voice sourcing, calibration, and per-output self-check rules.
manifest.yaml	Registers the new protocol and adds it to the two consuming templates.
formats/pr-comment-responses.md	Updates output format to use platform-native status vocab (GitHub vs ADO).
.github/skills/respond-to-pr-comments/SKILL.md	Updates skill guidance for GitHub + ADO support and native status vocabulary.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 10 comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.