Plan block

Read @/knowledge/acf-blocks/conventions.md for the breakdown format and namespace detection rules before starting.

Step 1 — Get GitHub project

Ask: Which GitHub project should this issue go into? Accept a project URL or project name. If the user has used one before this session, suggest it.

gh project list --owner <owner>

Step 2 — Understand the block

Ask: What is this block for? Describe it loosely.

Then ask clarifying questions based on the response. Cover all of these before drafting - but ask conversationally, not as a form:

• What content does it display? (text, images, video, links?)
• Any repeating items? (cards, slides, rows, accordion items?)
• Layout: single column, grid, split, tabs, accordion, slider?
• Does anything expand, animate, or change on user interaction?
• Is there a heading above the main content?
• Any CTAs or links?
• Mobile layout different from desktop?

Stop asking when you have enough to write a complete breakdown. Usually 3-5 exchanges.

Step 3 — Draft breakdown

Write the breakdown in standard format:

## Block: {slug}

**Slug:** `{slug}`
**Title:** {Title}
**Description:** {One sentence describing what this block does.}

### Fields
- `{field_name}` — {type} — {purpose}
- `{repeater_name}` — repeater
  - `{sub_field}` — {type}

### Layout
- {Layout description line by line}
- {Note any JS interactions needed}

Rules:

• Slug: kebab-case, descriptive, concise (e.g. team-grid, faq-accordion)
• Fields: only what render.php will actually read via get_field()
• Image fields: always note (return_format: id)
• Link fields: always note (return_format: array)
• Layout: enough detail for Claude to generate structural HTML - columns, order, loops, interactions

Show the draft to the user and ask: Does this look right? Any changes?

Iterate until approved.

Step 4 — Create GitHub issue

gh issue create \
  --repo <owner>/<repo> \
  --title "Block: {Title}" \
  --body "{breakdown}" \
  --project "{project name or URL}"

Show the created issue URL and number.

Step 5 — Handoff

Issue #42 created: Block: {Title}

Run this to scaffold:
/wp-acf-blocks:add-block #42