---
name: extension-planner
description: Transform a base schema into a Product Requirements Document and visual HTML mockups for customer sign-off. Use at Stage 2 after schema.md has been generated, when the consultant describes what the customer wants to build, or when revising requirements or mockups based on customer feedback.
---

# Extension Planner

## Prerequisites
- Stage 1 (Schema Discovery) is complete — `schema.md` exists at the workspace root
- `status.md` shows Stage 1 as done
- Consultant has a description (even rough) of what the customer wants

## Step 1: Check Prerequisites

Read `status.md` to confirm Stage 1 is complete. Then check for `schema.md`.

If `schema.md` is missing or Stage 1 is not marked done:
> "I need the base schema before we can plan the extension. Let's run Schema Discovery first — do you have the base ID?"

If `prd.md` already exists, check its status:
- If the Sign-Off Record section shows `[Pending]` — the PRD is in progress. Ask:
  > "You have a PRD in progress for this project. Do you have customer feedback to incorporate, or would you like to start fresh?"
- If the Sign-Off Record shows an approval date — the PRD was already approved. Ask:
  > "This project already has an approved PRD. Do you need to revise it, or are you ready to move to Code Generation?"

If revising an existing PRD, skip to Step 8 (Iterate on Feedback).

## Step 2: Requirements — Context & Purpose

Read `schema.md` to understand the base structure. Then ask the consultant about the extension's purpose. Reference specific tables and fields from the schema to ground the conversation.

> "Now I need to understand what the customer wants this extension to do. I'll ask a few questions — just describe it in plain language and I'll translate everything into a formal requirements doc."

Ask about:
- **Purpose**: What problem does this extension solve? What happens today without it?
- **Target users**: Who will use this? What are their roles? Roughly how many users?
- **User tasks**: What specific tasks do the users need to perform? Walk through the key things a user would do in a session. Each task becomes a user story in the PRD — e.g., "Review all open projects and filter by status", "Update a task's assignee and due date", "See a summary of overdue items."

Use the schema to offer context. For example:
> "I can see you have a Projects table linked to Tasks and Clients. Is this extension for managing projects, tracking tasks, or something else?"

Prompt the consultant to think through the user's workflow end-to-end:
> "Walk me through what a user would do in a typical session with this extension — from opening it to finishing their work. What are the key tasks they need to accomplish?"

Each task the consultant describes becomes the basis for a user story and acceptance criterion in the PRD. Push for specificity — "manage projects" is too vague; "filter projects by status, click into a project to see linked tasks, update task assignments" is actionable.

Do not proceed until the consultant has described at least 2-3 concrete user tasks. It is fine if answers are rough — you will refine in the next step.

## Step 3: Requirements — Functionality & UI

Now get specific about features and interface design. Ask about each category below, offering concrete options based on the schema rather than open-ended questions.

**Functionality** — Which of these does the extension need?
- View/browse records (which tables?)
- Edit existing records (which fields?)
- Create new records
- Filter or search
- Sort
- Aggregate or summarize (counts, totals, charts)
- Link or unlink records across tables
- Custom workflows (e.g., status transitions, approvals)

**Data model** — List the tables from schema.md and ask which are in scope:
> "Your base has these tables: [list]. Which ones does this extension need to read from? Which ones does it need to write to?"

**Layout and UI** — Offer common patterns:
- Dashboard with summary cards and a data table
- List view with a detail panel on click
- Tabbed interface with multiple views
- Form-based data entry
- Kanban/board view
- Split pane (list on left, detail on right)

**Interactions** — Phrase as user scenarios:
> "When a user clicks a row in the table, should it open a detail panel, navigate to a new view, or expand inline?"
> "Should users be able to edit fields directly in the table, or only through a detail/edit view?"

**Constraints** — Ask about:
- Expected number of records in the primary table (affects performance approach)
- Permission requirements (who can view vs. edit?)
- Any deadline or timeline pressure
- Mobile/responsive needs (or desktop-only within Airtable)

Summarize what you heard back to the consultant for confirmation before proceeding:
> "Let me make sure I've got this right: [summary]. Anything I'm missing or got wrong?"

## Step 4: Design References (Optional)

Before generating the PRD and mockups, check if the customer has any design references that should influence the look and feel of the extension.

> "One more thing before I draft the requirements doc — does the customer have any design preferences or references? This could be anything:
> - A written description (e.g., 'clean and modern', 'match our brand colors')
> - CSS files or style guides from their existing apps
> - Links to web pages or apps they want it to look similar to
> - Screenshots, logos, or brand guideline documents
>
> This is optional — if there's nothing specific, I'll use a clean default style. But any references you have will make the mockups and final build feel more like 'theirs'."

If the consultant **skips** (no references): acknowledge and move on to Step 5. No `design-spec.md` is created; downstream steps use the default wireframe style.

If the consultant **provides references**, process each type:

### Written Descriptions
Extract concrete design tokens where possible (colors, font names, adjectives about density/spacing). Note subjective direction (e.g., "minimal like Notion") as a pattern reference.

### CSS Files
Read the file and extract:
- Color values (custom properties, hex/rgb in common selectors)
- Font families and size scale
- Border-radius, box-shadow, and spacing patterns
- Note: save the raw file to `design/`

### Example Web Pages / Apps
If a URL is provided, fetch and analyze:
- Overall layout structure
- Color palette visible in the UI
- Typography choices
- Component patterns (card style, table style, navigation style)
- Note: take what's visually relevant — this is design inspiration, not cloning

If a screenshot is provided, read the image and extract the same observations.

### Image Assets (Logos, Brand Guides)
Read the image. Extract any visible colors, typography, and style patterns. Save the raw file to `design/`.

### Generate the Design Spec

After processing all references, generate `design-spec.md` using the template in [reference/design-spec-template.md](reference/design-spec-template.md).

Key rules:
- **Only fill rows where you have actual input** — don't invent a full palette from one hex color. Leave unknown rows blank.
- **Distinguish explicit vs. inferred** — if the customer said "use blue" and you picked `#2563EB`, note it as inferred
- **Keep Sources accurate** — every design decision should trace back to a specific input
- **Flag font loading risks** — if the customer wants a custom web font, note in Section 7 that the Airtable extension sandbox may limit external font loading

Present a summary to the consultant:
> "I've created a design spec from those references. Here's what I'm working with:
> - **Colors:** [brief summary — e.g., 'Navy primary (#1E3A5F), light gray backgrounds']
> - **Typography:** [brief summary — e.g., 'Inter font family, 14px base' or 'No specific font — using system default']
> - **Style:** [brief summary — e.g., 'Rounded corners, subtle shadows, comfortable spacing']
> - **Patterns:** [brief summary — e.g., 'Card-based layout inspired by their existing dashboard']
>
> I'll apply these to the mockup and carry them forward into the final build. Anything you'd adjust?"

If the consultant wants changes, update `design-spec.md`. Then proceed to Step 5.

## Step 5: Generate PRD

Generate `prd.md` using the template in [reference/prd-template.md](reference/prd-template.md).

Write the output to: `prd.md` at the workspace root

Key rules:
- **Fill every section** — do not leave template placeholders in the output. If information wasn't gathered, make a reasonable assumption and flag it with `*[Assumed — confirm with customer]*`
- **Acceptance criteria must be testable** — each one is a specific action + expected result. The QA Generator (Stage 5) reads this table directly to produce test scripts
- **Technical Approach should name SDK hooks** — reference specific hooks (`useRecords`, `useBase`, `useCustomProperties`, etc.) so the Extension Builder (Stage 4) can act on it
- **Data Model section must include field IDs** from schema.md — the Extension Builder needs them for `useRecords({ fields: [...] })` calls
- **Keep it readable** — this document gets shared with the customer. Use plain language in Sections 1-4 and 6. Technical details go in Section 5.

After writing, present a summary to the consultant:
> "Here's the PRD for **[Extension Name]**:
> - **[N] functional requirements** across [N] feature areas
> - **[N] tables** in scope ([list])
> - **Layout**: [brief layout description]
> - **[N] acceptance criteria** for QA testing
>
> Take a minute to read through it — especially the Functional Requirements and Acceptance Criteria sections. These drive everything downstream: the code I'll generate and the QA tests. Let me know if anything needs to change before we build the mockup."

Wait for the consultant to confirm or request changes before proceeding. If changes are needed, update `prd.md` and re-summarize.

## Step 6: Generate HTML Mockup

Read the PRD's User Interface Specification section (Section 4) and generate a visual HTML mockup. Follow the guidelines in [reference/mockup-guidelines.md](reference/mockup-guidelines.md).

**Check for design spec:** If `design-spec.md` exists, read it and apply the design tokens to the mockup (colors, typography, border-radius, shadows, layout preferences). See the "Applying Design References" section in the mockup guidelines for details. If no design spec exists, use the default wireframe style.

Key rules:
- **Self-contained HTML** — single file with Tailwind CDN, no external dependencies
- **Realistic sample data** — pull field names and types from schema.md, generate 5-8 believable records
- **For multi-view extensions** — use tab navigation within a single HTML file (data-tab switching via JS)
- **Include the wireframe banner** — customers should know this is a layout preview, not the final product
- **Annotate non-obvious interactions** — use yellow callout boxes for hover states, drag-and-drop, real-time updates, etc.

Save the mockup to: `mockups/mockup.html`

If the extension has 4+ distinct views that make a single file unwieldy, generate separate files (`view-dashboard.html`, `view-detail.html`, etc.) plus an `index.html` landing page with links to each view.

After generating, tell the consultant to preview:
> "I've created a visual mockup of the extension. Open it in your browser to preview:
> `mockups/mockup.html`
>
> This shows the layout, navigation, and sample data — the final extension will use Airtable SDK components which have their own styling, so colors and exact appearance will differ. Let me know if the structure and flow look right before we share it with the customer."

Wait for the consultant to confirm the mockup looks good before publishing.

## Step 7: Share Mockup with Customer

Tell the consultant how to share the mockup for customer review:

> "The mockup is ready for customer review. Here are your options to share it:
>
> 1. **Send the file directly** — find `mockups/mockup.html` in your project folder and share it via Slack, email, or Google Drive. The customer just opens it in any browser.
> 2. **Upload to Airtable** — if you have a project tracking base, upload the HTML file to an attachment field on the customer's record.
>
> When you have feedback from the customer, just tell me what they want changed."

## Step 8: Iterate on Feedback

When the consultant reports customer feedback:

1. **Restate the feedback** to confirm understanding:
   > "Got it. The customer wants: [restate each change]. Is that right?"

2. **Categorize each change:**
   - **Layout changes** (mockup only) — e.g., "move the filter bar above the table"
   - **Requirement changes** (PRD + mockup) — e.g., "add the ability to create new records"
   - **Data changes** (PRD data model + mockup) — e.g., "include the Budget field"
   - **Design changes** (design-spec + mockup) — e.g., "use our brand blue instead", "make it more compact" → update `design-spec.md` (or create it if it doesn't exist) and regenerate the mockup with the new tokens

3. **If the feedback fundamentally changes the extension** (e.g., "actually they want a Kanban board, not a dashboard"), flag it:
   > "That's a significant change from the original requirements. I'll regenerate the PRD from scratch rather than patching it — the acceptance criteria need to be rewritten too."

4. **Update `prd.md`** — modify affected sections and add an entry to the Revision History table:
   ```
   | [date] | [Summary of changes] | Customer feedback |
   ```

5. **Regenerate the mockup** — update affected sections of the HTML and save

6. **Ask about next steps:**
   > "I've updated the PRD and mockup based on that feedback. Share the updated `mockups/mockup.html` with the customer the same way as before.
   >
   > Is there more feedback to address, or is the customer ready to sign off?"

If more feedback: repeat this step.
If ready to sign off: proceed to Step 9.

## Step 9: Record Sign-Off and Stage Transition

When the consultant says they're ready to move on, have sign-off, or otherwise indicate approval — accept it and proceed. Do not ask for approver names, roles, or confirmation methods. The consultant saying "we're ready" is sufficient.

1. **Update `prd.md`** — Change the Status field at the top from `Draft` or `In Review` to `Approved`. If there is a Sign-Off Record section, fill in today's date and "Consultant confirmed".

2. **Update `status.md`:**
   ```
   - [x] Stage 2: Requirements & Planning — completed [date]
     - PRD: prd.md (Approved)
     - Mockup: mockups/mockup.html
   ```

3. **Transition to the next stage:**
   > "Requirements are locked. Next step is **Project Setup** — I'll walk you through setting up the development project on your Mac so we can start building. Ready to continue?"

Do not auto-advance. Wait for the consultant to confirm.