git-commit-scope-constitution

name	git-commit-scope-constitution
description	Build and refine a constitution defining valid commit scopes for each commit type. Use when maintaining .github/git-scope-constitution.md, discovering new scopes from git history or repo structure, validating scope choices, or conducting weekly scope reviews. Scopes are repo-specific; types are universal.
metadata	{"version":"2.0.0","author":"arisng"}

Commit Scope Constitution

Overview

This skill enables building and maintaining a living constitution that defines the inventory and rules for commit scopes used in conventional commits. The constitution serves as the authoritative source for:

• Approved scope names organized by commit type
• Naming conventions and patterns for scopes
• Scope definitions and boundaries
• Guidance for choosing appropriate scopes

Repository-Specific Design: Each repository maintains its own scopes inventory and constitution, stored within the repository itself. This ensures scopes align with the specific project structure, domains, and modules of that repository.

Core Principle: Type vs. Scope (Three-Tier Model)

Commit messages follow the pattern type(scope): subject, governed by a three-tier hierarchy:

Tier	What it governs	Defined by	Stability
1. Universal	Standard Conventional Commits types (feat, fix, docs, etc.)	Industry convention	Fixed across all repos
2. Author Preferences	Extended types (agent, copilot, devtool, codex) + default file-path mappings	Skill author (opinionated, portable)	Shared across author's repos; users may override
3. Workspace-Specific	Scopes, additional types, file-path overrides	.github/git-scope-constitution.md per repo	Unique per repository

• Commit Type (Tier 1 + 2): Represents the intent or category of the change. Universal types are immutable; extended types are the author's opinionated additions that take precedence when applicable.
• Commit Scope (Tier 3): Represents the domain, module, or location of the change. Scopes are tightly coupled to the context of each repository.

This skill's primary job is to define the Tier 3 Scopes for a specific repository and map them to the appropriate Types.

Repository Storage Convention

Scopes Inventory: .github/git-scope-inventory.md

• Purpose: Machine-readable inventory of all scopes extracted from git history
• Content: Simple structured list of scopes actually used in commits, organized by commit type
• Maintenance: Updated automatically by running extract_scopes.py
• Usage: Analysis tool for understanding current scope usage patterns
• Format: Structured markdown with summary statistics and scope lists

Constitution Document: .github/git-scope-constitution.md

• Purpose: Human-readable constitution defining approved scopes and usage rules
• Content: Authoritative definitions, naming conventions, selection guidelines, and amendment process
• Maintenance: Manually maintained with regular updates (weekly recommended)
• Usage: Reference guide for developers choosing commit scopes
• Format: Structured markdown with sections for different commit types and governance

Key Distinction: The inventory shows what has been used (historical fact), while the constitution defines what should be used (governance policy). The inventory feeds into constitution updates, but the constitution governs future commits.

Template Reference: skills/git-commit-scope-constitution/references/scope-constitution.md

• Template for creating new constitutions
• Not used at runtime (exists only in this skill)

Constitution Format

The commit scope constitution governs the scopes used in conventional commit messages:

<commit_type>(<scope>): <executive summary>

<optional_multi-line_description>

MANDATORY: Single Scope Only
Each commit MUST have exactly one scope. Never use multiple scopes (e.g., <type>(<scope1>)(<scope2>)). If a change affects multiple areas, choose the most significant one as the primary <scope> and explicitly mention any secondary area in the <subject> part (e.g., <type>(primary-scope): [secondary-area] actual message).

The constitution itself is stored in .github/git-scope-constitution.md and follows this structure:

# Commit Scope Constitution

Last Updated: YYYY-MM-DD

## Purpose

This constitution defines the approved scopes for atomic commits, ensuring consistency and clarity in commit history.

## Scope Naming Conventions

[Rules for creating scope names]

## Approved Scopes by Commit Type

### `commit_type`

- `scope-name`: Brief description of what this scope covers
- `another-scope`: Brief description

[Additional sections as needed]

## Scope Selection Guidelines

[Guidance for choosing appropriate scopes]

## Amendment Process

[How to propose and approve new scopes]

Workflow

1. Analyze Current Repository State

Start by understanding the repository from two perspectives:

1a. Extract Historical Scopes from Git

Analyze git commit history to see what scopes have been used:

# Extract all historical scopes
python skills/git-commit-scope-constitution/scripts/extract_scopes.py --format markdown --output .github/git-scope-inventory.md

# Or just recent scopes (last 3 months)
python skills/git-commit-scope-constitution/scripts/extract_scopes.py --since "3 months ago" --format markdown

This generates an inventory of all scopes currently used in the repository's git history, organized by commit type.

Note: The scopes inventory shows historical usage (what has been done), while the constitution defines approved usage (what should be done). Use the inventory as input for constitution updates, but always reference the constitution for governance decisions.

1b. Analyze Repository Structure

CRITICAL: Scopes should align with the actual project structure, not just historical commits. Analyze the repository to understand:

Folder Structure Analysis:

• List top-level directories and their purpose
• Identify module boundaries (e.g., services/, components/, tools/)
• Note domain-specific folders (e.g., auth/, billing/, dashboard/)
• Recognize documentation areas (e.g., .docs/, docs/, README.md)

Project Architecture:

• Identify bounded contexts or domains
• Note technology-specific directories (e.g., scripts/, tests/, config/)
• Recognize artifact types (e.g., agents/, skills/, prompts/)

Key Questions:

• What are the major functional areas of this project?
• How is the code organized (by feature, layer, domain)?
• What are the natural scope boundaries based on the structure?
• Are there emerging patterns in folder naming?

Example Analysis:

Repository: github-copilot-fc

Top-level structure:
- agents/          → Custom agent definitions
- instructions/    → Copilot instructions
- prompts/         → Prompt templates
- skills/          → Claude skills
- scripts/         → Automation scripts
- tools/           → Tools inventory and VS Code runtime toolsets
- .docs/           → Documentation

Derived scope patterns:
- Artifact-based: agent, instruction, prompt, skill, toolset
- Function-based: script (for automation)
- Domain-based: issue, changelog (from .docs/ subfolders)

2. Synthesize Scope Landscape

Combine insights from git history and repository structure:

Merge Historical and Structural Scopes:

• Historical scopes show what has been used
• Structural analysis shows what should be used
• Gaps indicate either unused structure or undocumented scopes

Identify Patterns:

• Do historical scopes align with folder structure?
• Are there folders without corresponding scopes?
• Are there scopes used for non-existent structures?

3. Review Existing Constitution

Check if a constitution already exists:

• Read .github/git-scope-constitution.md if present
• Compare with extracted historical scopes
• Compare with repository structure analysis
• Identify discrepancies (scopes used but not documented, structures without scopes)

4. Constitutional Analysis

Evaluate the current scope landscape:

Quality Checks:

• Are scope names consistent in format (kebab-case, singular vs plural)?
• Are scopes granular enough to be meaningful but not overly specific?
• Do scope definitions clearly distinguish between related scopes?
• Are there redundant or overlapping scopes that should be consolidated?
• Are scopes aligned with the codebase's module/domain structure?

Pattern Recognition:

• Identify naming patterns (e.g., module-based feature-based, domain-based, file-path-based)
• Detect inconsistencies (same concept with different names)
• Find under-scoped types (types with no or too few scopes)

5. Draft or Update Constitution

Based on analysis, create or update the constitution:

For New Constitutions:

1. Define scope naming conventions
2. Organize scopes by commit type (align with repository structure)
3. Provide clear definitions for each scope (reference folder/module names)
4. Establish guidelines for scope selection
5. Define amendment process
6. Document the repository structure that informed scope decisions

For Constitution Updates:

1. Document new scopes discovered in recent commits
2. Add scopes for new project structures (folders, modules, domains)
3. Consolidate redundant or similar scopes (with migration notes)
4. Refine definitions for ambiguous scopes
5. Update naming conventions if patterns have evolved
6. Add examples for unclear cases
7. Align with any structural refactoring in the repository

Key Principles:

• Stability: Minimize breaking changes to existing scopes
• Clarity: Each scope should have a clear, non-overlapping definition
• Discoverability: Organize scopes logically for easy lookup
• Flexibility: Allow for organic growth while maintaining consistency

6. Validation

Validate the updated constitution:

Completeness Checks:

• All commit types used in repository are documented
• All active scopes (from recent commits) are included
• Each scope has a clear definition
• Naming conventions are documented and examples provided

Consistency Checks:

• Scope names follow established conventions
• No duplicate or near-duplicate scopes
• Definitions are mutually exclusive
• Examples align with definitions

7. Document Changes

Record constitutional amendments:

Amendment Log Format:

## Amendment History

### YYYY-MM-DD - Amendment #N

**Changes:**
- Added scope `new-scope` to `commit_type`
- Consolidated `old-scope-1` and `old-scope-2` into `unified-scope`
- Clarified definition of `ambiguous-scope`

**Rationale:**
[Why these changes were made]

**Migration Notes:**
[How to handle existing commits with old scopes]

8. Publish Constitution and Inventory

Save the finalized constitution and inventory:

1. Write constitution to .github/git-scope-constitution.md
2. Write scopes inventory to .github/git-scope-inventory.md
3. Update the "Last Updated" date in constitution
4. Commit both files with a descriptive commit message

Recommended Commit Message:

docs(constitution): update scope inventory with Q1 2026 scopes

- Added 5 new scopes for `agent` type commits
- Consolidated instruction scopes into 3 clear categories
- Clarified boundaries between codex and copilot scopes

Usage Patterns

Weekly Refinement

Run this workflow weekly to keep the constitution current:

1. Extract scopes from the past week
2. Compare with constitution
3. Check for new project structures (folders, modules)
4. Add new scopes or flag anomalies
5. Update if needed

Pre-Commit Validation

Before committing, validate scope choice against constitution:

1. Identify commit type from file paths
2. Consult constitution for approved scopes under that type
3. Choose most appropriate scope
4. If no scope fits, propose amendment

Scope Discovery

When uncertain about scope naming:

1. Check constitution for similar scopes
2. Review historical usage with extract_scopes.py --since "1 month ago"
3. Follow naming conventions from constitution
4. Document new scope if creating one

Scripts

scripts/extract_scopes.py

Analyzes git history to extract all scopes used in conventional commit messages.

Usage:

# Extract all scopes
python scripts/extract_scopes.py

# Filter by time period
python scripts/extract_scopes.py --since "1 week ago"

# Output as JSON
python scripts/extract_scopes.py --format json

# Save to file
python scripts/extract_scopes.py --output inventory.md

Output Formats:

• markdown: Structured inventory with summary statistics and organized scope lists
• json: Machine-readable structure for tooling

Inventory Structure:

# Scopes Inventory

**Repository:** [name]
**Last Updated:** [date]
**Source:** Git commit history analysis

## Summary
- Total Commit Types: N
- Total Unique Scopes: N
- Analysis Period: [timeframe]

## Scopes by Commit Type
### `type`
- scope-1
- scope-2

## Notes
[Additional context]

References

Template Files (Skill Resources)

references/scope-constitution.md

• Template for creating new constitutions
• Not used at runtime (reference only)
• Copy to .github/git-scope-constitution.md in target repository

references/scope-inventory-template.md

• Example of structured inventory format
• Shows expected output structure
• Used as reference for manual inventory creation

Repository Files (Version Controlled)

.github/git-scope-constitution.md (in target repository)

• Role: Authoritative constitution defining all approved scopes and governance rules
• Content: Scope definitions, naming conventions, selection guidelines, amendment process
• Purpose: Governs what scopes developers should use in future commits
• Maintenance: Manually updated through constitutional amendments
• Usage: Primary reference for developers and commit validation tooling
• Update Frequency: Weekly reviews, amendments as repository evolves

.github/git-scope-inventory.md (in target repository)

• Role: Historical inventory of scopes actually used in the repository
• Content: Machine-readable list of all scopes found in git commit history
• Purpose: Tracks what scopes have been used (descriptive, not prescriptive)
• Maintenance: Automatically generated by extract_scopes.py script
• Usage: Analysis input for constitution updates and scope evolution tracking
• Update Frequency: With each constitution review or on-demand analysis

Best Practices

Scope Granularity

Category-Level Principle (Tier 2 Extended Types):

For extended types (agent, copilot, devtool, codex), scopes must be artifact categories, not specific instances. When scanning git log --oneline, type(category) instantly conveys what kind of thing changed; the subject line says which one.

Pattern	Example	Verdict
Category scope	agent(skill): add table extraction to pdf	✅
Instance scope	agent(pdf): add table extraction	❌
Category scope	copilot(instruction): tighten powershell linting rules	✅
Instance scope	copilot(powershell): tighten linting rules	❌
Category scope	devtool(script): fix publish path resolution	✅
Instance scope	devtool(publish): fix path resolution	❌

General Granularity (All Types):

Too Broad:

• feat(code): add feature → What part of the code?
• fix(app): fix bug → Which component?

Too Narrow:

• feat(src/components/forms/UserForm.tsx): add validation → File-specific
• fix(line-42-in-utils): fix typo → Too granular

Just Right:

• feat(user-form): add email validation
• fix(auth): correct token expiration logic

Naming Conventions