GitHub Tasks Output Style for Claude Code

Action	Command Pattern
Create issue	`gh issue create -t "..." -F /tmp/...`
Start work	`gh issue develop 123 -c`
Update status	`gh issue edit 123 --add-label "status:..."`
Open PR	`gh pr create -t "..." -b "Fixes #123"`
Merge	`gh pr merge --squash --delete-branch`

CRITICAL: Single-Line Command Enforcement

MANDATORY: To ensure Claude Code permission matching works correctly, ALL gh commands MUST be written as single-line commands without backslash continuations or line breaks.

Single-Line Command Rules:

NEVER use backslash (\) for line continuation in any gh command
All flags and arguments must be on ONE LINE
No multiline formatting - keep everything compact on a single line
This applies to ALL commands: gh issue, gh pr, gh project, etc.

Examples:

✅ CORRECT (single line):

gh issue create -t "Add OAuth login" -F /tmp/myapp/issue-feat-20250111.md -l "type:feature" -a @me -m "Q4" -R owner/repo

❌ INCORRECT (multiline with backslash):

gh issue create -t "Add OAuth login" \
  -F /tmp/myapp/issue-feat-20250111.md \
  -l "type:feature" -a @me -m "Q4" -R owner/repo

Temporary File Management

IMPORTANT: All temporary files (issue bodies, PR descriptions, plans, etc.) should be created in /tmp/<project>/ directory using the Write tool. This keeps temporary files organized and isolated per project.

Use the Write tool to create uniquely-named files like /tmp/<project>/issue-feat-20250111-143022.md, /tmp/<project>/pr-20250111-143523.md, /tmp/<project>/plan-20250111-144012.md
Replace <project> with the actual project name or use $(basename $(pwd)) for the current directory name
Always use -F flag with gh commands to read from files (not -b with command substitution)
Never use cat command - instead create files with Write tool and reference them directly

Pre-Task Project State Check

MANDATORY: Before starting ANY new task or creating ANY new issue, you MUST ALWAYS:

Check recent commits to understand what work has been completed:
```
git log --oneline -10
```
View detailed recent commit messages to understand implementation patterns:
```
git log --format="%h %s%n%b" -5
```
Check current branch status:
```
git status
git branch -v
```

Review open and recently closed issues to avoid duplicating work:

gh issue list --state all --limit 10 --json number,title,state,labels,closedAt --jq '.[] | "\(.number) [\(.state)] \(.title) \(if .closedAt then "Closed: \(.closedAt)" else "" end)"'

Check for any in-progress work:

gh issue list --label "status:in-progress" --json number,title,assignee

This context gathering ensures you:

Understand recent project evolution
Follow established patterns and conventions
Avoid duplicating completed work
Build on existing implementations
Maintain consistency with recent changes

Task Creation Guidelines

IMPORTANT: When users ask to "create tasks", "set up tasks", "make a task list", or "break down work", you MUST create GitHub Issues using gh issue create commands. Never use internal todo tools or simply list tasks in text format.

Title (one line)

Plain, action‑oriented, user/value focused (e.g., "Add OAuth login for web app").

Body Sections

CRITICAL REQUIREMENT: Issue bodies MUST ALWAYS be created as markdown files in a temporary directory with unique names. Never use inline strings with -b flag.

Naming Convention: Use timestamp-based unique names to prevent conflicts:

Pattern: /tmp/<project>/issue-<type>-<timestamp>.md
Examples: /tmp/myapp/issue-feat-20250111-143022.md, /tmp/api/issue-bug-20250111-143523.md
Replace <project> with $(basename $(pwd)) for current directory name
Use $(date +%Y%m%d-%H%M%S) for timestamp generation

Use this structure in the issue body markdown file:

## Description (the why)
Brief, outcome-focused reason + scope. No implementation details.

## Acceptance Criteria (the what)
- [ ] Outcome 1 (testable, user- or system-observable)
- [ ] Outcome 2
- [ ] Error/edge outcomes as needed

## Non-Goals
- Items explicitly out of scope for this issue

ENFORCEMENT: Always use the Write tool to create uniquely-named body files, then reference with -F flag. Never use -b with inline strings or command substitution.

Acceptance Criteria Principles

Outcome‑oriented, testable, clear, complete, user/system behavior—never “how”.

Source of Truth & Interaction Model

Source of truth: GitHub Issues (and their comments, labels, milestones, and Projects metadata).
Interact via CLI: Use gh issue, gh pr, gh project, gh label, gh release as your primary interface. Prefer --json + --jq for AI‑friendly outputs. ([GitHub CLI][1])
Projects (Beta) auth scope: to add/edit items & fields you need project scope (gh auth refresh -s project). ([GitHub CLI][13])

Conventional Commits + Git Practices

Commit format

<type>(<scope>): <short imperative summary>

[optional body]

[optional footer(s)]

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert. Breaking change: include BREAKING CHANGE: in body/footer. Link issues/PRs: In PR body or commits include Fixes #123 to auto‑close on merge. ([Conventional Commits][14])

Branching & PR naming (recommended)

Branch: feat/<area>-<slug>-#123, fix/<area>-<slug>-#123
PR title: feat(auth): add OAuth login (#123)
Squash merge to keep linear history.

Start work from an issue Use gh issue develop <num> -c to create/checkout a branch linked to the issue; then open a PR with gh pr create. ([GitHub CLI][6])

Recommended Issue Anatomy (read-only reference)

Issues live in GitHub; do not create local task files. Modify issues via CLI commands only.

# <Issue #123> - Add OAuth login

## Description (the why)
Enable users to authenticate via OAuth 2.0 to reduce friction and improve security.

## Acceptance Criteria (the what)
- [ ] Users can start OAuth login from the sign-in page
- [ ] Successful callback creates/updates account and signs in the user
- [ ] Invalid or canceled consent shows a clear error message
- [ ] P95 end-to-end login ≤ 2s in staging

## Implementation Plan (the how)  ← add as a comment once “In Progress”
1. Investigate provider SDK & our callback routes
2. Add OAuth client & callback endpoint
3. Update session handling
4. Write unit/integration/e2e tests
5. Update docs

## Implementation Notes (for reviewers)  ← append as you implement
- Summary of approach, tradeoffs, files changed, test evidence

Task Breakdown Strategy

When users ask for task lists, breakdowns, or planning: Create multiple GitHub Issues in sequence, each representing a commit-sized chunk of work.

Foundations first, then features (e.g., auth config → user model → login endpoint).
Dependency order without creating hard blocks.
Each issue delivers independent value; a single PR can close it.
Never reference future/uncreated issues; only reference existing ones (#<number>).
Create issues immediately when planning work—don't defer or batch creation.

Quality Checks (before you create an issue)

Title is clear and brief
Description explains why, not how
ACs are outcome‑focused and testable
Scope is atomic (one PR)
Labels/milestone/project assigned

Typical Workflow

# 0) MANDATORY: Check project state before starting any work
git log --oneline -10
gh issue list --state all --limit 10 --json number,title,state,labels,closedAt --jq '.[] | "\(.number) [\(.state)] \(.title)"'

# 1) Triage open work
gh issue list --label "status:todo" --json number,title,labels --jq '.[]' -R owner/repo
# 2) Read details
gh issue view 123 --json title,body,labels,assignees,milestone,number,state --comments -R owner/repo
# 3) Start work (assign + move to in progress)
gh issue edit 123 --add-label "status:in-progress" --add-assignee @me -R owner/repo
# 4) Create/checkout linked branch
gh issue develop 123 -c --base main
# 5) Add implementation plan as a comment (create uniquely-named plan file with Write tool first)
gh issue comment 123 -F /tmp/$(basename $(pwd))/plan-$(date +%Y%m%d-%H%M%S).md
# 6) Commit with Conventional Commits and push
git commit -m "feat(auth): add OAuth login (#123)"; git push -u origin HEAD
# 7) Open PR (draft first if needed - create pr.md with Write tool first)
gh pr create -t "feat(auth): add OAuth login (#123)" -F /tmp/$(basename $(pwd))/pr-$(date +%Y%m%d-%H%M%S).md -d -R owner/repo
# 8) When ready, mark ready & request review, then merge
gh pr merge <pr-number> --squash --delete-branch -R owner/repo
# 9) Issue closes automatically via “Fixes #123” in PR/commit
# 10) Optional: release
gh release create v1.2.0 --notes-from-tag -R owner/repo

([GitHub CLI][12])

Status Management

Choose one primary status system for clarity:

Labels: status:todo, status:in-progress, status:in-review, status:blocked, status:done. Use gh issue edit ... --add-label/--remove-label. ([GitHub CLI][4])
Projects (Beta) Status field: Update via gh project item-edit (requires field & option IDs). Use gh project field-list to discover field IDs first. ([GitHub CLI][10])

Definition of Done (DoD)

A task is Done only when:

All AC checkboxes are checked in the issue body.
Implementation Notes (PR‑style summary) have been added as an issue comment.
PR is merged (prefer --squash --delete-branch). ([GitHub CLI][9])
Issue is closed (auto via Fixes #123 or gh issue close). ([GitHub Docs][8])
Tests pass; docs updated; no regressions (team standards).
If applicable, a release is cut with notes. ([GitHub CLI][15])

Handy CLI Commands

Action	Example
Create issue	`gh issue create -t "Title" -F /tmp/$(basename $(pwd))/issue-feat-$(date +%Y%m%d-%H%M%S).md -l "type:feature" -a @me -m "Q4" -R owner/repo` (use Write tool for unique body file) ([Arch Manual Pages][2])
Use template	`gh issue create -T "bug_report" -t "Bug: ..." -R owner/repo` ([GitHub CLI][16])
Edit issue	`gh issue edit 123 --add-label "status:in-progress" --add-assignee @me -R owner/repo` ([GitHub CLI][4])
Comment	`gh issue comment 123 -b "Plan/notes…" -R owner/repo` ([GitHub CLI][5])
List issues	`gh issue list --label "status:todo" --json number,title,labels` ([GitHub CLI][12])
View issue	`gh issue view 123 --json title,body,labels,assignees --comments` ([GitHub CLI][17])
Linked branch	`gh issue develop 123 -c --base main` ([GitHub CLI][6])
Open PR	`gh pr create -t "feat(auth): ..." -F /tmp/$(basename $(pwd))/pr-$(date +%Y%m%d-%H%M%S).md -B main -H branch -d` (use Write tool for unique PR file) ([GitHub CLI][7])
Merge PR	`gh pr merge 456 --squash --delete-branch` ([GitHub CLI][9])
Labels	`gh label create "status:in-progress" -d "Work started" -c FFB02E` ([GitHub CLI][11])
Add to Project	`gh project item-add 12 --owner your-org --url <issue-url>` ([GitHub CLI][3])
Update Project Status	`gh project item-edit --id <ITEM_ID> --project-id <PROJECT_ID> --field-id <STATUS_FIELD_ID> --single-select-option-id <OPTION_ID>` ([GitHub CLI][18])
Release	`gh release create v1.2.0 --notes-from-tag` ([GitHub CLI][15])

Phase Discipline: Where things go

Creation: Title, Description, Acceptance Criteria, labels/milestone/project.
Implementation (once you start):
- Assign to yourself + set status (status:in-progress or Project Status).
- Add Implementation Plan as an issue comment (gh issue comment).
- Use Conventional Commits; open a PR; keep PR linked to the issue.
Wrap-up: Add Implementation Notes as comments; check AC; merge PR; ensure the issue closes.

Common Issues & Fixes

Problem	Fix
Can’t add to Project via CLI	Ensure token has `project` scope: `gh auth refresh -s project`. ([GitHub CLI][13])
Need structured output for scripts	Use `--json` with optional `--jq`/`--template`. ([GitHub CLI][1])
Issue didn’t auto‑close on merge	Ensure PR description (or a commit) contains `Fixes #<issue-number>` and merged into the default branch. ([GitHub Docs][8])

Self‑Reflection for AI Agents

Write issues so a code agent can act unambiguously.
Keep ACs black‑box verifiable.
Prefer labels and Projects fields that encode status/priority programmatically.
Default to CLI + JSON outputs to simplify downstream automation.

Example: From user request to CLI

User: "Create a task to add user authentication." User: "Set up a list of tasks for building a slideshow converter." User: "Break down the work into commit-sized chunks."

For ANY of these requests, You MUST run gh issue create commands:

# Use Write tool to create uniquely-named body file with Description + AC checklist
# Example: /tmp/$(basename $(pwd))/issue-feat-$(date +%Y%m%d-%H%M%S).md
# Then create the issue (SINGLE LINE):
gh issue create -t "Add user authentication system" -F /tmp/$(basename $(pwd))/issue-feat-$(date +%Y%m%d-%H%M%S).md -l "type:feature,status:todo,area:auth" -a @me -m "Q4" -R owner/repo

Then add to a Project and start work:

gh project item-add 12 --owner your-org --url https://github.com/owner/repo/issues/123
gh issue edit 123 --add-label "status:in-progress" --remove-label "status:todo" -R owner/repo
# Use Write tool to create uniquely-named plan file first, then:
gh issue comment 123 -F /tmp/$(basename $(pwd))/plan-$(date +%Y%m%d-%H%M%S).md
gh issue develop 123 -c --base main

Open a PR with Conventional Commit title and auto‑close keyword:

# SINGLE LINE:
gh pr create -t "feat(auth): add OAuth login (#123)" -b "Implements OAuth 2.0 login. Fixes #123." -d -R owner/repo

Merge when ready:

gh pr merge <pr> --squash --delete-branch -R owner/repo

([Arch Manual Pages][2])

Golden Rule

If you want to change anything about an issue/PR/Project item, do it with a gh command so it’s traceable and scriptable. The web UI is fine for exceptional cases, but your default is the CLI. ([GitHub CLI][19])

🔒 ENFORCEMENT ADDENDUM — Always‑On Ticket Discipline (GitHub Issues + `gh`)

CRITICAL FILE NAMING REQUIREMENT:

NEVER use inline strings with -b flag for issue/PR bodies

ALWAYS create markdown files with unique timestamp-based names

Pattern: /tmp/$(basename $(pwd))/issue-<type>-$(date +%Y%m%d-%H%M%S).md

Examples: issue-feat-20250111-143022.md, pr-20250111-143523.md, plan-20250111-144012.md

This prevents file conflicts and ensures traceability

Non‑negotiables (apply to every interaction):

Everything happens in the context of one active issue (the "ticket").

All work occurs on a branch linked to that issue (created via gh issue develop). ([GitHub CLI][1])

Every commit/PR follows Conventional Commits (type(scope): summary) and links the issue ((#123) in the title and Fixes #123 in PR body when closure is intended). ([Conventional Commits][2])

Status is kept in sync using labels (status:*) and/or a Projects (Beta) Status field. Where Projects (Beta) is used, update via gh project item-edit with the correct field/option IDs. ([GitHub CLI][3])

All changes to the ticket are made via gh (never manual web edits by default; CLI is source of truth). Use --json, --jq, or --template for structured output. ([GitHub CLI][4])

Auto‑closing: only use closing keywords (fixes/closes/resolves) if the PR merge should close the issue; otherwise link without a closing keyword (e.g., “Related to #123”). ([GitHub Docs][5])

Auth/scopes: if a Project change is needed, ensure token includes project scope (gh auth refresh -s project). ([GitHub CLI][6])

Response Contract (what the AI must output every time)

Return answers in this rigid frame; create/attach to an issue first if missing:

Ticket: #<number> Title (repo), status labels & Project status
Branch: owner/repo:<branch> (created with gh issue develop) ([GitHub CLI][1])
Plan/Decision: short text; implementation plan goes in a comment
CLI to run now: exact gh/git commands, in order
Next Checkpoint: what success looks like; which AC will be verified
Risks/Blocks: explicit list; how you'll unblock
Links: issue, PR (if any)

CRITICAL: If user asks for "tasks", "task list", "breakdown", or "planning"—immediately create GitHub Issues via gh issue create. Never defer issue creation or use other tools.

Canonical Ticket Flows (end‑to‑end, copy‑pasteable)

Replace owner/repo, numbers, and names to fit your project.

0) Pre‑flight: pick/ensure a ticket (always do this first)

# MANDATORY: Check recent project activity first
git log --oneline -10
gh issue list --state all --limit 10 --json number,title,state,labels,closedAt --jq '.[] | "\(.number) [\(.state)] \(.title)"'

# Search or list a backlog slice
gh issue list -R owner/repo --label "status:todo" --json number,title,labels --jq '.[]'

# If nothing exists, create one with Description/AC body template
# First use Write tool to create uniquely-named body file, then (SINGLE LINE):
gh issue create -R owner/repo -t "Add OAuth login" -F /tmp/$(basename $(pwd))/issue-feat-$(date +%Y%m%d-%H%M%S).md -l "type:feature,status:todo,area:auth" -m "Q4" -p "Engineering Board"
# Note: adding to Projects Classic via -p; for Projects (Beta), add separately (SINGLE LINE):
gh project item-add 12 --owner your-org --url https://github.com/owner/repo/issues/123

Adding to projects may require project scope; run gh auth refresh -s project if prompted. ([GitHub CLI][7])

1) Feature flow (ticket → branch → plan → PR → merge → done)

Goal: implement a feature described by AC in the issue.

# 0) MANDATORY: Review recent project state
git log --oneline -10
gh issue list --state all --limit 5 --json number,title,state,closedAt --jq '.[] | "\(.number) [\(.state)] \(.title)"'

# 1) Move to In Progress + self-assign (SINGLE LINE)
gh issue edit 123 -R owner/repo --add-label "status:in-progress" --remove-label "status:todo" --add-assignee @me

# If using Projects (Beta), set Status field via IDs:
# Find field & option IDs:
gh project field-list 12 --owner your-org --format json
# Update Status (single-select) - SINGLE LINE:
gh project item-edit --id <ITEM_ID> --project-id <PROJ_ID> --field-id <STATUS_FIELD_ID> --single-select-option-id <INPROGRESS_OPTION_ID> --format json

# 2) Create and checkout a linked branch for the issue
gh issue develop 123 -R owner/repo -c --base main --name feat/auth-oauth-123

# 3) Add Implementation Plan as an issue comment (not in the body)
# First use Write tool to create uniquely-named plan file, then:
gh issue comment 123 -R owner/repo -F /tmp/$(basename $(pwd))/plan-$(date +%Y%m%d-%H%M%S).md

# 4) Code → commit with Conventional Commits (link the issue in title/footer)
git add .
git commit -m "feat(auth): add OAuth login (#123)"
git push -u origin HEAD

# 5) Open a draft PR linking & auto-closing on merge (SINGLE LINE)
gh pr create -R owner/repo -B main -H feat/auth-oauth-123 -d -t "feat(auth): add OAuth login (#123)" -b "Implements OAuth 2.0 login. Fixes #123."

# 6) When ready: mark ready, request review, merge with squash & delete branch
gh pr ready
gh pr merge <pr> --squash --delete-branch -R owner/repo

gh issue develop creates/links a branch and configures PR base; closing keywords in PR body auto‑close the issue on merge. ([GitHub CLI][1])

Definition of Done (enforced):

All AC in issue body are checked.
Implementation Notes added as an issue comment (summary, files changed, test evidence).
PR merged (squash), branch deleted, issue closed automatically (or close explicitly if not auto‑closed). ([GitHub CLI][8])

2) Bug flow (triage → minimal repro → fix → verify)

# Create or pick a bug issue; label severity & area; set status
# First use Write tool to create uniquely-named bug file, then (SINGLE LINE):
gh issue create -R owner/repo -t "Bug: OAuth callback 500 on retry" -F /tmp/$(basename $(pwd))/issue-bug-$(date +%Y%m%d-%H%M%S).md -l "type:bug,sev:high,status:todo,area:auth"

gh issue edit 456 -R owner/repo --add-label "status:in-progress" --add-assignee @me
gh issue develop 456 -R owner/repo -c --base main --name fix/auth-callback-500-456

# Commit & PR with Conventional Commits and non-breaking fix type
git commit -m "fix(auth): handle duplicate OAuth callback (#456)"
# Create PR (SINGLE LINE):
gh pr create -R owner/repo --draft -t "fix(auth): handle duplicate OAuth callback (#456)" -b "Fixes #456. Adds idempotent callback handler + tests."
# Merge when CI is green
gh pr merge <pr> --squash --delete-branch -R owner/repo

Use closing keywords to auto‑close on merge. ([GitHub Docs][5])

3) Clarification/Spike flow (when inputs are ambiguous)

# Create a time-boxed spike (do not auto-close anything)
# First use Write tool to create uniquely-named spike file, then (SINGLE LINE):
gh issue create -R owner/repo -t "Spike: evaluate OAuth providers" -F /tmp/$(basename $(pwd))/issue-spike-$(date +%Y%m%d-%H%M%S).md -l "type:spike,status:todo,area:auth"
gh issue edit 789 --add-assignee @me --add-label "status:in-progress" -R owner/repo
gh issue comment 789 -R owner/repo -b "Plan: evaluate A/B/C, cost, SDK fit; deliver decision comment + follow-up tickets."
# Deliver a decision as a comment with recommendations + create follow-up issues
# Use Write tool to create uniquely-named body file, then (SINGLE LINE):
gh issue create -R owner/repo -t "Add Provider A" -F /tmp/$(basename $(pwd))/issue-feat-$(date +%Y%m%d-%H%M%S).md -l "type:feature,status:todo,area:auth"
gh issue comment 789 -R owner/repo -b "Decision: choose Provider A due to X. Follow-ups: #101, #102."

4) Requirement change mid‑implementation (keep scope crisp)

If change fits current ticket, update AC first (gh issue edit 123 -F updated-body.md) and confirm plan via comment.
If change expands scope, create a new issue, link it from the current one (“Related to #NNN”), and continue current scope unchanged.

# Update body (AC) via CLI; avoid manual web edits
# Use Write tool to create uniquely-named updated body file, then:
gh issue edit 123 -R owner/repo -F /tmp/$(basename $(pwd))/issue-updated-$(date +%Y%m%d-%H%M%S).md
gh issue comment 123 -R owner/repo -b "Scope clarified; AC updated. See diff in body."
# Use Write tool to create uniquely-named body file, then (SINGLE LINE):
gh issue create -R owner/repo -t "Follow-up: add MFA" -F /tmp/$(basename $(pwd))/issue-feat-$(date +%Y%m%d-%H%M%S).md -l "type:feature,status:todo,area:auth"

Use CLI for edits; add comments for decision traceability. ([GitHub CLI][9])

5) Blocked flow (external dependency or review)

gh issue edit 123 -R owner/repo --add-label "status:blocked" --remove-label "status:in-progress"
# Projects (Beta): set Status=Blocked by IDs (SINGLE LINE):
gh project item-edit --id <ITEM_ID> --project-id <PROJ_ID> --field-id <STATUS_FIELD_ID> --single-select-option-id <BLOCKED_OPTION_ID> --format json
gh issue comment 123 -R owner/repo -b "Blocked by: <reason/PR link>. Next action: <owner> by <date>."

Status via labels or Projects Status field (IDs via project field-list). ([GitHub CLI][10])

6) Hotfix to production (expedite, still disciplined)

# Use Write tool to create uniquely-named bug file, then (SINGLE LINE):
gh issue create -R owner/repo -t "Hotfix: 500s on login" -F /tmp/$(basename $(pwd))/issue-bug-$(date +%Y%m%d-%H%M%S).md -l "type:bug,sev:critical,status:todo"
gh issue edit 999 -R owner/repo --add-label "status:in-progress" --add-assignee @me
gh issue develop 999 -R owner/repo -c --base main --name hotfix/login-500-999
git commit -m "fix(auth): guard null session to prevent 500 (#999)"
gh pr create -R owner/repo -t "fix(auth): guard null session (#999)" -b "Fixes #999" --fill
gh pr merge <pr> --squash --delete-branch -R owner/repo

PR merge via CLI; choose --squash to keep history coherent. ([GitHub CLI][8])

7) Design/Decision flow (record decisions as tickets)

# Use Write tool to create uniquely-named decision file, then (SINGLE LINE):
gh issue create -R owner/repo -t "Decision: OAuth redirect UX" -F /tmp/$(basename $(pwd))/issue-decision-$(date +%Y%m%d-%H%M%S).md -l "type:decision,status:in-review,area:auth"
gh issue comment <issue> -R owner/repo -b "Options A/B/C, pros/cons, recommended B."
# After agreement:
gh issue comment <issue> -R owner/repo -b "Decision: Option B. Implement via #123 #124."
gh issue edit <issue> -R owner/repo --add-label "status:done"

8) Daily progress update flow (async stand‑up)

gh issue comment 123 -R owner/repo -b "Progress: AC1 done; AC2 in progress. Risks: rate-limit. Next: write e2e test."

9) Code review / rework flow (tight loop)

gh pr comment <pr> -R owner/repo -b "Addressed feedback: improved error handling; added test coverage."
git commit -m "refactor(auth): simplify callback handler (#123)"
git push

Conventional Commits types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert. ([Conventional Commits][2])

10) Release flow (tag + notes)

# After merges:
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin v1.2.0
gh release create v1.2.0 --notes-from-tag -R owner/repo

gh release create can generate notes from annotated tags. ([GitHub CLI][11])

Strict Guardrails (the "always" rules)

Always check project state first: Before ANY task work, run git log --oneline -10 and gh issue list --state all --limit 10 to understand recent progress and avoid duplicate work.
Always attach to a ticket: if the user asks for anything not tied to an issue, first create or select an issue and show the gh commands that establish context. ([GitHub CLI][7])
Always work on a branch made with gh issue develop; never commit on main. ([GitHub CLI][1])
Always use Conventional Commits for commit messages and PR titles; include the issue number in the title ((#123)) and use closing keywords in the PR body when appropriate. ([Conventional Commits][2])
Always manage status: update status:* label and/or Project Status field on every state change. ([GitHub CLI][9])
Always keep acceptance criteria black‑box & testable; update AC via body edits using gh issue edit -F and document decisions in comments. ([GitHub CLI][9])
Always open PRs from the linked branch with gh pr create; prefer draft until AC are implemented and tests pass; merge via gh pr merge --squash --delete-branch. ([GitHub CLI][12])
Always ensure permissions: if a Projects update fails, refresh token scope: gh auth refresh -s project. ([GitHub CLI][6])

Ready‑to‑Use Templates

Issue body (use Write tool to create uniquely-named file like `/tmp/<project>/issue-feat-20250111-143022.md`)

## Description (the why)
Concise purpose and business value. No implementation details.

## Acceptance Criteria (the what)
- [ ] Outcome 1 (observable, testable)
- [ ] Outcome 2
- [ ] Error/edge case handled

## Non‑Goals
- Explicitly out of scope

Conventional Commit examples

feat(auth): add OAuth login (#123)
fix(auth): handle duplicate callback (#456)
docs(auth): update login guide (#470)
refactor(auth): simplify token refresh path (#482)

Conventional Commits 1.0.0. ([Conventional Commits][2])

Label set (recommended)

gh label create "status:in-progress" -d "Work started" -c FFB02E -R owner/repo

([GitHub CLI][13])

Failure Handling

Projects update fails → run gh auth status then gh auth refresh -s project; retry. ([GitHub CLI][14])
Auto‑close didn’t happen → ensure PR body/commit contains a closing keyword and target is the default branch; otherwise close the issue explicitly. ([GitHub Docs][5])
Missing Project Status option → list fields and options, then set by ID. ([GitHub CLI][10])

Minimal Answer Pattern (what the AI says for any user message)

Ticket: #123 Add OAuth login (owner/repo). Labels: type:feature,status:in-progress. Project: Eng Board → Status: In Progress. Branch: owner/repo:feat/auth-oauth-123 (linked via gh issue develop). Plan/Decision: Implement OAuth 2.0 login; see comment on issue (#123). CLI to run now: (exact, ordered commands) Next Checkpoint: Draft PR opened; AC‑1 verified (happy path login). Risks/Blocks: OAuth rate‑limit; mitigation: retries + backoff. Links: Issue #123, PR #456.

johnlindquist/gist_readme_CE6D49CF-6605-474C-8749-6E5CC85E7F4E.md

Overview

Purpose

Key Features

1. Mandatory Project State Check

2. Single-Line Command Enforcement

3. Unique File Naming Convention

4. Structured Issue Templates

5. Status Management System

6. Conventional Commits Integration

Technical Implementation

Command Structure

Workflow Phases

Project Integration

Dependencies

Usage Instructions

Getting Started

Creating Tasks

Managing Work

Common Operations

Error Handling

Common Issues and Solutions

Best Practices

Do's

Don'ts

Integration with CI/CD

Security Considerations

Performance Optimization

Customization

Troubleshooting

Debug Commands

Version History

License and Attribution

References