Skip to main content

Backend Workflow Contract

Work in os-backend/ follows the Workflow Contract — a documented process that governs how changes are classified, designed, and tracked. The authoritative source is os-backend/CLAUDE.md and the spec under os-backend/ai/workflow-contract/spec/; this page is the orientation summary.

The shape of it​

  1. Classify the task before touching code (feature, fix, refactor, docs, ops).
  2. Validate against the contract — validate_workflow.py checks that the work follows the expected sequence and artifacts.
  3. Design before implementation — design decisions land in os-backend/docs/design/ (architecture, data models, API contracts), implementation planning in os-backend/docs/implementation/ (phases, tasks, status).
  4. Change proposals for significant work live in os-backend/docs/changes/proposed/ before they graduate into design docs.

Documentation layout​

PathContains
docs/design/Architecture proposal, solution design, data model, gateway/ports, api-spec.yml (the OpenAPI contract)
docs/implementation/phases/Numbered delivery phases (phase-03 … phase-13)
docs/implementation/tasks/Task-level specs and the backlog
docs/implementation/status/Weekly status
docs/changes/proposed/Change proposals awaiting adoption

The API contract rule​

The single most important artifact for anyone integrating with the backend is docs/design/api-spec.yml. Every endpoint change must be reflected there:

  • It feeds the Scalar reference at http://localhost:8080/docs.
  • It feeds the API Reference section of this site.
  • The frontend's spec-driven requirements must cite it — when frontend and backend disagree about a data shape, this file wins.

After editing it, regenerate this site's API pages (see API Reference → Overview).

Boundaries with the frontend workflow​

Backend planning artifacts never go under ipfos-web/spec-driven/, and frontend specs never go under os-backend/docs/. For features spanning both repos: discuss and lock decisions once (in ipfos-web/spec-driven/FEATURES.md), deliver the backend contract first, then write the frontend spec against it.