agentme 0.35.2 → 0.36.0

package/.xdrs/agentme/edrs/application/skills/250-github-connector/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: 250-github-connector
+description: >
+  Base connector providing authentication, read access, and write access to GitHub pull
+  requests and their comments via the gh CLI. Pure I/O -- no triage logic, no business
+  decisions. Activate when an agent or skill (such as pr-owner-assistant) needs to fetch or
+  post PR comments, resolve review threads, or check out a PR branch on GitHub.
+metadata:
+  author: flaviostutz
+  version: "1.1"
+---
+
+## Overview
+
+Reusable authentication and connection skill for GitHub pull requests, per
+[agentme-edr-127](../../127-external-system-adapter-skills.md) rule 06 (connector naming).
+Wraps the `gh` CLI -- GitHub's own supported API client -- so callers never construct raw
+REST/GraphQL calls or handle GitHub-specific auth themselves. Contains no business logic (per
+rule 05): it does not decide what a comment means, what action to take, or when to reply --
+it only reads and writes data and normalizes it to the shape consumed by
+[`400-pr-owner-assistant`](../../../principles/skills/400-pr-owner-assistant/SKILL.md).
+
+This is a base connector skill (number range 250-299).
+
+## Instructions
+
+### Authentication check
+
+1. Verify the `gh` CLI is installed (`gh --version`); if missing, ask the human whether to
+   install it now via the appropriate package manager for their OS (e.g. `brew install gh`
+   on macOS). Only run the install command after explicit confirmation; if the human
+   declines or the install fails, report the install requirement and stop.
+2. Run `gh auth status`. If authenticated, proceed -- this is the preferred path since `gh`
+   manages its own session token securely (per agentme-edr-124's least-exposure principle)
+   and needs no secret handling here.
+3. If not authenticated, run
+   `gh auth login --hostname github.com --git-protocol https --web` instead of bare
+   `gh auth login` -- these flags answer the "Where do you use GitHub?", "preferred
+   protocol?", and "how would you like to authenticate?" prompts non-interactively so the
+   human is never asked them. `gh` still asks one local yes/no question ("Authenticate Git
+   with your GitHub credentials?"); accept its default (`Y`) automatically, since it only
+   wires the existing `gh` credential helper into git and needs no human input. The only
+   step that still requires the human is the one-time code / "Press Enter to open ... in
+   your browser" prompt that follows -- `gh` stores the resulting token in its own secure
+   storage once that completes. Never ask the human for a raw PAT and never read, request,
+   or feed a token to `gh` directly. Do not proceed with a write operation until
+   `gh auth status` reports an authenticated session.
+4. Never substitute `gh` with a direct HTTP call (`curl`, `fetch`, or any other HTTP client)
+   against the GitHub REST/GraphQL API, and never scrape the PR's rendered HTML page as a
+   workaround -- this applies to reads as much as writes, and applies even when the target
+   data is public. If `gh` is missing or unauthenticated, stop and resolve that first (steps
+   1-3 above); do not degrade to an alternative retrieval method to route around it.
+
+### Reading data
+
+All read commands are plain `gh` invocations; none require confirmation (per
+agentme-edr-127 rule 04, read-only operations are exempt from the HITL confirmation step
+only -- they are not exempt from the CLI-only channel). Every read below MUST go through
+`gh`; never construct the equivalent call with `curl`/another HTTP client, and never fetch
+or scrape the PR's rendered web page as a substitute. When running `gh` from an automated
+or non-interactive shell, prefix calls with `GH_PAGER=cat` (see Known Issues) so output is
+never lost to a pager.
+
+- PR metadata: `gh pr view <n> --json title,body,baseRefName,headRefName,url,state,isCrossRepository,headRepositoryOwner,headRepository`
+- Issue-level (top) comments: `gh api repos/{owner}/{repo}/issues/{n}/comments`
+- Review (file/line) comments: `gh api repos/{owner}/{repo}/pulls/{n}/comments`
+- Review summaries: `gh api repos/{owner}/{repo}/pulls/{n}/reviews`
+- Thread resolution state (REST does not expose this): `gh api graphql` with a
+  `reviewThreads` query on the PR, reading `isResolved` and each thread's comment node ids.
+
+Normalize every fetched item to the shared record shape (`id`, `kind`, `status`, `can_reply`,
+`can_resolve`, `path`, `line`, `content`, `author`, `in_reply_to`, `diff_hunk`, `url`):
+- `kind` is `"issue-comment"`, `"review-comment"`, or `"review-summary"`.
+- `status` is `"resolved"` when the GraphQL thread lookup marks it resolved, else `"open"`.
+  GitHub has no `wontfix`/`closed` state of its own -- `pr-owner-assistant` tracks those
+  locally.
+- `can_resolve` is `true` only for `"review-comment"` items belonging to a resolvable
+  thread; `"issue-comment"` and `"review-summary"` are never resolvable -- set `false`.
+- `in_reply_to` is resolved to the thread's top-level/root comment id, never an intermediate
+  reply, so replies always thread correctly.
+- If the reply target is a reply-to-a-reply, resolve `in_reply_to` up to the root comment id
+  first (GitHub only allows replying to the root of a review thread).
+- `diff_hunk` is taken verbatim from the `diff_hunk` field already present on each
+  `"review-comment"` item returned by the review-comments read command above -- no extra
+  fetch needed. Null for `"issue-comment"` and `"review-summary"` items, since neither is
+  file/line-scoped.
+- `url` is taken verbatim from the `html_url` field already present on every issue-comment,
+  review-comment, and review object returned by the read commands above -- no extra fetch
+  needed for any `kind`.
+
+### Writing data
+
+Before any write below, show the mandatory confirmation (per agentme-edr-127 rule 04):
+**System** (`owner/repo` + PR number), **Operation**, **Fields** (exact verbatim text to
+post), **Estimated impact** (visible to PR participants, triggers notifications). Wait for
+explicit confirmation; never proceed on an assumed "yes."
+
+- Reply to an issue-level comment: `gh api repos/{owner}/{repo}/issues/{n}/comments -f body="..."`
+- Reply to a review thread: `gh api repos/{owner}/{repo}/pulls/{n}/comments -f body="..." -F in_reply_to=<root-comment-id>`
+- Post a new general PR comment: `gh pr comment <n> --body "..."`
+- Resolve a review thread: `gh api graphql` with a `resolveReviewThread` mutation, passing
+  the thread's GraphQL node id (not the REST numeric id -- these are different identifier
+  spaces; see Known Issues).
+- Check out the PR branch: `gh pr checkout <n>`.
+
+### Constraints
+
+- MUST use the `gh` CLI for every read and write handled by this connector -- never fall
+  back to `curl`, another raw HTTP client, or scraping the PR's HTML page, even when `gh` is
+  missing, unauthenticated, rate-limited, or erroring, and even when the target data is
+  public.
+- MUST stop and follow the Authentication check steps above when `gh` cannot complete a
+  request, instead of silently degrading to an alternative retrieval method.
+
+## Examples
+
+**Input**: fetch all comments for `https://github.com/acme/widgets/pull/482`
+
+Runs `gh pr view 482 --json ...` for metadata, then the three read commands above for
+issue-comments, review-comments, and reviews, then one `gh api graphql` call for thread
+resolution state, and returns a single normalized list.
+
+**Input**: reply to review comment id `review-comment/91234` and mark it resolved
+
+Shows the mandatory confirmation summary first. On explicit "yes," posts the reply via
+`gh api repos/{owner}/{repo}/pulls/{n}/comments -F in_reply_to=91234`, then resolves the
+thread via the GraphQL mutation using that comment's thread node id.
+
+## Edge Cases
+
+- **PR from a fork**: `headRepositoryOwner`/`headRepository` differ from the base repo;
+  checkout and branch comparisons must use the fork's remote, not the base repo's.
+- **Review-summary comments**: never resolvable and never file/line-scoped; `path`/`line`
+  are always null and `can_resolve` is always `false`.
+- **Reply-to-a-reply**: GitHub only supports replying to a thread's root comment; always
+  resolve `in_reply_to` up to the root before posting.
+
+## Known Issues
+
+- **Symptom:** `resolveReviewThread` mutation fails with a "could not resolve to a node"
+  error even though the comment id is valid.
+  **Cause:** the mutation requires the review thread's GraphQL node id, not the numeric
+  REST comment id or the numeric review id -- these are three different identifier spaces.
+  **Fix:** always fetch the thread's node id via the `reviewThreads` GraphQL query first,
+  and cache the numeric-id-to-node-id mapping per PR fetch. Verify the exact mutation shape
+  via `gh api graphql` introspection before first use in a new environment.
+- **Symptom:** posting a reply or resolving a thread returns HTTP 403 despite `gh auth
+  status` showing a valid session.
+  **Cause:** the authenticated account lacks write/triage permission on the repository (for
+  example, an outside collaborator with read-only access).
+  **Fix:** degrade to reply-only where permitted, report the permission gap plainly, and
+  never retry the same call silently.
+- **Symptom:** any `gh api` call returns HTTP 404 for a repo the human insists exists.
+  **Cause:** the authenticated token lacks the `repo` (or fine-grained equivalent) scope, so
+  GitHub reports a private resource as not found rather than as forbidden.
+  **Fix:** report this distinction explicitly and ask the human to re-run
+  `gh auth refresh -s repo` rather than assuming the PR truly does not exist.
+- **Symptom:** repeated calls start failing with HTTP 403 and a rate-limit message.
+  **Cause:** GitHub's REST/GraphQL rate limits were exceeded, often from re-fetching the
+  full comment list too frequently in one session.
+  **Fix:** space out calls and reuse the already-fetched result within a session; never
+  silently retry in a tight loop.
+- **Symptom:** an agent fetched PR metadata, comments, or diffs via `curl`/`api.github.com`
+  or by scraping the PR's rendered HTML page instead of using `gh`.
+  **Cause:** `gh` was missing or unauthenticated (e.g. `gh auth status` reported not logged
+  in), and the agent treated the unauthenticated public REST API or the rendered PR page as
+  an acceptable substitute since the target data was technically public.
+  **Fix:** never substitute `gh` with a direct HTTP call or a page scrape, regardless of
+  whether the data is public. Stop at the Authentication check step, report the missing or
+  failed `gh` session plainly, and wait for the human to install or authenticate `gh` before
+  retrying the same read or write through `gh`.
+- **Symptom:** a `gh api`/`gh pr view` read command run from an automated shell appears to
+  hang or return no captured output at all, even though `gh` itself succeeded.
+  **Cause:** `gh` falls back to `$PAGER` (commonly `less`) for output it thinks may be
+  interactive; this switches the terminal to its alternate screen buffer, and content shown
+  there is not part of normal scrollback, so an automated caller never sees it -- piping
+  through `| cat` alone does not reliably prevent this.
+  **Fix:** prefix every `gh` invocation with `GH_PAGER=cat` (e.g.
+  `GH_PAGER=cat gh api repos/{owner}/{repo}/issues/{n}/comments`) when running non-
+  interactively, which disables `gh`'s pager unconditionally.
+
+## References
+
+- [`400-pr-owner-assistant`](../../../principles/skills/400-pr-owner-assistant/SKILL.md) -- consumes this connector's normalized output.
+- [`agentme-edr-127`](../../127-external-system-adapter-skills.md) -- external system adapter skill rules (connector naming, Known Issues format, HITL-before-write).
+- [`agentme-edr-124`](../../124-secrets-management.md) -- credential storage and retrieval.
+- [`agentme-core-adr-003`](../../../../../agentme-core/adrs/principles/003-skill-numbering-ranges.md) -- skill numbering ranges (250-299 base connectors).

package/.xdrs/agentme/edrs/application/skills/250-github-connector/SKILL.test.md

@@ -0,0 +1,118 @@
+---
+skill: 250-github-connector
+skill-version: "1.0"
+---
+
+## Test Scenarios
+
+### Scenario 1: Fetch and normalize all comment kinds for a PR, happy path
+
+**Trigger / Input**
+
+Fetch all comments for `https://github.com/acme/widgets/pull/482`, a PR with one issue-level
+comment, two review (file/line) comments in one resolved thread, and one review-summary.
+
+**Expected Behaviour**
+
+The connector: (1) confirms `gh auth status` is authenticated; (2) runs the PR metadata
+read; (3) runs the issue-comments, review-comments, and reviews read commands; (4) runs one
+`gh api graphql` call to read thread resolution state; (5) returns a single normalized list
+where the issue-level comment has `kind: "issue-comment"` and `can_resolve: false`, the two
+review comments have `kind: "review-comment"`, `status: "resolved"`, and `can_resolve:
+true`, and the review-summary has `kind: "review-summary"` and `can_resolve: false`.
+
+**Assertions**
+
+- [ ] Output normalizes every fetched item to the shared record shape (id, kind, status,
+      can_reply, can_resolve, path, line, content, author, in_reply_to).
+- [ ] Output sets `can_resolve: false` for the issue-comment and the review-summary items.
+- [ ] Output sets `status: "resolved"` for the two review comments in the resolved thread,
+      derived from the GraphQL thread lookup rather than the REST response alone.
+- [ ] Connector never branches its own logic on business meaning of comment content.
+
+### Scenario 2: Reply-to-a-reply resolves to the thread root before posting
+
+**Trigger / Input**
+
+Post a reply targeting a review comment that is itself a reply (not the root) within its
+thread.
+
+**Expected Behaviour**
+
+Before posting, the connector resolves `in_reply_to` up to the thread's root comment id
+(GitHub only accepts replies anchored to the root), shows the mandatory System/Operation/
+Fields/Estimated impact confirmation using the resolved root id, and only posts via
+`gh api repos/{owner}/{repo}/pulls/{n}/comments -F in_reply_to=<root-id>` after explicit
+confirmation.
+
+**Assertions**
+
+- [ ] Connector resolves `in_reply_to` to the thread's root comment id, not the intermediate
+      reply id, before constructing the write call.
+- [ ] Connector shows the mandatory confirmation (System, Operation, Fields, Estimated
+      impact) before posting.
+- [ ] Connector does not post before receiving explicit human confirmation.
+
+### Scenario 3: Permission-denied write degrades to reply-only, no silent retry
+
+**Trigger / Input**
+
+A resolve-thread write (`gh api graphql` `resolveReviewThread` mutation) returns HTTP 403
+because the authenticated account lacks triage permission on the repository.
+
+**Expected Behaviour**
+
+Per the Known Issues entry for this symptom, the connector reports the permission gap
+plainly to the caller, does not retry the same call, and continues to allow a reply-only
+write path for that comment (an already-successful or subsequent reply post is unaffected).
+
+**Assertions**
+
+- [ ] Connector reports the permission error explicitly rather than failing silently.
+- [ ] Connector does not silently retry the failed resolve call.
+- [ ] Connector still allows a reply-only write for the same comment.
+
+### Scenario 4: No GitHub session available halts before any write
+
+**Trigger / Input**
+
+`gh auth status` reports not logged in.
+
+**Expected Behaviour**
+
+The connector runs `gh auth login --hostname github.com --git-protocol https --web`
+(non-interactive except for the one local git-credential yes/no, which the connector
+auto-accepts on its default) so the human is only asked to complete the browser/device-code
+step, and does not attempt any write operation until `gh auth status` reports an
+authenticated session. Read-only operations that do not require authentication (if any) are
+unaffected.
+
+**Assertions**
+
+- [ ] Connector does not attempt a write operation without an authenticated `gh` session.
+- [ ] Connector runs `gh auth login` with `--hostname`/`--git-protocol`/`--web` rather than
+      bare `gh auth login`, so the human is not asked the host/protocol/method questions.
+- [ ] Connector never asks for, reads, or feeds `gh` a raw PAT/token directly.
+
+### Scenario 5: gh unavailable or unauthenticated never triggers a curl/scrape fallback
+
+**Trigger / Input**
+
+Fetch PR metadata, comments, and diff for `https://github.com/acme/widgets/pull/482` while
+`gh auth status` reports not logged in (or `gh` is not installed).
+
+**Expected Behaviour**
+
+The connector does not issue any direct `curl`/HTTP request to `api.github.com`,
+`github.com`, or a `.diff`/`.patch` endpoint, and does not fetch or parse the PR's rendered
+HTML page as a substitute -- even though the target repository and PR are public. Instead it
+follows the Authentication check steps, reports the missing/failed `gh` session plainly, and
+halts every read and write until `gh auth status` reports an authenticated session.
+
+**Assertions**
+
+- [ ] Connector does not issue a `curl` or other raw HTTP request to any GitHub endpoint as
+      a substitute for `gh`.
+- [ ] Connector does not fetch or parse the PR's HTML page as a scraping fallback.
+- [ ] Connector halts reads and writes and prompts for `gh` installation/`gh auth login`
+      rather than degrading to an alternative retrieval method.

package/.xdrs/agentme/edrs/application/skills/251-azure-devops-connector/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: 251-azure-devops-connector
+description: >
+  Base connector providing authentication, read access, and write access to Azure DevOps
+  pull requests and their comment threads via the az CLI. Pure I/O -- no triage logic, no
+  business decisions. Activate when an agent or skill (such as pr-owner-assistant) needs to
+  fetch or post PR thread comments, change thread status, or check out a PR branch on Azure
+  DevOps.
+metadata:
+  author: flaviostutz
+  version: "1.1"
+---
+
+## Overview
+
+Reusable authentication and connection skill for Azure DevOps pull requests, per
+[agentme-edr-127](../../127-external-system-adapter-skills.md) rule 06 (connector naming).
+Wraps the `az` CLI (with the `azure-devops` extension) -- Azure DevOps's own supported API
+client -- plus `az rest` for the handful of operations the extension does not expose as a
+dedicated subcommand. Contains no business logic (per rule 05): it only reads and writes
+data and normalizes it to the shape consumed by
+[`400-pr-owner-assistant`](../../../principles/skills/400-pr-owner-assistant/SKILL.md).
+
+This is a base connector skill (number range 250-299).
+
+## Instructions
+
+### Authentication check
+
+1. Verify the `az` CLI is installed (`az --version`); if missing, ask the human whether to
+   install it now via the appropriate package manager for their OS (e.g. `brew install
+   azure-cli` on macOS). Only run the install command after explicit confirmation; if the
+   human declines or the install fails, report the install requirement and stop.
+2. Verify the `azure-devops` extension is present; if missing, install it with
+   `az extension add --name azure-devops` (auto-installs on first use in most `az` versions,
+   but check explicitly rather than assuming).
+3. Run `az account show`. If authenticated, proceed -- prefer `az login`'s own session over
+   handling a token directly.
+4. If not authenticated, check the OS keychain for a stored Azure DevOps PAT per
+   [agentme-edr-124](../../124-secrets-management.md) rather than any `.env` file, hardcoded
+   value, or shell profile export. If found, export it only transiently as
+   `AZURE_DEVOPS_EXT_PAT` for the current command invocation -- never persist it to disk.
+5. If no session and no stored PAT exist, prompt the human to run `az login` interactively
+   or to store a PAT in the keychain first, per agentme-edr-124's `setup-secrets` pattern.
+   Do not proceed with a write operation without one of these. Unlike `gh auth login`, bare
+   `az login` already opens the browser directly with no preceding host/protocol/method
+   questions, so no extra flags are needed here to keep it non-interactive.
+6. Set the default organization/project once per session
+   (`az devops configure --defaults organization=<url> project=<project>`) to shorten
+   subsequent commands.
+7. Never substitute `az`/`az rest` with a direct HTTP call (`curl`, `fetch`, or any other
+   HTTP client) against the Azure DevOps REST API, and never scrape the PR's web UI as a
+   workaround -- this applies to reads as much as writes, and applies even when the target
+   data looks read-only. If `az`, the `azure-devops` extension, or a valid session/PAT is
+   missing, stop and resolve that first (steps 1-5 above); do not degrade to an alternative
+   retrieval method to route around it.
+
+### Reading data
+
+All read commands are exempt from HITL confirmation (per agentme-edr-127 rule 04, read-only
+operations need no confirmation -- but they are not exempt from the CLI-only channel).
+Every read below MUST go through `az`/`az rest`; never construct the equivalent REST call
+with `curl`/another HTTP client, and never fetch or scrape the PR's web UI as a substitute.
+
+- PR metadata: `az repos pr show --id <n> --output json`
+- All comment threads (Azure DevOps has no separate "list comments" call -- threads are the
+  unit of data and already include every comment and their status):
+  `az rest --method GET --uri "https://dev.azure.com/{org}/{project}/_apis/git/repositories/{repo}/pullRequests/{n}/threads?api-version=7.1"`
+  There is no dedicated `az repos pr` subcommand for threads -- `az rest` is required for both
+  reads and writes; verify this generic-URI capability with `az rest --help` and a smoke-test
+  GET before first use in a new environment.
+
+Normalize every thread's comments to the shared record shape (`id`, `kind`, `status`,
+`can_reply`, `can_resolve`, `path`, `line`, `content`, `author`, `in_reply_to`, `diff_hunk`,
+`url`):
+- `id` is `"thread-comment/<threadId>.<commentId>"` -- Azure DevOps ids are scoped per PR, not
+  global, so always keep the PR number alongside when persisting.
+- `kind` is always `"thread-comment"` -- Azure DevOps has no separate review-summary concept;
+  never emit a `"review-summary"` kind for this provider.
+- `status` maps from the thread's `status` field: `"active"` -> `"open"`, `"fixed"` /
+  `"closed"` -> `"resolved"`, `"wontFix"` -> `"wontfix"`, `"pending"` -> `"open"`.
+- `path`/`line` come from `threadContext.filePath` and the relevant line range; when
+  `threadContext` is `null`, this is a general (PR-level, not file-scoped) comment -- classify
+  it as a general comment, not a parsing error.
+- `can_reply` and `can_resolve` are `true` for any non-deleted comment in a non-deleted
+  thread; Azure DevOps does not have GitHub's permission-driven resolve restriction in the
+  same way, but a 403 on write still means `can_resolve` should be treated as `false` for
+  that session (see Known Issues).
+- `in_reply_to` is the thread's first comment id whenever the target is a reply within the
+  same thread -- Azure DevOps threads are flat, so there is no root-vs-reply distinction to
+  resolve.
+- `diff_hunk` has no native equivalent in the Azure DevOps API -- `threadContext` exposes
+  only a file path and line range, not a unified-diff-style hunk string. Leave `diff_hunk`
+  null rather than fabricating one; `pr-owner-assistant` degrades to relying on
+  `source-lines` alone in that case, exactly as it does for a general (non-file-scoped)
+  comment.
+- `url` has no direct field in the thread-comment response either. Synthesize a best-effort
+  permalink from the PR's own web URL plus a `?discussionId=<threadId>` anchor (Azure
+  DevOps' web UI convention for deep-linking to a thread); fall back to the PR's own URL
+  with no anchor when this convention cannot be confirmed reliable for the target
+  organization, rather than risking a broken or misleading link (see Known Issues).
+
+### Writing data
+
+Before any write below, show the mandatory confirmation (per agentme-edr-127 rule 04):
+**System** (org/project/repo + PR number), **Operation**, **Fields** (exact verbatim text to
+post), **Estimated impact** (visible to PR participants, triggers notifications). Wait for
+explicit confirmation; never proceed on an assumed "yes."
+
+- Reply within an existing thread:
+  `az rest --method POST --uri ".../pullRequests/{n}/threads/{threadId}/comments?api-version=7.1" --body '{"content": "...", "parentCommentId": <id>}'`
+- Post a new general (non-file-scoped) comment as a new thread:
+  `az rest --method POST --uri ".../pullRequests/{n}/threads?api-version=7.1" --body '{"comments": [{"content": "..."}]}'`
+- Change thread status (the resolve/won't-fix equivalent):
+  `az rest --method PATCH --uri ".../pullRequests/{n}/threads/{threadId}?api-version=7.1" --body '{"status": "fixed"}'` (use `"wontFix"` or `"closed"` as appropriate instead of `"fixed"`).
+- Check out the PR branch: `az repos pr checkout --id <n>`.
+
+### Constraints
+
+- MUST use `az`/`az rest` for every read and write handled by this connector -- never fall
+  back to `curl`, another raw HTTP client, or scraping the PR's web UI, even when `az` is
+  missing, unauthenticated, or erroring, and even when the target data looks read-only.
+- MUST stop and follow the Authentication check steps above when `az` cannot complete a
+  request, instead of silently degrading to an alternative retrieval method.
+
+## Examples
+
+**Input**: fetch all comments for
+`https://dev.azure.com/contoso/Widgets/_git/widgets-api/pullrequest/1029`
+
+Runs `az repos pr show --id 1029` for metadata, then the single threads `az rest GET` call
+above, and returns a single normalized list built from every thread's comments.
+
+**Input**: reply to thread comment id `thread-comment/12.1` and set the thread to fixed
+
+Shows the mandatory confirmation summary first. On explicit "yes," posts the reply via the
+threads/comments `POST`, then updates thread status via the `PATCH` call.
+
+## Edge Cases
+
+- **Modern vs legacy URL formats**: recognize both
+  `dev.azure.com/{org}/{project}/_git/{repo}/pullrequest/{id}` and
+  `{org}.visualstudio.com/{project}/_git/{repo}/pullrequest/{id}` as valid Azure DevOps PR
+  URLs; extract org/project/repo/id from either shape.
+- **`threadContext` is `null`**: classify as a general PR-level comment, never as a parse
+  failure.
+- **PR-scoped ids**: never assume a thread or comment id is unique outside its PR; always
+  carry the PR number alongside when the tracking file persists an id.
+
+## Known Issues
+
+- **Symptom:** the `azure-devops` extension has no `az repos pr comment` or `az repos pr
+  thread` subcommand at all.
+  **Cause:** the extension only covers a subset of the Git PR API; thread and comment
+  operations were never added as first-class subcommands.
+  **Fix:** always use `az rest` with the documented REST endpoints above for every thread
+  and comment read or write; do not search for a nonexistent dedicated subcommand.
+- **Symptom:** a thread that should be resolvable cannot be updated; the `PATCH` call returns
+  HTTP 403 despite `az account show` showing a valid, logged-in session.
+  **Cause:** the authenticated identity lacks the "Contribute to pull requests" permission
+  on the repository.
+  **Fix:** degrade to reply-only for that thread, report the permission gap plainly, and
+  never retry the same call silently.
+- **Symptom:** `az rest` against a `dev.azure.com/.../_apis/...` URL fails most calls with
+  `TF400813: The user 'aaaaaaaa-aaaa-...' is not authorized`, or -- observed once, isolated
+  to a single call in an otherwise-failing batch -- exits 0 (looks successful) while the
+  write never actually appears when the thread is re-read.
+  **Cause:** `az rest` cannot always derive the correct Azure AD resource from the URL
+  alone and can silently fall back to an anonymous/placeholder identity; this has been
+  observed to be intermittent within a batch of otherwise-identical calls.
+  **Fix:** always pass `--resource 499b84ac-1321-427f-aa17-267ca6975798` (Azure DevOps'
+  well-known, tenant-agnostic AAD resource id) explicitly on every `az rest` call. Even
+  then, never treat a zero exit code alone as proof a write persisted -- read the thread
+  back afterward and verify the expected content/status is actually present before
+  reporting success. `400-pr-owner-assistant`'s `scripts/post-replies-azure-devops.js` does
+  this automatically for every write.
+- **Symptom:** a fetched thread has no obvious "kind" like GitHub's review-summary.
+  **Cause:** Azure DevOps genuinely has no equivalent concept -- every comment lives inside a
+  thread.
+  **Fix:** never emit a `"review-summary"` kind for this connector; always normalize to
+  `"thread-comment"`.
+- **Symptom:** an agent fetched PR metadata or thread comments via `curl`/direct REST calls
+  or by scraping the PR's web UI instead of using `az`/`az rest`.
+  **Cause:** `az` was missing, unauthenticated, or lacked the `azure-devops` extension, and
+  the agent treated a direct unauthenticated REST call or the rendered PR page as an
+  acceptable substitute since the target data looked read-only.
+  **Fix:** never substitute `az`/`az rest` with a direct HTTP call or a page scrape. Stop at
+  the Authentication check step, report the missing or failed `az` session plainly, and wait
+  for the human to install, extend, or authenticate `az` before retrying the same read or
+  write through `az`.
+- **Symptom:** a synthesized comment permalink (`url`) 404s, or lands on the PR overview
+  instead of the specific thread, when opened.
+  **Cause:** Azure DevOps' web UI deep-link format for a specific thread
+  (`?discussionId=<threadId>`) is a UI convention, not a documented, versioned part of the
+  REST API, and can vary by organization or Azure DevOps version.
+  **Fix:** verify the `?discussionId=<threadId>` anchor against a live PR in the target
+  organization before relying on it; degrade to the PR's own URL with no anchor when
+  uncertain, rather than guessing at a format that might mislead the human.
+
+## References
+
+- [`400-pr-owner-assistant`](../../../principles/skills/400-pr-owner-assistant/SKILL.md) -- consumes this connector's normalized output.
+- [`agentme-edr-127`](../../127-external-system-adapter-skills.md) -- external system adapter skill rules (connector naming, Known Issues format, HITL-before-write).
+- [`agentme-edr-124`](../../124-secrets-management.md) -- credential storage and retrieval.
+- [`agentme-core-adr-003`](../../../../../agentme-core/adrs/principles/003-skill-numbering-ranges.md) -- skill numbering ranges (250-299 base connectors).

package/.xdrs/agentme/edrs/application/skills/251-azure-devops-connector/SKILL.test.md

@@ -0,0 +1,114 @@
+---
+skill: 251-azure-devops-connector
+skill-version: "1.0"
+---
+
+## Test Scenarios
+
+### Scenario 1: Fetch and normalize thread comments, happy path
+
+**Trigger / Input**
+
+Fetch all comments for
+`https://dev.azure.com/contoso/Widgets/_git/widgets-api/pullrequest/1029`, a PR with one
+active file-scoped thread and one active general (PR-level) thread.
+
+**Expected Behaviour**
+
+The connector: (1) confirms `az account show` is authenticated; (2) runs
+`az repos pr show --id 1029`; (3) runs the single `az rest --method GET` threads call
+(there is no separate "list comments" call); (4) returns a normalized list where the
+file-scoped thread's comment has non-null `path`/`line` and `kind: "thread-comment"`, and
+the general thread's comment has null `path`/`line` and is still classified as a normal
+`"thread-comment"`, both with `status: "open"`.
+
+**Assertions**
+
+- [ ] Output normalizes every fetched comment to the shared record shape (id, kind, status,
+      can_reply, can_resolve, path, line, content, author, in_reply_to).
+- [ ] Output maps the thread `status: "active"` field to the normalized `status: "open"`.
+- [ ] Connector uses `az rest` for the threads read rather than searching for a dedicated
+      `az repos pr` comment subcommand.
+
+### Scenario 2: Null threadContext classified as a general comment, not an error
+
+**Trigger / Input**
+
+A fetched thread has `threadContext: null` in the raw API response.
+
+**Expected Behaviour**
+
+Per the Reading data normalization rule and the matching Edge Cases entry, the connector
+classifies this thread's comment as a general PR-level comment (`path`/`line` set to null in
+the normalized record) rather than treating the missing `threadContext` as a parsing failure
+or skipping the comment.
+
+**Assertions**
+
+- [ ] Connector includes the comment in its normalized output with `path`/`line` set to null.
+- [ ] Connector does not raise a parse error or silently drop the comment because of the
+      null `threadContext`.
+
+### Scenario 3: Thread status change writes via az rest PATCH with mandatory confirmation
+
+**Trigger / Input**
+
+Set thread id 12 on PR 1029 to resolved ("fixed") status after a fix was applied.
+
+**Expected Behaviour**
+
+The connector shows the mandatory System/Operation/Fields/Estimated impact confirmation
+(naming org/project/repo + PR number and the target status), waits for explicit
+confirmation, then issues
+`az rest --method PATCH --uri ".../pullRequests/1029/threads/12?api-version=7.1" --body '{"status": "fixed"}'`.
+No dedicated `az repos pr` subcommand is used for this operation.
+
+**Assertions**
+
+- [ ] Connector shows the mandatory confirmation before issuing the PATCH call.
+- [ ] Connector does not issue the PATCH call before explicit human confirmation.
+- [ ] Connector uses `az rest` rather than a nonexistent dedicated thread-status subcommand.
+
+### Scenario 4: Legacy visualstudio.com URL parses the same as a modern dev.azure.com URL
+
+**Trigger / Input**
+
+`https://contoso.visualstudio.com/Widgets/_git/widgets-api/pullrequest/1029` (legacy format)
+versus `https://dev.azure.com/contoso/Widgets/_git/widgets-api/pullrequest/1029` (modern
+format) for the same underlying PR.
+
+**Expected Behaviour**
+
+The connector extracts the same org (`contoso`), project (`Widgets`), repo
+(`widgets-api`), and PR id (`1029`) from either URL shape and proceeds identically from
+that point on.
+
+**Assertions**
+
+- [ ] Connector extracts identical org/project/repo/PR-id values from both URL formats.
+- [ ] Connector does not require the human to reformat a legacy URL before use.
+
+### Scenario 5: az unavailable or unauthenticated never triggers a curl/scrape fallback
+
+**Trigger / Input**
+
+Fetch PR metadata and thread comments for
+`https://dev.azure.com/contoso/Widgets/_git/widgets-api/pullrequest/1029` while `az account
+show` reports no session and no PAT is stored in the keychain (or `az`/the `azure-devops`
+extension is not installed).
+
+**Expected Behaviour**
+
+The connector does not issue any direct `curl`/HTTP request against the Azure DevOps REST
+API, and does not fetch or scrape the PR's web UI as a substitute -- even if the project
+looks publicly reachable. Instead it follows the Authentication check steps, reports the
+missing session/PAT or missing installation plainly, and halts every read and write until
+`az account show` succeeds or a keychain PAT is available.
+
+**Assertions**
+
+- [ ] Connector does not issue a `curl` or other raw HTTP request to any Azure DevOps
+      endpoint as a substitute for `az`/`az rest`.
+- [ ] Connector does not fetch or scrape the PR's web UI as a fallback.
+- [ ] Connector halts reads and writes and prompts for `az` installation/authentication
+      rather than degrading to an alternative retrieval method.

package/.xdrs/agentme/edrs/index.md

@@ -10,6 +10,7 @@ Foundational standards, principles, and guidelines.
 
 - [150-refine-plan-mode](principles/skills/150-refine-plan-mode/SKILL.md) - **Refine plan mode** — MANDATORY skill for ANY planning activity (plan, design, propose, outline, draft, brainstorm, architect). Read and follow in full before any execution begins. Must be read from XDRS even when not in `.agents/skills`. *(skill)*
 - [151-refine-user-story](principles/skills/151-refine-user-story/SKILL.md) - **Refine user stories** — Refine, elaborate, study or develop the contents of a user story used to create a unit of work for an agile team. Runs a structured 10-phase refinement process: understand the request, qualify requirements, research context, review consistency, validate visually, challenge from 9 user-perspective angles (Phase 6), challenge from 8 implementer-perspective angles (Phase 7), produce a ready-to-implement story (Phase 8), and run a final readiness double-check (Phase 9). *(skill)*
+- [400-pr-owner-assistant](principles/skills/400-pr-owner-assistant/SKILL.md) - **PR owner assistant** — Helps the OWNER of a pull request work through comments left by others: fetches every comment (GitHub or Azure DevOps) from its URL, tracks them in a local file, and walks through triaging each one (reply-question, won't-fix, work-on-a-fix) with explicit human confirmation at every step. A hands-on, mutating workflow to answer feedback and land fixes -- not a code-review skill. Delegates provider-specific reads/writes to `250-github-connector` or `251-azure-devops-connector`. *(skill)*
 - [agentme-edr-012](principles/012-continuous-xdr-enrichment.md) - **Continuous xdr improvement policy** - Promote recurring delivery lessons into reusable XDRs
 - [agentme-edr-016](principles/016-cross-language-module-structure.md) - **Cross-language module structure** - Organize modules consistently across supported languages
 - [agentme-edr-017](principles/017-skill-testing.md) - **skill testing** - Mandates a `SKILL.test.md` co-located with every skill in scopes that follow agentme; defines test scenario format (trigger, expected behaviour, assertions) and requires execution before merging any skill change *(includes skill: [200-run-skill-tests](application/skills/200-run-skill-tests/SKILL.md))*
@@ -30,6 +31,8 @@ Language and framework-specific tooling and project structure.
 - [agentme-edr-124](application/124-secrets-management.md) - **Secrets management** - Handle secrets securely using native keychains and cloud secret managers
 - [agentme-edr-125](application/125-coding-abstraction-practices.md) - **Coding abstraction practices** - Define when abstractions are justified and when they must be inlined
 - [agentme-edr-127](application/127-external-system-adapter-skills.md) - **External system adapter skills** - Priority-ordered approach and adapter skill authoring standards for automating interactions with external systems
+- [250-github-connector](application/skills/250-github-connector/SKILL.md) - **GitHub connector** — Base connector providing authentication, read access, and write access to GitHub pull requests and their comments via the `gh` CLI. *(skill)*
+- [251-azure-devops-connector](application/skills/251-azure-devops-connector/SKILL.md) - **Azure DevOps connector** — Base connector providing authentication, read access, and write access to Azure DevOps pull requests and their comment threads via the `az` CLI. *(skill)*
 
 ### Language and framework tooling
 

package/.xdrs/agentme/edrs/principles/017-skill-testing.md

@@ -57,6 +57,9 @@ specific enough that two independent agents produce comparable outputs.]
 
 Rules:
 - MUST contain at least two scenarios: one happy path and one edge or failure case.
+- MUST default to the 3 most relevant scenarios (typically the happy path plus the
+  highest-value edge/failure cases) and MUST NOT exceed 3 unless the user explicitly requests
+  more — larger suites cost more to execute and slow down verification.
 - Each scenario MUST have at least two assertions.
 - Assertions MUST be falsifiable (a pass/fail determination must be possible without ambiguity).
 - Assertion text MUST start with a verb ("Output contains …", "Skill asks …", "Review reports …").