repo-architecture

name	repo-architecture
description	Enforces strict separation between public-facing web directories (like docs/ for GitHub Pages) and internal repository files.

REPOSITORY ARCHITECTURE & SECURITY RULES

You MUST strictly separate public-facing files from internal development files. When a repository uses a directory like docs/ or public/ to serve a static website (e.g., GitHub Pages), you are FORBIDDEN from placing internal files inside it.

1. Web / LP Directories (website/, public/, lp/)

These directories must ONLY contain files that are meant to be served publicly to end-users via the web.

• ALLOWED: index.html, style.css, script.js, assets/, optimized images.
• STRICTLY BANNED: Internal markdown documentation (USER_GUIDE.md, ARCHITECTURE.md), AI configuration files, lockfiles, scripts, .agents/, .github/, source code for the backend.
• THE docs/ BAN FOR WEB: Do NOT hijack the docs/ folder to host a Landing Page or Web App just because GitHub Pages legacy settings support it. docs/ is strictly for real documentation (Markdown files, Sphinx, Docusaurus). For marketing pages, use website/ or public/.

2. Internal Directories (Project Root)

Files meant for developers, AI agents, or repository management must reside at the project root or in dedicated internal folders, NEVER inside the public web directory.

• Agent Skills: MUST be at <root>/.agents/skills/. Never place them in docs/.agents/.
• Documentation: Developer docs like README.md, USER_GUIDE.md, or architecture notes belong at the repository root.
• Config & State: Files like skills-lock.json, package.json, or environment variables must stay at the root.
• Admin & DevOps Docs: Setup guides for CI/CD, deployment secrets, or developer certificates MUST NEVER be placed in docs/ or other end-user documentation folders. They must be placed in internal administrative folders (e.g., .github/, .agents/scripts/) to prevent exposing internal infrastructure details to the public.

Enforcement

Before creating or moving any file, ask yourself: "Will this directory be exposed to the public internet via a static site host?" If yes, and the file is internal, you are committing a critical security and architectural failure.