Add project documentation and update workflow plan

Adds AGENTS.md, DESIGN.md, and docs/* covering architecture, conventions, decisions, checklists, branching, release process, and prompts. Updates README and workflow-feedback-plan to reflect the decoupled GroupName nomination model. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-28 23:31:13 +02:00
parent 18b61bed52
commit fc5c13a4fd
13 changed files with 1670 additions and 15 deletions
@@ -0,0 +1,124 @@
+# Development Workflow
+
+This document defines the default path from idea to released change.
+
+For branch policy, see [branching.md](branching.md). For release execution, see
+[release-process.md](release-process.md). For task quality gates, see
+[CHECKLISTS.md](CHECKLISTS.md).
+
+## Workflow Overview
+
+```mermaid
+flowchart LR
+    Idea["Idea, bug, or feedback"]
+    Clarify["Clarify scope"]
+    Plan["Plan or ADR"]
+    Implement["Implement"]
+    Validate["Validate"]
+    Review["Review"]
+    Merge["Merge"]
+    Release["Release"]
+    Learn["Update docs/checklists"]
+
+    Idea --> Clarify
+    Clarify --> Plan
+    Plan --> Implement
+    Implement --> Validate
+    Validate --> Review
+    Review --> Merge
+    Merge --> Release
+    Release --> Learn
+```
+
+## 1. Clarify Scope
+
+Before implementation:
+
+- restate the objective in engineering terms;
+- identify affected public, admin, backend, database, or deployment surfaces;
+- confirm acceptance criteria and non-goals;
+- identify security, authorization, migration, data-loss, or live-production
+  risk;
+- ask concise questions when ambiguity affects important behavior.
+
+## 2. Inspect Existing Context
+
+Read the relevant source and docs before editing:
+
+- [PROJECT.md](PROJECT.md) for runtime and product facts;
+- [ARCHITECTURE.md](ARCHITECTURE.md) for boundaries;
+- [CONVENTIONS.md](CONVENTIONS.md) for coding standards;
+- [DECISIONS.md](DECISIONS.md) for durable trade-offs;
+- [../DESIGN.md](../DESIGN.md) for UI work;
+- feature plans such as [workflow-feedback-plan.md](workflow-feedback-plan.md)
+  when the task builds on planned product feedback.
+
+## 3. Plan The Change
+
+Use a lightweight plan for non-trivial changes. Create or update an ADR when
+the change affects:
+
+- architecture style or module boundaries;
+- data ownership or public contracts;
+- authentication, authorization, or security posture;
+- deployment strategy, migrations, or long-term operating cost.
+
+## 4. Implement
+
+Implementation expectations:
+
+- keep changes focused and reviewable;
+- follow existing frontend/backend patterns;
+- split large Vue surfaces into smaller components or composables;
+- keep backend/admin data authoritative for public behavior;
+- avoid unrelated refactors unless needed for the requested change;
+- preserve user changes in a dirty worktree.
+
+## 5. Validate
+
+Default validation:
+
+```bash
+cd frontend
+npm run build
+
+cd ..
+dotnet build Backend/Backend.csproj --configuration Release
+git diff --check
+```
+
+Add targeted validation by risk:
+
+- API checks for backend behavior;
+- authenticated checks for admin/team/permission changes;
+- browser checks for visible UI changes;
+- responsive geometry checks for layout work;
+- database health and migration checks for schema changes;
+- live checks only for release or explicitly live-scoped work.
+
+When frontend and backend are both actively used for local verification, keep
+them running as a pair or shut both down together.
+
+## 6. Review
+
+Review should answer:
+
+- Does the change solve the stated problem?
+- Does it preserve backend/admin truth?
+- Is authorization enforced at the trusted boundary?
+- Are migrations and deployment risk understood?
+- Are docs and validation sufficient for the risk?
+
+## 7. Merge And Release
+
+`main` is the production deployment branch. Pushes to `main` run CI and deploy
+when the workflow conditions match. Follow [release-process.md](release-process.md).
+
+## 8. Learn
+
+After meaningful releases, regressions, or repeated review feedback:
+
+- update docs or checklists;
+- add or update ADRs;
+- add regression coverage when practical;
+- record follow-up work where the repo exposes an operational or test gap.