flows-external-app-submit

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:

1. App-Brief.md exists at repo root and all required frontmatter fields are populated.
2. The latest reviews/code-review/feedback-round-<N>/code-review-report.md is committed to git and reports Must Fix open: 0.
3. 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.
4. Certification artifacts are committed — apps submit uses git archive HEAD and silently excludes uncommitted files.
5. 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:

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

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:

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 0 → 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:

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:

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

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:

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."

On yes:

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: 1. 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. 2. Open dist/submit/ in your file manager and drop in a short screen recording of the certified user journey. 3. Attach every file in dist/submit/ (source archive, deploy bundle, screen recording) to the Zendesk ticket. 4. 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

# 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

# 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