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

Parse args. Validate --epic-id matches ^\d{4}$; else INVALID_EPIC_ID (exit 3).
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).
Validate --subject length ≤ 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; NEVER git 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 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.
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.

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)

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

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

Parse args. Validate --epic-id matches ^\d{4}$; else INVALID_EPIC_ID (exit 3).
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).
Validate --subject length ≤ 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; NEVER git 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 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.
Capture git rev-parse HEAD → commitSha.
Print {"commitSha": "<sha>", "filesCommitted": [<paths>], "noOp": false, "dryRun": false} and exit 0.

Error Envelope

No-op (diff vazio) is NOT an error — exit 0 with noOp=true.

Integration Notes

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)

Reference: .claude/rules/13-skill-invocation-protocol.md.

Adoption

edercnj/x-commit-planning

$ install --global

Security Scan Results

SKILL.md

Global Output Policy

Skill: Planning Artifact Commit (batch, no pre-commit chain)

Triggers

Parameters

Output Contract

Whitelist

Workflow

Error Envelope

Integration Notes

Rationale

Telemetry (Optional)

Related Skills

edercnj/x-generate-docs

edercnj/x-generate-ci

edercnj/x-generate-adr

edercnj/x-format-code

edercnj/x-commit-planning

$ install --global

Security Scan Results

SKILL.md

Global Output Policy

Skill: Planning Artifact Commit (batch, no pre-commit chain)

Triggers

Parameters

Output Contract

Whitelist

Workflow

Error Envelope

Integration Notes

Rationale

Telemetry (Optional)

Related Skills

edercnj/x-generate-docs

edercnj/x-generate-ci

edercnj/x-generate-adr

edercnj/x-format-code