Spell Builder

Purpose: produce production-ready spell definitions (YAML/JSON) that compose step commands and connectors into end-to-end automated spells, with proper data flow, validation, and engine integration.

Read First — Companion Files

Prerequisites

• MoFlo project with cli/spells package
• Familiarity with YAML syntax

Quick Start

Ask the user:

What would you like to do?

1. Create a new spell definition from scratch
2. Edit an existing spell definition
3. Discover available step commands and connectors
4. Validate an existing spell file

Then follow the appropriate section below.

Section 1: Create a New Spell

Step 1: Gather Spell Metadata

Step 2: Define Arguments (Optional)

If the spell needs runtime parameters, define each argument:

Arguments are referenced via {args.argumentName}.

Step 3: Define Steps

Walk the user through adding steps one at a time. For each step:

Data flow between steps: Use {stepId.outputKey} syntax to reference output from a previous step. For example, if step fetch-data outputs a url field, a later step can use {fetch-data.url}.

Special variable references:

• {args.name} — references a spell argument
• {credentials.NAME} — references a credential (resolved at runtime)
• {stepId.outputKey} — references output from a previous step

REQUIRED: Permission disclosure on step creation

After defining each step, display its permission profile. See permissions.md for the required format and per-capability warnings. Apply automatically — users must understand what each step can do before it becomes part of a spell.

REQUIRED: Preflight checks with human-readable hints

When a step depends on runtime state the user controls (clean git tree, logged-in CLI, reachable host, etc.), declare a preflight: block so the spell fails fast with a helpful message before any side effects. Every preflight MUST include a hint: field — the user-visible message on failure. See preflight.md for the full guide (severity levels, resolutions, hint copywriting rules).

Step 4: Generate the Spell YAML

Assemble the definition into:

name: <spell-name>
abbreviation: <optional-abbreviation>
description: <optional-description>
version: "<version>"
mofloLevel: <optional-level>

arguments:
  <arg-name>:
    type: <string|number|boolean|string[]>
    required: <true|false>
    default: <optional-default>
    enum: [<optional-values>]
    description: <optional-help-text>

steps:
  - id: <unique-step-id>
    type: <step-command-type>
    config:
      <type-specific-config-fields>
    output: <optional-variable-name>
    continueOnError: <optional-true>
    mofloLevel: <optional-level>

Step 5: Validate the Spell

Validate against the engine schema. The following rules must pass:

1. name is required and must be a non-empty string
2. steps is required and must be a non-empty array
3. Each step must have a unique id (no duplicates)
4. Each step must have a valid type matching a known step command
5. Variable references ({stepId.outputKey}) must not be forward references
6. Argument references ({args.name}) must match declared arguments
7. mofloLevel must be one of: none, memory, hooks, full, recursive
8. Step-level mofloLevel cannot exceed the spell-level mofloLevel
9. No circular condition jumps (condition steps referencing each other in a loop)
10. Argument definitions must have valid types, and defaults must match their declared type
11. permissionLevel (if declared) must be one of: readonly, standard, elevated, autonomous

If validation fails, show the specific errors and guide the user to fix them.

Step 5b: REQUIRED — Permission Dry-Run Report

After schema validation passes, display the full spell-wide permission report and require user acceptance before the spell can be cast. See permissions.md for the exact format. On acceptance the permission hash is stored — subsequent runs do not re-prompt unless the spell's permissions change.

Step 6: Write the File

Ask the user where to save:

• Project spells: spells/<name>.yaml (user-level, project-specific)
• Claude spells: .claude/spells/<name>.yaml (Claude Code integration)

Prefer the MCP tool when available:

mcp__moflo__spell_create — name, definition (YAML string), description

Or write the file directly to the chosen directory.

Section 2: Edit an Existing Spell

Step 1: Load the Spell

Ask for the spell file path, or use mcp__moflo__spell_list to browse available spells. Read the YAML/JSON file and parse the current definition.

Step 2: Present Current Structure

Show a summary: name, description, version, abbreviation, arguments (if any), steps list with id/type/output variable/continueOnError.

Step 3: Apply Changes

After each change, re-validate and show any errors introduced. When adding or modifying a step, display its permission report (see permissions.md). If the change introduces new destructive capabilities or raises the permission level, call this out explicitly.

Step 4: Save

Write the updated YAML back to the original file (or a new path if requested).

Section 3: Discover Available Spell Components

Step Commands

Each step type has its own self-contained README under .claude/skills/spell-builder/steps/:

.claude/skills/spell-builder/steps/
  <step-name>/README.md    — config, outputs, usage examples, source path

To find available steps, Glob .claude/skills/spell-builder/steps/*/README.md and read each H1.

Runtime source: src/cli/spells/commands/ — each step is a TypeScript file registered in index.ts.

Adding a new step: create steps/<name>/README.md (use existing READMEs as templates and follow .claude/guidance/moflo-guidance-rules.md); the step source goes in src/cli/spells/commands/ and is registered in index.ts. No changes to this SKILL.md needed.

Connectors

Each connector has its own self-contained README under .claude/skills/spell-builder/connectors/:

.claude/skills/spell-builder/connectors/
  <connector-name>/README.md    — actions, capabilities, usage, source path

To find available connectors, Glob .claude/skills/spell-builder/connectors/*/README.md.

Runtime source: src/cli/spells/connectors/ — each connector is a TypeScript file registered in index.ts.

Adding a new connector: create connectors/<name>/README.md; the connector source goes in src/cli/spells/connectors/ and is registered in index.ts. When to create a new connector vs composing existing ones: see architecture.md.

Section 4: Validate an Existing Spell

Step 1: Load and Parse

Read the spell file (YAML or JSON). The parser auto-detects format.

Step 2: Run Validation

Check against all engine validation rules from Section 1, Step 5.

Step 3: Report Results

• Valid: confirm the spell passes all checks.
• Invalid: list each error with its path and message, then offer to fix.

Reference

Type Definitions

• Spell definition: src/cli/spells/types/spell-definition.types.ts — SpellDefinition, StepDefinition, ArgumentDefinition, ArgumentType
• Step command interface: src/cli/spells/types/step-command.types.ts — StepCommand, StepConfig, StepOutput, CastingContext, MofloLevel, CapabilityType
• Connector interface: src/cli/spells/types/spell-connector.types.ts — SpellConnector, ConnectorAction, ConnectorOutput, ConnectorAccessor

Engine Components

• Schema validator: src/cli/spells/schema/validator.ts — validateSpellDefinition()
• YAML/JSON parser: src/cli/spells/schema/parser.ts — parseSpell()
• Grimoire (registry): src/cli/spells/registry/spell-registry.ts — Grimoire
• Definition loader: src/cli/spells/loaders/definition-loader.ts — two-tier loading (shipped + user)

MCP Tools

MoFlo Integration Levels

Variable Reference Syntax

Example: Complete Spell

name: security-audit
abbreviation: sa
description: Run security checks on a target directory
version: "1.0"
mofloLevel: memory

arguments:
  target:
    type: string
    required: true
    description: Directory to audit
  severity:
    type: string
    default: medium
    enum: [low, medium, high, critical]
    description: Minimum severity to report

steps:
  - id: scan-deps
    type: bash
    preflight:
      - name: "npm available"
        command: "npm --version"
        hint: "npm isn't installed or isn't on your PATH. Install Node.js from https://nodejs.org and try again."
    config:
      command: "npm audit --json"
      cwd: "{args.target}"
    output: audit-result

  - id: analyze-findings
    type: bash
    config:
      command: |
        claude -p "Analyze these npm audit results and filter for severity >= {args.severity}.
        Audit output: {scan-deps.stdout}"
      timeout: 300000
    output: analysis

  - id: save-report
    type: memory
    config:
      operation: write
      namespace: security
      key: "audit-{args.target}"
      value: "{analysis.summary}"

Related Skills

• /connector-builder — scaffold new connectors and step commands when the spell needs a component that doesn't exist yet