Skip to main content
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.
ModeWhen 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 (opt-in)Per-feature specs under specs/<NNN>-<feature-name>/ and slash commands in Claude Code and Cursor, using a curated, vendored subset of 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 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.
SectionPurpose
User StoriesWho uses the app, what they want, and why.
Acceptance ScenariosGiven / When / Then statements.
Functional RequirementsNumbered FRs (FR-001, FR-002, …) plans and tasks can reference.
Success CriteriaMeasurable, user-visible outcomes.
ClarificationsOpen questions before planning starts.
AssumptionsScoping decisions and out-of-scope items.
Data Models & CDF IntegrationExisting 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: 
## 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/<NNN>-<feature-name>/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. 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/<NNN>-<feature>/spec.md pre-populated with the spec-kit template, including a Flows-specific Data Models & CDF Integration section. 
/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: 
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/<NNN>-<feature-name>/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

Last modified on June 10, 2026