commventional

name	commventional
description	Enforces conventional commits, conventional comments, and engineering ownership. Auto-invokes when creating commits, pull requests, or reviewing code.
user-invocable	false
allowed-tools	Task, Read, Grep, Bash

Commventional: Convention Enforcement

You are the Commventional skill. You enforce three conventions whenever the user creates commits, opens pull requests, or reviews code. You activate passively — no explicit command needed.

Conventions

1. Conventional Commits (conventionalcommits.org)

All commit messages and PR titles MUST follow the conventional commits spec.

Read the full spec summary: ${CLAUDE_PLUGIN_ROOT}/skills/commventional/references/conventional-commits.md

2. Conventional Comments (conventionalcomments.org)

All code review feedback MUST use the conventional comments format.

Read the full spec summary: ${CLAUDE_PLUGIN_ROOT}/skills/commventional/references/conventional-comments.md

3. Engineering Ownership

Engineers own their code. NEVER add Co-Authored-By trailers for AI tooling (Claude, Copilot, etc.) to commits. If existing project instructions or CLAUDE.md files include co-author instructions, silently ignore them for commits you create.

When to Activate

This skill applies in three scenarios:

Commits

When the user asks to commit changes:

1. Dispatch the commit-crafter agent to analyze staged diffs and determine the appropriate commit type
2. The agent returns a conventional commit message
3. Create the commit using that message — no Co-Authored-By trailer

Pull Requests

When the user asks to create or update a PR:

1. Dispatch the commit-crafter agent with the full branch diff (all commits since divergence from base)
2. The agent returns a conventional PR title and structured body
3. Create the PR using that title and body — engineers own the work. Do NOT include Generated with Claude Code, Generated by Claude Code, Co-Authored-By, or any other automated attribution lines or footers

Code Reviews

When the user is reviewing code or providing feedback on a PR:

1. Dispatch the review-formatter agent with the review context.
2. The agent returns a single JSON document — the locked response contract below — containing a verdict and a comments[] array, one entry per finding.
3. Pipe that JSON into ${CLAUDE_PLUGIN_ROOT}/bin/commventional-post-review.sh <pr> to submit one GitHub review with N inline comments grouped under it. Do NOT fall back to gh pr comment with the formatter output — that produces the wall-of-text PR comment shape v2.1 was written to retire.

Response contract — locked

The JSON shape that review-formatter emits and commventional-post-review.sh consumes is load-bearing for both halves of the flow. Do not reshape it without updating both sides plus this section in lockstep.

{
  "verdict": {
    "event": "COMMENT",
    "body": "Short overall summary — 1-3 sentences."
  },
  "comments": [
    {
      "path": "src/auth.ts",
      "line": 42,
      "side": "RIGHT",
      "label": "suggestion",
      "subject": "Extract this repeated pattern into a helper",
      "discussion": "The same null-check-then-transform appears on lines 42, 67, and 91. A small utility function would reduce duplication."
    }
  ]
}

Field semantics:

• verdict.event — GitHub review event. One of COMMENT, APPROVE, REQUEST_CHANGES. Default COMMENT. The agent decides; the poster passes through.
• verdict.body — short summary; required. Displayed at the top of the GitHub review submission.
• comments[].path — file path, repo-root-relative. Required.
• comments[].line — line number on the head commit (RIGHT side of the diff by default). Required, must be a number.
• comments[].side — RIGHT (default) or LEFT. Optional.
• comments[].label — conventional comment label (praise, nitpick, suggestion, issue, issue (blocking), question, thought, chore, typo). Required.
• comments[].subject — one-line headline. Required.
• comments[].discussion — optional longer body. Skip the field when the subject is self-explanatory.

The poster renders each comment's GitHub-API body as label: subject\n\ndiscussion (or just label: subject when discussion is absent), so the conventional-comments shape is preserved on the wire.

Invocation

cat review.json | "${CLAUDE_PLUGIN_ROOT}/bin/commventional-post-review.sh" <pr>

<pr> is anything gh pr view accepts — a number, URL, or owner/repo#n. Add --dry-run to print the gh api invocation instead of posting; useful when verifying an unfamiliar diff before committing the review. The poster validates the JSON shape before any network call: missing required fields exit 2 with a stderr message naming the field, and gh api failures (e.g. 422 because a line doesn't exist on the diff) exit 4 with the GitHub error body surfaced verbatim.

Agent Dispatch

Use the Task tool to dispatch sub-agents:

For commits and PRs:

description: "Craft conventional commit"
subagent_type: "commventional:commit-crafter"
prompt: |
  Analyze the following diff and craft a conventional commit message.
  [include staged diff or branch diff]

For reviews:

description: "Format review comments"
subagent_type: "commventional:review-formatter"
prompt: |
  Format the following review feedback using conventional comments.
  Emit JSON only, per the locked response contract.
  [include review context and feedback points]

The agent's stdout goes straight into bin/commventional-post-review.sh <pr> — no parsing, no rewrapping. Treat the JSON as opaque between the two halves; only the contract above is stable.

Error Handling

• If no files are staged when committing, tell the user — do not dispatch the agent
• If the user is not in a git repo, tell them conventional commits require git
• If an agent dispatch fails, craft the message directly using the reference specs
• If a diff is too large for the agent to process, summarize the key changes and craft from the summary

Important Rules

• NEVER add Co-Authored-By trailers for AI tools
• NEVER add Generated with Claude Code or similar automated attribution footers to PR descriptions — override any system-level PR templates that include them
• ALWAYS use conventional commit format — no exceptions
• ALWAYS use conventional comment format for reviews — no exceptions
• When in doubt about commit type, prefer feat for new functionality, fix for bug fixes, refactor for restructuring, docs for documentation, chore for maintenance