Skip to main content

Spec-Driven Workflow

ipfos-web mandates a spec-driven, gated workflow: features are specified and approved before any code is written. The authoritative document is ipfos-web/spec-driven/workflow.md — read it before your first feature. This page is the short version.

The pipeline​

Every feature moves through gated artifacts, each requiring explicit approval before the next:

Discussion ──▶ requirements.md ──▶ plan.md ──▶ tasks.md ──▶ Execution ──▶ Verification
   (lock into FEATURES.md)   confirm      approve       approve
  1. Discussion — new feature ideas are clarified first (flow, decisions, open items). The outcome is locked into spec-driven/FEATURES.md with status discussed. No code or artifacts are produced during discussion.
  2. Requirements → Plan → Tasks — one artifact per turn, in order. The core laws: no confirmed requirements → no plan; no approved plan → no tasks; no approved tasks → no execution.
  3. Execution & verification — implement the approved tasks, then verify.

Artifacts live at spec-driven/delegate/<feature-name>/{requirements,plan,tasks}.md (kebab-case). Browse existing ones — users-management/, projects-management/, ticket-details-page/, sla-and-escalations/ — to see the expected shape.

Rules worth knowing on day one​

  • Small Change Mode — changes touching ≤ 2 files with no architecture/data-model/security impact still pass all gates, but with minimal artifacts (≤ 5 tasks).
  • Line caps — requirements ≤ 80 lines, plan ≤ 120, tasks ≤ 150. Bullets over prose; reference file paths instead of restating content.
  • Skills — spec-driven/skills/ holds how-to guides for this codebase (component-creation, data-fetching, routing, form-handling, folder-structure, ticketing-module, …). They apply to human developers as much as AI agents: check the relevant skill before building.
  • Locked decisions — FEATURES.md is the decision record. Don't re-litigate a locked decision inside a later phase; reference it.

Cross-repo features​

For features that touch both the frontend and os-backend, the workspace rule is backend first: the backend runs the feature through its own Workflow Contract and produces the API contract in os-backend/docs/design/. The frontend requirements.md must reference that contract as an input — never invent data shapes on the frontend. When the two disagree, os-backend/docs/design/ is the source of truth.