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.

Repository Storage Convention

Scopes Inventory: .github/scopes-inventory.md

•Machine-readable inventory of all scopes extracted from git history
•Updated automatically by running extract_scopes.py
•Simple structured format for easy consumption by tools and humans

Constitution Document: .github/scope-constitution.md

•Human-readable constitution with definitions, guidelines, and rationale
•Authoritative source for scope approval and usage
•Version controlled alongside code

Template Reference: skills/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 is defined as a conventional commit message:

txt

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

<optional_multi-line_description>

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

markdown

# 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:

bash

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

# Or just recent scopes (last 3 months)
python skills/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.

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:

code

Repository: github-copilot-fc

Top-level structure:
- agents/          → Custom agent definitions
- instructions/    → Copilot instructions
- prompts/         → Prompt templates
- skills/          → Claude skills
- scripts/         → Automation scripts
- toolsets/        → Tool configurations
- .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/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:

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

For Constitution Updates:

•Document new scopes discovered in recent commits
•Add scopes for new project structures (folders, modules, domains)
•Consolidate redundant or similar scopes (with migration notes)
•Refine definitions for ambiguous scopes
•Update naming conventions if patterns have evolved
•Add examples for unclear cases
•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:

markdown

## 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:

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

Recommended Commit Message:

txt

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

- Added 5 new scopes for ai(skill) 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:

•Extract scopes from the past week
•Compare with constitution
•Check for new project structures (folders, modules)
•Add new scopes or flag anomalies
•Update if needed

Pre-Commit Validation

Before committing, validate scope choice against constitution:

•Identify commit type from file paths
•Consult constitution for approved scopes under that type
•Choose most appropriate scope
•If no scope fits, propose amendment

Scope Discovery

When uncertain about scope naming:

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

Scripts

`scripts/extract_scopes.py`

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

Usage:

bash

# 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:

markdown

# 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/scope-constitution.md in target repository

references/scopes-inventory-template.md

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

Repository Files (Version Controlled)

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

•Authoritative constitution defining all approved scopes
•Version controlled with the repository
•Updated regularly (weekly recommended)
•Referenced by developers when choosing commit scopes
•Used as input for commit validation tooling

.github/scopes-inventory.md (in target repository)

•Machine-readable inventory of all scopes
•Generated by extract_scopes.py script
•Updated with each constitution review
•Provides quick overview of scope usage
•Used for tracking scope evolution over time

Best Practices

Scope Granularity

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

Recommended Patterns:

•Kebab-case: user-profile, api-client
•Singular form: skill, agent, instruction
•Domain/module-based: auth, billing, dashboard
•Avoid verbs: Use api-client not calling-api

Anti-Patterns:

•Camel case: userProfile
•Snake case: user_profile
•Spaces: user profile
•Overly generic: misc, other, stuff

Constitutional Amendments

Good Reasons to Add Scope:

•New module or domain added to codebase
•Existing scope is too broad and needs splitting
•Consistent pattern of commits without clear scope

Bad Reasons to Add Scope:

•One-off change that doesn't justify a scope
•Avoiding learning existing scopes
•Personal preference for different naming

Scope Lifecycle

Creation: New scope added via constitutional amendment Active Use: Scope appears regularly in commits Consolidation: Similar scopes merged into one Deprecation: Scope no longer relevant, marked deprecated Retirement: Deprecated scope removed from constitution (but remains in history)

Maintenance Schedule

Maintenance Schedule:

•Extract scopes from past week (--since "1 week ago")
•Analyze any new folders/modules added to repository
•Compare with constitution
•Flag anomalies or new scopes
•Update constitution if patterns warrant

Monthly:

•Review scope usage patterns
•Analyze repository structure changes (refactoring, new modules)
•Identify consolidation opportunities
•Update naming conventions if needed

Quarterly:

•Comprehensive constitution review
•Major amendments and restructuring based on repository evolution
•Scope lifecycle management (deprecations/retirements)

Integration with git-atomic-commit

This skill complements the git-atomic-commit skill:

•git-atomic-commit enforces commit type mappings (file path → commit type)
•commit-scope-constitution defines valid scopes within each commit type
•Together they ensure: correct_type(approved_scope): clear message

Workflow Integration:

code

File Changed → git-atomic-commit → Commit Type Assigned
                                           ↓
                          commit-scope-constitution → Scope Selected
                                           ↓
                                    Final Commit Message

Error Handling

Scope Not Found in Constitution:

•Search historical usage with extract_scopes.py
•Check if similar scope exists with different name
•If genuinely new, draft amendment proposal
•Get approval before using in commit

Constitution Conflicts:

•Multiple scopes seem valid for the change
•Review scope definitions for clarity
•Choose the most specific applicable scope
•If ambiguity persists, refine constitution

Scope Naming Violations:

•Flag non-conforming scope name
•Check constitution for correct format
•Propose rename if scope is valuable
•Update historical references if needed

Examples

Example 1: Creating Initial Constitution with Repository Analysis

bash

# Step 1: Extract historical scopes
python skills/commit-scope-constitution/scripts/extract_scopes.py \
  --output .github/scopes-inventory.md

# Step 2: Analyze repository structure
# List top-level directories
Repository: my-web-app/
  src/
    components/     → UI components
    services/       → Business logic services
    utils/          → Utility functions
  tests/            → Test files
  scripts/          → Build/automation scripts
  docs/             → Documentation
  .github/          → GitHub workflows

# Step 3: Map structure to scopes
From structure analysis:
- components/ → scope: "components" or specific component names
- services/auth/ → scope: "auth"
- services/billing/ → scope: "billing"
- scripts/ → scope: "script" or "build"
- docs/ → scope: "docs"

From git history (.github/scopes-inventory.md):
- feat(components): Used 15 times
- feat(auth): Used 8 times
- feat(billing): Used 12 times
- fix(api): Used 6 times
- chore(deps): Used 20 times

# Step 4: Create constitution
# Combine structure-based and history-based scopes
# Document in .github/scope-constitution.md with clear definitions

Example 2: Weekly Refinement

bash

# Extract last week's scopes
python skills/commit-scope-constitution/scripts/extract_scopes.py \
  --since "1 week ago" --format markdown

# Check for new folders/modules
# Found: New folder src/services/notifications/

# Review against constitution
# Found new scope: feat(notifications) used 3 times
# Found folder: services/notifications/ (new module)

# Update constitution
# Add to appropriate section:
# - `notifications`: Notification service and delivery system

Example 3: Scope Selection for Existing Codebase

code

Scenario: Modifying skills/git-atomic-commit/SKILL.md

Step 1: Check commit type mapping
  → File pattern: skills/* → ai(skill)

Step 2: Consult constitution under ai(skill)
  → Available scopes: skill-creator, git-atomic-commit, diataxis, ...

Step 3: Select appropriate scope
  → Change affects git-atomic-commit skill → Use `git-atomic-commit`

Result: ai(skill): improve pre-commit validation checklist

Example 4: Scope Selection with Repository Structure Analysis

code

Scenario: Adding new authentication feature

Step 1: Analyze repository structure
  → services/auth/ exists (authentication module)
  → New files: services/auth/oauth.ts, services/auth/jwt.ts

Step 2: Check commit type
  → File pattern: services/* → feat (no project-specific type)

Step 3: Check constitution for feat scopes
  → .github/scope-constitution.md shows:
    - auth: Authentication and authorization
    - billing: Payment processing
    - dashboard: Dashboard features

Step 4: Select scope based on structure
  → Files in services/auth/ → Use scope: auth
  → Aligns with both structure and constitution

Result: feat(auth): implement OAuth 2.0 authentication flow

Example 5: Constitutional Amendment

markdown

## Amendment History

### 2026-02-04 - Amendment #12

**Changes:**
- Split `copilot(custom-agent)` scope `agent` into three scopes:
  - `agent-definition`: For agent frontmatter and metadata
  - `agent-implementation`: For agent body and instructions
  - `agent-toolset`: For agent tool configurations
  
**Rationale:**
Analysis of Q1 2026 commits showed agents are modified in three distinct ways:
- Metadata updates (name, description)
- Instruction refinements
- Tool configuration changes

These often occur independently and benefit from separate scopes.

**Migration Notes:**
Existing commits with `agent` scope are valid. Use new scopes for future commits.
Consolidation commits that touch multiple aspects can use general `agent` scope.