Oma Scm

Software configuration management: SCM (oma-scm)

Scheduling

Goal

Manage Git and software configuration management safely: commits, branches, merges, worktrees, releases, baselines, audit posture, CODEOWNERS, and Conventional Commits.

Intent signature

• User asks to commit, stage, branch, merge, rebase, cherry-pick, tag, release, resolve conflicts, manage worktrees, inspect SCM posture, or apply Conventional Commits.
• User needs safe Git operations with explicit file staging, secret awareness, and CM governance.

This skill is the single place for configuration management (CM) on a software repo and for Conventional Commits / safe staging.

When to use

• Commits: “commit this”, /scm, message type/scope, splitting staged changes into multiple commits.
• CM / Git: branching (gitflow, GitHub Flow, GitLab Flow, trunk-based), protected branches, merge queue, merge conflicts, rebase, cherry-pick, worktrees, submodules/subtrees, tags and releases.
• Governance: issue/ADR links, breaking-change footers, changelog or release-tool alignment.
• Audit posture: signed commits, CI before merge, secret-sensitive paths.

When NOT to use

• Implementing product or application code -> use the relevant domain skill
• Debugging runtime failures without a Git or CM operation -> use oma-debug
• Security, performance, or accessibility review -> use oma-qa
• Planning feature requirements or decomposing work -> use oma-pm

Expected inputs

• Git task, desired branch/commit/release operation, and affected files
• Current worktree status, staged diff, branch tracking, config files, and governance constraints
• Optional issue/ADR/PR/release context

Expected outputs

• Safe commit, branch, merge/rebase guidance, conflict plan, status accounting, or CM audit findings
• Conventional Commit message and explicit staged paths when committing
• Risk notes for shared history, secrets, CODEOWNERS, CI, and release evidence

Dependencies

• Git CLI and repository metadata
• .agents/oma-config.yaml, Conventional Commit references, onboarding-risk and CODEOWNERS playbooks

Control-flow features

• Branches by quick commit path versus full CM/governance path
• Reads Git state and diffs; may write commits, branches, tags, or conflict resolutions
• Requires explicit approval for broad staging, shared-history rewrite, production-destructive operations, or secret-risk paths

Structural Flow

Entry

• Inspect Git status, branch, staged/unstaged changes, and user intent.
• Choose Quick Path for ordinary commits or Full CM Path for governance/risky history work.
• Read commit and CM config before enforcing project-specific rules.

Scenes

• PREPARE: Determine operation type, risk, and affected files.
• ACQUIRE: Read status, diff, logs, config, ownership, and release context.
• REASON: Split changes, choose message/scope, identify CM controls and risks.
• ACT: Stage explicit paths, commit, branch, resolve, or provide CM action plan.
• VERIFY: Check status, staged diff, CI expectations, signatures, secrets, and audit evidence.
• FINALIZE: Report operation result and remaining SCM tasks.

Transitions

• If user intent is commit-only, follow Quick Path and stop after safe commit.
• If branching/history/release/governance is involved, run Full CM Path.
• If shared history rewrite is requested, require maintainer approval.
• If changes span independent features, split commits unless user requests one commit.

Failure and recovery

• If worktree is dirty in unrelated files, avoid touching unrelated changes.
• If conflicts exist, resolve markers, test, and preserve target-branch context.
• If secrets are detected or suspected, stop before staging/committing.

Exit

• Success: requested SCM operation is complete or a safe, auditable plan is delivered.
• Partial success: blockers such as conflicts, missing approval, CI, or secret risk are explicit.

Logical Operations

Actions

| Action | SSL primitive | Evidence |

|--------|---------------|----------|

| Read Git state | READ | git status, diff, log, config |

| Select SCM path | SELECT | Quick Path vs Full CM Path |

| Compare change scopes | COMPARE | Split by type/scope/feature |

| Validate commit/governance rules | VALIDATE | Config and CM controls |

| Stage explicit files | CALL_TOOL | git add <specific-files> |

| Commit or manage refs | CALL_TOOL | Git commit/branch/merge/rebase/tag |

| Write audit notes | WRITE | Commit message or CM report |

| Report result | NOTIFY | Final SCM summary |

Tools and instruments

• Git CLI and repository metadata
• Commit/CM config, Conventional Commit guide, CODEOWNERS playbook, onboarding-risk signals

Canonical command path

git status -sb
git diff --staged
git log --oneline -5

Stage and commit only explicit paths:

git add <specific-files>
git commit -m "$(cat <<'EOF'
<type>(<scope>): <description>

[optional body]

Co-Authored-By: First Fluke <[email protected]>
EOF
)"

Resource scope

| Scope | Resource target |

|-------|-----------------|

| CODEBASE | Tracked files, diffs, conflicts, CODEOWNERS |

| LOCAL_FS | Git metadata, config files, commit message temp files |

| PROCESS | Git commands and verification commands |

| CREDENTIALS | Secret-sensitive files must not be staged or committed |

Preconditions

• Repository and Git intent are identifiable.
• User has authorized the requested SCM operation.

Effects and side effects

• May stage files, create commits, branches, tags, worktrees, or history operations.
• Can affect shared repository history if unsafe commands are used, so approvals matter.

Guardrails

• Explicit user override (highest priority). When the user gives an explicit, unambiguous instruction on how to perform a Git/SCM operation, follow it exactly and do not argue, re-litigate, or block on the conditions below. This overrides every default and guardrail in this skill — including "no direct push to main/protected branches", broad staging, the commit-split rules, single vs. multiple commits, message type/scope/length, and shared-history rewrite. State briefly what you are doing and proceed; do not ask for re-confirmation of an instruction the user already gave. Only confirm if the instruction is genuinely ambiguous (multiple plausible interpretations) — never as a way to push back on a clear directive.
• Single hard exception: likely-secret material (.env, keys, raw tokens). If the user's instruction would stage/commit such material, surface it once before proceeding; everything else proceeds without challenge.
• Choose Quick Path for ordinary commits and Full CM Path for branching, history, release, or governance work.
• Read .agents/oma-config.yaml before applying project-specific commit or CM rules.
• Stage only explicit files; never use broad staging unless the user explicitly approves it.
• Do not rewrite shared history without maintainer approval.
• Never stage or commit likely-secret material.
• Response language follows oma-config.yaml language: user-facing SCM output (status summaries, conflict explanations, CM audit notes, action plans) is localized. Per i18n-guide.md, commit messages, PR titles/body, branch names, and status keywords stay in English regardless of the setting.

Configuration

| File | Role |

|------|------|

| .agents/oma-config.yaml | Conventional Commit types, branch prefixes, message rules, and CM pointers |

Operating mode (choose first)

Quick Path (commit-focused, default)

Use this when the user intent is mainly "commit this safely."

• Follow Conventional Commits section only
• Stage explicit files only
• Validate message type/scope/length from commit-config.yaml
• Stop after safe commit unless user asks CM/governance operations

Full CM Path (repo governance / risky history operations)

Use this when the user asks about branching strategy, merges, rebase/cherry-pick, worktrees, release refs, CODEOWNERS, or audit posture.

• Run CM workflows in order (Planning -> Identification -> Control -> Status accounting -> Verification)
• Add onboarding risk scan when inheriting or auditing a repository
• Include commit governance from Conventional Commits when creating commits
• For large-scope merge operations, use risk scoring and Ask Gate criteria from ../../workflows/scm.md

CM process map (software)

| CM function | Intent | Typical artefacts / actions |

|-------------|--------|------------------------------|

| Management & planning | Agreed rules | CONTRIBUTING.md, SECURITY.md, commit-config.yaml |

| Configuration identification | What is managed, naming | Branch/tag rules, version files, .gitattributes, LFS |

| Configuration control | Reviewed change | PRs, checks, issue links, BREAKING CHANGE footers |

| Status accounting | As-built truth | main / release refs, CHANGELOG, tags, CI status |

| Verification & audit | Evidence | CI logs, signed commits, lockfiles / SBOM policy |

CM workflows (use before risky history operations)

1) Planning

• Read commit-config.yaml and files listed under documented_process.
• If missing, infer from CONTRIBUTING.md / README; state assumptions.
• Confirm branching model and whether force-push on shared branches is allowed (default: not without explicit approval).

2) Identification

• Canonical refs: default branch, release branches/tags, version sources (package.json, etc.).
• .gitattributes / LFS for binaries and generated assets.
• Branch names vs commit-config.yaml branch_prefixes when the project uses them.

3) Control

• Small, reviewable units; align commits with PR / issue intent.
• Conflicts: merge-base, git status, resolve markers, tests; suggest rerere when conflicts repeat.
• Worktrees: git worktree add; merge/rebase from the target branch’s checkout; all worktrees share one object database.
• Do not rewrite shared history without maintainer approval; prefer --force-with-lease if force-push is unavoidable.

4) Status accounting

• git status -sb: branch, remote tracking, ahead/behind, merge state.
• Relate last tag / release branch to CHANGELOG or tooling (semantic-release, release-please, changesets) if present.

5) Verification & audit

• Required CI and merge_group when merge queue applies.
• Never stage/commit secrets (.env, keys, raw tokens). Filename patterns from commit-config.yaml forbidden_patterns are enforced mechanically by the scm-guard PreToolUse hook; for content-level leaks (tokens hardcoded in ordinary source files), run a scanner when available (gitleaks protect --staged, trufflehog git) before large or unfamiliar commits.
• Call out signed-commit expectations when the org cares about verification badges.

CODEOWNERS maintenance checklist

• Validate CODEOWNERS file exists (prefer .github/CODEOWNERS).
• Ensure critical paths are explicitly owned (not only fallback *).
• Ensure owners are active and mapped to current teams.
• Confirm branch protection requires CODEOWNERS review where needed.
• Flag overlapping/ambiguous rules that can hide intended owners.

Read change_governance.require_codeowners and ownership.* in commit-config.yaml when present.

6) Onboarding risk scan (optional, recommended)

Use this quick scan when joining or inheriting a repository to identify risky areas before major changes.

• High churn files in lookback window.
• Ownership concentration / bus-factor signals.
• Bug hotspot files from fix-related history.
• Velocity trend by month.
• Revert/hotfix/emergency frequency.

Read thresholds from commit-config.yaml onboarding_metrics when present and cite caveats:

• squash merge teams can distort ownership metrics,
• weak commit labeling reduces hotspot accuracy,
• monorepo commit counts can bias subsystem interpretation.

Conventional Commits

Commit types

| Type | Description | Branch Prefix |

|------|-------------|---------------|

| feat | New feature | feature/ |

| fix | Bug fix | fix/ |

| refactor | Code improvement | refactor/ |

| docs | Documentation changes | docs/ |

| test | Test additions/modifications | test/ |

| chore | Build, configuration, etc. | chore/ |

| style | Code style changes | style/ |

| perf | Performance improvements | perf/ |

| build | Build system / external dependencies | build/ |

| ci | CI configuration and scripts | ci/ |

| revert | Revert a previous commit | (none) |

Commit format

<type>(<scope>): <description>

[optional body]

Co-Authored-By: First Fluke <[email protected]>

Commit workflow

Step 1: Analyze changes

git status
git diff --staged
git log --oneline -5

Step 1.5: Split by feature (if needed)

If changes span multiple features/domains, split commits by feature.

Split when: the changes are logically independent (different features, unrelated fixes).

Do not split when: one logical change (even if it touches code + tests + docs together), or the user asked for a single commit.

Precedence for edge cases (when both readings are defensible):

• Logical independence decides first — one logical change is one commit regardless of how many types/scopes it touches.
• File count is only a tiebreaker: ≤5 files lean single commit; >5 files spanning multiple scopes/types lean split.
• An explicit user instruction (single commit or split) overrides both.

Step 2: Determine type

• New capability → feat · Bug fix → fix · Structure-only → refactor · Docs only → docs · Tests → test · Build/config → chore

Step 3: Scope

Use module/component: feat(auth):, fix(api):, or omit: chore: update dependencies

Step 4: Description

≤72 chars (per commit-config.yaml), imperative mood, lowercase start, no trailing period.

Step 5: Execute commit

Show the message, then commit with explicit paths:

git add <specific-files>
git commit -m "$(cat <<'EOF'
<type>(<scope>): <description>

[optional body]

Co-Authored-By: First Fluke <[email protected]>
EOF
)"

If HEREDOC is unstable in your shell (or body is long), use file-based commit input:

git add <specific-files>
msgfile="$(mktemp)"
cat > "$msgfile" <<'EOF'
<type>(<scope>): <description>

[optional body]

Co-Authored-By: First Fluke <[email protected]>
EOF
git commit -F "$msgfile"
rm -f "$msgfile"

Use HEREDOC by default, and switch to -F for long or flaky terminal sessions.

Push and PR safety (only when requested)

Push only when the user asks or a workflow requires it. Before pushing:

• git status -sb — confirm branch, remote tracking, ahead/behind.
• Protected-branch check: if the target is the default/protected branch and commit-config.yaml sets require_pr_for_default_branch: true, push a topic branch and open a PR (gh pr create) instead of pushing directly — unless the user explicitly instructed a direct push (Guardrail 0).
• Never plain --force; after an approved history rewrite use git push --force-with-lease.
• If push is rejected (non-fast-forward), fetch and rebase/merge locally; do not retry with force.

Amend, fixup, autosquash

First determine whether the target commits are shared:

git status -sb                 # ahead/behind vs upstream
git log --oneline @{u}..HEAD   # commits not yet pushed (errors when no upstream — treat all as unpushed)

• Unpushed commits: git commit --amend, git commit --fixup <sha> + git rebase -i --autosquash, and interactive rebase are safe — proceed.
• Pushed/shared commits: this is a shared-history rewrite — require maintainer approval (Guardrail 4) and use --force-with-lease when pushing the result.
• Before --amend, check git diff --staged: the amend must not silently absorb unrelated staged changes.

References

• .agents/oma-config.yaml
• resources/conventional-commits.md
• resources/onboarding-risk-signals.md
• resources/codeowners-playbook.md
• Observability handoff: ../oma-observability/SKILL.md §Integrations — release markers (service.version), revert baseline diff

Important notes

• Explicit user instruction wins. A clear user directive on how to commit/push/branch overrides every rule below (and every other guardrail). Follow it without arguing; the only thing that still warrants a heads-up is likely-secret material.
• NEVER git add -A or git add . without explicit user permission.
• NEVER commit likely-secret material.
• ALWAYS stage by explicit paths; tie non-trivial CM work to the five CM rows above, even briefly.