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 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.
+This repository is designed for human + AI agent collaboration.
 
-## Documentation-First Workflow
-Agents must treat repository documentation as the source of truth. Conversation history is secondary and may be incomplete, stale, or contradictory.
+## Read Order
 
-Before making any substantial code change, agents must read the relevant docs first. At minimum, inspect:
-- `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
+Before meaningful code changes, read:
 
-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:
-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.
+## Core Rules
 
-Do not use a long chat thread as the durable memory for the project. Durable decisions, conventions, and task requirements belong in repository docs.
-
-## Pair Working Mode
-- Work as a pair with the repository owner, not as an isolated implementer.
-- Before substantial changes, read the relevant docs first, then restate the task briefly and inspect the existing code.
-- Surface assumptions, tradeoffs, and blockers early instead of silently picking risky directions.
-- Prefer small, reviewable increments when the product direction is still being shaped.
-- When requirements are exploratory, help turn them into concrete workflows, domain language, and next implementation steps.
-- Do not rewrite broad areas of the codebase without clear justification from the current task.
-- Preserve user changes in the worktree and treat uncommitted files as active collaboration unless told otherwise.
-- When creating commits, use the Conventional Commits format, for example `docs: update product planning`.
+- 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/`: 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.
-- `.github/workflows/`: build/deploy pipelines for backend (Azure Web App) and frontend (Azure Static Web Apps).
+
+- `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
-### 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
-- 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`
+Start infrastructure:
 
-## Backend Architecture
-### Composition Root
-- 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.
+```bash
+./scripts/start-infrastructure.sh
+```
 
-### API Style
-- FastEndpoints-based handlers.
-- Pattern: request/response records + optional FluentValidation validator + handler class.
-- Tagging via `Options(o => o.WithTags("..."))`.
-- File upload handlers call `AllowFileUploads()`.
+Run backend:
 
-### Data Boundaries
-- Separate DbContext per module:
-  - Identity, Workspaces, Clients, Projects, ContentItems, Assets, Comments, Approvals, Notifications.
-- Migrations are module-scoped under each `Modules/*/Migrations` folder.
+```bash
+./scripts/dev-backend.sh
+```
 
-### Auth/Security
-- JWT is generated manually in `Infrastructure/Security/GenerateJwtToken.cs`.
-- Refresh-token flow is implemented in Identity handlers (`/api/users/login`, `/api/users/refresh`).
-- User claim helpers live in `Infrastructure/Security/ClaimsPrincipalExtensions.cs`.
-- Role-gated frontend routes currently use `Administrator` and `Manager` checks for settings access.
+Run frontend:
+
+```bash
+./scripts/dev-frontend.sh
+```
+
+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
-### 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.
+## Task Discipline
 
-### Routing
-- Defined in `frontend/src/router/router.js`.
-- Route guards enforce:
-  - `meta.requiresAuth`
-  - `meta.notAuthenticated`
-  - optional `meta.roles`
-- Primary authenticated app routes live under `/app/*`.
+Agents should work from task files in `docs/TASKS/`.
 
-### State Management
-- 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.
+A good task:
 
-### API Client
-- Axios client in `frontend/src/plugins/api.js`.
-- Injects bearer token, proactively refreshes near expiry, retries once on 401.
+- has a clear goal
+- names the relevant feature spec
+- has a small scope
+- lists likely files
+- lists validation commands
 
-## High-Value Domains
-- 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`).
+If no task exists, create one before implementing a meaningful feature.
 
-## Task-Driven Development With Agents
-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.
+## Validation
 
-A good task file defines:
-- 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
+Backend:
 
-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
-1. Keep module boundaries intact. Do not couple DbContexts across modules.
-2. When adding endpoints, follow existing FastEndpoints pattern with validator + explicit route + tag.
-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.
+```bash
+cd frontend
+npm run build
+```
 
-## Validation Checklist Before Finishing
-- 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`.
+Contract changes:
 
-## Notes / Known Sharp Edges
-- Frontend config should come through `.env.development` / `.env.production` and `frontend/src/config.js`; avoid direct `import.meta.env` reads in feature code.
-- 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.
+```bash
+./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.

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.
-- `frontend/`: Vue 3 + Vite + Vuetify + Pinia SPA.
-- `docs/`: product, planning, and archived project documentation.
-
-## Current Backend Modules
-
-- `Identity`
-- `Workspaces`
-- `Clients`
-- `Projects`
-- `ContentItems`
-- `Assets`
-- `Comments`
-- `Approvals`
-- `Notifications`
+- Backend: .NET 10 Web API in `backend/src/Socialize.Api`
+- Backend tests: `backend/tests/Socialize.Tests`
+- Frontend: Vue 3 + Vite + Vuetify + Pinia in `frontend`
+- API contract: OpenAPI snapshot in `shared/openapi`
+- Deployment: Docker Compose + Caddy
+- Agentic workflow: specs, task files, and prompt templates under `docs`
 
 ## Local Development
 
-### Backend
-
-Prerequisites:
-
-- .NET 10 SDK
-- Docker
-
-Start infrastructure:
+Terminal 1:
 
 ```bash
-cd backend
 ./scripts/start-infrastructure.sh
+./scripts/dev-backend.sh
 ```
 
-Run the API:
+Terminal 2:
 
 ```bash
-cd backend
-dotnet run --project Socialize.Api.csproj
+./scripts/dev-frontend.sh
 ```
 
-Local backend URL:
+Frontend:
 
-- `http://localhost:5000`
-- Swagger UI: `http://localhost:5000/api`
+```txt
+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`
-- `frontend/.env.production`
-- `frontend/src/config.js`
+## Update Frontend API Types
 
-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 dev
+npm run build
 ```
 
-Local frontend URL:
+## Agentic Workflow
 
-- `http://localhost:5173`
+Start here:
 
-## Validation
+```txt
+docs/AGENTIC_WORKFLOW.md
+```
 
-- Backend: `cd backend && dotnet build Socialize.Api.csproj`
-- 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)
+Use feature specs, task files, and prompt templates instead of asking agents to work from vague chat history.

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"]