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

## Intent

Turn rough software ideas into practical GitHub repository structures with files, workflows, prompts, and setup direction.

## Workflow

1. Identify the exact task and available source material.
2. Apply the domain rules and output format in this skill.
3. State assumptions, uncertainty, and missing inputs clearly.
4. Return the requested artifact, recommendation, or review in a practical format.
5. Check the result against the validation checklist before finishing.

## Constraints

- Do not fabricate missing facts, measurements, dates, sources, or user context.
- Keep output aligned with Mick's direct, practical communication style unless the skill says otherwise.
- Preserve safety, legal, medical, financial, and operational boundaries stated in this file.
- Prefer concise, usable output over broad explanation.

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"

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

## Do Not Use When

- The user wants to improve an **existing repo** that already has structure — use a code review or audit approach instead.
- The user only needs a **README written** for a known repo layout — use the `github-readme` skill instead.
- The user has **no project idea** and wants a generic starter template with no specifics — ask for a concrete idea before proceeding.
- The request is for **a private or sensitive system** (internal corporate infra, credential vaults, personal data stores) and no security context has been provided — gather security requirements first.

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

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

## Validation Checklist

Run these checks before delivering any generated blueprint:

- Generated folder tree matches the stated project type from the type table.
- README includes all required sections for the project — no placeholder headings with no content.
- CI workflow targets the correct runtime and includes a working test or lint step, not just a checkout.
- Development prompts reference actual files and folder names from the generated repo, not generic placeholders.
- Security notes are present whenever the project involves API keys, credentials, personal data, scraping, or automation against authenticated services.
- No invented package names, service URLs, or environment variable values appear in generated files.
- Setup commands are runnable as written for the stated language and OS.
- Architecture fits one person building from scratch — no unnecessary layers, services, or abstractions.
- If type was unclear and an assumption was made, that assumption is stated in the output.

## Help And Examples

If the user is not sure how to use this skill, asks what it needs, or asks for examples:

- Explain in plain language what this skill can do.
- Tell the user the minimum input needed for a useful first pass.
- Show the example prompts below.
- Offer the fastest next prompt the user can send.

Minimum useful input:

- The project idea, target stack, and any must-have repo components.

Example prompts:

- `Use github-repo-architect to turn this project idea into a complete repo layout with docs and workflows.`
- `Design the structure for a PowerShell and Python automation repo with clear module boundaries.`
- `Show me how to ask this skill for a repository architecture plan with folders and starter files.`