| name | openspec-git-discipline |
| description | Use when OpenSpec propose, continue, apply, verify, archive, branch, merge, or worktree timing affects git history. |
| license | MIT |
| compatibility | Codex lazy-loaded skill for git-backed OpenSpec projects. |
Project context preflight before workflow actions: before this skill takes a workflow action, follow the project-constitution skill. Read root CONSTITUTION.md when present, enforce relevant project rules, stop on material conflicts, and follow the strict missing-constitution bootstrap/diagnostic policy. For architecture-sensitive work, also read ARCHITECTURE.md, adr/README.md, and relevant in-force adr/*.md. Read .secrets.local.env only when the current workflow actually needs a listed external system, and never reveal secret values.
OpenSpec Git Discipline
Use this skill whenever OpenSpec lifecycle state changes or git timing affects the workflow.
Project policy: checkpoint discipline is mandatory. Every completed artifact or coherent apply group must be checkpointed before the next lifecycle phase depends on it. Safe scaffold/artifact/apply-group checkpoint commits run automatically by default when session git discipline is auto; manual mode can still require approval.
Core rule: every OpenSpec state change must cross main before the next
lifecycle phase depends on it.
- Proposal artifacts may be drafted on a branch, but must be committed and
merged to
main before apply starts.
- Apply may run on
main, a branch, or a worktree only if that exact proposal
state is already available on main.
- Archive should run from
main after implementation is merged back.
- Safe lifecycle checkpoint commits may be created automatically in
auto mode after the changed paths and commit message are shown.
- Never create branches, merges, pushes, pull requests, archives, destructive git operations, or hard-gate bypasses unless the user explicitly asks.
Gates
Hard gates that always require explicit approval: branch creation, merge, push, pull request creation, archive, destructive git operations, dirty unrelated work, and any one-time override of a required gate.
- Before propose: prefer
main; otherwise warn and ask whether to continue.
- During continue: checkpoint completed artifact changes according to session git mode before the next artifact consumes them.
- Before apply: run
git status --short and verify planning artifacts are not
only local uncommitted state.
- Before archive: run
git branch --show-current and git status --short;
stop if not on main or implementation has not been merged.
- After archive: ask the user whether to commit archive/spec sync changes because archive remains an explicit hard gate.
Required Language
If proposal state has not reached main:
I should not apply this yet because the planning change has not reached
main. A proposal can be drafted on a branch, but apply must start only after
that proposal state is available on main.
If archive is not running from merged main:
I should not archive this yet because archive must run from main after
implementation is merged back. Verify makes a change eligible to merge; it
does not replace the merge.
Mandatory Checkpoint Boundaries
Checkpoint after each of these boundaries before a later lifecycle phase depends on the result:
openspec new change creates a change directory.- Each planning artifact is created or materially updated: proposal, specs, grill, design, design-review, adr, test-plan, tasks.
- Each coherent apply task group is completed and verified.
- Verify produces an archive-ready assessment.
- Archive moves the change and/or syncs specs.
At every checkpoint:
- run
git status --short;
- summarize changed files;
- in automatic mode, use
scripts/openspec-git-checkpoint when available for safe scoped checkpoint commits; in manual mode, ask before git add/git commit;
- always show affected paths, commit message, resulting commit hash, and re-check status;
Override Policy
Overrides are allowed only when the user explicitly names or clearly confirms the gate being bypassed. An override is one-time and does not disable future gates. Record the override in the response with:
- gate bypassed;
- files/state trusted despite the gate;
- risk accepted;
- next checkpoint where normal discipline resumes.
