Git Repo Standards

Git Repository Standards

Enforce consistent repository naming, structure, documentation, and security standards across all fyrsmithlabs projects.

Modes of Operation

Enforcement Tiers

Repository Naming

Format: lowercase-kebab-case

Pattern: [domain]-[type]

Valid Examples:

• marketplace
• auth-service
• plugin-registry-api
• git-workflow-lib
• temporal-worker

Blocked Patterns:

Validation Rules:

• Max 50 characters
• Must start with letter
• Only a-z, 0-9, -
• Hyphen cannot start/end name or be consecutive

Directory Structure

Go Projects

repo-name/
├── cmd/                    # Application entrypoints
│   └── app-name/
│       └── main.go
├── internal/               # Private packages (compiler-enforced)
│   ├── domain/             # Business logic by feature
│   └── platform/           # Infrastructure (db, cache, etc.)
├── pkg/                    # Public reusable libraries (optional)
├── api/                    # OpenAPI specs, protobuf definitions
├── configs/                # Config templates
├── scripts/                # Build, CI, dev scripts
├── deployments/            # Docker, k8s, terraform
├── docs/
│   ├── .claude/            # Agent artifacts (MUST be gitignored)
│   │   ├── tasks/
│   │   ├── plans/
│   │   └── orchestration/
│   └── adr/                # Architecture decision records
├── .github/
│   ├── workflows/          # GitHub Actions workflows
│   │   ├── ci.yml
│   │   ├── security.yml
│   │   └── release.yml
│   ├── dependabot.yml      # Dependency updates
│   ├── ISSUE_TEMPLATE/     # Issue templates
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── CODEOWNERS
├── .gitignore
├── .gitleaks.toml
├── .pre-commit-config.yaml # Pre-commit hooks (recommended)
├── CHANGELOG.md
├── CONTRIBUTING.md         # Contributor guide (public repos)
├── LICENSE
├── README.md
├── SECURITY.md             # Security policy (public repos)
└── go.mod

Generic/Non-Go Projects

repo-name/
├── src/                    # Source code
├── lib/                    # Shared libraries
├── tests/                  # Test files
├── docs/
│   ├── .claude/            # Agent artifacts (MUST be gitignored)
│   │   ├── tasks/
│   │   ├── plans/
│   │   └── orchestration/
│   └── adr/                # Architecture decision records
├── scripts/                # Build, CI, dev scripts
├── configs/                # Configuration templates
├── deployments/            # Infrastructure as code
├── .github/
│   ├── workflows/          # GitHub Actions workflows
│   ├── ISSUE_TEMPLATE/     # Issue templates
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── CODEOWNERS
├── .gitignore
├── .gitleaks.toml
├── .pre-commit-config.yaml # Pre-commit hooks (recommended)
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
└── SECURITY.md             # Security policy (public repos)

Monorepo Structure

For projects using monorepo patterns (nx, turborepo, lerna):

monorepo-name/
├── apps/                   # Application packages
│   ├── api/
│   ├── web/
│   └── cli/
├── packages/               # Shared libraries
│   ├── core/
│   ├── ui/
│   └── utils/
├── tools/                  # Build tools, generators
├── docs/
│   ├── .claude/            # Agent artifacts (MUST be gitignored)
│   └── adr/
├── .github/
│   ├── workflows/
│   ├── ISSUE_TEMPLATE/
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── CODEOWNERS
├── .gitignore
├── .gitleaks.toml
├── .pre-commit-config.yaml
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── SECURITY.md
├── nx.json / turbo.json / lerna.json
└── package.json / go.work

Monorepo Tool Support:

Multi-Language (Polyglot) Structure

For repositories containing multiple languages:

polyglot-service/
├── backend/                # Go, Rust, or Python
│   ├── cmd/
│   ├── internal/
│   └── go.mod
├── frontend/               # TypeScript/JavaScript
│   ├── src/
│   └── package.json
├── scripts/                # Shared build scripts
│   └── build.sh
├── docker/                 # Container definitions
│   ├── backend.Dockerfile
│   └── frontend.Dockerfile
├── docs/
│   ├── .claude/
│   └── adr/
├── .github/
│   ├── workflows/
│   └── CODEOWNERS
├── docker-compose.yml
├── Makefile               # Unified build commands
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
└── SECURITY.md

Anti-Patterns

README Requirements

Required Sections (Block if missing)

Required Badges

Badge Placement:

# repo-name

![Build](...)  ![Go](...)  ![License](...)  ![Gitleaks](...)  ![OpenSSF](...)

One-line description of what this repo does.

OpenSSF Best Practices Badge:

[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/XXXXX/badge)](https://www.bestpractices.dev/projects/XXXXX)

Register at bestpractices.dev to obtain a project ID.

Recommended Sections (Warn if missing)

CHANGELOG Requirements

Format: Keep a Changelog style

# Changelog

## [Unreleased]

## [1.2.0] - 2026-01-07
### Added
- New feature X

### Changed
- Updated behavior Y

### Fixed
- Bug Z

Enforcement Rules:

Valid Categories: Added, Changed, Deprecated, Removed, Fixed, Security

Licensing

Alternative Licenses (Supported but Flagged):

Enforcement Rules:

AGPL-3.0 Additional Requirements:

• Include notice in README: "This software is licensed under AGPL-3.0. Network use constitutes distribution."
• Add AGPL badge: ![License](https://img.shields.io/badge/license-AGPL--3.0-blue)

License Compliance Checking:

• Use tools like license-checker, go-licenses, or fossa to audit dependencies
• Document third-party licenses in THIRD_PARTY_LICENSES.md for projects with many dependencies
• Block commits that introduce GPL-incompatible dependencies into Apache-2.0 projects

SECURITY.md Requirements

Required for: All public repositories

Template:

# Security Policy

## Supported Versions

| Version | Supported          |
| ------- | ------------------ |
| 1.x.x   | :white_check_mark: |
| < 1.0   | :x:                |

## Reporting a Vulnerability

Please report security vulnerabilities via [security@fyrsmithlabs.com](mailto:security@fyrsmithlabs.com).

**Do NOT report security vulnerabilities through public GitHub issues.**

Include:
- Description of the vulnerability
- Steps to reproduce
- Potential impact
- Suggested fix (if any)

### Response Timeline

- **Acknowledgment:** Within 48 hours
- **Initial Assessment:** Within 7 days
- **Resolution Target:** Within 90 days (critical: 30 days)

## Security Measures

- All commits scanned with gitleaks
- Dependencies monitored via Dependabot/Renovate
- SBOM generated for releases

## Disclosure Policy

We follow coordinated disclosure. We request 90 days to address vulnerabilities before public disclosure.

Enforcement Rules:

CODEOWNERS Requirements

Purpose: Define code ownership for automated review assignment.

Location: .github/CODEOWNERS or CODEOWNERS (root)

Template:

# Default owners for everything
* @fyrsmithlabs/maintainers

# Specific ownership
/api/           @fyrsmithlabs/api-team
/internal/auth/ @fyrsmithlabs/security-team
/docs/          @fyrsmithlabs/docs-team

# Security-sensitive files require security team review
SECURITY.md     @fyrsmithlabs/security-team
.gitleaks.toml  @fyrsmithlabs/security-team
*.pem           @fyrsmithlabs/security-team

Enforcement Rules:

CONTRIBUTING.md Requirements

Purpose: Guide external and internal contributors.

Template:

# Contributing to [Project Name]

## Code of Conduct

This project follows our [Code of Conduct](CODE_OF_CONDUCT.md).

## Getting Started

1. Fork the repository
2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/repo-name`
3. Create a branch: `git checkout -b feature/your-feature`
4. Make your changes
5. Run tests: `make test`
6. Commit using conventional commits: `git commit -m "feat: add feature"`
7. Push and create a PR

## Development Setup

[Include prerequisites, build instructions, test commands]

## Pull Request Process

1. Update README.md and CHANGELOG.md if needed
2. Ensure all tests pass
3. Request review from CODEOWNERS
4. Squash and merge after approval

## Commit Messages

We use [Conventional Commits](https://www.conventionalcommits.org/):

- `feat:` new feature
- `fix:` bug fix
- `docs:` documentation only
- `chore:` maintenance

## Reporting Issues

Use GitHub Issues with the appropriate template.

Enforcement Rules:

Issue and PR Templates

Issue Templates

Location: .github/ISSUE_TEMPLATE/

Bug Report (bug_report.md):

---
name: Bug Report
about: Report a bug to help us improve
title: '[BUG] '
labels: bug, triage
assignees: ''
---

## Description
A clear description of the bug.

## Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. See error

## Expected Behavior
What you expected to happen.

## Actual Behavior
What actually happened.

## Environment
- OS: [e.g., macOS 14.0]
- Version: [e.g., v1.2.3]
- Go version: [e.g., 1.22]

## Additional Context
Any other context, logs, or screenshots.

Feature Request (feature_request.md):

---
name: Feature Request
about: Suggest a new feature
title: '[FEATURE] '
labels: enhancement
assignees: ''
---

## Problem Statement
What problem does this solve?

## Proposed Solution
How should this work?

## Alternatives Considered
What other approaches did you consider?

## Additional Context
Any other context or mockups.

Pull Request Template

Location: .github/PULL_REQUEST_TEMPLATE.md

## Summary
Brief description of changes.

## Type of Change
- [ ] Bug fix (non-breaking)
- [ ] New feature (non-breaking)
- [ ] Breaking change
- [ ] Documentation update

## Changes Made
- Change 1
- Change 2

## Testing
- [ ] Tests pass locally
- [ ] New tests added for changes
- [ ] Manual testing completed

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-reviewed my code
- [ ] Updated documentation if needed
- [ ] Updated CHANGELOG.md
- [ ] No secrets or credentials committed

## Related Issues
Closes #XXX

Enforcement Rules:

ADR (Architecture Decision Records)

Location: docs/adr/

Purpose: Document significant architectural decisions with context.

Naming Convention: NNNN-title-in-kebab-case.md (e.g., 0001-use-postgresql-for-persistence.md)

Template:

# ADR-NNNN: Title

**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
**Date:** YYYY-MM-DD
**Authors:** @username

## Context

What is the issue that we're seeing that is motivating this decision or change?

## Decision

What is the change that we're proposing and/or doing?

## Consequences

What becomes easier or more difficult to do because of this change?

### Positive
- Benefit 1
- Benefit 2

### Negative
- Drawback 1
- Drawback 2

### Neutral
- Trade-off 1

## Alternatives Considered

### Alternative 1
Description and why it was rejected.

### Alternative 2
Description and why it was rejected.

Enforcement Rules:

Branching Strategy

Model: GitHub Flow (trunk-based)

main (protected)
  └── feature/short-description
  └── fix/issue-number-description
  └── chore/cleanup-description

Branch Naming Pattern: [type]/[description]

Blocked Patterns:

Protected Branch Rules (main):

• Require PR with at least 1 approval
• Require CI passing
• Require gitleaks check passing
• No force push
• No deletion

Branch Protection Configuration

Required Settings (GitHub):

# Recommended branch protection rules for main
protection_rules:
  main:
    required_pull_request_reviews:
      required_approving_review_count: 1
      dismiss_stale_reviews: true
      require_code_owner_reviews: true
      require_last_push_approval: true
    required_status_checks:
      strict: true
      contexts:
        - "ci/test"
        - "ci/lint"
        - "security/gitleaks"
        - "security/dependency-review"
    enforce_admins: true
    required_linear_history: true
    allow_force_pushes: false
    allow_deletions: false
    required_conversation_resolution: true

Enforcement Tiers:

Enforcement Rules:

Commit Conventions

Format: Conventional Commits

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

[optional body]

[optional footer(s)]

Commit Types:

Breaking Changes:

feat(api)!: remove deprecated endpoints

BREAKING CHANGE: /v1/users endpoint removed, use /v2/users

Enforcement Rules:

Scope: Use package/module name (auth, api, db) or feature area (search, billing)

Gitleaks & Security

Required: Every repo must have gitleaks enabled.

Configuration Methods (any one):

Minimum .gitleaks.toml:

[extend]
useDefault = true

[allowlist]
description = "Project-specific allowlist"
paths = [
    '''docs/.claude/''',
    '''vendor/''',
    '''testdata/''',
]

Enforcement Rules:

Remediation on Detection:

1. Remove secret from code
2. Rotate the exposed credential immediately
3. Use git filter-branch or BFG to purge from history
4. Add to .gitleaks.toml allowlist only if false positive

GitHub Actions Workflow Templates

Location: .github/workflows/

CI Workflow (ci.yml)

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version-file: 'go.mod'
      - name: Test
        run: go test -race -coverprofile=coverage.out ./...
      - name: Upload coverage
        uses: codecov/codecov-action@v4
        with:
          files: coverage.out

  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: golangci/golangci-lint-action@v6
        with:
          version: latest

  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Gitleaks
        uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - name: Dependency Review
        uses: actions/dependency-review-action@v4
        if: github.event_name == 'pull_request'

Security Scanning (security.yml)

name: Security

on:
  push:
    branches: [main]
  pull_request:
  schedule:
    - cron: '0 6 * * 1'  # Weekly Monday 6am

permissions:
  contents: read
  security-events: write

jobs:
  codeql:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v3
        with:
          languages: go
      - name: Build
        run: go build ./...
      - name: Analyze
        uses: github/codeql-action/analyze@v3

  trivy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Trivy vulnerability scan
        uses: aquasecurity/trivy-action@master
        with:
          scan-type: 'fs'
          severity: 'CRITICAL,HIGH'
          exit-code: '1'

Release with SBOM (release.yml)

name: Release

on:
  push:
    tags: ['v*']

permissions:
  contents: write
  packages: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version-file: 'go.mod'
      - name: Generate SBOM
        uses: anchore/sbom-action@v0
        with:
          artifact-name: sbom.spdx.json
          output-file: sbom.spdx.json
      - name: Release
        uses: goreleaser/goreleaser-action@v6
        with:
          args: release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Enforcement Rules:

Pre-commit Hooks

Configuration: .pre-commit-config.yaml

Recommended Configuration:

repos:
  # General hooks
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-json
      - id: check-merge-conflict
      - id: detect-private-key
      - id: no-commit-to-branch
        args: ['--branch', 'main']

  # Secrets detection
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.4
    hooks:
      - id: gitleaks

  # Conventional commits
  - repo: https://github.com/compilerla/conventional-pre-commit
    rev: v3.4.0
    hooks:
      - id: conventional-pre-commit
        stages: [commit-msg]

  # Go-specific
  - repo: https://github.com/golangci/golangci-lint
    rev: v1.61.0
    hooks:
      - id: golangci-lint

  # JavaScript/TypeScript (if applicable)
  - repo: https://github.com/pre-commit/mirrors-eslint
    rev: v9.11.1
    hooks:
      - id: eslint
        files: \.[jt]sx?$

  # Python (if applicable)
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.6.9
    hooks:
      - id: ruff
      - id: ruff-format

Installation:

# Install pre-commit
pip install pre-commit  # or: brew install pre-commit

# Install hooks in repo
pre-commit install
pre-commit install --hook-type commit-msg

# Run on all files (first time)
pre-commit run --all-files

Enforcement Rules:

Dependency Scanning

Purpose: Automatically detect and update vulnerable or outdated dependencies.

Dependabot Configuration

Location: .github/dependabot.yml

version: 2
updates:
  # Go dependencies
  - package-ecosystem: "gomod"
    directory: "/"
    schedule:
      interval: "weekly"
      day: "monday"
    open-pull-requests-limit: 10
    commit-message:
      prefix: "chore(deps):"
    labels:
      - "dependencies"
      - "go"

  # GitHub Actions
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    commit-message:
      prefix: "chore(ci):"
    labels:
      - "dependencies"
      - "ci"

  # Docker (if applicable)
  - package-ecosystem: "docker"
    directory: "/"
    schedule:
      interval: "weekly"
    commit-message:
      prefix: "chore(docker):"

Renovate Alternative

Location: renovate.json

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "config:recommended",
    ":semanticCommits",
    ":preserveSemverRanges",
    "group:allNonMajor"
  ],
  "labels": ["dependencies"],
  "vulnerabilityAlerts": {
    "enabled": true,
    "labels": ["security"]
  },
  "packageRules": [
    {
      "matchUpdateTypes": ["major"],
      "labels": ["major-update"]
    }
  ]
}

Enforcement Rules:

SBOM (Software Bill of Materials)

Purpose: Document all dependencies for supply chain security and compliance.

Required for: All production services and public releases.

Generation Methods:

SBOM in Release Process:

# Generate SBOM with syft
syft . -o spdx-json=sbom.spdx.json

# Generate SBOM with cyclonedx-gomod
cyclonedx-gomod mod -output sbom.xml

# Include in release artifacts
gh release upload v1.2.3 sbom.spdx.json

SBOM Requirements:

Enforcement Rules:

OpenSSF Best Practices

Purpose: Demonstrate security posture through the OpenSSF Best Practices program.

Badge Levels:

Key Criteria:

Getting Started:

1. Go to bestpractices.dev
2. Sign in with GitHub
3. Add your project
4. Complete the questionnaire
5. Add badge to README

Enforcement Rules:

.gitignore Requirements

Universal (All Projects):

# Agent artifacts
docs/.claude/

# Environment & secrets
.env
.env.*
!.env.example
*.pem
*.key

# IDE & editors
.idea/
.vscode/
*.swp
*.swo
*~

# OS artifacts
.DS_Store
Thumbs.db

# Build outputs
dist/
build/
out/

Go-Specific:

# Binaries
*.exe
*.exe~
*.dll
*.so
*.dylib

# Test artifacts
*.test
*.out
coverage.html
coverage.txt

# Build
bin/

Enforcement Rules:

Review Mode Checklist

When reviewing a repository, check:

Critical (Block)

• Repository name follows [domain]-[type] pattern
• No secrets in codebase or git history
• LICENSE file exists and matches project type
• README.md exists with required sections
• CHANGELOG.md exists with proper format
• .gitignore exists with required patterns
• .gitleaks.toml or CI gitleaks configured
• docs/.claude/ is gitignored
• No agent artifacts in repo root
• SECURITY.md exists (public repos)
• CODEOWNERS file exists
• Main branch has protection enabled

Required (Block)

• .env patterns gitignored
• Service repos use AGPL-3.0
• CI workflow exists with tests
• Gitleaks enabled in CI
• Vulnerability alerts enabled

Style (Warn)

• Directory structure matches language conventions
• Branch naming follows conventions
• README has all recommended sections
• Required badges present (Build, License, Gitleaks, OpenSSF)
• CONTRIBUTING.md exists (public repos)
• Issue and PR templates exist
• ADR directory exists (docs/adr/)
• Pre-commit hooks configured
• Dependabot or Renovate configured
• SBOM generation in release workflow
• OpenSSF Best Practices badge

Generate Mode

When creating a new repository:

Phase 1: Core Setup

1. Validate repository name against naming rules
2. Determine project type (Go service, Go lib, generic, monorepo, polyglot)
3. Determine license (Apache-2.0 for libs, AGPL-3.0 for services)
4. Create directory structure from templates
5. Generate README.md with badges (Build, License, Gitleaks, OpenSSF placeholder)
6. Generate CHANGELOG.md with Unreleased section
7. Generate appropriate LICENSE file
8. Generate .gitignore for language

Phase 2: Security Configuration

9. Generate .gitleaks.toml
10. Generate SECURITY.md (public repos)
11. Generate CODEOWNERS file
12. Generate .pre-commit-config.yaml
13. Generate .github/dependabot.yml

Phase 3: CI/CD Setup

14. Generate .github/workflows/ci.yml (test, lint, security)
15. Generate .github/workflows/security.yml (CodeQL, Trivy)
16. Generate .github/workflows/release.yml (with SBOM generation)

Phase 4: Documentation

17. Generate CONTRIBUTING.md (public repos)
18. Generate .github/ISSUE_TEMPLATE/bug_report.md
19. Generate .github/ISSUE_TEMPLATE/feature_request.md
20. Generate .github/PULL_REQUEST_TEMPLATE.md
21. Create docs/adr/ directory

Phase 5: Initialization

22. Initialize git with main branch
23. Create initial commit: chore: initial repository setup
24. Configure branch protection (if GitHub CLI available)
25. Output next steps for manual configuration (OpenSSF badge, etc.)

Use templates from ${CLAUDE_PLUGIN_ROOT}/skills/git-repo-standards/templates/

Monorepo-Specific Steps

For monorepo projects, additionally:

• Generate workspace configuration (nx.json, turbo.json, go.work, or lerna.json)
• Create apps/ and packages/ directories
• Generate per-package CHANGELOG files if using independent versioning
• Configure CI matrix for affected packages only

Polyglot-Specific Steps

For multi-language projects, additionally:

• Create language-specific subdirectories (backend/, frontend/)
• Generate Makefile with unified commands
• Generate docker-compose.yml for local development
• Configure CI to run language-specific tests in parallel

Converted and distributed by TomeVault — claim your Tome and manage your conversions.