> ## Documentation Index > Fetch the complete documentation index at: https://docs.cognite.com/llms.txt > Use this file to discover all available pages before exploring further. # About spec-driven development > Learn how spec-driven development works in Cognite Flows: a checked-in SPEC.md for each app, or optional spec-kit slash commands for structured per-feature planning before you write code. In Flows, you treat checked-in specs as the source of truth for a feature: they align your team and give your agent the same brief every time you return to the repo. ## Specs vs. plan mode **Plan mode** (for example in Claude Code, or similar in-session planning in other AI coding tools) fits **one conversation**: you think through the task now, and your agent can act on that plan immediately. **Repo-native specs** live in **git**, survive across sessions, can go through **review** like code, and travel with the feature from first sketch to release. You refine the spec as you learn, share it with collaborators, and reuse it as **stable context** whenever you open the project with your agent. The approaches stack. You can use plan mode **inside** a spec-kit flow — for example, reason in-session, then run `/speckit.tasks`. Specs anchor **what** you are building; in-session planning helps with **how** you execute the next slice. ## Two modes in Flows When you run `npx @cognite/cli@latest apps create`, the CLI asks how you want to plan your app. | Mode | When to use | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Lightweight `SPEC.md` (default)** | One structured `SPEC.md` at the repository root. No spec-kit bundle or slash commands. Solo work, small apps, early ideation, or a single spec for the whole app. | | **[Spec-kit](#spec-kit) (opt-in)** | Per-feature specs under `specs/-/` and slash commands in Claude Code and Cursor, using a curated, vendored subset of [spec-kit](https://github.com/github/spec-kit). Teams, multi-session work, or several distinct features. | The spec-kit prompt defaults to **No**. If you skip it and want spec-kit later, there is no retrofit command — you would need to re-scaffold or manually copy the [spec-kit files](#spec-kit) into your app. ## Lightweight SPEC.md By default, your Flows custom app includes `SPEC.md` at the repository root. Use it as a living product spec: the template captures user intent, requirements, and how the app integrates with CDF data models. The following table describes each section. | Section | Purpose | | --------------------------------- | --------------------------------------------------------------- | | **User Stories** | Who uses the app, what they want, and why. | | **Acceptance Scenarios** | Given / When / Then statements. | | **Functional Requirements** | Numbered FRs (FR-001, FR-002, …) plans and tasks can reference. | | **Success Criteria** | Measurable, user-visible outcomes. | | **Clarifications** | Open questions before planning starts. | | **Assumptions** | Scoping decisions and out-of-scope items. | | **Data Models & CDF Integration** | Existing views, new views, and spaces *(mandatory)*. | **Example**: a populated excerpt for a **Production Accounting dashboard**. This is a CDF app that shows oil balance KPIs and a hierarchical reconciliation tree with quality-flagged flow components: ```markdown wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} ## User Stories ### User Story 1 — View at-a-glance production KPIs (Priority: P1) A production accountant opens the dashboard to get an immediate snapshot of oil balance health. The KPI bar surfaces four headline metrics — Gross Production, Net Export, Imbalance, and Closure % — so the accountant can tell at a glance whether the period is closing within acceptable tolerance. ### User Story 2 — Explore the Balance Reconciliation Tree (Priority: P2) The accountant needs to trace the source and destination of production volumes. The Balance Reconciliation Tree is a hierarchical table of flow components (Wellhead Production → Field Gross → Terminal Receipts → Pipeline Export → Losses). Each row shows the component name, a numeric value with a unit, a source tag, and a quality badge (Verified / Estimated / Manual). ## Functional Requirements - FR-001: The dashboard MUST display a KPI bar with four metrics: Gross Production (Mbbl), Net Export (Mbbl), Imbalance (Mbbl), and Closure (%). Imbalance MUST be derived from tree data; Closure % MUST equal Net Export / Gross Production × 100. - FR-004: The Balance Reconciliation Tree MUST render as a hierarchical table with collapsible parent rows and child rows. - FR-006: Quality badges MUST support exactly three states: Verified (success tone), Estimated (warning tone), Manual (neutral tone). ## Edge Cases - A flow component with no source tag MUST render an em-dash (—) placeholder, never a blank cell. - When Imbalance is exactly zero, the Imbalance KPI MUST render in a neutral success tone (fully balanced). - When Closure % exceeds 100%, the value MUST render as-is in a warning tone (over-allocation). ## Success Criteria - SC-001: The KPI bar renders within 1 second of load. - SC-003: A user can locate any flow component in the tree in under 30 seconds using expand/collapse and the quality filter. - SC-005: The tree supports at least 3 levels of hierarchy without layout breakage. ## Assumptions - Each balance covers a single reporting period; a period picker is out of scope for v1. - Volumes are in Mbbl (thousand barrels); Closure is a percentage. - The app embeds in the Cognite Data Fusion iframe; auth is delegated to the host. Export and print are out of scope for v1. ## Data Models & CDF Integration ### Existing views - `cdf_cdm.CogniteTimeSeries:v1` — meter readings and production rates behind each source tag (for example, `FLD-GROSS-001`, `LIFT-TOT-001`). ### New views - `production_accounting.FlowComponent:v1` — one node per balance line. Properties: name (string), parent (direct relation to FlowComponent), value (float64), unit (string), sourceTag (string), quality (enum: Verified | Estimated | Manual). - `production_accounting.BalancePeriod:v1` — a reporting period and its rollup KPIs. Properties: periodStart (timestamp), periodEnd (timestamp), grossProduction (float64), netExport (float64). ### Spaces - `production_accounting` — the app's own data model space. - `cdf_cdm` — read-only; Cognite's core data model space. ``` Your agent reads `SPEC.md` before making feature decisions and keeps it in sync with code changes as directed by `AGENTS.md`. ## Spec-kit When you opt into spec-kit during `apps create`, the CLI installs a curated vendor bundle. The following list describes what is added to your repository. * **`.specify/`** — templates, bash scripts, and configuration (`branch_numbering: sequential`). * **`.claude/commands/speckit.*.md`** — slash commands for Claude Code. * **`.cursor/commands/speckit.*.md`** — slash commands for Cursor. * **`.specify/memory/constitution.md`** — a symlink to `AGENTS.md`, so spec-kit commands pick up your app's coding standards automatically. Specs are stored at `specs/-/spec.md`, one directory per feature. Numbering is sequential: `001-production-accounting`, `002-export-report`, and so on. For a full worked run of `/speckit.specify`, `/speckit.clarify`, and `/speckit.plan`, including the exact commands, the clarification questions and answers, and the generated plan, see [Plan a dashboard app with spec-kit](/cdf/flows/guides/spec-kit-walkthrough). The sections below summarize each command with a short example. ### `/speckit.specify` The `/speckit.specify` command generates a new feature spec directory from a short description. It creates `specs/-/spec.md` pre-populated with the spec-kit template, including a Flows-specific **Data Models & CDF Integration** section. ```text wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} /speckit.specify Build an Oil Balance Detail dashboard called 'Production Accounting' with a KPI bar and a Balance Reconciliation Tree of flow components with quality badges. Read data from CDF data models. React + Tailwind. ``` This example creates `specs/001-production-accounting/spec.md`. Complete the template sections before the next step, with **Data Models & CDF Integration** as the highest priority. ### `/speckit.clarify` The `/speckit.clarify` command reads the current spec, surfaces questions that would block planning, and does not generate code. The command runs an internal coverage scan (functional scope, data model, integration, edge cases, and more), then asks up to five targeted questions, each with a recommendation and options. For the Production Accounting dashboard, it surfaced questions such as: * Is the Imbalance value derived from the tree, or independent of it? * Is the Imbalance warning threshold hardcoded or user-configurable? * Which UI state, if any, should persist in the CDF URL? You answer each question in your agent session, and the answers are written directly back into the **Clarifications** section of `spec.md`, so the choices are recorded in git. ### `/speckit.plan` The `/speckit.plan` command reads the clarified spec and generates a numbered implementation plan inside the feature directory — typically a summary, a technical context block, a constitution check against your `AGENTS.md` coding standards, and a project structure: ```text theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} specs/001-production-accounting/ ├── plan.md ├── research.md ├── data-model.md ├── quickstart.md ├── contracts/ └── tasks.md # created later by /speckit.tasks ``` If you prefer not to run `/speckit.plan`, you can plan the implementation another way — for example, with your agent's in-session plan mode — and still produce a numbered implementation plan in the feature directory. When you run `/speckit.tasks`, it decomposes that implementation plan into the ordered list in `tasks.md` (see `/speckit.tasks`). The plan can come from `/speckit.plan` or from your own write-up, as long as the steps are numbered and ordered clearly enough to split into tasks. ### `/speckit.tasks` The `/speckit.tasks` command writes an ordered task list to `tasks.md` in the feature directory, next to `spec.md`, following the pattern `specs/-/tasks.md` (this guide uses `specs/001-production-accounting/tasks.md`). Each task maps back to a functional requirement so your agent can track progress against the spec. ### `/speckit.implement` The `/speckit.implement` command runs the tasks in order, using both the spec and task list as context. It works through the Production Accounting feature — scaffolding the KPI bar, building the reconciliation tree with collapsible rows and quality badges, wiring the quality filter, and integrating with the CDF host via `@cognite/app-sdk`. It stops at each task to confirm before continuing. ## Where do specs live? Specs live in your repository alongside your code. Check them in with your changes so behavior, intent, and data model choices stay traceable in the same history as the implementation. Review spec updates in pull requests and keep them versioned in git under the same ownership model you use for source files. ## Spec-driven development vs. waterfall Classic waterfall runs into trouble when design is fixed for a long time before code ships. This workflow is different: you record enough to start building, then tighten the spec as you learn from implementation. The target is a *good enough* plan — clarity without endless prework. Ten minutes capturing intent in a spec often saves hours of repeated clarification with an agent that still lacks shared context. You won't write a perfect spec, and that is expected. Unknowns stay open until you resolve them, and when requirements change, you update the document and keep going. The spec is not a contract locked at kickoff; it is a living document that lowers the cost of change as you learn. ## Next steps * [Plan a dashboard app with spec-kit](/cdf/flows/guides/spec-kit-walkthrough) — Run through specify, clarify, and plan on a real example. * [Get started with Flows](/cdf/flows/guides/getting-started) — Create an app and see `SPEC.md` land in your workspace. * [Flows skills](/cdf/flows/concepts/skills) — Agent-agnostic skills that ship alongside your spec in every Flows custom app. * [spec-kit on GitHub](https://github.com/github/spec-kit) — Upstream project and full command reference.