# Checklist — AI Agent Instructions

Use this guide with **Claude, Cursor, ChatGPT, Copilot**, or any AI agent to generate a **test checklist JSON** for your project. Upload the JSON into the Checklist website (**Upload checklist JSON**).

---

## What this tool is

**Checklist** is a reusable, non-technical tester app:

1. Upload a JSON of features/tasks to test  
2. Tester marks Pass / Fail / Skip / N/A  
3. Optional notes per item  
4. Download results or save shared history (when API is available)

One website works for **any module or project** — only the JSON changes.

---

## Copy-paste prompt for AI agents

Replace the placeholders in `[brackets]`, then paste into your AI:

```text
Create a test checklist JSON for the Checklist web app.

Project / module: [NAME OF MODULE OR FEATURE]
App routes or pages involved: [e.g. /employee, /payroll, /settings]
Audience: non-technical QA / UAT testers
Language: [English or Filipino/English]

Requirements:
1. Output ONLY valid JSON (no markdown fences, no commentary).
2. Follow this exact schema:

{
  "version": 1,
  "title": "<Module name> — Test Checklist",
  "checklist": [
    {
      "id": "kebab-case-section-id",
      "title": "1. Section name",
      "items": [
        {
          "id": "kebab-case-item-id",
          "text": "Clear action the tester should do (and what success looks like)",
          "link": "/relative-path-or-empty-string"
        }
      ]
    }
  ]
}

3. Rules:
- Group tasks into logical sections (setup, happy path, edge cases, permissions, etc.).
- Each item.text must be one concrete test step a non-developer can follow.
- Prefer relative links like "/employee" (not full domains). Use "" if no page.
- ids must be unique, lowercase, kebab-case.
- Section titles numbered: "1. …", "2. …"
- Cover create/edit/delete, validation errors, empty states, and at least one edge case section.
- Aim for 15–60 items unless the module is tiny.

4. Base the tasks on this context / acceptance criteria / code:
[PASTE SPECS, USER STORIES, OR RELEVANT CODE SUMMARY HERE]
```

---

## JSON schema (reference)

| Field | Required | Description |
|-------|----------|-------------|
| `version` | yes | Number, use `1` |
| `title` | yes | Shown as the checklist name |
| `checklist` | yes | Array of sections |
| `checklist[].id` | yes* | Unique section id (`kebab-case`) |
| `checklist[].title` | yes | Section heading |
| `checklist[].items` | yes | Array of tasks |
| `checklist[].items[].id` | yes* | Unique item id |
| `checklist[].items[].text` | yes | What the tester should do |
| `checklist[].items[].link` | no | Relative path, full URL, or `""` |
| `draft` | no | Omit for new checklists (app creates empty draft) |

\* If missing, the website auto-generates ids on upload.

### Minimal valid example

```json
{
  "version": 1,
  "title": "Leave Credits — Test Checklist",
  "checklist": [
    {
      "id": "leave-setup",
      "title": "1. Leave setup",
      "items": [
        {
          "id": "leave-1",
          "text": "Open Leave Credits → create a new leave type → Save → it appears in the list",
          "link": "/leave-credits"
        },
        {
          "id": "leave-2",
          "text": "Leave balance empty → Save → show validation error",
          "link": "/leave-credits"
        }
      ]
    },
    {
      "id": "leave-edge",
      "title": "2. Edge cases",
      "items": [
        {
          "id": "leave-3",
          "text": "Employee with 0 credits → request leave → blocked or warning shown",
          "link": "/leave-request"
        }
      ]
    }
  ]
}
```

---

## How to use the generated JSON

1. Open the Checklist website (Home = checklist library).  
2. Ask your AI (using the prompt above) to generate the JSON.  
3. Save the output as `my-module-checklist.json`.  
4. On Home, click **+ Add checklist JSON** and select the file.  
5. Click **Open** on that checklist.  
6. Enter tester name → **Start checklist**.  
7. Set **Default app base URL** on Home if Open page links are needed.

---

## Writing good test items

**Good**

- `Create employee with Branch A + Branch B → Save → reopen → both branches still assigned`
- `Submit form with empty required field → error message shown, no save`

**Avoid**

- Vague: `Test the module`
- Dev-only: `Assert SQL join returns correct rate_id`
- Multiple unrelated steps in one item

---

## Reuse across projects

- Keep using the **same Checklist website**.  
- Home is a **library** of checklists stored in this browser.  
- For each new module/project, generate a JSON and **+ Add checklist JSON**.  
- Open any checklist anytime; drafts stay with that checklist until Finish/export.

---

## File name suggestion

`{module-slug}-test-checklist.json`  
Example: `leave-credits-test-checklist.json`