Handoff: ship and qualify the Claude Code authoring journey #20

This is the takeover issue for Stream 1: Claude Code installation, conversational Foundation Plan authoring, diagnostic revision, and the product Compile experience.

Outcome

Deliver one narrow, honest user journey:

1. Install the released firstdraft CLI and the Git-hosted Claude Code plugin.
2. Tell Claude Code, “Let’s make an app that helps me inventory my home.”
3. Let the agent interview the user, incrementally maintain one complete Foundation Plan snapshot, and push snapshots whenever useful for diagnostics.
4. Continue the dialogue and revise the Plan until the material first-release choices are resolved, delegated, or explicitly deferred.
5. Use Movie Catalog as the currently executable server fixture: author its complete Plan, repair diagnostics, reach valid whole-graph analysis, and request one well-prepared successful Compile.
6. Receive the resulting private GitHub repository URL.

The boundary up front: the source workflow is substantially implemented and locally rehearsed, but this user journey is not yet proved end to end. The CLI is unpublished; the GitHub-hosted marketplace install has not been exercised; an installed marketplace plugin has not been invoked by a fresh model; and the controlled Movie Catalog rehearsal replaced all real GitHub operations with a strict fake.

Keep Home Inventory as the interview-quality evaluation. Do not make completion depend on compiling it while its requirements exceed the admitted Compiler slice.

Ownership and related issues

This issue owns the user-facing Skill, plugin installation/discovery, interview behavior, evals, CLI-facing workflow, distribution readiness, and preserved evidence. firstdraft/skills is the primary repository.

firstdraft/firstdraft#283 continues to own the overlapping live staging, real GitHub App, private-repository mutation, singleton reconciliation, and release gate. Coordinate the shared live Movie Catalog run there rather than copying or redesigning its service checklist.

Do not implement firstdraft/firstdraft#291, gap-aware partial compilation, here. Compiler breadth remains under firstdraft/firstdraft#189. Render deployment, TestFlight, APNs, test push, and physical-device proof remain outside this stream; firstdraft/firstdraft#66 is the closest existing native/deployment track.

Labeled source snapshot

State checked on 2026-08-05:

• Skills main: 8ffbd9688f39118ddeeb48a3da7e5bc309b7be5e
  • #17, establish the interview evaluation foundation
  • #18, pin the product Compile CLI contract
  • #19, record workflow evaluation evidence
• CLI main: befef8ccfbe2bf6117149441b521c4a23d81f306
  • #16, unify local application identity tools
  • #18, unify Compile and publication
  • #19, distinguish Compilation provenance digests
  • package source is @firstdraft.com/[email protected]; npm still returns E404
• The service support for this stream landed through:
  • #301, Compilation Head digest
  • #303, controlled publication executor seam
  • #305, deterministic Movie Catalog product journey
  • #306, fresh-model rehearsal
  • final stream merge: 7bd5847ee59a3b07701f475bf97c23bd90300683

Service main had already advanced to 956e178162a9082cddb7f60a4fbfd4754e729139 when this issue was written, with other capability work in flight. Treat 7bd5847e as the exact Stream 1 evidence boundary, not as a current base. Fetch and requalify current origin/main before new work.

The retained Claude Code evidence is for 2.1.221. The locally available version at handoff is 2.1.222, so renew the observation rather than silently carrying the old version forward.

Workflow decisions not to reopen accidentally

• Edit .firstdraft/foundation-plan.json incrementally throughout the interview. The agent does not need to wait until every choice is resolved before writing.
• Push whenever useful. Frequent, unchanged, incomplete, or invalid candidates are not policy violations; the CLI/server should return useful results where the transport permits them.
• Each network submission is still one whole candidate snapshot. There is no fragment or patch protocol.
• firstdraft plan compile performs its own exact-byte push and waits for the matching analysis. Invalid JSON, schema diagnostics, semantic diagnostics, analyzer failure, or supersession stop before Publication.
• Invoking plan compile after the user has asked to Compile is the authorization; do not add another confirmation ceremony inside the Skill.
• Aim for one well-prepared successful Compile because the current Project retains one Publication singleton and cannot repoint it to a later Head. This is pragmatic guidance, not a ban on attempts: invalid pre-publication attempts may follow more dialogue, and replay after success or an ambiguous Publication returns the same singleton.
• There is no public plan publish command. Retained compilation status and compilation download are read-only inspection paths.
• There are no users or important compatibility commitments yet. Do not add compatibility shims for removed provisional commands; keep the three repositories on one explicit current contract.

Evidence already established

Read these before changing the workflow:

• Skills README
• current Skill
• candidate interview protocol
• Claude Code install smoke
• fresh Claude Code evaluations
• integrated Movie Catalog rehearsal
• staging publication runbook

What those sources prove:

• An isolated local-directory plugin registration/install smoke preserved the real Claude configuration and installed the expected source-only Skill tree.
• A one-turn Home Inventory run showed that the Skill asks about consequential ambiguity instead of immediately inventing product decisions.
• A fresh Claude Code 2.1.221 Opus/high process, using --plugin-dir and a freshly packed CLI, made two pushes, performed two bounded analysis waits with a wait between diagnostic and repair, reached valid graph version 2, and invoked Compile once.
• The controlled service journey exercised real local Rails, Solid Queue, Compilation, Publication, retained download, provenance, and artifact verification while replacing GitHub authorization and mutations with a strict fake. It materialized 194 files / 543,095 bytes with the expected Rails-and-iPhone navigation and required scalar validations.
• The final focused service surface passed 64 runs / 666 assertions. Full local CI on the code-identical parent passed 2,926 application tests / 198,966 assertions, 15 system tests / 87 assertions, and the generated application proofs. The final merged service commit passed hosted CI in run 30992176132.
• Both staging services were observed live on 7bd5847e and /up returned 200. No live qualification, real GitHub repository mutation, npm publication, or supported plugin release occurred.

Do not overstate that evidence. The model rehearsal exposed a bounded, precomputed repair path; it was not an unaided interview and arbitrary Plan-authoring proof. Model use happened through --plugin-dir, not through the separately installed marketplace plugin. Historical artifact counts and older release pins in the README/evidence must stay clearly labeled as historical rather than current expectations.

Remaining work

1. Renew the installation boundary

Using isolated Claude state and the current native Claude Code:

• run the existing non-recording install smoke;

• review packaging or Claude-version drift before renewing its recorded observation;

• add the real Git-hosted marketplace with:

  CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 claude plugin marketplace add firstdraft/skills
  claude plugin install firstdraft@firstdraft-skills

• prove the installed tree is the intended source-only Skill;

• start a fresh model-backed session without --plugin-dir;

• prove that the session discovers and invokes firstdraft:create-full-stack-app; and

• preserve exact, privacy-safe commands and observations.

A local-directory install and a Git-hosted clone are distinct evidence. Keep the real user’s Claude configuration, plugin caches, credentials, and history outside the test boundary.

2. Complete the Home Inventory interview eval

Extend the current opening-turn evaluation into a bounded multi-turn run that:

• asks only consequential questions in manageable rounds;
• incrementally writes the candidate Plan;
• preserves answers and stable subject identities across turns;
• identifies Entities, Fields, References, access assumptions, native needs, and unresolved material choices;
• reads the current interpretation back to the user;
• distinguishes delegated decisions, explicit deferrals, and blockers; and
• does not distort the product merely to fit today’s narrow Compiler.

Keep this run local when its honest Plan exceeds import or Compiler support. Record the model, exact Skill revision, prompt/answers, resulting non-secret file facts, and limitations.

3. Requalify Movie Catalog on current source

Start with the strict fake-remote path and current origin/main in all three repositories. Use a freshly packed CLI and the installed plugin. The agent should begin from the product request, not from a prewritten repaired Plan, then:

• author one complete current Plan snapshot;
• push whenever it finds diagnostics useful;
• preserve locally authored Project and subject identities correctly;
• wait for the exact accepted graph generation;
• repair at least one real schema or semantic diagnostic;
• avoid inventing fixes for analyzer failure, supersession, or ambiguous transport;
• reach valid whole-graph analysis;
• request one well-prepared successful Compile;
• verify the retained Compilation and local download; and
• independently verify representative Rails and iPhone output.

Reuse the existing deterministic cases for malformed JSON, schema diagnostics, semantic diagnostics, recurring diagnostics, stale bytes, ambiguous outcomes, and premature compilation. Add or change cases only where the new journey exposes a real gap.

4. Coordinate the live run through #283

After the non-mutating gates pass, post the exact candidate revisions and proposed commands on #283. Obtain explicit human authorization immediately before any staging mutation, npm publication, or real private-GitHub creation.

Use Movie Catalog. Exercise the signed-in staging account, GitHub App installation, API-token onboarding, app-owned Render One-Off dispatch, exact-byte Plan/analysis flow, singleton Publication, and final private repository URL. Preserve read-only reconciliation for ambiguous outcomes. Do not automatically retry a possibly successful repository mutation, advance to another name, assume main, force-push, or delete live resources.

Update #283 with the exact outcome and link the dated evidence rather than duplicating the provider details here.

5. Make the release decision explicit

Once the pre-release gates and live journey support the claim, present the human release decision with:

• exact CLI, Skills, and service revisions;
• the intended npm version/dist-tag and trusted-publishing path;
• the ordinary CLI and plugin installation commands;
• the remaining capability limits; and
• the rollback or stop conditions.

Only after approval, publish the CLI and mark ordinary plugin installation supported. Then perform a clean public-install smoke. If another real Compile/private repository would be required, obtain separate authorization or stop the post-release smoke before that mutation.

Update living docs in the same changes. Remove “do not install” language only when the released pair and endpoint actually satisfy it.

Acceptance criteria

• Current Claude Code can add the Git-hosted marketplace and install firstdraft@firstdraft-skills in isolated state.
• A fresh model-backed session discovers and invokes the installed Skill without --plugin-dir.
• The bounded multi-turn Home Inventory eval incrementally authors and reads back an honest candidate without inventing consequential choices.
• A fresh Movie Catalog run authors the Plan from the product request, uses diagnostic feedback, reaches valid current analysis, and completes one successful fake-remote Compile.
• Retained Compilation download and representative Rails/iPhone verification pass on current source.
• The coordinated #283 staging run reaches one real private personal GitHub repository and preserves exact provenance and safe singleton recovery.
• With explicit approval, the CLI is publicly installable at the chosen prerelease tag and ordinary plugin installation is documented and smoke-tested.
• Current and historical evidence are clearly separated; exact revisions, model, commands, fixture, result, and limitations are retained.
• No credentials, private CLI state, model transcript, raw Plan bytes, or raw artifact bytes enter Git, logs, issue comments, or reports.
• All affected repository checks and hosted CI pass.

Working rules

• Fetch and verify origin/main before branching.
• Use one dedicated codex/... worktree per repository and a separate sibling worktree for every editing subagent.
• Because this changes an existing Skill, invoke and follow $skill-creator before editing.
• One lead integrates SKILL.md; do not let multiple branches rewrite it independently.
• Work in small logical PRs. Run local Claude Review at high effort, address or explicitly reject findings, request re-review, then wait for hosted feedback and CI.
• Check comments on older stacked PRs as later work evolves. If later evidence supersedes an earlier statement, leave a clear superseding comment.
• If a genuine CLI or service defect appears, reproduce it with a contract test in a separate worktree. Do not hide it in Skill wording.
• Before release, run at least:
  • CLI: npm ci && npm run check, including installed-tarball behavior;
  • Skills: all repository checks, the exact external CLI contract, strict plugin validation, npm run check:claude-plugin-install, and gh skill publish --dry-run;
  • Service: proportional focused tests and the complete configured CI for any affected source.
• Keep evidence claims at their observed boundary.

Suggested parallel takeover slices:

1. Git-hosted plugin installation, isolation, and current-Claude evidence.
2. Multi-turn Home Inventory eval and deterministic harness support.
3. Current-source Movie Catalog black-box rehearsal.

The lead owns the Skill integration, cross-repository contract, release decision, and #283 coordination.