chore: moving towards agentic development

docs/AGENTIC_WORKFLOW.md

@@ -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