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:

AGENTS.md
docs/ARCHITECTURE.md
docs/DEVELOPMENT_WORKFLOW.md
docs/PRODUCT.md
docs/CONVENTIONS.md
docs/FEATURES/<feature>.md
docs/TASKS/<feature>/<task>.md
docs/PROMPTS/<prompt-template>.md

Workflow Loop

For every meaningful change:

Define or update a feature spec in docs/FEATURES/.
Create a small task in docs/TASKS/<feature>/.
Use the correct prompt template from docs/PROMPTS/.
Ask the agent to implement only that task.
Review the diff.
Run tests and builds.
Update OpenAPI when backend contracts change.
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:

./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

2.0 KiB Raw Blame History