moflo 4.9.20 → 4.9.22

package/.claude/skills/spell-builder/SKILL.md

@@ -5,27 +5,21 @@ description: "Create, edit, and validate spell definitions (YAML/JSON) that comp
 
 # Spell Builder
 
-Create 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.
+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.
 
-## Architecture — Read First
+## Read First — Companion Files
 
-**Before creating or modifying spells, read [architecture.md](architecture.md).** It defines the three-layer model (spell → step command → connector) and when to create what. Putting logic in the wrong layer is the most common mistake.
+| File | When to read |
+|------|--------------|
+| [architecture.md](architecture.md) | **Always** — three-layer model (spell → step → connector); putting logic in the wrong layer is the most common mistake |
+| [permissions.md](permissions.md) | When defining or editing any step — required disclosure & dry-run report format |
+| [preflight.md](preflight.md) | When the step depends on runtime state (clean git tree, logged-in CLI, reachable host) |
 
 ## Prerequisites
 
 - MoFlo project with `cli/spells` package
 - Familiarity with YAML syntax
 
-## What This Skill Does
-
-1. Guides you through building a **spell definition** (YAML/JSON)
-2. Discovers available **step commands** and **connectors** to compose
-3. Wires up **data flow** between steps via variable references
-4. Validates the generated definition against the engine schema
-5. Outputs the spell file to the correct project directory
-
----
-
 ## Quick Start
 
 Ask the user:
@@ -44,8 +38,6 @@ Then follow the appropriate section below.
 
 ### Step 1: Gather Spell Metadata
 
-Ask the user for:
-
 | Field | Required | Example |
 |-------|----------|---------|
 | **Name** | Yes (kebab-case) | `deploy-staging`, `security-audit` |
@@ -56,7 +48,7 @@ Ask the user for:
 
 ### Step 2: Define Arguments (Optional)
 
-If the spell needs runtime parameters, define arguments:
+If the spell needs runtime parameters, define each argument:
 
 | Field | Required | Description |
 |-------|----------|-------------|
@@ -65,139 +57,42 @@ If the spell needs runtime parameters, define arguments:
 | **Required** | Optional (default `false`) | Whether the argument must be provided |
 | **Default** | Optional | Default value if not provided |
 | **Enum** | Optional | Allowed values (e.g., `[low, medium, high]`) |
-| **Description** | Optional | Help text for the argument |
+| **Description** | Optional | Help text |
 
-Arguments are referenced in step configs via `{args.argumentName}`.
+Arguments are referenced via `{args.argumentName}`.
 
 ### Step 3: Define Steps
 
-Walk the user through adding steps one at a time. For each step, collect:
+Walk the user through adding steps one at a time. For each step:
 
 | Field | Required | Description |
 |-------|----------|-------------|
 | **ID** | Yes (unique) | Step identifier (kebab-case, e.g., `run-tests`) |
 | **Type** | Yes | One of the available step command types (see Discovery section) |
-| **Config** | Yes | Type-specific configuration (see per-type docs below) |
+| **Config** | Yes | Type-specific configuration (see per-step README) |
 | **Output** | Optional | Variable name to store step output (for downstream steps) |
 | **Continue on Error** | Optional | `true` to proceed even if this step fails |
 | **MoFlo Level** | Optional | Override spell-level mofloLevel (can only narrow, not escalate) |
-| **Permission Level** | Optional | `readonly`, `standard`, `elevated`, `autonomous` — controls Claude CLI tools when this step spawns a sub-agent. Auto-derived from capabilities when omitted. |
-
-**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}` in its config.
-
-#### REQUIRED: Permission Disclosure on Step Creation
-
-**After defining each step, you MUST display its permission requirements.** This is not optional — users must understand what each step can do before it becomes part of a spell.
-
-For each step, determine and display:
-
-1. **Permission level** — derived from capabilities or explicit `permissionLevel`:
-   - `readonly` (Read, Glob, Grep) — safe, analysis only
-   - `standard` (Edit, Write, Read, Glob, Grep) — can modify files
-   - `elevated` (Edit, Write, Bash, Read, Glob, Grep) — can run shell commands
-   - `autonomous` (all tools) — unrestricted, requires explicit opt-in
-
-2. **Risk classification** — based on the step's capabilities:
-   - **[SAFE]** — `fs:read`, `memory` only — no side effects
-   - **[SENSITIVE]** — `agent`, `net`, `browser` — can read external data or spawn processes
-   - **[DESTRUCTIVE]** — `shell`, `fs:write`, `browser:evaluate`, `credentials` — can permanently modify/delete data
-
-3. **Specific warnings** — for each destructive or sensitive capability, explain:
-   - `shell`: "Can execute arbitrary shell commands (rm, git push, etc.)"
-   - `fs:write`: "Can create, overwrite, or delete files on disk"
-   - `credentials`: "Can access stored secrets and API keys"
-   - `agent`: "Can spawn autonomous Claude sub-agents"
-   - `net`: "Can make network requests to external services"
-
-**Display format (show after every step definition):**
-
-```
-Permissions for step "deploy-code":
-  [DESTRUCTIVE] deploy-code (bash)
-    Permission level: elevated
-    Allowed tools: Edit, Write, Bash, Read, Glob, Grep
-    Warnings:
-      !! shell: Can execute arbitrary shell commands (rm, git push, etc.)
-      !! fs:write: Can create, overwrite, or delete files on disk
-```
+| **Permission Level** | Optional | `readonly`, `standard`, `elevated`, `autonomous` — auto-derived from capabilities when omitted |
 
-If the step is safe, still display the permissions but with a reassuring tone:
-
-```
-Permissions for step "analyze-logs":
-  [SAFE] analyze-logs (bash)
-    Permission level: readonly
-    Allowed tools: Read, Glob, Grep
-    No destructive capabilities.
-```
+**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: 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 occur.
-
-**Every preflight MUST include a `hint:` field.** The hint is what the end user will see when the check fails. Without it they get raw shell output (`command "git diff --quiet" exited with 1, expected 0`), which looks like a bug in the spell engine.
-
-Good hints:
-- Speak in plain English (no command names, exit codes, or tool jargon).
-- State the problem AND the fix in one or two sentences.
-- Assume a non-technical reader.
-
-```yaml
-steps:
-  - id: create-branch
-    type: bash
-    preflight:
-      - name: "working tree clean (tracked changes)"
-        command: "git diff --quiet"
-        hint: "You have uncommitted changes to tracked files. Commit them or stash them (git stash) before running this spell."
-      - name: "gh cli authenticated"
-        command: "gh auth status"
-        hint: "The GitHub CLI isn't signed in. Run: gh auth login"
-    config:
-      command: "git checkout -b feature/new"
-```
-
-Bad hint (don't do this):
-```yaml
-hint: "git diff --quiet failed with exit code 1"   # leaks command name + exit code
-hint: "Precondition violated"                       # tells user nothing actionable
-```
-
-Preflights with no `hint` still work but produce unfriendly default output — flag this to the user as a quality issue before saving the spell.
-
-##### Fatal vs warning severity
-
-By default every preflight is `severity: fatal` — if it fails, the spell aborts. Some preflights are better expressed as `severity: warning`: the user gets to choose how to handle the problem, and the spell continues if they pick a resolution.
+#### REQUIRED: Permission disclosure on step creation
 
-Use `warning` ONLY when:
-- The underlying problem has a safe, one-step fix the user might reasonably want to apply.
-- Proceeding is viable either way — the step itself is robust to the condition.
+After defining each step, display its permission profile. **See [permissions.md](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.
 
-Warning preflights MUST declare `resolutions:` — a list of options the user can pick from. Each resolution has a `label` and an optional `command` to run before continuing. If `command` is omitted, picking the resolution just proceeds (useful for "I'll handle it myself").
-
-```yaml
-preflight:
-  - name: "working tree clean (tracked changes)"
-    command: "git diff --quiet"
-    severity: "warning"
-    hint: "You have uncommitted changes. If you want them carried onto the new branch, pick 'Stash and carry over'."
-    resolutions:
-      - label: "Stash changes and carry them onto the new branch"
-        command: "git stash push --include-untracked --message 'pre-spell autostash'"
-      - label: "Commit changes to the current branch first, then continue"
-        command: "git commit -am 'wip: pre-spell snapshot'"
-```
+#### REQUIRED: Preflight checks with human-readable hints
 
-In non-interactive contexts (CI, daemons, scheduled spells) warnings automatically behave like fatals, because there is no one to prompt. Don't use `warning` as a way to silently ignore a problem — if ignoring it is always safe, the check shouldn't be there.
+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](preflight.md) for the full guide (severity levels, resolutions, hint copywriting rules).**
 
 ### Step 4: Generate the Spell YAML
 
-Assemble the definition into YAML format following this structure:
+Assemble the definition into:
 
 ```yaml
 name: <spell-name>
@@ -226,17 +121,17 @@ steps:
 
 ### Step 5: Validate the Spell
 
-Before writing the file, validate it against the engine schema. The following rules must pass:
+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 (the referenced step must appear before the current step)
+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)
+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`
 
@@ -244,56 +139,17 @@ 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, you MUST display a full permission report for the spell.** This is mandatory for new spells and updated spells — users must see and accept the permission profile before the spell can be run.
-
-Display the report in this format:
-
-```
-Permission Report: <spell-name>
-Overall risk: [DESTRUCTIVE] destructive
-Permission hash: a1b2c3d4e5f6g7h8
-
-  [SAFE] fetch-config (bash)
-    Permission level: readonly
-    Allowed tools: Read, Glob, Grep
-
-  [DESTRUCTIVE] implement-story (bash)
-    Permission level: elevated
-    Allowed tools: Edit, Write, Bash, Read, Glob, Grep
-    Warnings:
-      !! shell: Can execute arbitrary shell commands (rm, git push, etc.)
-      !! fs:write: Can create, overwrite, or delete files on disk
-
-  [SENSITIVE] analyze-results (agent)
-    Permission level: standard
-    Allowed tools: Edit, Write, Read, Glob, Grep
-    Warnings:
-      ! agent: Can spawn autonomous Claude sub-agents
-
---- DESTRUCTIVE STEPS ---
-1 step(s) can make destructive changes:
-  - implement-story: shell, fs:write
-
-These steps can modify files, run shell commands, or access credentials.
-Review the spell definition before accepting.
-```
-
-**After showing the report, ask the user:**
-
-> The spell requires the permissions shown above. Do you accept? (y/n)
-
-If the user accepts, the permission hash is stored and subsequent runs will not prompt again (unless the spell's permissions change).
-
-**Regular runs** (not dry-runs) do NOT show this verbose permission output — they just run quietly. The acceptance gate checks the stored hash and only blocks if it doesn't match.
+After schema validation passes, display the full spell-wide permission report and require user acceptance before the spell can be cast. **See [permissions.md](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 the spell:
+Ask the user where to save:
 
 - **Project spells:** `spells/<name>.yaml` (user-level, project-specific)
 - **Claude spells:** `.claude/spells/<name>.yaml` (Claude Code integration)
 
-Use the MCP tool to create the spell if available:
+Prefer the MCP tool when available:
+
 ```
 mcp__moflo__spell_create — name, definition (YAML string), description
 ```
@@ -306,21 +162,14 @@ Or write the file directly to the chosen directory.
 
 ### 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.
+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 of the spell:
-- Name, description, version, abbreviation
-- Arguments (if any)
-- Steps list with: id, type, output variable, continueOnError
+Show a summary: name, description, version, abbreviation, arguments (if any), steps list with id/type/output variable/continueOnError.
 
 ### Step 3: Apply Changes
 
-Support these edit operations:
-
 | Operation | Description |
 |-----------|-------------|
 | **Add step** | Insert a new step at a given position |
@@ -331,9 +180,7 @@ Support these edit operations:
 | **Add/remove arguments** | Modify spell argument definitions |
 | **Update metadata** | Change name, description, version, abbreviation, mofloLevel |
 
-After each change, re-validate the definition and show any errors introduced.
-
-**REQUIRED: When adding or modifying a step, display its permission report** (same format as Section 1, Step 3 — Permission Disclosure on Step Creation). If the change introduces new destructive capabilities or raises the permission level, explicitly call this out to the user.
+After each change, re-validate and show any errors introduced. **When adding or modifying a step, display its permission report (see [permissions.md](permissions.md)).** If the change introduces new destructive capabilities or raises the permission level, call this out explicitly.
 
 ### Step 4: Save
 
@@ -345,35 +192,33 @@ Write the updated YAML back to the original file (or a new path if requested).
 
 ### Step Commands
 
-**Each step type has its own directory with a self-contained README.** To discover available steps, scan the `steps/` directory within this skill:
+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 what steps are available:** Use `Glob` on `.claude/skills/spell-builder/steps/*/README.md` and read the H1 heading of each file. Each README is self-contained — it has everything needed to use that step type.
+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 a directory under `steps/<name>/` with a `README.md`. Follow `.claude/guidance/shipped/moflo-guidance-rules.md` and use existing step READMEs as templates. The step command source goes in `src/cli/spells/commands/` and is registered in `index.ts`. No changes to this SKILL.md needed.
+**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 directory with a self-contained README.** To discover available connectors, scan the `connectors/` directory:
+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 what connectors are available:** Use `Glob` on `.claude/skills/spell-builder/connectors/*/README.md`.
+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 a directory under `connectors/<name>/` with a `README.md`. Follow `.claude/guidance/shipped/moflo-guidance-rules.md` and use existing connector READMEs as templates. The connector source goes in `src/cli/spells/connectors/` and is registered in `index.ts`. No changes to this SKILL.md needed.
-
-**When to create a new connector vs composing existing ones:** See [architecture.md](architecture.md) for the decision tree.
+**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](architecture.md).
 
 ---
 
@@ -385,19 +230,12 @@ Read the spell file (YAML or JSON). The parser auto-detects format.
 
 ### Step 2: Run Validation
 
-Check against all engine validation rules:
-
-- Required fields: `name` (string), `steps` (non-empty array)
-- Step integrity: unique IDs, valid types, valid config structure
-- Variable references: no forward references, no undefined arguments
-- MoFlo levels: valid values, step-level cannot exceed the spell-level
-- Circular jumps: condition steps must not form cycles
-- Arguments: valid types, defaults match declared type, enum consistency
+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
+- **Valid:** confirm the spell passes all checks.
+- **Invalid:** list each error with its path and message, then offer to fix.
 
 ---
 
@@ -470,9 +308,6 @@ steps:
       - 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."
-      - name: "target directory exists"
-        command: "test -d \"{args.target}\""
-        hint: "The directory you passed as --target doesn't exist. Check the path and try again."
     config:
       command: "npm audit --json"
       cwd: "{args.target}"
@@ -484,30 +319,8 @@ steps:
       prompt: |
         Analyze the npm audit results and filter for severity >= {args.severity}.
         Audit output: {scan-deps.result}
-        Produce a summary of vulnerabilities found.
     output: analysis
 
-  - id: check-critical
-    type: condition
-    config:
-      expression: "{analysis.hasCritical} === true"
-      then: report-critical
-      else: report-clean
-
-  - id: report-critical
-    type: agent
-    config:
-      prompt: |
-        Critical vulnerabilities found. Generate a detailed report
-        with remediation steps for: {analysis.criticalItems}
-
-  - id: report-clean
-    type: agent
-    config:
-      prompt: |
-        No critical vulnerabilities. Generate a summary report
-        of {analysis.totalFindings} findings at {args.severity}+ severity.
-
   - id: save-report
     type: memory
     config:
@@ -519,4 +332,4 @@ steps:
 
 ### Related Skills
 
-- [/connector-builder](../connector-builder/) (#238) — scaffold new connectors and step commands when the spell needs a component that doesn't exist yet
+- [/connector-builder](../connector-builder/) — scaffold new connectors and step commands when the spell needs a component that doesn't exist yet

package/.claude/skills/spell-builder/architecture.md

@@ -153,7 +153,7 @@ steps:
 
 ## Documentation Rules for New Components
 
-**Every new step, connector, or spell MUST include a README.md.** Apply the rules in `.claude/guidance/shipped/moflo-guidance-rules.md` automatically — do not wait for the user to ask. Use existing READMEs in `steps/` and `connectors/` as templates.
+**Every new step, connector, or spell MUST include a README.md.** Apply the rules in `.claude/guidance/moflo-guidance-rules.md` automatically — do not wait for the user to ask. Use existing READMEs in `steps/` and `connectors/` as templates.
 
 **Where to put the README:**
 - Steps: `.claude/skills/spell-builder/steps/<name>/README.md`

package/.claude/skills/spell-builder/permissions.md

@@ -0,0 +1,107 @@
+# Spell Permissions — Disclosure & Dry-Run Reporting
+
+Purpose: when authoring or modifying a spell, you MUST surface what each step is allowed to do **before** the spell becomes runnable. This file is the canonical reference for that behaviour and is shared by the `spell-builder` and `connector-builder` skills.
+
+## Permission Levels
+
+Levels control which Claude CLI tools a step's sub-agent receives. Auto-derived from declared `capabilities` unless the step sets `permissionLevel:` explicitly. `autonomous` is never auto-derived — it requires explicit opt-in.
+
+| Level | Tools | Auto-derived when |
+|-------|-------|-------------------|
+| `readonly` | Read, Glob, Grep | Only `fs:read`, `memory` capabilities |
+| `standard` | Edit, Write, Read, Glob, Grep | Has `fs:write` or `agent`, no `shell`/`browser` |
+| `elevated` | Edit, Write, Bash, Read, Glob, Grep | Has `shell` or `browser` |
+| `autonomous` | All tools | Never auto — explicit opt-in only |
+
+## Risk Classification
+
+| Class | Triggered by | Meaning |
+|-------|--------------|---------|
+| `[SAFE]` | `fs:read`, `memory` only | No side effects |
+| `[SENSITIVE]` | `agent`, `net`, `browser` | Reads external data or spawns processes |
+| `[DESTRUCTIVE]` | `shell`, `fs:write`, `browser:evaluate`, `credentials` | Can permanently modify or delete data |
+
+## Capability Warnings
+
+For each destructive or sensitive capability declared on a step, include the matching warning in disclosure output:
+
+| Capability | Warning text |
+|------------|--------------|
+| `shell` | "Can execute arbitrary shell commands (rm, git push, etc.)" |
+| `fs:write` | "Can create, overwrite, or delete files on disk" |
+| `credentials` | "Can access stored secrets and API keys" |
+| `agent` | "Can spawn autonomous Claude sub-agents" |
+| `net` | "Can make network requests to external services" |
+| `browser` | "Can drive a browser session, including form submission and downloads" |
+
+## Per-Step Disclosure (REQUIRED on step creation)
+
+After defining or modifying a step, display its permission profile. For destructive/sensitive steps:
+
+```
+Permissions for step "deploy-code":
+  [DESTRUCTIVE] deploy-code (bash)
+    Permission level: elevated
+    Allowed tools: Edit, Write, Bash, Read, Glob, Grep
+    Warnings:
+      !! shell: Can execute arbitrary shell commands (rm, git push, etc.)
+      !! fs:write: Can create, overwrite, or delete files on disk
+```
+
+For safe steps, still display — with a reassuring tone:
+
+```
+Permissions for step "analyze-logs":
+  [SAFE] analyze-logs (bash)
+    Permission level: readonly
+    Allowed tools: Read, Glob, Grep
+    No destructive capabilities.
+```
+
+When editing an existing step, if the change introduces new destructive capabilities or raises the permission level, call this out explicitly.
+
+## Spell-Wide Dry-Run Report (REQUIRED before first run)
+
+After schema validation passes for a new or updated spell, display the full permission report and require user acceptance before the spell can be cast:
+
+```
+Permission Report: <spell-name>
+Overall risk: [DESTRUCTIVE] destructive
+Permission hash: a1b2c3d4e5f6g7h8
+
+  [SAFE] fetch-config (bash)
+    Permission level: readonly
+    Allowed tools: Read, Glob, Grep
+
+  [DESTRUCTIVE] implement-story (bash)
+    Permission level: elevated
+    Allowed tools: Edit, Write, Bash, Read, Glob, Grep
+    Warnings:
+      !! shell: Can execute arbitrary shell commands (rm, git push, etc.)
+      !! fs:write: Can create, overwrite, or delete files on disk
+
+  [SENSITIVE] analyze-results (agent)
+    Permission level: standard
+    Allowed tools: Edit, Write, Read, Glob, Grep
+    Warnings:
+      ! agent: Can spawn autonomous Claude sub-agents
+
+--- DESTRUCTIVE STEPS ---
+1 step(s) can make destructive changes:
+  - implement-story: shell, fs:write
+
+These steps can modify files, run shell commands, or access credentials.
+Review the spell definition before accepting.
+```
+
+Then ask:
+
+> The spell requires the permissions shown above. Do you accept? (y/n)
+
+On acceptance the permission hash is stored. Subsequent runs do NOT re-prompt unless the spell's permissions change. Regular runs (not dry-runs) skip this verbose output and silently check the stored hash.
+
+## See Also
+
+- [SKILL.md](SKILL.md) — main spell-builder skill
+- [preflight.md](preflight.md) — preflight check authoring
+- [architecture.md](architecture.md) — three-layer model (spell → step → connector)

package/.claude/skills/spell-builder/preflight.md

@@ -0,0 +1,101 @@
+# Preflight Checks — Author Guide
+
+Purpose: preflight checks let a step fail fast with a helpful message **before** any side effects occur, when the failure depends on runtime state the user controls (clean git tree, logged-in CLI, reachable host, etc.).
+
+## Required: every preflight has a `hint:` field
+
+The `hint:` is what the end user sees on failure. Without it they get raw shell output (`command "git diff --quiet" exited with 1, expected 0`) which looks like a bug in the spell engine.
+
+Good hints:
+- Plain English. No command names, exit codes, internal identifiers.
+- State BOTH the problem AND the fix in one or two sentences.
+- Assume a non-technical reader.
+
+```yaml
+steps:
+  - id: create-branch
+    type: bash
+    preflight:
+      - name: "working tree clean (tracked changes)"
+        command: "git diff --quiet"
+        hint: "You have uncommitted changes to tracked files. Commit them or stash them (git stash) before running this spell."
+      - name: "gh cli authenticated"
+        command: "gh auth status"
+        hint: "The GitHub CLI isn't signed in. Run: gh auth login"
+    config:
+      command: "git checkout -b feature/new"
+```
+
+Bad hints (don't do this):
+
+```yaml
+hint: "git diff --quiet failed with exit code 1"   # leaks command name + exit code
+hint: "Precondition violated"                       # tells user nothing actionable
+```
+
+Preflights without `hint` still work but produce unfriendly default output — flag this as a quality issue before saving the spell.
+
+## Severity: fatal vs warning
+
+Default `severity: fatal` — failure aborts the spell. Use `severity: warning` ONLY when:
+
+- The underlying problem has a safe, one-step fix the user might reasonably want to apply.
+- Proceeding is viable either way — the step itself is robust to the condition.
+
+Warning preflights MUST declare `resolutions:` — a list the user can pick from. Each resolution has a `label` and an optional `command` to run before continuing. If `command` is omitted, picking the resolution just proceeds (useful for "I'll handle it myself").
+
+```yaml
+preflight:
+  - name: "working tree clean (tracked changes)"
+    command: "git diff --quiet"
+    severity: "warning"
+    hint: "You have uncommitted changes. If you want them carried onto the new branch, pick 'Stash and carry over'."
+    resolutions:
+      - label: "Stash changes and carry them onto the new branch"
+        command: "git stash push --include-untracked --message 'pre-spell autostash'"
+      - label: "Commit changes to the current branch first, then continue"
+        command: "git commit -am 'wip: pre-spell snapshot'"
+```
+
+In non-interactive contexts (CI, daemons, scheduled spells) warnings automatically behave like fatals — there is no one to prompt. Don't use `warning` to silently ignore a problem; if ignoring is always safe, the check shouldn't be there.
+
+## Step-Command Preflight Checks (TypeScript)
+
+When authoring a step command (see `connector-builder`), the `preflight:` array on the command takes a `check` function. The `reason` string returned on failure is shown verbatim to end users — same copywriting rules apply.
+
+```typescript
+preflight: [
+  {
+    name: '<service> reachable',
+    severity: 'fatal',
+    check: async (config, ctx) => {
+      const ok = await ping(config.endpoint);
+      if (ok) return { passed: true };
+      return {
+        passed: false,
+        reason: `Can't reach ${config.endpoint}. Check your network connection or the service URL in your spell config.`,
+      };
+    },
+  },
+  {
+    name: 'local cache fresh',
+    severity: 'warning',
+    resolutions: [
+      { label: 'Refresh the cache now', command: '<type>-cli cache refresh' },
+      { label: 'Continue with stale cache' },
+    ],
+    check: async (config) => {
+      const stale = await isCacheStale(config.endpoint);
+      return stale
+        ? { passed: false, reason: 'Your local cache is more than 24 hours old and may produce outdated results.' }
+        : { passed: true };
+    },
+  },
+],
+```
+
+## See Also
+
+- [SKILL.md](SKILL.md) — main spell-builder skill
+- [permissions.md](permissions.md) — permission disclosure & dry-run reporting
+- [architecture.md](architecture.md) — three-layer model

package/.claude/skills/spell-schedule/SKILL.md

@@ -143,7 +143,7 @@ If the user asks to **run now** without altering the cadence:
 - **Catch-up window** (default 1h, `scheduler.catchUpWindowMs` in `moflo.yaml`): if the daemon was offline when a run was due, runs within the window still fire on the next poll. Older missed runs are skipped with a `schedule:skipped` event.
 - **maxConcurrent** (default 2): caps the number of scheduled spells running concurrently. Same-schedule overlap is never allowed.
 - **No update CLI yet**: `flo spell schedule` exposes create/list/cancel only. To change a cadence, cancel + recreate.
-- **Spell-required sandboxing** (#878): when that ships, scheduled runs honor it just like manual casts — a missing sandbox skips the run with a `schedule:skipped` event.
+- **Spell-required sandboxing**: when sandbox-required spells become enforced, scheduled runs will honor it just like manual casts — a missing sandbox skips the run with a `schedule:skipped` event.
 
 ## Output
 
@@ -163,5 +163,4 @@ Daemon:      running | needs-start
 
 ## Reference
 
-- Full daemon scheduler docs: https://github.com/eric-cielo/moflo/blob/main/docs/SPELLS.md#scheduling
-- Tracking issue: https://github.com/eric-cielo/moflo/issues/877
+- Full daemon scheduler docs: see `docs/SPELLS.md#scheduling` in the moflo source tree