# agdt-initiate-update-jira-issue-workflow

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

## TL;DR

Starts the update-an-existing-Jira-issue workflow. An issue key is required.
When run outside the issue's worktree/branch, pre-flight fails and a background
auto-setup creates the worktree, opens VS Code, and starts a Copilot session.
When run in-context, the command pre-fetches the issue details and renders the
`make-updates` prompt (or the `initiate` prompt if the fetch fails), then starts
a Copilot session.

## Parameters & State Keys

### CLI flags

| Flag | Effect | Default |
|------|--------|---------|
| `--issue-key` | Jira issue key to update. Required (falls back to `jira.issue_key`). | none |
| `--user-request` / `-u` | Free-text explanation of the desired updates. | 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 |
|-----|------|
| `jira.issue_key` | Issue under update (required state). |
| `jira.user_request` | Free-text request describing the updates. |
| `jira.summary` / `jira.description` / `jira.comment` | Optional fields consumed by the prompt template. |
| `jira.issue_summary` / `jira.issue_type` / `jira.issue_labels` / `jira.issue_description` / `jira.issue_comments` | Pre-fetched issue fields persisted for prompt re-rendering. |
| `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. **Issue key resolution** — from `--issue-key` or `jira.issue_key`; missing
   exits `1`.
2. **Pre-flight** — PASS proceeds in-context; FAIL spawns the background
   auto-setup.
3. **Pre-fetch outcome** — success renders the `make-updates` step (skipping
   `initiate`); failure falls back to the `initiate` step with a manual fetch
   instruction.
4. **`--skip-copilot-session`** — skips the session on the in-context path.
5. **`--interactive`** — attached vs background session.
6. **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 and clear workflow tracking state; set
   `copilot.model_id`.
3. Resolve the issue key from the CLI or state; exit `1` if missing.
4. Run the pre-flight check.
5. **Pre-flight FAIL** → build the nested auto-execute command and call
   `perform_auto_setup("update-jira-issue", ...)`; on success print the message
   and return.
6. **Pre-flight PASS** → re-persist `jira.issue_key` into the active state
   directory, pre-fetch the issue details, and persist the resulting
   `jira.issue_*` fields.
7. Choose the step: `make-updates` when issue data is available, else
   `initiate`. Render that step's prompt via `initiate_workflow(...)`.
8. When `--skip-copilot-session` is not set, start the Copilot session for the
   update-jira-issue workflow (passing the chosen step).

## 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-get-issue-details-response.json` (when the pre-fetch
  succeeds), and the rendered prompt
  (`temp-update-jira-issue-make-updates-prompt.md` or
  `temp-update-jira-issue-initiate-prompt.md`).
- **Workflow state** set to `update-jira-issue` at the chosen step.
- **Background task** record + logs (preflight-fail path).
- **Jira** — read-only fetch of the issue for the prompt context.
- **Process / VS Code** — a new VS Code window and a `gh copilot` session
  (in-context path, unless skipped).

## Success Criteria

1. Missing issue key exits `1`.
2. On the in-context path the issue is pre-fetched and the workflow reaches the
   `make-updates` step with the prompt rendered (or `initiate` when the fetch
   fails).
3. On the preflight-fail path the worktree is created and a Copilot session is
   prepared via auto-setup.
4. `agdt-get-workflow` shows `name=update-jira-issue` with the correct issue-key
   context.

## AI Agent Session Choreography

update-jira-issue is effectively **single-step from the agent's perspective**:
the rendered prompt is a self-contained three-step playbook (snapshot → update →
verify). The workflow has two prompt variants — `initiate` and `make-updates` —
but they describe the same agent steps; `make-updates` is used when the
pre-fetch succeeds (it embeds the current issue state), and `initiate` is the
fallback when the fetch fails.

### Session entrypoint

- The `gh copilot` session opens on `temp-update-jira-issue-make-updates-prompt.md`
  (see `_start_copilot_session_for_update_jira_issue` and
  `_WORKFLOW_PROMPT_FILENAMES["update-jira-issue"]` in
  [`worktree_setup.py`](../../agentic_devtools/cli/workflows/worktree_setup.py)).
  When the in-context pre-fetch fails, the `initiate` prompt is rendered instead
  and the agent runs `agdt-get-jira-issue` itself first.
- This is also the entrypoint the **create-jira-issue/epic/subtask** workflows
  hand off to after creating a placeholder (the agent fleshes out the placeholder
  here).

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

| Step | What the prompt asks | Commands the agent is expected to run |
|------|----------------------|---------------------------------------|
| 1. Pre-update snapshot | Document the current issue state before changing it | `agdt-add-jira-comment --jira-comment "h4. Pre-Update Snapshot ..."` |
| 2. Make updates | Set only the fields that change; update in one call | `agdt-set jira.summary "..."`, `agdt-set jira.description "..."`, then `agdt-update-jira-issue` |
| 3. Verify | Confirm summary/description/ACs are correct and nothing was lost | Review the auto-refreshed issue output from `agdt-update-jira-issue` |

The prompt explicitly scopes the workflow to **metadata only** (no code changes)
and tells the agent to ask for clarification if the request is ambiguous.

### Subagents

No workflow state-machine subagents are spawned. The `@agdt.update-jira-issue.*`
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 --> Key{Issue key available}
    Key -- No --> ExitKey[Print error and exit 1]
    Key -- Yes --> Preflight{In correct worktree and branch}
    Preflight -- No --> AutoSetup[Spawn background worktree auto-setup]
    AutoSetup --> Return[Print success and return]
    Preflight -- Yes --> Fetch[Pre-fetch Jira issue details]
    Fetch --> StepSel{Issue data available}
    StepSel -- Yes --> MakeUpdates[Render make-updates prompt and set workflow state]
    StepSel -- No --> InitiateStep[Render initiate prompt and set workflow state]
    MakeUpdates --> Session{Skip copilot session set}
    InitiateStep --> Session
    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-update-jira-issue-workflow.md` and
**specialize** it for your exact command and flags before executing.
