assistant-architect

What this skill does

# Assistant Architect

Create valid JSON import files for PSD AI Studio's Assistant Architect system.

**Spec Reference:** See `references/json-spec.md` for complete field definitions and validation rules.

---

## Input Modes

### From Screenshot

When the user provides a screenshot, extract:

| Element | Maps To |
|---------|---------|
| Text input boxes | `short_text` (single line) or `long_text` (multi-line) |
| Dropdowns/select menus | `select` with choices from visible options |
| Checkboxes/multi-select | `multi_select` |
| File upload areas | `file_upload` |
| Field labels | `label` property |
| Placeholder text | `options.placeholder` |
| Visible instructions | `system_context` or prompt `content` |
| Step numbers/tabs | Multiple prompts in sequence |

Also infer:
- **Assistant name** from title/header
- **Description** from any visible purpose text
- **Prompt content** from visible instructions or "what this does" text

### Handling Collapsed Dropdowns

**CRITICAL:** When you see a dropdown in a screenshot but can't see its options (e.g., shows "Select subject" or has a dropdown arrow but options aren't expanded), you MUST resolve the options before generating JSON.

**Resolution order:**

1. **Check if it matches a Common Field Library** (see below)
   - "Grade", "Grade Level" → Use Grade Levels library
   - "Subject", "Content Area" → Use Subjects library
   - "State" → Use US States library
   - "Language" → Use Language library
   - "Tone", "Style" → Use Writing Tone library
   - "Format", "Output Format" → Use Output Format library

2. **If no library match, ASK the user:**
   ```
   I see a dropdown for "[Field Name]" but can't see the options.

   Options:
   a) Provide a screenshot with the dropdown expanded
   b) List the values that should appear (comma-separated)
   c) Describe the type of options (e.g., "departments in our district")
   ```

3. **Never leave a select field without choices** - this will cause import errors

**Visual indicators of dropdowns:**
- Dropdown arrow (▼ or chevron) on right side
- "Select..." placeholder text
- Bordered box that looks clickable but isn't a text input
- Different styling from text inputs (often lighter/grayed placeholder)

### From Description (Dictation/Rambling)

Parse unstructured input for:

| Look For | Maps To |
|----------|---------|
| "user provides/enters/types..." | Input field |
| "asks for/needs a..." | Input field |
| "choose from/select/pick..." | `select` field |
| "upload/attach file..." | `file_upload` field |
| "then/next/after that..." | Additional prompt (chained) |
| "analyze/summarize/write/create..." | Prompt purpose |
| "should be/must be/format as..." | System context or prompt instructions |

### Smart Defaults

When not specified, use:

| Decision | Default |
|----------|---------|
| Model | `gpt-4o` (complex tasks), `gpt-4o-mini` (simple Q&A) |
| Field type for text | `long_text` with 6 rows |
| Execution | Sequential (single prompt unless steps mentioned) |
| Timeouts | `null` (system default) |
| Required fields | `true` for primary input, `false` for options |

---

## Workflow

### 1. Gather Requirements

**If screenshot provided:** Extract all visible elements per the table above.

**If description provided:** Parse for inputs, outputs, and flow.

**If unclear or incomplete:** Ask targeted questions:
- What should the assistant do?
- What inputs does it need?
- Single or multi-step?

### 1.5 Resolve All Dropdown Options (REQUIRED)

**Before generating JSON, ensure every dropdown has defined options.**

For each dropdown/select field identified:

| If... | Then... |
|-------|---------|
| Options are visible in screenshot | Extract them exactly |
| Field matches a Common Field Library | Use the library options |
| Field is domain-specific (e.g., "Department", "Building", "Program") | **ASK the user for the list** |
| Unclear what options should be | **ASK the user** |

**Example question format:**
```
I found these dropdowns that need options defined:

1. **Department** - What departments should be listed?
2. **Building** - What buildings/schools should be included?
3. **Program Type** - What program types exist?

You can provide comma-separated values, or share a screenshot with dropdowns expanded.
```

**Do NOT proceed to JSON generation with unresolved dropdowns.**

### 2. Design the Assistant

Based on requirements, determine:

| Decision | Options |
|----------|---------|
| Execution pattern | Sequential (default) / Parallel / Multi-level |
| Model selection | `gpt-4o` (complex) / `gpt-4o-mini` (simple) / `claude-3-5-sonnet` |
| Input fields | `short_text`, `long_text`, `select`, `multi_select`, `file_upload` |
| Timeouts | Default null, max 900 seconds |

### 3. Generate JSON

Build the JSON structure:

```json
{
  "version": "1.0",
  "exported_at": "[ISO-8601 timestamp]",
  "export_source": "Geoffrey Assistant Architect",
  "assistants": [{
    "name": "[Assistant Name]",
    "description": "[Purpose]",
    "prompts": [...],
    "input_fields": [...]
  }]
}
```

### 4. Write the File

Save to user's preferred location (default: `~/Downloads/[assistant-name].json`).

---

## Quick Patterns

### Simple Q&A Assistant

```json
{
  "version": "1.0",
  "export_source": "Geoffrey Assistant Architect",
  "assistants": [{
    "name": "Quick Helper",
    "description": "Answers questions clearly",
    "prompts": [{
      "name": "answer",
      "content": "Answer this question:\n\n${question}",
      "system_context": "You are a helpful expert.",
      "model_name": "gpt-4o-mini",
      "position": 0
    }],
    "input_fields": [{
      "name": "question",
      "label": "Your Question",
      "field_type": "long_text",
      "position": 0,
      "options": { "required": true, "rows": 6 }
    }]
  }]
}
```

### Multi-Level Parallel (Solo → Parallel → Synthesis)

Prompts at the same `position` with different `parallel_group` values run simultaneously. Parallel prompts can only reference outputs from **earlier** positions, never from other prompts at the same position.

```json
{
  "prompts": [
    {
      "name": "framing",
      "content": "Frame the key issues in this document:\n\n${document}",
      "model_name": "gpt-4o",
      "position": 0,
      "parallel_group": null
    },
    {
      "name": "strengths",
      "content": "Based on this framing:\n\n${prompt_0_output}\n\nIdentify strengths and opportunities.",
      "model_name": "gpt-4o",
      "position": 1,
      "parallel_group": 1000
    },
    {
      "name": "risks",
      "content": "Based on this framing:\n\n${prompt_0_output}\n\nIdentify risks and weaknesses.",
      "model_name": "gpt-4o",
      "position": 1,
      "parallel_group": 1001
    },
    {
      "name": "synthesis",
      "content": "Synthesize these perspectives:\n\nStrengths: ${prompt_1_output}\n\nRisks: ${prompt_2_output}",
      "model_name": "gpt-4o",
      "position": 2,
      "parallel_group": null
    }
  ]
}
```

**Key rules:**
- `parallel_group` = `null` → solo prompt (runs alone at its position)
- `parallel_group` = unique number → runs in parallel with other prompts at same position
- Parallel prompts reference `${prompt_N_output}` from earlier positions ONLY
- The synthesis prompt (position 2) can reference all earlier prompt outputs
- **Alternative syntax:** Instead of `${prompt_N_output}`, you can use `${slugified-prompt-name}` (e.g., `${framing}` for a prompt named "framing"). Both `${...}` and `{{...}}` delimiters work.

### Transform with Options

```json
{
  "prompts": [{
    "name": "transform",
    "content": "Rewrite in ${style} style:\n\n${content}",
    "model_name": "gpt-4o",
    "position": 0
  }],
  "input_fields": [
    {
      "name": "content",
      "label": "Content",
      "field_type": "long_text",
      "position": 0
    },
    {
      "name": "style",
      "label": "Writing Style",
      "field_type": "select",
      "position": 1,
      "options": {
        "choices": [
          { "value":