| name | luxonis-build-poc |
| description | Build a thin, runnable Luxonis/OAK proof of concept from a project brief by adapting a known-good example. |
| disable-model-invocation | true |
| argument-hint | project brief path or application goal |
| metadata | {"author":"luxonis","version":"1.0.0","status":"stable"} |
Luxonis Build POC
Build the thinnest runnable slice that demonstrates the brief's core value on a real OAK
device -- by adapting the closest known-good Luxonis example, not by inventing a pipeline from
scratch. One vertical slice that runs end-to-end beats a broad, half-wired app.
End in exactly one state:
- running-demo -- the slice runs and shows the brief's core success observation, proven by
re-running the exact command/snippet you report.
- blocked -- cannot reach a running demo locally; report the one blocking layer, the
evidence, and the next action (e.g. verify a device with
luxonis-device-setup).
Core discipline
- **Adapt a known-good example; never invent the DepthAI API from memory.** Tie every API
call to an example you cloned or a docs page you read.
- **Confirm the `depthai` version before writing pipeline code.** Always target DepthAI v3,
never v2 -- they differ sharply; match the installed major version and never mix v2 API into
v3 code. In DepthAI v3, `ColorCamera`/`MonoCamera` are deprecated on all platforms (RVC2
and RVC4 alike) -- use the `Camera` node.
- **One vertical slice first.** Get a single path running end-to-end before adding any second
behavior, option, or polish.
- **Never compile DepthAI from source.** If that seems required -> **blocked**.
1. Preflight
Read the working directory and the user's input. If present, read PROJECT_BRIEF.md (what to
build) and DEVICE.md (a cached record of a previously verified device). Be self-sufficient:
do not assume any sibling Luxonis skill is installed. Resolve the brief first, then the device.
Brief. No PROJECT_BRIEF.md -> the purpose-built tool is /luxonis-project-interview if
the user has it; otherwise capture a one-paragraph goal inline (behavior, target, success
observation) and continue. Do not run a full interview here.
Device. A running demo executes on real hardware: DepthAI cannot run without a connected
OAK (both RVC2 and RVC4 -- there is no host-only or simulation mode), and replay is an
on-device input source, never a substitute for a device. DEVICE.md is a hint, not proof a
device is attached, and it can be stale. Resolve the device by live reachability, not by the
presence of the file:
DEVICE.md present -> reconcile it against a quick live check. If the recorded device still
opens, use it. If a different device is discovered instead, trust live discovery, use it, and
offer to update DEVICE.md.DEVICE.md absent -> do not assume "no device". Run a minimal reachability probe (can a
known-good DepthAI snippet open a device and stream one frame). Do only this probe here; if it
fails in a way that needs real setup work (USB/udev, PoE, adoption), route to
/luxonis-device-setup.- Device reachable -> build the slice and run it (the normal path to running-demo).
- No device reachable -> build the slice and prepare the exact run command, then end
blocked: the slice is code-complete and ready, but proving it needs a verified device --
run
/luxonis-device-setup, then re-run this skill.
2. Knowledge sourcing
For any Luxonis-specific fact (device capabilities, API/SDK, commands, version requirements),
read live docs starting from `https://docs.luxonis.com/llms.txt` and follow its linked `.md`
pages, then web search only if the docs do not cover it. Never answer such facts from model
memory.
Use cloned example code as the implementation reference -- and only the curated
oak-examples repo on its main branch, which tracks DepthAI v3. Clone lazily, only when you
are ready to adapt one:
- Create the directory
~/.luxonis/agent-context (the .luxonis/agent-context folder in the
user's home) if it does not exist.
- Clone
https://github.com/luxonis/oak-examples over HTTPS (never SSH), shallow and
pinned to main, with git's low-speed guard (http.lowSpeedLimit=1000,
http.lowSpeedTime=60) so a stalled network aborts instead of hanging. Clone into a
temporary sibling path (e.g. oak-examples.tmp) and rename it into place only on success,
using commands appropriate to the host shell, so a failed clone never leaves a partial
checkout behind. If the checkout already exists, refresh it with a fast-forward-only pull
instead.
- A checkout is usable only if it contains
INDEX.md. If the clone fails or the directory is
incomplete, treat examples as unavailable and fall back to live docs. Never read a partial
checkout, and never substitute web-searched, older, or v2-era examples: always DepthAI v3,
never v2.
Navigate the checkout with its agent-facing catalog: read INDEX.md (match the brief to
Tags/Shape/Mode) and ESSENTIAL_KNOWLEDGE.md for shared vocabulary, then the chosen
example's AGENTS.md, then its README.md. With oakctl present, oakctl app examples list
is an alternative way to browse.
3. Choose the run path from the brief
The brief's desired run location plus the device family decide the shape:
- Laptop/computer connected to the camera -> host-side script (
Shape: script,
Mode: host). Plain Python with depthai, run on the host.
- On the camera, no computer connected -> standalone OAK app (
Mode: standalone),
packaged with oakapp.toml and run with oakctl app run. Requires RVC4/OAK4.
If the target is unclear, ask one question; do not build both. Pick the example whose
Shape/Mode already matches the chosen path so you adapt, not convert.
4. Build one vertical slice
Start from the closest example and change as little as possible to hit the brief's primary
behavior. Install host dependencies only in an isolated venv -- never global pip, never
edit project deps without approval. For standalone apps, keep the example's oakapp.toml
shape and adjust only what the slice needs.
5. Verify, then stop
The brief's success criteria define "works". Run the slice and capture the concrete
observation that proves it.
When the run fails, fix one hypothesis at a time and re-run the same command -- serialize
changes so you never stack edits or run competing device commands. Declare running-demo
only on a passing re-run; if you cannot run it (no device/offline), say so plainly and mark
blocked -- do not claim a demo that never ran.
Once the slice runs, stop. Record assumptions, the exact run command, and obvious next steps
in chat (or a short POC_NOTES.md if the user wants it). Do not broaden scope unprompted.
Guardrails
- Gate privileged/persistent actions. Global
pip/project-dependency changes, OS update,
flashing, factory reset, Hub adoption, publishing an app -> confirm first. Building and
running a dev app locally is fine.
- Models, not training. Reuse DepthAI Model Zoo / example models. If the target needs a
custom model, say dataset/training is required -- do not claim to train one here.
- WSL USB honesty. Do not pretend WSL has USB access; stop until the user exposes the
device or runs from a host with direct USB.
- Hardware fault (orange LED, boot failure, suspected calibration) -> blocked, contact
support@luxonis.com.
- Something already built is broken/slow/confusing rather than newly built -> that is
luxonis-troubleshoot's job.
Docs
