resolutionflow/docs/superpowers/specs/2026-03-29-parameterize-and-save-design.md

Parameterize & Save — Script Library Integration

Date: 2026-03-29 Status: Approved Scope: Fix AI-generated scripts saving to library without parameters; add parameter detection/review to save flow; add "New from Script" paste entry point

---

Problem

When the AI Script Builder generates a script and the user saves it to the Script Library:

1. parameters_schema is hardcoded to {"parameters": []} in save_to_library() — no parameter detection runs
2. The script body uses raw PowerShell param() syntax, not the {{ key }} template placeholders that ScriptTemplateEngine.render() expects

The result: saved templates have no parameters and can't be rendered with user-provided values. The template engine has nothing to substitute.

The frontend already has working parameter detection (scriptParameterDetector.ts) and a review UI (ParameterDetectorStepper), but they're only wired into ScriptTemplateEditor — not the save-to-library flow.

Solution

A shared ParameterizeAndSavePanel component that:

1. Shows the script with live preview of {{ }} replacements
2. Auto-runs parameter detection and lets the user review/accept/skip each candidate
3. Collects minimal metadata (name, description, category, share toggle)
4. Sends the rewritten script body + built parameters schema to the backend

Used in two entry points:

• AI Script Builder — replaces the current SaveToLibraryDialog
• Script Library page — "New from Script" button for pasting raw scripts

Note: Parameter detection currently supports PowerShell only. Bash and Python scripts will show "No parameters detected" and save as-is. Detection for those languages is planned for a future iteration.

---

Design

ParameterizeAndSavePanel Component

A slide-in panel from the right, ~480px wide, semi-transparent scrim behind it. Close via X button or scrim click.

Layout (top to bottom):

1. Script Preview — read-only code block showing the script body. As parameters are accepted via the stepper, the preview updates live to show {{ key }} replacements highlighted in amber.

2. Parameter Detection Zone — auto-runs detectParameterCandidates() when the panel opens.

   • If candidates found: renders the existing ParameterDetectorStepper inline
   • If no candidates found: shows "No parameters detected — script will be saved as-is"

3. Metadata Fields — name (required), description, category dropdown, share-with-team toggle. Same fields as the current SaveToLibraryDialog.

4. Save Button — sends rewritten script body + parameters schema + metadata to the backend.

Two modes controlled by props:

• script mode (from AI builder): script body + language provided, skips straight to preview + detection
• paste mode (from library page): shows a textarea + language picker at the top of the panel, above the preview area. Once pasted and confirmed, textarea collapses into the read-only preview and detection runs.

State: Local React state (not Zustand). Tracks:

• workingScript: the in-progress script body, mutated as candidates are accepted
• parametersSchema: accumulated ScriptParameter[] array
• metadata: name, description, categoryId, shareWithTeam
• mode: paste vs script (derived from props)

Entry Point 1: AI Script Builder

ScriptBuilderPage currently opens SaveToLibraryDialog. Replace with ParameterizeAndSavePanel in script mode.

Props:

• scriptBody: session.latest_script
• language: session.language
• defaultName: suggested filename minus extension
• onSave: calls scriptBuilderApi.saveToLibrary() with enriched payload
• onClose: closes the panel

Entry Point 2: Script Library Page

Add a "New from Script" button on ScriptLibraryPage (near the "Manage Templates" link). Opens ParameterizeAndSavePanel in paste mode.

Props:

• scriptBody: undefined (triggers paste mode)
• language: undefined (user picks in the panel)
• onSave: calls scriptsApi.createTemplate() directly
• onClose: closes the panel

Backend Changes

SaveToLibraryRequest schema (backend/app/schemas/script_builder.py):

Add two optional fields:

script_body: str | None = None        # Rewritten script with {{ }} placeholders
parameters_schema: dict | None = None  # Built parameter schema from frontend

save_to_library() service (backend/app/services/script_builder_service.py):

Add script_body: str | None = None and parameters_schema: dict | None = None to the function signature. Use provided values instead of hardcoding:

template = ScriptTemplate(
    ...
    script_body=script_body or session.latest_script,
    parameters_schema=parameters_schema or {"parameters": []},
    ...
)

save_to_library endpoint (backend/app/api/endpoints/script_builder.py):

Pass data.script_body and data.parameters_schema from the request through to the service function.

No new endpoints needed. The library paste flow uses the existing POST /scripts/templates which already accepts script_body + parameters_schema.

Script Rewriting Logic

The ParameterizeAndSavePanel reuses the same approach as ScriptTemplateEditor.handleAcceptCandidate():

When a candidate is accepted:

1. Find the matched line in the working script
2. Replace the default value portion with '{{ key }}'
3. Add the parameter to the accumulated schema

This happens in the panel's local state. The stepper emits accept/skip events; the panel handles the rewriting.

---

File Changes

New Files

• frontend/src/components/scripts/ParameterizeAndSavePanel.tsx — shared panel component

Modified Files

• frontend/src/pages/ScriptBuilderPage.tsx — replace SaveToLibraryDialog with ParameterizeAndSavePanel (script mode)
• frontend/src/pages/ScriptLibraryPage.tsx — add "New from Script" button, render ParameterizeAndSavePanel (paste mode)
• backend/app/schemas/script_builder.py — add script_body and parameters_schema to SaveToLibraryRequest
• backend/app/services/script_builder_service.py — use provided values in save_to_library()
• backend/app/api/endpoints/script_builder.py — pass new fields through

Deleted Files

• frontend/src/components/script-builder/SaveToLibraryDialog.tsx — replaced entirely

Unchanged (reused as-is)

• frontend/src/components/script-editor/ParameterDetectorStepper.tsx
• frontend/src/lib/scriptParameterDetector.ts
• frontend/src/components/script-editor/ScriptTemplateEditor.tsx
• POST /scripts/templates endpoint

---

Scope Boundaries

In scope:

• ParameterizeAndSavePanel component with script/paste modes
• Parameter detection + stepper review in the save flow
• Script body rewriting with {{ }} placeholders
• Backend accepting enriched save payload
• "New from Script" button on library page
• PowerShell parameter detection only

Out of scope:

• Bash/Python parameter detection (future iteration)
• Changes to ScriptTemplateEditor or ParameterSchemaBuilder
• Changes to ScriptTemplateEngine rendering logic
• New API endpoints