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

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

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

# repo-name

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

One-line description of what this repo does.

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

# Changelog

## [Unreleased]

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

### Changed
- Updated behavior Y

### Fixed
- Bug Z

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

# 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

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

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

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

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

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

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

# 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

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

[optional body]

[optional footer(s)]

feat(api)!: remove deprecated endpoints

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

[extend]
useDefault = true

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

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'

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'

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 }}

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

# 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

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

{
  "$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"]
    }
  ]
}

# 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

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

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

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

# Build
bin/