| name | devlearn-git |
| description | Teaches git commits, branches, pull requests, and merge workflow while the
agent performs real git operations. Use when the user asks about git, commits,
branches, PRs, "what did you just run in git", or curriculum routes here.
Pairs with devlearn-explain-diff. Proactively suggest when git commands run
and DEVLEARN.md is enabled.
|
DevLearn: Git
Iron law
Teach without blocking ship. Run git operations the user asked for; explain each meaningful step in plain language.
Voice
Follow ../shared/voice.md. After git operations, emit lesson blocks from ../shared/lesson-block.md.
Context
Git is a time machine + parallel universes for your code. Vibe coders don't need every flag — they need to know what just happened, why it's safe, and what to do when something looks scary.
Prerequisites
- Project with git initialized (or offer
git init)
- User goal: save work, try ideas safely, share via PR, or undo mistakes
Router handoff: users from "what did agent change" → devlearn-explain-diff after commit.
Before you start
- Read DEVLEARN.md depth (default curious for git — mistakes are costly)
- Step 0:
git status — what's dirty, what branch, remote?
- Never force-push
main without explicit user request and warning
Core mental model (teach once per session)
| Concept | Plain English |
|---|
| Working tree | Files on disk right now |
| Staging | Shopping cart of changes for next snapshot |
| Commit | Named snapshot with message |
| Branch | Parallel line of snapshots |
| Remote | Copy on GitHub/GitLab others can see |
| PR | "Please merge my branch into main" with review |
Workflow A: First commit
When: New project or never committed.
git status — show untracked/modified- Explain: commit = save point with message
- Stage intentional files only (warn on
.env, secrets)
git commit -m "..." — message describes why, not only what- Lesson block + terms: commit, staging
Try it yourself: Run git log -1 --oneline and read your message aloud.
Workflow B: Save work on a branch
When: Feature or experiment without breaking main.
- Explain branch as "copy of timeline for one idea"
git checkout -b feature/todo-save (or git switch -c)- Work + commits on branch
- Lesson: branch, why not commit directly to main
Smell: Long-lived work on main with no commits — suggest branch.
Workflow C: Pull request story
When: User wants review or merge to main.
- Push branch:
git push -u origin HEAD
gh pr create if available — title = user outcome, body = test plan- Teach PR as conversation + CI gate, not magic merge button
- Offer
/devlearn-explain-diff on PR diff
Terms: remote, PR, merge
Workflow D: Update from main
When: Branch is behind main.
- Explain: main moved; you need those fixes on your branch
- Prefer
git pull --rebase origin main on feature branches (teach rebase as "replay your commits on top")
- If conflicts: teach conflict markers, one file at a time
STOP: If conflict, pause and teach one file before continuing.
Workflow E: Oops recovery (safe only)
| User says | Teach + do |
|---|
| "Unstage" | git restore --staged |
| "Discard file changes" | git restore <file> — warn: loses uncommitted work |
| "Undo last commit keep changes" | git reset --soft HEAD~1 |
| "What did I change?" | git diff → /devlearn-explain-diff |
Never git reset --hard or force-push without careful warning and user confirmation.
Domain glossary
| Term | Definition |
|---|
| commit | Snapshot of staged changes with message |
| staging | Selecting which changes go into next commit |
| branch | Movable pointer to a line of commits |
| merge | Combine branch histories |
| rebase | Replay commits onto another base |
| remote | Server copy (origin) |
| PR | Request to merge branch with review |
| clone | Copy remote repo locally |
| .gitignore | Files git should not track |
Common mistakes
| Smell | What happened | Fix |
|---|
| "Everything is red in status" | Many untracked files | .gitignore, commit in chunks |
| "Committed secret" | .env in commit | Rotate secret, gitignore, teach env vars |
| "Can't push" | No upstream / auth | -u origin, SSH/token help |
| "Merge conflict scary" | Same lines edited twice | Open file, pick correct parts, commit |
Lesson integration
After each workflow step that changes git state, emit lesson block. Minimum one Term of the moment per workflow.
For multi-command sequences (push + PR), one combined lesson is OK in vibe mode.
STOP checkpoint
Before first push to remote:
"Your commits will be visible on [remote]. Ready to push, or want to review diff first?"
Offer /devlearn-explain-diff if they hesitate.
Before merge after PR:
"After merge, run /devlearn-pre-ship before production deploy."
Lifecycle handoffs
| After | Suggest |
|---|
| PR open | /devlearn-explain-diff on PR diff |
| Merge to main | /devlearn-pre-ship → /devlearn-security |
| Push deploy | /devlearn-deploy |
| Live URL | /devlearn-post-ship |
| Add GitHub Actions | /devlearn-devops |
Required footer
---
DevLearn status: DONE
Lesson depth: [from DEVLEARN.md]
Git actions: [e.g. commit, push, pr create]
Suggested next: /devlearn-explain-diff | /devlearn-deploy
---
Additional resources
- Command cheatsheet → reference.md
- Diff narrative →
devlearn-explain-diff
- Ambient teaching →
devlearn-teach-while-coding
