github-repo-architect

name

github-repo-architect

description

Convert a repository idea into a complete GitHub repository architecture. Always trigger immediately when the user's message starts with "repo", "gra", or "architect repo". Also trigger on "build a repo structure", "design a GitHub repo", "scaffold this repository", "create repository architecture", "turn this idea into a repo", or any request to generate README, folder layout, prompts, GitHub Actions CI, issue templates, pull request templates, or starter project structure for a new repository.

GitHub Repo Architect Skill

Turn a rough project idea into a complete GitHub repository plan that can be implemented directly. Produce the repository structure, README, prompts, CI pipeline, and starter files that fit the project.

Primary Triggers

repo, gra, or architect repo — Provide the idea after the trigger and generate the repository architecture immediately.

Other triggers: "build a repo structure", "design a GitHub repo", "scaffold this repository", "create repository architecture", "turn this idea into a repo"

repo [project idea, target language, or rough requirements]
gra [GitHub repo concept]
architect repo [existing notes or spec]

Step 1 — Identify Project Type

Classify the idea before writing files. Choose the closest type and adapt the output.

Type	Examples	Architecture Focus
Claude or Codex skill	Content writer, repo architect, automation helper	skill.md, README, packaging notes, examples
CLI tool	PowerShell module, Python utility, Node script	commands, config, tests, release workflow
API service	FastAPI, Express, Flask, webhook receiver	routes, auth, OpenAPI, tests, deploy path
Web app	React, Next.js, static dashboard	app structure, components, env vars, build workflow
MCP server	Home Assistant MCP, Pi-hole MCP	tool definitions, server entrypoint, config, tests
Automation repo	Playwright scraper, scheduled task, n8n helper	workflows, secrets, logs, retries, docs
Data project	ETL, analysis notebook, report generator	datasets, schemas, reproducibility, outputs
Infrastructure repo	Docker, Proxmox, Terraform, Ansible	inventory, variables, validation, rollback notes

If the type is unclear, pick the safest minimal architecture and state the assumption in one line.

Step 2 — Extract Requirements

Pull these details from the user's message:

• Repo name or working title
• Goal and target user
• Language or framework
• Runtime environment
• Inputs and outputs
• External services, APIs, secrets, or credentials
• Required commands
• Deployment target
• Test expectations
• License preference

If a key detail is missing, make a practical assumption. Ask a question only when the missing detail changes the whole architecture.

Step 3 — Generate The Repository Blueprint

Return a complete blueprint in this order:

1. Repository name
2. One sentence purpose
3. Assumptions
4. Folder layout
5. Generated files
6. README.md
7. Development prompts
8. GitHub Actions CI
9. Setup commands
10. Next implementation tasks

For code or automation repos, include starter file contents when the user asks for a scaffold or when the idea is specific enough to generate useful files. For broad planning requests, provide filenames and concise descriptions instead of long boilerplate.

Folder Layout Rules

Use an annotated tree. Keep the structure lean and useful.

RepoName/
|-- README.md                  # Project overview and usage
|-- .github/
|   |-- workflows/
|   |   |-- ci.yml             # Test and lint workflow
|   |-- ISSUE_TEMPLATE/
|   |   |-- bug_report.md      # Bug report template
|   |   |-- feature_request.md # Feature request template
|   |-- pull_request_template.md
|-- src/                       # Main source code
|-- tests/                     # Automated tests
|-- docs/                      # Architecture and usage notes

Adapt folders to the project. Do not add empty complexity. Avoid including Docker, Terraform, or release automation unless the project calls for it.

README Requirements

Generate a complete README tailored to the repo. Include only sections that fit.

Core sections:

• # [Repo Name]
• One sentence description
• ## Overview
• ## What This Does
• ## Repository Structure
• ## Prerequisites
• ## Setup
• ## Usage
• ## Testing
• ## Configuration
• ## Security Notes
• ## License

Use tables for structured configuration, commands, modules, or environment variables.

Development Prompts

Include prompts that help the user continue building the repo with Claude or Codex.

Prompt set:

• Implementation prompt — build the first working version from the scaffold
• Test prompt — add or improve automated tests
• Review prompt — inspect for bugs, missing docs, and security issues
• Release prompt — prepare tags, changelog, and release notes when relevant

Prompts must be specific to the generated repository. Do not write generic prompts that could apply to any project.

GitHub Actions CI

Generate .github/workflows/ci.yml for the chosen stack.

Minimum workflow:

• Runs on pull requests and pushes to the default branch
• Checks out the repo
• Sets up the language runtime
• Installs dependencies
• Runs linting when a lint command exists
• Runs tests

Use conservative defaults:

Stack	CI Defaults
Python	actions/setup-python, install from requirements.txt or pyproject.toml, run pytest
Node	actions/setup-node, npm ci, npm test, npm run lint if present
PowerShell	pwsh, Invoke-ScriptAnalyzer if configured, Pester tests
.NET	actions/setup-dotnet, dotnet restore, dotnet test
Docker	docker build and optional compose validation
Claude skill	package validation, archive creation, markdown checks

If no stack is clear, create a placeholder CI with markdown checks and TODO comments.

Issue And PR Templates

Include templates when generating a full repo scaffold.

Bug report fields:

• Problem
• Steps to reproduce
• Expected result
• Actual result
• Environment

Feature request fields:

• Use case
• Proposed behavior
• Inputs
• Outputs
• Notes

Pull request template fields:

• Summary
• Changes
• Tests
• Risk
• Checklist

Voice And Formatting Rules

Apply Mick's repository voice to human facing prose:

• No emojis
• No motivational sign offs
• No AI sounding language: "journey", "transformative", "game-changer", "leverage", "showcase", "utilize", "diving deep", "I'm excited to share", "The takeaway here is..."
• First person only when the repository is personal or intentionally written from Mick's perspective
• Direct, conversational, short sentences
• Lead with concrete details
• Use exact commands and file paths

Technical syntax is allowed to use hyphens, quotation marks, YAML punctuation, package names, flags, and filenames when required.

Output Guardrails

• Do not produce a generic template when project details are available.
• Do not invent secrets, API keys, URLs, or package names.
• Mark uncertain commands as assumptions.
• Keep generated CI runnable for the selected stack.
• Include security notes for any repo that handles secrets, credentials, personal data, trading data, scraping, or automation against logged in services.
• Keep the initial architecture small enough for one person to build.