gh-kickoff

name	gh-kickoff
description	Create a GitHub repo (or use an existing one), scaffold files, then turn a plan into milestones and issues.
allowed-tools	Bash Read Write Glob Grep
argument-hint	[repo-name] [--public] [--no-readme] [--no-changelog] [--org <name>]

GH Kickoff

Bootstrap a GitHub project from a plan. Creates the repo (or detects an existing one), scaffolds README and CHANGELOG, then creates milestones and issues from the plan in the current conversation.

When to Use

• The user says "kickoff", "gh-kickoff", "bootstrap this project", or "set up the repo"
• The user has a plan (in conversation context or a file) and wants it turned into GitHub milestones and issues
• The user wants to create a new repo and immediately populate it with project management structure

Input

The user provides one or more of:

• A repo name (e.g., lately) — creates it under the authenticated user's account by default
• Flags to override defaults (see below)
• A plan in the conversation context, or a file path to a plan

Arguments and flags:

Arg/Flag	Default	Description
<repo-name>	(inferred from cwd if in a repo)	Name of the repo to create
--public	false (private)	Make the repo public instead of private
--no-readme	false (include README)	Skip README.md scaffolding
--no-changelog	false (include CHANGELOG)	Skip CHANGELOG.md scaffolding
--org <name>	(authenticated user)	Create under an org instead of personal account

Workflow

Follow all steps in order. Do not skip steps. Present findings to the user at each checkpoint and wait for confirmation before proceeding.

Step 0 — Detect Environment

Check gh is available:

gh auth status

If gh is not installed, tell the user:

"This skill requires the GitHub CLI (gh). Install it from https://cli.github.com/ and run gh auth login to authenticate."

Stop here. Do not attempt workarounds.

Check if already in a GitHub repo:

git remote get-url origin 2>/dev/null

• If a GitHub remote exists (Path B): Extract the org/repo from the remote URL. Confirm with the user:

  "You're already in <org>/<repo>. I'll skip repo creation and go straight to creating milestones and issues. Sound right?"

  Wait for confirmation. If confirmed, skip to Step 4. The --public, --no-readme, and --no-changelog flags are ignored in Path B.

• If no remote exists (Path A): A <repo-name> argument is required. If not provided, ask:

  "What should the repo be called?"

  Wait for the user's response before continuing.

Step 1 — Create the Repository (Path A only)

Determine the owner. If --org was provided, use that. Otherwise, create under the authenticated user's personal account (no org prefix needed).

gh repo create <repo-name> --private --clone

If --org was provided:

gh repo create <org>/<repo-name> --private --clone

If --public was passed, replace --private with --public.

If the command fails (name conflict, permission error), show the user the error output and say:

"Repo creation failed. Check the error above — usually it's a name conflict or a permissions issue."

Stop here. Do not proceed with a failed create.

cd into the cloned repo directory.

Step 2 — Scaffold Files (Path A only)

README.md (unless --no-readme was passed):

Generate a README with the project title derived from the repo name and a placeholder description. Keep it minimal — this is a starting point, not a finished document.

# <Project Title>

> TODO: Add project description.

CHANGELOG.md (unless --no-changelog was passed):

Use references/changelog-template.md as the base. Fill in the project name.

Step 3 — Initial Commit and Push (Path A only)

Stage the scaffolded files and create the initial commit:

git add README.md CHANGELOG.md
git commit -m "chore: initial project scaffold"
git push -u origin main

Only include files that were actually created (respect --no-readme and --no-changelog).

Step 4 — Parse the Plan

Read the plan from one of these sources, in priority order:

1. A file path if provided by the user
2. The plan in the current conversation context (e.g., from a prior planning step or a scoping document)

If no plan is found in either location, ask:

"I don't see a plan in our conversation or a file path. Can you paste the plan or tell me where to find it?"

Wait for the user's response before continuing.

Parse the plan into milestones and tasks:

• Group related tasks into milestones that represent logical phases of work
• Name milestones with a sequential prefix: 1 - Setup and Configuration, 2 - Core Implementation, 3 - Testing and Validation, etc.
• For each milestone, write a 1-2 sentence description summarizing what the milestone achieves and why it matters in the sequence
• For each task, derive a label type from its content, aligning with commitlint conventions:

Label	When to use
feat	New functionality, new endpoints, new UI
fix	Bug fixes, corrections
docs	Documentation, comments, READMEs
chore	Config, setup, scaffolding, dependencies
refactor	Restructuring without behavior change
test	Adding or updating tests
ci	CI/CD pipeline changes

Present the parsed structure to the user for confirmation:

Here's how I'd break this down:

Milestone 1 - [Name] [Description]

• feat — [Task title]
• chore — [Task title]

Milestone 2 - [Name] [Description]

• feat — [Task title]
• test — [Task title]

Does this look right? Want to move, rename, or re-label anything before I create these?

Wait for the user to confirm or request changes. Iterate until they approve.

Step 5 — Create Labels

Collect the unique label types from Step 4. For each one, check if it already exists on the repo:

gh label list --repo <org>/<repo> --json name --jq '.[].name'

Create any missing labels:

gh label create "<label>" --repo <org>/<repo> --description "<description>" --color "<color>"

Use these colors:

Label	Color	Description
feat	0e8a16	New feature
fix	d73a4a	Bug fix
docs	0075ca	Documentation
chore	cfd3d7	Maintenance
refactor	a2eeef	Code restructuring
test	bfd4f2	Tests
ci	e4e669	CI/CD

Step 6 — Create Milestones

Create milestones in order using the GitHub API:

gh api repos/<org>/<repo>/milestones --method POST --field title="<milestone-title>" --field description="<milestone-description>"

Store the returned milestone number for each so issues can reference them.

If a milestone with the same title already exists, use the existing one instead of creating a duplicate.

Step 7 — Create Issues

Create issues in order within each milestone. Process milestones sequentially (Milestone 1 first, then 2, etc.) and tasks within each milestone in order. This ensures issue numbers track logically with the plan.

For each task, create an issue with a structured body:

gh issue create --repo <org>/<repo> \
  --title "<title>" \
  --label "<label>" \
  --milestone "<milestone-title>" \
  --body "<body>"

Title format: Clear and actionable, commitlint-style. Examples:

• feat: implement IP allowlist validation endpoint
• chore: configure Firebase project and deploy pipeline
• test: add integration tests for allowlist CRUD operations

Body structure:

## Context

[Why this task exists. Where it fits in the milestone. Background from the plan
that helps someone — human or LLM — understand the motivation and constraints.]

## Task

[What specifically needs to be accomplished. Implementation details, endpoints,
files, patterns, data structures — whatever the plan provides. Be specific enough
that an LLM can pick this up and start working without chasing down the original
plan.]

## Acceptance Criteria

- [ ] [Concrete, verifiable condition]
- [ ] [Another concrete, verifiable condition]
- [ ] [Derived from the plan's task description]

## Dependencies

- Depends on #N [if earlier issues in the sequence are prerequisites]
- No dependencies [if this is the first task or is independent]

The body should be rich enough that someone opening the issue cold — whether a developer or an LLM — has full context to start working.

Step 8 — Summary

After all milestones and issues are created, present a summary:

Project kickoff complete.

Repository: <org>/<repo> ([link]) Milestones: N created Issues: N created

Milestone	Issues	Labels
1 - Setup and Configuration	#1, #2, #3	chore, docs
2 - Core Implementation	#4, #5, #6, #7	feat, refactor
...	...	...

Issues are numbered in execution order. Start with #1.

Resources

• references/changelog-template.md — Keep a Changelog seed for new repos
• references/issue-body-template.md — Structural guide for issue bodies