Port To Os8088

Port a program to os8088, in C

This skill turns a reference codebase — the original program, in whatever language — into a native os8088 package written in C, the way apps/cword/ is Microsoft Word 1.1a. "Port" here means what it meant there: the user interface is the original's, taken from its source and not from memory; the behaviour is reimplemented in the strict C subset this toolchain compiles; what cannot be carried is present and greyed with the fact that greys it, never silently missing. The code of the original almost never compiles here and is not expected to. Its resources, tables, formats and behaviour do.

Invoking this skill authorises the multi-agent orchestration below (the Workflow tool — what the user calls "ultracode"). Every phase that reads a lot or writes a lot fans out; every decision that is the user's comes back to them through AskUserQuestion; everything else you decide and record.

Three files travel with this skill and are read by every agent it spawns:

Also binding, and already in the tree: docs/C-TOOLCHAIN.md (what to type and what each refusal means), SPEC.md §73 (the contract), apps/cc/os88.h (the API), CLAUDE.md (the hard rules and the performance table).

0. The model gate — do this first

This skill is supported on Opus 5 and Fable 5 only. Look at the # Environment block of your own system prompt: it says which model is running. If it is not claude-opus-5 or claude-fable-5, say so in one line, tell the user to switch with /model and re-run /port-to-os8088, and stop. Do not run the workflows on another model: they were sized and worded for these two, and a smaller model reading twenty thousand lines of someone else's source and a 50,000-line SPEC does not scout, it guesses.

Never pass a model override to an agent inside the workflows — they inherit the session model, which is the one the gate just checked.

1. Read before asking

1. LESSONS.md beside this file — all of it.
2. docs/C-TOOLCHAIN.md — the four rules, the ceiling, the overlay.
3. apps/cc/os88.h's header comment, and skim the prototypes.
4. SPEC.md §73.12 (the CWORD account) and §73.14 (the overlay).
5. apps/cword/cword.c's header comment — the redraw model and the cost table.

That is ~1,500 lines and it is the difference between a plan that fits and one that discovers the 60KB ceiling in wave 4.

2. Intake — where is the reference source?

Ask, with AskUserQuestion, in one call — three questions:

1. Where is the reference source? (single select)
   • Scan for repositories here (Recommended) — you list every git checkout in the current directory and its parent (ls -d ./*/ ../*/, keep the ones with a .git), and the user picks from them.
   • I will give you a list to clone — the user supplies URLs (or paths) in "Other"; you git clone --depth 1 each into the session scratchpad directory (never into this repo, never into build/).
2. What is the program? (single select)
   • Infer it from the repository — its name, README and about text (Recommended)
   • I will type the name and version — "Microsoft Word 1.1a", "Lotus 1-2-3 2.01"; the answer arrives as "Other".
3. Anything about scope you already know? (single select)
   • No — port it whole and grey what cannot carry (Recommended)
   • Yes, I will describe it — a subsystem to leave out, a file format to prefer, a feature that matters most; arrives as "Other".

If they chose scan, run the scan and ask a second AskUserQuestion (multiSelect) listing what you found — path, top-level language guess from file extensions, and one line from its README if it has one — and let them pick one or more. If nothing plausible is found, fall through to clone.

Then confirm the set back in one line and record it: write a memory (a reference type, like the existing word-opus-source memory) naming where the reference source lives, because the repo will never say — SPEC.md names the release, not a path — and the next session that touches the port will need it.

Two things to say to the user here, once, plainly:

• The reference source stays outside this repo. Nothing is vendored (CONTRIBUTING.md §6): the port quotes strings, tables and formats and cites the file; it does not copy code. If the reference is under a licence that needs attribution, that attribution goes into every file header that carries derived material and into the About box — CWORD carries the Computer History Museum credit exactly so.
• The port will be written in the C this toolchain accepts, which is smaller than C: no long, float, double, no &local, no struct by value, no printf, no malloc as they know it, one translation unit, 60KB. A program that needs 32-bit arithmetic on its hot path is a candidate for a rewrite of its behaviour, and the plan will say so.

3. Preflight — the machine and the branch

tools/setup-cc.sh && make cc-smoke        # the compiler, at the pinned commit; the smoke test builds
make covl                                 # the overlay gate builds (you will very likely need the overlay)
pkill -f qemu-system-i386 || true         # a stale QEMU answers on build/qmp.sock with an OLD image
git status --short                        # clean tree
git checkout -b port/<name> main          # branch; never work on main

If setup-cc.sh fails, that is a blocker for the user (network, Xcode tools) — say what it printed and stop. Every later step needs the compiler.

4. Scout — the multi-agent survey

Workflow({ scriptPath: "<abs repo>/.claude/skills/port-to-os8088/workflows/scout.js",
           args: { repo: "<abs repo>", sources: ["<abs path>", ...],
                   app: "<program name and version>", name: "<proposed package name or ''>",
                   notes: "<the user's scope notes>" } })

It runs one scout per reference repo and three over this tree, one planner, three adversarial reviewers and a reconciler, and returns { plan, sources, tree, reviews }. The plan is JSON in the shape PLAN_SCHEMA in scout.js: name, authority table (surface → defining source file), scope (ships / greyed-with-fact / absent), file split, byte budget with its basis, API gaps, waves, verification, risks, and questions.

While it runs, do nothing that touches the tree. If it returns with a source report missing (a null in sources), say which repo failed and re-run scouting for that one alone before planning on three-quarters of the facts.

5. Decide — the user's questions, and yours

Take plan.questions to the user with AskUserQuestion, at most four questions per call, each with the plan's options and its recommendation first, labelled (Recommended). Typical ones, and they are the only kind that belong here:

• the package name, if the plan's is unsure or collides
• a scope cut that changes what ships (which of two file formats; whether a whole subsystem is greyed or built)
• whether to spend an API slot / add a thunk versus greying a feature
• which reference wins where two disagree

Everything else — the file split, the wave order, the buffer sizes, which mode the program opens in — you decide, and you record the decision in the plan. Do not ask a question whose answer is in LESSONS.md or the SPEC.

Then write the plan into the tree, in this order:

1. SPEC.md — a new top-level section at the end (the next free number), titled <N>. <NAME> — <Product>, written in C, in the shape of §73.12: what it is, where the UI comes from (the authority table), the two segments and the byte budget, what ships, what is greyed and the fact for each, the names (package, dir, images, vm) and the sentence that it shares nothing with any other package. SPEC is updated before the code, and this is the section every wave amends. make runs tools/checkdocs.py, so every § you cite must exist.
2. docs/plans/<NAME>-PORT-PLAN.md — the plan itself, with the user's answers folded in and the questions section replaced by "Decisions". This is the file the implementation workflow reads.
3. Commit the two: Plan the <NAME> port (SPEC.md §<N>).