mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-16 20:45:33 -08:00
Sync upstream into v2.7.0: the git board skill replaces git-commit (ticket-free), and console docs and tests are split up
AI Assisted
This commit is contained in:
1 parent
6114914dd6
commit
f328406bb5
103 files changed
+17636
-9991
No files matched your search
@@ -0,0 +1,118 @@
|
||||
# 🔀 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 (<D>: 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 <D>/console.md and <D>/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 above the board; afterwards the board is theirs with Push lit. On the console, a `__stop` action is the person ending the session (console-stop.md); at every session end post `finish` BEFORE `stop`.
|
||||
|
||||
## 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 (`{ "i": "__git", "type": "git", "op": "switch", "branch": "main" }`, field shapes 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`, labelled **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`), `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 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**: Session End.
|
||||
- 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, 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.
|
||||
- **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 finish whose headline starts "Paused", with `"command": "/plan2code-git"`, then `stop`.
|
||||
- **Terminal:** the last state line is enough.
|
||||
|
||||
Returning context: run `/plan2code-git` again for the next action.
|
||||
Reference in new issue
Block a user