Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 18 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,7 @@ Optional, but they make devline leaner and more capable — `/devline:setup` off
| `/devline:plan <spec>` | Create a TDD implementation plan |
| `/devline:implement` | Implement tasks from an existing plan |
| `/devline:quick <task>` | 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 <error>` | Systematic root cause analysis |
| `/devline:deep-review` | Final merge-readiness audit (runs the reviewer at `scope: branch`) |
Expand Down Expand Up @@ -159,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.

Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -526,6 +528,20 @@ All modes output self-contained HTML previews -- inlined CSS, vanilla JS, Google

---

## Commits, Pushes and Pull Requests

`/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.
- **`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 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)).

---

## 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).
Expand Down Expand Up @@ -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

Expand Down
15 changes: 8 additions & 7 deletions skills/devline/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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 `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

**Exit cleanup sequence** (all foreground, in order):
Expand All @@ -177,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

Expand Down
113 changes: 113 additions & 0 deletions skills/git/SKILL.md
Original file line number Diff line number Diff line change
@@ -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. Do not use for general git questions.
argument-hint: "[commit|push|pr] [notes]"
user-invocable: true
disable-model-invocation: false
---

# Git — Commit, Push, Pull Request

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

`.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.
- **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. 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. 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), 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

**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...").

Message text and the PR body follow the `writing` skill. Skip preambles; evidence (before/after, test output) beats adjectives.

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 <branch>`. Otherwise `git push`.
- 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

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** (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.
- `## 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.

No `gh`, not authenticated, or no remote: say so and stop after writing the file.

## Hooks

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

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.
2 changes: 1 addition & 1 deletion skills/quick/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Loading