AGENT SKILL

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

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 --paths only. No other staged files are committed.
  • Git state (no-op): when git diff --cached --quiet returns 0 after git add <paths...>, exit 0 without committing. Report noOp=true, commitSha=null.
  • Git state (dry-run): no git add, no git commit. Report dryRun=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

  1. Parse args. Validate --epic-id matches ^\d{4}$; else INVALID_EPIC_ID (exit 3).

  2. Split --paths on 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).
  3. Validate --subject length ≤ 72 chars; reject non-imperative with a WARN but proceed (soft validation).

  4. If --dry-run: print {"dryRun": true, "commitSha": null, "filesCommitted": [<paths>], "noOp": false} and exit 0.

  5. Execute git add <paths...> (explicit list; NEVER git add .).

  6. 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.

  7. Build message:

    <scope>(epic-<NNNN>): <subject>
    
    <body>
    
  8. Execute git commit -m "<message>" without the pre-commit code chain. Do NOT invoke x-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 invoking x-commit-changes.

  9. Capture git rev-parse HEAD → commitSha.

  10. 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:

  1. Overkill — docs need no Java formatter / linter / compiler.
  2. Brittle — a lint rule change can fail planning commits and block orchestration.
  3. 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

review-bench
review-bench/edercnj_ia-dev-environment

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.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

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.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

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.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

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.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

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.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

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.

★ 0