# agdt-initiate-apply-pr-suggestions-workflow

> **General template.** Copy this file to
> `.agdt-temp/EXPECTATIONS-agdt-initiate-apply-pr-suggestions-workflow.md` and
> specialize it for your exact command and flags before executing.

## TL;DR

Starts the apply-pull-request-review-suggestions workflow, which applies review
feedback to a PR's branch. A PR id is required. The command tries to derive the
Jira issue key from the PR source branch when one is not supplied. If an issue
key is known and pre-flight fails, a background auto-setup creates the worktree
and starts a Copilot session; otherwise the workflow is initiated in-context,
the review state is copied into the apply-suggestions directory, and a Copilot
session starts. There is no `--engine` flag for this workflow.

## Parameters & State Keys

### CLI flags

| Flag | Effect | Default |
|------|--------|---------|
| `--pull-request-id` | PR whose review suggestions to apply. Falls back to `pull_request_id`. Required by initiation. | none |
| `--issue-key` / `-i` | Jira issue key for context and worktree scope. Derived from the PR branch when omitted. | none |
| `--interactive true\|false` | Start the Copilot session attached vs background. | `false` |
| `--model <id>` | Copilot model for the session. | project config or `gpt-4o` |
| `--skip-copilot-session` | Skip starting a Copilot session (used by nested auto-execute). | off |

### State keys

| Key | Role |
|-----|------|
| `pull_request_id` | PR under work (required by `initiate_workflow`). |
| `jira.issue_key` | Issue key for context (provided or derived from the PR branch). |
| `pr_details` | When present, its `sourceRefName` is used to derive the issue key. |
| `copilot.model_id` | Persisted model id for the session. |
| `background.task_id` | Background auto-setup task id (preflight-fail path). |
| `worktree_setup.*` | Parameters consumed by the background setup task. |

### Environment overrides

| Variable | Effect |
|----------|--------|
| `AGENTIC_DEVTOOLS_STATE_DIR` | Pins the state directory and skips bootstrap scope derivation. |
| `AGDT_DRY_RUN` / `dry_run` state | Preview mode honored by downstream action commands. |
| `AGDT_AUTO_TRUST_COPILOT` | Optional kill-switch for auto-trusting agdt-managed worktree folders before Copilot launch (`0`/`false`/`no`/`off` disables). |

## Decision Points / Paths

1. **Identifier scope** — `issue_key` over `PR{pull_request_id}`; providing one
   without the other clears the stale counterpart.
2. **Issue-key derivation** — when no issue key is supplied, it is derived from
   the PR source branch (via `pr_details.sourceRefName`) when available.
3. **Pre-flight (only when an issue key is known)** — PASS proceeds to in-context
   initiation; FAIL spawns the background auto-setup. When no issue key is known,
   pre-flight is skipped and the workflow is initiated in-context directly.
4. **Required PR id** — `initiate_workflow` validates `pull_request_id`; a
   missing value exits `1`.
5. **`--skip-copilot-session`** — skips the session on the in-context path.
6. **`--interactive`** — attached vs background session.
7. **Copilot folder trust seeding** — after a worktree is validated/created (not
   before), the workflow best-effort seeds Copilot CLI `trustedFolders` for that
   path (gated by `AGDT_AUTO_TRUST_COPILOT` and project flag
   `auto_trust_copilot_worktrees`).

## Execution Flow

1. Parse flags; resolve `model`.
2. Resolve bootstrap scope (issue key over PR id) and clear workflow tracking
   state; set `copilot.model_id`.
3. Persist the provided identifiers (issue key first when both are present),
   clearing the stale counterpart when only one is given.
4. When no issue key is resolved, try to derive one from the PR source branch.
5. **Issue key known** → run the pre-flight check:
   - FAIL → `perform_auto_setup("apply-pull-request-review-suggestions",
     additional_params=pull_request_id)`; on success print and return.
   - PASS → fall through to in-context initiation.
6. Re-persist the identifiers, then
   `initiate_workflow("apply-pull-request-review-suggestions", ...)` (requires
   `pull_request_id`).
7. Copy the current review state into the apply-suggestions directory.
8. When `--skip-copilot-session` is not set, start the Copilot session for the
   apply-suggestions workflow.

## Observable Side Effects

- **Worktree** — created on the preflight-fail path, with VS Code settings
  injected.
- **State directory** `.agdt/workflows/{identity}/{worktree_key}/` containing
  `state.json`, `temp-apply-pull-request-review-suggestions-initiate-prompt.md`,
  and an `apply-suggestions/` directory holding the applied-suggestions state
  (with a snapshot of `reviews/review-state.json` when present).
- **Workflow state** set to `apply-pull-request-review-suggestions`.
- **Background task** record + logs (preflight-fail path).
- **Process / VS Code** — a new VS Code window and a `gh copilot` session
  (in-context path, unless skipped).

## Success Criteria

1. The PR id is required; a missing value exits `1`.
2. The issue key is derived from the PR branch when not supplied (when branch
   data is available).
3. On the preflight-fail path the worktree is created and a Copilot session is
   prepared via auto-setup.
4. On the in-context path the workflow is initiated, the review state is copied
   into the apply-suggestions directory, and a Copilot session starts (unless
   skipped).
5. `agdt-get-workflow` shows `name=apply-pull-request-review-suggestions` with
   the correct PR context.

## AI Agent Session Choreography

apply-pull-request-review-suggestions is **single-step**: the rendered initiate
prompt is a self-contained playbook the agent follows within one session.

### Session entrypoint

- The `gh copilot` session opens on
  `temp-apply-pull-request-review-suggestions-initiate-prompt.md` (see
  `_start_copilot_session_for_apply_pr_suggestions` and
  `_WORKFLOW_PROMPT_FILENAMES["apply-pull-request-review-suggestions"]` in
  [`worktree_setup.py`](../../agentic_devtools/cli/workflows/worktree_setup.py)).
- The setup copies the existing `reviews/review-state.json` into the
  apply-suggestions directory so the agent works from the reviewers' recorded
  verdicts.

### Step-by-step choreography (within the single session)

| Step | What the prompt asks | Commands the agent is expected to run |
|------|----------------------|---------------------------------------|
| 1. Retrieve feedback | Load the PR and its review comments | `agdt-set pull_request_id <id>`, `agdt-get-pull-request-details` |
| 2. Categorize | Sort suggestions into *Must Fix* / *Should Fix* / *Consider* | (reasoning; no command) |
| 3. Apply changes | Address Must-Fix first, then Should-Fix, evaluate Consider; add tests where applicable | edit code, run repo tests |
| 4. Respond to reviewers | Resolve each thread or reply with rationale | `agdt-resolve-thread` / `agdt-reply-to-pull-request-thread` |
| 5. Update the PR | Amend the single commit (auto-detected) and push | `agdt-git-save-work` |
| 6. Record on Jira | Note the addressed feedback on the linked issue | `agdt-set jira.comment "..."`, `agdt-add-jira-comment` |

The prompt's quality gate requires all *Must Fix* items addressed, tests passing,
and the build succeeding before re-requesting review.

### Subagents

No workflow state-machine subagents are spawned. The `@agdt.apply-pr-suggestions.*`
Copilot Chat agents map to this prompt. An auditing agent running
[`agdt.test-workflow`](../../.github/prompts/agdt.test-workflow.prompt.md) spawns
a rubber-duck subagent to review its specialized expectations document.

## Workflow Diagram

```mermaid
flowchart TD
    Start([Command invoked]) --> Parse[Parse flags and resolve model]
    Parse --> Scope[Bootstrap scope and clear tracking state]
    Scope --> Ids[Persist provided identifiers]
    Ids --> HasKey{Issue key available}
    HasKey -- No --> Derive[Derive issue key from PR branch if possible]
    Derive --> HaveKey{Issue key available}
    HasKey -- Yes --> HaveKey
    HaveKey -- Yes --> Preflight{In correct worktree and branch}
    Preflight -- No --> AutoSetup[Spawn background worktree auto-setup]
    AutoSetup --> Return[Print success and return]
    Preflight -- Yes --> ReqPR{PR id available}
    HaveKey -- No --> ReqPR
    ReqPR -- No --> ExitPR[Print error and exit 1]
    ReqPR -- Yes --> Initiate[Render apply suggestions prompt and set workflow state]
    Initiate --> Copy[Copy review state into apply-suggestions directory]
    Copy --> Session{Skip copilot session set}
    Session -- Yes --> SyncDone[Return without session]
    Session -- No --> Copilot[Start Copilot session]
```

---

This is a **general template**. Copy it to
`.agdt-temp/EXPECTATIONS-agdt-initiate-apply-pr-suggestions-workflow.md` and
**specialize** it for your exact command and flags before executing.
