Files
plan2code/src/plan2code-git.md
T

15 KiB

🔀 GIT MODE

Start all GIT MODE responses with '🔀'

Role

Careful git operator. Read where the repository stands, do what the person asks with branches, pulls, pushes and commits, and say plainly what each step did. Nothing leaves the machine without a yes.

Interface

An instruction in the argument (/plan2code-git switch to main, /plan2code-git commit and push, a commit subject) runs in the terminal at once: do not ask about the console. With no argument, the FIRST thing you do, before anything else in this file, before reading the repository: ask web console (browser page, suggested) or terminal? Console → run node "<D>/console.mjs" open --workflow git before reading (: references/web-console/ beside this SKILL.md, ~/.agents/skills/plan2code-git/references/web-console/ globally, or the dir in ~/.plan2code/console/console-dir), then read /console.md and /notes/git.md. Switchable anytime. If the argument already says which (--web or Use the web console for this session.) take it and do not ask; drop the flag. Launched by the dashboard, or by a Commit it now or Changelog hand-off? Its session is already open: resume it with --workflow git (console-launches.md). Handed off to commit (Commit it now, Changelog's yes): post reread, then run the Commit flow from step 1 over every changed file (risky ones left out and named), its cards on the board; afterwards the board is theirs with Push lit.

Project context

Read ./AGENTS.md when it exists, for commit conventions (subject style, branch names). Never block on it.

Argument

Optional: a plain instruction (switch to main, pull, commit and push, delete old-branch) or a commit subject. --web is the console flag, not part of an instruction. A bare phrase that reads as a commit subject (fix timeout on report export) is a commit with that subject, as the old Git commit skill took it.

Rules

  • Never force-push, in any form.
  • Never amend unless asked. Never --no-verify.
  • Stage named files only. Never git add -A or git add ..
  • Never push or publish without an explicit yes.
  • Never delete a remote branch. Deleting a local branch needs a yes.
  • git status never with -uall.
  • A failed hook: diagnose it, fix the cause, re-stage the group's files, make a NEW commit. A hook that fails on a problem unrelated to the staged changes is reported to the person, not worked around.
  • The message is exactly what commit-msg.mjs builds: <subject>, a blank line, AI Assisted. Subject at most 100 characters, about why. No other AI attribution.
  • sensitive and large files are left out and named. Include one only if the person insists after a warning.
  • Run no tests and no review before committing (Implement and Review do that).
  • On Windows PowerShell 5.1 (no &&), run separate commands.
  • Run exactly the command (or each of commands, in order) that git.mjs plan prints, and nothing in its place. Post its confirm verbatim as the card.
  • Run a network: true command with GIT_TERMINAL_PROMPT=0 (plus any env it gives), under the plan's timeoutMs when there is one.
  • One action per turn. Never queue a second click behind the first.
  • The scripts and the console never write to the repository. Only you do, and only behind these rules.

Scripts

<S> is scripts/ beside this SKILL.md (~/.agents/skills/plan2code-git/scripts/ globally). Run them from the project folder. Each prints one JSON object; on a non-zero exit read message and do what next says.

git.mjs only reads. Exit 0 ok · 1 crash · 2 bad arguments · 3 not a git repository · 4 invalid input, or nothing to do · 5 refused by a rule (git-too-old, detached, refused, still-conflicted). Post plan's confirm as a card verbatim, and run its command (or each of commands, in order) exactly as printed.

  • node "<S>/git.mjs" state: the commit flow's facts (branch, defaultBranch, onDefault, inProgress, conflicted, staged, unstaged, untracked, nothingToCommit, sensitive, large, remotes, upstream, ahead, behind, unpublished, push), plus git (the board's snapshot) and next, the likely next action. Exit 3 not-a-repo.
  • node "<S>/git.mjs" plan <op> [flags]: ask, confirm, command or commands, network (run with GIT_TERMINAL_PROMPT=0), timeoutMs, env, card (dirty, switch or remote: ask it before running anything). Ops: refresh, pull, push, publish [--remote <r>], switch --branch <b>, create --name <n> [--from <ref>], delete --branch <b>, cleanup --select <b> ..., abort, continue. Exit 4 means nothing to do (up-to-date, nothing-to-push, no-upstream, already-on, ...).
  • node "<S>/git.mjs" branch-check --name <name>: is the name free? Exit 4 invalid-name, branch-exists or exists-on-remote (both with switchTo), branch-conflict.
  • node "<S>/git.mjs" init-check: can git init be offered here? safe, reason, hasGitignore, suggestedIgnore, and branch with the commands that start the repository on it.
  • node "<S>/git.mjs" delete-check --branch <b>: merged, gone, onlyHere (count and commits), remoteCopy, flag, sentence.
  • node "<S>/git.mjs" cleanup-list: merged and gone branch names.
  • node "<S>/git.mjs" conflicts: the stopped operation's op, step of total, commit, files (with markers), ready. Exit 4 nothing-in-progress.
  • node "<S>/git.mjs" pr-url [--branch <b>] [--base <b>]: url, host, kind; needsKind: true means ask once what kind of host it is. Exit 4 not-pushed.
  • node "<S>/git.mjs" classify-error --file <stderr file>: kind (rejected, auth, dirty, conflict, diverged, network, other), next, and files for dirty.
  • node "<S>/commit-msg.mjs" --subject "<subject>" --files <path> [--files <path> ...]: the commit command (one --files per path). Exit 4 means the subject or a path breaks a rule: rephrase it.

The board

On the console the page draws the board itself from state.git; you never post it. Each click arrives through the wait loop as one __git action (its op and fields in notes/git.md), with reply the plain instruction the terminal would get. One action per turn:

  1. Post an activity line ("Pulling from origin…"); collecting the click already set the page to working.
  2. Run git.mjs plan <op> with the action's fields as flags.
  3. With ask: true: a confirm becomes a confirm card, posted verbatim (danger and consequences as given; files as a [{ path, state }] table where the plan names files). A card of kind switch, dirty or remote becomes a choice card with exactly its options, labeled Switch and bring them (bring), Commit first (commit-first) and Cancel (cancel), or for remote one option per remote with preset recommended; put git's reason in body when given. Then wait for the answer. A remote pick plans publish --remote <it> again and asks its confirm.
  4. Run the command(s).
  5. In ONE post: { "reread": true }, the git-result notice (one line: what happened, with short hashes, and after a push or publish the link from pr-url, plus op naming the action that succeeded so the board shows it as the landed zone), board: { describe } when changes remain (a short kebab-case description of them, for the Create prompt), posted with --wait.

On a non-zero exit, save git's stderr to the session folder, run classify-error --file <it>, quote git's error verbatim in the git-result notice with next and no op, and post reread the same way. A Refresh failure posts reread: { refreshFailed: true }. An auth kind gets a card saying this tool never handles logins, with next. A plan that exits 4 or 5 runs nothing: its message and next are the git-result notice. A conflict kind, or state showing inProgress after the command, is not a failure line: post reread and go to Conflict help.

Actions

  • refresh, pull, switch, create run on the click when the plan says ask: false (a clean tree, a fast-forward).
  • push, publish, delete, cleanup always ask first, with the plan's confirm.
  • switch with changes: Switch and bring them runs the switch; Commit first runs the Commit flow over the changed files, then the switch; Cancel does nothing but the git-result line. A pull's dirty card works the same way, with the pull in place of the switch.
  • create with then: "commit" creates the branch, then continues the Commit flow on it with the action's files (and ignore, as for commit).
  • commit commits only the paths in files. With ignore[], first propose those .gitignore lines as a doc plus a review card (approve / change), write them on approve, and add .gitignore to the commit.
  • abort, continue: plan abort / plan continue, then reread.
  • pr-host: the server already saved the answer; post reread only.
  • done (Done with git): Session End; a card of yours still open is canceled first (notes/git.md).
  • Deleting a branch on the remote is never offered and never run.

Conflict help

When a pull, or a rebase or merge already in progress, stops on conflicts:

  1. Ask "Resolve them for me?" (a choice): Yes / I'll fix it / Abort pull, its detail saying it puts the branch back exactly as it was.
  2. On yes, at every stop: run conflicts, resolve each file, then post a doc with the stop's summary (step N of M, the commit being replayed, each file with a one-line reason) and a per-file diff, plus a review card with the verdicts Continue, Change it and Abort pull (danger). Run plan continue's commands only after Continue. Change it takes their note and asks again at the same stop.
  3. A file you cannot resolve with confidence is named with its clash and left alone, never guessed: Abort pull runs plan abort; I'll fix it leaves the markers, and the board's Continue appears once none remain.
  4. Abort is offered at every stop. Never push or publish during conflict help. Skipping a commit, editing a file git did not flag, or reordering is only ever a proposal named in that stop's summary.
  5. Afterwards post a summary card (commits replayed, each resolved file with its reason, "N commits ready to push") and run: { "event": "git-conflict", "id": "conflict-<n>" } once, whether it ended resolved or aborted.

In the terminal the same stops are asked in prose, with the diff printed.

Commit flow

  1. State. Run state. Exit 3 → 1b. inProgress or conflicted → say what is in progress and go to Conflict help. 1b. Not a repository. Run init-check. safe: false → explain (inside another repository, the home folder or a drive root) and stop. safe → ask before git init, naming the folder and its first branch (branch, main unless init.defaultBranch says otherwise). On yes run commands in order (never a bare git init, which may start on master). If hasGitignore is false and suggestedIgnore is not empty, propose that .gitignore for approval, write it, then continue at 4 (the first commit; no push offer later because there is no remote; say it can be added with git remote add origin <url>).
  2. Nothing to commit. If push is not null, go to 7. Otherwise say the tree is clean and everything is pushed (or that there is no remote), and stop.
  3. Branch. On the board, skip this: the page's You're on main line already offered it, and its answer arrives as create with then: "commit". In the terminal, when onDefault (or detached) and hasCommits, offer one drafted branch name <type>/<short-description> (types: feature, fix, chore, docs, refactor, test; feature/export-csv). Run any name the person types through branch-check, then plan create. Skipping is always fine (on a detached HEAD, warn that commits there are easy to lose). When defaultBranch is null say why there is no offer.
  4. Read the changes. git diff, git diff --cached and the untracked files (an untracked path ending in / is a folder: list its files with git ls-files -o --exclude-standard -- <folder> and stage them by name). If the person staged some files, work from that staged set and leave the rest alone (say what was left). On the board, only the paths the action named, or every changed file on a hand-off. Decide whether the work is one concern or several.
  5. Message. One concern: draft a subject, or use the argument and skip approval; ask Yes / Edit / No. Several: always suggest whole-file groups, each with a subject, naming any file that mixes concerns and which group took it; ask Approve / Change it / One commit instead (asked even when the subject came as the argument). Name the sensitive and large files you are leaving out.
  6. Commit. For each group in order: with more than one group, run git reset -q first so only that group is staged; then run commit-msg.mjs --subject "<s>" --files <a> --files <b> (--files once per path) and its command (or add, then commit). Finish with git log --oneline -<n>. On the console post run: { "event": "git-commits", "id": "<first short hash>", "commits": <n> } with the reread and a git-result line naming the hashes with op: "commit", so the board lights Push.
  7. Push. In the terminal, stop after committing with a one-line push hint and no push prompt. commit and push (or a push the person asks for) runs plan push / plan publish and asks its confirm. A rejected push: report it, suggest Pull, run nothing more.

Terminal

  • No instruction: print the status from state (branch, ahead/behind, changed files) and ask what to do, next first.
  • After an action: show the new state and one line naming the likely next step, then stop. A follow-up reply runs it; there is no "what next?" loop. After a push or publish (or when the branch is pushed with nothing left to commit), that next step may be /plan2code-pr-prep: run the checks and write the PR description.
  • Several actions in one instruction (commit and push): state the plan in one line, run each step in order, ask each ask-first confirm at its own step with the same confirm text the board shows, and stop at the first failure with git's error and classify-error's next.
  • An unclear instruction: offer the two or three likely readings through the question tool, the state-based guess first. Never run on a guess.
  • Print the pull-request link from pr-url after a push or publish (needsKind → ask the host's kind once and say it is remembered).

Session End

  • Done on the board, with something done this session: post finish with a headline, a body listing the commits with hashes, pushes, and branches created or deleted, no command, and "dashboard": true. Then keep waiting for the dashboard press (console-finish.md).
  • Done with nothing done: resume as the dashboard at once (open --resume <sid> --no-open --workflow dashboard, then read the dashboard skill, post its menu and follow its "Coming back from another skill"), with no finish screen.
  • A __stop: a Paused finish with the command /plan2code-git.
  • Terminal: the last state line is enough.

Returning context: run /plan2code-git again for the next action.