# @cleepi/git

Cleepi's git conventions as a pi package. Install in any repo
where you want a clean, standardised commit history — and never
another `Co-authored-by: Claude` line ever again.

## What's in the box

- **`skills/git-commit/SKILL.md`** — commit-message
  convention (Conventional Commits + AngularJS types,
  monorepo-aware domain, ticket-id discipline).
- **`skills/git-branch/SKILL.md`** — branch naming
  convention: `<type>/<ticket>-<slug>` with ticket optional.
- **`skills/git-pr/SKILL.md`** — PR/MR shape: title from
  branch, body 1–3 sentences + optional bullets. PRs should
  be small and modular.
- **`/commit <type> <message>`** — resolves domain + ticket,
  assembles the message, strips `Co-authored-by:`, asks
  before committing.
- **`/pr [<description>]`** — derives title from current
  branch, detects GitHub/GitLab, runs `gh pr create` /
  `glab mr create` or prints for manual paste.

## The 30-second version

Every cleepi commit follows this shape:

```
<type>(<domain>): [<ticket-id> ]<message>
```

Examples:

```
feat(crew): AC-201 add reviewer pre-step
refactor(sdd): AC-202 collapse Why-now into Why
docs(crew): fix README install path
chore(meta): bump prettier
fix(atlassian): DRAFT-007 handle empty JQL response
```

**Hard rules (non-negotiable):**

- One line. No body. No footers.
- **NEVER `Co-authored-by:`.** Not for AI assistants. Not for
  anyone. Strip it if your tooling tries to add it.
- No `Signed-off-by:` either.
- No emoji, no trailing period.
- Imperative, present tense, lowercase first letter of message.

For the full discipline (type table, domain rules, ticket-id
resolution chain, anti-patterns, voice), see
[`skills/git-commit/SKILL.md`](skills/git-commit/SKILL.md). It's
the source of truth.

## Install

Global (every pi session gets the convention):

```bash
pi install git:github.com/cleevio/cleepi/packages/git
```

Project-local (recommended for repos adopting the convention as
their actual standard):

```bash
cd <repo>
pi install -l git:github.com/cleevio/cleepi/packages/git
```

## How `/pr` works

```
/pr Rename the primary button per the AC-123 redesign.
```

1. Reads the current branch: `feat/AC-123-rename-primary-button`.
2. Derives title mechanically:
   `feat(AC-123): rename primary button`. **No diff reading.**
3. Uses your description as the body (or asks if you didn't
   pass one). Bullets optional, never invented.
4. Detects host from `git remote get-url origin`.
5. Shows you title + body + host. Asks `[y / N / edit]`.
6. Runs `gh pr create` / `glab mr create`, or prints for
   manual paste if neither CLI is installed.

If the branch doesn't match `<type>/...`, `/pr` refuses and
tells you to rename the branch first. The point of the
convention is that the title is mechanical.

## How `/commit` works

```
/commit feat add reviewer pre-step
```

1. Validates `feat` against the Angular type set.
2. Resolves domain: cwd is inside `packages/crew/` → `crew`.
3. Resolves ticket-id: cwd is under
   `docs/AC-201-reviewer-prestep/` → `AC-201`.
4. Assembles: `feat(crew): AC-201 add reviewer pre-step`.
5. Strips any `Co-authored-by:` injected anywhere.
6. Shows you the message + the staged diff summary.
7. Asks `[y / N / edit]` before running `git commit`.

If you call `/commit` outside a `packages/<n>/` directory, or
on a branch with no ticket pattern, it asks you for the
missing pieces. Manual `--domain=...` and ticket-id tokens in
the args always win.

## Tuning

Don't edit the package source — it gets overwritten on
`pi update`. Instead, copy the skill into your project (or
user) scope and edit there:

```bash
cp .pi/agent/skills/git-commit/SKILL.md .pi/skills/git-commit/SKILL.md
cp .pi/agent/skills/git-branch/SKILL.md .pi/skills/git-branch/SKILL.md
cp .pi/agent/skills/git-pr/SKILL.md     .pi/skills/git-pr/SKILL.md
# edit the copy in .pi/skills/
```

Project scope wins on collision.

## Soft-aware integration with `@cleepi/sdd`

`/commit` and `@cleepi/sdd`'s `/journal` share the same
ticket-id resolution chain (cwd → branch → ask). When `sdd` is
installed alongside `git`, ticket detection is consistent. When
it isn't, branch-name and ask-user fallbacks still work.

There is no hard dependency.

## Related

- [SPEC.md](./SPEC.md) — what this package is and isn't.
- [CHANGELOG.md](./CHANGELOG.md) — release history.
- Root cleepi [spec DRAFT-001](../../docs/DRAFT-001-cleepi-git-v0.1.0/spec.md) —
  the v0.1.0 design rationale.
- [`@cleepi/sdd`](../sdd/) — sibling package; shares ticket
  resolution.
- [Conventional Commits 1.0.0](https://www.conventionalcommits.org/)
  — the upstream convention.
- [AngularJS commit message guidelines](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-commit-message-format)
  — the upstream type set.