mapples 0.2.0-beta.8 → 0.2.0-beta.9

package/templates/agent/mapples.md

@@ -111,8 +111,14 @@ or editing the file and syncing pushes the tokens to Creator (missing file + emp
 
 ## The agent lease
 
-While `__DESIGN_COMMAND__` runs, `npx -y mapples@__CLI_VERSION__ agent start` holds a lease on the project so Creator shows
-"__AGENT_LABEL__ is working" and locks its own chat. `npx -y mapples@__CLI_VERSION__ agent step` reports progress;
+Creator shows "__AGENT_LABEL__ is working" and locks its own chat while you hold the project's
+lease. You do not manage it for ordinary requests: this app's hooks take the lease as soon as
+the user sends a prompt and release it when you finish responding, even when you change
+nothing. Do not call `agent start` or `agent stop` yourself for a normal request.
+
+The first thing `__DESIGN_COMMAND__` does — before syncing or asking the user anything — is
+`npx -y mapples@__CLI_VERSION__ agent start`, which holds a lease on the project so Creator shows
+"__AGENT_LABEL__ is working" and locks its own chat for the whole run, questions included. `npx -y mapples@__CLI_VERSION__ agent step` reports progress;
 `npx -y mapples@__CLI_VERSION__ agent stop` releases. `.mapples/agent.json` exists while the lease is held and labels
 every sync commit "__AGENT_LABEL__: <step>". Exit codes: `3` = the lease is gone (Creator
 disconnected you or it expired — stop and tell the user), `4` = another agent holds the project.

package/templates/agent/skills/mapples-design/SKILL.md

@@ -10,8 +10,41 @@ You are the product designer and builder for this app. Your bar is a finished sc
 designer would ship — not a wireframe. Everything you make is a file in this repo; every phase
 ends with `npx -y mapples@__CLI_VERSION__ sync --yes --json`, which pushes it to Creator where the user watches it land.
 
-Read `__CONVENTIONS_PATH__` and the `mapples-conventions` and `mapples-sync` skills before the
-first file. Reference material for this skill lives next to it:
+## First: take the project's lease
+
+Do this **before anything else** — before reading references, syncing, or asking the user a
+single question. While you hold the lease Creator locks its own AI chat and refuses Save, so
+nobody changes the project from the browser while you are still asking about the brief.
+
+1. `.mapples/config.json` must exist (the app is linked). If not: stop and ask the user to run
+   `npx -y mapples@__CLI_VERSION__ init --secret <key> --agent __AGENT_FLAG__` — never run it yourself.
+2. Take the lease, pre-declaring the fixed step titles:
+
+   ```bash
+   npx -y mapples@__CLI_VERSION__ agent start --agent __AGENT_ID__ --label "__AGENT_LABEL__" --steps "Brief,Style guides,Design tokens,Plan,Scaffold navigation & screens" --json
+   ```
+
+   Exit 4 = busy: another agent session holds the project. That is the only question you may
+   ask before holding the lease — whether to take over (re-run with `--takeover`, which
+   disconnects the other session). Never take over silently; if the user says no, stop.
+3. Mark the brief running at once — the brief questions happen inside this step:
+
+   ```bash
+   npx -y mapples@__CLI_VERSION__ agent step --index 0 --title "Brief" --status running --json
+   ```
+
+Only then:
+
+4. Read `__CONVENTIONS_PATH__` and the `mapples-conventions` and `mapples-sync` skills.
+5. `npx -y mapples@__CLI_VERSION__ sync --yes --json` — be current before designing. Exit 2 here means the repo
+   already had conflicts: resolve them (see `mapples-sync`) before going on.
+6. Read `mapples/design.md` if it exists: a previous run's brief, chosen style and plan. Resume
+   from the first phase whose output is missing rather than redoing everything.
+
+If the user stops the run at any point — including while you are still asking questions —
+release the lease before you reply (`agent stop --status failed --error "stopped by the user"`).
+
+Reference material for this skill lives next to it:
 
 - `reference/style-guides.md` — art directions and style guides (phase 1)
 - `reference/design-tokens.md` — the `mapples/theme.ts` contract and template (phase 2)
@@ -21,37 +54,19 @@ first file. Reference material for this skill lives next to it:
 - `reference/lint-checklist.md` — the review pass (phase N)
 - `reference/playbooks/<name>.md` — screen-kind playbooks, loaded per screen
 
-## Preconditions
-
-1. `.mapples/config.json` must exist (the app is linked). If not: stop and ask the user to run
-   `npx -y mapples@__CLI_VERSION__ init --secret <key> --agent __AGENT_FLAG__` — never run it yourself.
-2. `npx -y mapples@__CLI_VERSION__ agent status --json`. If `session` is non-null with `status: "active"` and
-   `holdsLease` is false, another agent is working on this project: stop and ask whether to take
-   over (`--takeover` disconnects it). Never take over silently.
-3. `npx -y mapples@__CLI_VERSION__ sync --yes --json` — be current before designing. Exit 2 here means the repo already
-   had conflicts: resolve them (see `mapples-sync`) before going on.
-4. Read `mapples/design.md` if it exists: a previous run's brief, chosen style and plan. Resume
-   from the first phase whose output is missing rather than redoing everything.
-
 ## Steps and the lease
 
-The run is one agent session. Steps have a **fixed index convention** shared with Creator's
-progress log:
+The lease taken above covers the whole run. Steps have a **fixed index convention** shared
+with Creator's progress log:
 
 ```
 0 Brief · 1 Style guides · 2 Design tokens · 3 Plan · 4 Scaffold navigation & screens ·
 5…N-2 one per plan step ("Build the Home screen", …) · N-1 Wiring · N Review
 ```
 
-Start the session as soon as the brief and scope are known, pre-declaring every step title:
-
-```bash
-npx -y mapples@__CLI_VERSION__ agent start --agent __AGENT_ID__ --label "__AGENT_LABEL__" --steps "Brief,Style guides,Design tokens,Plan,Scaffold navigation & screens" --json
-```
-
-Exit 4 = busy (see precondition 2). After the plan exists (phase 3), the remaining titles are
-declared as they run: `npx -y mapples@__CLI_VERSION__ agent step --index 5 --title "Build the Home screen" --status running`
-creates the step. Wrap **every** phase:
+After the plan exists (phase 3), the remaining titles are declared as they run:
+`npx -y mapples@__CLI_VERSION__ agent step --index 5 --title "Build the Home screen" --status running` creates the step.
+Wrap **every** phase:
 
 ```bash
 npx -y mapples@__CLI_VERSION__ agent step --index <i> --title "<title>" --status running --json
@@ -73,6 +88,8 @@ A phase's syncs are labelled with the running step in Creator's history automati
 
 ## Phase 0 — Brief and scope
 
+Step 0 is already running (you marked it right after taking the lease).
+
 Input: `$ARGUMENTS` (the brief, optionally `--scope single|minimal|basic|advanced`). If the
 brief is missing or too thin to name the audience, the core value and the mood, ask **one**
 round of questions (with your multiple-choice question tool, when you have one) — audience, the one thing the app must do well, the