Use First Draft as one tool for the user's app

[raghubetina]

Why

On 2026-10-04 the owner decided: "First Draft is a tool in the agent's belt. It should use it in whatever way helps achieve the user's goals: whether to only plan, plan and emit, or neither." The Skill assumed every request was an app First Draft could build, and it said what First Draft could not build only after the first push. An idea whose core is real-time sensors or a game loop got an interview for records it did not need.

Decisions as implemented

1. Start from the user's goal. The frontmatter description now reads: "Use when someone asks for help making or planning an app or game, even one First Draft may not fit. Experimental: researches whether the idea is possible and how similar things are built, then uses First Draft where it helps: Foundation Plans, analysis, and bounded Rails/iPhone/Android Compile for records, people, permissions, lists, and forms. Says early when First Draft won't cover the core, and what will." It is 411 characters, with the trigger first. The limits: this repository's test and the Agent Skills spec cap it at 1,024 characters. Claude Code truncates description plus when_to_use at 1,536 characters in its listing. Codex shortens descriptions when many Skills are installed and advises putting the trigger words first. The description test now checks the new fragments.

2. Research before building, always. The new section references/interview.md#start-from-the-users-goal follows the owner's follow-up decision. Before every interview, the agent takes a quick look of a few searches at how others build similar apps (common features, patterns, pitfalls) and uses it to pick better questions and defaults. It researches thoroughly only when feasibility is in question: device capabilities, outside data or APIs, store rules, or real-time behavior. In that case it opens the first turn with a few sourced lines. For a fitting app it still says nothing about fit, but may mention one or two findings. The tool-library and home-inventory opening cases now forbid only a First Draft service request, not any network request.

3. Say how First Draft helps, as soon as it's clear. There are four outcomes:

   • plan and Compile, with no fit talk;
   • the backbone, where the agent names native Swift or Kotlin in the generated projects and says those are Hotwire Native shells showing only public pages with no sign-in;
   • plan only, which pushes and uses the analysis but never Compiles;
   • not at all, which names a game engine, mentions accounts, leaderboards, or a website later, and creates or pushes no Plan.

   After that, the 0.8.3 interview runs unchanged for the First Draft part.

4. Three lists. implementation-notes.md keeps ## What First Draft builds, ## What is built otherwise, ## Feasibility findings and open questions, then ## After Compile. The modeling guide's read-back now has five items: what First Draft builds (the plain summary), what is not generated yet, what is built otherwise, feasibility findings and open questions, and the technical block. The evaluator protocol matches.

5. Safety: I added no rule. In both race-car runs the agent decided on its own that advice must be spoken, and that the app is for closed tracks.

Placement and SKILL.md bytes

SKILL.md is 20,313 bytes, down from 20,332 on main (−19). That stays under the 20,480 cap. The body adds one routing sentence in "Interview and author incrementally" and a reframed two-line intro. To pay for them I tightened three paragraphs without changing their meaning: the JSON Schema paragraph, the read-back order sentence, and the download description. Detail lives in references/interview.md and references/modeling-guide.md. No new reference file was added, so the packaging inventory is unchanged.

Rehearsals

Each run used a fresh session: claude -p --setting-sources local --plugin-dir <this worktree>, with only this plugin loaded and no user CLAUDE.md. The Claude Code version was 2.1.286 and the model claude-opus-5-5. I played the user minimally.

• Race-car coaching ("Help me build an app for hobbyist race car drivers…"), run twice from the opening turn.
  • Research: three web searches before replying. Sources it cited included Grassroots Motorsports, ClioSport, and Classic Motorsports forums, App Store pages for Lapper, G-Box, VRacer, and VBOX Laptimer, Garmin Catalyst 2 product and review pages, and an Apple Developer Forums thread.
  • Findings: phone GPS updates about 1 Hz, while serious apps use 10–25 Hz Bluetooth receivers. Garmin Catalyst is the coaching benchmark. RaceChrono, Harry's LapTimer, and TrackAddict do predictive timing.
  • Disclosure: in the opening turn, both runs said First Draft builds the backbone (accounts, cars, tracks, sessions, laps) and not the real-time sensor advice, which needs native Swift or Kotlin. They also said the generated phone apps show only public pages and have no sign-in. The opening questions followed, including the level question.
  • After the answers ("me and a few friends; live advice and lap review; nothing to share; make the technical decisions"), it ran plan init and pushed a backbone Plan to Production: Project 01a1096c-f01a-77e0-a77d-50e235af2809, graph version 2, Plan SHA-256 746c8d4c…. The first push got a 422 schema error (icon names, a missing Association authorization), which it fixed. It pushed once more to add a driver.sessions inverse.
  • Analysis: valid, GapSet 6495a813… with 2 gaps, both foundation_plan.gap.native_client.not_generated (iOS and Android). Every page is signed-in, so there is no public index. There were 15 public_scaffold warnings on Policy-protected pages, and the Account generated without a gap.
  • Reality check and notes: it said plainly that the coaching itself is not generated and that no phone app would be generated while every page is private. It then asked one decision: a public track list so the phone projects generate, the private web app only, or everything public. Its recommendation was a public track list. The modeling guide says not to recommend public indexes only to satisfy native prerequisites, so this is a question for you. Here the generated phone project is where the coaching code goes. implementation-notes.md had the three lists. Its feasibility list named sources without links, so the guide now asks for source links. I stopped before Compile.
• First-person shooter. With the first description, which said only "an app", the Skill did not trigger, and the agent started building a game itself. After adding "app or game, even one First Draft may not fit", it triggered. It said First Draft isn't the right tool, compared Godot, Unity, Unreal, and Three.js, and mentioned First Draft later for accounts, leaderboards, or a website. No .firstdraft/ was created and no Plan was pushed. It did not search the web, since engine choice is well known.
• Family network (the 0.8.3 workshop prompt), run three times.
  • Run 1 opened with "fits this tool well", so the full-fit bullet now says not to mention fit at all.
  • Run 2 had no fit talk and no research.
  • Run 3, after the research-always change, made two searches: private family photo apps (FamilyAlbum, Tinybeans) and Instagram clones in Rails. It then said what it found, with links to FamilyAlbum, Tinybeans, and The Odin Project: the key rule is that only invited people see, like, or comment, and "follow" adds little when one family sees everything. After that it proposed "FamilyGram" and asked about who uses it, materials, and the level question. There was no fit statement and no push. It also said that photo uploads may need adding after the first build.
• Controls: the Rails-maintenance and CSV-analysis prompts did not trigger the Skill with the new description.

Evals

There are five new structural cases:

• fit-partial-opening-race-coaching and fit-partial-backbone-plan-race-coaching: the owner's case (a), split so the opening turn and the backbone push can each be graded from one prompt.
• fit-none-first-person-shooter
• fit-full-family-photo-network
• fit-plan-only-other-stack

The two should_trigger: false controls are unchanged.

CI

Local sh script/check (stub CLI) passes 85/85. With the pinned CLI checkout, the only failure is plugin tarball must match its release compatibility digest; check-cli-contract passes. The version, CHANGELOG version label, and plugin_source.tarball_sha256 are deliberately left to the 0.8.4 release PR. So hosted CI is expected to fail on that one digest assertion until this is rebased onto the 0.8.4 release branch plugin-0-8-4. That rebase will happen when the branch exists.

Proposed CHANGELOG bullet

This text is also in CHANGELOG.md under an undated "Pending for 0.8.4" heading. The checks accept that heading, and the 0.8.4 entry should absorb it:

• The Skill treats First Draft as one tool for your app instead of assuming it can build whatever you describe. When your idea depends on more than records, people, and permissions, such as phone sensors, outside data, store rules, or real-time computation, the agent first searches the web for whether it is possible and how others build similar apps, and tells you what it found with sources. As soon as it is clear, it says how First Draft helps: plan and Compile the whole app; plan and Compile the backbone, such as accounts, sessions, and lists, while the core, such as real-time sensor advice, is built separately in native Swift or Kotlin; plan only, when you will build in another stack; or not at all, as for a first-person shooter, where it names a game engine and offers First Draft later for accounts, leaderboards, or a website. An app of records and people, such as a family photo feed, starts the interview as before. implementation-notes.md and the read-back keep three lists: what First Draft builds, what is built otherwise, and feasibility findings and open questions. The Skill's description now starts from your goal, so it triggers when you ask for help making or planning an app or game.

Docs: updated SKILL.md, references/interview.md, references/modeling-guide.md, the evaluator interview protocol, and CHANGELOG.md (Pending for 0.8.4)

[raghubetina]

Superseded: shipped in plugin 0.8.4 through #125 (claude-v0.8.4, skills 450ea99), now npm latest and selected in the catalog.