Skip to main content

FOR EVERYONE — a tutorial. Follow it top to bottom and you will ship one real change.

Your first issue → PR

This is a tutorial: a guided first run. By the end you will have created a tracked issue, made one small change on its own branch, opened a pull request, and merged it — the full loop the kit is built around. It takes about ten minutes and assumes nothing beyond a working install.

If you have not installed the kit yet, do Install first, then come back.

:::note What you need

  • The kit installed and /kit-init already run in a git project (see Install).
  • The GitHub CLI authenticated (gh auth status prints a green check). /kit-doctor checks this.
  • A clean working tree (git status shows nothing to commit) on your integration branch. :::

The loop you are about to learn​

/kit-task-new    →  a tracked GitHub issue (#N)
/kit-task-start  →  a branch + worktree for #N
   …make one change…
/kit-task-pr     →  a pull request that closes #N
/kit-task-pr-merge  →  merged; back on your integration branch

Every step is one command in the chat. You never leave the conversation.

Step 1 — Create the issue​

Tell the kit what you want to do. Keep it tiny for this first run — a typo fix or a one-line README edit is perfect.

/kit-task-new

Describe the change when asked (for example: "Fix the typo in the README intro"). The kit files a GitHub issue, applies labels, and adds it to your board. Note the number it prints back — call it #N.

:::tip Pick something trivial The goal here is to learn the loop, not to write code. The smaller the change, the faster you reach your first merged PR. :::

Step 2 — Start the work​

/kit-task-start N

This branches from your integration branch, creates an isolated worktree for the task, and marks the issue In Progress on the board. You are now on task/N-… — your change is sandboxed and cannot disturb anyone else's work.

Step 3 — Make the change​

Make your one small edit — ask the kit in plain language, or edit the file yourself. For the README example:

Fix the typo in the first paragraph of README.md.

Keep it to a single, obvious change. Save the file.

Step 4 — Open the pull request​

/kit-task-pr N

The kit commits your change, pushes the branch, and opens a pull request whose body says Closes #N. The PR inherits the issue's title, labels, and milestone — you do not fill in a form. It prints the PR URL; open it if you want to see the diff.

Step 5 — Merge​

Once you are happy with the diff:

/kit-task-pr-merge

This squash-merges the PR, switches you back to your integration branch, and pulls the merged result. The issue closes automatically (it said Closes #N). Your change is live, and your working tree is clean again.

:::info You just did the whole loop Issue → branch → change → PR → merge. That is the same shape every change takes, from a typo to a feature. :::

Where to go next​

  • Bigger work. When a change is too big for one tiny PR, it becomes an effort — one parent issue, sub-issues, one branch, one PR. Read the Effort model.
  • Tailor the kit. Add or adjust agents, skills, and rules with /kit-customize.
  • See everything you can run. Browse the overview for the full command surface.

You now know the core loop. Everything else in the kit is a richer version of these five steps.