Sails New App

---
name: sails-new-app-fae0fed4413a
description: Use when a builder is starting a new standard Gear/Vara Sails app and needs the correct greenfield sequence before implementation. Do not use for edits to an established repo, Vara.eth or ethexe targets, or non-Sails templates.
---

# Sails New App

## Goal

Move a greenfield request from scope to an approved Sails workspace path without skipping the planning artifacts that later implementation depends on.

## Sequence

1. If the machine does not already have `rustup`, the required Wasm targets, `cargo-sails`, and a local `gear` binary, start with `../sails-dev-env/SKILL.md`.
2. For a new standard Sails/Vara project, bootstrap the workspace first with `cargo sails new <project-name>` unless the user explicitly needs a custom non-template layout.
3. Write the feature or app goal to `docs/plans/YYYY-MM-DD-<topic>-spec.md` using `../../assets/spec-template.md`.
4. Route architecture decisions through `../sails-architecture/SKILL.md`.
5. Keep the standard template workspace shape created by `cargo sails new <project-name>` intact: `app`, `client`, `src`, `tests`, top-level `build.rs`, Wasm output, and generated-client path.
6. Keep the standard build-script pipeline intact. In a standard Sails workspace, use the repo-generated build path for `.idl` and Rust client artifacts. For a dedicated client crate, prefer `sails-rs` with `features = ["build"]` and `sails_rs::build_client::<Program>()` before introducing manual `sails-idl-gen` / `sails-client-gen-v2` wiring.
7. Validate before moving to later phases by finishing with `../sails-gtest/SKILL.md`, then `../sails-local-smoke/SKILL.md`.
8. When the builder needs a frontend, use `create-vara-app` to scaffold it from the program's `.idl`: `npx create-vara-app <name> --idl path/to/service.idl`. Then route to `../sails-frontend/SKILL.md` for customization.

## Shared Inputs

- `../../references/vara-domain-overview.md`
- `../../references/sails-cheatsheet.md`
- `../../references/sails-program-and-service-architecture.md`
- `../../references/sails-idl-client-pipeline.md`
- `../../references/sails-idl-v2-syntax.md` — IDL v2 annotations, `!@include`, service-scoped types

## Guardrails

- Keep the builder on standard Sails scaffolding and generated clients.
- Keep the standard Sails workspace shape and build-generated `.idl` and `.opt.wasm` artifact path intact, and check the crate's `build.rs` before adding ad hoc generation steps.
- Do not jump into raw Gear primitives when a Sails path already exists.
- Do not skip the planning docs just because the repo is greenfield.
- Always use `cargo sails new <project-name>` for greenfield Sails/Vara work. Hand-assembled workspaces are a known source of errors: shared top-level workspaces cause Cargo feature unification to enable both `gstd` and `gtest` on `sails-rs` simultaneously, breaking the build. See `../../references/sails-rs-imports.md` for the canonical layout.
- Use `#[sails_type]` for all custom types (structs, enums) used in service interfaces. This replaces the verbose `#[derive(Encode, Decode, TypeInfo)] #[codec(crate = ...)]` pattern from 0.x.