Skip to content
Type something to search...
to navigateto selectESC to close
Ultimate Astro Theme GuidesDocs
Kivo Theme Documentation

The AI Workflow

Skill level: Beginner · Time: 5 minutes to set up

The same loop works for every change: save a checkpoint → ask → review → check → keep or undo.

For Cursor, Windsurf, Claude Code, GitHub Copilot in VS Code, Gemini CLI, Codex, and similar tools.

  1. Open the whole kivo 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 so you can watch the change happen at http://localhost:4321/.

  3. Save a checkpoint. If you use git, commit. If not, copy the folder. See Editing 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.” 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, in light and dark mode, and on a narrow window. Ask the assistant to run npm run astro-check, or run it yourself.

  7. Keep it or undo it. Commit if you are happy. If not, ask the tool to revert, or restore your checkpoint.

Give The AI Good Context

The more precise the request, the better the result. Useful things to include:

  • The file. “Edit src/content/pricing/english/-index.md”, not “edit the pricing”.
  • The page. “The section under the hero on /home-api/.”
  • Your product. One paragraph: what it does, who it is for, and its main features. Paste it into every copywriting request.
  • The layout name. Copy it from the /elements/ gallery or the comment next to layout: in the section file: “use the bento layout of the feature grid”.
  • What must not change. “Keep every key, option, and the number of items.”
  • The recipe. For bigger jobs, point to SKILLS.md, which no tool reads on its own: “Follow the ‘Add or remove a language’ skill in SKILLS.md.”

Review Checklist

Before you accept a change, check:

  • Only the files you expected were edited.
  • Text was changed in src/content/ (or src/i18n/), not typed into a component.
  • Both english/ and french/ files were updated (unless you use one language).
  • Keys and indentation in Markdown frontmatter, TOML, and JSON still look like the rest of the file.
  • No new colors like text-[#123456] in components. Kivo uses its theme tokens (text-primary, bg-theme-light).
  • No testimonials, customer names, metrics, ratings, 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. astro-check doesn’t check section, contact, FAQ, or pricing files, and a misnamed page block is ignored without an error, so only the page shows these mistakes.

When The AI Gets Stuck

  • There is an error in the terminal. Copy the whole error, including the file name and line number, and paste it with: “Fix this error. Explain the cause in one sentence.”
  • The change does nothing. Ask: “Which file does this text come from on this page? Check the page’s named block and the section file.” A page block overrides the section file (see How Kivo Works).
  • It keeps going in circles. Undo to your checkpoint, start a new conversation, and ask for a smaller step.