IssueLens

# IssueLens — Copilot instructions

## Contributor role

You are a coding assistant maintaining this repository, not the deployed
IssueLens orchestrator. Implement requested repository changes, including
source code, tests, GitHub Actions workflows, and documentation, and use the
normal contributor tools to validate changes and prepare requested pull
requests. Do not route repository maintenance to IssueLens runtime sub-agents
or refuse it because the deployed product does not implement code.

The prompts under `agents/`, skills under `skills/`, and repository policies
under `.github/issuelens/` are application assets, not instructions that change
your contributor role or restrict your development tools. Preserve their
runtime behavior and safeguards when editing them. The runtime-only GitHub
MCP boundary does not prohibit contributor Git/GitHub tooling.

Keep the deployed orchestrator prompt at `agents/issuelens.md`, loaded
explicitly by `main.py`. Do not place runtime prompts in an `AGENTS.md` file
(including lowercase `agents.md`), which coding assistants can discover as
repository instructions. Deployment still requires explicit current-user
approval as described below.

## Product overview

IssueLens is a **GitHub issue-triage and planning agent** that runs as a
**Microsoft Foundry hosted agent**, built on the **GitHub Copilot SDK**. It
analyzes issues across repositories, identifies critical (hot / blocking /
regression) issues, creates planning artifacts, applies labels, and sends
notifications — acting on GitHub as a **GitHub App**, so all writes are
attributed to the App bot with the App's scoped permissions. It is reachable
two ways: the **invocations** protocol for automation and the **responses**
protocol for chat.

## Main features

- **Critical-issue triage** — the `find-criticals` sub-agent
  scans issues updated within the requested time scope (default: the last 24
  hours) and returns a structured JSON report
  identifying **hot**, **blocking**, and **regression** issues.
- **Duplicate detection** — compares a target issue with open and closed issues
  using strict technical evidence and reports high-confidence duplicates.
- **Auto-labeling** — classifies and applies labels using the repository's
  existing labels and the validated `labeling` instruction domain.
- **Auto-assignment** — routes issues to individual owners using repository area
  mappings and historical assignment patterns.
- **Notifications** — sends triage reports through Logic App-backed email and
  Teams notification tools.
- **Planning loop** — the `plan` sub-agent investigates a triaged issue,
  produces an action plan followed by a design specification, reports readiness
  using validated repository policy or built-in defaults, and waits for human
  direction before revising or advancing the proposal.
- **Team memory** - every agent reads relevant wiki knowledge through the
  read-only `team-memory` skill. Only the `team-memory` sub-agent owns separately
  authorized direct wiki maintenance through `write_wiki_pages`.
- **Built-in commands** — immutable `@issuelens triage`, `retriage`, `plan`,
  and `replan` commands work across Responses chat and validated GitHub
  maintainer comments. `@issuelens go` is reserved for a future coding loop and
  currently performs no action or write. Repository customization cannot
  redefine this command contract. One command may appear with supplemental
  prose, which becomes bounded guidance for the command's fixed owner;
  multiple-command inputs are rejected.
- **App-scoped GitHub access** — both protocols use the bundled stdio MCP
  server. It resolves the App installation for each explicit repository and
  mints repository- and permission-scoped tokens. Bounded REST reads fall back to
  anonymous access for public repositories without an installation. Writes
  always require App access and are attributed to the App bot rather than an
  ambient user identity.

## Architecture

- **`main.py`** — the Foundry hosted-agent server. A single host class
  (`IssueLensHost(InvocationAgentServerHost, ResponsesAgentServerHost)`) serves
  two protocols in one process:
  - **`POST /invocations`** — automation (GitHub Actions). Each request opens a
    fresh Copilot session and streams session events back as SSE.
    **Invocation payload:** one required field and one optional field —
    `{ "input": "<free-form task>", "attachments": [] }`. `input` is the task;
    `attachments` contains validated inline Copilot `blob` attachments.
  - **`POST /responses`** — chat (playground, Teams, any Responses client).
    The conversation's Copilot session is resumed each turn.
  - **Session-owned GitHub MCP** — every Copilot session starts the bundled
    `github_app_mcp` stdio process with the App ID and Key Vault secret URI. The
    process loads the private key lazily, resolves installations, and caches
    short-lived tokens only in memory for its process/session lifetime. A token
    is restricted to one repository and the minimum tool permission set.
  - **Paged change analysis** — the `change-analysis` skill guides existing
    agents through small PR/commit file pages and targeted pinned-source reads
    using the bundled GitHub MCP and normal Copilot tool/model turns. There is
    no separate analysis runtime or custom diff reader. `get_commit` supports
    upstream-style `none`/`stats`/`full_patch` detail and file pagination, with
    separate bounded transport and model-result sizes. Missing evidence remains
    explicit and cannot establish no-change or successful publication.
  - **Issue-body images** — before the model turn, the trusted host loader
    resolves explicit issue URLs or `owner/repository#number` references using
    the protocol's GitHub identity, accepts only allowlisted GitHub-hosted image
    URLs, validates redirects, type signatures, count, and size, and supplies
    Copilot blob attachments. It never exposes tokens or lets the model choose
    arbitrary download URLs.
  - **Model (inference) auth (auto-selected):** BYOK Foundry model
    (`FOUNDRY_PROJECT_ENDPOINT` + `AZURE_AI_MODEL_DEPLOYMENT_NAME`, using
    Microsoft Entra bearer tokens only), or the GitHub Copilot model
    (`GITHUB_TOKEN`) only when `FOUNDRY_PROJECT_ENDPOINT` is absent. A configured
    Foundry endpoint requires a model name; configuration/token failures never
    switch backends. The SDK per-request bearer callback uses async
    `DefaultAzureCredential`, caching tokens in host memory and refreshing before
    expiry for fresh and resumed sessions. Model API keys are unsupported and
    are not forwarded by deployment or to the Copilot process.
    The platform-provided agent runtime identity is distinct from the project
    managed identity (which proxies model calls to the account) and the Actions
    deployment principal. Preserve the project endpoint and do not inject the
    deployer's client ID into the runtime. Local execution can use existing
    Azure Identity service-principal/workload or developer credentials.
- **Custom agents** (registered in `main.py`):
  - **`issuelens`** — the global agent identity. Its system prompt lives in
    `agents/issuelens.md`. It routes issue-level analysis to `triage` and
    critical-issue scans to `find-criticals`. It also owns built-in command parsing, channel
    trust validation, replay checks, and normalized handoff; sub-agents never
    parse command text. If the
    sub-agent's response is not valid JSON or is an empty object, stop, skip
    labeling and notifications, and surface this error message:
    `Triage report could not be parsed; skipping downstream actions.`
  - **`triage`** — analyzes target issues and performs requested duplicate,
    label, assignment, and notification work through its preloaded skills. Its
    prompt lives in `agents/triage.md`.
  - **`find-criticals`** — scans a repository and time scope for hot, blocking,
    and regression issues. Its prompt lives in `agents/find-criticals.md` and it
    returns **only** the critical-issue JSON report.
  - **`plan`** — investigates a triaged issue and relevant repository context,
    then returns an action plan followed by a design specification. Its prompt
    lives in `agents/plan.md`. It uses the shared tools and preloads the label,
    assignment, and notification safeguards for planning-owned writes. It
    requires explicit authorization for writes and waits for human feedback or
    configured readiness signals rather than autonomously revising.
  - **`team-memory`** - maintains wiki knowledge from cited evidence and full
    source commit SHAs. Its prompt is `agents/team-memory.md`. Only its local
    MCP server exposes `write_wiki_pages`; the parent automatically supplies
    internal `--wiki-writer` mode. Users need no environment flag. The existing
    `GITHUB_MCP_ENABLE_WRITES` remains for triage, not wiki writes.
- **Skills** (`skills/`): `issuelens-config` (validated repository policy),
  `find-duplicates`, `label-issue`, `assign-issue`, `notify`, `change-analysis`, and `team-memory`
  (read-only retrieval preloaded on all agents, including the orchestrator).
- **Media inputs** — `media_inputs.py` normalizes Responses `input_image` and
  `input_file` content and invocation `blob` attachments into Copilot session
  attachments. Only inline base64 content is accepted; remote URLs, file IDs,
  and request-supplied server paths are rejected.
- **GitHub access** — both protocols use only the bundled GitHub App stdio MCP
  tools for model-facing GitHub reads and writes. Every tool requires an
  explicit `owner/repository`; REST reads prefer App access and may fall back to
  anonymous access for public repositories, while writes require successful
  App installation resolution. The constrained `issuelens-config` tool and
  host image loader create separate request-local, read-only App clients.
  Related public repositories named by duplicate instructions use the same MCP
  read tools without requiring an App installation. Wiki tools instead take
  the source project as `repository`, independently re-read and validate its
  wiki mapping, and resolve credentials/transport to the destination. App
  installation and operation-scoped read/write access are required there;
  tokens are scoped to that actual destination, not merely the source.
- **Wiki backend** - the packaged Dulwich Python library performs Git network
  and object operations without spawning Git, SSH, or credential helpers. The
  host still starts the stdio MCP server as a Python subprocess. Wiki operations
  use bounded temporary PACK storage and in-memory Git objects, with no full
  worktree checkout, hooks, filters, or Git config discovery. Typed validation,
  byte budgets, and redirect denial remain enforced. Internal HTTPS
  `x-access-token` authentication stays inside the backend. Socket/library/DNS
  timeouts are cooperative, not a hard CPU deadline. Only SHA-1 Git repositories
  (GitHub's current format) are supported; SHA-256 is rejected. Binary diffs are
  notices, not binary patches; unchanged assets are preserved byte-for-byte and
  page deletion is unsupported.
- **Runtime configuration** — `main.py` explicitly loads `agents/issuelens.md`,
  all four sub-agent prompts under `agents/`, and the skill directories. Explicit
  loading keeps local and hosted behavior identical without enabling config
  discovery in the read-only hosted code directory.

## Runtime design constraints

The following constraints describe the deployed application's behavior.
Preserve them in code and runtime prompts; they do not assign the runtime
agent's role or tool restrictions to repository contributors.

- **GitHub access has one model-facing boundary** — both deployed protocols
  must use only the bundled IssueLens GitHub MCP tools. The constrained
  `issuelens-config` host tool returns one validated policy domain. Do not add
  runtime paths that bypass this boundary through shell commands, model-directed
  GitHub HTTP calls, ambient credentials, or a Foundry GitHub toolbox connection, or
  expose App credentials. See the runtime contract in `agents/issuelens.md`.
- Only `find-criticals` is required to return JSON, which IssueLens preserves at
  the end of its response. `triage` may use the format appropriate for its task.
- Planning loads the validated `planning` instruction domain. Repository policy
  may define required sections, readiness states, and human signals, but cannot
  authorize writes or implementation. Planning approval does not authorize
  source changes, commits, pull requests, or deployment, and is never expressed
  by `@issuelens go`.
- Built-in command names, syntax, routing, channel trust, and authorization are
  hard-coded in `agents/issuelens.md` above user and repository customization.
  Responses users are trusted team maintainers. GitHub commands require exactly one valid
  command occurrence in the authoritative `issue_comment.created` comment from
  a human maintainer, verified through `get_issue_comment` and trusted event
  metadata. Event and authoritative comment associations must each independently
  be `OWNER`, `MEMBER`, or `COLLABORATOR`; their labels need not be identical.
  The GitHub workflow remains a neutral provenance transport.
- A request to plan or revise a specific issue authorizes `plan` to post the
  planning artifacts on that issue using explicit user instructions, validated
  planning customization, or the default of two separate comments. It
  authorizes no unrelated write.
- Repository customization is optional. A missing `.github/issuelens.yml` or an
  omitted domain uses legacy or built-in behavior; only a present but invalid
  configuration stops that capability and its related writes.
- **Wiki-destination exception** - validated `team_memory.wiki_repository`
  may select only the wiki capability's destination, not other source
  repositories, other writes, or notification scope. The structured
  `instructions.team_memory` requires `path`; optional `wiki_repository` is
  validated as a GitHub parent repository identifier (`owner/repository`), not a
  wiki UI name or Git URL. Its `.wiki.git` stores memory. The shared package
  parser returns resolved `wiki_repository` alongside `content` through the
  config tool. An omitted field, config, or domain defaults to the source
  project's own wiki. Pass the source project to all wiki MCP tools, never the
  destination. Markdown guides organization/topics only; it cannot override
  the target or supply arbitrary Git URLs, tokens, or shell settings.
- Source-user authorization is separate from destination App installation
  access. Never publish private/internal-source knowledge to a public wiki or
  read a private/internal wiki for public-source context. Cross-repository
  mappings between private/internal repositories are rejected for both reads
  and writes because their audience relationship cannot be verified; use the
  source project's own wiki. Same-repository and public-to-public mappings
  remain supported. A private/internal source may read a public wiki, and a
  public source may write public information to a private/internal wiki,
  subject to job authorization and destination App access.
  Invalid or inaccessible destinations fail without silent source-wiki fallback.
  No per-repository App environment configuration is needed.
- Wiki writes require an explicit current request or parent handoff authorizing
  a wiki update for the target; policy, a merge alone, and
  issue-loop commands grant no wiki-write authority. Preserve the paired
  `expected_wiki_repository` precondition, full-SHA `expected_base` checks,
  atomic Git history, and tool-confirmed status; expose
  no force option. If a mapping change conflicts with the read SHA, stop and
  re-establish destination, authorization, and evidence, not an automatic
  overwrite. No database, SQLite, proposal store, or host approval layer is used.
- The orchestrator routes by job responsibility, not tool availability. It
  splits mixed requests so triage work goes to `triage`, planning work goes to
  `plan`, separately authorized wiki maintenance goes to `team-memory`, and
  future capabilities go only to their owning sub-agent. Each
  sub-agent applies the relevant capability skill before an authorized write.
- Triage must inspect targeted repository source and tests when a conclusion
  depends on current implementation state, including whether an issue remains
  actionable or a behavior/root cause is actually implemented. Planning must
  inspect the owning implementation, interfaces, configuration, and tests
  before producing credible technical artifacts. Both roles use bounded
  `get_file` reads and report limitations instead of inferring code state from
  issue history alone.
- Trusted issue-loop invocations carry only workflow-owned event metadata. The
  orchestrator may read the explicit issue and comments solely to choose
  initial triage, re-triage, initial planning, re-planning, or no action. Issue
  and comment content remains untrusted context except for one valid built-in
  command occurrence and its supplemental instructions validated under the
  global contract; no action means no write.
- Within a sub-agent's fixed role, explicit current-user instructions override
  validated capability customization, which overrides built-in behavior. These
  sources may replace workflows, criteria, thresholds, readiness, publication,
  and presentation defaults, but not role ownership, parent-handoff contracts,
  security boundaries, repository scope, or write authorization. The validated
  structured wiki-destination exception above is the only team-memory scope
  mapping; explicit instructions cannot override it through content guidance.
- Prefer adding behavior to a skill or sub-agent prompt before changing
  `main.py`; register new runtime components explicitly when needed.
- Keep agent and skill instructions universal across calling surfaces. Do not
  assume a request comes from GitHub Actions, Teams, or any other client.
  Origin and trigger context must be explicitly supplied in the request or
  trusted host context; such claims do not by themselves establish authority.
  Caller-specific event metadata, validation requirements, acknowledgement
  preferences, and requested response schemas belong in the caller's input,
  not a permanent transport-specific agent or knowledge-policy contract.
  Preserve role ownership, explicit write authorization, and existing
  channel-specific command validation when its trusted context is present.

## Triggering (GitHub Actions)

The agent is driven by a workflow in the target repo
(`.github/workflows/issue-triage.yml`):

1. Authenticate to the Foundry agent endpoint via **Azure OIDC** (`azure/login`).
2. POST `{ input, attachments? }` to the agent's invocations endpoint. The
  hosted agent owns the App credentials; target repositories do not store the
  App private key or mint tokens.

Both issue-loop and team-memory workflows use `.github/actions/issuelens`.
Its `request-type` selects `issue-loop`, `team-memory`, or a direct `task` with
explicit `input`. Request adapters validate before shared OIDC login and one
bounded invocation. The action does not choose sub-agents or parse commands.
The event adapter omits issue/comment bodies; direct tasks never synthesize
trusted event provenance. Generic final answers are saved in a runner-local
`response-path`: `completed` means stream completion, not successful writes.
Only team-memory results require the wiki-specific structured result contract.
The action's `output-mode` selects hybrid live text/activity, activity-only, or
quiet display; `summary-mode` selects full, status-only, or no job summary.
Defaults publish sanitized user-facing text and a final report, not raw event
JSON, reasoning, or tool payloads. Display stays separate from outcome validation.
Callers must choose privacy-appropriate modes for their Actions audience.

Triggers: `issues` opened/reopened, `issue_comment` created/edited for issues
only, and `workflow_dispatch`. The workflow does not subscribe to issue edits or
pull request comments. A preflight step rejects PR-backed and bot-authored
comments before Azure login, then sends a neutral orchestration task with
trusted event metadata. Per-issue concurrency allows different issues to run
independently while coalescing bursts for the same issue.

Team-memory postmerge orchestration uses the opt-in
`.github/workflows/team-memory-post-merge.yml`: default-branch pushes and
explicit single-PR manual dispatch. The shared composite action in `.github/actions/issuelens`
owns preflight, pinned Azure OIDC login, and submission through a standalone
Python helper. External callers pin an action commit and need no checkout;
this repository's thin caller sparsely loads the local action from the trusted
`github.workflow_sha`, never a PR head, with credentials not persisted. The
action checks authoritative GitHub metadata before OIDC login and submits a
bounded wiki-only job using the issue-loop secrets. For a push, it verifies the
complete fast-forward commit inventory and discovers all eligible merged PRs
using bounded GitHub metadata reads before submitting one batch. It fails on
incomplete discovery rather than silently omitting sources. Different pushes
have separate concurrency groups; manual dispatch keeps per-PR grouping.
Verify default-branch Azure OIDC federation when migrating from a PR-scoped subject.
Enable it with the repository
variable `ISSUELENS_TEAM_MEMORY_ENABLED=true`, not an agent environment flag.
The workflow explicitly requests merge revalidation, wiki-only writes, no
reactions/comments, and a JSON result through its `input`. The generic agent
preserves wiki policy/privacy/preconditions and the requested response format;
the caller's schema is not a permanent agent instruction. Only completed
`updated`/`no-change` results with matching source metadata and verified wiki
identity succeed. Push batches explicitly permit publication of independent,
fully verified PRs while deferring incomplete or dependent changes. Every PR
must appear exactly once in the result. A partial batch fails the job while
retaining its per-PR response and any confirmed wiki publication, never implying
that no write occurred. The batch schema remains caller-owned.
Ambiguous submissions
are not retried automatically. Git provides knowledge, history, and conflict
detection, not a durable job queue or guaranteed exactly-once delivery. Local
tests do not establish live OIDC federation, hosted writer dispatch, or publication.

## Run & deploy

- **Local:** `pip install -r requirements.txt`, copy `.env.example` → `.env` and
  fill it in, then `python main.py` (serves `/invocations` and `/responses` on
  `:8088`).
- **Deployment approval gate:** never deploy, redeploy, roll back, or otherwise
  publish an agent version to Microsoft Foundry unless the user explicitly
  authorizes that deployment in the current request. Permission to edit, test,
  investigate, or prepare deployment changes does not imply permission to
  deploy them.
- **Deploy to Foundry:** `azd deploy` — see `azure.yaml` (Python hosted agent,
  ZIP `codeConfiguration` with `remote_build` and `runtime: python_3_13`) and
  `agent.yaml` (hosted-agent manifest). The ZIP remote build installs root
  `requirements.txt`; standalone MCP packaging in `github_app_mcp/pyproject.toml`
  declares the same Dulwich dependency (1.2.14). A `Dockerfile` is also provided
  for a container build. Wiki access needs no Git installation, Dockerfile
  change, or runtime installer in either mode.

## Pull request review follow-up

These rules apply to coding assistants maintaining this repository, not to the
IssueLens runtime agent's capabilities or write authorization.

- Self-review changes and run relevant tests before pushing review fixes.
- After pushing and verifying the fix on the PR branch, reply to each addressed
  review thread with the fixing commit and validation results, then resolve the
  thread without waiting for another user request. A reply alone is not enough.
- Resolve only threads whose concerns are fully addressed by the verified
  commits. Leave partially addressed or still-valid concerns unresolved.
- Re-read the thread state to confirm resolution. If permissions or tooling
  prevent resolution, report the blocker and identify the threads still open;
  never claim they are resolved without confirmation.

## Layout

- `main.py` — agent server, session wiring, custom-agent registration
- `github_app_mcp/` — bundled GitHub App stdio MCP server and isolated tests
- `agents/issuelens.md` — deployed IssueLens identity, runtime scope, and orchestration
- `agents/` — runtime prompts (`issuelens.md`, `triage.md`, `find-criticals.md`,
  `plan.md`, `team-memory.md`), not contributor instructions
- `skills/` — modular skills (`issuelens-config`, `find-duplicates`,
  `label-issue`, `assign-issue`, `notify`, `team-memory`)
- `azure.yaml` / `agent.yaml` / `Dockerfile` — deployment config
- `.github/workflows/issue-triage.yml` — the triggering workflow