Module 2 of 10

Your first app

A video for this module is coming.

What you'll do

You will run /shipyard:new-app, answer up to five questions, approve a written plan, and end with a live app at a real web address that has passed its checks. Then you will learn how to make changes safely. You need to have finished Install and set up first.

Start it

Open Claude Code in the folder where you want your apps to live, and type:

/shipyard:new-app

Shipyard first checks that GitHub, Vercel and Supabase are connected. If one is missing it offers to run setup and stops. If you started an app before and ran out of usage, it offers to continue where it stopped. Your progress is saved after every step.

The three services, in plain words

• GitHub stores your app's code and its full history. Think of it as the safe copy.
• Vercel puts your app on the internet. Every app gets a free address like your-app.vercel.app.
• Supabase is the database (where your app's information lives) and the sign-in system (accounts and passwords).

The app itself is built with Next.js, a popular tool for making websites that work like apps. You do not need to know it. The agent does.

The five questions

Shipyard asks about outcomes, never about technology. It asks one at a time and says which answer it recommends. If you already told it something, it does not ask again. You can answer all at once, even by dictating a long ramble.

1. Who is it for, and what problem does it solve?
2. What is the one main thing a person does in it?
3. Will it make money? Free, paid subscribers or an email list. Free is the default. Payments come later, so this is only noted.
4. Will people use it on phones, and should it be installable? This also decides the menu style: tabs along the bottom for phone-first apps, a left sidebar for tools, links across the top for site-like apps.
5. Is there a look you like? A name, a website, a screenshot. If not, you choose in the design step.

If you say "you decide", it decides and tells you what it chose.

The plan and SPEC.md

Shipyard writes a file called SPEC.md in your new app's folder. It holds who the app is for, the main action, the features as small steps (marked first version or later), what data is stored, and the hard rules it must follow. It also gives you a plan of five to eight steps in plain words.

Nothing is built until you say "go". Read the plan. If something is off, say what to change. This is the cheapest moment to fix anything.

What gets created

After "go", Shipyard works through these steps. You mostly watch.

1. A starter app. A working app with sign-in, light and dark mode, your chosen menu layout, installable as a phone shortcut (a PWA), and a test gate described below.
2. The look. If you saved a default look, it is applied. Otherwise you get the design question; see Design without AI slop.
3. Your features, built in small steps. Every piece of logic gets a test, and every table of data follows the privacy rules in Data and safety.
4. The database. Shipyard creates the Supabase project and sets it up. The free plan allows two active projects in total, across all your organizations. If you already have two, Shipyard offers two choices: pause a project you no longer use, or put the new app inside one of your existing projects. In that case the app gets its own separate space (a schema, like a folder for its tables), and Shipyard never changes anything the other apps in that project use. The apps do share one list of logins, so someone with an account in another app there can sign in to this one with the same email and password. Each app's data stays separate.
5. Save to GitHub. It asks first: "OK to save this first version to GitHub?" The repository is private by default. Nothing is saved without your yes.
6. Publish on Vercel. It connects the project, sets the settings, and turns off a login wall that would otherwise block visitors. It prints your address.
7. Your own account. It creates your account as the owner and opens a one-time sign-in in your browser. The link is never printed in the chat.
8. A hand-off file. HANDOFF.md lists what is where, how to run the checks, how to make changes, and the known limits.

The verify gate

Before Shipyard says the app is live, it runs verify. This is the "make it prove it" idea from module 1, done by a script. It checks the real address, not just that Vercel said "ready".

It also says what it could not check, for example forgot-password email, payments and real devices. Look at the two phone screenshots it saves. If anything is off, tell Shipyard and it fixes and re-runs until the checks are green, or explains plainly what is left.

Changing the app later: branches and pull requests

Once the app is live, you never change it directly. This keeps your live app safe.

• A branch is a separate copy of the code where you try a change.
• A pull request is a proposal to merge that branch into the main code. GitHub runs the test gate on it: types, style, tests, a full build, and a scan for leaked keys.
• You merge only when the checks are green.

Just tell Shipyard what you want changed. It makes the branch, makes the small change, opens the pull request and waits for the green tick. GitHub cannot block a merge for you on a free private repository, so the rule is yours to keep: never merge while it is red. Shipyard also never saves or pushes without asking.

Already have an app? Upgrade mode

If you built something earlier, in any tool, say so: "Upgrade my app" or run /shipyard:new-app and tell it. Shipyard asks for the project folder and then audits it without changing anything. It reads the code and reports:

• Fix now: keys in the code, data anyone can read, account takeover risks.
• Should fix: missing tests, no checks before merging, no spending caps on AI calls, missing privacy and terms pages.
• Nice to have: smaller polish items.

Each finding comes with a sentence about what could go wrong for your users and the file where it is. Then you pick where to start (it recommends the first "Fix now" item) and it fixes them one at a time, on a branch, with a test where logic is involved, and with your approval each time. For apps built with Next.js and Supabase it copies the starter's approach. For other stacks, such as Flutter or plain HTML, it turns the audit into a checklist and adapts the fixes, and says clearly what it could not automate.

Done when

• You have a live address and Shipyard told you which checks passed and which were skipped.
• You looked at the phone screenshots.
• SPEC.md and HANDOFF.md exist in the app's folder.
• You know that changes go through a branch, a pull request and green checks.

If something goes wrong

• Shipyard says setup is not done. Run /shipyard:setup. It continues from the step that is open.
• Supabase says two projects are already active. That is the free limit, counted across all your organizations. Pause a project you don't use in the Supabase dashboard, or tell Claude to put the app in an existing project (Shipyard's shared mode keeps it in its own space). Then run /shipyard:new-app again.
• Visitors get a 401 error on the live address. Vercel's login wall is on. Ask Shipyard to run the publish step again, or turn off Deployment Protection in the Vercel project settings.
• The checks say sign-up is blocked (a 405 error). A sign-in route is not public. Ask Shipyard to fix it and re-run verify.
• Your usage limit hits in the middle. Wait for it to reset and run /shipyard:new-app again. It offers to continue.
• A free Supabase project is asleep. Free projects pause after a week without use. Wake it with one click in the Supabase dashboard.

See Troubleshooting for more.

Check yourself