82 lines
2.0 KiB
Markdown
82 lines
2.0 KiB
Markdown
# 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
|