deepx-ai/dx-all-suite/dx-agent-showcase-build

Skill: Build a dx-agent-dev Showcase

RIGID skill. Follow every phase and gate in order. The gates exist because

each one corresponds to a mistake that has actually happened. Do NOT declare a

showcase DONE until Phase 8 verify passes.

Pairs with the `dx-showcase-gen` tool (.deepx/tools/src/dx_showcase_gen/), which owns the deterministic mechanics. This skill owns the orchestration, the KB-based judgment, and the human-in-the-loop steps a tool cannot do.

Trigger Words

"add a showcase", "create a showcase", "showcase 만들/추가/제작", "build a demo for the README", <!-- KOREAN-OK: trigger words include Korean so agents recognize Korean showcase requests --> "promote this as a showcase".

Hard rules (the recurring mistakes, as gates)

1. Record the REAL claude code screen — never a synthetic/rendered substitute.

The build runs in a visible terminal and is captured with dx-showcase-gen's x11grab path. (If a human is present, prefer the real interactive claude TUI.)

1. Capture the build's `--output-format stream-json` STDOUT to a file. The

COMPLETE transcript (with Wall-clock + Cost + the closing narration) is rendered from that capture AFTER the process exits — the in-session sentinel reads the session store, which has no result event and is therefore incomplete.

1. MUST read the routed `.deepx/toolsets/*` before generating code — the build

reads the canonical KB (e.g. ultralytics-train-eval.md, ultralytics-deepx-export.md) rather than improvising from prior outputs/memory. verify FAILS a showcase whose transcript read no toolset (the pills gap).

1. Tool/model are explicit and verified: tool=claude, model=claude-opus-4-8

(the recommended model) unless the user overrides. verify checks them.

1. Artifacts must actually be copied into the showcase dir and made portable.
2. No DONE without `dx-showcase-gen verify` PASS.
3. Every showcase MUST have an entry in `dx-agent-dev-showcase/showcases.json` —

the manifest is the single source for the root-README card grid, the showcase catalog, and the docs 00_Agent_Driven_Development table. verify fails (and regen-docs warns) if a showcase dir is missing from it — this is how ultralytics-yolo-deepx-export once went missing from the docs table. NEVER hand-edit the generated dx-showcase:docs:* marker regions; add to the manifest and run regen-docs.

1. External repos: clone fresh into the build's session dir; NEVER touch a user repo.

When the build needs a third-party/DEEPX-fork checkout (e.g. RapidDoc, PaddleOCR-deepx), the prompt/build MUST git clone it into a temp/isolated dir — it MUST NOT discover (find /) and reuse, modify, or delete a pre-existing repo elsewhere on disk (e.g. under ~/git/). Deleting a user's repo is a destructive action and has happened. And provision models with the fork's model-download script in the FOREGROUND — never hand-compile .dxnn, and never launch the download/compile as a background task: a headless claude -p cannot resume on the completion notification and deadlocks (the recurring PaddlePaddle build freeze).

1. **Fork-based apps MUST be a GENERATED standalone app — not a wrapper around the fork's

demo. When the showcase is "build an app on a third-party fork" (RapidDoc, PaddleOCR), the deliverable is the agent's own entry program that imports the fork's pipeline API as a library; the showcase must be runnable from its own dir. Concretely: (a) the build clones the fork only to obtain source, then vendors the importable package into the app (the fork is not re-cloned at run time); (b) `run.sh` runs the generated entry (`pdf_to_markdown.py` / `ocr_video.py`) — a `run.sh` that shells out to the fork's `demo/demo_offline.py` (or any `demo/*`/example) is a FAIL, not an app; (c) only the NPU models are downloaded by `setup.sh` (never committed). `verify` enforces (b). (d) Portability verify (HARD GATE): the verify step MUST copy the produced app dir to a temp dir OUTSIDE the suite and run its entry there — if it fails because it imported a source/showcase dir in-place (no engine/`common`/models when copied out), it is NOT self-contained → FAIL. NEVER import another showcase's `engine/`/package in-place, NEVER symlink a source dir into the session, and NEVER point a model/output dir at `dx-agent-dev-showcase/...` — vendor the pipeline INTO the app and keep all code/model paths app-relative (`$SCRIPT_DIR`/`APP_DIR`). This applies to every** fork-based AND dx_app showcase (and is the same self-containment retrain-eval requires per §6 of dx-compiler/.deepx/toolsets/ultralytics-train-eval.md).

1. dx_app-based showcases MUST follow the dx_app relocatable script patterns. A

showcase whose app uses a dx_app model / dx_engine MUST author setup.sh/run.sh per dx-runtime/dx_app/.deepx/skills/dx-agent-app-build-python/SKILL.md — run.sh: derive the model path from $SUITE_ROOT/dx-runtime/dx_app/assets/models/…, NEVER an ancestor-walked ${DX_APP_ROOT:-}/… (collapses to an unresolvable path once relocated — the squat model-not-found bug); setup.sh: reuse venv-dx-runtime or write a dx_runtime_bridge.pth, NEVER a local venv that only FATALs on missing dx_engine (the stretching ModuleNotFoundError bug). Retrain-eval showcases MUST be self-contained per dx-compiler/.deepx/toolsets/ultralytics-train-eval.md §6 (no absolute paths in *.json; regenerate-if-missing). verify enforces all three (model-discovery / venv-bridge / abs-paths).

Setup

# Make the tool importable (editable) or use PYTHONPATH:
export PYTHONPATH="$(git rev-parse --show-toplevel)/.deepx/tools/src"
SG() { python3 -m dx_showcase_gen.cli "$@"; }   # or the installed `dx-showcase-gen`

Phase 1 — Requirements + prompt synthesis (KB)

• Gather the showcase scenario (what the showcase demonstrates, the target user).
• Synthesize the end-user-style natural-language build prompt — the prompt a real

user would type, no operator scaffolding. Keep it short and goal-only: name NO toolset path, KB file, repo branch, or env script — the skill + the routing table supply those from the task vocabulary, and a concise prompt that still builds correctly is the whole point of the showcase. (Headless/unattended runs may append "work autonomously … / Respond in English"; if so, that scaffolding is trimmed from the displayed prompt in the showcase README — see Phase 7.)

• The prompt MUST also require a visualized detection sample: an annotated image of

the (retrained/exported) model run on a representative domain sample, saved as sample_detect.jpg — this is shown beside the build GIF in the README (Phase 7).

• Fix tool=claude, model=claude-opus-4-8.
• In autopilot (user absent), pick scenario defaults from the KB; do not block.

Phase 2 — Recording-prep gate (human-in-the-loop)

• Guide the user to clear a screen region and open a terminal there; the build

terminal must not be overlapped by other windows for the whole recording.

• WAIT for explicit "ready" before starting. In autopilot, launch the build terminal

in an already-cleared region and crop to its rect (capture full screen, post-crop).

Phase 3 — Recorded build (real claude screen)

SG keepawake start --pidfile /tmp/sc.ka.pid                 # stop GNOME blanking
SG capture-start --output /tmp/sc.raw.mp4 --pidfile /tmp/sc.ff.pid   # full-screen
# Run the build in the prepared, titled terminal, TEEING stream-json:
#   claude -p "<PROMPT>" --model claude-opus-4-8 \
#     --output-format stream-json --verbose | tee /tmp/sc.stream.jsonl
# (interactive real-TUI runs are captured the same way — the human runs claude.)
SG capture-stop --pidfile /tmp/sc.ff.pid ; SG keepawake stop --pidfile /tmp/sc.ka.pid
SG crop --input /tmp/sc.raw.mp4 --output /tmp/sc.crop.mp4 --title DEEPXBUILDREC
SG gif  --input /tmp/sc.crop.mp4 --output docs/source/img/dx-agent-dev-<name>-build.gif \
        --duration <recorded_secs>

• Headless unattended fallback (no human to run the interactive TUI): launch a

titled gnome-terminal that runs the build while LIVE-rendering the stream to the screen so the recording captures the build AS IT HAPPENS. The build command MUST pipe stream-json through the renderer to the terminal in real time, NOT redirect-to-file: ```bash # CORRECT — live: render prints to the terminal as events arrive (tee keeps the raw for the transcript) stdbuf -oL claude -p "<PROMPT>" … --output-format stream-json --verbose --dangerously-skip-permissions \

`` The render MUST preserve newlines (so the DEEPX banner renders) and be cropped to the terminal rect. **HARD: never claude … > stream.jsonl then render at the end** — that leaves the screen static during the build, so the GIF shows a frozen "BUILDING" screen instead of the real build (a recurring mistake). verify` rejects a static (no-motion) GIF.

• If the agent stops at the brainstorm approval gate, add

"work autonomously to completion; produce the actual artifacts" to the prompt.

Phase 4 — COMPLETE transcript

SG transcript --stream-json /tmp/sc.stream.jsonl \
   --session-id <uuid> --project "$(git rev-parse --show-toplevel)" \
   --out-dir dx-agent-dev-showcase/<name>

• This writes claude-code-session.{md,html,jsonl} and fails unless the stream

carries a result event (⇒ Wall-clock + Cost). Never substitute the in-session sentinel output for the showcase transcript.

Phase 5 — Artifact copy + portability

SG copy-artifacts --session-dir <build_session_dir> --showcase-dir dx-agent-dev-showcase/<name>

• Copies the generated files (skips venv / caches / heavy recordings / runtime-download

dirs) and prints any absolute/session-specific path refs in scripts AND data files (`*.json`). Fix every flagged ref so the showcase runs standalone (SCRIPT_DIR / SUITE_ROOT relative; auto-download instead of /tmp; no absolute best_pt/save_dir in train_result.json).

• Curated run-evidence is a committed deliverable (retrain/export showcases). The

produced models and training evidence MUST be copied in and committed so a fresh git clone carries the real artifacts (no recompile needed) — this is the recurring "runs/ + *_deepx_model/ were regenerated locally but never committed" gap:

• *_deepx_model/ — the DeepX export dir(s) **with config.json + metadata.yaml +

the .dxnn** (base and retrained).

• runs/<train>/ training evidence: results.png, confusion_matrix*.png,

Box*_curve.png, results.csv, args.yaml, val_batch*_pred.jpg, and weights/best.pt (the retrained weights). last.pt is optional.

• metrics.json + sample_detect.jpg.

The .gitignore re-includes *.dxnn/*.onnx/*.pt under dx-agent-dev-showcase/** (only env/cache/download/dxnn_models/output dirs stay ignored), and verify FAILS a retrain/export showcase missing this evidence. After copy, `git add` the deliverables explicitly (they are untracked until added).

Phase 6 — Run/result GIF

• Record the generated app running (or the report/eval run) → a second GIF

docs/source/img/dx-agent-dev-<name>-run.gif via the same capture→crop→gif path. Optional when the showcase has no visual runtime (then the build GIF suffices).

Phase 7 — Catalog + docs (manifest-driven, single source)

The showcase's OWN README is written in its dir; the THREE cross-showcase surfaces (root README card grid, showcase catalog, docs 00_Agent_Driven_Development table) are GENERATED from one manifest — never hand-edited.