---
name: develop-task
description: Coordinate repository development through a read-only task issue, one tracker sub-issue, delegated pull-request shepherding, and merge-aware Test or Staging validation. Use when work begins from a task issue or needs tracker and deploy routing; use shepherd-pull-request instead for pull-request-only work.
---

# Develop Task

## Task Issue And Tracker Issue

- **Task issue:** Read it for the problem, outcome, and acceptance criteria. Do
  not modify its title, body, labels, comments, or state.
- **Tracker issue:** Use one tracker issue for execution state, next steps,
  phases, and pull requests. Update it throughout execution.

Make the tracker a direct sub-issue of the task issue. Do not create, link, or
reconcile sub-issues under the tracker. Keep phases and workstreams in the
tracker. Do not turn the task issue into the tracker or use it for progress
updates. Markdown links may add context but do not satisfy the sub-issue link.

Resolve the task issue before creating or reusing a tracker. If it cannot be
resolved, stop and ask the user.

Read the task issue and its discussion before deriving phases or updating the
tracker. Use current repository and GitHub state to resolve conflicts. Do not
edit the task issue.

## Source-To-Tracker Link

Maintain only the `task issue -> tracker issue` edge:

1. Resolve the parent and child GraphQL issue IDs independently with `gh api
   graphql`, and query the child's `parent { id }` in the same request. Require
   all reads to succeed.
2. If the current parent ID matches the target parent ID, make no
   mutation.
3. If the child has a different parent ID, stop. Do not remove or replace that
   relationship unless the user asks.
4. Only if the tracker has no parent, call `addSubIssue` with the resolved task
   and tracker IDs and `replaceParent: false`.
5. Re-read the child and require its `parent.id` to match the target
   parent ID before proceeding or reporting success.

Do not modify other issue relationships. Stop on API errors, permission errors,
rate limits, missing nodes, or failed verification. Do not fall back to
issue-body edits, comments, or Markdown links.

## Tracker Issue

Before creating a tracker, inspect the task issue's direct sub-issues and search
for trackers that reference it. Reuse one match. If none exists, create one. If
multiple issues match, stop and ask the user.

Create or reuse the tracker before opening the first pull request. Link every
pull request from the tracker.

Treat the tracker as current state, not history. Update it when execution state
changes and remove obsolete or completed items. Keep only active and upcoming
phases and unmet completion conditions. After a pull request merges, reflect
its result in the tracker and remove its phase.

Do not add progress history, completed checklists, commit hashes, branch names,
timestamps, run IDs, command output, blocker ledgers, or evidence ledgers. Do
not update the tracker if its content would not change.

## Pull Requests

Use `$shepherd-pull-request` for every pull-request creation, update, review
response, rebuttal, stacked-branch propagation, readiness decision, and merge.
That skill is authoritative for pull-request scope, title and body, exact-head
Codex Review handling, guarded pushes, stack maintenance, and merge gates. Load
and follow it instead of reproducing those rules here.

`develop-task` owns only the task-level integration:

1. Create or reuse the tracker before the first pull request.
2. Give the shepherd the task outcome, acceptance criteria, active phase, and
   tracker link.
3. Link every pull request from the tracker and keep only active or upcoming
   pull-request phases there.
4. When the shepherd reports an exact merged state, re-read it, remove the
   completed phase from the tracker, and use that merged state for the Test or
   Staging decision below.

Do not infer that task tracking authorizes a merge, release, or Production
deployment. Those actions retain their own authority boundaries.

## Deploy And Test

When a plan includes both deployment and testing, deployment must not wait for
pull-request review or merge. Codex Review gates merge, not deployment to Test.

Treat every implementation, integration, pin, lock, lineage, or other change
needed to assemble the deployed candidate as required. A required change that
is not represented by a merged pull request counts as unmerged. Resolve the
exact candidate commits across all required repositories before dispatch.

- If any required pull request is unmerged, immediately deploy the exact
  candidate to the configured Test environment with workflow-supported
  immutable refs, then run the planned tests there. For a multi-repository
  stack, use the deployment-owner candidate to pin or resolve every required
  candidate. Creating, reviewing, approving, or merging a pull request must not
  delay Test deployment once deployable candidate refs exist. Do not merge a
  pull request merely to make the candidate deployable.
- If every required pull request is merged and the normal Staging ref contains
  or pins every merged change, deploy the merged candidate to Staging and run
  the planned tests there. Do not deploy unmerged code to Staging.

Unrelated open pull requests do not affect this decision. Re-evaluate the
required refs immediately before every dispatch. A changed candidate head
requires a new Test deployment. If the final required pull request merges while
a Test deployment is running, do not cancel that deployment solely because of
the transition; route the next deployment to Staging. Test evidence does not
bypass review or replace required Staging validation. This policy selects only
Test or Staging and never authorizes a Production deployment or release.