Charon/.github/instructions/structure.instructions.md

applyTo, description

applyTo	description
*	Repository structure guidelines to maintain organized file placement

Repository Structure Guidelines

Root Level Rules

The repository root should contain ONLY:

• Essential config files (.gitignore, .pre-commit-config.yaml, Makefile, etc.)
• Standard project files (README.md, CONTRIBUTING.md, LICENSE, CHANGELOG.md)
• Go workspace files (go.work, go.work.sum)
• VS Code workspace (Chiron.code-workspace)
• Primary Dockerfile (entrypoint and compose files live in .docker/)

File Placement Rules

Implementation/Feature Documentation

• Location: docs/implementation/
• Pattern: *_SUMMARY.md, *_IMPLEMENTATION.md, *_COMPLETE.md, *_FEATURE.md
• Never place implementation docs at root

Docker Compose Files

• Location: .docker/compose/
• Files: docker-compose.yml, docker-compose.*.yml
• Override: Local overrides go in .docker/compose/docker-compose.override.yml (gitignored)
• Exception: docker-compose.override.yml at root is allowed for backward compatibility

Docker Support Files

• Location: .docker/
• Files: docker-entrypoint.sh, Docker documentation (README.md)

Test Artifacts

• Never commit: *.sarif, *_test.txt, *.cover files at root
• Location: Test outputs should go to test-results/ or be gitignored

Debug/Temp Config Files

• Never commit: Temporary JSON configs like caddy_*.json at root
• Location: Use configs/ for persistent configs, gitignore temp files

Scripts

• Location: scripts/ for general scripts
• Location: .github/skills/scripts/ for agent skill scripts

Before Creating New Files

Ask yourself:

1. Is this a standard project file? → Root is OK
2. Is this implementation documentation? → docs/implementation/
3. Is this Docker-related? → .docker/ or .docker/compose/
4. Is this a test artifact? → test-results/ or gitignore
5. Is this a script? → scripts/
6. Is this runtime config? → configs/

Directory Structure Reference

/
├── .docker/                    # Docker configuration
│   ├── compose/               # All docker-compose files
│   └── docker-entrypoint.sh   # Container entrypoint
├── .github/                    # GitHub workflows, agents, instructions
├── .vscode/                    # VS Code settings and tasks
├── backend/                    # Go backend source
├── configs/                    # Runtime configurations
├── docs/                       # Documentation
│   ├── implementation/        # Implementation/feature docs archive
│   ├── plans/                 # Planning documents
│   └── ...                    # User-facing documentation
├── frontend/                   # React frontend source
├── scripts/                    # Build/test scripts
├── test-results/               # Test outputs (gitignored)
├── tools/                      # Development tools
└── [standard files]           # README, LICENSE, Makefile, etc.

Enforcement

This structure is enforced by:

• .gitignore patterns preventing commits of artifacts at root
• Code review guidelines
• These instructions for AI assistants

When reviewing PRs or generating code, ensure new files follow these placement rules.