Flows External App Submit

This is step 4 (final) of the Flows app certification flow:

flows-app-brief  →  build  →  flows-code-review  →  flows-design-review  →  flows-external-app-submit (this skill)

This skill does not rerun any review. It verifies the artifacts from the prior three steps and only then invokes the CLI submit command.

Preconditions (show these to the user first)

Before doing anything, print this checklist so the user knows exactly what is being verified:

```
App-Brief.md
```
exists at repo root and all required frontmatter fields are populated.

The latest

reviews/code-review/feedback-round-<N>/code-review-report.md

is committed to git and reports Must Fix open: 0
.

The latest

reviews/design-review/feedback-round-<N>/design-review-report.md

is committed to git and reports Average score: X.X
with X.X ≥ 3.8.

Certification artifacts are committed —
```
apps submit
```
uses
```
git archive HEAD
```
and silently excludes uncommitted files.
A deploy bundle exists in
```
.cognite-bundles/
```
and is not older than HEAD.

Step 0 — Air-hatch preflight (offer stubs if reviews are missing)

App-Brief.md

is non-negotiable — it captures the value case the certification reviewer reads first. The code and design reviews, however, can be air-hatched with a clear "SKIPPED" status that the reviewer will see and act on. Use this when the user wants to submit without spending the 20+ minutes each review takes.

Probe for each review artifact via

git ls-files

bash

git ls-files 'reviews/code-review/'   | grep -q 'code-review-report.md'   && echo code_present   || echo code_missing
git ls-files 'reviews/design-review/' | grep -q 'design-review-report.md' && echo design_present || echo design_missing

Both reports present → skip Step 0, continue at Step 1.
```
App-Brief.md
```
missing → continue to Step 1, which fails with the standard "Run
```
flows-app-brief
```
first" message. The air-hatch does not cover App-Brief.
Either review missing → offer the air-hatch via
```
AskQuestion
```
:

"Review artifacts missing: <list which>. Choose:
Run real reviews — exit here; user runs
flows-code-review
/
flows-design-review
first (~20 min each). Recommended for first-time submissions.
Quick submit (stubs) — write SKIPPED stub reports for the missing reviews. The Cognite certification reviewer will see the SKIPPED status and request real reviews before approval, but you can submit now.

Cancel — stop without doing anything."

On Run real reviews: print the next-step command (

flows-code-review

and/or

flows-design-review

) and exit.

On Cancel: exit.

On Quick submit: for each missing review, write the stub using the templates in "Stub templates" at the end of this skill:

reviews/code-review/feedback-round-0/code-review-report.md

reviews/design-review/feedback-round-0/design-review-report.md

Round 0 is intentional — real review skills start at

feedback-round-1

. When the user later runs a real review,

sort -V | tail -1

picks the higher round number, so the stub is automatically superseded without manual cleanup.

After writing the stubs, tell the user:

"Stub reports written. Commit them along with
App-Brief.md
, then re-run this skill:
git add App-Brief.md reviews/
git commit -m 'chore: certification artifacts (reviews skipped)'"

Exit. The user re-runs the skill after committing.

Step 1 — Verify App-Brief.md

bash

test -f App-Brief.md

If missing → fail with: "Run
flows-app-brief
first to create the App-Brief.md."

Parse the YAML frontmatter (the block between the first

---

and the next

---

at the top of the file). Required keys that must be present and non-empty:

```
appName
```
```
customer
```
```
tier
```
```
owner
```
```
userRole
```
```
currentProblem
```
```
oneSentenceStory
```
```
successCriteria
```
```
userEvidence
```

If any are missing or empty → fail with the list of missing fields and: "Re-run
flows-app-brief
to complete the brief."

Optional (not blocking):

userCount

businessValue

milestones

repoUrl

Step 2 — Verify code review

Find the latest committed round report:

bash

git ls-files 'reviews/code-review/' | grep 'code-review-report.md' | sort -V | tail -1

If no result → fail with: "Run
flows-code-review
first, then commit the artifacts."

Parse the Summary block from that

code-review-report.md

If the Summary block contains a line matching

^- Status: SKIPPED$

→ mark this check as SKIPPED (not PASS, not FAIL) and skip the numeric check. The stub came from the Step 0 air-hatch; the reviewer will see the SKIPPED status.

Otherwise, it must contain a line matching this exact regex:

^- Must Fix open: (\d+)$

If the integer is

→ pass. Otherwise → fail with: "Open Must Fix items remain in the latest
code-review-report.md
. Re-run
flows-code-review
until
Must Fix open: 0
."

If neither the Status nor the Must Fix line is present → fail with: "Latest code review report is missing the Summary block. Re-run
flows-code-review
."

Step 3 — Verify design review

Find the latest committed round report:

bash

git ls-files 'reviews/design-review/' | grep 'design-review-report.md' | sort -V | tail -1

If no result → fail with: "Run
flows-design-review
first, then commit the artifacts."

Parse the Summary block from that

design-review-report.md

If the Summary block contains a line matching

^- Status: SKIPPED$

→ mark this check as SKIPPED (not PASS, not FAIL) and skip the numeric check. The stub came from the Step 0 air-hatch; the reviewer will see the SKIPPED status.

Otherwise, it must contain a line matching:

^- Average score: (\d+(?:\.\d+)?)$

If the number is ≥ 3.8 → pass. Otherwise → fail with: "Design review average is below the launch threshold (3.8). Address the Must Fix and Should Fix items in the latest design-review-report.md and re-run
flows-design-review
in a new feedback round."

Step 4 — Verify certification artifacts are committed

apps submit

uses

git archive HEAD

— uncommitted files are silently excluded from the source archive. Check that the three certification artifacts are tracked:

bash

git ls-files --error-unmatch App-Brief.md 2>/dev/null
git ls-files --error-unmatch "<latest-code-review-report-path>" 2>/dev/null
git ls-files --error-unmatch "<latest-design-review-report-path>" 2>/dev/null

If any of these files is not committed → BLOCK with:

"The following certification files are not committed to git.
apps submit
uses
git archive HEAD
and will silently omit them from the source archive — the reviewer will not see them.\n\nPlease run:\n git add <missing files>\n git commit -m 'chore: add certification artifacts'\n\nThen re-run this skill."

If all certification artifacts are committed but there are other uncommitted changes in the working tree → WARN (do not block):

"You have uncommitted changes outside the certification artifacts.
apps submit
uses
git archive HEAD
— those changes will not appear in the submitted source archive. If they should be part of certification, commit them first."

Step 5 — Verify deploy bundle

bash

ls .cognite-bundles/*.zip 2>/dev/null | head -1

If no bundle exists → WARN (do not block): "No deploy bundle found in
.cognite-bundles/
. Run
npx @cognite/cli apps deploy
first so the submitted source archive and deployed bundle come from the same code."

If a bundle exists, check whether it pre-dates HEAD:

bash

bundle=$(ls -1t .cognite-bundles/*.zip 2>/dev/null | head -1)
if [ -n "$bundle" ]; then
  bundle_mtime=$(stat -f %m "$bundle" 2>/dev/null || stat -c %Y "$bundle")
  head_time=$(git log -1 --format=%ct HEAD)
  if [ "$bundle_mtime" -lt "$head_time" ]; then
    echo "WARN"
  fi
fi

If the bundle is older than HEAD → WARN (do not block):

"The deploy bundle in
.cognite-bundles/
is older than the current HEAD commit. The certification reviewer compares the deployed bundle against the submitted source — if you committed changes after your last deploy, they won't match. Re-run
npx @cognite/cli apps deploy
before submitting. (
npm run build
alone does not refresh the bundle — only
apps deploy
does.)"

Step 6 — Print pass/fail table

Print a table like:

Check                                  Result
-----                                  ------
App-Brief.md complete                  PASS / FAIL — reason
Code review Must Fix open: 0           PASS / FAIL / SKIPPED — reason
Design review average ≥ 3.8            PASS / FAIL / SKIPPED — reason
Certification artifacts committed      PASS / FAIL — reason
Deploy bundle present and current      PASS / WARN — reason

SKIPPED

only applies to the code and design review rows and only when Step 0's air-hatch wrote a stub. Render SKIPPED rows with the note

SKIPPED — user opted out via Step 0 air-hatch

If any check is FAIL: stop here. Do not run the CLI. Print the precise next-step skill the user should run. SKIPPED rows do not block — they pass through to Step 7, which adds an explicit confirmation.

Step 7 — Confirm and submit

If any check is

SKIPPED

, prepend an explicit warning to the confirm prompt:

"WARNING — the following reviews are SKIPPED: <list>. The Cognite certification reviewer will see the SKIPPED status in the submitted reports and will request a real review before approval. Proceed with submit anyway?"

Otherwise (all PASS, warnings OK), use the standard confirm prompt:

"All certification checks passed. Run
npx @cognite/cli apps submit
now? This will zip the repo and pre-populate the Zendesk submission form."

yes

bash

npx @cognite/cli@latest apps submit

Stream the output to the user.

Step 8 — Post-submit handoff

When this skill invokes

apps submit

via

Bash

, the CLI runs non-interactively (

process.stdout.isTTY === false

) and skips its auto-open-browser / reveal-in-file-manager step. The CLI still prints the file list, screen-recording prompt, and Zendesk URL — but the user must act on them manually.

After the CLI finishes, print this to the user:

The CLI ran non-interactively so it didn't open the browser or file manager. To finish:
Open the Zendesk URL from the CLI output above. The URL requires a sign-in on
support.cognite.com
— create an account there if you don't have one, then revisit the link.
Open
dist/submit/
in your file manager and drop in a short screen recording of the certified user journey.
Attach every file in
dist/submit/
(source archive, deploy bundle, screen recording) to the Zendesk ticket.
Push your commits if the branch is ahead of origin.

Then run

git status --short --branch

and surface the ahead/behind count explicitly under step 4 if the branch is ahead of origin.

Stub templates (used by Step 0 air-hatch)

When the user picks Quick submit (stubs) in Step 0, write the missing reports using these exact templates. Create the parent directory first if it does not exist.

Code review stub

Path:

reviews/code-review/feedback-round-0/code-review-report.md

markdown

# Code Review Report — Round 0

**Status: SKIPPED** — user opted out of `flows-code-review` at submit time.

The Cognite certification reviewer will see this SKIPPED status and request a real `flows-code-review` run before approval. Re-run `flows-code-review` to replace this stub with a real round.

## Summary

- Status: SKIPPED
- Must Fix open: 0
- Should Fix open: 0
- Nit open: 0

Design review stub

Path:

reviews/design-review/feedback-round-0/design-review-report.md

markdown

# Design Review Report — Round 0

**Status: SKIPPED** — user opted out of `flows-design-review` walkthrough at submit time.

The Cognite certification reviewer will see this SKIPPED status and request a real `flows-design-review` walkthrough before approval. Re-run `flows-design-review` to replace this stub with a real round.

## Summary

- Status: SKIPPED
- Average score: N/A

flows-external-app-submit

NPX Install

Tags

SKILL.md Content

Flows External App Submit

Preconditions (show these to the user first)

Step 0 — Air-hatch preflight (offer stubs if reviews are missing)

Step 1 — Verify App-Brief.md

Step 2 — Verify code review

Step 3 — Verify design review

Step 4 — Verify certification artifacts are committed

Step 5 — Verify deploy bundle

Step 6 — Print pass/fail table

Step 7 — Confirm and submit

Step 8 — Post-submit handoff

Stub templates (used by Step 0 air-hatch)

Code review stub

Design review stub