# agdt-initiate-create-jira-subtask-workflow

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

## TL;DR

Creates a new Jira **Sub-task** under a parent issue and sets up a worktree to
flesh it out. When no issue key is supplied, the command creates a placeholder
Sub-task under the parent and spawns a background auto-setup that hands off to
the update-jira-issue workflow. When an issue key is supplied and pre-flight
passes, it renders the create-jira-subtask prompt in-context and starts a
Copilot session. A parent key is required to create the placeholder (and on the
preflight-fail auto-setup path).

## Parameters & State Keys

### CLI flags

| Flag | Effect | Default |
|------|--------|---------|
| `--parent-key` | Parent issue key. Required to create the placeholder. Falls back to `jira.parent_key`. | none |
| `--issue-key` / `-i` | Continuation key (after a placeholder exists). | none |
| `--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.parent_key` | Parent issue key (required state for the create-subtask prompt). |
| `jira.issue_key` | Continuation/created Sub-task key. |
| `jira.user_request` | Free-text request used to populate fields. |
| `jira.summary` / `jira.description` | Optional fields consumed by the prompt template. |
| `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. |

The target project key is derived from the parent key (the segment before the
first `-`). When `--issue-key` is omitted, stale issue-selection keys are
cleared so the create flow 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 Sub-task;
   absent triggers placeholder creation.
2. **With issue key — pre-flight** — PASS renders the create-subtask prompt
   in-context; FAIL requires a parent key (exit `1` if missing) then spawns the
   create-jira-subtask auto-setup.
3. **Without issue key — parent key required** — missing parent key exits `1`;
   otherwise a placeholder Sub-task is created under the parent.
4. **Placeholder creation** — on success hand off to the update-jira-issue
   workflow via auto-setup; on failure exit `1`.
5. **`--skip-copilot-session`** — skips the session on the in-context PASS 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 and clear workflow tracking state; when no issue key
   is given, clear stale issue-selection keys.
3. Set `copilot.model_id`; persist any provided `parent_key`, `issue_key`,
   `user_request`.
4. Resolve values; re-persist `jira.issue_key` and `jira.parent_key` into the
   active state directory.
5. **Issue key present** →
   - pre-flight PASS → `initiate_workflow("create-jira-subtask", ...)` (requires
     `jira.parent_key`) then start the Copilot session (unless skipped).
   - pre-flight FAIL → require a parent key (exit `1` if missing), then
     `perform_auto_setup("create-jira-subtask", additional_params=parent_key)`.
6. **Issue key absent** → require a parent key (exit `1` if missing), create a
   placeholder Sub-task under the parent. 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 Sub-task is created under the parent (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-subtask-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-subtask prompt is rendered and the
   workflow state is `create-jira-subtask`.
2. Without an issue key, a placeholder Sub-task is created under the parent and
   auto-setup hands off to the update-jira-issue workflow.
3. Missing parent key exits `1` on both the preflight-fail and no-issue-key
   paths.
4. Failure to create the placeholder exits `1` with a clear message.
5. The created placeholder Sub-task key is recorded for follow-up and cleanup.

## AI Agent Session Choreography

Like the other create workflows, this is **single-step**: the rendered initiate
prompt is a self-contained playbook the agent follows within one session.

### Session entrypoint

- **In-context PASS path** (issue key present): the `gh copilot` session opens on
  `temp-create-jira-subtask-initiate-prompt.md` (see
  `_start_copilot_session_for_create_jira_subtask` and
  `_WORKFLOW_PROMPT_FILENAMES["create-jira-subtask"]` in
  [`worktree_setup.py`](../../agentic_devtools/cli/workflows/worktree_setup.py)).
  The prompt asks the agent to review the parent issue for context and define a
  clear, single-session-sized subtask scope, then create the subtask.
- **No-issue-key path:** the command creates a *placeholder* Sub-task under the
  parent 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`, where the agent
  fleshes out the placeholder (see the update-jira-issue choreography).

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

```bash
agdt-set jira.parent_key <PARENT-KEY>
agdt-set jira.summary "<subtask summary>"
agdt-set jira.description "<detailed description>"
agdt-create-subtask   # background task; monitor with agdt-task-wait
```

The prompt emphasizes good vs poor subtask examples and warns against subtasks
that are too large (which should be their own story).

### Subagents

No workflow state-machine subagents are spawned by this command. The
`@agdt.create-subtask` 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. The
`break-down-issue-into-subtasks` workflow drives this command repeatedly (once
per identified subtask).

## 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 subtask 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 --> ParentChk1{Parent key available}
    ParentChk1 -- No --> ExitParent1[Print error and exit 1]
    ParentChk1 -- Yes --> AutoSetupCreate[Spawn auto-setup for create subtask]
    AutoSetupCreate --> Return1[Print success and return]
    HasKey -- No --> ParentChk2{Parent key available}
    ParentChk2 -- No --> ExitParent2[Print error and exit 1]
    ParentChk2 -- Yes --> Placeholder[Create placeholder subtask under parent]
    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-subtask-workflow.md` and
**specialize** it for your exact command and flags before executing.
