x-commit-changes
Creates Conventional Commits with Task ID in scope and pre-commit chain (format -> lint -> compile). Central commit point in the task-centric workflow with TDD tag support.
- License 许可
- MIT
- 最近更新
- 2026-10-27
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- x-commit-changes
- model
- haiku
- description
- Creates Conventional Commits with Task ID in scope and pre-commit chain (format -> lint -> compile). Central commit point in the task-centric workflow with TDD tag support.
- allowed-tools
- Bash, Read, Grep, Glob, Write, Edit, Skill
- argument-hint
- --task TASK-XXXX-YYYY-NNN --type <type> --subject <subject> [--tdd RED|GREEN|REFACTOR] [--body <body>] [--skip-chain] [--amend]
- context-budget
- light
- user-invocable
- true
- requires-capabilities
- []
02 资源文件 2
- 参考文档README.md2.8 KB
- 参考文档references/full-protocol.md7.7 KB
03 SKILL.md 正文
Global Output Policy
- Language: English ONLY.
- Tone: Technical, Direct, and Concise.
- Efficiency: Remove all conversational fillers and greetings to save tokens.
Skill: Conventional Commit with Task ID (slim — ADR-0012)
Creates standardized commits for {{PROJECT_NAME}} with the Task ID in the scope, enforces the pre-commit chain (RULE-007: x-format-code -> x-lint-code -> compile -> commit), and annotates commits with TDD tags (RULE-008). Central commit point in the task-centric workflow.
Triggers
/x-commit-changes --task TASK-XXXX-YYYY-NNN --type feat --subject "add detection logic"-- normal commit/x-commit-changes --task TASK-XXXX-YYYY-NNN --type test --subject "add unit tests" --tdd RED-- TDD-tagged commit/x-commit-changes --task TASK-XXXX-YYYY-NNN --type chore --subject "update config" --skip-chain-- skip pre-commit chain (emergency only)
Parameters
| Parameter | Required | Description |
|---|---|---|
--task |
Yes | Task ID TASK-XXXX-YYYY-NNN (4-digit epic, 4-digit story, 3-digit task) |
--type |
Yes | Conventional Commits type: feat, fix, test, refactor, docs, chore, perf |
--subject |
Yes | Commit subject, imperative mood, no period, max 72 characters |
--tdd |
No | TDD tag: RED, GREEN, REFACTOR, or generic TDD |
--body |
No | Multi-line commit body (additional context) |
--skip-chain |
No | Skip pre-commit chain (emergency use only, emits WARNING) |
--amend |
No | Amend the last commit instead of creating a new one |
Output Contract
- Commit message format:
<type>(<TASK-XXXX-YYYY-NNN>): <subject> [TDD:TAG](tag suffix omitted when--tddabsent) followed by optional body/footer. - Orchestrator signature trailer: every commit produced by
x-commit-changesMUST carryCo-Authored-By: x-commit-changes@<HEAD-sha-40-hex>(injected viagit commit --trailer). This trailer is the proof-of-orchestration required by the.githooks/commit-msgsurface-D guard (EPIC-0059, story-0059-0005). The<sha>is$(git rev-parse HEAD)captured immediately before the commit executes, so it references the parent commit (not the commit being created — that SHA is unavailable at commit-message composition time). - Git state: one new commit on the current branch (or last commit amended when
--amend); staged files are re-staged after format/lint auto-fix. - Report to stdout: task id, type, subject, TDD tag, chain status (passed/skipped), short SHA, full message first line.
- Exit codes: see
## Error Envelopebelow.
Pre-Commit Chain (RULE-007)
x-format-code -> x-lint-code -> compile ({{COMPILE_COMMAND}}) -> commit
Each step invoked via the Skill tool (Rule 13 — INLINE-SKILL pattern). Files modified by format/lint are automatically re-staged. Chain-wide error rows (exit codes, soft-vs-hard classification) live in _shared/error-handling-pre-commit.md.
Error Envelope
Chain-wide error matrix. The canonical
format -> lint -> compile -> commiterror rows (shared across the pre-commit cluster) live in_shared/error-handling-pre-commit.md. The rows below coverx-commit-changes-specific scenarios only.
| Scenario | Behavior |
|---|---|
Invalid task ID format (does not match TASK-\d{4}-\d{4}-\d{3}) |
ABORT with format hint |
| Subject exceeds 72 characters | ABORT with character count |
| Invalid commit type | ABORT with valid types list (feat, fix, test, refactor, docs, chore, perf) |
| Invalid TDD tag | ABORT with valid tags list (RED, GREEN, REFACTOR, TDD) |
| No staged files | ABORT with "No staged files for commit" |
| x-format-code fails | ABORT with "Pre-commit chain failed at step 'x-format-code'" |
| x-lint-code finds ERRORs | ABORT with "Pre-commit chain failed at step 'x-lint-code'" |
| Compile fails | ABORT with "Pre-commit chain failed at step 'compile'" |
| git commit fails | ABORT with git error message |
| Non-imperative subject (e.g., "adds", "fixed") | WARN but proceed (soft validation) |
--skip-chain used |
Proceed with WARNING "Pre-commit chain skipped — emergency use only" |
Full Protocol
Minimum viable contract above. Detailed validation rules, the full workflow with shell snippets, message-building examples, TDD tag semantics, and the amend flow live in references/full-protocol.md per ADR-0012 (skill body slim-by-default). Reading the full protocol is only required for atypical scenarios (custom amend flow, diagnosing a chain failure); happy-path invocations need only this SKILL.md.
Integration Notes
| Skill | Relationship | Context |
|---|---|---|
x-format-code |
invoked by | First step of pre-commit chain |
x-lint-code |
invoked by | Second step of pre-commit chain |
x-push-branch |
followed by | Push after commit is created |
x-implement-story |
orchestrated by | Lifecycle invokes x-commit-changes for each task |
x-execute-tests |
precedes | Tests should pass before committing |
Template Variables
| Variable | Description | Example |
|---|---|---|
{{COMPILE_COMMAND}} |
Project compile command | mvn compile -q |
{{LANGUAGE}} |
Project language | java |
{{BUILD_TOOL}} |
Project build tool | maven |
{{PROJECT_NAME}} |
Project name | my-java-cli |
04 同仓库更多 Skills
x-parallel-eval
Detects and classifies file-collision risks between work units (tasks, stories, or epic phases) before parallel execution. Reads ## File Footprint blocks produced by x-task-plan / x-story-plan, applies the parallelism-heuristics knowledge pack (hard / regen / soft categories + hotspot overrides), and emits a collision matrix + serialization recommendation in Markdown (default) or JSON.
parallelism-heuristics
Canonical catalog of file-collision heuristics for parallel task, story, and epic execution. Defines the File Footprint block format, the three Conflict Categories (hard / regen / soft), a hotspot list of high-contention paths, and the degrade-with-warning policy. Consumed by x-task-plan, x-story-plan, x-epic-map, x-parallel-eval, and x-dev-*-implement.
x-watch-pr-ci
Polls a PR's CI checks and Copilot review status, blocking until checks complete or timeout. Returns one of 8 stable exit codes (SUCCESS=0, CI_PENDING_PROCEED=10, CI_FAILED=20, TIMEOUT=30, PR_ALREADY_MERGED=40, NO_CI_CONFIGURED=50, PR_CLOSED=60, PR_NOT_FOUND=70). Writes a versioned state-file for session resume.
x-validate-docs
Documentation freshness gate: validates 6 dimensions (readme, api-specs, grpc-proto, adr, skill-docs, system-architecture) against code changes in a PR. Stack-aware — only validates targets declared/auto-detected from ProjectConfig.documentation.targets. Returns exit non-zero on staleness; produces structured report.
x-update-system-architecture
Incrementally updates docs/architecture/system.md after an epic completes. Appends new entries to the Decision Log (§11) using x-internal-write-report --append (dedup by ## ID: marker) and surgically inserts component/integration changes into sections 1-10 via Edit. Idempotent: re-running with the same epic produces a byte-identical system.md.
x-update-architecture
Incrementally updates the service architecture document with changes from architecture plans. Adds new components, integrations, flows, and ADR references without rewriting existing content. Use after implementation to keep architecture documentation current.