Git Workflow Skill
Create properly scoped git commits for task operations.
Context Loading
Load context on-demand when needed:
@.claude/context/standards/git-staging-scope.md- Canonical per-operation commit-scope contract (research/plan/implement staging rules, forbidden operations, fail-safe direction)@.claude/context/standards/git-safety.md- Git safety rules and best practices@.claude/context/index.json- Full context discovery index
Relationship to orchestrator-postflight.sh
This skill is the documentation front for the commit-scope contract — it is not literally
invoked as a runtime script from bash. .claude/scripts/orchestrator-postflight.sh is now an
orphaned script with no live callers (confirmed by a repo-wide grep for actual invocation sites)
— it was the shared postflight-commit execution site for the three base lifecycle skills before
they were deleted. The actual execution of task-scoped commits happens today in:
.claude/skills/skill-orchestrate/SKILL.md's own dispatch-loop commit site (Move 2's per-task scoped commit, covering both single-task and multi-task dispatch — there is one engine now) — the shared execution site forresearch/plan/implementpostflight commits, branching on outcome for targeted staging (never staging the entire working tree)..claude/agents/general-implementation-agent.md's Green Sub-Step Commit (per-objective) and Phase Checkpoint Protocol (per-phase commit) — the innermost, per-objective/per-phase commit sites forimplementdispatch.
Both sites implement the same contract documented in git-staging-scope.md. This SKILL.md
describes that contract and where it is enforced; it does not add a third execution path.
Trigger Conditions
This skill activates when:
- Task status changes (research, plan, implement complete)
- Artifacts are created
- Task lifecycle operations occur
Commit Message Formats
Task Operations
| Operation | Format | CI Triggered |
|---|---|---|
| Create task | task {N}: create {title} |
No |
| Complete research | task {N}: complete research |
No |
| Create plan | task {N}: create implementation plan |
No |
| Complete phase | task {N} phase {P}: {phase_name} |
No |
| Complete task | task {N}: complete implementation |
No |
| Complete task (with CI) | task {N}: complete implementation [ci] |
Yes |
| Revise plan | task {N}: revise plan (v{V}) |
No |
System Operations
| Operation | Format |
|---|---|
| Archive tasks | todo: archive {N} completed tasks |
| Error fixes | errors: create fix plan for {N} errors |
| Code review | review: {scope} code review |
| State sync | sync: reconcile TODO.md and state.json |
Execution Flow
1. Receive commit request:
- operation_type
- task_number (if applicable)
- scope (files to include)
- message_template
2. Determine appropriate files:
- {scope}
3. Stage and commit together via `git-commit-scoped.sh`:
- Format message
- Execute `bash .claude/scripts/git-commit-scoped.sh --message "..." --session "${session_id}" [--task task_number] -- {scope}`
(pass `--task` when a task number governs the request, per step 1's `task_number (if applicable)`; omit it when none does)
4. Verify success:
- Check exit code
- Log result
5. Return result
Commit Scope Rules
See @.claude/context/standards/git-staging-scope.md for the authoritative, canonical
per-operation commit-scope contract. Summary:
Task-Specific Commits
Include only task-related files:
specs/TODO.md
specs/state.json
specs/{NNN}_{SLUG}/**
Implementation Commits
Include source files modified, via the agent's self-reported modified_files field (see
@.claude/context/formats/return-metadata-file.md) — never a blanket stage of the entire
working tree:
Logos/**/*.lean (for Lean tasks)
src/**/* (for general tasks)
Phase Commits
Scope to phase changes only, using the paths accumulated in that phase's progress-file
files_touched array (see @.claude/context/formats/progress-file.md):
Files modified in that phase
Updated plan with phase status
Fail-Safe Direction
Under-stage with a loud, non-silent warning rather than over-stage. If the modified-files self-report is absent or empty, stage only the fixed task-directory paths and print a warning — never fall back to staging the entire working tree.
Safety Checks
Before Commit
1. git status - verify staged files
2. Check no sensitive files staged (.env, credentials)
3. Verify commit message format
Never Run
git push --forcegit reset --hard(without explicit request)git rebase -igit add -A/git add .(stages the entire working tree; use targeted staging per@.claude/context/standards/git-staging-scope.mdinstead)- A directory or glob
git addpathspec (e.g.git add -- some/dir/,git add src/*.lean) — same over-staging problem asgit add -A/.in a narrower disguise; an explicit multi-file list (git add -- a.lean b.lean) remains permitted git commit -am(implicitly stages all tracked-file modifications — same over-staging problem)
Message Template
{scope}: {action} {description}
CI Triggering
Overview
CI is skipped by default on push events. To trigger CI, add [ci] marker to the commit message.
trigger_ci Parameter
When creating commits, the trigger_ci parameter controls whether CI runs:
| Value | Behavior | Use Case |
|---|---|---|
false (default) |
No CI marker added | Routine commits, research, planning |
true |
Append [ci] to message |
Lean changes, implementation completion |
CI Decision Criteria
Trigger CI (trigger_ci: true) when:
- Lean files modified (.lean) - Ensures build passes
- Implementation completed - Final verification before merge
- CI configuration changed (.github/workflows/) - Validate workflow changes
- Mathlib dependencies updated (lakefile.lean, lake-manifest.json) - Ensure compatibility
- Critical bug fixes - Verify fix works
Skip CI (default) when:
- Documentation changes only (.md files)
- Research/planning artifacts
- Configuration changes (non-CI)
- Routine task management operations
Commit Message with CI Marker
task {N}: complete implementation [ci]
When CI Always Runs
CI runs regardless of marker on:
- Pull request events (all PRs run CI)
- Manual workflow_dispatch trigger
- Commits with
[ci]marker
Execution Commands
Both forms below go through .claude/scripts/git-commit-scoped.sh, the single sanctioned
implementation of path-scoped, mutex-serialized committing — never a bare git add followed by a
a bare git commit.
Standard Commit
This form is for operations with no governing task number (sync:, review:, and similar), so
neither --honest-index-rows nor --task applies — there is no single task number for either
flag to key on. Copy the Task Commit form below instead whenever a task number does govern the
commit.
bash .claude/scripts/git-commit-scoped.sh \
--message "{message}" \
--session "${session_id}" \
-- {files}
Task Commit
bash .claude/scripts/git-commit-scoped.sh \
--message "task {N}: {action}" \
--session "${session_id}" \
--honest-index-rows {N} \
--task {N} \
-- specs/TODO.md specs/state.json {artifact paths}
Return Format
{
"status": "completed|failed",
"summary": "Created commit: {short_message}",
"commit_hash": "abc123",
"files_committed": [
"path/to/file1",
"path/to/file2"
],
"message": "Full commit message",
"ci_triggered": true|false
}
Error Handling
Nothing to Commit
{
"status": "committed",
"summary": "No changes to commit",
"commit_hash": null
}
Pre-Commit Hook Failure
{
"status": "failed",
"error": "Pre-commit hook failed",
"recovery": "Fix issues and retry (do not use --no-verify)"
}
Git Error
{
"status": "failed",
"error": "Git command failed: {error}",
"recovery": "Check git status and resolve manually"
}
Non-Blocking Behavior
Git failures should NOT block task operations:
- Log the failure
- Continue with task
- Report to user that commit failed
- Task state is preserved regardless