Keep a Content-Generation Workflow App's Backend and Frontend in Sync via OpenAPI
Use when changing an app where users extract items, confirm them on a preparation page, and start generation in a production workspace. It regenerates OpenAPI types after each API change, keeps each screen's job and each kind of state separate, and keeps docs and release notes current.
To use this AI rule
## Regenerate OpenAPI Types and Clients After Every Backend API Change
After every backend API change, run the repository's OpenAPI update command. Treat the generated schema and frontend types as part of the same change, not as later cleanup.
Frontend code must call backend endpoints through the generated OpenAPI client. Do not add handwritten service wrappers that duplicate generated request and response contracts.
Keep backend responsibilities strict:
- the API layer parses input, performs authentication and authorization, and organizes responses;
- the service layer owns business rules, state transitions, and data orchestration.
Place cross-layer generation contracts, including input and output DTOs and provider configuration, in a shared contracts module. Task modules should contain task wrapping, dispatch, and execution orchestration, not shared DTO definitions.
Integration modules may depend on shared contracts but must not depend on task-internal type modules.
When an API, type, or state model changes, update the backend implementation, OpenAPI document, generated frontend types, client usage, and directly related documentation together.
## Comment Every Function and Keep Current Facts Apart from Future Plans in Docs
When frontend styling is repeated more than once, prefer a reusable component or shared style structure over another copy.
Every function, class, or comparable code block needs a comment that explains what it does and why it exists. Complex logic should also document relevant parameters, return behavior, and essential internal decisions. Keep comments synchronized with implementation.
Classify documentation before writing:
- `guide` explains how to perform a task or integrate a capability;
- `architecture` records the system that is currently implemented;
- `plans` records future work, staged tasks, and proposed changes;
- `reference` contains stable facts intended for lookup;
- `blog` contains release notes.
Put current boundaries, implemented state transitions, and actual behavior in architecture documentation. Put work still being designed or executed in plans. Put operating procedures and development workflows in guides.
Do not mix current facts and future intentions in one how-to document. Split them between architecture and plans even when they concern the same topic.
Do not modify a finalized historical release note unless the task explicitly requires it.
## Keep the Task Center Light and Give Each Workflow Screen Its Own Job
Separate the primary user workflow into focused surfaces:
- a preparation page extracts domain data, confirms candidates, corrects basic information, and advances the item to `ready`;
- a production workspace checks output readiness, manages key assets and parameters, starts generation, and presents results;
- a task center shows only lightweight, generic task information such as status, progress, success, failure, cancellation, and a return link.
Do not place domain-specific summaries, prompt-debugging context, asset mappings, or other heavy details in the generic task center. Keep them in the relevant preparation, production, generation, or diagnostic panel.
If extraction tools remain available in the production workspace, expose them only as shortcuts or diagnostics. They must not replace the preparation page as the main confirmation surface.
When a responsibility boundary changes, update both the relevant UI and the architecture documentation. A task-center redesign must not turn the task center into a new business-detail page.
## Use the Item Status Only for Confirmation, Not for Generation Progress
Use the domain item's primary status only for information-confirmation state:
- `pending` means extraction or confirmation work remains;
- `ready` means required information has been confirmed and downstream preparation may begin.
Do not use that status for runtime generation state. Values such as `generating` belong to the task system and runtime summary.
Represent output readiness as a separate dimension. An item being `ready` for downstream preparation does not guarantee that every condition for generation is satisfied.
Every user interface must distinguish:
1. information-confirmation state;
2. runtime task state;
3. output-generation readiness.
When state semantics change, synchronize backend behavior, OpenAPI, generated frontend types, state labels, navigation conditions, and development documentation.
## Send Users from the Preparation Page to the Production Workspace After Confirming
The standard flow is:
1. extract work items from source content;
2. confirm and correct extracted assets, dialogue, or other required information on the preparation page;
3. move to the production workspace for key assets, reference material, output parameters, and readiness checks;
4. start generation from the production workspace;
5. inspect results in the domain workspace while using the task center only for generic task progress.
The preparation page owns extraction, confirmation, and correction. The production workspace owns generation preparation, execution, and result review.
After preparation succeeds, clearly direct the user to the production workspace. If the workspace finds an item that is not `ready`, direct the user back to preparation with a clear explanation.
Prioritize this flow when changing interactions. Convenience shortcuts must not obscure the canonical next step or collapse preparation and generation into one ambiguous surface.
## Update Architecture Docs with Each Change and Add Usable Migration Steps to Release Notes
Architecture documentation contains only behavior that is currently true. Plans contain work still in progress, staged tasks, priorities, and future execution paths.
When code behavior, state semantics, or page responsibilities change, update architecture documentation in the same work. When plan scope, priority, or sequence changes, update the plan. A landed plan should move into architecture or become a release note.
Treat stale architecture or plan documents as incomplete work.
Release notes must include frontmatter for title, date, description, tags, and authors. Use a stable section order, omitting only sections that do not apply:
1. Highlights;
2. Added, Changed, and Fixed;
3. Breaking Changes and Deprecations;
4. Security and Known Issues;
5. Migration Guide and Rollback Notes;
6. Compatibility Matrix, Validation Commands, and Upgrade Checklist;
7. References, Contributor Notes, and Acknowledgements.
Write in a maintainer release voice: lead with conclusions and executable information, use short paragraphs and lists, and keep terminology stable. Clearly separate new capabilities, behavior changes, compatibility risks, and known issues.
Migration steps, rollback steps, and validation commands must be directly usable rather than vague.
## Finish Only When Generated Types and Docs Match the Code
Work is complete only when all applicable conditions hold:
1. implementation is present with no obvious placeholders or obsolete compatibility residue;
2. new and changed functions and classes have accurate, useful comments;
3. API changes have updated OpenAPI, generated frontend types, and generated-client usage;
4. current behavior is reflected in architecture documentation and future work in plans;
5. preparation, production, and task-center responsibilities remain distinct;
6. frontend changes pass the repository's TypeScript no-output check;
7. backend changes pass relevant tests or, at minimum, the documented syntax and import checks;
8. the completion report states what changed and what verification passed;
9. remaining work or follow-up recommendations are listed separately.
Do not claim completion while code, contracts, generated types, documentation, state semantics, or workflow surfaces disagree.