AI Workflow

AI Workflow

Skill level: Beginner

Two ways to work, depending on whether your assistant can open your project folder. Pick the tab that matches your tool.

• AI editor (recommended)
• Chat assistant

1. Open the whole veltro project folder in the tool (the folder with package.json), not a single file or the unzipped download around it. The tool needs that folder to find AGENTS.md and its own rules file.

2. Start the site with npm run dev and keep it open at http://localhost:4321, so you see each change.

3. Save a checkpoint. If you use git, commit. If not, copy the folder. See Editing Content Safely.

4. Ask for one change. Name the file if you know it. The tools listed in the AI Overview load the theme’s rules on their own. If your tool isn’t listed, or its answers ignore the rules, start your first request with “Read AGENTS.md first.” For a bigger job, add “Follow the matching recipe in SKILLS.md.” The Prompt Library has ready-made requests.

5. Review what changed. Every tool shows a list of edited files and the changes (“diff”). Check the list against the review checklist below before you accept.

6. Check the result in the browser, at a narrow window and at /ar/. npm run dev regenerates the config from config.toml when it starts, and picks up saved content changes on its own. Restart it after you change src/config/fonts.json, src/config/language.json, trailingSlash, or anything in [settings.multilingual]: Astro reads those only when it starts. Ask the assistant to run npm run astro-check, or run it yourself.

What To Tell The Assistant

The more of this you give, the less it has to invent.

• The file. “Edit src/content/sections/english/services-section.md”, not “edit the services”.
• The page. “The section under the hero on /about/.”
• Your company. One paragraph: what you build, for whom, and what makes you different. Paste it into every copywriting request.
• Your real figures. Prices, team size, years in business, results you can back up. If you don’t give them, tell the assistant to keep the sample values and list them for you to replace.
• The layout value. Take it from src/enum.ts: “set the services card layout to carousel”.
• What must not change. “Keep every key, option, and the number of items.”
• The recipe. For bigger jobs, point to SKILLS.md, which most tools don’t read on their own: “Follow the ‘Add or remove a language’ skill in SKILLS.md.”

Review Checklist

Go through this before you accept a change.

• Text was changed in src/content/, src/config/, or src/i18n/, not typed into a component.
• Every language was updated: each language folder under src/content/, src/i18n/<language>.json, and src/config/menu.<language>.json (unless you turned a language off).
• Prices and other numbers are identical in the pricing file of every language.
• Keys, ids, and indentation in Markdown frontmatter, TOML, and JSON still look like the rest of the file.
• A new page block is actually passed to its section in the route file.
• Any options.layout value exists in src/enum.ts for that card.
• Button variant, hoverEffect, and class values come from sharedButton in src/sections.schema.ts, not from an out-of-date comment.
• No new colors like text-[#123456] in components. Veltro uses its theme tokens (bg-primary, bg-accent, bg-theme-light, text-text-dark).
• New or changed CSS uses logical classes (ms, me, ps, pe, text-start), not ml, pr, or text-left.
• No client names, testimonials, case-study results, awards, metrics, or prices were made up. Where you didn’t provide them, the assistant kept the sample items and told you which ones to replace.
• npm run astro-check reports no errors.
• The changed pages look right in the browser:
  • at about 375 px wide and at 1280 px
  • in every language (the language switch, or /fr/ or /ar/ in front of the path). Arabic pages should read right to left

astro-check validates the collections that have a schema. The sections, about, awards, faq, pricing, and author collections have none, so a wrong option value there passes the check, and a key no schema declares is dropped silently. Only the page shows those mistakes.

When Something Goes Wrong

• The build or the check fails. Paste the whole error, including the file and line, and ask for the cause and the smallest fix.
• astro-check complains about the config. Run npm run toml:watch once: the check needs .astro/config.generated.json.
• The change does nothing. Ask: “Which file does this text come from on this page? Check the section file in src/content/sections/english/, and whether the route in src/pages/[...lang]/ passes a content prop that overrides it.” A page’s frontmatter block only wins when the route passes it (see How The Theme Is Organized). If the change is in config.toml, restart npm run dev.
• A new field is ignored. A frontmatter key that no schema declares is dropped. Ask the assistant to add it to src/sections.schema.ts or src/content.config.ts.
• A card layout value does nothing. The comment beside options.layout is out of date in some files. The real values are in src/enum.ts: ServiceCard grid, card, carousel; BlogCard card, grid, horizontal, creative; PortfolioCard grid, masonry, horizontal; TestimonialCard carousel-full, carousel, card; IndustryCard list, grid.
• A list page ignores an option. List pages read options from that collection’s -index.md, not from the section file.
• The header behaves oddly on one page. Those are Base.astro props in the route: headerPosition (sticky, fixed, static), headerBorderOnScroll, hideOffcanvas, hideHeader.
• The layout broke at /ar/. Ask the assistant to replace physical classes with logical ones, and to add rtl: handling for translate-x-*, transform origins, and gradient directions, which don’t flip by themselves.
• It keeps ignoring a rule. Say “Re-read AGENTS.md, section [NAME], then redo this.”