Git

Best practices and conventions for git operations in the Forge ecosystem. This is a multi-repo project with git submodules — commit ordering, message style, and staging discipline matter.

Commit Messages

Use conventional commit prefixes. Message should explain why, not what.

Keep the first line under 72 characters. Add a blank line and body for context when the change is non-obvious.

Never add Co-Authored-By trailers unless the user explicitly asks.

Staging

• •Stage specific files by name — never use git add -A or git add .
• •Review git diff --staged before committing
• •Never commit files that contain secrets (.env, config.yaml, credentials)
• •config.yaml is gitignored at every level — never commit it
• •CLAUDE.md and AGENTS.md are generated outputs — never commit manual edits to them

Submodule Workflow

Forge-core uses git submodules. Commit order matters:

1. •Commit and push each dirty submodule first (children before parent)
2. •Stage the updated submodule pointers in the parent repo (git add Modules/forge-*)
3. •Commit the parent with a message describing what changed across the ecosystem

When multiple submodules have the same kind of change (e.g., a docs sweep), commit them in parallel if independent.

Checking submodule state

git submodule foreach --quiet 'if [ -n "$(git status --porcelain)" ]; then echo "$name: dirty"; git status --short; fi'

Push Policy

• •Never force-push (--force, --force-with-lease) unless the user explicitly asks
• •Never skip hooks (--no-verify) unless the user explicitly asks
• •Push submodules before the parent — the parent's pointer must reference a pushed commit
• •Do not push unless the user asks — committing and pushing are separate actions

Pull Requests

• •Title under 70 characters — details go in the body
• •Body format: ## Summary (1-3 bullets) + ## Test plan (checklist)
• •Create from a feature branch, never directly from main

Generated Files

These files are generated by forge-init.sh / forge-update.sh and should not be edited by hand:

If the generated content is wrong, fix the source (content in Orchestration/, module skills, steering rules) and regenerate.

Version Bumps

When releasing a module:

1. •Bump version: in module.yaml
2. •Bump version in .claude-plugin/plugin.json (must match)
3. •Commit with: chore: bump <module> to <version> or include in the feature commit