chore: moving towards agentic development
This commit is contained in:
81
docs/AGENTIC_WORKFLOW.md
Normal file
81
docs/AGENTIC_WORKFLOW.md
Normal file
@@ -0,0 +1,81 @@
|
||||
# Agentic Workflow
|
||||
|
||||
This repository is designed to be worked on by humans and coding agents.
|
||||
|
||||
The goal is to avoid the common failure mode where the first AI prompt creates a lot of code and later prompts degrade because the agent loses product and architecture context.
|
||||
|
||||
## Core Rule
|
||||
|
||||
Agents do not work from vague chat history.
|
||||
|
||||
Agents work from repository files:
|
||||
|
||||
1. `AGENTS.md`
|
||||
2. `docs/ARCHITECTURE.md`
|
||||
3. `docs/DEVELOPMENT_WORKFLOW.md`
|
||||
4. `docs/PRODUCT.md`
|
||||
5. `docs/CONVENTIONS.md`
|
||||
6. `docs/FEATURES/<feature>.md`
|
||||
7. `docs/TASKS/<feature>/<task>.md`
|
||||
8. `docs/PROMPTS/<prompt-template>.md`
|
||||
|
||||
## Workflow Loop
|
||||
|
||||
For every meaningful change:
|
||||
|
||||
1. Define or update a feature spec in `docs/FEATURES/`.
|
||||
2. Create a small task in `docs/TASKS/<feature>/`.
|
||||
3. Use the correct prompt template from `docs/PROMPTS/`.
|
||||
4. Ask the agent to implement only that task.
|
||||
5. Review the diff.
|
||||
6. Run tests and builds.
|
||||
7. Update OpenAPI when backend contracts change.
|
||||
8. Commit the task separately.
|
||||
|
||||
## Unit Of Work
|
||||
|
||||
A task should usually be small enough to finish in one agent session.
|
||||
|
||||
Good task examples:
|
||||
|
||||
- Add one endpoint.
|
||||
- Add one route-level screen.
|
||||
- Add one Pinia store action and its API integration.
|
||||
- Add validation for one request model.
|
||||
- Add tests for one workflow transition.
|
||||
|
||||
Bad task examples:
|
||||
|
||||
- Build all approvals.
|
||||
- Redesign the app.
|
||||
- Fix every workspace issue.
|
||||
- Add publishing, billing, and analytics together.
|
||||
|
||||
## Contract Workflow
|
||||
|
||||
When backend endpoints or contracts change:
|
||||
|
||||
```bash
|
||||
./scripts/dev-backend.sh
|
||||
./scripts/update-openapi.sh
|
||||
```
|
||||
|
||||
Then check frontend errors and update affected frontend code.
|
||||
|
||||
## Agent Guardrails
|
||||
|
||||
Agents must not:
|
||||
|
||||
- invent architecture
|
||||
- perform broad unrelated refactors
|
||||
- manually duplicate generated API types when generated types are available
|
||||
- ignore existing docs
|
||||
- change deployment defaults without updating docs
|
||||
- silently replace the chosen backend/frontend structure
|
||||
|
||||
Agents should:
|
||||
|
||||
- make small changes
|
||||
- update feature specs when behavior changes
|
||||
- update task files if implementation scope changes
|
||||
- run or list validation commands
|
||||
92
docs/ARCHITECTURE.md
Normal file
92
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,92 @@
|
||||
# Architecture
|
||||
|
||||
## Backend
|
||||
|
||||
```txt
|
||||
backend/
|
||||
├─ Socialize.slnx
|
||||
├─ src/Socialize.Api/
|
||||
│ ├─ Common/
|
||||
│ ├─ Data/
|
||||
│ ├─ Infrastructure/
|
||||
│ ├─ Migrations/
|
||||
│ ├─ Modules/
|
||||
│ └─ Program.cs
|
||||
└─ tests/Socialize.Tests/
|
||||
```
|
||||
|
||||
The backend is one API project plus one test project.
|
||||
|
||||
The original bootstrap scaffold uses `Endpoints/<Feature>` and `Contracts/<Feature>` for a minimal API. Socialize already uses FastEndpoints modules, so current backend feature code stays under `Modules/<Feature>` until a task intentionally changes that pattern.
|
||||
|
||||
## Backend Composition
|
||||
|
||||
Entry point:
|
||||
|
||||
```txt
|
||||
backend/src/Socialize.Api/Program.cs
|
||||
```
|
||||
|
||||
Composition registers:
|
||||
|
||||
- web services and auth in `DependencyInjection.cs`
|
||||
- infrastructure in `Infrastructure/DependencyInjection.cs`
|
||||
- domain modules for Identity, Workspaces, Clients, Projects, ContentItems, Assets, Comments, Approvals, and Notifications
|
||||
|
||||
## Data Ownership
|
||||
|
||||
The current implementation uses a shared `AppDbContext` in:
|
||||
|
||||
```txt
|
||||
backend/src/Socialize.Api/Data/AppDbContext.cs
|
||||
```
|
||||
|
||||
Workflow data is organized by module folders. Do not couple unrelated modules through ad hoc service calls; keep ownership boundaries explicit.
|
||||
|
||||
## Frontend
|
||||
|
||||
```txt
|
||||
frontend/src/
|
||||
├─ api/
|
||||
├─ app/
|
||||
├─ components/
|
||||
├─ features/
|
||||
├─ layouts/
|
||||
├─ pages/
|
||||
├─ plugins/
|
||||
├─ router/
|
||||
├─ stores/
|
||||
└─ views/
|
||||
```
|
||||
|
||||
The generated scaffold expects `app/`, `features/`, `pages/`, `router/`, `stores/`, and `api/`. Socialize currently has substantial existing code under `views/`, `stores/`, and `plugins/`. New isolated feature work should prefer `features/<feature>/`; existing screens should be migrated only by explicit task.
|
||||
|
||||
## API Contract
|
||||
|
||||
The backend exposes NSwag OpenAPI in development at:
|
||||
|
||||
```txt
|
||||
http://localhost:5080/swagger/v1/swagger.json
|
||||
```
|
||||
|
||||
The frontend updates its OpenAPI model with:
|
||||
|
||||
```bash
|
||||
./scripts/update-openapi.sh
|
||||
```
|
||||
|
||||
Contract flow:
|
||||
|
||||
```txt
|
||||
Backend contracts -> OpenAPI -> frontend TypeScript types
|
||||
```
|
||||
|
||||
## Deployment Shape
|
||||
|
||||
Docker Compose runs:
|
||||
|
||||
- `postgres`
|
||||
- `api`
|
||||
- `web`
|
||||
|
||||
Caddy serves the frontend and reverse-proxies API paths to the backend.
|
||||
14
docs/BACKLOG.md
Normal file
14
docs/BACKLOG.md
Normal file
@@ -0,0 +1,14 @@
|
||||
# Backlog
|
||||
|
||||
## Technical
|
||||
|
||||
- Migrate frontend app entry and route-level views toward the generated `app/`, `pages/`, and `features/` structure.
|
||||
- Replace manually maintained frontend API shapes with generated OpenAPI types where practical.
|
||||
- Add meaningful backend tests for workspace scoping and content approval transitions.
|
||||
- Add frontend route smoke tests for the authenticated app shell.
|
||||
|
||||
## Product
|
||||
|
||||
- Define the external reviewer experience.
|
||||
- Clarify publishing handoff states after approval.
|
||||
- Define reminder and notification escalation rules.
|
||||
34
docs/CONVENTIONS.md
Normal file
34
docs/CONVENTIONS.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# Conventions
|
||||
|
||||
## Backend
|
||||
|
||||
- Use FastEndpoints handlers for API work.
|
||||
- Keep request/response records near the handler unless an existing module pattern says otherwise.
|
||||
- Add FluentValidation validators for non-trivial input.
|
||||
- Use explicit routes and tags.
|
||||
- Preserve workspace scoping for workspace-owned data.
|
||||
- Keep schema changes in the owning data area and update migrations intentionally.
|
||||
|
||||
## Frontend
|
||||
|
||||
- Use `frontend/src/config.js` for runtime configuration.
|
||||
- Use the shared Axios API client in `frontend/src/plugins/api.js` for current JavaScript flows.
|
||||
- Preserve auth refresh behavior in `authStore` and the API plugin.
|
||||
- Route-level authenticated app screens live under `/app/*`.
|
||||
- New isolated feature slices should prefer `frontend/src/features/<feature>/`.
|
||||
- Do not move existing views/stores into feature folders unless a task owns that migration.
|
||||
|
||||
## Docs
|
||||
|
||||
- Current feature behavior belongs in `docs/FEATURES/`.
|
||||
- Implementation work belongs in `docs/TASKS/<feature>/`.
|
||||
- Reusable prompts belong in `docs/PROMPTS/`.
|
||||
- Durable decisions belong in `docs/DECISIONS/`.
|
||||
- Archived material belongs in `docs/archive/`.
|
||||
|
||||
## Validation
|
||||
|
||||
- Backend changes: `dotnet build backend/Socialize.slnx`
|
||||
- Backend behavior changes: `dotnet test backend/Socialize.slnx`
|
||||
- Frontend changes: `cd frontend && npm run build`
|
||||
- Backend contract changes: `./scripts/update-openapi.sh`
|
||||
27
docs/DECISIONS/0001-adopt-agentic-scaffold.md
Normal file
27
docs/DECISIONS/0001-adopt-agentic-scaffold.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# Decision 0001: Adopt Agentic Scaffold
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
The current project was not originally generated by `bootstrap-vdp-agentic.sh`, but future work should follow the structure and workflow that script creates.
|
||||
|
||||
## Decision
|
||||
|
||||
Move the existing Socialize implementation into the scaffold shape:
|
||||
|
||||
- backend project under `backend/src/Socialize.Api`
|
||||
- backend tests under `backend/tests/Socialize.Tests`
|
||||
- root scripts under `scripts/`
|
||||
- Docker Compose and Caddy deployment files
|
||||
- OpenAPI snapshot under `shared/openapi`
|
||||
- agentic docs under `docs/FEATURES`, `docs/TASKS`, `docs/PROMPTS`, and `docs/DECISIONS`
|
||||
|
||||
## Consequences
|
||||
|
||||
- Existing code is preserved.
|
||||
- Path-sensitive docs, scripts, and CI must target the new layout.
|
||||
- The frontend remains JavaScript for now, even though the generated scaffold uses Vue TypeScript.
|
||||
- Future work should use small task files and feature specs.
|
||||
71
docs/DEVELOPMENT_WORKFLOW.md
Normal file
71
docs/DEVELOPMENT_WORKFLOW.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# Development Workflow
|
||||
|
||||
## Before Coding
|
||||
|
||||
Read:
|
||||
|
||||
1. `README.md`
|
||||
2. `AGENTS.md`
|
||||
3. `docs/ARCHITECTURE.md`
|
||||
4. `docs/AGENTIC_WORKFLOW.md`
|
||||
5. `docs/DEVELOPMENT_WORKFLOW.md`
|
||||
6. Relevant feature spec in `docs/FEATURES/`
|
||||
7. Relevant task file in `docs/TASKS/`
|
||||
|
||||
## Backend
|
||||
|
||||
```bash
|
||||
./scripts/start-infrastructure.sh
|
||||
./scripts/dev-backend.sh
|
||||
```
|
||||
|
||||
Backend URL:
|
||||
|
||||
```txt
|
||||
http://localhost:5080
|
||||
```
|
||||
|
||||
Swagger UI:
|
||||
|
||||
```txt
|
||||
http://localhost:5080/api
|
||||
```
|
||||
|
||||
## Frontend
|
||||
|
||||
```bash
|
||||
./scripts/dev-frontend.sh
|
||||
```
|
||||
|
||||
Frontend URL:
|
||||
|
||||
```txt
|
||||
http://localhost:5173
|
||||
```
|
||||
|
||||
## API Model Sync
|
||||
|
||||
When backend request/response models change:
|
||||
|
||||
```bash
|
||||
./scripts/update-openapi.sh
|
||||
```
|
||||
|
||||
Then check frontend build errors.
|
||||
|
||||
## Validation
|
||||
|
||||
```bash
|
||||
dotnet build backend/Socialize.slnx
|
||||
dotnet test backend/Socialize.slnx
|
||||
cd frontend && npm run build
|
||||
```
|
||||
|
||||
## Commit Discipline
|
||||
|
||||
Use Conventional Commits:
|
||||
|
||||
```bash
|
||||
git commit -m "feat: add content approval request flow"
|
||||
git commit -m "docs: add agentic workflow tasks"
|
||||
```
|
||||
60
docs/FEATURES/platform-scaffold.md
Normal file
60
docs/FEATURES/platform-scaffold.md
Normal file
@@ -0,0 +1,60 @@
|
||||
# Feature: Agentic Platform Scaffold
|
||||
|
||||
## Status
|
||||
|
||||
In Progress
|
||||
|
||||
## Goal
|
||||
|
||||
Align Socialize with the structure generated by `bootstrap-vdp-agentic.sh` while preserving the current product implementation.
|
||||
|
||||
## Backend
|
||||
|
||||
The backend is located at:
|
||||
|
||||
```txt
|
||||
backend/src/Socialize.Api
|
||||
```
|
||||
|
||||
The solution is:
|
||||
|
||||
```txt
|
||||
backend/Socialize.slnx
|
||||
```
|
||||
|
||||
The test project is:
|
||||
|
||||
```txt
|
||||
backend/tests/Socialize.Tests
|
||||
```
|
||||
|
||||
## Frontend
|
||||
|
||||
The frontend remains the existing Vue 3 app. The scaffold directories `frontend/src/api`, `frontend/src/features`, `frontend/src/pages`, `frontend/src/layouts`, and `frontend/src/app` are available for incremental migration.
|
||||
|
||||
## API Contract
|
||||
|
||||
OpenAPI workflow:
|
||||
|
||||
```bash
|
||||
./scripts/update-openapi.sh
|
||||
```
|
||||
|
||||
Writes:
|
||||
|
||||
```txt
|
||||
shared/openapi/openapi.json
|
||||
frontend/src/api/schema.d.ts
|
||||
```
|
||||
|
||||
## Done When
|
||||
|
||||
- [x] Backend code lives under `backend/src/Socialize.Api`
|
||||
- [x] Backend solution exists at `backend/Socialize.slnx`
|
||||
- [x] Test project exists under `backend/tests/Socialize.Tests`
|
||||
- [x] Root scripts exist
|
||||
- [x] Docker Compose and Caddy files exist
|
||||
- [x] Agentic docs, specs, tasks, and prompts exist
|
||||
- [ ] OpenAPI generation verified against a running backend
|
||||
- [x] Backend build passes
|
||||
- [x] Frontend build passes
|
||||
52
docs/FEATURES/workspace-review-workflow.md
Normal file
52
docs/FEATURES/workspace-review-workflow.md
Normal file
@@ -0,0 +1,52 @@
|
||||
# Feature: Workspace Review Workflow
|
||||
|
||||
## Status
|
||||
|
||||
Draft
|
||||
|
||||
## Goal
|
||||
|
||||
Support workspace-scoped social media content review from content creation through comments, revision, approval, and ready-to-publish handoff.
|
||||
|
||||
## User Stories
|
||||
|
||||
- As a social media manager, I want content items grouped by workspace, client, and project so that I can manage review work for multiple accounts.
|
||||
- As a client approver, I want one clear place to review content, comment, and approve or request changes.
|
||||
- As an account manager, I want notifications and review queues so that work does not stall silently.
|
||||
|
||||
## Backend Modules
|
||||
|
||||
- Identity
|
||||
- Workspaces
|
||||
- Clients
|
||||
- Projects
|
||||
- ContentItems
|
||||
- Assets
|
||||
- Comments
|
||||
- Approvals
|
||||
- Notifications
|
||||
|
||||
## Frontend Areas
|
||||
|
||||
- `/app`
|
||||
- `/app/workspaces/new`
|
||||
- `/app/clients`
|
||||
- `/app/projects`
|
||||
- `/app/content`
|
||||
- `/app/content/:id`
|
||||
- `/app/reviews`
|
||||
- `/app/settings`
|
||||
|
||||
## Domain Rules
|
||||
|
||||
- Workspace is the top-level scoping boundary.
|
||||
- Content items belong to a workspace and may belong to a client or project.
|
||||
- Comments, approvals, assets, and notifications must remain traceable to the workflow entity they relate to.
|
||||
- Ready-to-publish state should come from explicit approval workflow transitions.
|
||||
|
||||
## Done When
|
||||
|
||||
- [ ] Workspace access is enforced consistently
|
||||
- [ ] Content item lifecycle is documented as a state machine
|
||||
- [ ] Approval decisions create traceable notifications/events
|
||||
- [ ] Review queue behavior is covered by tasks and validation
|
||||
@@ -1,593 +1,20 @@
|
||||
# LLM Development Workflow
|
||||
|
||||
## Purpose
|
||||
This document defines how to use coding agents such as Codex, Claude Code, ChatGPT, or similar tools on this repository without losing architectural coherence over time.
|
||||
This document is kept as a compatibility pointer for older references.
|
||||
|
||||
The core rule is simple:
|
||||
The current agentic workflow now lives in:
|
||||
|
||||
- `docs/AGENTIC_WORKFLOW.md`
|
||||
- `docs/DEVELOPMENT_WORKFLOW.md`
|
||||
- `docs/ARCHITECTURE.md`
|
||||
- `docs/CONVENTIONS.md`
|
||||
- `docs/FEATURES/`
|
||||
- `docs/TASKS/`
|
||||
- `docs/PROMPTS/`
|
||||
- `docs/DECISIONS/`
|
||||
|
||||
Core rule:
|
||||
|
||||
> The repository is the source of truth. The chat is only a temporary execution surface.
|
||||
|
||||
Coding agents should not rely on long conversation history to understand the product, architecture, or current task. Important context must live in versioned files inside the repository.
|
||||
|
||||
## Why This Workflow Exists
|
||||
|
||||
LLM coding tools are very strong at creating an initial project or implementing isolated changes. They become less reliable when the work shifts from greenfield generation to incremental product engineering.
|
||||
|
||||
The common failure mode is this:
|
||||
|
||||
1. The first prompt creates a large amount of useful code.
|
||||
2. Later prompts become increasingly specific and corrective.
|
||||
3. The agent starts forgetting prior decisions, duplicating patterns, inventing architecture, or changing unrelated files.
|
||||
4. Most of the work becomes re-explaining context instead of shipping features.
|
||||
|
||||
This does not mean the tools are useless. It means the workflow must change.
|
||||
|
||||
Early-stage prompting can be broad. Mature product work must be driven by stable docs, scoped tasks, acceptance criteria, and reviewable diffs.
|
||||
|
||||
## Operating Model
|
||||
|
||||
Use coding agents as fast implementation partners, not as autonomous product owners.
|
||||
|
||||
Agents should:
|
||||
|
||||
- read repository documentation first;
|
||||
- understand the current task before editing;
|
||||
- propose a small implementation plan;
|
||||
- make minimal, reviewable changes;
|
||||
- preserve existing architecture and conventions;
|
||||
- report risks, assumptions, and validation steps.
|
||||
|
||||
Agents should not:
|
||||
|
||||
- use chat history as the primary source of truth;
|
||||
- invent product behavior when docs are missing;
|
||||
- perform broad rewrites during a feature task;
|
||||
- silently change unrelated files;
|
||||
- mix backend, frontend, database, UX, and refactoring work without a scoped plan.
|
||||
|
||||
## Repository Documentation Model
|
||||
|
||||
The repository should contain a small set of durable documents that agents always consult.
|
||||
|
||||
Recommended structure:
|
||||
|
||||
```text
|
||||
docs/
|
||||
PRODUCT.md
|
||||
ARCHITECTURE.md
|
||||
CONVENTIONS.md
|
||||
DECISIONS.md
|
||||
BACKLOG.md
|
||||
LLM_DEVELOPMENT_WORKFLOW.md
|
||||
tasks/
|
||||
TASK-001-example.md
|
||||
TASK-002-example.md
|
||||
AGENTS.md
|
||||
```
|
||||
|
||||
### `AGENTS.md`
|
||||
|
||||
`AGENTS.md` is the entry point for coding agents.
|
||||
|
||||
It should tell agents:
|
||||
|
||||
- how to work in this repo;
|
||||
- what docs to read first;
|
||||
- how the backend and frontend are structured;
|
||||
- what commands to run;
|
||||
- what rules are non-negotiable;
|
||||
- how to validate work before finishing.
|
||||
|
||||
This file should stay concise enough that agents actually follow it.
|
||||
|
||||
### `docs/PRODUCT.md`
|
||||
|
||||
Defines the product from the user's perspective.
|
||||
|
||||
Include:
|
||||
|
||||
- what the product is;
|
||||
- target users;
|
||||
- major workflows;
|
||||
- important UX principles;
|
||||
- feature boundaries;
|
||||
- what the product explicitly does not do yet.
|
||||
|
||||
Use this file to prevent agents from inventing product behavior.
|
||||
|
||||
### `docs/ARCHITECTURE.md`
|
||||
|
||||
Defines the technical structure.
|
||||
|
||||
Include:
|
||||
|
||||
- backend architecture;
|
||||
- frontend architecture;
|
||||
- module boundaries;
|
||||
- authentication model;
|
||||
- data ownership;
|
||||
- routing model;
|
||||
- state management model;
|
||||
- API integration patterns.
|
||||
|
||||
Use this file to prevent agents from inventing new architecture for each task.
|
||||
|
||||
### `docs/CONVENTIONS.md`
|
||||
|
||||
Defines repeatable implementation patterns.
|
||||
|
||||
Include:
|
||||
|
||||
- C# style and backend endpoint conventions;
|
||||
- FastEndpoints patterns;
|
||||
- EF Core migration rules;
|
||||
- Vue component conventions;
|
||||
- Pinia store conventions;
|
||||
- API client usage;
|
||||
- validation and error handling patterns;
|
||||
- testing expectations;
|
||||
- naming conventions.
|
||||
|
||||
Use this file to reduce code style drift.
|
||||
|
||||
### `docs/DECISIONS.md`
|
||||
|
||||
A lightweight architecture decision log.
|
||||
|
||||
Each entry should capture:
|
||||
|
||||
- date;
|
||||
- decision;
|
||||
- context;
|
||||
- consequences.
|
||||
|
||||
Example:
|
||||
|
||||
```md
|
||||
## 2026-04-23 — Runtime frontend config is centralized
|
||||
|
||||
Decision: Frontend runtime configuration must be accessed through `frontend/src/config.js`.
|
||||
|
||||
Context: Direct `import.meta.env` reads scattered across feature code make configuration harder to audit.
|
||||
|
||||
Consequence: New frontend code should import config from `frontend/src/config.js` instead of reading env variables directly.
|
||||
```
|
||||
|
||||
Use this file to prevent agents from revisiting settled choices.
|
||||
|
||||
### `docs/BACKLOG.md`
|
||||
|
||||
A human-readable backlog of possible future work.
|
||||
|
||||
Use this for ideas, improvements, bugs, and deferred refactors.
|
||||
|
||||
Important rule:
|
||||
|
||||
> If an agent sees an adjacent problem that is outside the current task, it should add or suggest a backlog item instead of fixing it opportunistically.
|
||||
|
||||
### `docs/tasks/TASK-xxx.md`
|
||||
|
||||
Task files are the LLM-friendly equivalent of Jira tickets.
|
||||
|
||||
They are not just backend tickets. A product feature is usually fullstack and should describe backend, frontend, UX behavior, data model, validation, and acceptance criteria.
|
||||
|
||||
The task file should be specific enough that a fresh agent can implement it without reading a long chat thread.
|
||||
|
||||
## Task File Template
|
||||
|
||||
Use this template for implementation tasks.
|
||||
|
||||
```md
|
||||
# TASK-000 — Short Feature Name
|
||||
|
||||
## Status
|
||||
Draft | Ready | In Progress | Done | Blocked
|
||||
|
||||
## Objective
|
||||
Describe the user-visible or technical outcome in 1-3 sentences.
|
||||
|
||||
## Product Context
|
||||
Explain why this exists and where it fits in the product workflow.
|
||||
|
||||
## Scope
|
||||
- What this task includes.
|
||||
- Keep this list concrete.
|
||||
|
||||
## Out of Scope
|
||||
- What this task explicitly must not include.
|
||||
- Add adjacent ideas here to prevent scope creep.
|
||||
|
||||
## Existing References
|
||||
Agents must inspect these before implementation:
|
||||
- `docs/PRODUCT.md`
|
||||
- `docs/ARCHITECTURE.md`
|
||||
- `docs/CONVENTIONS.md`
|
||||
- relevant existing backend files
|
||||
- relevant existing frontend files
|
||||
|
||||
## Backend Requirements
|
||||
### API Contract
|
||||
Endpoint:
|
||||
- `METHOD /api/example`
|
||||
|
||||
Request:
|
||||
```json
|
||||
{
|
||||
"example": "value"
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"id": "string"
|
||||
}
|
||||
```
|
||||
|
||||
### Validation
|
||||
- Rule 1
|
||||
- Rule 2
|
||||
|
||||
### Data / Persistence
|
||||
- Entity changes, if any.
|
||||
- DbContext/module affected, if any.
|
||||
- Migration required: yes/no.
|
||||
|
||||
### Security / Authorization
|
||||
- Authentication required: yes/no.
|
||||
- Roles or workspace access rules.
|
||||
|
||||
## Frontend Requirements
|
||||
### Route / Screen
|
||||
- Route: `/app/example`
|
||||
- View file: `frontend/src/views/app/ExampleView.vue`
|
||||
|
||||
### Components
|
||||
- `ExampleForm.vue`
|
||||
- `ExampleList.vue`
|
||||
|
||||
### State Management
|
||||
- Pinia store used or created.
|
||||
- Existing store actions to reuse.
|
||||
|
||||
### API Integration
|
||||
- Existing API client usage.
|
||||
- Expected loading, success, and error behavior.
|
||||
|
||||
### UX Behavior
|
||||
- Empty state.
|
||||
- Loading state.
|
||||
- Validation display.
|
||||
- Toasts or inline errors.
|
||||
- Navigation after success, if any.
|
||||
|
||||
## Files Likely Involved
|
||||
Backend:
|
||||
- `backend/...`
|
||||
|
||||
Frontend:
|
||||
- `frontend/...`
|
||||
|
||||
Docs:
|
||||
- `docs/...`
|
||||
|
||||
## Acceptance Criteria
|
||||
- User can complete the intended workflow.
|
||||
- Backend validates invalid input correctly.
|
||||
- Frontend displays loading and error states correctly.
|
||||
- Existing auth, workspace scoping, and refresh behavior are preserved.
|
||||
- Build passes.
|
||||
|
||||
## Validation Plan
|
||||
Backend:
|
||||
- `cd backend && dotnet build Socialize.Api.csproj`
|
||||
- Additional manual or automated checks.
|
||||
|
||||
Frontend:
|
||||
- `cd frontend && npm run build`
|
||||
- Additional manual route/store checks.
|
||||
|
||||
## Risks / Edge Cases
|
||||
- Risk 1
|
||||
- Risk 2
|
||||
|
||||
## Open Questions
|
||||
- Question 1
|
||||
```
|
||||
|
||||
## Feature Definition: Fullstack by Default
|
||||
|
||||
A feature should normally be defined across these dimensions:
|
||||
|
||||
1. Product workflow: what the user is trying to accomplish.
|
||||
2. UX behavior: screens, states, feedback, errors, navigation.
|
||||
3. Frontend implementation: routes, components, stores, API calls.
|
||||
4. Backend implementation: endpoints, validation, persistence, authorization.
|
||||
5. Data model: entities, migrations, ownership boundaries.
|
||||
6. Acceptance criteria: what must be true before the task is done.
|
||||
7. Validation plan: commands and manual checks.
|
||||
|
||||
Avoid defining features as backend-only unless the task is explicitly backend-only.
|
||||
|
||||
## Recommended Agent Workflow
|
||||
|
||||
Use this sequence for non-trivial changes.
|
||||
|
||||
### 1. Prepare or update the task file
|
||||
|
||||
Create a `docs/tasks/TASK-xxx.md` file before asking an agent to implement a feature.
|
||||
|
||||
The task can be rough at first, but it must state:
|
||||
|
||||
- objective;
|
||||
- scope;
|
||||
- out of scope;
|
||||
- backend requirements, if any;
|
||||
- frontend requirements, if any;
|
||||
- acceptance criteria.
|
||||
|
||||
### 2. Start a fresh agent thread per task
|
||||
|
||||
Do not run an entire project through one endless chat.
|
||||
|
||||
Use one thread for one task or one small group of tightly related subtasks.
|
||||
|
||||
### 3. Ask for analysis before implementation
|
||||
|
||||
Default prompt:
|
||||
|
||||
```text
|
||||
Read AGENTS.md and the relevant docs first.
|
||||
Then read docs/tasks/TASK-000-short-name.md.
|
||||
Do not edit files yet.
|
||||
Summarize the task, identify the relevant backend and frontend files, list risks, and propose a minimal implementation plan.
|
||||
```
|
||||
|
||||
### 4. Implement one bounded step at a time
|
||||
|
||||
Default prompt:
|
||||
|
||||
```text
|
||||
Implement only step 1 from the plan.
|
||||
Keep the diff minimal.
|
||||
Do not refactor unrelated code.
|
||||
Do not change public behavior outside this task.
|
||||
At the end, summarize changes and list validation steps.
|
||||
```
|
||||
|
||||
### 5. Review the diff
|
||||
|
||||
The repository owner reviews:
|
||||
|
||||
- scope creep;
|
||||
- architectural drift;
|
||||
- duplicated code;
|
||||
- inconsistent UI behavior;
|
||||
- unsafe auth or workspace scoping changes;
|
||||
- broken conventions.
|
||||
|
||||
### 6. Validate
|
||||
|
||||
Run the relevant commands from `AGENTS.md` and the task file.
|
||||
|
||||
Minimum expected validation:
|
||||
|
||||
- backend build for backend changes;
|
||||
- frontend build for frontend changes;
|
||||
- affected user flow checked manually when UI behavior changes.
|
||||
|
||||
### 7. Update docs if the task changed architecture or product behavior
|
||||
|
||||
If implementation creates a durable decision, update `docs/DECISIONS.md`.
|
||||
|
||||
If implementation changes structure, update `docs/ARCHITECTURE.md`.
|
||||
|
||||
If implementation changes conventions, update `docs/CONVENTIONS.md`.
|
||||
|
||||
If implementation changes user-facing behavior, update `docs/PRODUCT.md`.
|
||||
|
||||
## Prompt Patterns
|
||||
|
||||
### Planning Prompt
|
||||
|
||||
```text
|
||||
You are working in an existing repository.
|
||||
|
||||
First read:
|
||||
- AGENTS.md
|
||||
- docs/PRODUCT.md
|
||||
- docs/ARCHITECTURE.md
|
||||
- docs/CONVENTIONS.md
|
||||
- docs/DECISIONS.md
|
||||
- docs/tasks/TASK-000-short-name.md
|
||||
|
||||
Do not edit files yet.
|
||||
|
||||
Return:
|
||||
1. summary of the task;
|
||||
2. relevant existing files;
|
||||
3. backend impact;
|
||||
4. frontend impact;
|
||||
5. risks and ambiguities;
|
||||
6. minimal implementation plan;
|
||||
7. validation plan.
|
||||
```
|
||||
|
||||
### Implementation Prompt
|
||||
|
||||
```text
|
||||
Implement the task from docs/tasks/TASK-000-short-name.md.
|
||||
|
||||
Rules:
|
||||
- follow AGENTS.md;
|
||||
- follow docs/ARCHITECTURE.md and docs/CONVENTIONS.md;
|
||||
- keep the diff minimal;
|
||||
- do not refactor unrelated code;
|
||||
- preserve auth, workspace scoping, token refresh, and runtime config patterns;
|
||||
- if you discover missing requirements, stop and report them instead of inventing behavior.
|
||||
|
||||
At the end, provide:
|
||||
- files changed;
|
||||
- summary of behavior added;
|
||||
- validation performed;
|
||||
- validation still needed;
|
||||
- risks or follow-up items.
|
||||
```
|
||||
|
||||
### Frontend-Only Prompt
|
||||
|
||||
```text
|
||||
Implement only the frontend part of docs/tasks/TASK-000-short-name.md.
|
||||
|
||||
Do not modify backend code.
|
||||
Use existing routes, stores, API client, UI framework, and runtime config conventions.
|
||||
Preserve loading, error, empty, and success states described in the task.
|
||||
```
|
||||
|
||||
### Backend-Only Prompt
|
||||
|
||||
```text
|
||||
Implement only the backend part of docs/tasks/TASK-000-short-name.md.
|
||||
|
||||
Do not modify frontend code.
|
||||
Follow the existing FastEndpoints, validation, module, DbContext, and migration conventions.
|
||||
Preserve auth and workspace scoping rules.
|
||||
```
|
||||
|
||||
### Review Prompt
|
||||
|
||||
```text
|
||||
Review the current diff against:
|
||||
- AGENTS.md
|
||||
- docs/ARCHITECTURE.md
|
||||
- docs/CONVENTIONS.md
|
||||
- docs/tasks/TASK-000-short-name.md
|
||||
|
||||
Look specifically for:
|
||||
- scope creep;
|
||||
- architectural drift;
|
||||
- broken frontend state patterns;
|
||||
- broken backend module boundaries;
|
||||
- auth or workspace scoping regressions;
|
||||
- missing loading/error states;
|
||||
- missing validation;
|
||||
- missing tests or manual checks.
|
||||
|
||||
Do not edit files. Return findings only.
|
||||
```
|
||||
|
||||
## Rules for Frontend Work
|
||||
|
||||
Frontend changes must be explicit in the task.
|
||||
|
||||
A frontend task should identify:
|
||||
|
||||
- route or screen;
|
||||
- components to create or modify;
|
||||
- Pinia stores involved;
|
||||
- API calls involved;
|
||||
- loading state;
|
||||
- error state;
|
||||
- empty state;
|
||||
- success feedback;
|
||||
- navigation behavior;
|
||||
- role/access behavior;
|
||||
- responsive or layout expectations, if relevant.
|
||||
|
||||
Agents must not invent a new frontend architecture for a single feature.
|
||||
|
||||
They should reuse:
|
||||
|
||||
- existing Vue patterns;
|
||||
- existing Vuetify/Tailwind conventions;
|
||||
- existing Pinia stores where appropriate;
|
||||
- existing Axios client;
|
||||
- existing router guards;
|
||||
- existing toast/error patterns.
|
||||
|
||||
## Rules for Backend Work
|
||||
|
||||
Backend changes must respect module boundaries.
|
||||
|
||||
A backend task should identify:
|
||||
|
||||
- endpoint route and method;
|
||||
- request and response shape;
|
||||
- validation rules;
|
||||
- module ownership;
|
||||
- DbContext affected;
|
||||
- migration requirement;
|
||||
- authorization rules;
|
||||
- workspace scoping rules;
|
||||
- expected errors.
|
||||
|
||||
Agents must not couple module DbContexts or bypass existing auth/security helpers.
|
||||
|
||||
## Handling Ambiguity
|
||||
|
||||
When a requirement is unclear, agents should not silently invent behavior.
|
||||
|
||||
Preferred behavior:
|
||||
|
||||
1. State the ambiguity.
|
||||
2. Propose the safest default.
|
||||
3. Keep implementation narrow.
|
||||
4. Add an open question or backlog item if needed.
|
||||
|
||||
For small ambiguities that do not affect architecture or product behavior, the agent may choose the safest existing pattern and document the assumption.
|
||||
|
||||
For large ambiguities, the agent should stop before implementation.
|
||||
|
||||
## Handling Refactors
|
||||
|
||||
Refactors should be separate tasks unless they are strictly required for the current feature.
|
||||
|
||||
If a refactor is needed, the task should state:
|
||||
|
||||
- why the refactor is necessary;
|
||||
- what files are in scope;
|
||||
- what behavior must remain unchanged;
|
||||
- how to validate no regression occurred.
|
||||
|
||||
Agents should not do opportunistic cleanup in unrelated files.
|
||||
|
||||
## Handling Backlog Items
|
||||
|
||||
When an agent notices an issue outside scope, it should not fix it by default.
|
||||
|
||||
It should report it as:
|
||||
|
||||
```md
|
||||
Suggested backlog item:
|
||||
- Title:
|
||||
- Reason:
|
||||
- Affected files:
|
||||
- Risk if ignored:
|
||||
```
|
||||
|
||||
The repository owner can then decide whether to create a task.
|
||||
|
||||
## Definition of Done
|
||||
|
||||
A task is done when:
|
||||
|
||||
- implementation matches the task file;
|
||||
- scope and out-of-scope boundaries were respected;
|
||||
- relevant backend and/or frontend validation passed;
|
||||
- user-facing behavior was manually checked when applicable;
|
||||
- docs were updated if durable behavior or architecture changed;
|
||||
- remaining risks or follow-up items were explicitly listed.
|
||||
|
||||
## Practical Mental Model
|
||||
|
||||
Use this model:
|
||||
|
||||
- `AGENTS.md` tells the agent how to behave.
|
||||
- `docs/PRODUCT.md` tells the agent what the product is.
|
||||
- `docs/ARCHITECTURE.md` tells the agent how the system is shaped.
|
||||
- `docs/CONVENTIONS.md` tells the agent how to write code here.
|
||||
- `docs/DECISIONS.md` tells the agent what choices are already settled.
|
||||
- `docs/BACKLOG.md` stores ideas that are not current work.
|
||||
- `docs/tasks/TASK-xxx.md` tells the agent what to do now.
|
||||
|
||||
The more this information lives in the repo, the less each new prompt has to reconstruct the project from memory.
|
||||
For new work, create or update a feature spec in `docs/FEATURES/`, create a small task in `docs/TASKS/<feature>/`, and ask the agent to implement only that task.
|
||||
|
||||
47
docs/PRODUCT.md
Normal file
47
docs/PRODUCT.md
Normal file
@@ -0,0 +1,47 @@
|
||||
# Product
|
||||
|
||||
Socialize is a workflow application for social media content review, revision, approval, and publication readiness.
|
||||
|
||||
It is not a public social network. It is a workspace-based coordination tool for internal teams, providers, and client approvers.
|
||||
|
||||
## Primary Users
|
||||
|
||||
- Social media manager
|
||||
- Account manager or customer success manager
|
||||
- Client approver
|
||||
- External provider or production partner
|
||||
- Internal producer
|
||||
- Internal employee or content contributor
|
||||
- Administrator
|
||||
|
||||
## Core Product Shape
|
||||
|
||||
- workspace-based account boundary
|
||||
- agencies able to manage multiple workspaces
|
||||
- content items as the main reviewable unit
|
||||
- assets and revisions tracked against content items
|
||||
- comments and approvals attached to the work itself
|
||||
- notifications driven by workflow events
|
||||
|
||||
## Must Do Well
|
||||
|
||||
- centralize review state
|
||||
- preserve a clear audit trail
|
||||
- make the latest approved version obvious
|
||||
- support internal review before client review
|
||||
- support client-facing review with low friction
|
||||
- keep publication handoff clear once approval is complete
|
||||
|
||||
## Not In Version 1
|
||||
|
||||
- public social feed
|
||||
- full direct publishing engine
|
||||
- full DAM platform
|
||||
- analytics suite
|
||||
- billing or subscription flows
|
||||
|
||||
## Current Sources
|
||||
|
||||
- `docs/product/vision.md`
|
||||
- `docs/product/glossary.md`
|
||||
- `docs/constraints.md`
|
||||
30
docs/PROMPTS/backend-task.md
Normal file
30
docs/PROMPTS/backend-task.md
Normal file
@@ -0,0 +1,30 @@
|
||||
# Backend Task Prompt
|
||||
|
||||
You are implementing a backend task in this repository.
|
||||
|
||||
## Read First
|
||||
|
||||
- `AGENTS.md`
|
||||
- `docs/ARCHITECTURE.md`
|
||||
- `docs/DEVELOPMENT_WORKFLOW.md`
|
||||
- `docs/AGENTIC_WORKFLOW.md`
|
||||
- Relevant feature spec in `docs/FEATURES/`
|
||||
- Relevant task file in `docs/TASKS/`
|
||||
|
||||
## Instructions
|
||||
|
||||
- Implement only the requested backend task.
|
||||
- Keep code under `backend/src/Socialize.Api`.
|
||||
- Follow the existing FastEndpoints module structure.
|
||||
- Add or update tests under `backend/tests/Socialize.Tests` when the behavior is testable.
|
||||
- Do not introduce repository/service layers unless the task explicitly requires it.
|
||||
|
||||
## After Coding
|
||||
|
||||
Run or recommend:
|
||||
|
||||
```bash
|
||||
dotnet build backend/Socialize.slnx
|
||||
dotnet test backend/Socialize.slnx
|
||||
./scripts/update-openapi.sh
|
||||
```
|
||||
24
docs/PROMPTS/debug.md
Normal file
24
docs/PROMPTS/debug.md
Normal file
@@ -0,0 +1,24 @@
|
||||
# Debug Prompt
|
||||
|
||||
You are debugging a specific failure in this repository.
|
||||
|
||||
## Read First
|
||||
|
||||
- `AGENTS.md`
|
||||
- `docs/ARCHITECTURE.md`
|
||||
- `docs/DEVELOPMENT_WORKFLOW.md`
|
||||
|
||||
## Error
|
||||
|
||||
Paste the full error here.
|
||||
|
||||
## Instructions
|
||||
|
||||
- Identify the most likely root cause.
|
||||
- Make the smallest safe fix.
|
||||
- Do not refactor unrelated code.
|
||||
- Explain how to verify the fix.
|
||||
|
||||
## Validation
|
||||
|
||||
List the exact command or commands to run after the fix.
|
||||
30
docs/PROMPTS/frontend-task.md
Normal file
30
docs/PROMPTS/frontend-task.md
Normal file
@@ -0,0 +1,30 @@
|
||||
# Frontend Task Prompt
|
||||
|
||||
You are implementing a frontend task in this repository.
|
||||
|
||||
## Read First
|
||||
|
||||
- `AGENTS.md`
|
||||
- `docs/ARCHITECTURE.md`
|
||||
- `docs/DEVELOPMENT_WORKFLOW.md`
|
||||
- `docs/AGENTIC_WORKFLOW.md`
|
||||
- Relevant feature spec in `docs/FEATURES/`
|
||||
- Relevant task file in `docs/TASKS/`
|
||||
|
||||
## Instructions
|
||||
|
||||
- Implement only the requested frontend task.
|
||||
- Existing route-level app screens live under `frontend/src/views/app`.
|
||||
- New isolated feature slices should prefer `frontend/src/features/<feature>`.
|
||||
- Use `frontend/src/config.js` for runtime configuration.
|
||||
- Preserve token refresh behavior in `authStore` and `frontend/src/plugins/api.js`.
|
||||
- Use generated API types from `frontend/src/api/schema.d.ts` when the endpoint has been generated.
|
||||
|
||||
## After Coding
|
||||
|
||||
Run or recommend:
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm run build
|
||||
```
|
||||
29
docs/PROMPTS/refactor.md
Normal file
29
docs/PROMPTS/refactor.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# Refactor Prompt
|
||||
|
||||
You are refactoring part of this repository.
|
||||
|
||||
## Read First
|
||||
|
||||
- `AGENTS.md`
|
||||
- `docs/ARCHITECTURE.md`
|
||||
- `docs/AGENTIC_WORKFLOW.md`
|
||||
- Relevant feature spec
|
||||
|
||||
## Scope
|
||||
|
||||
Describe the exact refactor boundary.
|
||||
|
||||
## Rules
|
||||
|
||||
- Preserve behavior.
|
||||
- Do not add features.
|
||||
- Keep the diff focused.
|
||||
- Update docs if structure or workflow changes.
|
||||
- Run tests/builds after.
|
||||
|
||||
## Validation
|
||||
|
||||
```bash
|
||||
dotnet test backend/Socialize.slnx
|
||||
cd frontend && npm run build
|
||||
```
|
||||
37
docs/PROMPT_TEMPLATE.md
Normal file
37
docs/PROMPT_TEMPLATE.md
Normal file
@@ -0,0 +1,37 @@
|
||||
# General Agent Prompt Template
|
||||
|
||||
You are working in this repository.
|
||||
|
||||
## Read First
|
||||
|
||||
- `AGENTS.md`
|
||||
- `README.md`
|
||||
- `docs/ARCHITECTURE.md`
|
||||
- `docs/DEVELOPMENT_WORKFLOW.md`
|
||||
- `docs/AGENTIC_WORKFLOW.md`
|
||||
- `<feature spec>`
|
||||
- `<task file>`
|
||||
|
||||
## Task
|
||||
|
||||
Implement:
|
||||
|
||||
`<paste task title or path>`
|
||||
|
||||
## Rules
|
||||
|
||||
- Implement only this task.
|
||||
- Do not refactor unrelated code.
|
||||
- Follow existing backend/frontend structure.
|
||||
- Backend code currently belongs under `backend/src/Socialize.Api/Modules/<Feature>`.
|
||||
- New isolated frontend feature code should prefer `frontend/src/features/<feature>`.
|
||||
- If backend contracts change, update OpenAPI using `./scripts/update-openapi.sh`.
|
||||
- Do not manually duplicate generated API types when generated types exist.
|
||||
|
||||
## Output Expected
|
||||
|
||||
- Code changes
|
||||
- Tests where appropriate
|
||||
- Minimal docs update if behavior changed
|
||||
- Summary of what changed
|
||||
- Validation commands run
|
||||
@@ -1,32 +1,40 @@
|
||||
# Docs
|
||||
|
||||
This folder contains the project documentation used to guide product, implementation, and architecture work.
|
||||
This folder contains the project documentation used to guide product, implementation, architecture, and agentic development work.
|
||||
|
||||
## Current Product Docs
|
||||
## Start Here
|
||||
|
||||
- [product/vision.md](/home/jbourdon/repos/social-media/docs/product/vision.md): current product intent, users, scope, and priorities.
|
||||
- [product/glossary.md](/home/jbourdon/repos/social-media/docs/product/glossary.md): canonical domain vocabulary. Prefer these terms in code, UI copy, and specs.
|
||||
- [constraints.md](/home/jbourdon/repos/social-media/docs/constraints.md): business and technical invariants that should not be violated casually.
|
||||
- [AGENTIC_WORKFLOW.md](/home/jbourdon/repos/social-media/docs/AGENTIC_WORKFLOW.md): human + agent development loop.
|
||||
- [ARCHITECTURE.md](/home/jbourdon/repos/social-media/docs/ARCHITECTURE.md): technical structure and module boundaries.
|
||||
- [DEVELOPMENT_WORKFLOW.md](/home/jbourdon/repos/social-media/docs/DEVELOPMENT_WORKFLOW.md): local commands and validation.
|
||||
- [PRODUCT.md](/home/jbourdon/repos/social-media/docs/PRODUCT.md): current product definition.
|
||||
- [CONVENTIONS.md](/home/jbourdon/repos/social-media/docs/CONVENTIONS.md): implementation and documentation conventions.
|
||||
|
||||
## Current Delivery Docs
|
||||
## Agentic Scaffold
|
||||
|
||||
- [use-cases/review-workflows.md](/home/jbourdon/repos/social-media/docs/use-cases/review-workflows.md): scenario-driven workflow descriptions.
|
||||
- [specs/content-approval-workflow.md](/home/jbourdon/repos/social-media/docs/specs/content-approval-workflow.md): structured feature spec for the primary workflow.
|
||||
- [specs/TEMPLATE.md](/home/jbourdon/repos/social-media/docs/specs/TEMPLATE.md): template for future feature specs.
|
||||
- [FEATURES/](/home/jbourdon/repos/social-media/docs/FEATURES): feature specs and product behavior.
|
||||
- [TASKS/](/home/jbourdon/repos/social-media/docs/TASKS): small implementation tickets for agents.
|
||||
- [PROMPTS/](/home/jbourdon/repos/social-media/docs/PROMPTS): reusable task prompts.
|
||||
- [DECISIONS/](/home/jbourdon/repos/social-media/docs/DECISIONS): decision records.
|
||||
- [FEATURE_TEMPLATE.md](/home/jbourdon/repos/social-media/docs/FEATURE_TEMPLATE.md): feature spec template.
|
||||
- [TASK_TEMPLATE.md](/home/jbourdon/repos/social-media/docs/TASK_TEMPLATE.md): task template.
|
||||
- [PROMPT_TEMPLATE.md](/home/jbourdon/repos/social-media/docs/PROMPT_TEMPLATE.md): general prompt template.
|
||||
|
||||
## Decision Records
|
||||
## Current Product Sources
|
||||
|
||||
- [decisions/README.md](/home/jbourdon/repos/social-media/docs/decisions/README.md): ADR conventions and when to add a decision record.
|
||||
- [decisions/ADR-TEMPLATE.md](/home/jbourdon/repos/social-media/docs/decisions/ADR-TEMPLATE.md): template for new architecture or product decisions.
|
||||
- [product/vision.md](/home/jbourdon/repos/social-media/docs/product/vision.md): product intent, users, scope, and priorities.
|
||||
- [product/glossary.md](/home/jbourdon/repos/social-media/docs/product/glossary.md): canonical domain vocabulary.
|
||||
- [constraints.md](/home/jbourdon/repos/social-media/docs/constraints.md): business and technical invariants.
|
||||
- [BACKLOG.md](/home/jbourdon/repos/social-media/docs/BACKLOG.md): deferred technical and product work.
|
||||
|
||||
## Archived
|
||||
|
||||
- [archive/PLAN.md](/home/jbourdon/repos/social-media/docs/archive/PLAN.md): early pivot plan; useful for historical context, but stale as an execution checklist.
|
||||
- [archive/SOCIALIZE.md](/home/jbourdon/repos/social-media/docs/archive/SOCIALIZE.md): original consolidated product brief before the docs were split into focused source-of-truth files.
|
||||
- [archive/Stripe.md](/home/jbourdon/repos/social-media/docs/archive/Stripe.md): legacy Hutopy monetization notes for memberships and tips.
|
||||
- [archive/WORKSHEET.md](/home/jbourdon/repos/social-media/docs/archive/WORKSHEET.md): historical implementation worksheet from an earlier transition phase.
|
||||
- [archive/PLAN.md](/home/jbourdon/repos/social-media/docs/archive/PLAN.md): early pivot plan.
|
||||
- [archive/SOCIALIZE.md](/home/jbourdon/repos/social-media/docs/archive/SOCIALIZE.md): original consolidated product brief.
|
||||
- [archive/Stripe.md](/home/jbourdon/repos/social-media/docs/archive/Stripe.md): legacy Hutopy monetization notes.
|
||||
- [archive/WORKSHEET.md](/home/jbourdon/repos/social-media/docs/archive/WORKSHEET.md): historical transition worksheet.
|
||||
|
||||
## Root Docs
|
||||
|
||||
- [README.md](/home/jbourdon/repos/social-media/README.md): repository overview and local development setup.
|
||||
- [AGENTS.md](/home/jbourdon/repos/social-media/AGENTS.md): working guide for coding agents. This stays at repo root intentionally.
|
||||
- [AGENTS.md](/home/jbourdon/repos/social-media/AGENTS.md): working guide for coding agents.
|
||||
|
||||
@@ -0,0 +1,64 @@
|
||||
# Task: Align repository with bootstrap scaffold
|
||||
|
||||
## Feature
|
||||
|
||||
`docs/FEATURES/platform-scaffold.md`
|
||||
|
||||
## Goal
|
||||
|
||||
Move the current Socialize repository into the structure that `bootstrap-vdp-agentic.sh` would have generated, without replacing the existing product implementation.
|
||||
|
||||
## Context
|
||||
|
||||
The script generates a simple .NET + Vue monorepo with:
|
||||
|
||||
- backend under `backend/src/<App>.Api`
|
||||
- tests under `backend/tests/<App>.Tests`
|
||||
- root scripts under `scripts/`
|
||||
- Docker Compose and Caddy deployment files
|
||||
- OpenAPI sync into `shared/openapi`
|
||||
- agentic docs under `docs/FEATURES`, `docs/TASKS`, `docs/PROMPTS`, and `docs/DECISIONS`
|
||||
|
||||
Socialize already has a larger FastEndpoints backend and Vue app. Preserve that implementation while adopting the scaffold.
|
||||
|
||||
## Files Likely To Change
|
||||
|
||||
- `backend/Socialize.slnx`
|
||||
- `backend/src/Socialize.Api/**`
|
||||
- `backend/tests/Socialize.Tests/**`
|
||||
- `scripts/**`
|
||||
- `deploy/caddy/Caddyfile`
|
||||
- `docker-compose.yml`
|
||||
- `docs/**`
|
||||
- `README.md`
|
||||
- `AGENTS.md`
|
||||
- `.github/workflows/backend-ci.yml`
|
||||
- `frontend/package.json`
|
||||
- `frontend/scripts/fetch-openapi.mjs`
|
||||
- `frontend/src/api/schema.d.ts`
|
||||
|
||||
## Constraints
|
||||
|
||||
- Preserve existing product code.
|
||||
- Do not convert the frontend to TypeScript in this task.
|
||||
- Do not rewrite backend modules into minimal API folders in this task.
|
||||
- Do not introduce new secrets.
|
||||
|
||||
## Done When
|
||||
|
||||
- [x] Backend implementation moved under `backend/src/Socialize.Api`
|
||||
- [x] Backend solution points at the new project path
|
||||
- [x] Test project scaffold exists
|
||||
- [x] Root scripts exist
|
||||
- [x] OpenAPI sync command exists
|
||||
- [x] Agentic docs/specs/tasks/prompts exist
|
||||
- [x] Backend build passes
|
||||
- [x] Frontend build passes
|
||||
|
||||
## Validation Commands
|
||||
|
||||
```bash
|
||||
dotnet build backend/Socialize.slnx
|
||||
dotnet test backend/Socialize.slnx
|
||||
cd frontend && npm run build
|
||||
```
|
||||
@@ -0,0 +1,39 @@
|
||||
# Task: Document content state machine
|
||||
|
||||
## Feature
|
||||
|
||||
`docs/FEATURES/workspace-review-workflow.md`
|
||||
|
||||
## Goal
|
||||
|
||||
Define the current and intended content item states, transitions, and approval side effects before further workflow implementation.
|
||||
|
||||
## Context
|
||||
|
||||
The code already contains content items, approvals, comments, assets, notifications, and review queue screens. The workflow needs one durable spec so future agents do not infer state transitions from scattered UI code.
|
||||
|
||||
## Files Likely To Change
|
||||
|
||||
- `docs/FEATURES/workspace-review-workflow.md`
|
||||
- `docs/FEATURES/content-approval-workflow.md`
|
||||
- optionally `docs/DECISIONS/*.md`
|
||||
|
||||
## Constraints
|
||||
|
||||
- Documentation-only task.
|
||||
- Do not change backend or frontend code.
|
||||
- Distinguish current behavior from proposed behavior.
|
||||
|
||||
## Done When
|
||||
|
||||
- [ ] States are listed
|
||||
- [ ] Allowed transitions are listed
|
||||
- [ ] Actor permissions are listed
|
||||
- [ ] Notification side effects are listed
|
||||
- [ ] Open questions are explicit
|
||||
|
||||
## Validation Commands
|
||||
|
||||
```bash
|
||||
git diff -- docs/FEATURES docs/DECISIONS
|
||||
```
|
||||
46
docs/TASK_TEMPLATE.md
Normal file
46
docs/TASK_TEMPLATE.md
Normal file
@@ -0,0 +1,46 @@
|
||||
# Task: <Task Name>
|
||||
|
||||
## Feature
|
||||
|
||||
`docs/FEATURES/<feature>.md`
|
||||
|
||||
## Goal
|
||||
|
||||
One concrete change.
|
||||
|
||||
## Context
|
||||
|
||||
What the agent needs to know before coding.
|
||||
|
||||
## Files Likely To Change
|
||||
|
||||
- `backend/src/Socialize.Api/...`
|
||||
- `frontend/src/...`
|
||||
- `docs/...`
|
||||
|
||||
## Constraints
|
||||
|
||||
- Follow existing architecture.
|
||||
- Do not refactor unrelated files.
|
||||
- Do not manually duplicate generated API types when generated types exist.
|
||||
- Keep the diff focused.
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
1. Step one.
|
||||
2. Step two.
|
||||
3. Step three.
|
||||
|
||||
## Done When
|
||||
|
||||
- [ ] Code implemented
|
||||
- [ ] Tests/build pass
|
||||
- [ ] OpenAPI regenerated if backend contracts changed
|
||||
- [ ] Docs updated if behavior changed
|
||||
|
||||
## Validation Commands
|
||||
|
||||
```bash
|
||||
dotnet test backend/Socialize.slnx
|
||||
cd frontend && npm run build
|
||||
```
|
||||
Reference in New Issue
Block a user