Skip to main content

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.

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 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).
Here is a populated excerpt for an asset health dashboard — a CDF app that lists assets and flags timeseries values outside a threshold: 
## User Stories

- As an operations engineer, I want to see the health status of each
  asset on a single dashboard so that I can identify underperforming
  equipment at a glance.

## Functional Requirements

- FR-001: The app MUST display all assets in the selected CDF space
  with their latest timeseries values.
- FR-002: The app MUST highlight values outside a configurable
  threshold in red.
- FR-003: Clicking an asset MUST open a timeseries trend chart.

## Data Models & CDF Integration

### Existing views

- `cdf_cdm.CogniteAsset:v1` — asset metadata and hierarchy.
- `cdf_cdm.CogniteTimeSeries:v1` — latest values and historical trends.

### New views

- `asset-health.AssetThreshold:v1` — upper and lower bounds per asset.
  Properties: assetExternalId (string), lowerBound (float64),
  upperBound (float64).

### Spaces

- `asset-health` — 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-asset-health-dashboard, 002-export-report, and so on.

​
/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 Asset health dashboard: show CDF assets with timeseries trends and threshold alerts
The example command creates specs/001-asset-health-dashboard/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 and surfaces questions that would block planning. It does not generate code. For the asset health dashboard, the command might surface questions like: Are thresholds global or per-asset? What CDF space do the assets live in? Should trend data show raw timeseries or aggregated values? Answer these questions in the Clarifications section of the spec before moving on.

​
/speckit.plan

The /speckit.plan command reads the clarified spec and generates a numbered implementation plan inside the feature directory. 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 the next section). 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-asset-health-dashboard/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 asset health dashboard feature — scaffolding the asset list, wiring CDF data hooks, creating the threshold model, and applying visual feedback. 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.

​
Isn’t this just 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 back-and-forth 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 May 12, 2026