chore: moving towards agentic development

.github/workflows/backend-ci.yml

@@ -28,7 +28,7 @@ jobs:
       - name: dotnet build and publish
         run: |
           cd backend
-          dotnet publish --configuration Release --artifacts-path ./publish/ backend.sln
+          dotnet publish --configuration Release --artifacts-path ./publish/ Socialize.slnx
 
       # Deploy to Azure WebApp
       - name: Deploy to Azure WebApp

.gitignore

@@ -19,6 +19,16 @@
 .DS_Store
 Thumbs.db
 
+# .NET
+bin/
+obj/
+TestResults/
+
+# Node
+node_modules/
+dist/
+.vite/
+
 # Local environment files
 *.local
 .env.local

AGENTS.md

@@ -1,103 +1,74 @@
-# AGENTS.md
+# AGENTS
 
-## Purpose
+This repository is designed for human + AI agent collaboration.
-This document is a working guide for coding agents in this repository. It captures the current architecture, conventions, and safe execution workflow for making reliable changes.
 
-## Documentation-First Workflow
+## Read Order
-Agents must treat repository documentation as the source of truth. Conversation history is secondary and may be incomplete, stale, or contradictory.
 
-Before making any substantial code change, agents must read the relevant docs first. At minimum, inspect:
+Before meaningful code changes, read:
-- `AGENTS.md`
-- `docs/LLM_DEVELOPMENT_WORKFLOW.md`
-- `docs/PRODUCT.md` when product behavior, UX, or user workflow may change
-- `docs/ARCHITECTURE.md` when structure, module boundaries, routing, data flow, or integration points may change
-- `docs/CONVENTIONS.md` when adding or modifying code patterns
-- `docs/DECISIONS.md` before revisiting architecture or product decisions
-- the active `docs/tasks/TASK-*.md` file when one exists
 
-If one of these files does not exist yet, do not invent broad behavior from chat history. State what is missing and proceed only with the narrowest safe interpretation of the current task.
+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/`
 
-For non-trivial work, follow this sequence:
+## Core Rules
-1. Read the relevant docs and existing code.
-2. Restate the task in a short summary.
-3. Identify backend impact, frontend impact, data impact, and documentation impact.
-4. List files likely to change.
-5. Surface ambiguities or risky assumptions.
-6. Propose a minimal implementation plan.
-7. Implement only the approved or clearly requested scope.
-8. Validate with the relevant commands before finishing when possible.
 
-Do not use a long chat thread as the durable memory for the project. Durable decisions, conventions, and task requirements belong in repository docs.
+- Do not invent architecture.
-
+- Work from docs, feature specs, and task files instead of long chat history.
-## Pair Working Mode
+- Keep backend code under `backend/src/Socialize.Api`.
-- Work as a pair with the repository owner, not as an isolated implementer.
+- The solution file is `backend/Socialize.slnx`.
-- Before substantial changes, read the relevant docs first, then restate the task briefly and inspect the existing code.
+- Backend feature code currently follows FastEndpoints module folders under `Modules/<Feature>`.
-- Surface assumptions, tradeoffs, and blockers early instead of silently picking risky directions.
+- Frontend feature work should prefer `frontend/src/features/<feature>` for new isolated slices while preserving existing route/store code until a task migrates it.
-- Prefer small, reviewable increments when the product direction is still being shaped.
+- Frontend runtime config must flow through `frontend/src/config.js`.
-- When requirements are exploratory, help turn them into concrete workflows, domain language, and next implementation steps.
+- If backend contracts change, run `./scripts/update-openapi.sh` when the backend is running.
-- Do not rewrite broad areas of the codebase without clear justification from the current task.
+- Dev servers use HTTP and bind to `0.0.0.0` for LAN access.
-- Preserve user changes in the worktree and treat uncommitted files as active collaboration unless told otherwise.
+- Avoid broad refactors unless the task explicitly asks for one.
-- When creating commits, use the Conventional Commits format, for example `docs: update product planning`.
 
 ## Repository Layout
-- `backend/`: ASP.NET Core (`net10.0`) API using FastEndpoints, EF Core (PostgreSQL), ASP.NET Identity, and modular bounded contexts for workflow data.
+
-- `frontend/`: Vue 3 + Vite + Vuetify + Pinia + Vue Router + Tailwind CSS SPA.
+- `backend/src/Socialize.Api/`: ASP.NET Core `net10.0` API using FastEndpoints, EF Core, PostgreSQL, ASP.NET Identity, and workflow modules.
-- `.github/workflows/`: build/deploy pipelines for backend (Azure Web App) and frontend (Azure Static Web Apps).
+- `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
-### Backend
-- Prereqs: .NET 10 SDK, Docker, PostgreSQL container.
-- Start database:
-  - `cd backend`
-  - `./scripts/start-infrastructure.sh`
-- Run API:
-  - `dotnet run --project Socialize.Api.csproj` (from `backend/`)
-- Local API URL:
-  - `http://localhost:5000`
-- Swagger/OpenAPI UI in dev:
-  - `/api`
 
-### Frontend
+Start infrastructure:
-- Prereqs: Node/npm.
-- Runtime configuration:
-  - frontend app config is loaded from `.env.development` and `.env.production`
-  - `frontend/src/config.js` is the single frontend source of truth for runtime env access
-- Commands:
-  - `cd frontend && npm install`
-  - `npm run dev`
-  - `npm run build`
-- Local dev server:
-  - `http://localhost:5173`
 
-## Backend Architecture
+```bash
-### Composition Root
+./scripts/start-infrastructure.sh
-- Entry point: `backend/Program.cs`.
+```
-- Registers:
-  - Web services/auth (`backend/DependencyInjection.cs`)
-  - Infrastructure services (`backend/Infrastructure/DependencyInjection.cs`)
-  - Modules: Identity, Workspaces, Clients, Projects, ContentItems, Assets, Comments, Approvals, Notifications.
-- Each module has:
-  - `Add{Module}Module(...)` to register DbContext/services.
-  - `Use{Module}ModuleAsync()` to auto-run migrations at startup.
 
-### API Style
+Run backend:
-- FastEndpoints-based handlers.
-- Pattern: request/response records + optional FluentValidation validator + handler class.
-- Tagging via `Options(o => o.WithTags("..."))`.
-- File upload handlers call `AllowFileUploads()`.
 
-### Data Boundaries
+```bash
-- Separate DbContext per module:
+./scripts/dev-backend.sh
-  - Identity, Workspaces, Clients, Projects, ContentItems, Assets, Comments, Approvals, Notifications.
+```
-- Migrations are module-scoped under each `Modules/*/Migrations` folder.
 
-### Auth/Security
+Run frontend:
-- JWT is generated manually in `Infrastructure/Security/GenerateJwtToken.cs`.
+
-- Refresh-token flow is implemented in Identity handlers (`/api/users/login`, `/api/users/refresh`).
+```bash
-- User claim helpers live in `Infrastructure/Security/ClaimsPrincipalExtensions.cs`.
+./scripts/dev-frontend.sh
-- Role-gated frontend routes currently use `Administrator` and `Manager` checks for settings access.
+```
+
+Update OpenAPI:
+
+```bash
+./scripts/update-openapi.sh
+```
+
+## Current Domain Modules
 
-### 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.
@@ -108,82 +79,44 @@ Do not use a long chat thread as the durable memory for the project. Durable dec
 - `Approvals`: review decisions and workflow state transitions.
 - `Notifications`: activity feed and unread workflow notifications.
 
-## Frontend Architecture
+## Task Discipline
-### Bootstrap
-- `frontend/src/main.js` wires Vue app + Pinia + Vuetify + Router + i18n + Google OAuth + Toasts.
-- `frontend/src/config.js` is the app-facing runtime configuration module. Do not scatter `import.meta.env` reads across the app.
 
-### Routing
+Agents should work from task files in `docs/TASKS/`.
-- Defined in `frontend/src/router/router.js`.
-- Route guards enforce:
-  - `meta.requiresAuth`
-  - `meta.notAuthenticated`
-  - optional `meta.roles`
-- Primary authenticated app routes live under `/app/*`.
 
-### State Management
+A good task:
-- Pinia stores:
-  - `authStore`: token lifecycle + refresh concurrency guard.
-  - `workspaceStore`: active workspace context.
-  - `clientsStore`: client list and creation flows.
-  - `projectsStore`: project list and creation flows.
-  - `contentItemsStore` and `contentItemDetailStore`: content item listing/detail flows.
-  - `reviewQueueStore`: pending review work.
-  - `notificationsStore`: workflow notifications.
-  - `userProfileStore`: current user profile and account edits.
 
-### API Client
+- has a clear goal
-- Axios client in `frontend/src/plugins/api.js`.
+- names the relevant feature spec
-- Injects bearer token, proactively refreshes near expiry, retries once on 401.
+- has a small scope
+- lists likely files
+- lists validation commands
 
-## High-Value Domains
+If no task exists, create one before implementing a meaningful feature.
-- Identity and social login (`backend/Modules/Identity/*`, `frontend/src/views/auth/*`).
-- Workspace-scoped operations and role checks (`backend/Modules/Workspaces/*`, `frontend/src/stores/workspaceStore.js`, `frontend/src/router/router.js`).
-- Client and project workflow (`backend/Modules/Clients/*`, `backend/Modules/Projects/*`, `frontend/src/views/app/ClientsView.vue`, `frontend/src/views/app/ProjectsView.vue`).
-- Content review lifecycle (`backend/Modules/ContentItems/*`, `backend/Modules/Assets/*`, `backend/Modules/Comments/*`, `backend/Modules/Approvals/*`, `frontend/src/views/app/ContentItemsView.vue`, `frontend/src/views/app/ContentItemDetailView.vue`, `frontend/src/views/app/ReviewQueueView.vue`).
-- Notifications and workflow awareness (`backend/Modules/Notifications/*`, `frontend/src/stores/notificationsStore.js`).
 
-## Task-Driven Development With Agents
+## Validation
-Use `docs/tasks/TASK-*.md` files as LLM-friendly implementation tickets. A task file should be self-contained enough for a fresh agent to understand the desired change without relying on a long conversation.
 
-A good task file defines:
+Backend:
-- objective and product context
-- scope and out of scope
-- backend requirements, API contract, validation, data, authorization
-- frontend requirements, route/screen, components, state, API integration, UX states
-- files likely involved
-- acceptance criteria
-- validation plan
-- risks and open questions
 
-Features are fullstack by default unless the task explicitly says otherwise. Do not assume a feature is backend-only. For user-facing work, define both backend and frontend behavior before implementation.
+```bash
+dotnet build backend/Socialize.slnx
+dotnet test backend/Socialize.slnx
+```
 
-When an adjacent issue is discovered outside the task scope, do not fix it opportunistically. Report it as a suggested backlog item or add it to `docs/BACKLOG.md` if explicitly asked.
+Frontend:
 
-## Agent Working Rules For This Repo
+```bash
-1. Keep module boundaries intact. Do not couple DbContexts across modules.
+cd frontend
-2. When adding endpoints, follow existing FastEndpoints pattern with validator + explicit route + tag.
+npm run build
-3. If schema changes are needed, generate migration in the matching module only.
+```
-4. Preserve token refresh behavior in frontend client/store; avoid introducing parallel refresh races.
-5. Keep frontend runtime configuration centralized in `frontend/src/config.js` and `.env.*`; do not introduce ad hoc env fallbacks.
-6. Preserve workspace scoping and route-role checks when editing app flows.
-7. Do not commit secrets. Existing appsettings and env files include sensitive-looking values; treat them as legacy and avoid propagating.
-8. For non-trivial features, prefer a `docs/tasks/TASK-*.md` file before implementation.
-9. Treat frontend behavior as part of the feature definition: route, components, Pinia store usage, API integration, loading/error/success states, and navigation must be explicit or derived from existing patterns.
-10. If requirements conflict with repository docs, stop and surface the conflict instead of silently choosing one.
 
-## Validation Checklist Before Finishing
+Contract changes:
-- Backend:
-  - `cd backend && dotnet build Socialize.Api.csproj`
-  - run affected endpoint flows if change touches handlers/auth/workspace scoping/data writes
-- Frontend:
-  - `cd frontend && npm run build`
-  - validate affected route/store interactions in browser when UI behavior changed
-- If migrations were changed:
-  - ensure module context name/output directory remain consistent with `backend/scripts/add-migration.sh`.
 
-## Notes / Known Sharp Edges
+```bash
-- Frontend config should come through `.env.development` / `.env.production` and `frontend/src/config.js`; avoid direct `import.meta.env` reads in feature code.
+./scripts/update-openapi.sh
-- Backend development now runs on HTTP locally (`http://localhost:5000`), while HTTPS redirection stays enabled outside development.
+```
-- `frontend/.env.development` is currently checked in and points `VITE_API_URL` to `http://192.168.1.2:5000`; verify whether changes should target `localhost` or the LAN host before editing.
+
-- Some style/formatting is inconsistent across JS/Vue/C# files; minimize churn to touched lines.
+## 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.

README.md

@@ -1,88 +1,101 @@
 # Socialize
 
-Socialize is a workflow application for social media content review, revision, approval, and publication readiness.
+Socialize is a workspace-based workflow application for social media content review, revision, approval, and publication readiness.
 
-It is not a public social network. The current product direction is a workspace-based review tool for internal teams, providers, and client approvers.
+It is not a public social network. The product is for internal teams, providers, and client approvers coordinating content work before publication.
 
-## Repository Structure
+## Monorepo
 
-- `backend/`: ASP.NET Core `net10.0` API with FastEndpoints, EF Core, PostgreSQL, and modular bounded contexts.
+- Backend: .NET 10 Web API in `backend/src/Socialize.Api`
-- `frontend/`: Vue 3 + Vite + Vuetify + Pinia SPA.
+- Backend tests: `backend/tests/Socialize.Tests`
-- `docs/`: product, planning, and archived project documentation.
+- Frontend: Vue 3 + Vite + Vuetify + Pinia in `frontend`
-
+- API contract: OpenAPI snapshot in `shared/openapi`
-## Current Backend Modules
+- Deployment: Docker Compose + Caddy
-
+- Agentic workflow: specs, task files, and prompt templates under `docs`
-- `Identity`
-- `Workspaces`
-- `Clients`
-- `Projects`
-- `ContentItems`
-- `Assets`
-- `Comments`
-- `Approvals`
-- `Notifications`
 
 ## Local Development
 
-### Backend
+Terminal 1:
-
-Prerequisites:
-
-- .NET 10 SDK
-- Docker
-
-Start infrastructure:
 
 ```bash
-cd backend
 ./scripts/start-infrastructure.sh
+./scripts/dev-backend.sh
 ```
 
-Run the API:
+Terminal 2:
 
 ```bash
-cd backend
+./scripts/dev-frontend.sh
-dotnet run --project Socialize.Api.csproj
 ```
 
-Local backend URL:
+Frontend:
 
-- `http://localhost:5000`
+```txt
-- Swagger UI: `http://localhost:5000/api`
+http://localhost:5173
+http://<this-machine-lan-ip>:5173
+```
 
-### Frontend
+Backend:
 
-Prerequisites:
+```txt
+http://localhost:5080
+http://<this-machine-lan-ip>:5080
+```
 
-- Node.js / npm
+Swagger UI:
 
-The frontend reads runtime values from:
+```txt
+http://localhost:5080/api
+```
 
-- `frontend/.env.development`
+## Update Frontend API Types
-- `frontend/.env.production`
-- `frontend/src/config.js`
 
-Run the frontend:
+The backend must be running first.
+
+```bash
+./scripts/update-openapi.sh
+```
+
+This writes:
+
+```txt
+shared/openapi/openapi.json
+frontend/src/api/schema.d.ts
+```
+
+## Docker Compose
+
+```bash
+docker compose up --build
+```
+
+Then open:
+
+```txt
+http://localhost:8080
+http://<this-machine-lan-ip>:8080
+```
+
+## Solution
+
+```bash
+dotnet build backend/Socialize.slnx
+dotnet test backend/Socialize.slnx
+```
+
+## Frontend Build
 
 ```bash
 cd frontend
-npm install
+npm run build
-npm run dev
 ```
 
-Local frontend URL:
+## Agentic Workflow
 
-- `http://localhost:5173`
+Start here:
 
-## Validation
+```txt
+docs/AGENTIC_WORKFLOW.md
+```
 
-- Backend: `cd backend && dotnet build Socialize.Api.csproj`
+Use feature specs, task files, and prompt templates instead of asking agents to work from vague chat history.
-- Frontend: `cd frontend && npm run build`
-
-## Docs
-
-- [docs/README.md](/home/jbourdon/repos/social-media/docs/README.md)
-- [docs/product/vision.md](/home/jbourdon/repos/social-media/docs/product/vision.md)
-- [docs/product/glossary.md](/home/jbourdon/repos/social-media/docs/product/glossary.md)
-- [docs/constraints.md](/home/jbourdon/repos/social-media/docs/constraints.md)
-- [AGENTS.md](/home/jbourdon/repos/social-media/AGENTS.md)

backend/Socialize.slnx

@@ -0,0 +1,11 @@
+<Solution>
+  <Configurations>
+    <Platform Name="Any CPU" />
+    <Platform Name="x64" />
+    <Platform Name="x86" />
+  </Configurations>
+  <Folder Name="/tests/">
+    <Project Path="tests/Socialize.Tests/Socialize.Tests.csproj" />
+  </Folder>
+  <Project Path="src/Socialize.Api/Socialize.Api.csproj" />
+</Solution>

backend/backend.sln

@@ -1,16 +0,0 @@
-
-Microsoft Visual Studio Solution File, Format Version 12.00
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Socialize.Api", "Socialize.Api.csproj", "{D790B528-6968-4CCD-A25D-A108A82CBDAC}"
-EndProject
-Global
-	GlobalSection(SolutionConfigurationPlatforms) = preSolution
-		Debug|Any CPU = Debug|Any CPU
-		Release|Any CPU = Release|Any CPU
-	EndGlobalSection
-	GlobalSection(ProjectConfigurationPlatforms) = postSolution
-		{D790B528-6968-4CCD-A25D-A108A82CBDAC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{D790B528-6968-4CCD-A25D-A108A82CBDAC}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{D790B528-6968-4CCD-A25D-A108A82CBDAC}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{D790B528-6968-4CCD-A25D-A108A82CBDAC}.Release|Any CPU.Build.0 = Release|Any CPU
-	EndGlobalSection
-EndGlobal

backend/scripts/add-migration.sh

@@ -13,5 +13,7 @@ fi
 dotnet ef migrations add \
   --context "Socialize.Modules.${MODULE_NAME}.Data.${MODULE_NAME}DbContext" \
   --configuration Debug \
+  --project "src/Socialize.Api/Socialize.Api.csproj" \
+  --startup-project "src/Socialize.Api/Socialize.Api.csproj" \
   --output-dir "Modules/${MODULE_NAME}/Migrations" \
   "$MIGRATION_NAME"

backend/scripts/update-databases.sh

@@ -16,6 +16,8 @@ UPDATE_COMMAND=(
   dotnet ef database update
   --context "Socialize.Modules.${MODULE_NAME}.Data.${MODULE_NAME}DbContext"
   --configuration Debug
+  --project "src/Socialize.Api/Socialize.Api.csproj"
+  --startup-project "src/Socialize.Api/Socialize.Api.csproj"
 )
 
 if [ -n "$TARGET_MIGRATION" ]; then

backend/src/Socialize.Api/Dockerfile

@@ -0,0 +1,25 @@
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+
+COPY backend/Socialize.slnx backend/
+COPY backend/src/Socialize.Api/Socialize.Api.csproj backend/src/Socialize.Api/
+COPY backend/tests/Socialize.Tests/Socialize.Tests.csproj backend/tests/Socialize.Tests/
+
+RUN dotnet restore backend/Socialize.slnx
+
+COPY backend/ backend/
+
+RUN dotnet publish backend/src/Socialize.Api/Socialize.Api.csproj \
+    -c Release \
+    -o /app/publish \
+    --no-restore
+
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS runtime
+WORKDIR /app
+COPY --from=build /app/publish .
+
+ENV ASPNETCORE_URLS=http://0.0.0.0:8080
+ENV ASPNETCORE_ENVIRONMENT=Production
+
+EXPOSE 8080
+ENTRYPOINT ["dotnet", "Socialize.Api.dll"]