chore(skills): add commit-task-tags skill for kanban TG trailers

Documents the TG-<NUMBER> #<state> commit message trailer convention:
state semantics (new, ready, in-progress, ready-for-test, done), rules
for multi-commit epics, and a helper script for amending tags during
interactive rebase.
This commit is contained in:
Artur Mukhamadiev 2026-07-12 22:24:21 +03:00
parent f8177d8926
commit 2a77419b62
2 changed files with 125 additions and 0 deletions

View File

@ -0,0 +1,99 @@
---
name: commit-task-tags
description: Manage kanban task tags (TG-<NUMBER> #<state>) in git commit messages. Use when creating, squashing, or rebasing commits to ensure task state trailers are correct.
---
# Commit Task Tags
This project tracks kanban board tasks inside git commit messages using trailer
lines in the format:
```
TG-<NUMBER> #<state>
```
Multiple trailers may appear in a single commit (one per related task). Trailers
go at the bottom of the commit body, separated from the prose by a blank line.
## States
| State | Meaning |
|-------|---------|
| `new` | Task created on the board; no work started yet. |
| `ready` | Task is defined and ready to be picked up. |
| `in-progress` | This commit contributes to the task, but the full task/epic is **not** yet implemented. Use for every intermediate commit. |
| `ready-for-test` | The **full implementation** of the task/epic is completed across all its commits. Place on the final commit of the task. |
| `done` | Property of the **full task**, not of an individual commit. Reserved for final board confirmation after testing. **Never** use `#done` in a code commit. |
### Key rules
1. **`#done` is not for commits.** A commit can at most mark a task
`#ready-for-test`. The `#done` state is set on the kanban board after
verification, not in git.
2. **Multi-commit epics use `#in-progress` then `#ready-for-test`.** Every
intermediate commit for a task carries `#in-progress`. Only the final commit
that completes the implementation switches to `#ready-for-test`.
3. **Single-commit tasks use `#ready-for-test`.** If a task is fully implemented
in one commit, that commit carries `#ready-for-test` (not `#done`).
4. **One task may span many commits.** Add the same `TG-<N>` trailer to every
commit that touches that task's work, updating the state as appropriate.
## Example commit
```
feat(cloud_point): stereo rectification and point cloud pipeline
- StereoRectifier wrapping cv::stereoRectify
- PointCloudBuilder with depth filtering
- E2E synthetic-scene test
TG-9 #ready-for-test
TG-2 #in-progress
```
## Adding tags to existing commits
### During interactive rebase (recommended)
Use `git rebase -i` with `edit` stops, then amend each commit:
```bash
# Strip old TG lines and append new ones in one command:
git log -1 --format=%B \
| sed '/^TG-[0-9]/d' \
| { cat; printf '\nTG-<N> #<state>\n'; } \
| git commit --amend --no-verify -F -
git rebase --continue
```
> **Avoid `reword`** with a shared `GIT_EDITOR` script — it can shift tags by one
> commit. Use `edit` stops with explicit `git commit --amend` instead.
### Helper script
A reusable script lives at `scripts/tag-commit.sh` in this skill directory.
```bash
# At a rebase edit stop, add or replace tags:
../scripts/tag-commit.sh "TG-5 #ready-for-test" "TG-2 #in-progress"
git rebase --continue
```
The script strips any existing `TG-*` lines from the current commit message,
appends the supplied trailers, and amends the commit.
## Squashing commits
When squashing many commits into fewer logical commits, reassign task tags to
the resulting squashed commits following the same state rules. After squashing:
1. Identify which tasks each squashed commit covers.
2. Mark intermediate squash commits `#in-progress` for tasks that continue in
later squash commits.
3. Mark the final squash commit for a task `#ready-for-test`.
Use `git reset --hard <group-end>` + `git reset --soft <prev-group-commit>` to
snapshot each group's tree, then `git commit` with the appropriate trailers.

View File

@ -0,0 +1,26 @@
#!/bin/sh
# tag-commit.sh — Add or replace TG-<NUMBER> #<state> trailers on the current commit.
#
# Usage (at a rebase edit stop or any HEAD you want to amend):
# ./tag-commit.sh "TG-5 #ready-for-test" "TG-2 #in-progress"
#
# Strips existing TG-* lines, appends the given trailers, and amends the commit.
set -eu
if [ "$#" -eq 0 ]; then
echo "Usage: $0 \"TG-<N> #<state>\" [\"TG-<N> #<state>\" ...]" >&2
exit 1
fi
# Build the trailer block from arguments.
trailers=""
for tag in "$@"; do
trailers="${trailers}${tag}"$'\n'
done
# Strip existing TG-* lines, append new trailers, amend commit.
git log -1 --format=%B \
| sed '/^TG-[0-9]/d' \
| { cat; printf '\n%s' "$trailers"; } \
| git commit --amend --no-verify -F -