| name | plan-block |
| description | Discuss a new block's purpose and requirements with the user, then create a GitHub issue with a structured breakdown ready for /wp-acf-blocks:add-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
