> For the complete documentation index, see [llms.txt](https://docs.stoobly.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stoobly.com/getting-started/configuring-an-ai-assistant/skills/stoobly-scaffold-create.md).

# Scaffold Create

````markdown
---
name: stoobly-scaffold-create
description: Bootstraps a new Stoobly scaffold app and services. Use when the user
  wants to get started with Stoobly, create a scaffold app, add services, or run
  their first workflow.
---

# Scaffold Create

You are helping the user bootstrap a Stoobly scaffold application.

## Step 1: Detect existing state

Check if `.stoobly/services/.config.yml` exists in the current directory.

- If it exists, read it and report the user's current config (app name, runtime, proxy mode). Then ask: "You already have a scaffold app. Do you want to add more services, or start fresh?"
- If it does not exist, proceed to Step 2.

## Step 2: Read the docs

Read the local file `.stoobly/docs/faq/scaffold/README.md` to get current command syntax. If it doesn't exist, fetch `https://docs.stoobly.com/faq/scaffold.md` instead.

## Step 3: Ask the user these questions (ask all at once, in a single message)

1. **App name**: What do you want to call this scaffold app? (e.g., `my-app`)
2. **Runtime**: Local (faster, no Docker required) or Docker (recommended for teams and CI/CD)?
3. **Proxy mode**: Forward proxy (your app/tests explicitly use `http://localhost:8080` as a proxy) or Reverse proxy (traffic routed transparently by hostname — better for browser-based apps)?
4. **E2E testing**: Are you setting up E2E tests? If so, which framework — Playwright, Cypress, both, or neither?
5. **Services**: List the backend service(s) you want to mock. For each, provide:
   - A short name (e.g., `api`, `payments-service`)
   - The hostname of the real service (e.g., `api.example.com` or `localhost`)
   - The port (e.g., `3000`, `443`)
   - The scheme (`http` or `https`)

## Step 4: Create scaffold config and apply

Write a declarative scaffold config at **`.stoobly/scaffold.yml`** (create the `.stoobly/` directory if it does not exist). This file is consumed by `stoobly-agent scaffold apply` and maps 1:1 to scaffold CLI commands.

Use this structure:

```yaml
version: 1
commands:
  - resource: app
    action: create
    options:
      app_name: <app-name>
      runtime: <local|docker>
      proxy_mode: <forward|reverse>
      # plugin: [playwright]   # uncomment if E2E framework selected

  - resource: service
    action: create
    options:
      service_name: <service-name>
      hostname: <hostname>
      scheme: <http|https>
      port: <port>

  # Add one service block per service. Repeat as needed.

  # Optional reference — uncomment to create custom workflows later:
  # - resource: workflow
  #   action: create
  #   options:
  #     workflow_name: ci
  #     template: mock
  #     service: [<service-name>]
```

Rules for the YAML file (full reference: `.stoobly/docs/faq/scaffold/apply.md`, or `https://docs.stoobly.com/faq/scaffold/apply.md` if that file doesn't exist):

- Top-level `version` must be the integer `1` (not the string `"1"`).
- `commands` is a non-empty ordered list; the whole config is validated up front, then steps run sequentially and stop on the first failure — steps already applied are not rolled back.
- `resource`/`action` pairs are limited to: `app create`; `service create|list|show|delete|update`; `workflow create|copy|show|up|down|logs|mkcert|rewrite|filter|validate`; `hostname install|uninstall`.
- Option keys use **snake_case** matching the CLI flag (e.g., `app_name`, `proxy_mode`, `service_name`). An unknown option key for the target command is a validation error.
- Flags are booleans (`true` / `false`).
- Multi-value options (e.g., `plugin`, `service`) use YAML lists; a bare scalar is also accepted as one value.
- Omit `app_dir_path` to scaffold in the current working directory (typical single-repo setup).
- Only these keys are path-expanded: `app_dir_path`, `context_dir_path`, `script_path`, `ca_certs_dir_path`, `certs_dir_path`, `docker_socket_path`. Relative values resolve against `.stoobly/` (the config file's directory), not the cwd. Apply never creates directories.
- `--format json` is also supported if the user prefers JSON over YAML.

Show the generated YAML to the user and ask: "Ready to apply this? (yes / let me review first)"

Once confirmed:

1. Write `.stoobly/scaffold.yml` to disk
2. Validate with a dry run: `stoobly-agent scaffold apply .stoobly/scaffold.yml --dry-run` — note this checks the config's schema but does not exercise every check a real apply does (e.g. required directories existing)
3. If dry run succeeds, apply for real: `stoobly-agent scaffold apply .stoobly/scaffold.yml`

After execution, report whether it succeeded or failed. If it fails, stop and show the full error output before asking how to proceed.

Tell the user they can re-run or share this setup anytime with `stoobly-agent scaffold apply .stoobly/scaffold.yml`.

## Step 5: Surface next steps

After all commands succeed, tell the user:

- How to route traffic through the proxy (proxy env vars for forward proxy, or hostname setup for reverse proxy)
- If recording HTTPS, remind them the CA cert was installed (or how to install it manually if skipped)
- Offer to immediately start the record workflow

End with:

> **Next steps:**
> - Now that your Stoobly scaffold is created, you can now run workflows! See [How to Run a Workflow](https://docs.stoobly.com/guides/how-to-integrate-e2e-testing/how-to-run-a-workflow)
> - Or to further customize a workflow, see [Customizing a Workflow](https://docs.stoobly.com/guides/how-to-integrate-e2e-testing/how-to-scaffold-an-app/customizing-a-workflow)
>
> Docs: https://docs.stoobly.com/faq/scaffold
> 
> Runtime comparison: https://docs.stoobly.com/faq/scaffold/runtime
````