x-commit-planning
Batch-commits planning artifacts under plans/** (or whitelisted template paths) without triggering the code pre-commit chain (format/lint/compile). Sibling of x-commit-changes for docs/markdown/json generated by planning skills.
- License 许可
- MIT
- 最近更新
- 2026-10-27
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- x-commit-planning
- description
- Batch-commits planning artifacts under plans/** (or whitelisted template paths) without triggering the code pre-commit chain (format/lint/compile). Sibling of x-commit-changes for docs/markdown/json generated by planning skills.
- allowed-tools
- Bash, Read
- argument-hint
- --epic-id <NNNN> --paths <p1,p2,...> --subject <msg> [--scope chore|docs] [--body <text>] [--dry-run]
- context-budget
- light
- user-invocable
- true
- requires-capabilities
- []
02 资源文件 1
- 参考文档README.md3.8 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: Planning Artifact Commit (batch, no pre-commit chain)
Batch-commits planning artifacts produced by planning skills (x-epic-create, x-epic-decompose, x-epic-map, x-orchestrate-epic, x-story-create, x-plan-story, x-plan-task) under ai/epics/epic-XXXX/**. Unlike x-commit-changes, this skill does NOT invoke the code pre-commit chain (format / lint / compile) because planning outputs are pure docs/markdown/json and running the chain over them is both overkill and breaks (e.g., markdown linting may fail the whole batch).
RULE-007 of EPIC-0049 requires every planning skill to delegate to this skill at end-of-run so the working tree stays clean and every plan mutation has a Git audit trail.
Triggers
/x-commit-planning --epic-id XXXX --paths ai/epics/epic-XXXX/epic-XXXX.md --subject "add epic scaffold"-- single-file commit/x-commit-planning --epic-id XXXX --paths ai/epics/epic-XXXX/epic-XXXX.md,ai/epics/epic-XXXX/IMPLEMENTATION-MAP.md --subject "add planning artifacts (22 stories)"-- batch commit/x-commit-planning --epic-id XXXX --paths ai/epics/epic-XXXX/epic-XXXX.md --subject "preview" --dry-run-- dry-run preview/x-commit-planning --epic-id XXXX --paths ai/epics/epic-XXXX/epic-XXXX.md --subject "chore bump" --scope chore-- chore scope
Parameters
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
--epic-id |
String (4 digits) | Yes | — | Epic number used in the commit scope (docs(epic-0049): ...). Regex ^\d{4}$. |
--paths |
Comma-separated list | Yes | — | Paths to stage + commit. Each path MUST exist AND be inside the whitelist (plans/**, .claude/templates/**, ai/epics/**, ai/products/**, ai/memory/**, or ai/releases/**). NEVER git add .. |
--subject |
String (≤ 72 chars) | Yes | — | Conventional Commits subject (imperative mood, no trailing period). |
--scope |
Enum | No | docs |
Conventional Commits type: chore or docs. |
--body |
String (≤ 4096 chars) | No | — | Optional multi-line commit body. |
--dry-run |
Boolean | No | false |
When true, print the message that would be created and exit 0 without staging or committing. |
Output Contract
- Commit message format:
<scope>(epic-<NNNN>): <subject>\n\n<body>(body omitted when absent). - Git state (success): exactly one new commit on the current branch containing the declared
--pathsonly. No other staged files are committed. - Git state (no-op): when
git diff --cached --quietreturns 0 aftergit add <paths...>, exit 0 without committing. ReportnoOp=true,commitSha=null. - Git state (dry-run): no
git add, nogit commit. ReportdryRun=true,commitSha=null. - Report to stdout (JSON line):
{"commitSha": "<40-char sha | null>", "filesCommitted": [...], "noOp": <bool>, "dryRun": <bool>}. - Exit codes: see
## Error Envelope.
Whitelist
Allowed path prefixes (enforced before any git add):
plans/(any depth — epic / story / task plans, reports, execution-state, implementation map).claude/templates/(when a planning skill ships an updated template)ai/epics/(v4 layout — epic/story/task plans and reports under ai/epics/epic-XXXX-slug/)ai/products/(product artifact directory — capabilities, features, stories per product)ai/memory/(AI memory layer artifacts — epic summaries, index)ai/releases/(release state files — release-state-X.Y.Z.json)
Any --paths entry that resolves outside this whitelist FAILS with PATH_NOT_WHITELISTED.
Workflow
-
Parse args. Validate
--epic-idmatches^\d{4}$; elseINVALID_EPIC_ID(exit 3). -
Split
--pathson comma. For each path:- Reject if it does not exist on disk →
PATH_NOT_EXISTS(exit 2). - Reject if it does not start with any whitelisted prefix (
plans/,.claude/templates/,ai/epics/,ai/products/,ai/memory/,ai/releases/) →PATH_NOT_WHITELISTED(exit 1).
- Reject if it does not exist on disk →
-
Validate
--subjectlength ≤ 72 chars; reject non-imperative with a WARN but proceed (soft validation). -
If
--dry-run: print{"dryRun": true, "commitSha": null, "filesCommitted": [<paths>], "noOp": false}and exit 0. -
Execute
git add <paths...>(explicit list; NEVERgit add .). -
Check
git diff --cached --quiet -- <paths...>— if exit code 0, no diff → print{"noOp": true, "commitSha": null, "filesCommitted": [], "dryRun": false}and exit 0. Also un-stage anything this invocation just staged (git reset HEAD -- <paths...>) to keep the index clean. -
Build message:
<scope>(epic-<NNNN>): <subject> <body> -
Execute
git commit -m "<message>"without the pre-commit code chain. Do NOT invokex-format-code,x-lint-code, or the compile step. Do NOT use--no-verify(it bypasses legitimate commit-msg hooks too); the chain is skipped simply by not invokingx-commit-changes. -
Capture
git rev-parse HEAD→commitSha. -
Print
{"commitSha": "<sha>", "filesCommitted": [<paths>], "noOp": false, "dryRun": false}and exit 0.
Error Envelope
| Exit Code | Error Code | Condition | Message |
|---|---|---|---|
| 1 | PATH_NOT_WHITELISTED |
Path outside all whitelisted prefixes | "Path '<p>' not in whitelist (plans/**, .claude/templates/**, ai/epics/**, ai/products/**, ai/memory/**, ai/releases/**)" |
| 2 | PATH_NOT_EXISTS |
Path does not exist on disk | "Path '<p>' does not exist" |
| 3 | INVALID_EPIC_ID |
--epic-id does not match ^\d{4}$ |
"Epic ID must be 4 digits, got '<value>'" |
| 4 | COMMIT_FAILED |
git commit returned non-zero |
"git commit failed: <stderr>" |
| 5 | SUBJECT_TOO_LONG |
--subject > 72 chars |
"Subject exceeds 72 characters (got <n>)" |
No-op (diff vazio) is NOT an error — exit 0 with noOp=true.
Integration Notes
| Skill | Relationship | Context |
|---|---|---|
x-epic-create |
invokes | At end-of-run commits ai/epics/epic-XXXX/epic-XXXX.md + IMPLEMENTATION-MAP.md. |
x-epic-decompose |
invokes | Commits full batch of story files + implementation map. |
x-epic-map |
invokes | Commits IMPLEMENTATION-MAP.md updates. |
x-orchestrate-epic |
invokes | Commits per-story planning artifacts in batch after each wave. |
x-story-create |
invokes | Commits the generated story file. |
x-plan-story |
invokes | Commits 6 planning artifacts (arch / test / task-breakdown / security / compliance / plan). |
x-plan-task |
invokes | Commits per-task plan files. |
x-commit-changes |
sibling | Code pre-commit chain — use for source code. Never delegates here. |
Rationale
x-commit-changes enforces the format → lint → compile chain for every commit. Running this chain over markdown/json generated by a planning skill is:
- Overkill — docs need no Java formatter / linter / compiler.
- Brittle — a lint rule change can fail planning commits and block orchestration.
- Slow — full compile can take tens of seconds per planning run.
x-commit-planning isolates the no-chain path explicitly. The whitelist prevents accidentally using it for source files: any src/main/** or src/test/** path is rejected at step 2.
Telemetry (Optional)
If invoked from a numbered phase of another skill, wrap the invocation with standard phase markers in the caller. This skill itself emits no internal phase markers — it is a single-step wrapper around git add + git commit.
Reference: .claude/rules/13-skill-invocation-protocol.md.
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.