Odevio Agent Skill

Odevio — from a Flutter project to an iPhone

Odevio builds and signs iOS apps on remote Macs. The user needs no Mac and no iOS knowledge: certificates,

provisioning profiles and app identifiers are already automated. This skill drives the whole path and asks as

little as possible.

Read this file fully before acting. Then read a reference only when its situation arises:

| Reference | Read it when |

| ---------------------------------- | -------------------------------------------------------------------------------------- |

| references/first-time-setup.md | no Apple developer account registered, or no Odevio app for this project |

| references/when-a-build-fails.md | a build failed |

| references/delivery.md | a build succeeded |

| references/app-store-listing.md | the goal is the App Store — read it before building, not after |

| references/cli-contract.md | you are unsure how a command behaves — it records what was learned by getting it wrong |

| references/voice.md | always, before acting - how to speak; the words never to use |

Before anything — make sure Odevio is installed

This skill drives the odevio command; it does nothing without it. If you reached this skill through

discovery rather than odevio skill install, the CLI may not be present yet. Check once, install if missing:

odevio --version || pip install odevio

Use pipx install odevio instead if this machine's Python is externally managed. Then, so the commands

below run without a permission prompt each time, register the skill for your agent once:

odevio skill install

Neither step re-does anything already done — both are safe to run when Odevio is already set up.

How to talk to the user

This matters as much as the mechanics. The words never to use, when to stay silent, and how to ask a

question live in references/voice.md. Read it before you act - it is not optional.

Step 0 — What do they actually want

Their goal decides the kind of build, whether Apple's side needs setting up at all, and what "done" means. It

is the one thing you cannot read from the project.

If the way they asked already says it — "get my app on my phone", "publish it", "does this even build" —

take it and never ask again.

If they gave no clue, for instance a bare invocation, ask once, in outcomes, never with type names.

Offer these five, and all five, whatever form the question takes:

| Offer it as | Never as |

| ----------------------------------------------- | --------------------------------------- |

| See it running on a Mac we provide | a configuration build, a remote desktop |

| Try it on your own iPhone | ad-hoc |

| Share it with a few testers, through TestFlight | publication |

| Put it on the App Store | publication |

| Just check that it compiles | distribution |

Publishing to the App Store is its own answer, and the one most easily lost. It shares a build with the

testers option, which makes it tempting to fold the two together — do not. They lead to entirely different

work: testers means the app is with Apple and you are finished, while the App Store means a page has to be

written, pictures provided and a questionnaire answered. Someone who meant to publish and was offered only

"send to testers" has no way of knowing the rest exists.

The wording of each option is what the user reads, so no build type ever appears in it — not in the

heading, not in the explanatory line underneath. "Sends it to Apple and puts it in front of your testers"

says what happens. "Build publication — envoi chez Apple" leaks the machinery and tells them nothing they

can act on.

The first option matters more than it looks: seeing it running needs no Apple account at all. Everything

else on that list requires a paid Apple developer account, so for someone who has not paid yet, that is the

only thing you can offer today — and it is a real one, not a consolation prize.

Do not skip this and default to compiling. A silent assumption is worse than a question here: it spends a

quarter of an hour producing something they did not ask for, and the App Store route needs a manual step that

the others do not.

If they said the App Store, read the page before doing anything else. Not after building — before. Go to

references/app-store-listing.md now and run odevio app store-status.

The reason is concrete: Apple may already hold a build. Building takes a quarter of an hour and occupies a

machine someone else is waiting for, and there is no point spending either if what is needed is a description

and three pictures. Only the page can say which of the two it is.

Then say what the whole thing involves, and what you are about to do first. Sending the app is the easy half;

the page has to be filled in too, and two parts of it can only be done on Apple's own website:

> Right — the App Store. Two things there that only you can do, about ten minutes in total: creating the

> app's page, and answering Apple's questions about data. I will tell you exactly what to click.

>

> Let me look at where your page stands before anything else — if your app is already with Apple there is no

> need to build it again.

Only once the page has been read does building become a question, and then it is one to put to them rather

than assume. references/app-store-listing.md covers the three cases.

Step 1 — Find out what is already there

Read the state before asking anything. Stop at the first blocking check.

Run as few commands as will do. Every one appears in front of the user as a block of shell and output,

and a screenful of it before the first sentence makes a tool that promised to handle things look like it is

rummaging. Two rules keep it short:

• Never inspect your own installation. Listing the skill's own directory, reading its own files to see

what is there, checking where it is installed — none of that tells you anything about their project and

all of it is visible to them.

• One command per fact, and only facts you are about to use. odevio profile proves the CLI is

installed _and_ that there is a session, so odevio --version on top of it earns nothing. Their version

is worth having only when something has already gone wrong.

| # | Check | If missing |

| --- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

| 1 | odevio profile — is the CLI there, and is there a session? | blocking — if the command is not found, offer pip install odevio and stop; do not install it yourself, as the wrong Python environment is worse than none. If it asks for credentials, see below |

| 2 | odevio app ls — an app matching this project? | references/first-time-setup.md |

| 3 | odevio apple ls — any Apple account registered? Only needed when step 2 found nothing, since an app already carries its account | references/first-time-setup.md |

| 4 | pubspec.yaml and lib/ present? | blocking — say they are not in a Flutter project and stop, rather than uploading an unrelated directory |

From pubspec.yaml, record without asking: the app name, the version, and the build number after +. Note

any .odevio file, and the identifier already configured in the project.

Match step 2 against that identifier. A match settles both the app and the Apple account, so neither is asked.

Only if several plausible matches remain do you ask — showing names, never internal keys.

If step 1 asks for credentials, this is one of the hand-overs. You cannot sign in for them: these

commands prompt, and a prompt without a terminal dies on an error rather than working.

> You need to sign in to Odevio first — run odevio signin in your terminal, it'll ask for your e-mail and

> password. Tell me when it's done and I'll carry on from there.

With no Odevio account at all, offer both odevio signup and creating it on https://odevio.com, usually

gentler the first time. When they say they are done, verify with odevio profile rather than taking their

word.

What the user sees from this step: almost nothing. These checks are your bookkeeping. When everything is in

place, that is one warm sentence and you carry on.

Step 2 — Check locally, for free

Before spending a remote build, run what costs nothing:

• flutter pub get — failures here are a typo in pubspec.yaml, or a package that does not exist
• dart analyze — catches most beginner mistakes
• flutter test — skip silently when there is no test directory; a fresh project with no tests is normal

Fix what they report locally, in a loop, without touching Odevio.

Do not run flutter build apk. It needs the whole Android toolchain, which the user may not have, and an

Android failure says nothing about an iOS build — a pass gives false confidence, a failure sends you chasing

an irrelevant problem.

Do not attempt an iOS build locally. Not having a Mac is the whole reason Odevio exists.

Be honest about what this proves: nothing about iOS. Native plugins, CocoaPods, Xcode configuration and the

deployment target can only surface on the remote build. A project can pass all three checks and still fail on

iOS — that is the normal case this skill exists to handle.

Step 3 — Build

Map the goal onto a build type

The goal came from Step 0. Translate it here, and never discuss type names with the user — they do not know

them and explaining them is not a service.

Everything in this table is for you. None of its wording belongs in a message or in a list of choices,

and the right-hand column least of all. Copying a row into an option is how publication and ad-hoc end up

in front of someone who came here to avoid exactly that.

| What they said they want | Type |

| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

| see it running, without paying Apple anything | configuration — a Mac desktop with their project and the iOS simulator. No Apple account, no certificate, no app needed |

| try it on their own phone, nothing shared | ad-hoc — installs straight from a link or QR code, needs the device registered first |

| share it with a few testers | publication — uploads to Apple, feeds TestFlight |

| put it on the App Store | do not come here first — references/app-store-listing.md decides whether a build is needed at all, since Apple may already hold one. When one is needed it is publication, the same as the testers option, with entirely different work afterwards |

| just check that it builds | distribution — builds and signs, uploads nothing |

A configuration build is the only type that survives without Apple credentials: the server tolerates the

failure to send them for this type alone. See references/delivery.md for what to tell them about it.

If you reach this point still not knowing, go back to Step 0 and ask. Do not pick one on their behalf.

Build the type they actually want, from the first attempt

Do not run a verification build first. It costs a full fifteen minutes and a slot on a shared Mac to

produce something that cannot be installed, and then the real build has to run anyway. For a project that

compiles — the common case — the whole job should be one build.

What the server actually meters, checked in its code, makes this safe:

• there is no per-build credit. The only limit is a rate: a free account may publish once every few days
• it applies only to free accounts, and only for apps outside a team. Paid accounts and team apps have no

limit at all

• only validation and publication count towards it. distribution and ad-hoc count for nothing
• a failed build does not count either: FAIL and STOP are excluded from the statuses considered

So retrying a failed publication is free of quota consequences, and there is no reason to detour through a

throwaway build.

Use distribution in exactly one case: when the goal from Step 0 was only to check that the app builds.

One thing to watch, for a free account only: a publication that is queued or running does count while it is in

flight. So never launch a second one alongside it — which the rule against two concurrent builds already

covers.

Launch

COLUMNS=200 odevio build start <app-key> <project-dir> \
  --build-type <type> --no-progress --flutter <version> --build-number <n>

• put COLUMNS=200 in front of the command itself, as above — never export COLUMNS=200; followed by

the command. The default 80-column formatting wraps long values onto continuation lines and silently

breaks parsing, but a chained command also loses the permissions this skill was granted, so the user is

asked to approve something that should have been silent. See the rule on running one command at a time

• increment --build-number on every attempt, or a reused number triggers an interactive confirmation
• prefer a Flutter version already on the host: the first build of a new one pays to download and extract a

2.2 GB SDK, and that space is never reclaimed

Take the key from the output, between the quotes:

Build #8 has been registered. It has key "K7B3Q" and will be started as soon as possible.

No key means stop. Never continue without knowing which build to follow.

Follow

Watch it without blocking yourself. Start the watcher in the background, so you stay able to answer while

it runs, and let it tell you when something changes. Never sit in a foreground loop of sleep calls: it locks

you up for minutes at a time, and you have just promised the user they can ask you anything — a promise you

cannot keep while blocked. If the host offers no way to watch in the background, say honestly that you will

check back rather than claiming to be reachable.

Warn them that starting the watcher asks for approval. Whatever runs a background task is not among the

commands this skill was granted in advance, and deliberately so: it can carry any shell command inside it, so

pre-approving it would quietly undo the care taken to have anything touching Apple confirmed. The user

therefore sees a prompt full of shell they have no way to judge, at the exact moment you told them to relax.

Put the loop in the command itself, never in a script file you then run. Approving zsh /tmp/…/watch.sh

asks someone to trust a path they cannot read; approving the loop shows them a poll of odevio build detail

and a sleep, which is at least judgeable. Same prompt either way — one of them treats them as an adult.

Say what it is before it appears, in the same message as the waiting one:

> Your app is building. Your tool will ask you to approve one thing — it is just how I keep an eye on the

> build without blocking this conversation. Allow it and there is nothing else to do.

What to watch: COLUMNS=200 odevio build detail <key>, roughly every 20 seconds, reading the Status : line.

Stop on any end state — Succeeded, Failed, Stopped, or Configuration for remote desktop — not only

on the first two:

Waiting for available instance → In progress - Starting instance
→ In progress - Preparing build → In progress - Building app → Failed or Succeeded

A configuration build never reaches Succeeded. Its finish line is a different status,

Configuration for remote desktop, because the Mac is now waiting for the user rather than having produced

something. Watch for that one, and treat it exactly as success — the moment it appears, fetch the connection

details and hand them over without being asked. Waiting for Succeeded on this type means waiting for ever

while the user sits in front of a ready machine.

Whatever you promised in your waiting message, deliver it the moment the build reaches its end state. If you

said "I'll give you the connection details as soon as it's ready", that is a commitment to act on the

transition, not something to produce when prodded.

Translate for the user, never quote: waiting for a free Mac; the Mac is starting up; getting your project

ready; compiling, which is the long part; and for a configuration build, your Mac is ready.

Three things to handle:

• a poll can return nothing. Roughly one in thirty gives no status line. Treat it as "unknown, poll

again", never as an ending

• queueing is normal — 8 minutes 30 seconds was measured behind one other build. Say so, or silence reads

as a freeze

• queueing can also be permanent. Stale records on the server make a host look busy for ever, with no

error anywhere. Past ten minutes queued, stop and tell them to have someone check the server side

If they ask where it's at, answer from a fresh build detail, in plain words, then say again there is

nothing to do and go back to watching. Being interrupted must never start a second build — resume

following the one already running. If they ask you to stop: odevio build stop <key>.

What it really costs

Measured on an empty project, so a floor rather than an average:

| Queueing | VM start and preparation | Xcode archive | Whole build |

| ---------- | ------------------------ | ------------- | -------------- |

| 8 min 30 s | ~8 min | 8 min 51 s | 15 min 9 s |

The same compile takes 30 seconds on a developer's own machine — the VM is about seventeen times slower. Tell

them an attempt takes roughly fifteen minutes, and never suggest it will be quick.

Never run two builds at once for the same project: there are two slots on one Mac for every Odevio user, and

two builds slow each other down.

Step 4 — Then

Failed → references/when-a-build-fails.md. Classify before touching anything: changing their code

because of an infrastructure problem is the worst thing this skill can do, and they will not notice.

Succeeded → references/delivery.md. What they actually get depends on the type, and a distribution

build produces nothing installable.

Hard rules

Never fabricate a value the user must own. Identifier, app name, Apple credentials: derive or propose,

then let them confirm. Never invent an Apple ID, a team, or a key.

Stop cleanly rather than continue blind. If a command fails in a way this skill does not cover, or output

cannot be parsed, report exactly what happened and stop. A wrong guess costs a fifteen-minute slot, or a

broken project.

Never print secrets. The .p8 key is referenced by path only.

Every Odevio command must be non-interactive. Pass every argument explicitly. If a command opens a menu or

asks for confirmation, you omitted an argument — supply it rather than answering the prompt.

Run one command per call. No ;, no &&, no pipes into head, no export on a line of its own. The

harmless-looking read commands are pre-approved so the user is never interrupted by them, and that only works

when the command runs on its own: chain two together and the whole thing stops being recognised, so someone

who asked for their app to be published is instead asked to approve a shell command they cannot judge.

Read the whole output rather than piping it through head. It is short, and truncating it is how the wrong

value gets parsed.

Some commands are deliberately not pre-approved, and the line is not "does it change anything on Apple".

Filling in a description changes something on Apple, and interrupting someone to confirm it would be absurd.

The three things that earn a question are:

• it cannot be undone — odevio app check-submittable opens a review submission Apple never lets you

delete, and submitting for review is final

• it costs a machine — odevio build start, and the simulator commands, take a Mac for up to an hour

that someone else is waiting for

• it can destroy something with no copy elsewhere — odevio screenshot push clears the pictures already

on a slot before sending, and pictures uploaded directly to Apple exist nowhere else

Everything else is fair to run unannounced: writing the page's text, attaching a build, reading anything.

All of it is reversible, none of it is visible outside their own account, and stopping to ask turns a tool

that was supposed to handle the tedium into a series of dialogues.

Never invent a command, and never invent an option either. If you find yourself reaching for one that is

not written in these files, it almost certainly does not exist — odevio device does not, for instance, and

odevio build ls --app-key does not either. Check with odevio --help or odevio <group> --help before

running anything you have not seen here, and if the thing you need has no command, it is because a human has

to do it somewhere else. Say that instead of guessing.

Options are the easier mistake of the two, because a plausible flag reads like something that must be there.

build ls filtering by app is the obvious example: it sounds inevitable, and it does not exist. Filter the

output yourself rather than inventing the argument that would have done it for you.

The full surface, so there is no need to guess: top-level signup, signin, signout, profile, apikey,

skill; and the groups build (start, ls, detail, logs, ipa, download, patch, connect,

tunnel, stop, rm, flutter-versions), apple (ls, detail, add, edit, rm, link, unlink,

refresh-devices), app (ls, mk, rm, link, unlink, import, screenshots, store-status,

set-metadata, categories, attach-build, check-submittable), privacy (scan), screenshot (devices, start, capture, push) and team.

One of those is not like the others. odevio app check-submittable opens a submission on Apple that

cannot afterwards be deleted. It gives Apple's own verdict, which is worth having, but only run it when the

user means to finish — never to check on progress. odevio app store-status answers that, and changes

nothing.