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):