tpo-repository-structure

Defines standard repository structure guidelines with checklists, templates, and review rules for projects.

Updated Mar 22, 2026
One-click install
npx skills add https://github.com/TECH-HY/SKILLS --skill tpo-repository-structure-tech-hy
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: tpo-repository-structure
Source: https://github.com/TECH-HY/SKILLS/tree/main/skills/tpo-repository-structure
Command: npx skills add https://github.com/TECH-HY/SKILLS --skill tpo-repository-structure-tech-hy

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams and AI agents often create inconsistent, disorganized repository layouts that make projects hard to navigate, test, deploy, and review. This Skill provides a Technical Product Owner guideline module that standardizes repository structure so human and AI developers can extend projects safely. ## Core Features & Use Cases - Standard Structure Templates: Provides full-stack monorepo and simple MVP directory layouts covering apps, services, packages, docs, tests, scripts, and infra. - Root File Requirements: Specifies mandatory content for README.md, CONTRIBUTING.md, SECURITY.md, CHANGELOG.md, .env.example, and CODEOWNERS. - Review Checklist & ADR Template: Includes a repository review checklist, an Architecture Decision Record template, and a required output format for AI agents making structural changes. - Use Case: When starting a new project or auditing an existing one, an agent applies these rules to verify separation of source, tests, docs, and infrastructure, confirm secrets are excluded, and document structural decisions. ## Quick Start Review my repository structure against the TPO guidelines and list any missing root files, misplaced modules, or undocumented architecture decisions.

Frequently Asked Questions about tpo-repository-structure

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I structure a full-stack monorepo project?

Separate user-facing apps into apps/, backend services into services/, shared libraries into packages/, and keep docs, tests, scripts, and infra in dedicated top-level directories. Each service owns its routes, repositories, validators, migrations, and tests.

What files should every repository root contain?

A repository root should include README.md, CONTRIBUTING.md, SECURITY.md, CHANGELOG.md, LICENSE, .gitignore, and .env.example with placeholder values. Add CODEOWNERS when multiple modules or critical areas need clear review ownership.

How do I document architecture decisions in a repository?

Use Architecture Decision Records stored in docs/decisions/ with a template covering status, context, decision, consequences, and alternatives considered. Each significant decision gets its own numbered ADR file.

When should I use a simple structure instead of a monorepo?

Use the simple MVP structure when the project is small and does not need multiple apps or shared packages. It keeps a single src/ directory with routes, services, and models plus top-level tests, migrations, scripts, and infra folders.

What should an AI agent report when changing repository structure?

The agent must list directories and files added, moved, or removed, explain why the structure supports the architecture, describe migration impact on imports and build paths, and identify risks or follow-up work.