Skip to content

feat(cli): onboard agents into the build-first workflow (init + agent docs)#3098

Merged
josephfarina merged 1 commit into
mainfrom
feat/cli-build-first-docs
Jun 25, 2026
Merged

feat(cli): onboard agents into the build-first workflow (init + agent docs)#3098
josephfarina merged 1 commit into
mainfrom
feat/cli-build-first-docs

Conversation

@josephfarina

@josephfarina josephfarina commented Jun 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🎯 Why this exists

Part of a broader push to make Astryx the easiest design system for AI agents to build real UIs with — one-shot, no escape hatches, no broken renders. We're vibe-testing the full agent journey (install → init → discover → compose → build → typecheck → render) and fixing every friction point it surfaces, so an agent given a one-line prompt lands a correct, fully-styled, type-safe page using only design-system components.

Summary

  • Generated CLAUDE.md is now build-first: the workflow leads with astryx build, and search is reframed as a neutral universal find.
  • Adds a required-CSS setup note to the agent docs (reset.css + astryx.css) so components never render unstyled. Theme is noted as optional.
  • init output restructured to point at astryx build / astryx search instead of dumping page-template names.

Why

Round-3 vibe tests showed agents adopt build 10/10 when the docs lead with it. Two unstyled renders were caused purely by agents forgetting the CSS imports — the setup note targets that directly.

Stacked on #3097 (build command + ranking). Review/merge that first.

Test plan

  • npx astryx init --all prints the build/search pointer (no template dump) + the SETUP block
  • generated CLAUDE.md step 1 is astryx build "..."
  • npx vitest run packages/cli/src/commands/agent-docs.test.mjs

Made with Cursor

@vercel

vercel Bot commented Jun 24, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated (UTC)
astryx Ignored Ignored Jun 25, 2026 6:50pm

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Jun 24, 2026
josephfarina
josephfarina commented Jun 24, 2026
View reviewed changes
Comment thread packages/cli/src/commands/agent-docs.mjs
Comment on lines +126 to +127
lines.push(' import "@astryxdesign/core/reset.css";');
lines.push(' import "@astryxdesign/core/astryx.css";');

@josephfarina josephfarina Jun 24, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a big failing point where an agent forgets to add the required css. Adding instructions in the init output seem to solve it.

@cixzhang cixzhang Jun 25, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it better to put it in agent docs or have it link a getting started doc?

@josephfarina josephfarina force-pushed the feat/cli-build-command branch from f1855d3 to b5357a2 Compare June 24, 2026 23:41
@josephfarina josephfarina force-pushed the feat/cli-build-first-docs branch from d991e3f to a552c28 Compare June 24, 2026 23:41
@josephfarina josephfarina changed the title feat(cli): build-first agent docs + restructured init output feat(cli): onboard agents into the build-first workflow (init + agent docs) Jun 25, 2026
cixzhang
cixzhang approved these changes Jun 25, 2026
View reviewed changes

@cixzhang cixzhang left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agent docs are getting a bit long. Maybe we can run it through some optimizer.

@josephfarina josephfarina deleted the branch main June 25, 2026 18:47
@josephfarina josephfarina reopened this Jun 25, 2026
@josephfarina josephfarina changed the base branch from feat/cli-build-command to main June 25, 2026 18:49
@josephfarina @cursoragent
feat(cli): build-first agent docs + restructured init output
20eefba 
Generated CLAUDE.md now leads with the `build` workflow and a required-CSS
setup note (reset.css + astryx.css) to prevent unstyled renders; `search` is
reframed as a neutral universal find. `init` points at `astryx build`/`search`
instead of dumping template names.

Co-authored-by: Cursor <cursoragent@cursor.com>
@josephfarina josephfarina force-pushed the feat/cli-build-first-docs branch from a552c28 to 20eefba Compare June 25, 2026 18:50
@josephfarina josephfarina enabled auto-merge (squash) June 25, 2026 18:52
@github-actions

github-actions Bot commented Jun 25, 2026

Copy link
Copy Markdown
Contributor

🚀 Vercel Preview Deployment
Status ✅ Deployed
Preview Open Preview
Commit 20eefba
Inspect Vercel Dashboard
Workflow View Logs

No authentication required — anyone with the link can view the preview.

@josephfarina josephfarina merged commit f891eff into main Jun 25, 2026
15 checks passed
@github-actions

github-actions Bot commented Jun 25, 2026

Copy link
Copy Markdown
Contributor

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

🧪 Sandbox Preview

View Sandbox for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

No new or modified components detected.

Bundle Size Summary

Package Size (ESM) Size (CJS) Gzipped
@astryxdesign/core N/A 4.6KB 0B

Accessibility Audit

Status: No accessibility violations detected.

Generated by PR Enrichment workflow | Storybook | Sandbox | View full report

github-actions Bot added a commit that referenced this pull request Jun 25, 2026
@github-actions
Deploy PR #3098 preview
f5e6c69
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@cixzhang cixzhang cixzhang approved these changes
@imdreamrunner imdreamrunner Awaiting requested review from imdreamrunner imdreamrunner is a code owner
@ejhammond ejhammond Awaiting requested review from ejhammond ejhammond is a code owner
@nynexman4464 nynexman4464 Awaiting requested review from nynexman4464 nynexman4464 is a code owner
@marie-lucas marie-lucas Awaiting requested review from marie-lucas marie-lucas is a code owner
@thedjpetersen thedjpetersen Awaiting requested review from thedjpetersen thedjpetersen is a code owner

Assignees

No one assigned

Labels

CLA Signed This label is managed by the Meta Open Source bot.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@josephfarina @cixzhang