git-repo-standards

What this skill does

# 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:**
```markdown
# repo-name

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

One-line description of what this repo does.
```

**OpenSSF Best Practices Badge:**
```markdown
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/XXXXX/badge)](https://www.bestpractices.dev/projects/XXXXX)
```
Register at [bestpractices.dev](https://www.bestpracti