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

bash

# 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

bash

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

markdown

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

bash

# Via gh CLI
gh repo create-conduct

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

CONTRIBUTING.md Structure:

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

SECURITY.md:

markdown

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

markdown

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

yaml

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

markdown

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

markdown

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

markdown

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

yaml

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

yaml

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

yaml

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

yaml

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)

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

```
docs/index.html
```
:

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>

```
docs/_sidebar.md
```
:

markdown

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

Option 2: Jekyll (GitHub Pages default)

Create
```
_config.yml
```
:

yaml

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

Enable GitHub Pages in repository settings
Select source:
```
main
```
branch,
```
/docs
```
folder

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

Install:
```
pip install mkdocs mkdocs-material
```
Initialize:
```
mkdocs new .
```
Configure
```
mkdocs.yml
```
Build:
```
mkdocs build
```
Deploy:
```
mkdocs gh-deploy
```

Phase 6: Badges & Metadata (15 min)

Essential Badges:

markdown

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

bash

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

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

Repository fails if:

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

github-repository-architect

NPX Install

Tags

SKILL.md Content

GitHub Repository Architect

Core Competencies

1. Repository Foundation

2. Community Health Files

3. Issue & PR Templates

4. CI/CD Automation

5. Documentation Site

Implementation Phases

Phase 1: Repository Initialization (30 min)

Phase 2: Community Health Files (45 min)

Phase 3: Issue & PR Templates (30 min)

Phase 4: CI/CD Workflows (60 min)

Phase 5: Documentation Site (60 min)

Phase 6: Badges & Metadata (15 min)

Quality Checklist

Repository Health ✅

Automation ✅

Templates ✅

Documentation ✅

Metadata ✅

Best Practices

Branch Protection Rules

Semantic Versioning

Commit Message Convention

Release Process

Common Pitfalls

Pitfall 1: Incomplete .gitignore

Pitfall 2: No Branch Protection

Pitfall 3: Unclear Contributing Guidelines

Pitfall 4: Missing CI/CD

Pitfall 5: Stale Documentation

Resources

Success Criteria