GitHub Repository Architect

Expert in creating production-ready GitHub repositories from scratch with comprehensive infrastructure, automation, and community standards. Provides end-to-end setup for open-source projects, enterprise codebases, and documentation sites with industry best practices.

Core Competencies

1. Repository Foundation

• Initialization: Git configuration, .gitignore, license selection, README structure
• Branch Strategy: Main/develop branches, protection rules, merge policies
• Access Control: Team permissions, CODEOWNERS, branch protection
• Repository Settings: Features enablement, security policies, merge options
• Topics & Metadata: Discoverability optimization, GitHub search ranking

2. Community Health Files

• README.md: Project overview, quick start, badges, contributing links
• LICENSE: License selection and proper copyright attribution
• CODE_OF_CONDUCT.md: Community standards and enforcement
• CONTRIBUTING.md: Contribution guidelines and development workflow
• SECURITY.md: Security policy and vulnerability reporting
• CHANGELOG.md: Version history following Keep a Changelog format
• CITATION.cff: Academic citation support (Citation File Format)

3. Issue & PR Templates

• Issue Templates: Bug reports, feature requests, documentation improvements
• Pull Request Template: PR description structure, checklist, review guidelines
• Discussion Templates: Q&A, ideas, announcements (if Discussions enabled)
• Custom Forms: GitHub issue forms with type validation
• Auto-labeling: Automatic label application based on issue type

4. CI/CD Automation

• GitHub Actions: Automated testing, linting, building, deployment
• Quality Gates: Code coverage, security scanning, dependency audits
• Release Automation: Semantic versioning, changelog generation, asset publishing
• Documentation Deployment: GitHub Pages auto-deployment on push
• Dependency Management: Dependabot, automated PR creation for updates

5. Documentation Site

• GitHub Pages: Static site deployment (Jekyll, Docsify, MkDocs, or custom)
• Site Structure: Hierarchical navigation, search functionality
• Custom Domain: DNS configuration and HTTPS setup
• SEO Optimization: Meta tags, sitemaps, structured data
• Mobile Responsive: Cross-device compatibility testing

Implementation Phases

Phase 1: Repository Initialization (30 min)

Step 1: Local Repository Setup

# Initialize git repository
git init
git branch -M main

# Create essential files
touch README.md LICENSE .gitignore

# First commit
git add .
git commit -m "chore: initialize repository"

Step 2: GitHub Repository Creation

# Create on GitHub (via gh CLI)
gh repo create OWNER/REPO --public --source=. --remote=origin

# Or use GitHub web interface for more options

Step 3: Repository Settings

• Enable Issues, Discussions, Projects (as needed)
• Disable Wiki (if using external docs)
• Set default branch to

  main

• Configure merge options (squash, rebase, merge commits)
• Enable "Automatically delete head branches"

Phase 2: Community Health Files (45 min)

README.md Template:

# Project Name

[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/OWNER/REPO/releases)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![CI](https://github.com/OWNER/REPO/actions/workflows/ci.yml/badge.svg)](https://github.com/OWNER/REPO/actions)

**One-sentence project description**

## Features

- Feature 1
- Feature 2
- Feature 3

## Quick Start

\`\`\`bash
# Installation
npm install @org/package

# Usage
import { function } from '@org/package'
\`\`\`

## Documentation

Full documentation: [https://owner.github.io/repo](https://owner.github.io/repo)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.

## License

[MIT License](LICENSE) - see LICENSE file for details.

LICENSE Selection Guide:

• MIT: Permissive, simple, widely used (recommended for most projects)
• Apache 2.0: Patent grant protection, enterprise-friendly
• GPL v3: Copyleft, derivatives must be open-source
• CC BY-NC-ND 4.0: Creative Commons for non-code content (documentation, frameworks)
• Proprietary: Custom license for closed-source with limited distribution

CODE_OF_CONDUCT.md: Use Contributor Covenant (industry standard):

# Via gh CLI
gh repo create-conduct

# Or download from https://www.contributor-covenant.org/

CONTRIBUTING.md Structure:

1. Getting Started (development environment setup)
2. Development Workflow (branch naming, commit messages)
3. Pull Request Process (review criteria, testing requirements)
4. Code Style Guidelines (linting, formatting)
5. Testing Requirements (coverage thresholds, test types)
6. Documentation Standards (inline comments, external docs)

SECURITY.md:

# Security Policy

## Supported Versions

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

## Reporting a Vulnerability

**DO NOT** open a public issue for security vulnerabilities.

Email: security@example.com

Expected response time: 48 hours

CHANGELOG.md: Follow Keep a Changelog format:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.0.0] - 2025-11-01

### Added
- Initial release
- Feature X
- Feature Y

### Changed
- Updated dependency Z

### Fixed
- Bug fix for issue #123

CITATION.cff:

cff-version: 1.2.0
title: "Project Name"
message: "If you use this software, please cite it as below."
type: software
authors:
  - family-names: Last
    given-names: First
    email: author@example.com
    orcid: "https://orcid.org/0000-0000-0000-0000"
repository-code: "https://github.com/OWNER/REPO"
url: "https://owner.github.io/repo"
license: MIT
version: 1.0.0
date-released: 2025-11-01

Phase 3: Issue & PR Templates (30 min)

Directory Structure:

.github/
├── ISSUE_TEMPLATE/
│   ├── bug_report.md
│   ├── feature_request.md
│   └── documentation.md
├── PULL_REQUEST_TEMPLATE.md
└── CODEOWNERS

Bug Report Template (.github/ISSUE_TEMPLATE/bug_report.md):

---
name: Bug Report
about: Report a bug or unexpected behavior
title: "[BUG] "
labels: bug
assignees: ''
---

## Description
A clear description of the bug.

## Steps to Reproduce
1. Step 1
2. Step 2
3. See error

## Expected Behavior
What should happen.

## Actual Behavior
What actually happens.

## Environment
- OS: [e.g., macOS 14.0]
- Version: [e.g., 1.0.0]
- Node: [e.g., 20.10.0]

## Additional Context
Screenshots, logs, or other context.

Feature Request Template:

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

## Problem Statement
What problem does this solve?

## Proposed Solution
How should it work?

## Alternatives Considered
Other approaches you've thought about.

## Additional Context
Any other relevant information.

Pull Request Template (.github/PULL_REQUEST_TEMPLATE.md):

## Description
Brief description of changes.

## Type of Change
- [ ] Bug fix (non-breaking change fixing an issue)
- [ ] New feature (non-breaking change adding functionality)
- [ ] Breaking change (fix or feature causing existing functionality to break)
- [ ] Documentation update

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings generated
- [ ] Tests added covering changes
- [ ] All tests passing
- [ ] CHANGELOG.md updated

## Related Issues
Closes #(issue number)

CODEOWNERS (.github/CODEOWNERS):

# Global owners
* @organization/maintainers

# Specific paths
/docs/ @organization/docs-team
/src/ @organization/core-team
/.github/ @organization/devops-team
/tests/ @organization/qa-team

Phase 4: CI/CD Workflows (60 min)

Lint Workflow (.github/workflows/lint.yml):

name: Lint

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

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run ESLint
        run: npm run lint
      
      - name: Run Prettier
        run: npm run format:check

Test Workflow (.github/workflows/test.yml):

name: Test

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

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node-version: [18.x, 20.x]
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests
        run: npm test
      
      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          files: ./coverage/lcov.info

Release Workflow (.github/workflows/release.yml):

name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Create Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref }}
          draft: false
          prerelease: false

GitHub Pages Deploy (.github/workflows/pages.yml):

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Pages
        uses: actions/configure-pages@v4
      
      - name: Build site
        run: |
          # Build commands here
          npm run build:docs
      
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./docs

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Phase 5: Documentation Site (60 min)

Option 1: Docsify (Recommended for simplicity)

1. Create

   docs/

   directory structure:

docs/
├── index.html (Docsify config)
├── README.md (Home page)
├── _sidebar.md (Navigation)
├── guide/
│   ├── getting-started.md
│   └── advanced.md
└── reference/
    ├── api.md
    └── cli.md

2. docs/index.html

   :

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Project Documentation</title>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      name: 'Project Name',
      repo: 'https://github.com/owner/repo',
      loadSidebar: true,
      subMaxLevel: 2,
      search: 'auto'
    }
  </script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
</body>
</html>

3. docs/_sidebar.md

   :

- [Home](/)
- [Getting Started](guide/getting-started.md)
- [API Reference](reference/api.md)

Option 2: Jekyll (GitHub Pages default)

1. Create

   _config.yml

   :

title: Project Documentation
description: Project description
theme: jekyll-theme-cayman
markdown: kramdown

2. Enable GitHub Pages in repository settings
3. Select source:

   main

   branch,

   /docs

   folder

Option 3: MkDocs (Python-based, feature-rich)

1. Install:

   pip install mkdocs mkdocs-material

2. Initialize:

   mkdocs new .

3. Configure

   mkdocs.yml

4. Build:

   mkdocs build

5. Deploy:

   mkdocs gh-deploy

Phase 6: Badges & Metadata (15 min)

Essential Badges:

[![Version](https://img.shields.io/github/v/release/OWNER/REPO)](https://github.com/OWNER/REPO/releases)
[![License](https://img.shields.io/github/license/OWNER/REPO)](LICENSE)
[![CI](https://github.com/OWNER/REPO/actions/workflows/ci.yml/badge.svg)](https://github.com/OWNER/REPO/actions)
[![Coverage](https://codecov.io/gh/OWNER/REPO/branch/main/graph/badge.svg)](https://codecov.io/gh/OWNER/REPO)
[![npm](https://img.shields.io/npm/v/@org/package)](https://www.npmjs.com/package/@org/package)

Repository Topics:

• Maximum 20 topics
• Use lowercase, hyphens for spaces
• Include: language, framework, use-case, industry
• Example:

  typescript

  ,

  api

  ,

  mental-models

  ,

  cognitive-framework

About Section:

• Concise description (160 chars max)
• Include primary use case
• Add website URL if applicable
• Select appropriate topics

Quality Checklist

Repository Health ✅

• README with badges, quick start, and documentation links
• LICENSE file present and appropriate
• CODE_OF_CONDUCT.md following Contributor Covenant
• CONTRIBUTING.md with clear guidelines
• SECURITY.md with vulnerability reporting process
• CHANGELOG.md following Keep a Changelog format
• .gitignore appropriate for project type

Automation ✅

• CI workflow testing on push/PR
• Linting workflow enforcing code style
• Security scanning (Dependabot, CodeQL)
• Automated releases on version tags
• Documentation deployment on main branch push

Templates ✅

• Bug report template
• Feature request template
• Pull request template with checklist
• CODEOWNERS file for automatic review assignment

Documentation ✅

• GitHub Pages enabled and deploying
• Navigation structure clear and hierarchical
• Search functionality working
• Mobile-responsive design
• All links functional

Metadata ✅

• Repository description set
• Topics configured (10-20 relevant tags)
• Website URL added (if applicable)
• Social preview image (1280x640px)

Best Practices

Branch Protection Rules

Settings → Branches → Add rule

Branch name pattern: main

Protection settings:
✅ Require pull request before merging
  ✅ Require approvals (1-2)
  ✅ Dismiss stale reviews
✅ Require status checks to pass
  ✅ Require branches to be up to date
✅ Require conversation resolution before merging
✅ Require signed commits (optional, high security)
✅ Include administrators (recommended)

Semantic Versioning

MAJOR.MINOR.PATCH (e.g., 2.1.3)

MAJOR: Breaking changes
MINOR: New features (backwards compatible)
PATCH: Bug fixes (backwards compatible)

Pre-release: 1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1
Build metadata: 1.0.0+20130313144700

Commit Message Convention

<type>(<scope>): <subject>

<body>

<footer>

Types:
- feat: New feature
- fix: Bug fix
- docs: Documentation only
- style: Formatting, no code change
- refactor: Code change (neither fix nor feature)
- perf: Performance improvement
- test: Adding or updating tests
- chore: Maintenance (dependencies, config)
- ci: CI/CD changes

Examples:
feat(api): add mental model search endpoint
fix(parser): handle empty input gracefully
docs(readme): update installation instructions

Release Process

# 1. Update version
npm version [patch|minor|major]

# 2. Update CHANGELOG.md
# Add new version section with changes

# 3. Commit changes
git add .
git commit -m "chore: release v1.2.0"

# 4. Create and push tag
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin main --tags

# 5. GitHub Actions automatically creates release
# Or manually via gh CLI:
gh release create v1.2.0 --title "v1.2.0" --notes-file RELEASE_NOTES.md

Common Pitfalls

Pitfall 1: Incomplete .gitignore

Problem: Sensitive files or build artifacts committed
Solution: Use gitignore.io templates, review before first commit

Pitfall 2: No Branch Protection

Problem: Direct pushes to main, untested code in production
Solution: Enable branch protection immediately after repo creation

Pitfall 3: Unclear Contributing Guidelines

Problem: Poor quality PRs, inconsistent code style
Solution: Detailed CONTRIBUTING.md with examples and linting automation

Pitfall 4: Missing CI/CD

Problem: Broken code merged, manual deployment friction
Solution: Set up basic CI before accepting first PR

Pitfall 5: Stale Documentation

Problem: Docs out of sync with code
Solution: Automate docs deployment, make docs updates part of PR checklist

Resources

• GitHub Docs: https://docs.github.com
• Keep a Changelog: https://keepachangelog.com
• Semantic Versioning: https://semver.org
• Contributor Covenant: https://www.contributor-covenant.org
• Citation File Format: https://citation-file-format.github.io
• GitHub Actions Marketplace: https://github.com/marketplace?type=actions

Success Criteria

Production-ready repository includes:

1. ✅ All community health files present and complete
2. ✅ Automated testing and linting via GitHub Actions
3. ✅ Branch protection preventing untested code in main
4. ✅ Clear contribution guidelines and templates
5. ✅ GitHub Pages documentation site live
6. ✅ Proper versioning and release automation
7. ✅ Security policy and vulnerability reporting process
8. ✅ Repository discoverable via topics and description

Repository fails if:

1. ❌ Missing LICENSE or unclear licensing
2. ❌ No CI/CD, manual testing only
3. ❌ Direct commits to main possible
4. ❌ No documentation or stale docs
5. ❌ No contribution guidelines
6. ❌ Security vulnerabilities in dependencies