git:20260522.736a01e to git:20260609.a0be1e4

+ ---

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

+