Git Repository Standards

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

Modes of Operation

Mode	Trigger	Action
Review	"review repo standards", "audit repository"	Analyze repo against standards, produce compliance report
Generate	"create new repo", "scaffold repository"	Create new repo with correct structure from scratch
Enforce	Automatic via hooks	Block critical violations, warn on style issues

Enforcement Tiers

Tier	Action	Violations
Critical	Block	Secrets detected, missing LICENSE/README/CHANGELOG/.gitignore, gitleaks not configured, agent artifacts in repo root, invalid repo naming, missing SECURITY.md (public repos)
Required	Block	`.env` not gitignored, `docs/.claude/` not gitignored, service repo missing AGPL-3.0, missing CODEOWNERS, no branch protection on main
Style	Warn	Incomplete README sections, non-conventional commits, missing badges, suboptimal structure, outdated copyright year, missing CONTRIBUTING.md, no OpenSSF badge

Repository Naming

Format: lowercase-kebab-case

Pattern: [domain]-[type]

Component	Required	Examples
`domain`	Required	`marketplace`, `auth`, `billing`, `plugin-registry`
`type`	Optional	`-api`, `-cli`, `-lib`, `-service`, `-worker`

Valid Examples:

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

Blocked Patterns:

Pattern	Reason
`CamelCase`, `snake_case`	Inconsistent, URL issues
`my-project-v2`	No versions in names
`johns-cool-thing`	No personal names
`backend`, `service`	Too generic
Spaces, special chars	URL/CLI incompatible

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:

Tool	Config File	Language	Best For
Nx	`nx.json`	JS/TS, Go, Rust	Large teams, enterprise
Turborepo	`turbo.json`	JS/TS	Frontend-heavy projects
Lerna	`lerna.json`	JS/TS	Publishing multiple packages
Go Workspaces	`go.work`	Go	Multi-module Go projects

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

Pattern	Action	Reason
`/src` in Go project	Warn	Java convention, not Go
`TODO.md`, `PLAN.md` in root	Block	Agent artifacts must go to `docs/.claude/`
`.task`, `.orchestration` in root	Block	Agent artifacts must go to `docs/.claude/`
Missing `internal/` for 3+ packages	Warn	Exposes private APIs
Deep nesting (>3 levels)	Warn	Go prefers shallow hierarchies
Mixing app code with infra	Warn	Separate concerns (apps/, packages/, deployments/)
No workspace file in monorepo	Warn	Use go.work, nx.json, or turbo.json
Language-specific files in root of polyglot	Warn	Group by language in subdirectories

README Requirements

Required Sections (Block if missing)

Section	Purpose
Title + Description	One-line summary of what this repo does
Installation	How to install/build
Usage	Basic usage examples
License	License type (link to LICENSE file)

Required Badges

Badge	Purpose
Build/CI Status	Shows pipeline health
Go Version	Min Go version (Go projects only)
License	License type
Gitleaks	Security scanning enabled
OpenSSF Best Practices	Security posture (recommended for public repos)
Dependency Status	Shows if dependencies are up-to-date

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)

Recommended Sections (Warn if missing)

Section	Purpose
Prerequisites	Required tools, versions, dependencies
Configuration	Environment variables, config files
Development	How to set up local dev environment
Testing	How to run tests
Contributing	Link to CONTRIBUTING.md
Security	Link to SECURITY.md for reporting vulnerabilities

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:

Rule	Action
CHANGELOG.md missing	Block
No `[Unreleased]` section	Warn
Tagged release without CHANGELOG entry	Block
Entry missing category	Warn

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

Licensing

Project Type	License	Indicators
Libraries, CLIs, tools	Apache-2.0	`-lib`, `-cli`, `*-sdk`, pkg-only repos
Services, platforms, APIs	AGPL-3.0	`-service`, `-api`, `-server`, `-worker`, has `cmd/`
Internal/proprietary	Proprietary	Private repos, no LICENSE file

Alternative Licenses (Supported but Flagged):

License	Acceptable For	Flag Level
MIT	Libraries, small utilities	Warn - prefer Apache-2.0 for patent protection
BSD-3-Clause	Libraries	Warn - prefer Apache-2.0 for patent protection
ISC	Minimal packages	Warn - prefer Apache-2.0
GPL-3.0	Libraries that must stay copyleft	Warn - consider AGPL-3.0 for network use

Enforcement Rules:

Rule	Action
LICENSE missing (public repo)	Block
Service repo with MIT/BSD/Apache-2.0	Warn - services should use AGPL-3.0 to ensure network use triggers copyleft
Library repo with AGPL-3.0	Warn - may limit adoption
MIT/BSD instead of Apache-2.0	Warn - Apache-2.0 provides patent protection

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:

Rule	Action
SECURITY.md missing (public repo)	Block
No contact method for reporting	Warn
No supported versions table	Warn

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:

Rule	Action
CODEOWNERS missing	Block
No default owner (`*`)	Warn
Security files without security team	Warn

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:

Rule	Action
CONTRIBUTING.md missing (public repo)	Warn
No development setup instructions	Warn
No commit message guidelines	Warn

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:

Rule	Action
No issue templates	Warn
No PR template	Warn
Missing required fields in templates	Warn

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:

Rule	Action
`docs/adr/` directory missing	Warn
ADR without status field	Warn
Major architectural change without ADR	Warn

Branching Strategy

Model: GitHub Flow (trunk-based)

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

Branch Naming Pattern: [type]/[description]

Type	Purpose	Example
`feature/`	New functionality	`feature/plugin-search`
`fix/`	Bug fixes	`fix/123-auth-timeout`
`chore/`	Maintenance, deps	`chore/update-deps`
`docs/`	Documentation only	`docs/api-reference`
`refactor/`	Code restructuring	`refactor/auth-module`
`release/`	Release prep	`release/1.2.0`

Blocked Patterns:

Pattern	Reason
Direct push to `main`	Must use PR
`john/thing`, `wip/stuff`	No personal/vague names
`FEATURE/CAPS`	Lowercase only
`feature_underscore`	Use hyphens
Branch name > 50 chars	Too long

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:

Tier	Settings	Repos
Standard	1 approval, CI required, gitleaks	All repos
Enhanced	2 approvals, CODEOWNERS, linear history	Production services
Critical	3 approvals, security team review, signed commits	Security-sensitive

Enforcement Rules:

Rule	Action
No branch protection on main	Block
Allows force push to main	Block
No required status checks	Warn
CODEOWNERS review not required	Warn

Commit Conventions

Format: Conventional Commits

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

[optional body]

[optional footer(s)]

Commit Types:

Type	Purpose	CHANGELOG Category
`feat`	New feature	Added
`fix`	Bug fix	Fixed
`docs`	Documentation only	-
`style`	Formatting, no code change	-
`refactor`	Code restructuring	Changed
`perf`	Performance improvement	Changed
`test`	Adding/updating tests	-
`chore`	Maintenance, deps, CI	-
`build`	Build system changes	-
`ci`	CI/CD changes	-
`revert`	Revert previous commit	Removed

Breaking Changes:

feat(api)!: remove deprecated endpoints

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

Enforcement Rules:

Rule	Action
No type prefix	Warn
Type not in allowed list	Warn
Description > 72 chars	Warn
Description starts with capital	Warn
Description ends with period	Warn

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

Method	File
Config file	`.gitleaks.toml`
CI workflow	`.github/workflows/*` with gitleaks action
Pre-commit hook	`.pre-commit-config.yaml` with gitleaks

Minimum .gitleaks.toml:

[extend]
useDefault = true

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

Enforcement Rules:

Rule	Action
No gitleaks config or CI job	Block
Secrets detected in commit	Block
Secrets in git history	Block PR + require history rewrite
`.env` files not in .gitignore	Block
Hardcoded API keys/tokens	Block

Remediation on Detection:

Remove secret from code
Rotate the exposed credential immediately
Use git filter-branch or BFG to purge from history
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:

Rule	Action
No CI workflow	Block
No gitleaks in CI	Block
No dependency review	Warn
No CodeQL/security scanning	Warn
No SBOM generation for releases	Warn

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:

Rule	Action
No `.pre-commit-config.yaml`	Warn
Missing gitleaks hook	Warn
Missing conventional-pre-commit	Warn
Missing language-specific linter	Warn

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:

Rule	Action
No Dependabot or Renovate config	Warn
Vulnerability alerts disabled	Block
Major updates not labeled	Warn
No GitHub Actions updates configured	Warn

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:

Tool	Format	Best For
`syft`	SPDX, CycloneDX	General purpose, multi-language
`cyclonedx-gomod`	CycloneDX	Go projects
`trivy`	SPDX, CycloneDX	Container images
`anchore/sbom-action`	SPDX	GitHub Actions integration

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:

Requirement	Purpose
Include in all releases	Supply chain transparency
Use standardized format (SPDX or CycloneDX)	Interoperability
Sign SBOM with release signing key	Integrity verification
Store in release artifacts	Accessibility

Enforcement Rules:

Rule	Action
Release without SBOM (production service)	Warn
Non-standard SBOM format	Warn
SBOM not included in release artifacts	Warn

OpenSSF Best Practices

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

Badge Levels:

Level	Requirements	Recommended For
Passing	Basic security practices	All public repos
Silver	Enhanced security, signed releases	Production services
Gold	Comprehensive security program	Critical infrastructure

Key Criteria:

Category	Requirements
Basics	README, LICENSE, CHANGELOG, issue tracker
Change Control	Version control, unique versioning, release notes
Reporting	Security contact, vulnerability process
Quality	Test suite, CI, static analysis
Security	Hardening, crypto, vulnerability response

Getting Started:

Go to bestpractices.dev
Sign in with GitHub
Add your project
Complete the questionnaire
Add badge to README

Enforcement Rules:

Rule	Action
Public repo without OpenSSF badge	Warn
OpenSSF score below passing	Warn
Production service without Silver level	Warn

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

Rule	Action
.gitignore missing	Block
`docs/.claude/` not ignored	Block
`.env` not ignored	Block
IDE folders not ignored	Warn
OS artifacts not ignored	Warn

Review Mode Checklist

When reviewing a repository, check:

Critical (Block)

Required (Block)

Style (Warn)

Generate Mode

When creating a new repository:

Phase 1: Core Setup

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

Phase 2: Security Configuration

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

Phase 3: CI/CD Setup

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

Phase 4: Documentation

Generate CONTRIBUTING.md (public repos)
Generate .github/ISSUE_TEMPLATE/bug_report.md
Generate .github/ISSUE_TEMPLATE/feature_request.md
Generate .github/PULL_REQUEST_TEMPLATE.md
Create docs/adr/ directory

Phase 5: Initialization

Initialize git with main branch
Create initial commit: chore: initial repository setup
Configure branch protection (if GitHub CLI available)
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

git-repo-standards

Git Repository Standards

Modes of Operation

Enforcement Tiers

Repository Naming

Directory Structure

Go Projects

Generic/Non-Go Projects

Monorepo Structure

Multi-Language (Polyglot) Structure

Anti-Patterns

README Requirements

Required Sections (Block if missing)

Required Badges

Recommended Sections (Warn if missing)

CHANGELOG Requirements

Licensing

SECURITY.md Requirements

CODEOWNERS Requirements

CONTRIBUTING.md Requirements

Issue and PR Templates

Issue Templates

Pull Request Template

ADR (Architecture Decision Records)

Branching Strategy

Branch Protection Configuration

Commit Conventions

Gitleaks & Security

GitHub Actions Workflow Templates

CI Workflow (ci.yml)

Security Scanning (security.yml)

Release with SBOM (release.yml)

Pre-commit Hooks

Dependency Scanning

Dependabot Configuration

Renovate Alternative

SBOM (Software Bill of Materials)

OpenSSF Best Practices

.gitignore Requirements

Review Mode Checklist

Critical (Block)

Required (Block)

Style (Warn)

Generate Mode

Phase 1: Core Setup

Phase 2: Security Configuration

Phase 3: CI/CD Setup

Phase 4: Documentation

Phase 5: Initialization

Monorepo-Specific Steps

Polyglot-Specific Steps

CI Workflow (`ci.yml`)

Security Scanning (`security.yml`)

Release with SBOM (`release.yml`)