From 4453da4f400549800eeeaa14a5fcbc97239d2c13 Mon Sep 17 00:00:00 2001 From: Marlon Kranz Date: Sun, 15 Nov 2026 15:53:02 +0100 Subject: [PATCH 1/6] feat(git): add a git skill for commits, pushes and pull requests Commits and PRs were written ad hoc at the end of each pipeline, with no shared rules for message style or when pushing needs a confirmation. The skill has three modes (commit, push, pr). Messages follow Conventional Commits with a short body on why the change was needed and what it does beyond the diff; PR bodies go to an editable file and are posted only after the user says so. quick and the devline final gate commit through it, and the final gate can open a PR. --- README.md | 18 ++++++- skills/devline/SKILL.md | 9 ++-- skills/git/SKILL.md | 113 ++++++++++++++++++++++++++++++++++++++++ skills/quick/SKILL.md | 2 +- 4 files changed, 136 insertions(+), 6 deletions(-) create mode 100644 skills/git/SKILL.md diff --git a/README.md b/README.md index d590a8b..dda459c 100644 --- a/README.md +++ b/README.md @@ -107,6 +107,7 @@ Optional, but they make devline leaner and more capable — `/devline:setup` off | `/devline:plan ` | Create a TDD implementation plan | | `/devline:implement` | Implement tasks from an existing plan | | `/devline:quick ` | Fast lane -- implement, review, and commit a small change | +| `/devline:git [commit\|push\|pr]` | Commit with a Conventional Commit message, push, or write a PR body to an editable file and open the PR | | `/devline:review` | Code review of recent changes | | `/devline:debug ` | Systematic root cause analysis | | `/devline:deep-review` | Final merge-readiness audit (runs the reviewer at `scope: branch`) | @@ -342,6 +343,7 @@ claude-devline/ | | |-- SKILL.md | | +-- references/ # Implementation protocol, worktree protocol, agent health | |-- setup/ # /devline:setup +| |-- git/ # /devline:git (commit, push, PR body) | |-- find-docs/ # Context7 doc lookup (used by agents) | |-- writing/ # /writing (purpose-aware: AI-slop cleanup + scientific citation enforcement) | |-- kb-tdd-workflow/ # TDD methodology (injected into agents) @@ -526,6 +528,20 @@ All modes output self-contained HTML previews -- inlined CSS, vanilla JS, Google --- +## Commits, Pushes and Pull Requests + +`/devline:git` handles every commit, push and PR devline makes for you. Each mode includes the one before it, and the default is `commit`. + +- **`commit`** -- stages the files that belong to the change and writes a Conventional Commit. +- **`push`** -- commits anything pending, then pushes the current branch. +- **`pr`** -- commits, pushes, and writes the PR body to `.devline/pr-body.md`. It stops there so you can edit the file, and runs `gh pr create --body-file` only when you say to post. + +Messages follow the `writing` skill. The body says why the change was needed and what it does at a level the code doesn't show, and never restates the diff. The PR body has Background, What it does, Details, Screenshots (UI changes only) and How to verify, in that order, unless the repo has a PR template, which takes precedence. + +The skill never pushes to a protected branch without asking and never force-pushes on its own. It uses `--force-with-lease` only when you ask. It never merges. New branch names follow `branch_format` and `branch_kinds` (see [Branching strategy](#branching-strategy)). + +--- + ## Writing and Content The `/writing` skill takes a draft and strips the AI slop out of it — negative parallelism, tricolon abuse, uniform sentence length, sycophantic filler — while catching mistakes, so the text reads like a person wrote it. It can write from scratch too, but its best use is on writing you've already drafted: **write it yourself, then run `/writing` to clean it up and find mistakes.** It detects the purpose first and applies purpose-specific rules; for scientific writing it enforces a strict citation contract before returning anything (see below). @@ -604,7 +620,7 @@ fast_lane: always |---------|---------|-------------| | `branch_format` | `"{kind}/{title}"` | Branch naming (`{kind}`, `{title}` placeholders) | | `branch_kinds` | `"feat\|fix\|refactor\|docs\|chore\|test\|ci"` | Allowed branch kinds | -| `protected_branches` | `"(main\|master\|develop\|release\|production\|staging)"` | Branches the pipeline auto-creates a feature branch off of | +| `protected_branches` | `"(main\|master\|develop\|release\|production\|staging)"` | Branches the pipeline auto-creates a feature branch off of, and branches `/devline:git` will not push to without asking | #### Framework overrides diff --git a/skills/devline/SKILL.md b/skills/devline/SKILL.md index 85b8cbf..f1a5c23 100644 --- a/skills/devline/SKILL.md +++ b/skills/devline/SKILL.md @@ -32,9 +32,9 @@ A single task, run in place — no worktrees, no waves, no gates. 1. **Branch setup** (Stage 0). 2. **Implement** — one implementer agent, TDD at the right level (unit for pure logic, integration for persistence/endpoints; see `kb-tdd-workflow`). 3. **ONE `reviewer` (scope=task)** — the standard per-task review. Run a fix cycle if it returns blocking findings. -4. **Commit.** Then auto-proceed and ask only merge-or-not. +4. **Commit** with the `git` skill (commit mode). Then auto-proceed and ask only: merge, open a PR (`git` pr mode), or leave it. -The fast lane SKIPS: brainstorm + its approval gate; design-system (Stage 1.5); the full plan doc + plan approval gate; the mandatory Feature E2E task; worktree/wave machinery (the single task runs in place); the deferred-findings batch-fix cycle (Stage 3.5); the docs-keeper full documentation scan (Stage 4); `reviewer scope=branch` / deep review (Stage 5); and the final approval gate (it auto-proceeds, asking only whether to merge). +The fast lane SKIPS: brainstorm + its approval gate; design-system (Stage 1.5); the full plan doc + plan approval gate; the mandatory Feature E2E task; worktree/wave machinery (the single task runs in place); the deferred-findings batch-fix cycle (Stage 3.5); the docs-keeper full documentation scan (Stage 4); `reviewer scope=branch` / deep review (Stage 5); and the final approval gate (it auto-proceeds, asking only whether to merge or open a PR). ## Progress Tracking @@ -163,8 +163,9 @@ When deep review approves: 2. Report summary (what was built, files, test results) 3. Ask user via AskUserQuestion: - "I found a mistake / want to add something" → route to debugger (runtime bugs) or planner (everything else), restart from Stage 2 - - "Merge to main and exit" → commit, squash merge (confirm target branch first), cleanup - - "Commit and exit" → commit, cleanup + - "Merge to main and exit" → commit with the `git` skill, then squash merge into the target branch (confirm it first) as one commit, cleanup + - "Commit and exit" → commit with the `git` skill, cleanup + - "Open a PR and exit" → `git` pr mode; run cleanup only after the PR is posted or the user declines (cleanup deletes `.devline/pr-body.md`) - "Exit" → cleanup **Exit cleanup sequence** (all foreground, in order): diff --git a/skills/git/SKILL.md b/skills/git/SKILL.md new file mode 100644 index 0000000..72822ea --- /dev/null +++ b/skills/git/SKILL.md @@ -0,0 +1,113 @@ +--- +name: git +description: Commit, push, or open a pull request with a Conventional Commit message and a PR body the user can edit before it is posted. Use when the user asks to commit, commit and push, push the branch, open/create a PR, write a commit message, or write a PR description, and when devline or quick reach their commit step. Do not use for general git questions (how rebase works, reading history, resolving a conflict). +argument-hint: "[commit|push|pr] [notes]" +user-invocable: true +disable-model-invocation: false +--- + +# Git — Commit, Push, Pull Request + +You make the commits, pushes and pull requests devline produces on the user's behalf. The goal is a commit message and a PR body the user would post without editing. + +## Defaults + +A later config layer may override these; until then they apply as written. The rest of this skill refers to them instead of repeating values. + +- **Protected branches** (`protected_branches`): main, master, develop, release, production, staging. +- **Branch names**: `branch_format` `{kind}/{title}`; `branch_kinds` feat, fix, refactor, docs, chore, test, ci. Values in `.claude/devline.local.md` win. +- **Granularity**: one commit per logical change. +- **Subject**: at most 72 characters. Body wrapped at 72. +- **PR body file**: `.devline/pr-body.md`; screenshots in `.devline/pr-assets/`. +- **Never** force push on your own initiative, never run `gh pr merge`, never push to a protected branch without an explicit yes. + +## Modes + +``` +/devline:git [commit|push|pr] [notes] (no argument: commit) + commit : branch guard -> stage the related files -> Conventional Commit + push : commit (if anything is pending) -> push the current branch + pr : commit + push -> PR body file -> user edits -> gh pr create +``` + +Each mode includes the one before it. Free text maps to the nearest mode ("commit and push" is `push`, "open a PR" is `pr`). `push` and `pr` skip the commit step when the tree is clean. Notes after the mode, and any context paths a caller passes, feed the *why*. If `.devline/brainstorm.md` or `.devline/plan.md` exist and their `**Branch:**` matches the current branch, read them for the reason behind the change. + +## Branch guard (all modes) + +Read `protected_branches`, `branch_format` and `branch_kinds` from `.claude/devline.local.md`, falling back to the Defaults. If the current branch is protected: + +- `commit`: ask whether to branch off first. Offer a name built from `branch_format`, with `{kind}` taken from the commit type when it is one of `branch_kinds` (otherwise `chore`) and `{title}` a short kebab-case summary. +- `push` / `pr`: do not push to it without an explicit yes. Offer to branch off as above. In a non-interactive run, stop and report instead of pushing. + +## Staging + +1. Read `git status` and `git diff` (plus `git diff --staged`) before touching anything. +2. Stage the files that belong to the change by name. Never `git add -A` or `git add .`. +3. Never stage secrets (`.env`, keys, tokens, credentials) or junk (build output, caches, editor files, logs). Mention anything suspicious you left out. +4. If the tree holds unrelated changes, propose separate commits, one per logical change, and say which files go where. Do not fold them into one mixed commit. + +## Commit message + +**Subject:** `type(scope)!: summary`. Imperative mood, lowercase after the colon, no trailing period, within the Defaults length. Scope is optional; use it when the change sits in one clear area. + +Types: `feat`, `fix`, `refactor`, `docs`, `chore`, `test`, `ci`, `perf`, `build`, `style`. Add `!` and a `BREAKING CHANGE:` footer when behaviour users rely on changes. + +**Body** (omit it for trivial changes such as a typo): + +- First, why the change was needed: the bug, the limitation, the request. +- Then what it does, at a level the code does not show: the approach, the trade-off, what now behaves differently. +- Never list files, restate the diff line by line, or narrate ("This commit...", "This PR..."). + +The message text follows the `writing` skill's rules; apply them. + +Example shape: + +``` +fix(parser): keep quoted commas inside one field + +CSV rows with a quoted value such as "Smith, Jane" were split into two +columns, so imports silently shifted every later field. + +The tokenizer now tracks quote state and only treats a comma as a +separator outside quotes. Escaped quotes ("") inside a field still work. +``` + +Pass the message with a heredoc (`git commit -F - <<'EOF'`) or a `-F` file so line breaks survive. + +**Failures:** if a pre-commit hook fails, fix the cause, re-stage and make a new commit. Never `--no-verify`. Never `--amend` unless the user asked for it. + +## Push + +- No upstream yet: `git push -u origin `. Otherwise `git push`. +- Rejected push: stop. Run `git fetch`, explain how local and remote diverged, and ask what to do. Do not force push on your own initiative. +- The user asks to update a rebased or amended branch: `git push --force-with-lease`, never bare `--force`. + +## PR mode + +1. **Base:** the repo default (`gh repo view --json defaultBranchRef -q .defaultBranchRef.name`) unless the user named one. State the base you use. +2. **Title:** the same Conventional Commits form as a subject; squash merges use it as the commit subject. +3. **Template:** if `.github/pull_request_template.md` or `.github/PULL_REQUEST_TEMPLATE/` exists, its structure wins and the content below fills it. +4. **Body sections**, in this order, omitting any that would be empty: + - **Background**: the problem or need, in a few sentences. + - **What it does**: the change in the abstract, a few sentences. + - **Details**: only what a reviewer needs to judge the change. Add a small diff sketch, call tree or file tree only if it makes a point clearer than prose. + - **Screenshots**: UI changes only. Capture headlessly with what the project already has (Playwright, an existing screenshot script), save to the Defaults assets directory, and put one placeholder line per image in the body. `gh` cannot upload images, so tell the user to drag them into the PR on GitHub. If nothing can capture, say so and leave the placeholder. Never install a tool for this. + - **How to verify**: exact commands or steps, and what the reviewer should see. +5. **Write** the body to the Defaults PR body file. Create `.devline/` and add it to `.gitignore` first if either is missing. Print the proposed title and the absolute path of the file, then stop and wait for the user. +6. **Post** only when the user says so: `gh pr create --base --title "" --body-file .devline/pr-body.md`, then report the PR URL. Never run `gh pr merge`; merging is the user's call. + +No `gh`, not authenticated, or no remote: say so and stop after writing the file. + +Prose in the body follows the `writing` skill as well. Skip preambles; evidence (before/after, test output) beats adjectives. + +## Hooks + +devline's hooks ask before a bare force push and before `gh pr merge`. `--force-with-lease` and `gh pr create` pass. When a hook asks, put the question to the user; never rephrase or split a command to get around it. + +## Credits + +Paraphrased, not copied, from: + +- obra/superpowers, `finishing-a-development-branch` (MIT): the user owns the integration decision, confirm the base, investigate a rejected push instead of forcing it, follow the repo's PR template. +- mattpocock/skills, `pr` (MIT; its summary section credits humanlayer `show-me`): brief prose, evidence over description, a small visual only when it clarifies. +- Conventional Commits 1.0.0 (CC-BY-3.0): the subject and `BREAKING CHANGE:` format. diff --git a/skills/quick/SKILL.md b/skills/quick/SKILL.md index 96d387f..1743208 100644 --- a/skills/quick/SKILL.md +++ b/skills/quick/SKILL.md @@ -15,7 +15,7 @@ Steps (single task, run in place — no worktrees, no waves, no gates): 1. **Branch setup** — Stage 0 of the `devline` skill (branch off protected branches, create `.devline/`). 2. **Implement** — launch ONE **implementer** agent with the task. It writes tests first (TDD at the right level: unit for pure logic, integration for persistence/endpoints — see `kb-tdd-workflow`), then implements. The fast lane runs at `focused` depth — small changes don't warrant deep, so skip exhaustive per-method units for trivial code; cover behavior plus any genuinely hard logic. 3. **Review** — launch ONE **reviewer** agent (scope=task). Run a fix cycle if it returns blocking findings. -4. **Commit**, then ask only whether to merge (auto-proceed otherwise). +4. **Commit** with the `git` skill (commit mode), then ask only whether to merge, open a PR (`git` pr mode), or leave it (auto-proceed otherwise). Explicitly SKIP: brainstorm + its gate, design-system, the full plan doc + plan gate, the Feature E2E task, worktree/wave machinery, the deferred-findings batch-fix cycle, the docs-keeper full scan, `reviewer scope=branch` (deep review), and the final approval gate. From adc820d53003ae2cfa826f7a09ffa6d6c0381bed Mon Sep 17 00:00:00 2001 From: Marlon Kranz <dev@marlonkranz.com> Date: Sun, 15 Nov 2026 15:57:57 +0100 Subject: [PATCH 2/6] refactor(git): state each rule once and narrow the skill trigger --- skills/git/SKILL.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/skills/git/SKILL.md b/skills/git/SKILL.md index 72822ea..3b543f8 100644 --- a/skills/git/SKILL.md +++ b/skills/git/SKILL.md @@ -1,6 +1,6 @@ --- name: git -description: Commit, push, or open a pull request with a Conventional Commit message and a PR body the user can edit before it is posted. Use when the user asks to commit, commit and push, push the branch, open/create a PR, write a commit message, or write a PR description, and when devline or quick reach their commit step. Do not use for general git questions (how rebase works, reading history, resolving a conflict). +description: Commit, push, or open a pull request with a Conventional Commit message and a PR body the user can edit before it is posted. Use when the user asks to commit, commit and push, push the branch, open/create a PR, write a commit message, or write a PR description. Do not use for general git questions (how rebase works, reading history, resolving a conflict). argument-hint: "[commit|push|pr] [notes]" user-invocable: true disable-model-invocation: false @@ -37,7 +37,7 @@ Each mode includes the one before it. Free text maps to the nearest mode ("commi Read `protected_branches`, `branch_format` and `branch_kinds` from `.claude/devline.local.md`, falling back to the Defaults. If the current branch is protected: - `commit`: ask whether to branch off first. Offer a name built from `branch_format`, with `{kind}` taken from the commit type when it is one of `branch_kinds` (otherwise `chore`) and `{title}` a short kebab-case summary. -- `push` / `pr`: do not push to it without an explicit yes. Offer to branch off as above. In a non-interactive run, stop and report instead of pushing. +- `push` / `pr`: offer to branch off as above. In a non-interactive run, stop and report instead of pushing. ## Staging @@ -58,7 +58,7 @@ Types: `feat`, `fix`, `refactor`, `docs`, `chore`, `test`, `ci`, `perf`, `build` - Then what it does, at a level the code does not show: the approach, the trade-off, what now behaves differently. - Never list files, restate the diff line by line, or narrate ("This commit...", "This PR..."). -The message text follows the `writing` skill's rules; apply them. +Message text and the PR body follow the `writing` skill. Skip preambles; evidence (before/after, test output) beats adjectives. Example shape: @@ -79,7 +79,7 @@ Pass the message with a heredoc (`git commit -F - <<'EOF'`) or a `-F` file so li ## Push - No upstream yet: `git push -u origin <branch>`. Otherwise `git push`. -- Rejected push: stop. Run `git fetch`, explain how local and remote diverged, and ask what to do. Do not force push on your own initiative. +- Rejected push: stop. Run `git fetch`, explain how local and remote diverged, and ask what to do. - The user asks to update a rebased or amended branch: `git push --force-with-lease`, never bare `--force`. ## PR mode @@ -98,8 +98,6 @@ Pass the message with a heredoc (`git commit -F - <<'EOF'`) or a `-F` file so li No `gh`, not authenticated, or no remote: say so and stop after writing the file. -Prose in the body follows the `writing` skill as well. Skip preambles; evidence (before/after, test output) beats adjectives. - ## Hooks devline's hooks ask before a bare force push and before `gh pr merge`. `--force-with-lease` and `gh pr create` pass. When a hook asks, put the question to the user; never rephrase or split a command to get around it. From bd39bf6c3fb5e707c741cba607e42a6181409e76 Mon Sep 17 00:00:00 2001 From: Marlon Kranz <dev@marlonkranz.com> Date: Sun, 15 Nov 2026 16:08:04 +0100 Subject: [PATCH 3/6] fix(git): keep text requests draft-only and protect PR screenshots A request for only a commit message or PR description committed and pushed; it now only drafts. Exit cleanup kept deleting .devline/pr-assets before the screenshots could be uploaded. The squash commit that lands on the target branch now follows the skill's message rules, and protected-branch and override rules are stated once. --- README.md | 2 +- skills/devline/SKILL.md | 6 +++--- skills/git/SKILL.md | 21 +++++++++++---------- 3 files changed, 15 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index dda459c..af951de 100644 --- a/README.md +++ b/README.md @@ -530,7 +530,7 @@ All modes output self-contained HTML previews -- inlined CSS, vanilla JS, Google ## Commits, Pushes and Pull Requests -`/devline:git` handles every commit, push and PR devline makes for you. Each mode includes the one before it, and the default is `commit`. +`/devline:git` handles the final commit, push and PR at the end of a pipeline or fast lane, or whenever you ask. Each mode includes the one before it, and the default is `commit`. - **`commit`** -- stages the files that belong to the change and writes a Conventional Commit. - **`push`** -- commits anything pending, then pushes the current branch. diff --git a/skills/devline/SKILL.md b/skills/devline/SKILL.md index f1a5c23..7beef7b 100644 --- a/skills/devline/SKILL.md +++ b/skills/devline/SKILL.md @@ -163,7 +163,7 @@ When deep review approves: 2. Report summary (what was built, files, test results) 3. Ask user via AskUserQuestion: - "I found a mistake / want to add something" → route to debugger (runtime bugs) or planner (everything else), restart from Stage 2 - - "Merge to main and exit" → commit with the `git` skill, then squash merge into the target branch (confirm it first) as one commit, cleanup + - "Merge to main and exit" → commit with the `git` skill, then `git merge --squash` into the target branch (confirm it first) and write the single commit's message per the git skill's Commit message rules; the branch guard does not apply because the user confirmed the target. Then cleanup - "Commit and exit" → commit with the `git` skill, cleanup - "Open a PR and exit" → `git` pr mode; run cleanup only after the PR is posted or the user declines (cleanup deletes `.devline/pr-body.md`) - "Exit" → cleanup @@ -178,8 +178,8 @@ When deep review approves: ```bash git branch --list 'worktree-agent-*' | xargs -r git branch -D 2>/dev/null ``` -3. Clean `.devline/` contents (keep the directory): `find .devline/ -mindepth 1 -exec rm -rf {} + 2>/dev/null` -4. Output final summary and stop immediately. +3. Clean `.devline/` contents (keep the directory), but keep `.devline/pr-assets/` when it exists so screenshots can still be uploaded: `find .devline/ -mindepth 1 -not -path '.devline/pr-assets' -not -path '.devline/pr-assets/*' -exec rm -rf {} + 2>/dev/null` +4. Output final summary (say that `.devline/pr-assets/` was kept, if it was) and stop immediately. ## General Rules diff --git a/skills/git/SKILL.md b/skills/git/SKILL.md index 3b543f8..3f09477 100644 --- a/skills/git/SKILL.md +++ b/skills/git/SKILL.md @@ -8,14 +8,14 @@ disable-model-invocation: false # Git — Commit, Push, Pull Request -You make the commits, pushes and pull requests devline produces on the user's behalf. The goal is a commit message and a PR body the user would post without editing. +You handle the final commit, push and pull request at the end of a devline pipeline or fast lane, or whenever the user asks. The goal is a commit message and a PR body the user would post without editing. ## Defaults -A later config layer may override these; until then they apply as written. The rest of this skill refers to them instead of repeating values. +`.claude/devline.local.md` overrides any value here; a later config layer may replace this section. The rest of this skill refers to these values instead of repeating them. - **Protected branches** (`protected_branches`): main, master, develop, release, production, staging. -- **Branch names**: `branch_format` `{kind}/{title}`; `branch_kinds` feat, fix, refactor, docs, chore, test, ci. Values in `.claude/devline.local.md` win. +- **Branch names**: `branch_format` `{kind}/{title}`; `branch_kinds` feat, fix, refactor, docs, chore, test, ci. - **Granularity**: one commit per logical change. - **Subject**: at most 72 characters. Body wrapped at 72. - **PR body file**: `.devline/pr-body.md`; screenshots in `.devline/pr-assets/`. @@ -30,20 +30,21 @@ A later config layer may override these; until then they apply as written. The r pr : commit + push -> PR body file -> user edits -> gh pr create ``` -Each mode includes the one before it. Free text maps to the nearest mode ("commit and push" is `push`, "open a PR" is `pr`). `push` and `pr` skip the commit step when the tree is clean. Notes after the mode, and any context paths a caller passes, feed the *why*. If `.devline/brainstorm.md` or `.devline/plan.md` exist and their `**Branch:**` matches the current branch, read them for the reason behind the change. +Each mode includes the one before it. Free text maps to the nearest mode ("commit and push" is `push`, "open a PR" is `pr`). `push` and `pr` skip the commit step when the tree is clean. A request only for a message or description is draft-only: print the commit message, or write the PR body file, and do not commit, push or post unless the user asked to. Notes after the mode, and any context paths a caller passes, feed the *why*. If `.devline/plan.md` exists and its `**Branch:**` matches the current branch, read it, and `.devline/brainstorm.md` too (it has no branch header), for the reason behind the change. ## Branch guard (all modes) Read `protected_branches`, `branch_format` and `branch_kinds` from `.claude/devline.local.md`, falling back to the Defaults. If the current branch is protected: - `commit`: ask whether to branch off first. Offer a name built from `branch_format`, with `{kind}` taken from the commit type when it is one of `branch_kinds` (otherwise `chore`) and `{title}` a short kebab-case summary. -- `push` / `pr`: offer to branch off as above. In a non-interactive run, stop and report instead of pushing. +- `push` / `pr`: offer to branch off as above. If the user declines, push only after an explicit yes to pushing to that branch. +- Non-interactive run: stop and report; do not commit on the protected branch. ## Staging 1. Read `git status` and `git diff` (plus `git diff --staged`) before touching anything. 2. Stage the files that belong to the change by name. Never `git add -A` or `git add .`. -3. Never stage secrets (`.env`, keys, tokens, credentials) or junk (build output, caches, editor files, logs). Mention anything suspicious you left out. +3. Never stage secrets (`.env`, keys, tokens, credentials), junk (build output, caches, editor files, logs) or `.devline/`. If `.devline/` is not ignored, add it to `.git/info/exclude` first (local, no tracked-file change). Mention anything suspicious you left out. 4. If the tree holds unrelated changes, propose separate commits, one per logical change, and say which files go where. Do not fold them into one mixed commit. ## Commit message @@ -86,21 +87,21 @@ Pass the message with a heredoc (`git commit -F - <<'EOF'`) or a `-F` file so li 1. **Base:** the repo default (`gh repo view --json defaultBranchRef -q .defaultBranchRef.name`) unless the user named one. State the base you use. 2. **Title:** the same Conventional Commits form as a subject; squash merges use it as the commit subject. -3. **Template:** if `.github/pull_request_template.md` or `.github/PULL_REQUEST_TEMPLATE/` exists, its structure wins and the content below fills it. +3. **Template:** if `pull_request_template.md` (any case) exists in the repo root, `docs/` or `.github/`, or `.github/PULL_REQUEST_TEMPLATE/` exists, its structure wins and the content below fills it. 4. **Body sections**, in this order, omitting any that would be empty: - **Background**: the problem or need, in a few sentences. - **What it does**: the change in the abstract, a few sentences. - **Details**: only what a reviewer needs to judge the change. Add a small diff sketch, call tree or file tree only if it makes a point clearer than prose. - **Screenshots**: UI changes only. Capture headlessly with what the project already has (Playwright, an existing screenshot script), save to the Defaults assets directory, and put one placeholder line per image in the body. `gh` cannot upload images, so tell the user to drag them into the PR on GitHub. If nothing can capture, say so and leave the placeholder. Never install a tool for this. - **How to verify**: exact commands or steps, and what the reviewer should see. -5. **Write** the body to the Defaults PR body file. Create `.devline/` and add it to `.gitignore` first if either is missing. Print the proposed title and the absolute path of the file, then stop and wait for the user. -6. **Post** only when the user says so: `gh pr create --base <base> --title "<title>" --body-file .devline/pr-body.md`, then report the PR URL. Never run `gh pr merge`; merging is the user's call. +5. **Write** the body to the Defaults PR body file. Create `.devline/` first if missing, and exclude it per Staging. Print the proposed title and the absolute path of the file, then stop and wait for the user. +6. **Post** only when the user says so. If `gh pr view` shows an open PR for the branch, offer `gh pr edit --body-file .devline/pr-body.md` instead. Otherwise `gh pr create --base <base> --title "<title>" --body-file .devline/pr-body.md`, then report the PR URL. Never run `gh pr merge`; merging is the user's call. No `gh`, not authenticated, or no remote: say so and stop after writing the file. ## Hooks -devline's hooks ask before a bare force push and before `gh pr merge`. `--force-with-lease` and `gh pr create` pass. When a hook asks, put the question to the user; never rephrase or split a command to get around it. +When devline's hooks are active (they skip in default permission mode), they ask before a bare force push and before `gh pr merge`; `--force-with-lease` and `gh pr create` pass. The rules in this skill apply either way. When a hook asks, put the question to the user; never rephrase or split a command to get around it. ## Credits From 34cf2570e0513c5b080eb13056e36b3988af5054 Mon Sep 17 00:00:00 2001 From: Marlon Kranz <dev@marlonkranz.com> Date: Sun, 15 Nov 2026 16:11:18 +0100 Subject: [PATCH 4/6] fix(devline): ignore .devline via .git/info/exclude in Stage 0 Stage 0 edited the tracked .gitignore while the git skill already used the local exclude file, so a fast-lane run left an unrelated tracked change. --- README.md | 2 +- skills/devline/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index af951de..3ea781b 100644 --- a/README.md +++ b/README.md @@ -160,7 +160,7 @@ flowchart LR <details> <summary><strong>Stage 0: Branch Setup</strong> (automatic)</summary> -Reads branching config from `.claude/devline.local.md`. If you're on a protected branch (main, master, develop, release, production, staging), it creates a feature branch using your configured format (default: `feat/your-feature-name`). Sets up the `.devline/` working directory and adds it to `.gitignore`. +Reads branching config from `.claude/devline.local.md`. If you're on a protected branch (main, master, develop, release, production, staging), it creates a feature branch using your configured format (default: `feat/your-feature-name`). Sets up the `.devline/` working directory and, if git does not already ignore it, adds it to `.git/info/exclude` so no tracked file changes. If a previous pipeline left artifacts behind, it detects them and asks whether to resume or start fresh. diff --git a/skills/devline/SKILL.md b/skills/devline/SKILL.md index 7beef7b..ecf8a36 100644 --- a/skills/devline/SKILL.md +++ b/skills/devline/SKILL.md @@ -77,7 +77,7 @@ Read `.claude/devline.local.md` (if it exists): 1. Read branching settings from `.claude/devline.local.md` (`branch_format`, `branch_kinds`, `protected_branches`) 2. **Active pipeline detection:** If `.devline/state.md` exists, this is a resume scenario (new conversation or post-compaction). Run the recovery protocol (`references/recovery.md`) and ask the user whether to resume or start fresh. If resuming, skip to the recovered stage. 3. If on a protected branch (default: main, master, develop, release, production, staging): create a branch using `branch_format` (default: `{kind}/{title}`). The `{kind}` must be one of `branch_kinds` (default: feat, fix, refactor, docs, chore, test, ci). -4. Create `.devline/` directory and add to `.gitignore` if needed +4. Create `.devline/`; if git does not already ignore it, add it to `.git/info/exclude` (local, no tracked-file change) 5. **CLAUDE.md check:** If `CLAUDE.md` does not exist in the project root, warn the user: "No CLAUDE.md found. Run `/devline:setup` to create one — it stores project conventions that improve pipeline quality across runs." Continue without it (not blocking). 6. **Stale artifact check:** If `.devline/plan.md` or any `.devline/plan-phase-*.md` files already exist, read the `**Branch:**` header from `plan.md` (or `plan-phase-1.md` if only phase plans exist). If it references a different branch or the `**Status:**` is `completed`, delete all `.devline/` artifacts (including `plan-phase-*.md`) and inform user. If it matches current branch with `active` status, ask user whether to resume or start fresh. From dc42840b94b1fdb976a2c8ecca98e60f9fc371b2 Mon Sep 17 00:00:00 2001 From: Marlon Kranz <dev@marlonkranz.com> Date: Sun, 15 Nov 2026 20:21:57 +0100 Subject: [PATCH 5/6] fix(git): follow the repo's PR template, otherwise a short Description The fixed Background / What it does / How to verify sections read as generated and ignored the repo's own template. The body now uses the template when one exists; otherwise a short Description of what and why, the technical details, and a Verification section only when needed. --- README.md | 2 +- skills/git/SKILL.md | 11 ++++++----- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 3ea781b..9aa94c9 100644 --- a/README.md +++ b/README.md @@ -536,7 +536,7 @@ All modes output self-contained HTML previews -- inlined CSS, vanilla JS, Google - **`push`** -- commits anything pending, then pushes the current branch. - **`pr`** -- commits, pushes, and writes the PR body to `.devline/pr-body.md`. It stops there so you can edit the file, and runs `gh pr create --body-file` only when you say to post. -Messages follow the `writing` skill. The body says why the change was needed and what it does at a level the code doesn't show, and never restates the diff. The PR body has Background, What it does, Details, Screenshots (UI changes only) and How to verify, in that order, unless the repo has a PR template, which takes precedence. +Messages follow the `writing` skill. The body says why the change was needed and what it does at a level the code doesn't show, and never restates the diff. The PR body follows the repo's PR template when there is one. Otherwise it has a short `## Description` (what and why: intended effect, use case, issue), then the technical details (how it works, trade-offs, notable effects, closed issues), screenshots for UI changes, and a short `## Verification` only when it is needed. The skill never pushes to a protected branch without asking and never force-pushes on its own. It uses `--force-with-lease` only when you ask. It never merges. New branch names follow `branch_format` and `branch_kinds` (see [Branching strategy](#branching-strategy)). diff --git a/skills/git/SKILL.md b/skills/git/SKILL.md index 3f09477..c06ab83 100644 --- a/skills/git/SKILL.md +++ b/skills/git/SKILL.md @@ -88,12 +88,13 @@ Pass the message with a heredoc (`git commit -F - <<'EOF'`) or a `-F` file so li 1. **Base:** the repo default (`gh repo view --json defaultBranchRef -q .defaultBranchRef.name`) unless the user named one. State the base you use. 2. **Title:** the same Conventional Commits form as a subject; squash merges use it as the commit subject. 3. **Template:** if `pull_request_template.md` (any case) exists in the repo root, `docs/` or `.github/`, or `.github/PULL_REQUEST_TEMPLATE/` exists, its structure wins and the content below fills it. -4. **Body sections**, in this order, omitting any that would be empty: - - **Background**: the problem or need, in a few sentences. - - **What it does**: the change in the abstract, a few sentences. - - **Details**: only what a reviewer needs to judge the change. Add a small diff sketch, call tree or file tree only if it makes a point clearer than prose. +4. **Body** (no template), in this order, omitting any part that would be empty: + - `## Description`: a very short overview of what the change does and why: the intended effect, the use case, the issue it addresses. A few sentences. + - Technical details below it, as plain paragraphs or a short list: how it works, trade-offs, notable side effects, `Closes #N` for closed issues. Only what a reviewer needs to judge the change; a small diff sketch or tree only when it is clearer than prose. - **Screenshots**: UI changes only. Capture headlessly with what the project already has (Playwright, an existing screenshot script), save to the Defaults assets directory, and put one placeholder line per image in the body. `gh` cannot upload images, so tell the user to drag them into the PR on GitHub. If nothing can capture, say so and leave the placeholder. Never install a tool for this. - - **How to verify**: exact commands or steps, and what the reviewer should see. + - `## Verification`: only when a reviewer can't easily tell how to check the change. Short: the command or steps and what they should see. + + No generic section names such as "Background" or "What it does". 5. **Write** the body to the Defaults PR body file. Create `.devline/` first if missing, and exclude it per Staging. Print the proposed title and the absolute path of the file, then stop and wait for the user. 6. **Post** only when the user says so. If `gh pr view` shows an open PR for the branch, offer `gh pr edit --body-file .devline/pr-body.md` instead. Otherwise `gh pr create --base <base> --title "<title>" --body-file .devline/pr-body.md`, then report the PR URL. Never run `gh pr merge`; merging is the user's call. From 69c4f5e1bda4bafe65d4f544cd63286aa7c7c851 Mon Sep 17 00:00:00 2001 From: Marlon Kranz <dev@marlonkranz.com> Date: Mon, 16 Nov 2026 10:54:30 +0100 Subject: [PATCH 6/6] Update git skill description and wording Refine description for clarity and conciseness in the git skill documentation. --- skills/git/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/git/SKILL.md b/skills/git/SKILL.md index c06ab83..1af26e3 100644 --- a/skills/git/SKILL.md +++ b/skills/git/SKILL.md @@ -1,6 +1,6 @@ --- name: git -description: Commit, push, or open a pull request with a Conventional Commit message and a PR body the user can edit before it is posted. Use when the user asks to commit, commit and push, push the branch, open/create a PR, write a commit message, or write a PR description. Do not use for general git questions (how rebase works, reading history, resolving a conflict). +description: Commit, push, or open a pull request with a Conventional Commit message and a PR body the user can edit before it is posted. Use when the user asks to commit, commit and push, push the branch, open/create a PR, write a commit message, or write a PR description. Do not use for general git questions. argument-hint: "[commit|push|pr] [notes]" user-invocable: true disable-model-invocation: false @@ -8,7 +8,7 @@ disable-model-invocation: false # Git — Commit, Push, Pull Request -You handle the final commit, push and pull request at the end of a devline pipeline or fast lane, or whenever the user asks. The goal is a commit message and a PR body the user would post without editing. +You handle commits, pushes and pull requests during or at the end of a devline pipeline or fast lane, or whenever the user asks. The goal is a commit message and a PR body the user would write themselves. ## Defaults