social-media/AGENTS.md

AGENTS

This repository is designed for human + AI agent collaboration.

Read Order

Before meaningful code changes, read:

1. README.md
2. docs/AGENTIC_WORKFLOW.md
3. docs/ARCHITECTURE.md
4. docs/DEVELOPMENT_WORKFLOW.md
5. docs/PRODUCT.md
6. docs/CONVENTIONS.md
7. Relevant file in docs/FEATURES/
8. Relevant file in docs/TASKS/

Core Rules

• Do not invent architecture.
• Work from docs, feature specs, and task files instead of long chat history.
• Keep backend code under backend/src/Socialize.Api.
• The solution file is backend/Socialize.slnx.
• Backend feature code currently follows FastEndpoints module folders under Modules/<Feature>.
• Frontend feature work should prefer frontend/src/features/<feature> for new isolated slices while preserving existing route/store code until a task migrates it.
• Frontend runtime config must flow through frontend/src/config.js.
• If backend contracts change, run ./scripts/update-openapi.sh when the backend is running.
• Dev servers use HTTP and bind to 0.0.0.0 for LAN access.
• Avoid broad refactors unless the task explicitly asks for one.

Repository Layout

• backend/src/Socialize.Api/: ASP.NET Core net10.0 API using FastEndpoints, EF Core, PostgreSQL, ASP.NET Identity, and workflow modules.
• backend/tests/Socialize.Tests/: backend test project scaffold.
• frontend/: Vue 3 + Vite + Vuetify + Pinia SPA.
• docs/FEATURES/: product and technical feature specs.
• docs/TASKS/: implementation tickets for coding agents.
• docs/PROMPTS/: reusable agent prompt templates.
• docs/DECISIONS/: architecture and product decision records.
• shared/openapi/: backend OpenAPI schema snapshots.
• scripts/: root developer workflow commands.
• deploy/caddy/: Caddy reverse proxy config for Docker Compose.

Local Runbook

Start infrastructure:

./scripts/start-infrastructure.sh

Run backend:

./scripts/dev-backend.sh

Run frontend:

./scripts/dev-frontend.sh

Update OpenAPI:

./scripts/update-openapi.sh

Current Domain Modules

• Identity: authentication, refresh tokens, email verification, password reset, social login.
• Workspaces: workspace membership, workspace settings, access scoping.
• Clients: client records and primary contacts tied to workspaces.
• Projects: project pipeline and client/project relationships.
• ContentItems: reviewable content records tied to clients/projects.
• Assets: linked asset metadata and revision history.
• Comments: discussion threads on reviewable work.
• Approvals: review decisions and workflow state transitions.
• Notifications: activity feed and unread workflow notifications.

Task Discipline

Agents should work from task files in docs/TASKS/.

A good task:

• has a clear goal
• names the relevant feature spec
• has a small scope
• lists likely files
• lists validation commands

If no task exists, create one before implementing a meaningful feature.

Validation

Backend:

dotnet build backend/Socialize.slnx
dotnet test backend/Socialize.slnx

Frontend:

cd frontend
npm run build

Contract changes:

./scripts/update-openapi.sh

Sharp Edges

• Existing checked-in env and appsettings files may include legacy sensitive-looking values; do not propagate those values into new docs or templates.
• The frontend is still JavaScript, not the TypeScript starter app generated by the bootstrap script. New OpenAPI scaffolding exists, but migrating app code to generated typed API calls should happen by task.
• Some existing frontend code still lives under views/, stores/, and plugins/. Move it into feature folders only when a task explicitly owns that migration.