Step 1: Project Example

# AGENTS.md

## Purpose
This repository is developed with AI-assisted workflows in OpenCode.
Agents working in this repo must prioritize:
- correctness
- maintainability
- explicit architecture
- testability
- safe incremental delivery
- business value per stage

Do not treat this repo as a one-shot generation task.
Work in small, reviewable increments.

---

## Working model

### Default execution model
For any non-trivial task:
1. Start with a plan.
2. Limit scope to the current stage only.
3. Implement the minimum viable increment.
4. Run relevant verification.
5. Produce a concise change report.

Do not attempt broad uncontrolled rewrites unless explicitly asked.

### Stage discipline
Work must be organized into stages.
Each stage should:
- produce demonstrable value
- be testable
- be reviewable
- have clear acceptance criteria
- have clear out-of-scope boundaries

### End-to-end preference
Prefer vertical slices over layer-by-layer delivery.
Do not build the whole backend first and postpone frontend/integration until later unless explicitly requested.
For product features, prefer:
- backend changes
- frontend changes
- DB changes
- integration
- tests
within the same stage.

---

## Planning rules

Before making large or risky changes, produce a plan that includes:
- objective
- scope
- out of scope
- impacted modules
- data model changes
- API changes
- frontend changes
- risks
- verification strategy
- rollout / migration notes if applicable

If the task is ambiguous, choose the simplest extensible design and state assumptions explicitly.

---

## Code quality rules

### General
- Prefer simple, explicit code over clever abstractions.
- Keep functions and modules cohesive.
- Avoid hidden side effects.
- Avoid premature generalization.
- Follow existing project conventions unless they are clearly harmful.

### Readability
- Write code for future maintainers.
- Use descriptive names.
- Keep files focused.
- Remove dead code when safe to do so.
- Do not leave unexplained hacks.

### Architecture
- Respect module boundaries.
- Do not introduce circular dependencies.
- Keep business logic out of UI glue code.
- Keep transport concerns separate from domain logic.
- Keep persistence concerns separate from application behavior where practical.

### Change safety
- Minimize blast radius.
- Avoid unnecessary rewrites.
- Preserve backward compatibility unless the task explicitly allows breaking changes.
- If a breaking change is introduced, document it clearly.

---

## Testing rules

Testing is required for meaningful changes.

### Minimum expectations
For each completed stage, add or update the appropriate level of tests:
- unit tests for isolated logic
- integration tests for contracts and boundaries
- end-to-end or smoke tests for critical user flows
- migration verification for DB changes
- type checks / lint / static analysis where applicable

### Required mindset
Do not say "done" if code was written but not verified.
If tests cannot be run, state exactly why.

### Test priority
Prioritize tests for:
- critical business flows
- auth / permissions
- money-related logic
- order / workflow transitions
- data integrity
- external integrations
- error handling

---

## Database and migrations

For any DB change:
- prefer explicit migrations
- make schema changes reversible when practical
- document data migration implications
- avoid destructive changes without explicit warning
- preserve production safety

If changing schema:
- update related models
- update seeds / fixtures if needed
- update integration tests
- mention rollout order if relevant

---

## API and contracts

For any API change:
- keep contracts explicit
- update request/response types
- update docs or examples if applicable
- preserve backward compatibility where possible
- document breaking changes clearly

When frontend and backend both change:
- keep payload contracts aligned
- do not leave frontend relying on stale mocks unless explicitly temporary
- state temporary mismatches clearly if they exist

---

## Frontend rules

Frontend changes must prioritize:
- clarity
- predictable state flow
- loading/error/empty states
- accessibility basics
- minimal but consistent UX

Do not build visual complexity before flow correctness.
Prefer working user paths over decorative completeness.

---

## Infrastructure and operations

Treat infra changes as production-sensitive.

### For infra-related tasks
- prefer configuration as code
- show intended changes explicitly
- mention rollout order
- mention rollback path
- do not run destructive commands unless explicitly authorized

### Secrets and safety
- never hardcode secrets
- do not expose credentials in logs or code
- prefer environment-based configuration
- preserve least privilege assumptions

---

## Verification commands

Agents should run the smallest relevant set of checks for the current scope.

Examples (customize for project):
- install deps: `make install` or `pnpm install && pip install -r requirements.txt`
- backend lint: `make lint-backend`
- frontend lint: `make lint-frontend`
- typecheck: `make typecheck`
- backend tests: `make test-backend`
- frontend tests: `make test-frontend`
- integration tests: `make test-integration`
- e2e tests: `make test-e2e`
- full check: `make check`

If project-specific commands differ, use those.

---

## Expected final response format for implementation tasks

At the end of a task, provide:

1. Summary of changes
2. Files/modules affected
3. Verification performed
4. Known risks / tech debt / assumptions
5. Manual QA steps
6. Recommended next step

Do not claim verification that was not actually run.

---

## Review expectations

A review pass should look for:
- correctness issues
- edge cases
- missing tests
- risky migrations
- contract drift
- architecture drift
- unnecessary complexity
- maintainability issues

Review output should separate:
- critical issues
- important follow-ups
- optional improvements

---

## Delivery philosophy

The goal is not maximal code generation.
The goal is controlled delivery of working software.

Favor:
- small stages
- explicit assumptions
- visible progress
- stable contracts
- end-to-end validation
- maintainable code
over:
- giant rewrites
- implicit decisions
- hidden complexity
- unverified output

---

## If unsure

If unsure:
- inspect relevant code first
- propose a small safe plan
- choose the minimal extensible design
- document assumptions
- avoid pretending certainty

# Stage Report

## Stage
[Stage name]

## Objective
[What this stage was supposed to achieve]

## Scope
[What is included in this stage]

## Out of scope
[What is intentionally not included]

## Business value
[What user or business capability is enabled by this stage]

---

## Implemented

### Backend
- [change]
- [change]
- [change]

### Frontend
- [change]
- [change]
- [change]

### Database
- [schema / migration / seed change]

### Infrastructure / DevEx
- [CI / Docker / config / observability / scripts]

---

## API / contract changes
- [new endpoint]
- [changed payload]
- [breaking change if any]

---

## Files / modules affected
- [module/path]
- [module/path]
- [module/path]

---

## Verification performed

### Automated checks run
- [command] — [result]
- [command] — [result]
- [command] — [result]

### Manual checks performed
- [manual scenario]
- [manual scenario]

### Not verified
- [what could not be verified]
- [why]

---

## Acceptance criteria status
- [criterion] — Done / Partial / Not done
- [criterion] — Done / Partial / Not done
- [criterion] — Done / Partial / Not done

---

## Known issues
- [issue]
- [issue]

## Tech debt introduced or preserved
- [debt]
- [debt]

## Assumptions
- [assumption]
- [assumption]

## Risks
- [risk]
- [risk]

---

## Manual QA checklist
- [step]
- [step]
- [step]

---

## Release notes
### Added
- [item]

### Changed
- [item]

### Fixed
- [item]

### Deferred
- [item]

---

## Recommended next stage
[What should be implemented next and why]

# Stage Summary

## Done
- ...

## Verified
- ...

## Not verified
- ...

## Risks / debt
- ...

## QA steps
- ...

## Next
- ...

# Stage Definition

## Name
[Stage name]

## Goal
[User-visible or business-visible capability]

## Business value
[Why this stage matters]

## Scope
- ...
- ...
- ...

## Out of scope
- ...
- ...
- ...

## Backend work
- ...
- ...

## Frontend work
- ...
- ...

## Database work
- ...
- ...

## Infra / DevEx work
- ...
- ...

## Acceptance criteria
- ...
- ...
- ...

## Required tests
- unit:
- integration:
- e2e/smoke:

## Risks
- ...
- ...

## Dependencies
- ...
- ...

## Deliverables
- code
- tests
- stage report
- release notes
- QA checklist

You are working in a controlled stage-based delivery workflow.

Task:
[describe the task]

Your job now is PLAN ONLY.
Do not modify files yet.

Produce a structured implementation plan with:

1. Objective
2. Scope
3. Out of scope
4. Business value
5. Impacted modules/files
6. Backend changes
7. Frontend changes
8. Database changes
9. API / contract changes
10. Infra / config implications
11. Risks
12. Assumptions
13. Verification plan
14. Recommended implementation order

Constraints:
- prefer the smallest viable increment
- prefer end-to-end deliverable slices
- avoid broad rewrites
- preserve maintainability
- call out breaking changes explicitly
- if ambiguous, choose the simplest extensible design

At the end, include:
- Acceptance criteria
- Suggested stage name
- Estimated blast radius (small / medium / large)

Implement the approved plan for the current stage.

Rules:
- stay within scope
- do not expand the task unless necessary
- prefer minimal viable implementation
- keep frontend/backend/db aligned
- update tests relevant to the change
- preserve project conventions
- document assumptions in final report
- do not claim verification that was not run

Required final output:
1. Summary of changes
2. Files/modules affected
3. Verification performed
4. Not verified
5. Known risks / tech debt / assumptions
6. Manual QA checklist
7. Recommended next step

Review the current changes as a strict senior engineer.

Focus on:
- correctness
- maintainability
- architecture drift
- missing tests
- contract drift
- migration risk
- edge cases
- security / auth / data integrity issues
- unnecessary complexity

Output format:

## Critical issues
- ...

## Important follow-ups
- ...

## Nice-to-have improvements
- ...

## Testing gaps
- ...

## Migration / rollout concerns
- ...

## Overall assessment
[Ready / Ready with follow-ups / Not ready]

Investigate the issue without making broad unrelated changes.

Problem:
[describe bug]

Your task:
1. identify likely root cause
2. inspect affected flow
3. propose minimal fix
4. list regression risks
5. define verification steps

Prefer the smallest safe correction.
Do not rewrite unrelated modules.

Produce a Stage Report for the work just completed.

Include:
- objective
- implemented backend/frontend/db/infra changes
- contract changes
- verification performed
- not verified
- acceptance criteria status
- known issues
- tech debt
- assumptions
- manual QA checklist
- release notes
- recommended next stage

Plan the stage "Catalog MVP" for an online shop project.

Goal:
Users can browse the product catalog and open product detail pages.

Produce:
1. objective
2. business value
3. scope
4. out of scope
5. backend changes
6. frontend changes
7. database changes
8. API contracts
9. risks
10. assumptions
11. verification plan
12. implementation order
13. acceptance criteria

Constraints:
- prefer end-to-end delivery
- do not design future stages unless needed for extensibility
- keep architecture simple and scalable
- do not implement cart, checkout, auth, or admin in this stage

Implement the approved stage "Catalog MVP".

Required scope:
- product/category schema
- backend endpoints for product list and product detail
- frontend catalog page
- frontend product detail page
- frontend uses real backend API
- basic loading/error/empty states
- test data / seed
- relevant tests

Do not expand scope into cart/auth/admin.

At the end provide:
- summary of changes
- files/modules affected
- verification performed
- not verified
- known issues / assumptions / tech debt
- manual QA checklist
- recommended next stage

Review the Catalog MVP implementation as a strict senior engineer.

Check:
- correctness of API and UI integration
- schema design sanity
- test coverage gaps
- frontend/backend contract drift
- missing loading/error/empty states
- maintainability concerns
- future risk created by current design

Output:
- critical issues
- important follow-ups
- nice-to-have improvements
- test gaps
- overall assessment

# Definition of Done

A stage is done only if:

- scope is implemented
- acceptance criteria are satisfied
- relevant tests are added or updated
- relevant checks are run
- backend/frontend/db changes are aligned
- known issues are explicitly listed
- assumptions are explicitly listed
- manual QA steps are provided
- stage report is produced
- review pass is completed