# The AI Workflow

## 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.**

<Tabs>
  <TabItem label="AI editors and agents">

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

    <Steps>

    1. **Open the whole `taskly` project folder** in the tool (the folder with `package.json`), not a single file or the folder 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/](http://localhost:4321/).

    3. **Save a checkpoint.** If you use git, commit. If not, copy the folder. See [Editing Safely](/taskly/beginner/editing-safely/).

    4. **Ask for one change.** Name the file if you know it. The tools listed in the [AI Overview](/taskly/ai-customization/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](/taskly/ai-customization/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, on a narrow window, and in French if you changed it. 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.

    </Steps>

  </TabItem>
  <TabItem label="Chat assistants">

    For ChatGPT, Claude, Gemini, or any assistant in a browser tab.

    <Steps>

    1. **Give it the rules once per conversation.** Open `AGENTS.md` in your editor, copy all of it, and paste it with: "These are the rules of the website theme I'm editing. Follow them in every answer."

    2. **Paste the file you want to change**, with its path. For example: "Here is `src/content/sections/english/hero-section.md`:" and the whole file.

    3. **Ask for the change and the full file back**: "Return the complete file, ready to paste, and change nothing else."

    4. **Paste the answer over the file** in your editor and save.

    5. **Check the result** in the browser. If the terminal shows an error, copy the error and paste it back into the chat.

    </Steps>

    Chat assistants work best for text: rewriting copy, translating, writing posts. For changes that touch several files, an AI editor saves a lot of copying.

  </TabItem>
</Tabs>

### 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-3/`."
- **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 `marquee` layout of the testimonials".
- **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.
- [ ] Colors use the tint names (`sun`, `lime`, `sky`…) in content and theme tokens (`text-primary`, `bg-cream`) in components, never new values like `text-[#123456]`.
- [ ] 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 open without an error in `npm run dev` and look right. A misnamed page block or key 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 Taskly Works](/taskly/getting-started/how-taskly-works/)).
- **It keeps going in circles.** Undo to your checkpoint, start a new conversation, and ask for a smaller step.

<Aside type="caution">
  Never paste passwords, API keys, or private customer data into an AI chat.
  Taskly doesn't need any to be customized: form endpoints and analytics IDs
  are public values.
</Aside>