agile-github-task-from-diff

name	agile-github-task-from-diff
description	Create a GitHub Task (sub-issue) from the current git diff vs main and link it as a sub-issue of a parent Feature in the local GitHub Project. Use when Codex needs to summarize branch changes into a horizontally sliced task with acceptance criteria and create it via `gh`.
models	{"claude":"sonnet","copilot":"auto","codex":"gpt-5.4"}

Task From Diff

Overview

Generate a GitHub Task issue from the current branch diff versus main. The task is horizontally sliced — scoped to one technical layer (backend, tests, docs, ai-tooling, config) — and added to the local GitHub Project as a sub-issue of a vertically sliced parent Feature issue.

Workflow

1. Ensure the repo has an up-to-date origin/main (or override the base ref).
2. Run a dry run to review the generated title, body, and acceptance criteria.
3. Create the task issue, add it to the project, and optionally link it as a sub-issue of the Feature.
4. Rename the current branch to match the <type>/<issue>-short-description naming standard using the newly created issue number — see Rename Branch After Creation.

Script

Use scripts/create_github_task_from_diff.py.

# Preview (dry run)
python3 .agents/skills/agile-github-task-from-diff/scripts/create_github_task_from_diff.py --dry-run

# Create task, add to project #1, link as sub-issue of Feature #42 (number or issue URL)
python3 .agents/skills/agile-github-task-from-diff/scripts/create_github_task_from_diff.py --feature-issue 42

# Combine flags from the Inputs table as needed, e.g.:
python3 .agents/skills/agile-github-task-from-diff/scripts/create_github_task_from_diff.py \
  --feature-issue 42 --base-ref main --title "Add persistence layer tests" --open

Inputs

Flag	Default	Description
--feature-issue	(none)	Parent Feature issue — accepts an issue number (42) or a full GitHub issue URL (https://github.com/.../issues/42). When set, the task is linked as a sub-issue.
--title	(generated)	Override the auto-generated task title.
--repo	(from remote)	GitHub repo as owner/repo. Auto-detected when omitted.
--project	1	GitHub project number under the org.
--no-project	—	Create the issue only; skip adding it to any GitHub Project.
--org	(repo owner)	GitHub org that owns the project. Defaults to the repo owner detected from the git remote.
--label	task	Label applied to the created issue.
--base-ref	origin/main → main	Override base ref for the diff.
--dry-run	—	Print output without creating anything.
--open	—	Open the created issue in the browser.

Behavior

• Computes the diff from merge-base between HEAD and the base ref.
• Classifies the diff into horizontal layers: backend, tests, documentation, ai-tooling, config, general.
• Builds a title from the detected layers and affected top-level areas.
• Generates an acceptance criteria checklist based on touched paths.
• Creates the issue via gh issue create.
• Adds the issue to the GitHub Project via gh project item-add.
• Links the issue as a sub-issue of the parent Feature via the GitHub REST API (gh api POST /repos/.../sub_issues).

Rename Branch After Creation

After the task issue is created, rename the current local branch so it conforms to the <type>/<issue>-short-description standard enforced by the git-commit-push-pr skill and .agents/rules/git/git-policy.instructions.md (the source of truth). This guarantees the downstream PR title and Closes #<issue> link can be derived from the branch name.

The script prints a ready-made suggestion after creating the issue (Suggested branch rename: git branch -m <type>/<issue>-<slug>) — it derives <type> from the dominant horizontal layer, <issue> from the new issue number, and the slug from the task title. Run that command (no commit/push is performed by this skill). Override the <type> if the diff is better described by fix/refactor than the layer mapping suggests.

Notes:

• Skipped on --dry-run — nothing is created, so there is no issue number to rename against.
• If a conforming <type> or slug cannot be determined, stop and ask the user — do not guess, matching the format-enforcement rule in git-policy.instructions.md.
• If the branch was already pushed, the rename stays local; the subsequent git-commit-push-pr run pushes the renamed branch (its --issue handling parses the same number back out of the branch name).

Vertical vs Horizontal Slicing

Concept	Owner	Description
Feature (parent)	Product	Vertically sliced — one complete user-facing capability across all layers.
Task (this skill)	Engineer	Horizontally sliced — one technical layer of work from the diff (e.g. just the backend changes, or just the test changes).

Requirements

• gh CLI authenticated with a token that has repo and project scopes.
• git available in the repo.
• The task label must exist in the target repo (create with gh label create task --color 0075ca).

Troubleshooting

• If gh issue create fails, run gh auth status to verify authentication.
• If gh project item-add fails, ensure your token has the project scope (gh auth refresh -s project).
• If the sub-issue API call fails, the script prints a fallback message; link manually in the GitHub UI.
• If the diff is empty, ensure your branch contains changes against main or override --base-ref.