GitHub Workflow

SKILL.md

---
name: GitHub Workflow
description: "Professional GitHub workflow skill for AI agents. Covers full project lifecycle: repo setup, Git Flow branching, atomic commits, pull requests, code review, CI/CD monitoring, semantic versioning, releases, secrets management, and security rules. Includes mandatory agent behavior directives for skill installation, new projects, and returning to existing work. Features built-in work log system for task state and session continuity. Trigger on: GitHub, git, gh CLI, repo, PR, branch, merge, commit, issue, release, CI, GitHub Actions, tag, secret."
---

# GitHub Skill

## Agent Directives

These are mandatory behavioral rules. Follow them in every situation involving code, projects, or tasks.

### On skill installation
When this skill is first loaded, introduce it to the user:
- Explain that all project work will now follow a professional GitHub workflow
- Mention: branching strategy, work logs, CI checks, semantic versioning, security rules
- Ask: "Do you have an existing project, or are we starting a new one?"

### On new project
**If this is the user's first project ever:**
- Check `gh auth status` — if not authenticated, run `gh auth login --web` before anything else
- Offer to create a new repo: name, visibility (public/private), license, .gitignore
- Set up branch protection on `main` and `develop` right away
- Clone into `~/workspace/projects/<repo-name>/`
- Create initial `develop` branch
- Confirm setup is complete before starting any work

**If the user already has projects:**
- Ask which repo they want to work on, or detect from context
- Clone into `~/workspace/projects/<repo-name>/` if not already there
- Verify branch protection is in place — if not, offer to set it up
- Proceed directly to task workflow

### On continuing existing work
When the user returns to an already-cloned project — run the Session start checklist (see Agent Workflow below) before making any changes.

### On every task
- Assess task scale first (see Task scale table in Agent Workflow).
- Tiny tasks: branch → commit → quick-log → PR → confirm with user → merge.
- Normal/significant tasks: Issue and work log are mandatory before branching.
- Never commit directly to `main` or `develop`.
- Never skip the pre-PR checklist on normal/significant tasks.
- Never expose tokens, secrets, or credentials in any command or output.
- If something is irreversible (delete, merge, release, force push) — **always confirm with the user first**.

### On using this skill
- This file (SKILL.md) is always in context — use it for workflow, branching, work log rules.
- Reference files are loaded **on demand only** — read them when the task requires it, not upfront.
- Work log is not optional — it is part of every task from start to finish.
- When in doubt about a GitHub operation — check the relevant reference file before acting.

---

## Security (always)
- All operations via `gh` CLI. Always `--repo owner/repo` outside a git directory.
- Auth: `gh auth login --web` or `GITHUB_TOKEN` env var
- Secrets: `gh secret set NAME --repo owner/repo` (interactive, never `--body`)
- Never print/log tokens. `gh auth status` to verify.

## Quick Reference

Read-only lookup. All write operations require explicit user confirmation — see ⚠️ markers in reference files.

| Task | Command |
|------|---------|
| Auth check | `gh auth status` |
| List PRs | `gh pr list --repo o/r` |
| Create PR | `gh pr create --repo o/r --title "..." --base develop --head branch` |
| PR checks | `gh pr checks <n> --repo o/r` |
| Merge (squash) | `gh pr merge <n> --squash --delete-branch --repo o/r` |
| Failed CI logs | `gh run view <id> --log-failed --repo o/r` |
| Re-run failed | `gh run rerun <id> --failed-only --repo o/r` |
| Create issue | `gh issue create --repo o/r --title "..." --body "..."` |
| Create release | `gh release create vX.Y.Z --repo o/r --title "..." --notes "..."` |
| Set secret | `gh secret set KEY --repo o/r` |
| Branch protect | `gh api --method PUT repos/o/r/branches/main/protection ...` |

## Branching Model
```
main       ← production, protected
develop    ← integration
feature/*  ← from develop
fix/*      ← from develop (reference issue: fix/123-desc)
hotfix/*   ← from main (emergency)
release/*  ← from develop (prep)
chore/*    ← from develop (deps, tooling, CI — no product change)
```
Commit convention: `feat: description (#42)` / `fix: description (#42)`
PR merge: `--squash` for features, `--merge` for releases.
Semver: `MAJOR.MINOR.PATCH` — breaking/feature/fix.

## Agent Workflow

### Workspace layout
Always clone into `~/workspace/projects/<repo-name>/`. Never work in `/tmp` — it doesn't persist between sessions.

```bash
mkdir -p ~/workspace/projects
gh repo clone owner/repo ~/workspace/projects/repo-name
cd ~/workspace/projects/repo-name
```

### Session start (every time)
```bash
gh auth status                   # 1. verify auth
git checkout develop && git pull # 2. sync before any work
git branch                       # 3. confirm you're on the right branch
# 4. open work/<issue>-<desc>.md and read Status.next
```

### Task scale
Before starting any task, assess its scale — this determines the workflow level.

| Scale | Signals | What to skip |
|-------|---------|--------------|
| **tiny** | ≤2 files, no backend/auth/infra, cosmetic or config change | Issue, PR, full work log → use `quick-log.md` instead |
| **normal** | 3–10 files, one area of the codebase | Issue optional if obvious, PR only if risky |
| **significant** | backend, auth, infra, API, DB, multi-component, deploy | Nothing — full workflow mandatory |

When in doubt — treat as significant.

### Clarification (significant tasks only)
Before creating an Issue or branching, ask until requirements are clear:
- What exactly needs to change and why?
- Are there affected components, APIs, or dependencies?
- Any constraints — performance, backward compatibility, deadlines?
- What does "done" look like?

**Do not start implementation until answers are clear.** For tiny/normal tasks — skip this, infer from context.

### Task process

**Tiny task:**
```
1. Branch from develop          → git checkout -b fix/short-desc
2. Atomic commit                → "fix: description"
3. Append to quick-log.md       → date + one line what changed
4. ⚠️ CONFIRM WITH USER — merge via PR → gh pr merge --squash --delete-branch
```

**Normal/significant task:**
```
1. Create or find the Issue                → gh issue create / gh issue list
2. Create work log file                    → work/<issue>-<desc>.md (see Work Log section below)
3. Branch from develop                     → git checkout -b feature/42-short-desc
4. Make small atomic commits               → one change per commit
5. Commit message references Issue         → "feat: description (#42)"
6. Open draft PR after first commit        → gh pr create --draft (signals work in progress early)
7. Monitor CI                              → gh run watch
   If CI fails:
   - Download failed logs                  → gh run view <id> --log-failed
   - Record cause in work log              → Status.blocked or Notes
   - Fix, commit ("fix: resolve CI failure"), push
   - Wait for green before proceeding
8. Pre-PR checklist (see below)
9. Mark ready + request review             → gh pr ready / gh pr review
10. Merge after approval                   → gh pr merge --squash --delete-branch
11. Close Issue + compact work log         → gh issue close 42
```

### Pre-PR checklist
Before marking PR ready:
- Run tests locally
- `git diff origin/develop` — no debug code, credentials, or temp files
- CI is green (`gh pr checks <n>`)
- PR description follows the template below
- **Self-review:** read your own diff one more time — check for hardcoded values, leftover debug statements, missing error handling. Only after this request human review.

**PR description template:**
```markdown
## What
Brief description of the change.

## Why
Closes #<issue>

## Changes
- Change 1
- Change 2

## Testing
- [ ] Tests pass locally
- [ ] CI green
- [ ] Manual check done (if UI)
```

### Between sessions
If a task is unfinished at end of session:
```bash
git stash push -m "wip: description of what's in progress"
```
Update `Status` and `next` in the work log, then stop. On next session: read `next`, then `git stash pop`.

### Merge conflicts
When a conflict occurs during merge or rebase:
```bash
git status                         # see conflicted files
# Open each file — resolve manually, keep correct code
git add <resolved-file>
git rebase --continue              # or git merge --continue

# If too complex — abort and ask the user
git rebase --abort
git merge --abort
```
Rules:
- Never blindly accept `--ours` or `--theirs` without understanding the diff
- If unsure which change is correct — **stop and ask the user**
- After resolving, re-run tests before pushing

### Scope creep
If during implementation something additional is discovered that wasn't in the original Issue:
- Do **not** expand the current task
- Complete current task as originally scoped
- Create a new Issue for the additional work
- Add a note in the current work log under `Notes`

### Hotfix workflow
Hotfixes are emergency fixes branched from `main`. After merging into `main`, the same fix **must** be merged back into `develop` — otherwise the bug returns in the next release.

```
1. Branch from main                        → git checkout main && git pull
                                             git checkout -b hotfix/short-desc
2. Fix, commit                             → "fix: description"
3. Open PR → main                          → gh pr create --base main --head hotfix/...
4. Merge into main after approval          → gh pr merge --squash --delete-branch
5. ⚠️ CONFIRM WITH USER — merge into develop too → git checkout develop && git pull
                                                    git merge main
                                                    git push origin develop
6. Tag the release                         → gh release create vX.Y.Z --target main
7. Record in work log                      → what broke, what was fixed, why
```

Never skip step 5 — an unsynced `develop` will reintroduce the bug on next release.

---

## Work Log

Every task gets a log entry. Format depends on scale.

### Quick log (tiny tasks only)
One shared file per project: `work/quick-log.md`

```markdown
## 2026-05-08
- fixed listing card spacing (components/Card.css)
- updated parser timeout (config/parser.yml)
- corrected Georgian translation (locales/ka.json)
```

Append one line per tiny task. No structure, no status, no decisions. Created once, never compacted.

### Full log (normal / significant tasks)
Every significant task gets its own log file. It is the agent's memory — orientation, decisions, state.

### Setup
```bash
mkdir -p work
# Add to .gitignore once per project
echo "work/" >> .gitignore
```
File: `work/<issue-number>-<short-desc>.md`

### Structure
```markdown
# Task: <title> (#<issue>)
Goal: <one sentence — what "done" means>

## Status
current: <what agent is doing right now>
next: <planned next action>
blocked: <blocker or —>

## Done
- [x] Created branch feature/42-user-auth
- [x] Added JWT middleware (src/auth.js)
- [ ] PR review pending

## Decisions
- Used HS256 — no key infrastructure in this project
- Skipped refresh token — out of scope per Issue comment

## Notes
- src/auth.js:84 — edge case when token is exactly expired, needs attention
- AUTH_SECRET env var must be added to secrets before deploy
```

### When to write

| Event | Action |
|-------|--------|
| Session start | Read `next`, update `current` |
| File or module created | Add to `Done` |
| Decision made | Add to `Decisions` with reason |
| Unexpected finding | Add to `Notes` |
| Step completed | Check off `Done`, update `next` |
| Session end | Update `Status`, write `next` explicitly |
| Task complete | Compact, then archive |

### Compacting
Compact when file exceeds ~80 lines **or** when task is complete.
- `Done` — keep unchecked + last 3 completed, drop the rest
- `Decisions` — keep all, never delete
- `Notes` — drop resolved, keep open
- `Status` — rewrite fresh

### Rules
- Always update `next` before ending a session — it is the re-entry point
- Never delete `Decisions` — they prevent re-debating solved problems
- Never store secrets, tokens, or credentials in work logs
- Compact proactively — a bloated log defeats the purpose

---

## When to read reference files

Load only what you need for the current task:

| Task | Read |
|------|------|
| Setting up a new repo, branch protection | `references/repo-setup.md` |
| PRs, reviews, merge strategies | `references/pull-requests.md` |
| CI runs, GitHub Actions | `references/ci-actions.md` |
| Releases, versioning, tags | `references/releases.md` |
| Secrets, environments | `references/secrets-envs.md` |
| JSON queries, audit, search | `references/api-queries.md` |