First Draft Skills

This repository packages the portable agent instructions that turn a product conversation into a reviewed Foundation Plan and drive the First Draft authoring workflow. The canonical Skills and bundled CLI are packaged once for Claude Code and Codex. UI continuation follows the generated app's own design and components. The public catalog and Drawing Board pins determine what an installed workspace actually receives.

Release compatibility names the CLI, Service API, and Foundation Plan format that this source requires. The public catalog owns the installed version; source compatibility does not establish publication. New remote work uses production at https://firstdraft.com; staging is explicit with firstdraft --staging ... and a separate staging token. The workflow preserves the planning workspace under .firstdraft/design/ and defaults to current-folder local output. Use explicit --github for server Publication. Only create-full-stack-app is packaged; the UI Skill auditions remain deferred source.

Trying First Draft as a tester? Start with the local development guide. Start in an empty local folder; a Drawing Board clone and GitHub push are unnecessary. The Drawing Board guide is the Codespaces fallback.

What this repository owns

• the portable create-full-stack-app Skill and its task routing;
• deferred UI extension and consistency-review Skill auditions;
• beginner-to-machine-reference authoring guidance for Foundation Plan 0.23;
• the exact schema, examples, and review checklists packaged with the Skill;
• behavioral evaluations for agent workflow changes;
• shared Claude/Codex plugin assembly around the canonical Skills and reviewed CLI package; and
• release compatibility checks and release runbooks.

The Service owns Foundation Plan semantics and Compilation behavior. The CLI owns transport and terminal command behavior. This repository teaches an agent how to use those contracts without creating a second product definition.

Start with the right document

Task	Read first
Change the Skill or repository	Agent instructions
Understand the installed workflow	Skill entrypoint
Continue or review an app's UI	The app's UI.md and shared components; UI Skill status
Review improvements for an existing app or workflow	First Draft changelog
Change Plan authoring guidance	Skill entrypoint, then modeling guide
Check current Foundation Plan capability	Foundation Plan reference
Inspect exact Plan structure	Bundled schema
Add or run behavioral evaluations	Evaluation guide
Prepare or publish a release	Release runbook
Commit, review, or land a change	Contributing guide

Using Codex

The catalog manifest selects the shared plugin, which includes the compatible CLI and discovers it in either agent. Drawing Board supplies its own project wrapper and installed CLI. A fresh authenticated student Codespace journey remains unproved.

Start in a local folder. Codex uses the same catalog as Claude. Install it with:

codex plugin marketplace add firstdraft/skills
codex plugin add firstdraft@firstdraft-skills

Start a new Codex conversation after installation. Use $firstdraft:create-full-stack-app, or select it from /skills. Node.js 22 or newer and npm must be available. The package includes the compatible First Draft CLI; there is no separate CLI version to choose.

A plugin install does not sign you into First Draft. Log in once per environment from any terminal with npx --yes @firstdraft.com/cli@0.8.1 login (add --staging for staging). The login is saved in your user configuration directory, so Claude Code, Codex CLI, and desktop sessions all use it without exported variables. If authentication interrupts an already requested operation, log in and tell the same conversation to continue. Approve the specific CLI command when Codex requests network access; its tool permission is separate from approval of the Plan and Compile mode.

For the Codespaces fallback, Drawing Board already has the Skill and CLI installed. Follow the workspace sign-in and start instructions. Describe your app normally, or select firstdraft:create-full-stack-app from /skills. To return to the same conversation, run codex resume from the same workspace root.

Repository layout

Path	Responsibility
skills/create-full-stack-app/	Canonical portable Skill and packaged references
skills/extend-app-ui/, skills/review-ui-consistency/	Deferred UI Skill sources, excluded from the package
.claude-plugin/, packages/	Release-gated public catalog selection and plugin assembly, not a second editable Skill copy
evals/	Behavioral cases and evaluator contracts
script/	Repository, package, and release compatibility checks
docs/	Dist-tag repair runbook for published packages

Packing copies the selected canonical Skill from the explicit package inventory and adds the reviewed CLI package. Deferred Skill sources remain in this repository. Keep editable truth under skills/; do not maintain parallel prose under a package directory. The packer derives portable plugin.json and the .codex-plugin/plugin.json compatibility overlay from the same release metadata as the Claude manifest. Both clients use .claude-plugin/marketplace.json, which Codex supports directly. The existing npm package name is retained so release versions and catalog selection cannot drift between clients. Package checks compare every installed Skill file with its canonical bytes. The portable layout discovers skills/ by convention; the Codex overlay supplies display metadata, not additional tool permissions.

UI continuation

Use the generated app's UI.md, comparable screens, and shared components for source development. The new Rails UI uses ERB/Basecoat Vega and selected shadcn base-vega islands through Turbo Mount. The app owns its theme, partial contracts, and component update commands. Existing apps keep their own stack unless migration is requested.

The retained extension and consistency-review auditions are excluded from both candidate distribution manifests and the package. Their selection and qualification will be decided separately after the infrastructure release. Their existing source is not current plugin-install guidance.

Upstream shadcn guidance and its MCP can help discover React components. They are optional development aids, not bundled Skills, required sign-ins, or dependencies of Compilation, builds, or CI. A registry page example does not change the Rails ownership of an existing screen.

Development

Use Node.js 22 or newer and a Git checkout. Checks inspect the repository index and complete Skill tree.

npm ci --ignore-scripts
sh script/check

The check covers repository structure, documentation links and currency, each Skill's packaging boundary, the Plan schema and fixtures, the eval corpus, deterministic packaging with a stub CLI, and release compatibility.

CI checks consumer commands against the exact pinned CLI and verifies the candidate package digest. CLI-owned tests cover the complete Publication protocol matrix; Skills retains representative recovery cases, compatible fixtures, and packaged-executable integration. The release runbook owns the commands for reproducing these checks.

Preview the plugin directly from a checkout:

claude --plugin-dir .

To test a standalone Codex candidate with its bundled CLI:

node script/claude-plugin-package.mjs stage tmp/firstdraft --cli-root /path/to/exact/cli
node script/check-codex-plugin-install.mjs --codex /absolute/path/to/codex --plugin-root tmp/firstdraft
node script/check-packaged-claude-plugin-install.mjs --claude /absolute/path/to/claude --plugin-root tmp/firstdraft

These install checks use temporary client state, discover every Skill through the real client, compare all Skill files with the candidate, and exercise the bundled CLI without a global firstdraft. They need no agent login or First Draft service. Behavioral cases remain shared across clients; the eval guide describes the separate agent-session checks.

If the installed GitHub CLI supports Skill preview:

gh skill preview firstdraft/skills create-full-stack-app

Source validation does not publish a package, move a dist-tag, select a catalog version, or deploy the Service. Those actions follow the machine-owned compatibility record and RELEASING.md, which names the service repository's release coordination.

Credential boundary

The user logs in once per environment with firstdraft login, or firstdraft --staging login for https://staging.firstdraft.com. A workspace may instead supply FIRSTDRAFT_API_TOKEN for production or FIRSTDRAFT_STAGING_API_TOKEN for staging; a set variable takes precedence over a saved login. The CLI never uses one environment's credential for another. Existing Plans keep their saved origin. FIRSTDRAFT_API_URL is an advanced custom-server override; a conflicting URL cannot be combined with --staging or redirect an existing Project. The shared helper prefers the project's bin/firstdraft credential wrapper, then the bundled CLI, then an installed CLI on PATH. It preserves the working directory and arguments. The adapter forwards ambient credentials; it does not read ignored credential files. The bundled CLI reads its own saved login, and only the user runs login or logout. Claude Code does not deliver plugin userConfig to bin/ executables; a secure bridge is tracked in issue #27. Never put a token in agent conversation, command-line arguments, checked-in files, examples, evaluations, or evidence. The executable adapter may read the environment, but ordinary Skill reference text must not receive or reproduce secret values.