# agdt-initiate-create-jira-issue-workflow

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

## TL;DR

Creates a new Jira issue and sets up a worktree to flesh it out. When no issue
key is supplied, the command first creates a **placeholder** issue, then spawns
a background auto-setup that hands off to the update-jira-issue workflow in a new
worktree. When an issue key is supplied and pre-flight passes, the command
renders the create-jira-issue prompt in-context and starts a Copilot session;
when pre-flight fails it spawns the create-jira-issue auto-setup.

## Parameters & State Keys

### CLI flags

| Flag | Effect | Default |
|------|--------|---------|
| `--project-key` | Jira project key for the new issue. Falls back to `jira.project_key`. | `PROJECT` |
| `--issue-key` / `-i` | Continuation key (after a placeholder exists). | none |
| `--issue-type` / `-t` | Issue type for the placeholder/issue. | `Story` |
| `--user-request` / `-u` | Free-text explanation the agent uses to populate fields. | 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.project_key` | Target project (resolved default persisted as `PROJECT`). |
| `jira.issue_key` | Continuation/created issue key. |
| `jira.issue_type` | Issue type (default `Story`). |
| `jira.user_request` | Free-text request used to populate fields. |
| `copilot.model_id` | Persisted model id for the session. |
| `background.task_id` | Background auto-setup task id. |
| `worktree_setup.*` | Parameters consumed by the background setup task. |

When `--issue-key` is omitted, stale `issue_key` / `jira.issue_key` values from a
prior workflow are cleared so the create flow always starts fresh.

### 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 present vs absent** — present continues an existing issue; absent
   triggers placeholder creation.
2. **With issue key — pre-flight** — PASS renders the create prompt in-context;
   FAIL spawns the create-jira-issue auto-setup.
3. **Without issue key — placeholder creation** — on success the command hands
   off to the update-jira-issue workflow via auto-setup; on failure it exits `1`.
4. **`--skip-copilot-session`** — skips the session on the in-context PASS 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; when no issue key
   is given, clear stale issue-selection keys.
3. Set `copilot.model_id`; persist any provided `project_key`, `issue_key`,
   `issue_type`, `user_request`.
4. Resolve values (project key default `PROJECT`, issue type default `Story`);
   persist the project-key default.
5. **Issue key present** →
   - pre-flight PASS → `initiate_workflow("create-jira-issue", ...)` then start
     the Copilot session (unless skipped).
   - pre-flight FAIL → `perform_auto_setup("create-jira-issue", ...)` and return.
6. **Issue key absent** → create a placeholder issue of the resolved type. On
   failure exit `1`. On success persist the new key, build an update-style
   user request, compute the branch name, and `perform_auto_setup(...)` targeting
   the **update-jira-issue** workflow.

## Observable Side Effects

- **Jira** — a new placeholder issue is created (no-issue-key path). This is a
  durable side effect that must be tracked for cleanup.
- **Worktree** — created via auto-setup (FAIL or no-issue-key paths), with VS
  Code settings injected.
- **State directory** `.agdt/workflows/{identity}/{worktree_key}/` containing
  `state.json` and, on the in-context path,
  `temp-create-jira-issue-initiate-prompt.md`.
- **Background task** record + logs (auto-setup paths).
- **Process / VS Code** — a new VS Code window and a `gh copilot` session
  (in-context path, unless skipped).

## Success Criteria

1. With an issue key in-context, the create prompt is rendered and the workflow
   state is `create-jira-issue`.
2. Without an issue key, a placeholder issue is created and auto-setup hands off
   to the update-jira-issue workflow in a new worktree.
3. Failure to create the placeholder exits `1` with a clear message.
4. Stale issue-selection state is cleared when no issue key is provided.
5. The created placeholder issue key is recorded for follow-up and cleanup.

## AI Agent Session Choreography

Unlike the multi-step workflows, create-jira-issue is **single-step**: the
rendered initiate prompt is a self-contained playbook the agent follows within
one session — there are no state-machine transitions to advance through.

### Session entrypoint

- **In-context PASS path** (issue key present): the `gh copilot` session opens on
  `temp-create-jira-issue-initiate-prompt.md` (see
  `_start_copilot_session_for_create_jira_issue` and
  `_WORKFLOW_PROMPT_FILENAMES["create-jira-issue"]` in
  [`worktree_setup.py`](../../agentic_devtools/cli/workflows/worktree_setup.py)).
  The prompt instructs the agent to gather a summary, description, issue type,
  and **acceptance criteria** (the prompt embeds unit/E2E/integration test and
  documentation decision trees), then create the issue.
- **No-issue-key path:** the command creates a *placeholder* issue first and then
  **hands off to the update-jira-issue workflow** via auto-setup. The Copilot
  session in the new worktree therefore opens on the update workflow's
  `temp-update-jira-issue-make-updates-prompt.md`, and the agent fleshes out the
  placeholder there (see the update-jira-issue choreography).

### Commands the agent is expected to run (in-context create path)

```bash
agdt-set jira.project_key <PROJECT>
agdt-set jira.summary "<issue summary>"
agdt-set jira.description "<detailed description + acceptance criteria>"
agdt-create-issue   # background task; monitor with agdt-task-wait
```

The prompt requires every issue to carry explicit acceptance criteria and walks
the agent through the test/documentation decision trees before
`agdt-create-issue` is called.

### Subagents

No workflow state-machine subagents are spawned by this command. The
`@agdt.create-issue` Copilot Chat agent maps to this same 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 --> HasKey{Issue key provided}
    HasKey -- Yes --> Preflight{In correct worktree and branch}
    Preflight -- Yes --> Initiate[Render create issue prompt and set workflow state]
    Initiate --> Session{Skip copilot session set}
    Session -- Yes --> SyncDone[Return without session]
    Session -- No --> Copilot[Start Copilot session]
    Preflight -- No --> AutoSetupCreate[Spawn auto-setup for create issue]
    AutoSetupCreate --> Return1[Print success and return]
    HasKey -- No --> Placeholder[Create placeholder issue]
    Placeholder --> PHOK{Placeholder created}
    PHOK -- No --> ExitPH[Print error and exit 1]
    PHOK -- Yes --> AutoSetupUpdate[Spawn auto-setup handing off to update workflow]
    AutoSetupUpdate --> Return2[Print success and return]
```

---

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