--- name: Plan Create GitHub slug: plan-create-github category: AI Engineering description: Plan Create GitHub turns a GitHub issue into a phased implementation plan stored as parent and child issues. Use it to define the goal, context, and phase contracts before creating issues and linking them as native sub-issues. github: "https://github.com/CodelyTV/agent-harness/tree/main/.agents/skills/codely-plan-create-github" language: Shell stars: 242 forks: 6 install: "npx degit https://github.com/CodelyTV/agent-harness/tree/main/.agents/skills/codely-plan-create-github ~/.claude/skills/codely-plan-create-github" installs_to: ~/.claude/skills/codely-plan-create-github source_path: .agents/skills/codely-plan-create-github/SKILL.md collection_size: 6 category_size: 2793 collection_url: "https://dirskills.com/collections/CodelyTV/agent-harness" added: 2026-09-03T06:03:42.955Z last_synced: 2026-09-03T06:03:42.955Z canonical_url: "https://dirskills.com/skills/plan-create-github" --- # Plan Create GitHub Plan Create GitHub turns a GitHub issue into a phased implementation plan stored as parent and child issues. Use it to define the goal, context, and phase contracts before creating issues and linking them as native sub-issues. **Install:** ```bash npx degit https://github.com/CodelyTV/agent-harness/tree/main/.agents/skills/codely-plan-create-github ~/.claude/skills/codely-plan-create-github ``` ## README # ๐Ÿง  How to create a plan > [!CRITICAL] > Do NOT create or edit any GitHub issue until the user has agreed on the specific public contracts to be considered and the implementation phases. Propose first, get approval, then create the issues. The structure of a plan, its sections and the rules to shape them are defined in [`resources/plan-guidelines.md`](resources/plan-guidelines.md). Read it before proposing anything. ## ๐ŸŽฏ Input This skill is invoked as `/codely-plan-create-github `. - `` is the URL of the GitHub issue describing the task to plan. **This issue becomes the parent "plan" issue.** - If no URL is provided, ask the user for it before doing anything else. ## ๐Ÿ—‚๏ธ Repository All the plan lives as GitHub issues in the repository of the current working directory. Never hardcode a repository: let `gh` resolve it from the local Git remote. ```bash gh issue view gh issue create --title "..." --body "..." gh issue edit --body "..." ``` Derive `` from the provided URL. Confirm the repository `gh` resolves with `gh repo view --json nameWithOwner --jq .nameWithOwner`, and check that the provided URL belongs to it. If it does not, stop and ask the user to run the skill from the clone of that repository. To link a phase as a **native GitHub sub-issue** of the parent, use the sub-issues REST API. It expects the child's numeric database `id` (not its issue number), so resolve it first. The `{owner}` and `{repo}` placeholders are substituted by `gh` with the current repository: ```bash # Resolve the child issue database id from its number child_id=$(gh api repos/{owner}/{repo}/issues/ --jq .id) # Attach the child as a native sub-issue of the parent gh api --method POST repos/{owner}/{repo}/issues//sub_issues -F sub_issue_id="$child_id" ``` ## ๐Ÿงฑ Issue structure A plan is stored as a **tree of issues**, using GitHub's **native sub-issues** feature: - **Parent "plan" issue**: the issue whose URL was passed in. It holds the `Goal`, the `Context`, the agreed design decisions, and a **checklist of the phases**, each item linking its child issue. The parent depends on its children: when every child issue is closed, the parent closes too. - **One child issue per phase**: each holds the phase description and its to-do actions as a checkbox list, plus a reference back to the parent (`Part of #`). Every child is attached to the parent as a **native GitHub sub-issue** (via the sub-issues API), not only as a checklist link. ``` #12 Product Bundles (parent plan) Goal / Context / design decisions - [ ] #13 Phase 1: ... - [ ] #14 Phase 2: ... #13 Phase 1: ... (child, to-do checkboxes) #14 Phase 2: ... (child, to-do checkboxes) ``` ## ๐Ÿชœ Steps to create a plan 1. **Read the task** from the parent issue with `gh issue view `. 2. Define task phases, letting the user choose the amount of phases as described in the guidelines. 3. Specify the public contracts to be created/modified/deleted on each phase task, as described in the guidelines. 4. Propose the plan to the user for approval. IMPORTANT: Do not create any issue until the user has agreed on the specific contracts to be considered and the implementation phases. 5. **Create one child issue per phase** with `gh issue create`. Each child issue body must contain: - The phase description. - The phase to-do actions as a checkbox list (`- [ ] ...`). - The public contracts for that phase. - A `Part of #` reference line. Capture the number of every child issue returned by `gh`. 6. **Attach every child as a native sub-issue of the parent.** For each child, resolve its database id and link it to the parent with the sub-issues API (see the snippet in the Repository section above): ```bash child_id=$(gh api repos/{owner}/{repo}/issues/ --jq .id) gh api --method POST repos/{owner}/{repo}/issues//sub_issues -F sub_issue_id="$child_id" ``` Do this for every phase, in order, so the parent lists all phases as native sub-issues. 7. **Update the parent issue** with `gh issue edit --body ...` so its body contains the `Goal`, `Context`, agreed design decisions and a `Phases` checklist that links every child issue (`- [ ] # Phase N: `). Preserve the original task description from the parent issue: keep it as-is and append the new plan content below it, separated by a `---` line (do not lose or rewrite the original text). 8. Suggest next steps. Ask the user what do they want to do: - Do not do anything else. - Implement the plan by executing the `/codely-plan_phase-implement-github <parent-issue-url>` skill (implements Phase 1 only). - Implement a specific phase by executing the `/codely-plan_phase-implement-github <child-issue-url>` skill. > [!IMPORTANT] > `/codely-plan_phase-implement-github` handles one phase per invocation. Never implement all phases at once. ## ๐Ÿ—ƒ๏ธ Plan metadata GitHub issues have no YAML frontmatter, so add the plan metadata as a footer at the end of the **parent** issue body: ```markdown --- <sub>Created by { tool } ยท { model.name } { model.version } (reasoning effort: { model.reasoning_effort }) ยท { current_date }</sub> ``` - `current_date`: The current date in the format ISO 8601 RFC 3339 (`YYYY-MM-DDTHH:MM:SSZ`). - `tool`: The AI coding tool used (e.g. `Claude Code`, `Cursor`, `Copilot`, `Codex`) - `model.name`: The name of the model used to make the change (e.g. `Claude Opus`, `Cursor Composer`, `OpenAI GPT`) - `model.version`: The version of the model used to make the change (e.g. `4.6`, `1.5`, `5.4`) - `model.reasoning_effort`: The reasoning effort of the model used to make the change (e.g. `low`, `medium`, `high`) ## ๐Ÿ—‚๏ธ Where each plan section lives The parent issue holds the `Goal`, the `Context`, the `Phases` checklist and the `Next step` sections described in [`resources/plan-guidelines.md`](resources/plan-guidelines.md). Each child issue holds the description and the to-do actions list of its own phase. As the phases are implemented through pull requests, the last to-do action of every phase asks for pull request titles instead of commit messages.