Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): the global skill gives a concrete build workflow (#7893)

Joeybe423330bc38
diff --git a/.changeset/cli-skill-build-workflow.md b/.changeset/cli-skill-build-workflow.md
new file mode 100644
index 0000000000..4ecf5d42ef
--- /dev/null
+++ b/.changeset/cli-skill-build-workflow.md
@@ -0,0 +1,8 @@
+---
+'@astryxdesign/cli': patch
+'@astryxdesign/core': patch
+---
+
+[fix] The agent guide that global mode writes to the home folder now says how to build, not only how to find things. It tells agents to work in a project folder (creating one if there is none) with `@astryxdesign/core` and `@astryxdesign/cli` added to a new project or one without Core, or, in a project that already has `@astryxdesign/core`, the CLI at the same version, and `astryx init` run there, then gives the same template-first workflow and self-check the project agent docs give, and ends with building the project and delivering that build. Before, agents that found the right template could still build the page with a tool that cannot install packages and deliver a page with no Astryx in it. The guide stays version-free and names only commands every release keeps. The project agent docs are unchanged, and so is what `@astryxdesign/core`'s install script prints: its copy of the shared agent-docs file only gains the same workflow lines.
+
+@josephfarina
diff --git a/docs/specs/AST-081-global-mode/spec.md b/docs/specs/AST-081-global-mode/spec.md
index 0234b29ab3..ba45187f7b 100644
--- a/docs/specs/AST-081-global-mode/spec.md
+++ b/docs/specs/AST-081-global-mode/spec.md
@@ -403,6 +403,11 @@ works on is `spec:AST-040` FR9's.
start with `astryx search`; it names no version, no release-specific
command or prop, and only entry points every release keeps (`search`,
`docs`, `component`, and the like), so an older copy never misleads.
+ It also gives the build route the project agent docs give, through their
+ shared workflow wording: work in a project folder, new or existing, adding
+ `@astryxdesign/core` and `@astryxdesign/cli`, or, where the project already
+ installs Core, the CLI at that Core's version; run `astryx init` there; then
+ start from a template, check, and deliver the built project.
- The computer-level text is one file, `.agents/skills/astryx/SKILL.md` in
the home folder, which most agent tools read. The computer-level agent
files table below names each other folder it reaches: a folder link to its
diff --git a/packages/cli/foundation/agent-docs/agent-doc-state.mjs b/packages/cli/foundation/agent-docs/agent-doc-state.mjs
index d9b6d38b80..9b02eced3a 100644
--- a/packages/cli/foundation/agent-docs/agent-doc-state.mjs
+++ b/packages/cli/foundation/agent-docs/agent-doc-state.mjs
@@ -34,6 +34,26 @@ export const CURSOR_RULES = '.cursorrules';
export const HERMES_DOT_MD = '.hermes.md';
export const HERMES_MD = 'HERMES.md';
+/**
+ * The page workflow every Astryx agent text gives, written with the command
+ * name `astryx`: the project agent docs and the computer-level skill both
+ * render these lines, so the two never drift.
+ */
+export const WORKFLOW_TITLE =
+ 'WORKFLOW — start every page from a template, never from scratch:';
+export const WORKFLOW_STEPS = Object.freeze([
+ '1. `astryx build "<idea>"` — names the template to scaffold from and the parts it lacks.',
+ '2. `astryx template <name> <path>` — scaffold it; keep its frame, gap and padding; replace the content.',
+ '3. `astryx template <Block>` for parts it lacks; `astryx component <Name>` to read props before using one.',
+]);
+
+/**
+ * The self-check's fix for a project with no StyleX or Tailwind compiler,
+ * and for an agent outside a project.
+ */
+export const SELF_CHECK_CSS =
+ 'replace any raw <div>/<span>, imported .css/@apply, or hardcoded #hex/px with the component or a token';
+
export const MARKER_START = '<!-- ASTRYX:START -->';
export const MARKER_END = '<!-- ASTRYX:END -->';
// Legacy markers — read during migration so the script finds existing XDS blocks
@@ -91,7 +111,9 @@ export function holdsAstryxBlock(content) {
while (at !== -1) {
const from = at + marker.length;
const end = content.indexOf('<!--', from);
- const inner = (end === -1 ? content.slice(from) : content.slice(from, end)).trim();
+ const inner = (
+ end === -1 ? content.slice(from) : content.slice(from, end)
+ ).trim();
if (!/^@\S+$/.test(inner)) return true;
at = content.indexOf(marker, from);
}
@@ -153,7 +175,7 @@ export function isAstryxPromptInReach(startDir = process.cwd()) {
* @returns {string | null}
*/
function findRepositoryRoot(start) {
- for (let dir = start; ; ) {
+ for (let dir = start; ;) {
if (fs.existsSync(path.join(dir, '.git'))) return dir;
const parent = path.dirname(dir);
if (parent === dir) return null;
diff --git a/packages/cli/foundation/agent-docs/agent-docs.mjs b/packages/cli/foundation/agent-docs/agent-docs.mjs
index 700283d6f1..192746a09a 100644
--- a/packages/cli/foundation/agent-docs/agent-docs.mjs
+++ b/packages/cli/foundation/agent-docs/agent-docs.mjs
@@ -58,6 +58,9 @@ import {
discoverAgentDocs,
isAstryxInitialized,
isAstryxPromptInReach,
+ SELF_CHECK_CSS,
+ WORKFLOW_STEPS,
+ WORKFLOW_TITLE,
} from './agent-doc-state.mjs';
// The agent-doc locations, markers, and the setup-state predicates
@@ -762,10 +765,7 @@ export function generateCompressedIndex(
// Workflow — `build` is the front door, and every page starts from the
// template it names. build/template/component are covered here, so they are
// intentionally omitted from the command reference below.
- lines.push('WORKFLOW — start every page from a template, never from scratch:');
- lines.push('1. `astryx build "<idea>"` — names the template to scaffold from and the parts it lacks.');
- lines.push('2. `astryx template <name> <path>` — scaffold it; keep its frame, gap and padding; replace the content.');
- lines.push('3. `astryx template <Block>` for parts it lacks; `astryx component <Name>` to read props before using one.');
+ lines.push(WORKFLOW_TITLE, ...WORKFLOW_STEPS);
lines.push('Changing an existing page? Keep it: skip step 2 and add blocks/components inside its sections.');
lines.push('');
@@ -793,7 +793,7 @@ export function generateCompressedIndex(
'replace any className=, style={{…}}, raw <div>/<span>, imported .css/@apply, or hardcoded #hex/px with the component or the xstyle prop + a token',
tailwind:
'replace any style={{…}}, raw <div>/<span>, imported .css/@apply, or hardcoded/arbitrary value (bg-[#fff], p-[13px]) with the component or a token-backed utility',
- css: 'replace any raw <div>/<span>, imported .css/@apply, or hardcoded #hex/px with the component or a token',
+ css: SELF_CHECK_CSS,
};
lines.push(
`- SELF-CHECK: re-read the file; ${selfCheckFix[stylingSystem] ?? selfCheckFix.css}.`,
diff --git a/packages/cli/foundation/agent-docs/computer-agent-text.mjs b/packages/cli/foundation/agent-docs/computer-agent-text.mjs
index 188c71455c..fedd842340 100644
--- a/packages/cli/foundation/agent-docs/computer-agent-text.mjs
+++ b/packages/cli/foundation/agent-docs/computer-agent-text.mjs
@@ -43,7 +43,13 @@ import {createHash} from 'node:crypto';
import {cliDoor} from '../env/cli-command.mjs';
import {astryxCommandsOnSearchPath} from '../env/search-path.mjs';
import {samePath} from '../fs/path-compare.mjs';
-import {MARKER_START, MARKER_END} from './agent-doc-state.mjs';
+import {
+ MARKER_START,
+ MARKER_END,
+ SELF_CHECK_CSS,
+ WORKFLOW_STEPS,
+ WORKFLOW_TITLE,
+} from './agent-doc-state.mjs';
/** The command the computer-level text uses when no host door is set. */
export const COMPUTER_COMMAND = 'astryx';
@@ -175,6 +181,15 @@ function bodyLines(run) {
`Its docs, components, templates, and themes are all reachable through \`${run}\`. Start with \`${run} search '<what you need>'\`.`,
`Then read \`${run} component <Name>\` or \`${run} docs <topic>\`, not the package's files.`,
"In a project, the project's version of Astryx answers automatically.",
+ // How to build, which discovery alone leaves to the agent's own page
+ // route: in a project, from the template, with the project agent docs'
+ // own workflow lines.
+ // A project that already installs Core gets the CLI at that version, as
+ // the CLI's own hint for that state says, never a newer CLI beside it.
+ `To build UI, work in a project folder (create one if there is none). Add \`@astryxdesign/core\` and \`@astryxdesign/cli\` to a new project or one without \`@astryxdesign/core\`; to a project that already has \`@astryxdesign/core\`, add \`@astryxdesign/cli\` at the same version. Run \`${run} init\` there and follow the agent docs it writes.`,
+ WORKFLOW_TITLE,
+ ...WORKFLOW_STEPS.map(step => step.replaceAll('`astryx ', `\`${run} `)),
+ `Before you deliver, re-read each file; ${SELF_CHECK_CSS}. Then build the project and deliver that build, not a description of it.`,
];
}
diff --git a/packages/cli/foundation/agent-docs/computer-agent-text.test.mjs b/packages/cli/foundation/agent-docs/computer-agent-text.test.mjs
index 6adaacc21d..94d5af147c 100644
--- a/packages/cli/foundation/agent-docs/computer-agent-text.test.mjs
+++ b/packages/cli/foundation/agent-docs/computer-agent-text.test.mjs
@@ -27,7 +27,13 @@ import {
renderComputerAgentText,
writeComputerAgentText,
} from './computer-agent-text.mjs';
-import {MARKER_END, MARKER_START} from './agent-doc-state.mjs';
+import {
+ MARKER_END,
+ MARKER_START,
+ SELF_CHECK_CSS,
+ WORKFLOW_STEPS,
+ WORKFLOW_TITLE,
+} from './agent-doc-state.mjs';
import {runWithCliDoor} from '../env/cli-command.mjs';
import {runCli} from '../../test-utils/run-cli.mjs';
import {parse as parseYaml} from 'yaml';
@@ -123,12 +129,27 @@ describe('renderComputerAgentText', () => {
it('stays short, and tells agents to read docs through the CLI', () => {
const text = renderComputerAgentText({command: 'astryx'});
- expect(text.split('\n').length).toBeLessThanOrEqual(15);
+ expect(text.split('\n').length).toBeLessThanOrEqual(22);
expect(text).toContain(
"Then read `astryx component <Name>` or `astryx docs <topic>`, not the package's files.",
);
});
+ // Discovery alone leaves the build to the agent's own page route, which
+ // may not install packages; the skill names the route and the project
+ // agent docs' own workflow lines.
+ it('gives the build workflow: a project with Astryx installed and init run, the shared template steps, then check and deliver the build', () => {
+ const text = renderComputerAgentText({command: 'astryx'});
+ expect(text).toContain(
+ 'To build UI, work in a project folder (create one if there is none). Add `@astryxdesign/core` and `@astryxdesign/cli` to a new project or one without `@astryxdesign/core`; to a project that already has `@astryxdesign/core`, add `@astryxdesign/cli` at the same version. Run `astryx init` there and follow the agent docs it writes.',
+ );
+ for (const line of [WORKFLOW_TITLE, ...WORKFLOW_STEPS]) {
+ expect(text).toContain(line);
+ }
+ expect(text).toContain(`re-read each file; ${SELF_CHECK_CSS}.`);
+ expect(text).toContain('deliver that build');
+ });
+
it("uses the host's door when one is set", () => {
const text = runWithCliDoor('acme astryx', () => renderComputerAgentText());
expect(text).toContain("`acme astryx search '<what you need>'`");
diff --git a/packages/core/scripts/agent-doc-state.mjs b/packages/core/scripts/agent-doc-state.mjs
index e4eccd5b0d..9b17e16705 100644
--- a/packages/core/scripts/agent-doc-state.mjs
+++ b/packages/core/scripts/agent-doc-state.mjs
@@ -44,6 +44,26 @@ export const CURSOR_RULES = '.cursorrules';
export const HERMES_DOT_MD = '.hermes.md';
export const HERMES_MD = 'HERMES.md';
+/**
+ * The page workflow every Astryx agent text gives, written with the command
+ * name `astryx`: the project agent docs and the computer-level skill both
+ * render these lines, so the two never drift.
+ */
+export const WORKFLOW_TITLE =
+ 'WORKFLOW — start every page from a template, never from scratch:';
+export const WORKFLOW_STEPS = Object.freeze([
+ '1. `astryx build "<idea>"` — names the template to scaffold from and the parts it lacks.',
+ '2. `astryx template <name> <path>` — scaffold it; keep its frame, gap and padding; replace the content.',
+ '3. `astryx template <Block>` for parts it lacks; `astryx component <Name>` to read props before using one.',
+]);
+
+/**
+ * The self-check's fix for a project with no StyleX or Tailwind compiler,
+ * and for an agent outside a project.
+ */
+export const SELF_CHECK_CSS =
+ 'replace any raw <div>/<span>, imported .css/@apply, or hardcoded #hex/px with the component or a token';
+
export const MARKER_START = '<!-- ASTRYX:START -->';
export const MARKER_END = '<!-- ASTRYX:END -->';
// Legacy markers — read during migration so the script finds existing XDS blocks
@@ -101,7 +121,9 @@ export function holdsAstryxBlock(content) {
while (at !== -1) {
const from = at + marker.length;
const end = content.indexOf('<!--', from);
- const inner = (end === -1 ? content.slice(from) : content.slice(from, end)).trim();
+ const inner = (
+ end === -1 ? content.slice(from) : content.slice(from, end)
+ ).trim();
if (!/^@\S+$/.test(inner)) return true;
at = content.indexOf(marker, from);
}
@@ -163,7 +185,7 @@ export function isAstryxPromptInReach(startDir = process.cwd()) {
* @returns {string | null}
*/
function findRepositoryRoot(start) {
- for (let dir = start; ; ) {
+ for (let dir = start; ;) {
if (fs.existsSync(path.join(dir, '.git'))) return dir;
const parent = path.dirname(dir);
if (parent === dir) return null;