engram-project-structure

---
name: engram-project-structure
description: >
  Repository structure and placement rules for Engram. Trigger: Creating files,
  packages, handlers, templates, styles, or tests in this repo.
license: Apache-2.0
metadata:
  author: gentleman-programming
  version: "1.0"
---

## When to Use

Use this skill when:
- Creating a new package, file, or directory
- Deciding where code belongs
- Adding tests, templates, assets, or docs

---

## Placement Rules

1. Put behavior near its domain, not near the caller that happens to use it.
2. Keep templates in `internal/cloud/dashboard/*.templ` and generated files checked in.
3. Keep dashboard styling in `internal/cloud/dashboard/static/styles.css` unless a new static asset is clearly needed.
4. Put HTTP handlers in server packages, not in store packages.
5. Put persistence queries in store/cloudstore, not in handlers.

---

## File Creation Rules

- New route -> handler + tests in dashboard/server package
- New DB behavior -> store/cloudstore code + focused tests
- New UI partial/page -> templ component + generated `_templ.go`
- New contributor guidance -> update docs/catalog in same change

---

## Anti-Patterns

- Do not mix SQL, HTML, and transport logic in one file.
- Do not create utility packages for one-off helpers.
- Do not add package layers unless they remove real coupling.

More agent context in Gentleman-Programming/engram

19 other files this repository gives its agents.