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:
parent
f8177d8926
commit
2a77419b62
99
.pi/skills/commit-task-tags/SKILL.md
Normal file
99
.pi/skills/commit-task-tags/SKILL.md
Normal 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.
|
||||
26
.pi/skills/commit-task-tags/scripts/tag-commit.sh
Executable file
26
.pi/skills/commit-task-tags/scripts/tag-commit.sh
Executable 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 -
|
||||
Loading…
x
Reference in New Issue
Block a user