# 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